Open source · Apache 2.0 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.

Get started View on GitHub

$ curl -fsSL https://raw.githubusercontent.com/Koberum/Sonect/main/installer.sh | sudo bash

sonect — now playing

Kind of Blue

Miles Davis · 1959

2:14 9:22

Why Sonect

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. No polling — MPD idle events pushed directly to all connected clients.

Smart queue strategy

Album → artist → genre fallback fills your queue intelligently. Repeat, random, consume, and single modes are all first-class.

Album art pipeline

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

In-browser MPD config

Edit audio output settings and MPD config drop-ins right from the Settings page. Save once, MPD restarts automatically.

Quick start

Up in three steps.

Sonect is a pnpm monorepo. You need Node.js 20+ 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 Settings page to populate your collection.

bash

                  # Raspberry Pi (production)
                
                  curl -fsSL
                  https://raw.githubusercontent.com/Koberum/Sonect/main/installer.sh
                  |
                  sudo bash
                
                  # Local development
                
                  git clone
                  https://github.com/Koberum/Sonect
                
                  cd Sonect
                  &&
                  pnpm install
                
                  pnpm dev
                
                  # → frontend: http://localhost:5173
                
                  # → backend: http://localhost:3000

Documentation

Everything you need to know.

Installation

Sonect requires Node.js 20 or later and pnpm 9+. A running MPD instance is also required — Sonect does not manage MPD itself, it connects to one you provide.

Install MPD via your distribution's package manager (apt install mpd on Debian/Ubuntu)
Ensure MPD is listening on port 6600 (default)
On a Raspberry Pi, run the one-line installer: curl -fsSL https://raw.githubusercontent.com/Koberum/Sonect/main/installer.sh | sudo bash
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 except COVERS_DIR, which you should set to a writable directory.

Variable	Default	Description
MPD_HOST	localhost	MPD server hostname or IP
MPD_PORT	6600	MPD server port
MUSIC_DIR	/music	Root of your music library
COVERS_DIR	—	Where cover JPEGs are cached
DB_PATH	./data/music.db	SQLite database path
PORT	3000	Backend HTTP port

MPD configuration is split between a root-owned /etc/mpd.conf and a user-editable drop-in at /opt/sonect/data/mpd-audio.conf. The drop-in is edited from the Settings page in the UI.

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
db — SQLite schema and query layer (Drizzle-style)
@repo/db — SQLite schema, migrations, and query helpers
@repo/types — Shared TypeScript types (no runtime dependencies)

The browser communicates with the backend over both HTTP (REST) and WebSocket. The WebSocket connection listens to MPD idle events and fans out state changes to all connected clients — this is what keeps every tab in sync without polling.

request flow

                      Browser
                      ──HTTP──►
                      Express API
                      ──►
                      MPD :6600
                    

                      Browser
                      ──WS────►
                      WS Server 
                      ──►
                      MPD idle
                    

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	/library/albums	List all albums
GET	/library/albums/:id	Get album by ID
GET	/library/albums/:id/tracks	Tracks for an album
GET	/library/artists	List all artists
GET	/library/artists/:id/albums	Albums for an artist
POST	/library/scan	Trigger library re-scan
POST	/mpd/play	Play a track
POST	/mpd/pause	Toggle pause
POST	/mpd/next	Skip to next track
PATCH	/mpd/volume	Set volume (0–100)
WS	ws://host:3000	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 node packages/backend/dist/index.js
GitHub Actions CI builds both artifacts on every push to main
For containerised deployments, mount your music directory at MUSIC_DIR

Your music,your server.