Add genre mixes from clustering recent listens

A new cluster_mix_rule clusters a Listenbrainz user's listens from the
last few months by MusicBrainz genre (with tracks played in the same
session pulled together) and maintains one Subsonic playlist per cluster,
filled with the cluster's most played tracks plus unheard library songs
from the best matching library genres.

- listenbrainz: fetch raw listens since a timestamp and bulk recording
  genres, handling rate limits
- cluster: tag TF-IDF + co-listen smoothing, spherical k-means with k
  chosen by silhouette score
- mix: match cluster profiles to library genres and pick songs, with a
  per-artist cap; reuse playlists across rebuilds by genre overlap
- subsonic: getGenres, getSongsByGenre, rename/delete playlist, genre and
  MBID fields on tracks, API error detection
- daemon, migration, POST/GET /api/playlist/mix and README docs

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018opPJMJjLWr4RqdG6vuK6p
This commit is contained in:
Claude committed 2026-11-13 14:53:29 +00:00
1 parent e082209bd2
commit 18b3f0974e
13 files changed
+1728 -5

No files matched your search

@@ -0,0 +1,23 @@
-- A rule that periodically clusters a user's recent listens by genre and
-- maintains one Subsonic "mix" playlist per cluster.
CREATE TABLE "cluster_mix_rule"
(
id UUID NOT NULL PRIMARY KEY,
tracking_user VARCHAR(250) NOT NULL, -- Listenbrainz user to cluster
months INT NOT NULL DEFAULT 3, -- How many months of listens to cluster
cluster_count INT, -- Number of mixes. NULL = choose automatically
playlist_size INT NOT NULL DEFAULT 50, -- Tracks per mix
familiar_ratio DOUBLE PRECISION NOT NULL DEFAULT 0.3, -- Share of each mix taken from recently played tracks
name_template VARCHAR(250) NOT NULL DEFAULT 'Mix: {label}', -- {label} is replaced by the mix's genres
refresh_hours INT NOT NULL DEFAULT 24, -- How often to rebuild the mixes
last_run TIMESTAMPTZ -- When the mixes were last rebuilt
);
-- The Subsonic playlists currently owned by a cluster mix rule.
CREATE TABLE "cluster_mix_playlist"
(
id UUID NOT NULL PRIMARY KEY,
rule_id UUID NOT NULL REFERENCES "cluster_mix_rule" (id) ON DELETE CASCADE,
playlist_id VARCHAR(250) NOT NULL, -- ID of the playlist in subsonic
tags TEXT[] NOT NULL -- Genres describing the cluster, used to keep playlists stable across rebuilds
);