sonda/internal/mixes/mixes.go
tgiachi 407b20334a feat: radio stations that Sonda makes by itself
Stations made from the music, random and without end, with nothing to set up: the
mixes the listener has (genres, favourites, rediscover, new to you), everything,
one for each decade that has 30 songs by 4 artists, and the radio of an artist (their
songs, four times as likely, and the songs of the two genres most of theirs have).
Every time a station is asked for it picks other songs, with the same weights as the
mixes (taste, hearts, nothing skipped lately).

- mixes.Service.Radios and Radio; Filter has All and years, the store has Decades
- GET /radio and GET /radio/{id}, in the OpenAPI spec
- OpenSubsonic: each station is a playlist (rd-<id>, "Radio · Rock") that has other
  songs every time it is opened, for apps that cannot play a radio that never ends
2026-11-16 12:13:55 +01:00

535 lines
17 KiB
Go

// Package mixes makes playlists for a listener, from what they listen to and from the genres of
// their music, the way the mixes of a streaming service are made.
//
// A mix is worked out when it is asked for and is never stored, like the taste profile: it is
// built from the listener's own history and from the genre tags of the files, and nothing leaves
// the server. It stays the same for a day (the seed is the user, the mix, the day and a variant
// number the client may change to ask for another).
//
// There are mixes by genre, one for each genre of the library that is big enough, the ones the
// listener plays most first, and three made for the listener that need some history: Your
// favourites, Rediscover and New to you (which needs none). The songs are picked by weighted
// chance (see Pick); a mix has Size songs, at most PerArtist by one artist.
package mixes
import (
"context"
"errors"
"fmt"
"hash/fnv"
"math/rand/v2"
"sort"
"strings"
"time"
"unicode"
"git.kmalloc.org/squid/sonda/internal/catalog"
"git.kmalloc.org/squid/sonda/internal/taste"
)
// The shape of a mix and of the list of mixes.
const (
Size = 50
PerArtist = 3
MinGenreTracks = 30 // a genre needs this many songs...
MinGenreArtists = 4 // ...by this many artists to have a mix
MaxGenreMixes = 12
MinLiked = 3 // liked artists for Your favourites, and old ones for Rediscover
MaxFavourites = 100
RediscoverAfter = 30 * 24 * time.Hour
RecentPlay = 3 * 24 * time.Hour // a song played this lately is less wanted
SkipWindow = 14 * 24 * time.Hour
unheardGenres = 3 // New to you takes songs from the best genres this many
MaxVariant = 1_000_000
recentPlayFactor = 0.3
CoverAlbums = 4 // albums that stand for a mix, to make its picture
)
// Kind is what a mix is made of.
type Kind string
// The kinds of mixes.
const (
KindGenre Kind = "genre"
KindFavourites Kind = "favourites"
KindRediscover Kind = "rediscover"
KindUnheard Kind = "unheard"
// The kinds that only the radio has.
KindAll Kind = "all"
KindDecade Kind = "decade"
KindArtist Kind = "artist"
)
// Errors returned by the service.
var (
ErrNotFound = errors.New("mix not found")
ErrInvalidInput = errors.New("invalid input")
)
// Mix says what a mix is. Its songs come from Service.Get.
type Mix struct {
ID string // "genre:rock", "favourites", "rediscover", "unheard"
Kind Kind
Title string // in English; a client may say it in its own words from the kind and the genre
Genre string // the genre, for a genre mix
Artists []string // a few of the artists it has, up to 3
Decade int // the first year of the decade, for a decade station
// AlbumIDs are up to CoverAlbums albums that have a cover and stand for the mix: by different artists, the
// ones with most songs among those the mix draws from. Empty when none of them has a cover.
AlbumIDs []int64
}
// Genre is a genre as the files spell it, with how many songs have it and by how many artists.
type Genre struct {
Name string
Tracks int
Artists int
}
// History is what one listener did with one song.
type History struct {
Plays int // listens that counted
LastPlayed time.Time // the last of them
SkippedAt time.Time // the last skip, zero when there is none
}
// Heart says why a song is a favourite of the listener: they hearted the song, or the album it is on.
type Heart struct {
Track bool
Album bool
}
// The extra chance a heart gives a song in the mixes of what the listener likes: a hearted song 1.5 times, a song of a
// hearted album 1.25 times, and both 1.75 times.
const (
heartTrackBonus = 0.5
// artistFocus is how many times more the songs of the artist of an artist station are wanted.
artistFocus = 4
heartAlbumBonus = 0.25
)
// heartFactor is how many times more a song is wanted for its hearts.
func heartFactor(h Heart) float64 {
f := 1.0
if h.Track {
f += heartTrackBonus
}
if h.Album {
f += heartAlbumBonus
}
return f
}
// TrackRef is a song that can be played and its main artist (0 when it has none).
type TrackRef struct {
TrackID int64
ArtistID int64
}
// Filter says which songs a mix draws from. Both lists narrow the choice: a song is in when it has one
// of the genres or is by one of the artists (an empty list adds nothing). All takes every song; the years, when
// they are set, keep the songs of those years among the ones chosen (or among all, when only the years are set).
type Filter struct {
Genres []string // as the files spell them
ArtistIDs []int64
All bool
MinYear int // 0 is no limit
MaxYear int
}
// Decade is a decade of the music, with how many songs and artists it has.
type Decade struct {
Start int // the first year: 1990
Tracks int
Artists int
}
// Store reads what the mixes are made of. It never writes.
type Store interface {
// Genres returns every genre of the playable songs, as spelled in the files.
Genres(ctx context.Context) ([]Genre, error)
// GenreArtists returns the names of the artists with most songs among the genres, up to limit.
GenreArtists(ctx context.Context, genres []string, limit int) ([]string, error)
// ArtistGenres returns, for each artist, how many of their songs have each genre.
ArtistGenres(ctx context.Context, artistIDs []int64) (map[int64]map[string]int, error)
// Covers returns up to limit albums that have a cover, by different artists, with most playable songs
// of the filter first.
Covers(ctx context.Context, f Filter, limit int) ([]int64, error)
// Pool returns the playable songs of the filter.
Pool(ctx context.Context, f Filter) ([]TrackRef, error)
// History returns what the user did with the songs they did anything with; minListen is how
// long a play must last to count as a listen.
History(ctx context.Context, userID int64, minListen time.Duration) (map[int64]History, error)
// Decades returns every decade the playable songs with a year are from.
Decades(ctx context.Context) ([]Decade, error)
// Hearts returns, for the songs that are favourites of the user or are on a favourite album, which of the two.
Hearts(ctx context.Context, userID int64) (map[int64]Heart, error)
ArtistNames(ctx context.Context, ids []int64) (map[int64]string, error)
// Tracks returns the songs in the order given, leaving out any that cannot be played.
Tracks(ctx context.Context, ids []int64) ([]catalog.Track, error)
}
// Taster says what the listener likes: *taste.Service.
type Taster interface {
Learn(ctx context.Context, userID int64) (taste.Learned, error)
}
// Service makes the mixes.
type Service struct {
store Store
taster Taster
minListen time.Duration
now func() time.Time
// seed is where the radio gets its luck from: random, unless a test says otherwise.
seed func() uint64
}
// NewService builds a Service. minListen is how long a play must last to count as a listen.
func NewService(store Store, taster Taster, minListen time.Duration) *Service {
return &Service{store: store, taster: taster, minListen: minListen, now: time.Now, seed: rand.Uint64}
}
// junkGenres are tags that say nothing about the music.
var junkGenres = map[string]bool{"other": true, "unknown": true, "genre": true, "none": true, "(none)": true, "misc": true, "miscellaneous": true, "blues/other": false}
// typos maps a genre that is written wrong, in the files of many people, to the right one.
var typos = map[string]string{"trash metal": "thrash metal"}
// normalizeGenre is the genre as it is compared: lower case, with "+", "-", "_" and "/" taken for
// spaces, and "" when it is not a genre ("other", "unknown"). "jazz+funk" and "jazz-funk" are one.
func normalizeGenre(g string) string {
g = strings.ToLower(strings.TrimSpace(g))
g = strings.Map(func(r rune) rune {
switch r {
case '+', '-', '_', '/':
return ' '
}
return r
}, g)
g = strings.Join(strings.Fields(g), " ")
if g == "" || junkGenres[g] {
return ""
}
if fixed, ok := typos[g]; ok {
return fixed
}
return g
}
// NormalizeGenre is normalizeGenre for the packages that compare genres the way the mixes do.
func NormalizeGenre(g string) string { return normalizeGenre(g) }
func titleCase(s string) string {
words := strings.Fields(s)
for i, w := range words {
r := []rune(w)
r[0] = unicode.ToUpper(r[0])
words[i] = string(r)
}
return strings.Join(words, " ")
}
// genreGroup is one genre with the spellings of it that the files have.
type genreGroup struct {
name string
raw []string
tracks int
artists int // of the spelling that has most: the spellings overlap, so a sum would promise too much
affinity float64
}
// definition is a mix that can be made, with what it takes.
type definition struct {
Mix
raw []string // genre spellings, for a genre mix and for New to you
artists []int64 // artists to draw from, for favourites and rediscover
// The radio's own: every song, or the songs of some years, and the artist an artist station is about.
all bool
minYear, maxYear int
focus int64
}
// filter is what the store is asked for the songs of a definition.
func (d definition) filter() Filter {
return Filter{Genres: d.raw, ArtistIDs: d.artists, All: d.all, MinYear: d.minYear, MaxYear: d.maxYear}
}
// state is what the list of mixes and one mix are both made from.
type state struct {
learned taste.Learned
defs []definition
}
// groups returns the genres that are big enough for a mix, the ones the listener plays most first,
// then the biggest.
func (s *Service) groups(ctx context.Context, learned taste.Learned) ([]genreGroup, error) {
genres, err := s.store.Genres(ctx)
if err != nil {
return nil, fmt.Errorf("read genres: %w", err)
}
byName := map[string]*genreGroup{}
for _, g := range genres {
n := normalizeGenre(g.Name)
if n == "" {
continue
}
grp := byName[n]
if grp == nil {
grp = &genreGroup{name: n}
byName[n] = grp
}
grp.raw = append(grp.raw, g.Name)
grp.tracks += g.Tracks
grp.artists = max(grp.artists, g.Artists)
}
// What the listener plays: each liked artist gives their score to the genres of their songs, in
// the share of those songs that have each.
liked := learned.Liked
if len(liked) > MaxFavourites {
liked = liked[:MaxFavourites]
}
if len(liked) > 0 {
ids := make([]int64, len(liked))
for i, p := range liked {
ids[i] = p.ArtistID
}
of, err := s.store.ArtistGenres(ctx, ids)
if err != nil {
return nil, fmt.Errorf("read artist genres: %w", err)
}
for _, p := range liked {
total := 0
for _, n := range of[p.ArtistID] {
total += n
}
for raw, n := range of[p.ArtistID] {
if grp := byName[normalizeGenre(raw)]; grp != nil && total > 0 {
grp.affinity += p.Score * float64(n) / float64(total)
}
}
}
}
out := make([]genreGroup, 0, len(byName))
for _, grp := range byName {
if grp.tracks >= MinGenreTracks && grp.artists >= MinGenreArtists {
sort.Strings(grp.raw)
out = append(out, *grp)
}
}
sort.Slice(out, func(i, j int) bool {
a, b := out[i], out[j]
switch {
case a.affinity != b.affinity:
return a.affinity > b.affinity
case a.tracks != b.tracks:
return a.tracks > b.tracks
}
return a.name < b.name
})
return out, nil
}
func (s *Service) state(ctx context.Context, userID int64) (state, error) {
learned, err := s.taster.Learn(ctx, userID)
if err != nil {
return state{}, fmt.Errorf("learn taste: %w", err)
}
groups, err := s.groups(ctx, learned)
if err != nil {
return state{}, err
}
now := s.now()
st := state{learned: learned}
liked := learned.Liked
if len(liked) > MaxFavourites {
liked = liked[:MaxFavourites]
}
var likedIDs, oldIDs []int64
for _, p := range liked {
likedIDs = append(likedIDs, p.ArtistID)
if !p.LastListened.IsZero() && now.Sub(p.LastListened) >= RediscoverAfter {
oldIDs = append(oldIDs, p.ArtistID)
}
}
namesOf := func(ids []int64) ([]string, error) {
if len(ids) > 3 {
ids = ids[:3]
}
names, err := s.store.ArtistNames(ctx, ids)
if err != nil {
return nil, fmt.Errorf("read artist names: %w", err)
}
out := make([]string, 0, len(ids))
for _, id := range ids {
if n := names[id]; n != "" {
out = append(out, n)
}
}
return out, nil
}
if len(likedIDs) >= MinLiked {
names, err := namesOf(likedIDs)
if err != nil {
return state{}, err
}
st.defs = append(st.defs, definition{Mix: Mix{ID: "favourites", Kind: KindFavourites, Title: "Your favourites", Artists: names}, artists: likedIDs})
}
if len(oldIDs) >= MinLiked {
names, err := namesOf(oldIDs)
if err != nil {
return state{}, err
}
st.defs = append(st.defs, definition{Mix: Mix{ID: "rediscover", Kind: KindRediscover, Title: "Rediscover", Artists: names}, artists: oldIDs})
}
if len(groups) > 0 {
var raw []string
for _, g := range groups[:min(unheardGenres, len(groups))] {
raw = append(raw, g.raw...)
}
st.defs = append(st.defs, definition{Mix: Mix{ID: "unheard", Kind: KindUnheard, Title: "New to you", Artists: []string{}}, raw: raw})
}
for _, g := range groups[:min(MaxGenreMixes, len(groups))] {
names, err := s.store.GenreArtists(ctx, g.raw, 3)
if err != nil {
return state{}, fmt.Errorf("read genre artists: %w", err)
}
if names == nil {
names = []string{}
}
st.defs = append(st.defs, definition{
Mix: Mix{ID: "genre:" + g.name, Kind: KindGenre, Title: titleCase(g.name) + " Mix", Genre: g.name, Artists: names},
raw: g.raw,
})
}
return st, nil
}
// List returns the mixes the listener has: the ones made for them first, then the genres.
func (s *Service) List(ctx context.Context, userID int64) ([]Mix, error) {
st, err := s.state(ctx, userID)
if err != nil {
return nil, err
}
out := make([]Mix, len(st.defs))
for i, d := range st.defs {
if out[i], err = s.withCovers(ctx, d); err != nil {
return nil, err
}
}
return out, nil
}
// withCovers gives the mix the albums that stand for it.
func (s *Service) withCovers(ctx context.Context, d definition) (Mix, error) {
ids, err := s.store.Covers(ctx, d.filter(), CoverAlbums)
if err != nil {
return Mix{}, fmt.Errorf("read covers: %w", err)
}
m := d.Mix
m.AlbumIDs = append([]int64{}, ids...)
return m, nil
}
// Get makes one mix: its songs in order. variant 0 is the mix of the day; another number gives
// another mix of the same kind. It gives ErrNotFound for a mix the listener does not have.
func (s *Service) Get(ctx context.Context, userID int64, id string, variant int) (Mix, []catalog.Track, error) {
if variant < 0 || variant > MaxVariant {
return Mix{}, nil, fmt.Errorf("%w: variant must be from 0 to %d", ErrInvalidInput, MaxVariant)
}
st, err := s.state(ctx, userID)
if err != nil {
return Mix{}, nil, err
}
var def *definition
for i := range st.defs {
if st.defs[i].ID == id {
def = &st.defs[i]
}
}
if def == nil {
return Mix{}, nil, ErrNotFound
}
h := fnv.New64a()
fmt.Fprintf(h, "%d|%s|%d|%d", userID, id, s.now().Unix()/86400, variant)
return s.make(ctx, userID, st, *def, h.Sum64())
}
// make picks the songs of a definition with a seed.
func (s *Service) make(ctx context.Context, userID int64, st state, d definition, seed uint64) (Mix, []catalog.Track, error) {
cands, err := s.candidates(ctx, userID, st, d)
if err != nil {
return Mix{}, nil, err
}
picked := Pick(cands, Size, PerArtist, seed)
tracks, err := s.store.Tracks(ctx, picked)
if err != nil {
return Mix{}, nil, fmt.Errorf("read songs: %w", err)
}
mix, err := s.withCovers(ctx, d)
if err != nil {
return Mix{}, nil, err
}
return mix, tracks, nil
}
// candidates weighs the songs a mix may take. A song skipped lately is out, and so is every song
// of an artist the listener avoids; a song played in the last days is less wanted; a song the listener hearted, or one
// on an album they hearted, is wanted more (not in New to you, which is about what they have not met).
func (s *Service) candidates(ctx context.Context, userID int64, st state, d definition) ([]Candidate, error) {
pool, err := s.store.Pool(ctx, d.filter())
if err != nil {
return nil, fmt.Errorf("read the pool: %w", err)
}
history, err := s.store.History(ctx, userID, s.minListen)
if err != nil {
return nil, fmt.Errorf("read history: %w", err)
}
hearts, err := s.store.Hearts(ctx, userID)
if err != nil {
return nil, fmt.Errorf("read favourites: %w", err)
}
now := s.now()
out := make([]Candidate, 0, len(pool))
for _, ref := range pool {
h, heard := history[ref.TrackID]
if !h.SkippedAt.IsZero() && now.Sub(h.SkippedAt) < SkipWindow {
continue
}
pref := st.learned.Prefs[ref.ArtistID].Preference
if pref < 0 {
continue
}
var w float64
switch d.Kind {
case KindGenre, KindAll, KindDecade, KindArtist:
w = 1 + 1.5*pref
if h.Plays == 0 {
w += 0.5
}
w *= heartFactor(hearts[ref.TrackID])
if d.Kind == KindArtist && ref.ArtistID == d.focus {
w *= artistFocus // the songs of the artist the station is about
}
case KindFavourites, KindRediscover:
if pref <= 0 {
continue
}
w = (pref + 0.2) * heartFactor(hearts[ref.TrackID])
case KindUnheard:
if heard {
continue
}
w = 1
}
if h.Plays > 0 && now.Sub(h.LastPlayed) < RecentPlay {
w *= recentPlayFactor
}
out = append(out, Candidate{TrackID: ref.TrackID, ArtistID: ref.ArtistID, Weight: w})
}
return out, nil
}