Lyterion
Lyterion brings a Spotify library (liked songs, saved albums, followed artists, every playlist with its order and cover) over to your own Navidrome, writing verified, tagged files into the music folder. lodesong plays what it places and talks to it in three places.
| where | what |
|---|---|
| import (settings → library → import from spotify) | every Spotify playlist with how much of it is in your library, a progress bar each, and the songs still missing |
| library doctor | fix on a problem (a low-quality file, a fake FLAC) and fix all shown hand the songs to Lyterion's ⇪ Upgrade playlist; it looks for a better copy and replaces the file |
| add a song | ⌘K, then paste a YouTube, SoundCloud or Deezer link, or type a song name (admins only). lodesong shows what it understood, Lyterion finds a good copy across its sources, checks and places it, and you can play it when it lands |
| new releases | get it on a release in "new from artists you follow" (admins) hands that album, EP or single to Lyterion the way add a song does; RELEASES_AUTO_GET=on does it for every new one (at most ten a week). See new releases |
| follow sync | the artists you follow on Spotify are followed in lodesong, daily and on demand (admins). See follow from Spotify |
| playlists | Lyterion pushes its playlists into Navidrome as normal playlists, so you can edit them in lodesong (and every Subsonic app) |
Setting them up together
-
Run Lyterion next to your stack with its own guide: Lyterion setup. It needs its own Spotify developer app, Postgres and Trigger.dev, and writes into the same music folder Navidrome reads (
LYTERION_MUSIC_DIR, under alyterion/sub-folder by default). Point it at the same Navidrome. -
Make a shared token, at least 24 characters:
openssl rand -base64 33 | tr -d '/+=' | cut -c1-40 -
On Lyterion's api, set
LYTERION_PLAYER_TOKENto it. -
On lodesong, in
.env:LYTERION_URL=http://lyterion-api:3001 # Lyterion's api as the lodesong container reaches it LYTERION_TOKEN=<the same token>and
docker compose up -d. Both must be set, or neither.
Check: settings → library → import from spotify shows your playlists with "N of M songs in". Without Lyterion that page takes a Spotify export file instead (spotify import).
Uploads into Lyterion's inbox
lodesong's uploads (self-hosting) can land in an inbox Lyterion or beets imports from:
set UPLOAD_DIR to that folder, mounted writable.
New releases
Mixes lists new releases by artists you follow. They are handed over as the
text Artist - Release title through the same call as add a song, so Lyterion finds, checks, tags and places the
files and Navidrome picks them up on its next scan. Nothing is handed over unless you press get it or set
RELEASES_AUTO_GET=on.
Genres
Lyterion writes GENRE only on files it places itself. Backfilling it on older files is Lyterion's work; until then
lodesong says how many songs have no genre and infers genres from their artists.
Follow from Spotify
Every artist you follow on Spotify is followed in lodesong too, so their new releases show up in new from artists you follow. It runs once a day for admins who are signed in, and sync from spotify on the following page (admins) runs it now.
It only adds. Artists you follow here are never unfollowed, and an artist you unfollowed here is not followed again.
lodesong asks Lyterion's api, with the same x-lyterion-token header as the other calls:
GET {LYTERION_URL}/api/rpc/api-reference/player/followed-artists
200 {
"artists": [{ "id": "<spotify artist id>", "name": "Night Owls", "genres": ["indie"], "image": "https://..." }],
"syncedAt": "2026-11-01T04:00:00.000Z"
}lodesong reads artists[].name (required) and id; the rest is ignored. 401 for a wrong token. Lyterion already
exports followed artists into spotify_artist with its daily sync, so the endpoint reads that table
(FindMalek/lyterion#192). Until it exists lodesong gets a 404, follows
nothing and tries again at the next check.
What goes where
lodesong never downloads anything itself and never writes into the music folder itself (uploads only land in UPLOAD_DIR).
Where songs come from is Lyterion's business and is configured there.
Shortcuts
Press ? in the app for this list, searchable, with what applies right now highlighted. Every shortcut can be rebound there (pencil icon); a rebound key shows everywhere the app shows the key.
Spotify import
Rebuild your Spotify playlists and liked songs from a Spotify data export. Settings → library → import from spotify (or /import).