sonda/internal/mixes/mixes.go
tgiachi ca5cbbf088 feat: favourites teach Sonda my taste
A heart adds to what the listening says of an artist: a favourite artist counts
as much as three complete listens, a favourite album 1.5 for its album artist and
a favourite song 1 for each of its main artists, at most 6 for one artist, without
fading with time. An artist hearted but never played is liked, with no listens.
That feeds Discover, the mixes and the smart playlists that use the taste, and
GET /me/taste.

In the mixes of what the listener likes (genre mixes, Your favourites,
Rediscover) a hearted song is wanted 1.5 times as much and a song on a hearted
album 1.25 times. New to you is not changed.
2026-11-16 11:08:20 +01:00

495 lines
15 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"
"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"
)
// 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
// 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
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).
type Filter struct {
Genres []string // as the files spell them
ArtistIDs []int64
}
// 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)
// 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
}
// 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}
}
// 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
}
// 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, Filter{Genres: d.raw, ArtistIDs: d.artists}, 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
}
cands, err := s.candidates(ctx, userID, st, *def)
if err != nil {
return Mix{}, nil, err
}
h := fnv.New64a()
fmt.Fprintf(h, "%d|%s|%d|%d", userID, id, s.now().Unix()/86400, variant)
picked := Pick(cands, Size, PerArtist, h.Sum64())
tracks, err := s.store.Tracks(ctx, picked)
if err != nil {
return Mix{}, nil, fmt.Errorf("read songs: %w", err)
}
mix, err := s.withCovers(ctx, *def)
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, Filter{Genres: d.raw, ArtistIDs: d.artists})
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:
w = 1 + 1.5*pref
if h.Plays == 0 {
w += 0.5
}
w *= heartFactor(hearts[ref.TrackID])
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
}