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.

CI Release Image Bun React OpenSubsonic MIT

An album open next to its synced lyrics, a song playing

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 160 KB of JS (gzip).
  • Mac media keys, Now Playing, a mini player (always on top) and scrobbling back to Navidrome.
home stats, from a listening history
home: recently added, rediscover, most played stats: minutes, streaks, top lists, a listening clock
search the queue
search (⌘K): songs, albums, artists, lyrics, commands queue: yours, apart from the album it came from

on a phone: an album, a song playing

All screenshots are the generated demo library: synthesized tracks and dithered covers, no real music. The album shot has a light twin, served automatically on a light system theme.

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 import · listen togetherhow they work
architecture · securityhow it's built, what's protected
demo library · previewsthe generated library, and per-PR preview deployments
troubleshootingwhen something's off
contributing · roadmapworking on it

FAQ

Does it work on a phone? Yes: the layout follows the window down to 320 px, and it installs as an app from the browser's menu. For a native feel use a Subsonic app too (Arpeggi, Substreamer, Symfonium…); the queue hands off between them.

Can I try it without my own music? Yes: bun run demo:library ./demo-music generates a library and compose.demo.yaml serves it from a Navidrome. See demo library.

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

A Bun workspace: apps/player (the React app), apps/server (the Bun server that serves it and proxies Navidrome), packages/shared (types both sides use).

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
6bun run demo:library ./demo-music # a real, copyright-free library for a real Navidrome

Every pull request gets a preview deployment with a demo account. More in CONTRIBUTING.

Credits

Built on Navidrome, Bun, React, shadcn/ui (on Base UI) and LRCLIB. The demo library's tracks are generated by this repository; there is no third-party music in it.

License

MIT