MPD-powered playback
Sits on top of Music Player Daemon — battle-tested, gapless, and supports virtually any audio format your hardware can handle.
Open source · MIT License
Sonect wraps Music Player Daemon in a modern React interface. Self-host your entire library — browse by album, artist, or genre, control playback in real time, and never depend on a streaming service again.
Why Sonect
Built on the rock-solid MPD protocol. No subscriptions, no telemetry, no limits on your own files.
Sits on top of Music Player Daemon — battle-tested, gapless, and supports virtually any audio format your hardware can handle.
Playback changes reflect instantly across every open tab. State is polled from MPD (2 s during play, 10 s paused) and pushed to all connected clients over WebSocket.
Album → artist → genre → similar-genre fallback fills your queue intelligently, ranked by your play counts. Random and repeat are one click away.
Artwork is extracted from your audio files, served over HTTP, and cached aggressively in the browser — never fetched twice.
Pick your ALSA output device from the Settings page. Sonect writes the MPD drop-in and reloads the daemon automatically.
Quick start
Sonect is a pnpm monorepo. You need
Node.js 24+ and a
running MPD instance on port 6600.
Clone the repo, drop a .env in
packages/backend/ pointing at your music directory,
and start the dev server. The React frontend proxies API calls
to Express automatically.
Once running, open http://localhost:5173 and
trigger a library scan from the sidebar refresh button to
populate your collection.
Documentation
Sonect requires Node.js 24 or later and
pnpm 10.34.7 (pinned via
packageManager). For local development you also
need a running MPD instance — the single Docker image bundles
its own.
apt install mpd
on Debian/Ubuntu)
6600 (default)
docker run -d -p 3000:3000 -v
/path/to/music:/libraries/music:ro -v
sonect-data:/app/data ghcr.io/koberum/sonect:latest
pnpm install
pnpm dev for development, or
pnpm build for production
Create a .env file in
packages/backend/. All variables have sensible
defaults; set MUSIC_DIR and
COVERS_DIR explicitly for production.
| Variable | Default | Description |
|---|---|---|
| MPD_HOST | localhost | MPD server hostname or IP |
| MPD_PORT | 6600 | MPD server port |
| MUSIC_DIR | /opt/sonect/music (code default; /libraries in docker) | Root of your music library |
| COVERS_DIR | ./data/covers | Where cover WebPs are cached |
| DB_PATH | /db/music.db (dev) / /app/data/music.db (docker) | SQLite database path |
| PORT | 3000 | Backend HTTP port |
MPD configuration is split between a baked
mpd.conf
(immutable) and a user-editable drop-in at
/app/data/mpd-audio.conf in the container (/opt/sonect/data/mpd-audio.conf
in dev). The Audio settings tab rewrites the
audio_output
block and reloads MPD automatically.
Sonect is a monorepo with four packages, each with a single responsibility:
backend — Express 5 API server + WebSocket
server on port 3000
frontend — React 19 + Vite SPA on port 5173 in
development
@repo/db — SQLite schema, migrations, and query
layer (node:sqlite + Drizzle)
@repo/types — shared TypeScript types and zod
schemas
The browser communicates with the backend over both HTTP (REST) and WebSocket. MPD status is polled (2 s while playing, 10 s paused) and fanned out to all connected clients; browser sessions tick locally and broadcast through the same channel — this is what keeps every tab in sync.
The Express backend exposes a REST API for library browsing and MPD control, plus a WebSocket endpoint for live state.
| Method | Path | Description |
|---|---|---|
| GET | /catalog/albums | List all albums |
| GET | /catalog/albums/:id | Get album by ID |
| GET | /catalog/albums/:albumId/tracks | Tracks for an album |
| GET | /catalog/artists | List all artists |
| GET | /catalog/artists/:artistId/albums | Albums for an artist |
| POST | /catalog/scan | Trigger library re-scan |
| POST | /player/play | Play a track (requires X-Session-Id) |
| POST | /player/pause | Pause playback |
| POST | /player/next | Skip to next track |
| PATCH | /player/volume | Set volume (0–100) |
| WS | ws://host:3000/ws?sessionId=&deviceId= | Live playback state |
Run pnpm build from the repo root to compile all
packages. The frontend is output to
packages/frontend/dist and served as static files
by the Express backend in production — no separate web server
needed.
FRONTEND_DIST to point at the built
frontend directory
pnpm backend:start (the
esbuild bundle at backend/dist/bundle.cjs)
main
/libraries/<name> and persist
/app/data