lodesong

Lyterion

updated Nov 3, 2026

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.

wherewhat
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 doctorfix 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 releasesget 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 syncthe artists you follow on Spotify are followed in lodesong, daily and on demand (admins). See follow from Spotify
playlistsLyterion pushes its playlists into Navidrome as normal playlists, so you can edit them in lodesong (and every Subsonic app)

Setting them up together

  1. 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 a lyterion/ sub-folder by default). Point it at the same Navidrome.

  2. Make a shared token, at least 24 characters:

    openssl rand -base64 33 | tr -d '/+=' | cut -c1-40
  3. On Lyterion's api, set LYTERION_PLAYER_TOKEN to it.

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

On this page