"Play mix" in the discover UI used to spread new songs through the whole library playlist, so the share of new songs depended on how many there were. It now plays the new songs with songs the user has played mixed in evenly at the rule's familiar_ratio (30% by default), the same ratio that sets how much of the Subsonic playlist is familiar. Which songs in each mix playlist were played recently is now recorded when the mix is built (cluster_mix_playlist.known_song_ids) and returned with the mix; the UI marks them as "Played". Mixes built before this fall back to using the library songs. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018opPJMJjLWr4RqdG6vuK6p
163 lines
7.4 KiB
Markdown
163 lines
7.4 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 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 |
|