The first visit to the UI creates the account from a username and password; after that every API route needs a session cookie from logging in. Accounts are stored in app_user (Argon2id password hashes) and sessions in user_session (SHA-256 token hashes, 30 days). The account page lets the user save a Listenbrainz token, checked with Listenbrainz first. It takes priority over listenbrainz.token from the config for LB Radio suggestions. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
playlistd
A daemon and API for automatically updating Subsonic playlists from Listenbrainz data
Note: I've not actually tested this against Subsonic, only Navidrome
Building & running
This is a standard Rust project and should be uncomplicated to build and run. It does read some environment variables:
SUBSONIC_BASE, your Subsonic instance's API base. For navidrome users, this is<protocol>://<host>/restSUBSONIC_USERNAME, your Subsonic usernameSUBSONIC_PASSWORD, your Subsonic passwordDATABASE_URL, the URL for a Postgres databaseDAEMON_INTERVAL, how often to update playlists
For deploying, these can be configured in /etc/playlistd.toml.
SQL queries are checked at compile time, against the database in DATABASE_URL if it's set, or
otherwise against the query data in .sqlx/. After changing a query, update that with
cargo sqlx prepare (from cargo install sqlx-cli) and commit it.
Docker Compose
compose.yaml runs playlistd with its own Postgres database. The image includes the web UI,
yt-dlp and Deno (which yt-dlp needs for YouTube).
cp .env.example .env # then fill in your Subsonic server and a database password
docker compose up -d --build
The web UI is then at http://localhost:8000. The first visit asks you to create an account (see
Logging in), and anyone who reaches it first can, so it only listens on the Docker
host by default: create your account, then set PLAYLISTD_BIND=0.0.0.0 in .env to open it to
your network. If your
Subsonic server runs on the Docker host, use http://host.docker.internal:4533/rest as
SUBSONIC_BASE.
YouTube changes often break older yt-dlp versions, and the image installs the latest one when it's built, so rebuild it now and then to keep new songs playing:
docker compose build --pull && docker compose up -d
With podman, use podman compose, or build the image with podman build -f Dockerfile .: on its
own, podman build picks Containerfile, which builds the .deb below.
Container build (Ubuntu 22.04)
Build the image:
podman build -t playlistd-22 -f Containerfile .
Then build the web UI and the .deb. The sqlx query macros check queries against a live,
migrated database at compile time, so the host's Postgres socket is mounted into the container. With
rootless podman, the container's root maps to your host user, so local peer authentication works
without a password:
podman run --rm \
-v "$PWD":/mnt -w /mnt \
-v /var/run/postgresql:/var/run/postgresql \
-e DATABASE_URL='postgres://jude@%2Fvar%2Frun%2Fpostgresql/playlistd' \
playlistd-22 sh -c 'npm --prefix discover ci && npm --prefix discover run build && cargo deb'
The package is written to target/debian/. It installs the web UI to /usr/share/playlistd/discover,
which the default config serves at /. cargo deb refuses to build the package if the UI hasn't been
built.
The package recommends yt-dlp, for playing suggested songs from YouTube. Distribution packages of
yt-dlp are often too old to work with YouTube, so you may want a current one instead, e.g. from pip.
Logging
playlistd logs to stdout. Set the level with log.level in playlistd.toml (or LOG_LEVEL):
error, warn, info (the default), debug or trace. RUST_LOG overrides it for finer control,
e.g. RUST_LOG=playlistd=debug to also see which top songs couldn't be found in your library.
Under systemd, lines are tagged with their priority, so journalctl -u playlistd -p warning shows
just the problems. A failure that keeps happening (say, a tracked playlist for a Listenbrainz user
that doesn't exist) is logged as a warning once, and again only if the error changes; recovering
from it is logged too.
How to use
Each of these will work best when your music library is well organised with Musicbrainz metadata.
Tracked playlists, recurring playlists and genre mixes can all be managed from the web UI (see Discover UI), under "Tracked playlists". The SQL below does the same by hand.
Tracked playlist
A tracked playlist is a single Subsonic playlist that tracks data from Listenbrainz. For example, a playlist that contains your top 15 songs from the past week.
You can create a tracked playlist by inserting a row into the tracked_playlist table.
Tracked playlist rule
A tracked playlist rule is a time-based instruction to create a new tracked playlist. For example, a playlist every year that contains your top songs.
You can create a tracked playlist rule by inserting a row into the create_tracked_playlist table.
For a yearly top songs playlist, run the following:
INSERT INTO create_tracked_playlist (id, name_template, playlist_size, tracking_user, tracking_type)
VALUES (gen_random_uuid(), '%Y - Top 100', 100, 'jellywx', 'this_year');
Genre mixes
A cluster mix rule groups the tracks you've listened to over the last few months by genre, and keeps one Subsonic playlist ("mix") per group, filled with songs from your library.
How it works:
- Your listens for the period are fetched from Listenbrainz, along with the MusicBrainz genres of each recording, its release group and its artists.
- Tracks are clustered on their genres. Tracks you tend to play in the same listening session are pulled closer together, so untagged tracks and genre-hopping artists land with what you play them next to. The number of clusters is chosen automatically unless you set one.
- Each cluster's most characteristic genres are matched against your library's genres
(
getGenres/getSongsByGenre), case and punctuation insensitively, so a library tagged with MusicBrainz genres by Picard works best. - Each mix is made of the cluster's most played tracks (
familiar_ratioof the mix), plus songs from the matching genres that you haven't played in the period, picked at random weighted by how well their genres fit, with at mostplaylist_size / 8songs per artist.
Mixes are rebuilt every refresh_hours. On a rebuild, existing mix playlists are reused for the
new cluster with the most similar genres (and renamed), new playlists are created for new
clusters, and playlists for clusters that no longer appear are deleted.
Create a rule through the API (after logging in, see Logging in):
curl -b cookies -X POST localhost:8000/api/playlist/mix -H 'Content-Type: application/json' \
-d '{"tracking_user": "jellywx", "months": 3, "playlist_size": 50}'
or with SQL:
INSERT INTO cluster_mix_rule (id, tracking_user, months, playlist_size)
VALUES (gen_random_uuid(), 'jellywx', 3, 50);
| Column | Default | Meaning |
|---|---|---|
months |
3 | Months of listening history to cluster |
cluster_count |
automatic | Number of mixes |
playlist_size |
50 | Songs per mix |
familiar_ratio |
0.3 | Share of each mix made of songs you've played recently (also used by the discover UI's "Play mix") |
name_template |
Mix: {label} |
Playlist name; {label} becomes the mix's top genres |
refresh_hours |
24 | How often to rebuild the mixes |
discovery_count |
15 | New songs (not in your library) to suggest per mix |
Set last_run to NULL to rebuild a rule's mixes on the next daemon tick.
Discover UI
discover/ is a React app for listening to the genre mixes, alongside new songs that aren't in
your library yet.
Each time the mixes are rebuilt, playlistd also looks for new songs for each mix:
- your Listenbrainz recommendations, keeping only recordings you've never listened to, and
- if a Listenbrainz token is saved to your account (or
listenbrainz.tokenis set), an LB Radio playlist for each mix's top genres.
Every candidate's MusicBrainz genres are compared with each mix's, and it's suggested in the mix it fits best (if it fits well enough), skipping songs already in your library.
In the UI, songs from your library stream from Subsonic. New songs are found on YouTube with yt-dlp and streamed through playlistd, so yt-dlp needs to be installed on the server (keep it up to date: YouTube changes often break older versions). You can like a new song to keep it in "Liked new songs", or hide it so it isn't suggested again.
"Play mix" plays a mix's new songs in random order with songs you already know (the songs in the
mix you've played recently) mixed in evenly, so that familiar_ratio of what you hear is familiar.
If a mix has too few known songs to keep that ratio, all of them are used.
The .deb includes it (see Container build). To run it from a
checkout, build it with:
cd discover
npm ci
npm run build
and set discover.ui (or DISCOVER_UI) to the discover/dist directory to serve it from
playlistd at /. For development, npm run dev serves the UI with hot reload and forwards API
requests to playlistd on localhost:8000 (or PLAYLISTD_URL).
Logging in
The web UI and every API endpoint need you to log in. There's no default account: the first time
anyone opens the UI, it asks for a username and password, and creates the account with them. After
that, the UI shows a login page instead, and new accounts can't be created. Passwords are stored as
Argon2id hashes in the app_user table, and logging in sets a session cookie that lasts 30 days.
To start over (e.g. if you forget your password), delete the account, and the next visit to the UI will set it up again:
DELETE FROM app_user;
Under the account page in the UI (your username, in the sidebar), you can save your Listenbrainz
user token to your account. It's checked with Listenbrainz first, and is then used instead of
listenbrainz.token from the config.
To use the API from a script, log in with a cookie jar and pass it with each request:
curl -c cookies -X POST localhost:8000/api/auth/login -H 'Content-Type: application/json' \
-d '{"username": "you", "password": "your password"}'
curl -b cookies localhost:8000/api/tracked/playlists
Requests without a valid session get 401 {"error": "Log in to continue"}. These endpoints are
under /api/auth:
| Endpoint | Purpose |
|---|---|
GET /status |
Whether the account still has to be set up, and who's logged in |
POST /setup |
Create the account (username, password), only if there isn't one |
POST /login |
Log in (username, password) |
POST /logout |
Log out |
GET /account |
The logged in account |
PUT /account/listenbrainz |
Save a Listenbrainz token to the account (empty removes it) |
Endpoints
The UI uses these endpoints under /api/discover:
| Endpoint | Purpose |
|---|---|
GET /rules |
Cluster mix rules |
GET /rules/<id>/mixes |
A rule's mixes |
GET /mixes/<id> |
A mix's library songs and new song suggestions |
GET /rules/<id>/liked |
Liked suggestions |
PUT /suggestions/<id> |
Set a suggestion's status (new, liked, dismissed) |
POST /rules/<id>/rebuild |
Rebuild a rule's mixes on the next daemon tick |
GET /stream/<song id> |
Stream a library song from Subsonic |
GET /cover/<cover art id> |
Library cover art from Subsonic |
GET /youtube/<suggestion id> |
Stream a suggested song from YouTube |
and these under /api/tracked for tracked playlists:
| Endpoint | Purpose |
|---|---|
GET /playlists |
Tracked playlists, with their names and song counts |
POST /playlists |
Track an existing playlist (playlist_id) or a new one (name) |
PUT /playlists/<id> |
Change size, user or period; rename with name |
DELETE /playlists/<id>?delete_playlist=true |
Stop tracking, optionally deleting the playlist |
POST /playlists/<id>/refresh |
Update a playlist's songs now |
GET /subsonic-playlists |
Playlists that can be tracked |
GET/POST /rules, PUT/DELETE /rules/<id> |
Recurring playlist rules |
GET /preview-name?template= |
What a name template produces today |