README.md
lodesong
Your own music, played like a streaming app.
A monochrome web player for your Navidrome library: synced lyrics, a queue you can see,
mixes made from what you play, one session on every device.
| 1 | docker run -d -p 8080:8080 -v lodesong-data:/data \ |
| 2 | -e NAVIDROME_URL=http://host.docker.internal:4533 \ |
| 3 | ghcr.io/findmalek/lodesong |
Open http://localhost:8080 and sign in with your Navidrome account. On Linux add
--add-host=host.docker.internal:host-gateway. Compose and building from source are under Run it.
Run it · Why · Features · Works with · Docs · FAQ · Develop
Try it live: demo.lodesong.findmalek.engineer, no sign-in needed. It runs on generated music and resets every night. Or run it yourself without your own music, no Docker and no Navidrome: a fake one with 10k generated songs (bun run mock), login demo / demo.
| 1 | git clone https://github.com/FindMalek/lodesong && cd lodesong && bun install |
| 2 | bun run mock & # the fake Navidrome, on :4599 |
| 3 | NAVIDROME_URL=http://127.0.0.1:4599 bun run dev # the player, on :8080 |
For a real, copyright-free library in a real Navidrome there is the demo library.
Run it
You need a running Navidrome and Docker (or Bun to build it yourself). Pick by where your Navidrome runs:
- In a Docker compose file: use 1, so the player joins its network.
- Anywhere else (on the host, or another machine): use 2.
- No Docker: use 3.
1. Docker compose, on the same Docker network as 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 # Navidrome's service name and port on that network |
| 8 | ports: |
| 9 | - "8080:8080" |
| 10 | volumes: |
| 11 | - player-data:/data |
| 12 | networks: [navidrome] |
| 13 | volumes: |
| 14 | player-data: |
| 15 | networks: |
| 16 | navidrome: |
| 17 | external: true |
| 18 | name: navidrome_default # Navidrome's network, see `docker network ls` |
If Navidrome is in the same compose file, drop the networks lines and add player next to it.
| 1 | docker compose up -d |
2. Docker run, one container, Navidrome on the host (or set NAVIDROME_URL to any address that container can reach):
| 1 | docker run -d --name lodesong --restart unless-stopped -p 8080:8080 \ |
| 2 | --add-host host.docker.internal:host-gateway \ |
| 3 | -e NAVIDROME_URL=http://host.docker.internal:4533 \ |
| 4 | -v lodesong-data:/data \ |
| 5 | ghcr.io/findmalek/lodesong:latest |
3. From source, one executable:
| 1 | git clone https://github.com/FindMalek/lodesong && cd lodesong |
| 2 | bun install && bun run build |
| 3 | NAVIDROME_URL=http://localhost:4533 ./dist/lodesong |
Open http://localhost:8080 and 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. Every setting is in configuration.
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.
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) | ✓ | — |
It reads through Navidrome's API and never touches your files. Likes, ratings, playlists and plays stay Navidrome's, so every other app agrees with it.
Features
Listen
- Lyrics for nearly every song (Navidrome's, else LRCLIB's), line by line, word by word when the file has word
timings. Full screen with
⇧F,[]fix the timing per song. lyrics - Playback that doesn't stutter: gapless two-deck handover, ReplayGain, crossfade, a ten-band equalizer, and the next songs precached by a service worker (instant seeks, plays offline).
- 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
- A queue you can see, 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), and playlist folders (nest 4 deep, drag playlists in, a folder keeps its own picture or generated aura) that live in lodesong, not in Navidrome. A new playlist gets the animated dither cover, or a picture you add; remove it on the playlist and it goes back to Navidrome's four-album mosaic.
- Recap of your month or year, stats, history, forgotten favourites, and a radio that learns what you skip.
- Following: the artists you play most are followed for you, 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. Listen together with friends on the same server. listen together
- Apps: a Mac app with the song around the notch, an iPhone app, an Android app and a Linux and Windows app, each a small shell around the same page with media controls and background playback. On a phone the queue also hands off with Arpeggi. sync
- Scrobbling through Navidrome (Last.fm, ListenBrainz): settings say whether it is on 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.
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 album folders from the browser into your tagging inbox, and a library doctor for missing covers, tags and ReplayGain, duplicates and low-quality files, with one-click fixes through Lyterion.
- Keyboard first: everything has a key,
?shows them all. 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).
More screenshots
![]() |
![]() |
| 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 |

The hero and feature images are the built app over generated data (invented names and lyrics, generated covers, no real
music). bun run hero makes them again. The other screenshots are the demo library.
Works with
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. Subsonic apps (Arpeggi, Substreamer, Symfonium) talk to the same Navidrome and account, so likes, ratings, playlists and plays agree; the queue hands off with Arpeggi. sync
Servers: built and tested against Navidrome. Other OpenSubsonic servers should work, untested.
With Lyterion: it 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. 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 | the generated library, per-PR previews |
| 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.
Can I try it without my own music? Yes, with the fake Navidrome under the picture (bun run mock), or
bun run demo:library ./demo-music for a generated library that compose.demo.yaml serves from a
real one. 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 telemetry, no analytics. It talks to your Navidrome and, by default, to two public services:
LRCLIB for lyrics Navidrome doesn't have (the song's title and artist) and MusicBrainz once a week for new releases by the
artists you follow (artist names only). LRCLIB_URL= and MUSICBRAINZ_URL= (empty) turn each off. The rest is opt-in:
Groq for playlists from a prompt and upload tags, only with GROQ_API_KEY (it gets artist names, never your files);
the release check on GitHub, only with UPDATE_CHECK=on; Lyterion, only if you set LYTERION_URL to your own.
Scrobbling to Last.fm or ListenBrainz is Navidrome's to do, not lodesong's. every setting
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 |
| 7 | bun run hero # builds, then redraws the README hero and feature images in docs/ |
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.



