docs/ROADMAP.md

Roadmap

The plan for making lodesong 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.

Where it stands (3 Nov 2026, 1.13): the web player, the Mac app, the iPhone shell, an Android shell, a Linux and Windows shell, previews, the landing page and the API are in. This round shipped: start radio as a page, a following page with a releases feed (grouped by week, filtered by type, mark seen), the Spotify follow sync through Lyterion, an inferred-genres fallback, AI-filled upload tags, stats without recharts (111 KB to 4 KB gzip), phone polish, a security pass (CodeQL, audit, CSP reports), mobile performance budgets, a screen-reader-ready a11y suite, scrobbling state in settings, the i18n groundwork and the repo side of a public demo.

What the rest needs. Nearly everything left is not code: it needs a real device, a server only the owner can set up, or a change in Lyterion. They are listed that way below, so nothing looks done that has not been tried.

What is left

Priorities: P0 blocks people or hides a bug class, P1 the next thing worth doing, P2 good and not urgent, P3 ideas. Sizes: S under a day, M a few days, L a week or more.

Needs a device

whatprisize
#410run the iPhone checklist on a real phone (silent switch, lock screen, AirPods, interruptions)P0M
#412install the AltStore / SideStore source on a phone and see an update arriveP1S
#411Android: screen-off playback, lock-screen controls, Bluetooth buttons, battery optimisation (checklist)P1M
#309Linux and Windows: audio on WebKitGTK, a tray, close to tray, an updater, signing (the Tauri shell is minimal)P2L
#418the VoiceOver and NVDA pass (checklist); axe already covers every pageP1M
#319native Now Playing and remote commands in the iPhone shell, only if WebKit's lock screen proves flakyP3M

Needs the owner

whatprisize
#416host the public demo: a public host and DNS, PUBLIC_DEMO_HOST, DEMO_URL on Vercel (steps)P1S
turn on the Dependency graph in the repo settings, then bring the dependency review job backP1S
the French strings of the i18n groundwork need a native readP2S
#413WebKit and phone e2e projects: merge needs a token with the workflow scopeP0S

Needs Lyterion

whatprisize
#435the followed-artists endpoint (lyterion#192); lodesong's side is done and retries until it existsP1M
#437backfill GENRE on files Lyterion did not write; lodesong shows an honest state and inferred genres meanwhileP1M
#183finding and fetching missing artists belongs to Lyterion; lodesong fills tags into a sidecar, writing them into the files needs a tag writerP3L

Code, next

whatprisize
browse.e2e.ts fails on WebKit (the genre filter never shows "N of M"): probably a real Safari bugP1S
cover art on the release cards (a Cover Art Archive proxy) instead of the generated tileP2M
#420convert the other pages to t() (history is the template); Last.fm and ListenBrainz connection stateP2M
#417lazy-load the player-bar menus, AVIF covers, a gate that compares with the last releaseP2M
settings search: a filter box in the dialog now that it has nine tabsP2S
a "what's new" in the web app, as the Mac app hasP2S
gapless and crossfade verified per format with an automated listening testP2M
drag a playlist track to reorder on touch screensP2M
visual regression for the key pages in dark, light and phoneP2M
offline downloads inside the shells (iOS evicts web storage; native files don't)P2L
client error reports, opt in, into the server's logP3S
Widgets, CarPlay and Android Auto: need native code and, on iOS, a paid developer accountP3L

The site and the community

whatprisize
the promo video (apps/video) on the landing page, with captionsP2S
comparison and "migrate from Spotify" pages for search, with real screenshotsP2M
a docs version switcherP3S
#320a hosted lodesong against your own Navidrome (design)P3L

Next version

This is a 2.0, not 1.x: the apps and the release feed change what lodesong is. 2.0 ships when the three device rows (iPhone, Android, screen reader) have been run and the demo is public. Everything under "Code, next" can land in 1.x releases meanwhile.

Housekeeping that bit this time

  • Install the Claude GitHub App on the renamed repository (the repo moved from keep-player to lodesong; the app's events stopped reaching sessions that still use the old name).
  • docs/ was written before the rebrand in places: the QA pass found the old CSRF header name in docs/security.md (fixed). A link and name check on the docs, run in CI, would catch the rest.
  • Local development: the dev bundler's inline script trips the CSP in the console (production is clean), which hides real errors. Give the dev server a matching hash.

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