README.md
Try it: a public live demo (sign in with demo / demo, resets every night) is set up in the
repo and waits for its host; the page says what is left.
A monochrome web player for your Navidrome library. Square covers, hairline borders, synced lyrics, a queue you can see, mixes made from what you play, and one session across all your devices.
Jump to: Self-host · Features · Browsers · With Lyterion · Docs · FAQ · Develop
Why
Your own music deserves a player as good as the streaming apps, and better where they cut corners:
| lodesong | Spotify web player | |
|---|---|---|
| your files, your server | ✓ | — |
| daily mixes, discover weekly, a daylist, made from your library | ✓ | ✓ (their catalog) |
| a playlist from a sentence ("rainy sunday, slow, warm"), only songs you own | ✓ | ✓ (their catalog) |
| one session across devices: play here, control from there | ✓ | ✓ (Connect) |
| search by a half-remembered lyric, and play from that line | ✓ | exact words only, from the start |
| lyrics timing you can nudge per song, saved across devices | ✓ | — |
| next songs downloaded ahead, playing offline in the browser | ✓ | — |
| now playing and play/pause in your terminal (Claude Code, OpenCode) | ✓ | — |
every action on the keyboard, a searchable cheat sheet (?) | ✓ | some shortcuts |
Self-host
Next to your Navidrome:
| 1 | # compose.yaml |
| 2 | services: |
| 3 | player: |
| 4 | image: ghcr.io/findmalek/lodesong:latest # amd64 |
| 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 |
| 12 | volumes: |
| 13 | player-data: |
docker compose up -d, open http://localhost:8080, sign in with your Navidrome account. No Navidrome yet?
docs/deploy/full-stack.compose.yaml runs both.
The whole stack (Navidrome, lodesong, uploads into a tagging inbox, AI playlists, a domain with HTTPS, Lyterion) is in self-hosting, written so a person or a coding agent can follow it step by step.
With a coding agent
Paste this into Claude Code, OpenCode, Codex or Cursor on the machine that will run it:
| 1 | Set up lodesong (https://github.com/FindMalek/lodesong) on this machine by following |
| 2 | docs/self-hosting.md in that repo, top to bottom. Ask me before each choice the guide marks as |
| 3 | "ask", never print secrets, and finish with the guide's "check it works" list, showing me each result. |
The guide has a decision list up front (fresh Navidrome or existing, domain or local, which extras), commands with the output to expect, and a closing checklist, so the agent can tell you what it did and what to look at.
Features
Listen
- Lyrics for nearly every song: Navidrome's, else LRCLIB's, cached and fetched ahead. Word by word, full screen
with
⇧F,[]fix the timing per song. lyrics - Playback that doesn't stutter: two decks for gapless handover, ReplayGain, the next songs precached by a service worker (instant seeks, plays offline), stalls recovered in place, crossfade and a ten-band equalizer.
- Stream quality per device: auto plays songs kept offline as they are and streams the rest as Opus 192, or pick original, mp3 320, Opus 192 or Opus 96. devices
- Queue you can see and steer: your queue apart from the album it came from, balanced shuffle, undo, stop after this song, sleep timer.
Discover · mixes
Made for you on home: daily mixes grouped by the artists you play together, discover weekly every Friday (songs you own and never played), and a daylist that changes four times a day. All saved as Navidrome playlists, so your phone has them too.
Playlists from a prompt: "late night drive, 90s, no vocals" → Groq picks artists from your library, the server builds the list from songs you own. Review it, make it again, save.
Playlist folders: make, nest (4 deep), rename and delete folders, drag playlists in and out, give a folder a picture or keep its generated aura. Folders live in lodesong, so playlist names in Navidrome never change; a
Chill / Nightgroup converts to a real folder in one click. Playlists move by drag or from "move to folder…" in their menu.
Recap: your month or year as a reel: minutes, top artists and songs, your listening hours, your biggest day, and your top songs played back or saved.
Stats, history, forgotten favourites, and a radio that learns what you skip. Radio opens as a page.
Following: the artists you play most are followed for you, you can follow, pin or unfollow others, and their new albums, EPs and singles land on a page grouped by week. With Lyterion your Spotify follows come over too. new from artists you follow
Everywhere · devices
- One session across devices, like Spotify Connect: start on one tab or computer, control it from another, move playback with the device picker in the player bar.
- Your phone: the 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
- A Mac app with the song around the notch: cover and bars while it plays, controls on hover, lyrics and the queue on click. macOS
- Phone and desktop apps: an iPhone app (sideload with a free Apple ID, or an AltStore source), an Android app (an APK from the releases) and a Linux and Windows app. Each is a small shell around the same page, with media controls and playback in the background.
- Scrobbling through Navidrome (Last.fm, ListenBrainz): settings say whether it is on for you and how many plays were sent today.
- Now playing in your terminal: the song, its lyric line and ⏮ ⏸ ⏭ above the prompt in Claude Code and OpenCode.
- Listen together with friends on the same server. listen together
Your library
- Search (
⌘K): songs, albums, artists, playlists, lyrics and commands, typo-tolerant, with filters (artist:year:1990..1999is:likedformat:flac…). search - Upload songs or whole album folders from the browser into your tagging inbox (beets, Lyterion).
- Library doctor: missing covers, tags and ReplayGain, duplicates, low-quality files, with one-click fixes through Lyterion.
- Keyboard first: everything has a key,
?shows them all, lists move withj/k. shortcuts - Fast: a 10k-song list renders ~40 rows, the library is cached so a reload paints instantly, the first screen is under 161 KB of JS (gzip).
![]() |
![]() |
| home: recently added, rediscover, most played | stats: minutes, streaks, top lists, a listening clock |
![]() |
![]() |
search (⌘K): songs, albums, artists, lyrics, commands |
queue: yours, apart from the album it came from |

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.
Browsers
Desktop browsers from the last two years. CI signs in and plays in Chromium (the whole suite) and WebKit (the engine of Safari) on every pull request.
| Chrome, Edge, Arc, Brave | Safari | Firefox | |
|---|---|---|---|
| the player (playback, lyrics, offline, mixes, devices…) | ✓ | ✓ | ✓ (not in CI) |
| mini player that stays on top | ✓ | — | — |
| pick the output device (speakers, headphones) | ✓ | — | ✓ |
| install as an app | ✓ | ✓ (File → Add to Dock) | — |
Phones: the layout works down to 320 px, and there are iPhone and Android apps; a Subsonic app (Arpeggi, Substreamer, Symfonium) works too, and the queue hands off between them. sync
With Lyterion
Lyterion brings a Spotify library over to your own Navidrome. lodesong connects to it: the import page shows each Spotify playlist and how much of it is already in your library, the doctor's "fix with Lyterion" hands songs over for a better copy, and Lyterion keeps every playlist editable in Navidrome. Setting them up together: lyterion.
Docs
| start to finish | the whole route: stack, address, music, Lyterion, every device |
| self-hosting | the whole stack, step by step, agent-friendly |
| getting started | run it next to Navidrome, sign in, first run |
| configuration | every setting (generated from the code) |
| deploy | Traefik, Caddy, nginx, Dokploy, image tags, health |
| devices · sync · listen together | one session, your phone, friends |
| iPhone · Android · Linux and Windows | the apps |
| mixes · search · lyrics · shortcuts | how they work |
| genres · lyterion · spotify import | bringing a Spotify library over |
| API | the typed API, its reference at /api, tokens for your own integrations |
| architecture · security | how it's built, what's protected |
| demo library · previews · public demo | the generated library, per-PR previews, the permanent demo |
| troubleshooting | when something's off |
| contributing · roadmap | working 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. There are also an iPhone app you can sideload with a free Apple ID (music keeps playing with the screen locked) and an Android app (an APK from the releases). A Subsonic app (Arpeggi, Substreamer, Symfonium…) works too; 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; lodesong 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). Groq is called only for playlists from a prompt, and only when you set GROQ_API_KEY; it gets your artist names,
never your files. 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 driven by Turbo: apps/player (the React app), apps/api (the Bun server that serves it and proxies
Navidrome), apps/macos (the Mac app), packages/ui (the shared shadcn components), packages/shared (types both sides
use) and packages/config (the shared tsconfig). typecheck and test run per package and are cached.
| 1 | bun install |
| 2 | bun run mock # fake Navidrome on :4599 with 10k songs (demo / demo) |
| 3 | NAVIDROME_URL=http://127.0.0.1:4599 bun run dev # app on :8080, hot reload |
| 4 | bun run check # typecheck, lint, unit tests, bundle size, generated docs |
| 5 | bun run e2e # Playwright against the mock |
| 6 | bun 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. The executable embeds satori, resvg-wasm and two OFL fonts: see THIRD-PARTY-NOTICES.md.



