Open source · MIT License

Your music,
your server.

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.

$ docker run -d --name sonect -p 3000:3000 -v /path/to/music:/libraries/music:ro -v sonect-data:/app/data ghcr.io/koberum/sonect:latest

Everything your music deserves.

Built on the rock-solid MPD protocol. No subscriptions, no telemetry, no limits on your own files.

MPD-powered playback

Sits on top of Music Player Daemon — battle-tested, gapless, and supports virtually any audio format your hardware can handle.

Live WebSocket state

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.

Smart queue strategy

Album → artist → genre → similar-genre fallback fills your queue intelligently, ranked by your play counts. Random and repeat are one click away.

Album art pipeline

Artwork is extracted from your audio files, served over HTTP, and cached aggressively in the browser — never fetched twice.

Audio output setup in the browser

Pick your ALSA output device from the Settings page. Sonect writes the MPD drop-in and reloads the daemon automatically.


Up in three steps.

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.

bash
# Docker (production)
docker run -d --name sonect -p 3000:3000
-v /path/to/music:/libraries/music:ro -v sonect-data:/app/data
ghcr.io/koberum/sonect:latest
 
# Local development
git clone https://github.com/Koberum/Sonect
cd Sonect && pnpm install
pnpm dev
 
# → frontend: http://localhost:5173
# → backend: http://localhost:3000

Everything you need to know.

Installation

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.

  • Install MPD via your distribution's package manager (apt install mpd on Debian/Ubuntu)
  • Ensure MPD is listening on port 6600 (default)
  • For production (including Raspberry Pi), run the single Docker image: docker run -d -p 3000:3000 -v /path/to/music:/libraries/music:ro -v sonect-data:/app/data ghcr.io/koberum/sonect:latest
  • For local development, clone the repo and run pnpm install
  • Start with pnpm dev for development, or pnpm build for production

Configuration

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.

Architecture

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.

request flow
Browser ──HTTP──► Express API ──► MPD :6600
Browser ──WS────► WS Server ──► MPD poll (2s/10s)

API Reference

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

Build & Deploy

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.

  • Set FRONTEND_DIST to point at the built frontend directory
  • Run the backend with pnpm backend:start (the esbuild bundle at backend/dist/bundle.cjs)
  • GitHub Actions CI builds both artifacts on every push to main
  • For containerised deployments, bind-mount music under /libraries/<name> and persist /app/data