# Lyterion (/docs/lyterion)

[Lyterion](https://github.com/FindMalek/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](#new-releases) |
| **follow sync** | the artists you follow on Spotify are followed in lodesong, daily and on demand (admins). See [follow from Spotify](#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

1. **Run Lyterion** next to your stack with its own guide: [Lyterion setup](https://github.com/FindMalek/lyterion/blob/main/docs/setup.md).
   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:

   ```sh
   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`:

   ```sh
   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](/docs/spotify-import)).

## Uploads into Lyterion's inbox

lodesong's uploads ([self-hosting](/docs/self-hosting#uploads)) can land in an inbox Lyterion or beets imports from:
set `UPLOAD_DIR` to that folder, mounted writable.

## New releases

[Mixes](/docs/mixes#new-from-artists-you-follow) 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](/docs/genres).

## 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](/docs/mixes#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](https://github.com/FindMalek/lyterion/issues/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.
