Self-hosted, AI-powered music command center
|
 |
 |
 |
 |
 |
 |
- Navidrome-integrated browsing (artists, albums, songs)
- Full-text search and album detail views
- Audio streaming proxy with quality selection (128/256/320 kbps)
- Background library sync & indexing
- Per-user Navidrome accounts (user-scoped stars, playlists, scrobbles)
- Dual-deck crossfade engine with gapless transitions
- 10 real-time audio visualizers (bars, waveform, circular, particles, starfield, spiral, and more)
- Lyrics display via LRCLIB integration
- Network-resilient playback with stall recovery & auto-resume
- Keyboard shortcuts and Media Session API (lock screen / headphone controls)
- PWA with mobile controls & offline support
- Spotify Connect-style device handoff via WebSocket
- Remote transport commands (skip, pause, play) across devices
- Per-field timestamp conflict resolution
- Real-time queue, playback position, and volume sync
- Device presence with heartbeat monitoring
- Multi-provider LLM support (Ollama, Anthropic, OpenRouter, GLM)
- 7-signal blended scoring engine:
- Last.fm similarity (crowdsourced from billions of scrobbles)
- Compound history correlation with recency decay
- DJ match scoring (BPM, energy, harmonic key compatibility)
- User feedback weighting (thumbs up/down)
- Skip penalty (avoids frequently skipped tracks)
- Temporal patterns (time-of-day, weekday vs weekend)
- Diversity bonus (artist variety enforcement)
- DJ set builder with BPM analysis, harmonic mixing, energy flow
- Mix compatibility badges
- Background discovery with personalized suggestions
- Discovery feed with interaction tracking & analytics
- Artist fatigue, blocklists, and seasonal pattern detection
- MusicBrainz-powered artist metadata enrichment (type, country, life-span, genres, tags, biography)
- Similar artist discovery with match scoring
- Dashboard discovery section with recommendations, trending artists, and recent additions
- Rich artist detail pages with social links (Wikipedia, Discogs, AllMusic, Bandcamp)
- DB-cached metadata with 7-day TTL (zero API overhead during playback)
- Integrated as a candidate source in the blended recommendation engine
- Rule-based filters evaluated server-side by Navidrome
- Multi-field conditions: title, artist, album, genre, year, duration, rating, play count, loved, dates
- Logical operators: AND/OR with nested conditions
- 8 preset templates (Never Played, Favorites, Recent Releases, 80s & 90s Classics, and more)
- Preview songs before creating
- Random song generation from rules
- Artist-aware shuffle algorithm (Fisher-Yates with artist separation repair)
- Listening hour distribution chart
- Album decade distribution
- Longest sessions tracker
- Artist interest trends over time
- Mood profile analysis
- Shareable identity cards with unique URLs
- Play count & listening stats
- Mood timeline
- Seasonal patterns
- Library growth tracking
- Discovery analytics (acceptance rate, genre exploration)
- Recommendation performance tracking
- Create, edit, drag-and-drop reorder
- Collaborative playlists with real-time song suggestions
- Import/export (M3U, JSON)
- Navidrome two-way sync
- Liked songs auto-sync from starred songs
- Safe Mode (PG) -- filters explicit songs using Deezer metadata
- Configurable crossfade (0-10s), volume, autoplay, and quality defaults
- Per-user playback preferences synced to server
- YouTube audio downloads via MeTube
- Lidarr album search, monitoring, & acquisition
- Download queue management
| Layer | Technology |
|---|---|
| Framework | React 19 + React Compiler, TanStack Start / Router / Query |
| Styling | Tailwind CSS v4 + shadcn/ui + Radix UI |
| State | Zustand (9 stores with persistence) |
| Database | PostgreSQL + Drizzle ORM (22 schemas, 30 migrations) |
| Auth | Better Auth (email/password + GitHub + Google OAuth) |
| Charts | Recharts |
| Audio | Web Audio API, dual-deck crossfade engine |
| Real-time | WebSocket (cross-device sync, collaborative playlists) |
| Testing | Vitest + React Testing Library, Playwright E2E |
| CI/CD | GitHub Actions, Cloudflare Pages |
| Service | Purpose | Required |
|---|---|---|
| Navidrome | Music library & streaming (Subsonic API) | Yes |
| PostgreSQL | Application database | Yes |
| Aurral | Artist metadata enrichment & similar artist discovery (MusicBrainz) | Optional |
| Ollama / Anthropic / OpenRouter | AI DJ, mood translation, playlist generation | Optional |
| Last.fm | Similar tracks/artists, scrobbling metadata | Optional |
| Lidarr | Music acquisition & monitoring | Optional |
| MeTube | YouTube audio downloads | Optional |
| Spotify | Metadata lookup (no streaming) | Optional |
| Deezer | Explicit content detection, cover art, metadata | Optional |
| LRCLIB | Synced lyrics lookup | Optional |
- Node.js 20+
- PostgreSQL
- Navidrome instance
git clone https://github.com/lolimmlost/aidj.git
cd aidj
npm install
cp .env.example .env # then edit with your service URLs and credentials
npm run db # generate and apply database migrations
npm run devThe dev server starts at http://localhost:3003.
Optional services (Last.fm, Lidarr, MeTube, Ollama, Aurral) can be configured later in Settings.
| Variable | Required | Description |
|---|---|---|
DATABASE_URL |
Yes | PostgreSQL connection URL |
BETTER_AUTH_SECRET |
Yes | Min 32 chars, session encryption |
VITE_BASE_URL |
Yes | Public URL (e.g., https://example.com) |
NAVIDROME_URL |
Yes | Navidrome server URL |
NAVIDROME_USERNAME |
Yes | Navidrome admin username |
NAVIDROME_PASSWORD |
Yes | Navidrome admin password |
OLLAMA_URL |
No | Ollama LLM server URL |
LIDARR_URL |
No | Lidarr server URL |
LIDARR_API_KEY |
No | Lidarr API key |
LASTFM_API_KEY |
No | Last.fm API key |
METUBE_URL |
No | MeTube server URL |
AURRAL_URL |
No | Aurral metadata service URL |
AURRAL_USERNAME |
No | Aurral authentication username |
AURRAL_PASSWORD |
No | Aurral authentication password |
SPOTIFY_CLIENT_ID |
No | Spotify client credentials |
SPOTIFY_CLIENT_SECRET |
No | Spotify client credentials |
GITHUB_CLIENT_ID |
No | GitHub OAuth |
GITHUB_CLIENT_SECRET |
No | GitHub OAuth |
GOOGLE_CLIENT_ID |
No | Google OAuth |
GOOGLE_CLIENT_SECRET |
No | Google OAuth |
src/
├── components/ # 135 React components
│ ├── dashboard/ # Dashboard widgets, Aurral discovery section
│ ├── discovery/ # Discovery queue & suggestions
│ ├── discovery-feed/ # Discovery feed cards
│ ├── dj/ # DJ tools & mix badges
│ ├── downloads/ # Download management
│ ├── layout/ # PlayerBar, sidebar, nav
│ ├── library/ # Artist/album/song views, artist metadata hero
│ ├── lyrics/ # Lyrics modal
│ ├── music-identity/ # Wrapped-style analytics charts
│ ├── playlists/ # Playlist CRUD, collaboration, smart playlists
│ ├── recommendations/ # Rec cards, analytics, mood timeline
│ ├── ui/ # 36 shadcn/ui primitives
│ └── visualizer/ # Audio visualizer modal
├── lib/
│ ├── auth/ # Better Auth config
│ ├── config/ # Config & feature flag system
│ ├── db/schema/ # 22 Drizzle schema files
│ ├── hooks/ # 17 custom hooks (crossfade, sync, media session, artist metadata, etc.)
│ ├── services/ # ~98 backend service modules
│ │ ├── ai-dj/ # AI DJ core engine
│ │ ├── background-discovery/
│ │ ├── cache/ # Caching layer
│ │ ├── lastfm/ # Last.fm API client
│ │ ├── lidarr/ # Lidarr integration
│ │ ├── library-sync/# Navidrome sync
│ │ ├── llm/ # LLM providers (Ollama, Anthropic, OpenRouter, GLM)
│ │ └── offline/ # Offline/PWA support
│ ├── stores/ # 9 Zustand stores
│ └── utils/ # Shuffle scoring, device info, etc.
├── routes/ # TanStack file-based routes
│ ├── (auth)/ # Login / Signup
│ ├── api/ # 148 API endpoints
│ ├── dashboard/ # Dashboard, analytics, discover, mood
│ ├── dj/ # DJ set builder & settings
│ ├── downloads/ # Download management
│ ├── library/ # Artists / albums / search
│ ├── music-identity/ # Wrapped-style identity page
│ ├── playlists/ # Playlist views & collaboration
│ ├── settings/ # Playback, services, profile, notifications
│ └── tasks/ # Background task management
└── styles.css
Detailed architecture documentation is auto-generated from the codebase:
| Document | Description |
|---|---|
SYSTEM-MAP.md |
Where everything is -- stores, schemas, routes, services, hooks, components |
AUDIO-PLAYBACK.md |
Dual-deck crossfade, audio store, stall recovery, cross-device sync |
RECOMMENDATION-ENGINE.md |
Scoring pipeline, weights, compound/skip/DJ formulas, discovery |
DATA-MODEL.md |
Complete table reference with columns, types, indexes, relationships |
EXTERNAL-INTEGRATIONS.md |
Protocol, auth, config, and gotchas for each external service |
CONVENTIONS.md |
Code patterns, naming, do/don't pairs with examples |
npm run dev # Start dev server (port 3003)
npm run build # Production build (node-server target)
npm test # Run tests (watch mode)
npm run test:coverage # Run with coverage (>80% required)
npm run lint # Lint with ESLint
npm run db # Generate & apply database migrations
npm run db:studio # Open Drizzle StudioCI runs lint, build, test, security scanning (Trivy + Gitleaks), and uploads coverage to Codecov on every push and PR. See .github/workflows/README.md for details.
Unlicense -- public domain.