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.

CI Latest release Docker image License

sh
1docker 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.

lodesong playing: the home screen with daily mixes and the queue, then full-screen lyrics next to the cover, one line at a time.

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.

sh
1git clone https://github.com/FindMalek/lodesong && cd lodesong && bun install
2bun run mock & # the fake Navidrome, on :4599
3NAVIDROME_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:

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 # Navidrome's service name and port on that network
8 ports:
9 - "8080:8080"
10 volumes:
11 - player-data:/data
12 networks: [navidrome]
13volumes:
14 player-data:
15networks:
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.

sh
1docker compose up -d

2. Docker run, one container, Navidrome on the host (or set NAVIDROME_URL to any address that container can reach):

sh
1docker 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:

sh
1git clone https://github.com/FindMalek/lodesong && cd lodesong
2bun install && bun run build
3NAVIDROME_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:

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.

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)✓—

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

Two views: the album grid with generated dithered covers, and the queue with the device picker open.

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..1999 is:liked format: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 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

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, 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, 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 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
iPhone · Android · Linux and Windowsthe apps
mixes · search · lyrics · shortcutshow they work
genres · 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 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.

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
7bun 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.