README.md

lodesong: your own music, played like a streaming app

CI Latest release Docker image License Last commit

Navidrome Bun React 19 shadcn/ui OpenSubsonic

An album open next to its synced lyrics, a song playing

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:

lodesongSpotify 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:

yaml
1# compose.yaml
2services:
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
12volumes:
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:

text
1Set up lodesong (https://github.com/FindMalek/lodesong) on this machine by following
2docs/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.
  • 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.
  • 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.

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
  • 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..1999 is:liked format: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 with j/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 stats, from a listening history
home: recently added, rediscover, most played stats: minutes, streaks, top lists, a listening clock
search the queue
search (⌘K): songs, albums, artists, lyrics, commands queue: yours, apart from the album it came from

on a phone: an album, a song playing

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, BraveSafariFirefox
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, but a Subsonic app (Arpeggi, Substreamer, Symfonium) plays better in your pocket; 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 finishthe whole route: stack, address, music, Lyterion, every device
self-hostingthe whole stack, step by step, agent-friendly
getting startedrun it next to Navidrome, sign in, first run
configurationevery setting (generated from the code)
deployTraefik, Caddy, nginx, Dokploy, image tags, health
devices · sync · listen togetherone session, your phone, friends
mixes · search · lyrics · shortcutshow they work
lyterion · spotify importbringing a Spotify library over
APIthe typed API, its reference at /api, tokens for your own integrations
architecture · securityhow it's built, what's protected
demo library · previewsthe generated library, per-PR previews
troubleshootingwhen something's off
contributing · roadmapworking 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 is also an iPhone app you can sideload with a free Apple ID (music keeps playing with the screen locked). 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.

sh
1bun install
2bun run mock # fake Navidrome on :4599 with 10k songs (demo / demo)
3NAVIDROME_URL=http://127.0.0.1:4599 bun run dev # app on :8080, hot reload
4bun run check # typecheck, lint, unit tests, bundle size, generated docs
5bun run e2e # Playwright against the mock
6bun 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