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
190 lines
9.3 KiB
Markdown
190 lines
9.3 KiB
Markdown
# 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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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](#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:
|
|
|
|
```sql
|
|
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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```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](https://github.com/yt-dlp/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:
|
|
|
|
```sh
|
|
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 |
|