README.md
keep music
A monochrome web player for your Navidrome library. Square covers, hairline borders, synced lyrics, a queue you can see, and nothing on screen when nothing is playing.

Features
- Library: home (recently added, recently played, most played, rediscover), albums with sorting, artists A–Z with bio and popular tracks, all songs, genres as tags, and your folders exactly as they sit on disk.
- Playlists with folders: name a playlist
Chill / Nightand it shows up inside a Chill folder. - Player bar with shuffle, repeat (all / one), seek and volume — and it disappears when the queue is empty.
- Queue panel (jump, remove, clear) and a synced lyrics panel that follows the song; click a line to seek.
- ⌘K search across artists, albums and songs, keyboard first.
- ReplayGain through Web Audio: album gain when an album plays in order, track gain otherwise, clipped to the peak.
- Mac media keys and Now Playing (Media Session), scrobbling back to Navidrome, and the queue and position survive a reload.
- Keyboard:
spaceplay/pause ·←→seek ·shift ←/→previous/next ·mmute ·sshuffle ·rrepeat ·qqueue ·llyrics ·⌘Kor/search.
| albums | search |
|---|---|
![]() | ![]() |
| home | queue |
![]() | ![]() |
How it works
A small Bun server serves the app and forwards /rest/* to Navidrome on your internal network:
- same origin, so there's no CORS and Web Audio can apply ReplayGain to the stream;
Rangeheaders pass through, so seeking in a FLAC is instant;- login happens server-side: the server turns your password into a Subsonic token (
md5(password + salt)), checks it against Navidrome and keeps it encrypted in$DATA_DIR/sessions.db. The browser only gets an httpOnly session cookie. The password is never stored; - search runs on the server's own index (
$DATA_DIR/library.db, SQLite FTS5), which adds typo tolerance ("radiohed"), missing spaces ("okcomputer") and accent folding ("beyonce") to what Navidrome's search does.
The index covers the whole library, so it is built as one account: INDEX_USER / INDEX_PASSWORD if set,
otherwise the Navidrome admin who signed in most recently. It syncs after every Navidrome scan and once a day.
Results are always cut down to the music folders the person searching may see, so a shared server doesn't leak
one library into another. Admins see the index under their user menu → library index, with a "rebuild now" button.
Built for the desktop web. On a phone, use a native Subsonic app.
Run it
| 1 | services: |
| 2 | player: |
| 3 | build: . |
| 4 | restart: unless-stopped |
| 5 | environment: |
| 6 | NAVIDROME_URL: http://navidrome:4533 # reachable from this container |
| 7 | ports: |
| 8 | - "8080:8080" # or route it through your reverse proxy |
Sign in with any Navidrome account. Album metadata, cover art, genres and lyrics come from Navidrome, so tags from beets (MusicBrainz, LRCLIB synced lyrics, ReplayGain) show up as-is.
Develop
| 1 | bun install |
| 2 | NAVIDROME_URL=http://localhost:4533 bun src/server.ts |
| 3 | bun run typecheck |
Deploying to your own box: put KEEP_HOST, COMPOSE_ID and SOURCE_DIR in a git-ignored .deploy.env and run
./deploy.sh (Dokploy).
Credits
Screenshots use Creative Commons music: The Slip by Nine Inch Nails (CC BY-NC-SA 3.0), The Shade from Our Trees and Breadcrumbs by Josh Woodward (CC BY 3.0), Direct to Video by Chris Zabriskie (CC BY 3.0), Guess Who's a Mess by Brad Sucks (CC BY-NC-SA 3.0).
License
MIT



