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.

Bun React Subsonic License

album with synced lyrics

Why

Your own music deserves a player as good as the streaming apps, and better where they cut corners:

keep musicSpotify web player
your files, your server✓—
search that forgives typos, accents, missing spaces✓partly
search by a half-remembered lyric, and play from that line✓exact words only, plays from the start
lyrics timing you can nudge per song, saved across devices✓—
next songs downloaded ahead, playing offline in the browser✓—
every action on the keyboard, a searchable cheat sheet (?), rebindable✓some shortcuts
start on your phone, continue here (any Subsonic app, e.g. Arpeggi)✓✓ (Connect)

Features

  • Search (⌘K): one box for songs, albums, artists, playlists, lyrics and commands. Typo-tolerant, ranked by what you play, with filters (artist: year:1990..1999 is:liked format:flac …). search
  • Lyrics for nearly every song: Navidrome's, else LRCLIB's, cached and fetched ahead. They follow the song word by word, full screen with ⇧F, and [ ] fix the timing per song. lyrics
  • Playback that doesn't stutter: two decks for gapless handover, ReplayGain (album gain in album order), the next songs precached by a service worker (instant seeks, plays offline), stalls recovered in place.
  • Queue you can see and steer: your queue apart from the album or playlist it came from, balanced shuffle, undo for removals, stop after this song, sleep timer.
  • Keyboard first: everything has a key, ? shows them all, lists move with j/k, x selects. shortcuts
  • Library: home (recently added, played, most played, rediscover), albums, artists with bio and top songs, songs, genres, liked songs, your folders as on disk, playlists in folders (Chill / Night).
  • With your phone: the play queue hands off both ways with Arpeggi or any OpenSubsonic app; likes, ratings, playlists and plays are the server's, so every app agrees. sync
  • Fast: a 10k-song list renders ~40 rows, the library is cached in the browser so a reload paints instantly, covers are resized WebP served forever-cached, the first screen is under 155 KB of JS.
  • Mac media keys, Now Playing, a mini player (always on top) and scrobbling back to Navidrome.
albumssearch
albumssearch
homequeue
homequeue

Quick start

yaml
1# compose.yaml, next to your Navidrome
2services:
3 player:
4 image: ghcr.io/findmalek/keep-player:latest # amd64 and arm64
5 restart: unless-stopped
6 environment:
7 NAVIDROME_URL: http://navidrome:4533 # as this container reaches Navidrome
8 ports:
9 - "8080:8080"
10 volumes:
11 - player-data:/data
12volumes:
13 player-data:

docker compose up -d, open http://localhost:8080, sign in with your Navidrome account. The sign-in screen checks the server first and tells you what to fix if it can't reach it. Getting started

Docs

getting startedrun it, sign in, first run
configurationevery setting (generated from the code)
deployfull stack, Traefik, Caddy, nginx, Dokploy, image tags, health
shortcutsevery key (generated from the code)
search · lyrics · sync · spotify importhow they work
architecture · securityhow it's built, what's protected
troubleshootingwhen something's off
contributing · roadmapworking on it

FAQ

Does it work on a phone? It's built for the desktop web. On a phone use a native Subsonic app (Arpeggi, Substreamer, Symfonium…); the queue hands off between them.

Does it change my music files? No. It reads through Navidrome's API. Likes, ratings, playlists and plays are stored by Navidrome; keep music keeps only its own data (sessions, its search and lyrics cache, history) in /data.

Does it phone home? No. It talks to your Navidrome and, for missing lyrics, to LRCLIB (LRCLIB_URL= turns that off). The release check is off unless you set UPDATE_CHECK=on.

Several Navidrome servers? NAVIDROME_SERVERS=home=http://a:4533,friend=https://b and pick at sign-in.

Other Subsonic servers? Anything that speaks OpenSubsonic should work; it's tested against Navidrome.

Develop

sh
1bun install
2bun run mock # fake Navidrome on :4599 with 10k songs (demo / demo)
3NAVIDROME_URL=http://127.0.0.1:4599 bun run dev # app on :8080, hot reload
4bun run check # typecheck, lint, unit tests, bundle size, generated docs
5bun run e2e # Playwright against the mock

More in CONTRIBUTING.

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