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 (1.20, Nov 2026): the web player, the Mac app, the iPhone and Android shells, a Linux and Windows shell, the following page, inferred genres, previews, the public demo, the launch film and the API are in. v1 is done as a product; what is left is getting music you do not own yet and a native iPhone app. Candidate search, fetch the rest of an album, Release Radar from followed artists, playlist cover choices, the queue drag test, the instant pause, clickable release cards, a faster Made for you and the phone touch targets have shipped; the rows below mark what is still open.

Shipped, no longer open work: the iPhone device checklist (#410), Android shell (#411), AltStore source (#412), WebKit and phone e2e (#413), public demo (#416), mobile budgets in CI (#417), screen-reader pass (#418), Last.fm and ListenBrainz with i18n groundwork (#420), Linux and Windows app (#309), music import with AI metadata (#183), following every Spotify artist through Lyterion (#435), backfilled genres (#437). All closed as completed with a merged pull request. #319 (mobile app) closed as done; its leftover, native Now Playing, lives on as #512.

Versions

release-please decides the number from commit types: fix is a patch, feat a minor, feat! a major.

  • 1.x keeps shipping everything that does not break a self-hoster: new pages, fixes, Lyterion-backed features.
  • 2.0 is cut when one of these lands: the native iPhone app with offline downloads (the headline), or a change that forces action on a running install (config, data, or the Lyterion contract).

1.x: next, in order

Get the music (the most wanted)

One pipeline, play now, keep it: resolve a track from a source, stream it through the player, and let Lyterion download and place it in the background; when the file lands the track swaps to the local copy. Fetch is the same pipeline without the play. Design notes: music import, discovery status.

whatprisizestatus
#578search with candidates: a typed name returns 5 to 8 matches (Deezer, SoundCloud, YouTube) to pick from, not one guessP0Mshipped (#595, lyterion#197)
#579missing-tracks strip on album and artist pages: "own 2 of 10", greyed missing rows, Fetch rest and Play from webP1LFetch rest shipped (#596); Play from web todo (under #581)
#580artist Discover tab: full discography (MusicBrainz or Deezer), each release in library, partial or missing, Fetch or Play on every rowP1Ltodo
#582batch add: queue many songs at once. Lyterion refuses a wish while a run is live, so adds go one by oneP1Mtodo
#583new releases from followed artists go into the Release Radar; remove the "get it" cardsP1Mshipped (#597)
#581start streaming while it downloads, then swap to the file without a gapP1Ltodo

Playback and polish

whatprisizestatus
#590pause silences at once (master gain ramp) and the button updates before the event; confirm on the Mac appP0Spause ramp shipped (#600), Mac app check todo
#589crossfade: say what it does, then a smarter fade that spares an ending that already fades outP1Mtext shipped (#600), smart fade todo
#586drag and drop: queue, playlists into folders, tracks inside a playlistP1Lqueue test shipped (#599), touch reorder and the rest todo
#584playlist covers: a picture at creation, the dither otherwise, removing the cover goes back to the mosaic; showing them outside the playlist page (search palette) todoP2Sshipped (#598)
#585dither that says something: speed, pixel size and density driven by the playlist's mood and energy; a larger blurred copy as the playlist backgroundP2Mtodo
#587playlist tags under the title, not next to the sort buttonsP2Stodo
#588inferred genre: fix the "inferred, no genre tag, by artists in this genre" copy and logicP2Stodo
#602home: release cards you can click, past week only, shelf at the bottomP1Sshipped (#620)
#603Made for you: daily mixes first, no pop inP1Sshipped (#625)
#606same artist written two ways (SHYLER vs Shyler) merged on the lodesong side; track rows and the lyterion tag fix todoP1Sshipped (#622), rest todo
#609tap targets of 44px across the phone uiP1Sshipped (#623)
#610visible row actions on touch screensP1Sshipped (#623)
#632player bar: remove the 'playing on chrome on mac' textP2Sin review (#635)
#633player bar: remove the file format (FLAC, MP3...) from the bottom barP2Sin review (#635)
#604loading play icon, skeletons and page placeholdersP1Mtodo
#608library-wide check: every page has a skeleton, empty state and error stateP1Mtodo
#607refetch cover action for albums and artistsP1Stodo
#611track list time column leaves a dead strip on the rightP2Stodo
#612phone player bar: seek bar and times collide with the coverP1Stodo
#613artists A-Z rail is cut off and too small on phoneP2Stodo
#614settings on phone: tab row cut off, tiny slider and togglesP1Stodo
#615playlist header: too many competing actions, delete next to a toggleP2Stodo
#616queue panel: misaligned times, hidden row controls, bare clearP2Stodo
#617following: names are not links, unexplained badge, misclick riskP2Stodo
#618listen together: misaligned join row, unclear toggles and jargonP2Stodo
#619search palette empty state: no recents, two search fields on resultsP2Stodo
#621home and stats nits: jargon, missing border, truncated text, sparse chartP2Stodo
#605theme: import a shadcn preset codeP2Mtodo
#628command palette (cmd+k) best practices: prefetch, live data, contextual, blurP2Mtodo
#629mobile gestures: no react renders while dragging, transform and opacity onlyP2Mtodo
#630predictive preloading: pointer velocity predicts the click, preload the route firstP2Mtodo
#631remote volume control: change the volume of the device that is playingP2Mtodo
#626trackpad haptics for reordering and other drag interactionsP3Stodo
#627pre-commit hooks with lefthook: format, oxlint, react doctorP3Stodo
Daily Mix cover: the dither plus four album images inside the playlistP2Stodo, no issue yet
browse.e2e.ts fails on WebKit (the genre filter never shows "N of M")P1Stodo, no issue yet
settings search, a "what's new" in the web app, visual regression, gapless verified per formatP2Mtodo, no issue yet
cover art on release cards (Cover Art Archive)P2Stodo, no issue yet

The Mac app on a managed machine

whatprisizestatus
#591the build is ad-hoc signed and not notarized. Without a paid Apple account a download is quarantined; an admin-managed Mac may block it. Ship a user-folder install (~/Applications) that works without admin and document clearing quarantineP1Stodo

2.0: the native iPhone app

Looks like Arpeggi and Apple Music. Streaming works through the same "play now, keep it" server path. The iPhone shell and its device checklist already shipped (see above), so 2.0 is gated on the rows below.

whatprisize
#592themes: Apple, Monochrome (ours)P1M
#593offline: native file storage, a per-playlist "downloaded" switchP1L
#593download queue: new tracks in a downloaded playlist download on Wi-Fi only, with a quality choice like SpotifyP1L
#593storage manager: size per playlist, remove downloadsP2M
#512native Now Playing and remote commands, only if WebKit's lock screen proves flakyP3M

Later

Still wanted, not scheduled:

  • the hosted lodesong (#320, design), use the player against your own Navidrome with no install
  • turn on the dependency graph setting and bring the dependency review job back
  • French strings native read
  • i18n for the remaining pages (follow-up to #420) and lazy-loading player-bar menus (follow-up to #417)
  • widgets, CarPlay and Android Auto (native code, a paid developer account on iOS)
  • comparison pages for search, client error reports, offline downloads in the web shells, a docs version switcher
  • GitHub App reinstall note and the dev CSP 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