docs/ROADMAP.md

Roadmap

The plan for making keep music the best self-hosted music player. Every item is a GitHub issue; epics hold sub-issues. Run scripts/setup-project.sh once to put them all on a GitHub Project board with a Phase and Priority field.

Principles

  • shadcn ecosystem only. UI is shadcn/ui (Base UI) + Tailwind v4 + the @audiocn registry. No hand-rolled components where one exists, no Tailwind palette colors. The brand (monochrome, square, IBM Plex + JetBrains Mono, color only for errors) lives only in the shadcn theme tokens.
  • Instant. Persisted cache, prefetch on intent, virtualized lists, selector-based player state, precached audio.
  • Keyboard first, never memorized. One shortcut registry drives the shortcuts, the ? cheat sheet, the command palette and every tooltip.
  • Navidrome is the source of truth. Sync with Arpeggi and other clients uses standard (Open)Subsonic APIs only.
  • Self-hostable by anyone. One container, one env var to start, guided onboarding, safe defaults.

Epics

#epicpriority
#1Foundation: shadcn + Tailwind v4 + audiocnp0
#2Performancep0
#3Playback engine: gapless, precaching, crossfadep0
#4Keyboard-firstp0
#30Search: fuzzy, typo-tolerant, lyricsp0
#5Lyrics everywherep0
#6UX polish: loading, tooltips, motion, statesp1
#7Cross-device sync with Arpeggip1
#8Library & playlistsp1
#9Self-hosting: onboarding, security, docsp1
#60Signature features other players missp1
#10Discovery, AI playlists & aurap2

Build order

Phases are ordered by dependency, not just importance: later work assumes the earlier foundations.

  1. Foundation & speed: the shadcn rebuild, tooling, player store, virtualization, data layer, covers, sessions (credential-free URLs make covers and audio cacheable). #11 #12 #13 #14 #15 #16 #17 #18 #19 #20 #54
  2. Playback & keyboard: gapless, precache, resilience, the queue model, the shortcut registry and cheat sheet, list navigation, a11y. #21 #22 #25 #47 #26 #27 #28 #29
  3. Lyrics & search: lyrics service and UI, the server index, lyrics search, search UX. #34 #35 #31 #32 #33
  4. Polish & sync: tooltips, skeletons, motion, states, now-playing views, queue hand-off, likes, history, context menus, playlist editing. #37 #38 #39 #40 #41 #42 #43 #44 #45 #46
  5. v1.0 public release: onboarding, distribution, docs, settings/PWA, lyrics coverage, Spotify import, library browsing. #50 #51 #52 #53 #36 #48 #49
  6. Beyond: crossfade, audio quality, radio, AudioMuse, Groq mixes, aura, stats, moments, trims, undo, library doctor, listen together. #23 #24 #55 #56 #57 #58 #59 #61 #62 #63 #64 #65

Decisions

topicdecision
aurastrictly monochrome generated textures from audio features; no cover-derived color
lyrics filescached in the app by default; writing .lrc sidecars is opt-in (LYRICS_WRITE_LRC)
Arpeggi syncsavePlayQueue/getPlayQueue (Arpeggi lists "sync queue across devices"), stars, ratings, playlists
crossfade / EQgapless always on; crossfade and EQ optional, off by default; no crossfade within an album
lyrics searchneeds an index: the Bun server keeps SQLite FTS5 (words + trigram) over library and lyrics
upstream serverfixed by server config (NAVIDROME_URL / allowlist), never chosen by the browser
credentialsserver-side sessions with an httpOnly cookie; no tokens in browser storage or URLs