Each mix rebuild now also finds songs that aren't in the library: the user's Listenbrainz recommendations they've never played, plus an LB Radio prompt per mix when a Listenbrainz token is configured. Each candidate goes to the mix whose genre profile it fits best and is skipped if it's already in the library or was played recently. discover/ is a new React app to listen to the mixes: library songs stream from Subsonic and suggested songs are found on YouTube with yt-dlp, both proxied through playlistd with Range support for seeking. Suggestions can be liked (kept in a "Liked new songs" list) or hidden. - discover: candidate gathering, genre fit scoring, library filtering - web: /api/discover routes, Subsonic/YouTube streaming proxy - youtube: yt-dlp search (skipping hour-long results) and audio URLs - mix tags now hold library genre names, for display in the UI - config: listenbrainz.token, discover.ui, discover.ytdlp, discover.format Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018opPJMJjLWr4RqdG6vuK6p
159 lines
7.1 KiB
Markdown
159 lines
7.1 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/`.
|
|
|
|
## How to use
|
|
|
|
Each of these will work best when your music library is well organised with Musicbrainz metadata.
|
|
|
|
### 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 taken from recently played tracks |
|
|
| `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.
|
|
|
|
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 |
|