Claude a594c56abc Set up logging properly
Rocket's logger was the only one, so messages from the daemons depended on
it having launched, and most messages bypassed logging with println!.

- Install env_logger at startup: level from log.level (LOG_LEVEL), with
  RUST_LOG overriding it. Rocket's per-request logs and sqlx's Postgres
  notices are kept to warnings.
- Under systemd, prefix lines with their syslog priority so journald
  records levels (journalctl -p warning works).
- Replace every println! with a log macro at a fitting level.
- Recurring failures are a warning when they start or change, debug while
  they repeat, and an info message when they recover.
- Listenbrainz errors are readable: an unknown user is "Listenbrainz user
  "x" doesn't exist" rather than a JSON decode error, and a period without
  stats yet (204) leaves the playlist alone instead of failing to decode.
  The UI's Refresh shows the same messages.
- Warnings name the playlist or rule they're about.
- Songs missing from the library are debug output, not errors every tick.
- Daemons no longer run twice at startup (interval's first tick is
  immediate), and a failing playlist rule or daemon is logged instead of
  panicking the task.
- Subsonic errors display as messages rather than Debug output.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018opPJMJjLWr4RqdG6vuK6p
2026-11-13 21:48:54 +00:00
2026-11-07 18:01:56 +00:00
2026-11-13 21:48:54 +00:00
2026-11-13 21:48:54 +00:00
2024-04-20 19:10:49 +01:00
2026-11-13 21:48:54 +00:00
2026-11-13 21:48:54 +00:00
2026-11-07 18:01:56 +00:00
2023-08-13 21:48:41 +01:00
2026-11-13 21:48:54 +00:00

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>/rest
  • SUBSONIC_USERNAME, your Subsonic username
  • SUBSONIC_PASSWORD, your Subsonic password
  • DATABASE_URL, the URL for a Postgres database
  • DAEMON_INTERVAL, how often to update playlists

For deploying, these can be configured in /etc/playlistd.toml.

Container build (Ubuntu 22.04)

Build the image:

podman build -t playlistd-22 -f Containerfile .

Then build 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 cargo deb

The package is written to target/debian/.

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:

  1. Your listens for the period are fetched from Listenbrainz, along with the MusicBrainz genres of each recording, its release group and its artists.
  2. 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.
  3. 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.
  4. Each mix is made of the cluster's most played tracks (familiar_ratio of 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 most playlist_size / 8 songs 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:

curl -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 listenbrainz.token is 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.

Build it with:

cd discover
npm install
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).

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
S
Description
No description provided
Readme AGPL-3.0
875 KiB
0 Stars 1 Watchers 0 Forks
Languages
Rust 88.9%
TypeScript 7.4%
Dockerfile 1.4%
SCSS 1.2%
HTML 1.1%