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>
269 lines
13 KiB
Markdown
269 lines
13 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`.
|
|
|
|
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).
|
|
|
|
```sh
|
|
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](#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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```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 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](#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 (after logging in, see [Logging in](#logging-in)):
|
|
|
|
```sh
|
|
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:
|
|
|
|
```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.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.
|
|
|
|
The `.deb` includes it (see [Container build](#container-build-ubuntu-2204)). To run it from a
|
|
checkout, build it with:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sql
|
|
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:
|
|
|
|
```sh
|
|
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 |
|