feat(smart): the songs I play most, in rotation lately and over the year

- A smart playlist rule, plays_within_days, that counts only the plays of the last N days where plays are counted: the minimum of plays and the most and least played orders. The other listening rules are not changed.
- Two more suggested smart playlists on it: on-rotation (the most played of the last 30 days, at least twice) and top-year (the same over 365 days). most-played stays as the plays of all time.
- The editor has the new rule and the page says it in words. Texts in English and Italian.
This commit is contained in:
tgiachi 2026-11-13 10:44:55 +01:00
commit bf5c108785
7 changed files with 297 additions and 28 deletions

View file

@ -291,7 +291,7 @@ func TestSuggestedSmartPlaylistsAreThereForEveryoneWithTheirRules(t *testing.T)
s := x.(map[string]any)
byKey[s["key"].(string)] = s
}
for _, key := range []string{"recently-added", "never-played", "most-played", "forgotten", "high-quality", "long-tracks"} {
for _, key := range []string{"recently-added", "on-rotation", "top-year", "most-played", "never-played", "forgotten", "high-quality", "long-tracks"} {
if byKey[key] == nil {
t.Errorf("%s is missing from %v", key, byKey)
}
@ -348,3 +348,52 @@ func TestASuggestedSmartPlaylistIsKeptAsAPlaylist(t *testing.T) {
t.Errorf("unknown key: %d %v", r.Code, r.Body)
}
}
func TestPlaysInTheLastDaysAreCountedForTheListenerOnly(t *testing.T) {
m := newMixAPI(t)
var ids []int64
rows, err := m.db.Query("SELECT id FROM tracks WHERE title LIKE 'hard song%' ORDER BY id LIMIT 3")
if err != nil {
t.Fatal(err)
}
for rows.Next() {
var id int64
if err := rows.Scan(&id); err != nil {
t.Fatal(err)
}
ids = append(ids, id)
}
rows.Close()
// Song 0: three listens long ago. Song 1: two listens this week. Song 2: one this week.
events := []struct {
track int64
days int
}{{ids[0], 200}, {ids[0], 201}, {ids[0], 202}, {ids[1], 1}, {ids[1], 2}, {ids[2], 3}}
for i, e := range events {
if _, err := m.db.Exec(`INSERT INTO listening_events (user_id, track_id, event_type, occurred_at, duration_played_ms, idempotency_key)
VALUES (1, ?, 'complete', strftime('%s','now') - ?, 60000, ?)`, e.track, e.days*86400, fmt.Sprintf("r%d", i)); err != nil {
t.Fatal(err)
}
}
rot := trackIDs(t, do(t, m.h, "GET", sp+"/suggested/on-rotation/tracks", m.alice, nil))
if len(rot) != 1 || rot[0] != float64(ids[1]) {
t.Errorf("on rotation = %v, want only the song played twice this week (%d)", rot, ids[1])
}
year := trackIDs(t, do(t, m.h, "GET", sp+"/suggested/top-year/tracks", m.alice, nil))
if len(year) != 2 || year[0] != float64(ids[0]) && year[0] != float64(ids[1]) {
t.Errorf("top of the year = %v", year)
}
all := trackIDs(t, do(t, m.h, "GET", sp+"/suggested/most-played/tracks", m.alice, nil))
if len(all) != 3 || all[0] != float64(ids[0]) {
t.Errorf("most played ever = %v, want song %d first (three listens)", all, ids[0])
}
// The rule is in the API for a smart playlist of one's own too.
id := smartMade(t, m, map[string]any{"name": "Lately", "sort": "most_played", "rules": map[string]any{"plays_within_days": 7, "min_plays": 1}})
got := smartTracks(t, m, id, "")
if len(got) != 2 || got[0] != float64(ids[1]) {
t.Errorf("a smart playlist with the window = %v, want %d then %d", got, ids[1], ids[2])
}
if r := do(t, m.h, "POST", sp, m.alice, map[string]any{"name": "x", "rules": map[string]any{"plays_within_days": -1}}); r.Code != http.StatusBadRequest {
t.Errorf("a negative window: %d", r.Code)
}
}

View file

@ -1385,8 +1385,10 @@ paths:
summary: The smart playlists Sonda makes for you
description: |
A fixed set that is there without anybody making it, the same rules for everyone and worked out on your
own library and history: `recently-added`, `never-played`, `most-played`, `forgotten` (played once, but not
in the last 90 days), `high-quality` (bitrate of 900 kbps or more) and `long-tracks` (6 minutes or more).
own library and history: `recently-added`, `on-rotation` (the songs you played most in the last 30 days, at
least twice), `top-year` (the same over 365 days), `most-played` (over all time), `never-played`, `forgotten`
(played once, but not in the last 90 days), `high-quality` (bitrate of 900 kbps or more) and `long-tracks`
(6 minutes or more).
Nothing is stored for them. A client says their names in its own language from the `key`. To change one,
make a smart playlist of your own from its rules with `POST /smart-playlists`.
security: [{bearerAuth: []}]
@ -2881,7 +2883,7 @@ components:
in: path
required: true
description: A key from `GET /smart-playlists/suggested`.
schema: {type: string, enum: [recently-added, never-played, most-played, forgotten, high-quality, long-tracks]}
schema: {type: string, enum: [recently-added, on-rotation, top-year, most-played, never-played, forgotten, high-quality, long-tracks]}
MixId:
name: id
in: path
@ -3646,6 +3648,7 @@ components:
played_within_days: {type: integer, minimum: 0, maximum: 36500}
not_played_within_days: {type: integer, minimum: 0, maximum: 36500, description: Songs not played for this many days (the ones never played too).}
min_plays: {type: integer, minimum: 0, maximum: 1000000}
plays_within_days: {type: integer, minimum: 0, maximum: 36500, description: "Counts only the plays of the last N days where plays are counted: `min_plays` and the `most_played` and `least_played` orders. The other listening rules are not changed."}
skipped_within_days: {type: integer, minimum: 0, maximum: 36500}
not_skipped_within_days: {type: integer, minimum: 0, maximum: 36500, description: Leaves out songs skipped in the last days.}
liked_artists_only: {type: boolean, description: Only songs by artists you like.}
@ -3658,7 +3661,7 @@ components:
additionalProperties: false
required: [key, rules, sort, limit]
properties:
key: {type: string, enum: [recently-added, never-played, most-played, forgotten, high-quality, long-tracks]}
key: {type: string, enum: [recently-added, on-rotation, top-year, most-played, never-played, forgotten, high-quality, long-tracks]}
rules: {$ref: '#/components/schemas/SmartRules'}
sort: {$ref: '#/components/schemas/SmartSort'}
limit: {type: integer, minimum: 1, maximum: 500}

View file

@ -93,12 +93,15 @@ type Rules struct {
AddedWithinDays int `json:"added_within_days,omitempty"`
// The listening rules are about the owner's history: a listen counts when the play was completed or lasted
// the minimum listen of the server, and a skip when it came before that.
NeverPlayed bool `json:"never_played,omitempty"`
PlayedWithinDays int `json:"played_within_days,omitempty"`
NotPlayedWithinDays int `json:"not_played_within_days,omitempty"`
MinPlays int `json:"min_plays,omitempty"`
SkippedWithinDays int `json:"skipped_within_days,omitempty"`
NotSkippedWithinDays int `json:"not_skipped_within_days,omitempty"`
NeverPlayed bool `json:"never_played,omitempty"`
PlayedWithinDays int `json:"played_within_days,omitempty"`
NotPlayedWithinDays int `json:"not_played_within_days,omitempty"`
MinPlays int `json:"min_plays,omitempty"`
// PlaysWithinDays counts only the plays of the last N days where plays are counted: the minimum of plays and
// the most and least played orders. It does not change the other listening rules.
PlaysWithinDays int `json:"plays_within_days,omitempty"`
SkippedWithinDays int `json:"skipped_within_days,omitempty"`
NotSkippedWithinDays int `json:"not_skipped_within_days,omitempty"`
// LikedArtistsOnly keeps the songs of artists the owner likes; WithoutAvoidedArtists leaves out the ones
// the owner avoids (see package taste).
LikedArtistsOnly bool `json:"liked_artists_only,omitempty"`
@ -179,6 +182,8 @@ type Store interface {
// 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)
// Plays returns how many listens the user has of each song since a moment, for the songs they listened to.
Plays(ctx context.Context, userID int64, minListen time.Duration, since time.Time) (map[int64]int, 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)
}
@ -311,6 +316,7 @@ func cleanRules(r Rules) (Rules, error) {
{"skipped_within_days", r.SkippedWithinDays, MaxDays},
{"not_skipped_within_days", r.NotSkippedWithinDays, MaxDays},
{"min_plays", r.MinPlays, MaxPlays},
{"plays_within_days", r.PlaysWithinDays, MaxDays},
{"min_duration_sec", r.MinDurationSec, MaxDurationSec},
{"max_duration_sec", r.MaxDurationSec, MaxDurationSec},
} {
@ -533,13 +539,23 @@ func (s *Service) run(ctx context.Context, userID, id int64, r Rules, order Sort
return nil, fmt.Errorf("read the songs: %w", err)
}
countsPlays := order == SortMostPlayed || order == SortLeastPlayed || r.MinPlays > 0
var history map[int64]History
if order == SortMostPlayed || order == SortLeastPlayed || r.NeverPlayed || r.MinPlays > 0 ||
if (countsPlays && r.PlaysWithinDays == 0) || r.NeverPlayed ||
r.PlayedWithinDays > 0 || r.NotPlayedWithinDays > 0 || r.SkippedWithinDays > 0 || r.NotSkippedWithinDays > 0 {
if history, err = s.store.History(ctx, userID, s.minListen); err != nil {
return nil, fmt.Errorf("read history: %w", err)
}
}
// The plays that are counted: all of them, or only those of the window.
plays := func(id int64) int { return history[id].Plays }
if countsPlays && r.PlaysWithinDays > 0 {
window, err := s.store.Plays(ctx, userID, s.minListen, s.now().Add(-time.Duration(r.PlaysWithinDays)*24*time.Hour))
if err != nil {
return nil, fmt.Errorf("read plays: %w", err)
}
plays = func(id int64) int { return window[id] }
}
var learned taste.Learned
if r.LikedArtistsOnly || r.WithoutAvoidedArtists {
if learned, err = s.taster.Learn(ctx, userID); err != nil {
@ -561,7 +577,7 @@ func (s *Service) run(ctx context.Context, userID, id int64, r Rules, order Sort
r.NeverPlayed && h.Plays > 0,
r.PlayedWithinDays > 0 && !within(h.LastPlayed, r.PlayedWithinDays),
r.NotPlayedWithinDays > 0 && within(h.LastPlayed, r.NotPlayedWithinDays),
r.MinPlays > 0 && h.Plays < r.MinPlays,
r.MinPlays > 0 && plays(c.TrackID) < r.MinPlays,
r.SkippedWithinDays > 0 && !within(h.SkippedAt, r.SkippedWithinDays),
r.NotSkippedWithinDays > 0 && within(h.SkippedAt, r.NotSkippedWithinDays),
r.LikedArtistsOnly && learned.Prefs[c.ArtistID].Preference <= 0,
@ -571,7 +587,7 @@ func (s *Service) run(ctx context.Context, userID, id int64, r Rules, order Sort
kept = append(kept, c)
}
sortCandidates(kept, order, history, func(c Candidate) uint64 {
sortCandidates(kept, order, plays, func(c Candidate) uint64 {
h := fnv.New64a()
fmt.Fprintf(h, "%d|%d|%d|%d|%d", userID, id, now.Unix()/86400, variant, c.TrackID)
return h.Sum64()
@ -592,7 +608,7 @@ func (s *Service) run(ctx context.Context, userID, id int64, r Rules, order Sort
// sortCandidates puts the songs in the order; a tie goes to the lower id. A random order sorts by the
// hash of the song with the seed of the day, which is the same until the day or the variant changes.
func sortCandidates(c []Candidate, order Sort, history map[int64]History, hash func(Candidate) uint64) {
func sortCandidates(c []Candidate, order Sort, plays func(int64) int, hash func(Candidate) uint64) {
var keys map[int64]uint64
if order == SortRandom {
keys = make(map[int64]uint64, len(c))
@ -610,7 +626,7 @@ func sortCandidates(c []Candidate, order Sort, history map[int64]History, hash f
return 1
}
case SortMostPlayed, SortLeastPlayed:
pa, pb := history[a.TrackID].Plays, history[b.TrackID].Plays
pa, pb := plays(a.TrackID), plays(b.TrackID)
if order == SortLeastPlayed {
pa, pb = pb, pa
}
@ -664,6 +680,7 @@ func (r Rules) Summary() string {
add(r.PlayedWithinDays > 0, "played in the last %d days", r.PlayedWithinDays)
add(r.NotPlayedWithinDays > 0, "not played for %d days", r.NotPlayedWithinDays)
add(r.MinPlays > 0, "played at least %d times", r.MinPlays)
add(r.PlaysWithinDays > 0, "plays counted over the last %d days", r.PlaysWithinDays)
add(r.SkippedWithinDays > 0, "skipped in the last %d days", r.SkippedWithinDays)
add(r.NotSkippedWithinDays > 0, "not skipped in the last %d days", r.NotSkippedWithinDays)
add(r.LikedArtistsOnly, "only liked artists")

View file

@ -23,6 +23,8 @@ type fakeStore struct {
cands []Candidate
history map[int64]History
asked []Filter
windowed map[int64]int // plays inside the window asked for
since []time.Time // the starts of the windows asked for
saved map[int64]SmartPlaylist // by id
nextID int64
listened int // how many times history was read
@ -44,6 +46,11 @@ func (f *fakeStore) History(context.Context, int64, time.Duration) (map[int64]Hi
return f.history, nil
}
func (f *fakeStore) Plays(_ context.Context, _ int64, _ time.Duration, since time.Time) (map[int64]int, error) {
f.since = append(f.since, since)
return f.windowed, nil
}
func (f *fakeStore) Tracks(_ context.Context, ids []int64) ([]catalog.Track, error) {
out := make([]catalog.Track, len(ids))
for i, id := range ids {
@ -539,7 +546,7 @@ func TestSuggestedAreAFixedSetOfValidRules(t *testing.T) {
t.Errorf("%s: shape changed by cleaning: %+v", s.Key, in)
}
}
for _, want := range []string{"recently-added", "never-played", "most-played", "forgotten", "high-quality", "long-tracks"} {
for _, want := range []string{"recently-added", "on-rotation", "top-year", "most-played", "never-played", "forgotten", "high-quality", "long-tracks"} {
if !seen[want] {
t.Errorf("%s is missing", want)
}
@ -612,3 +619,88 @@ func TestSummaryOfRulesIsAFewWordsInEnglish(t *testing.T) {
t.Errorf("ids: %q", got)
}
}
// ---- plays inside a window ----
func TestPlaysCanBeCountedOverTheLastDaysOnly(t *testing.T) {
st := newStore()
st.cands = songs(5)
// Over all time song 1 is the most played; in the last 30 days it is song 3.
st.history = map[int64]History{1: {Plays: 40, LastPlayed: daysAgo(100)}, 2: {Plays: 9, LastPlayed: daysAgo(3)}, 3: {Plays: 8, LastPlayed: daysAgo(1)}, 4: {Plays: 2, LastPlayed: daysAgo(2)}}
st.windowed = map[int64]int{2: 3, 3: 7, 4: 1}
svc := newService(st, taste.Learned{})
got := preview(t, svc, Rules{}, SortMostPlayed)
if !slices.Equal(got[:3], []int64{1, 2, 3}) {
t.Fatalf("over all time = %v, want 1, 2, 3 first", got)
}
if len(st.since) != 0 {
t.Errorf("a window was asked for with no rule that wants one: %v", st.since)
}
got = preview(t, svc, Rules{PlaysWithinDays: 30}, SortMostPlayed)
if want := []int64{3, 2, 4, 1, 5}; !slices.Equal(got, want) {
t.Errorf("in the last 30 days = %v, want %v: 40 old plays count for nothing", got, want)
}
if len(st.since) != 1 || !st.since[0].Equal(daysAgo(30)) {
t.Errorf("window starts = %v, want %v", st.since, daysAgo(30))
}
got = preview(t, svc, Rules{PlaysWithinDays: 30}, SortLeastPlayed)
if got[0] != 1 && got[0] != 5 {
t.Errorf("least played in the window = %v, want a song with no plays in it first", got)
}
}
func TestTheMinimumOfPlaysCountsOnlyTheWindowWhenThereIsOne(t *testing.T) {
st := newStore()
st.cands = songs(4)
st.history = map[int64]History{1: {Plays: 40}, 2: {Plays: 9}, 3: {Plays: 8}, 4: {Plays: 2}}
st.windowed = map[int64]int{2: 3, 3: 7, 4: 1}
svc := newService(st, taste.Learned{})
if got := preview(t, svc, Rules{MinPlays: 3}, SortTitle); !slices.Equal(got, []int64{1, 2, 3}) {
t.Errorf("at least 3 plays, ever = %v", got)
}
if got := preview(t, svc, Rules{MinPlays: 3, PlaysWithinDays: 30}, SortTitle); !slices.Equal(got, []int64{2, 3}) {
t.Errorf("at least 3 plays in the last 30 days = %v, want 2 and 3", got)
}
// Never played still means never, in the window or not.
if got := preview(t, svc, Rules{NeverPlayed: true, PlaysWithinDays: 30}, SortTitle); len(got) != 0 {
t.Errorf("never played = %v: every song has been played", got)
}
}
func TestOnRotationAndTheTopOfTheYearCountTheirOwnWindows(t *testing.T) {
st := newStore()
st.cands = songs(6)
st.windowed = map[int64]int{1: 1, 2: 5, 3: 9, 4: 2}
svc := newService(st, taste.Learned{})
sug, tracks, err := svc.SuggestedTracks(context.Background(), 1, "on-rotation", 0)
if err != nil {
t.Fatal(err)
}
if got := ids(tracks); !slices.Equal(got, []int64{3, 2, 4}) {
t.Errorf("on rotation = %v, want the songs played at least twice lately, the most first", got)
}
if sug.Rules.PlaysWithinDays != 30 || sug.Sort != SortMostPlayed {
t.Errorf("on-rotation = %+v", sug)
}
st.since = nil
if _, _, err := svc.SuggestedTracks(context.Background(), 1, "top-year", 0); err != nil {
t.Fatal(err)
}
if len(st.since) != 1 || !st.since[0].Equal(daysAgo(365)) {
t.Errorf("top-year window = %v", st.since)
}
}
func TestAWindowOfDaysIsChecked(t *testing.T) {
for _, n := range []int{-1, MaxDays + 1} {
if _, err := newService(newStore(), taste.Learned{}).Preview(context.Background(), 1, Input{Rules: Rules{PlaysWithinDays: n}}, 0); !errors.Is(err, ErrInvalidInput) {
t.Errorf("plays_within_days %d: %v", n, err)
}
}
if got := (Rules{PlaysWithinDays: 30, MinPlays: 2}).Summary(); got != "played at least 2 times; plays counted over the last 30 days" {
t.Errorf("summary = %q", got)
}
}

View file

@ -21,8 +21,10 @@ type SuggestedPlaylist struct {
// the user can make their own with Create.
var suggested = []SuggestedPlaylist{
{Key: "recently-added", Rules: Rules{AddedWithinDays: 30}, Sort: SortRecentlyAdded, Limit: 100},
{Key: "never-played", Rules: Rules{NeverPlayed: true}, Sort: SortRandom, Limit: DefaultLimit},
{Key: "on-rotation", Rules: Rules{PlaysWithinDays: 30, MinPlays: 2}, Sort: SortMostPlayed, Limit: DefaultLimit},
{Key: "top-year", Rules: Rules{PlaysWithinDays: 365, MinPlays: 2}, Sort: SortMostPlayed, Limit: DefaultLimit},
{Key: "most-played", Rules: Rules{MinPlays: 1}, Sort: SortMostPlayed, Limit: DefaultLimit},
{Key: "never-played", Rules: Rules{NeverPlayed: true}, Sort: SortRandom, Limit: DefaultLimit},
{Key: "forgotten", Rules: Rules{MinPlays: 1, NotPlayedWithinDays: 90}, Sort: SortRandom, Limit: DefaultLimit},
{Key: "high-quality", Rules: Rules{MinBitrateKbps: 900}, Sort: SortRandom, Limit: DefaultLimit},
{Key: "long-tracks", Rules: Rules{MinDurationSec: 360}, Sort: SortRandom, Limit: DefaultLimit},

View file

@ -165,6 +165,32 @@ func (r *SmartRepo) History(ctx context.Context, userID int64, minListen time.Du
return r.mix.History(ctx, userID, minListen)
}
// Plays returns how many listens the user has of each song since a moment (a play counts as a listen when it was
// completed or lasted minListen), for the songs they listened to in that time.
func (r *SmartRepo) Plays(ctx context.Context, userID int64, minListen time.Duration, since time.Time) (map[int64]int, error) {
ms := minListen.Milliseconds()
rows, err := r.db.QueryContext(ctx,
`SELECT track_id, COUNT(*) FROM listening_events
WHERE user_id = ? AND occurred_at >= ? AND (event_type = 'complete' OR duration_played_ms >= ?)
GROUP BY track_id`, userID, since.Unix(), ms)
if err != nil {
return nil, fmt.Errorf("read plays: %w", err)
}
defer rows.Close()
out := map[int64]int{}
for rows.Next() {
var (
id int64
n int
)
if err := rows.Scan(&id, &n); err != nil {
return nil, err
}
out[id] = n
}
return out, rows.Err()
}
// Tracks returns the playable songs among ids, in the order given.
func (r *SmartRepo) Tracks(ctx context.Context, ids []int64) ([]catalog.Track, error) {
return r.mix.Tracks(ctx, ids)

View file

@ -331,3 +331,41 @@ func TestSmartPlaylistsGoWhenTheirOwnerGoes(t *testing.T) {
}
})
}
func TestSmartRepoCountsTheListensOfEachSongSinceAMoment(t *testing.T) {
smartBackends(t, smartSongs, func(t *testing.T, e *smartEnv) {
ctx := context.Background()
at := func(track string, user int64, kind string, played int64, when int64, key string) {
t.Helper()
if _, err := e.db.Exec(`INSERT INTO listening_events (user_id, track_id, event_type, occurred_at, duration_played_ms, idempotency_key)
VALUES (?, ?, ?, ?, ?, ?)`, user, e.tracks[track], kind, when, played, key); err != nil {
t.Fatal(err)
}
}
const day = 86_400
now := int64(1_700_000_000)
at("a", e.alice, "complete", 180_000, now-1*day, "k1") // counts
at("a", e.alice, "complete", 180_000, now-2*day, "k2") // counts
at("a", e.alice, "play", 30_000, now-3*day, "k3") // played long enough: counts
at("a", e.alice, "play", 5_000, now-3*day, "k4") // too short: not a listen
at("a", e.alice, "skip", 2_000, now-1*day, "k5") // a skip
at("a", e.alice, "complete", 180_000, now-60*day, "k6") // before the window
at("b", e.alice, "complete", 180_000, now-5*day, "k7")
at("a", e.bob, "complete", 180_000, now-1*day, "k8") // somebody else's
got, err := e.repo.Plays(ctx, e.alice, 20*time.Second, time.Unix(now-30*day, 0))
if err != nil {
t.Fatal(err)
}
if got[e.tracks["a"]] != 3 || got[e.tracks["b"]] != 1 || len(got) != 2 {
t.Errorf("last 30 days = %v, want a: 3, b: 1", got)
}
all, _ := e.repo.Plays(ctx, e.alice, 20*time.Second, time.Unix(0, 0))
if all[e.tracks["a"]] != 4 {
t.Errorf("all time = %v, want a: 4", all)
}
if none, _ := e.repo.Plays(ctx, e.alice, 20*time.Second, time.Unix(now+day, 0)); len(none) != 0 {
t.Errorf("a window in the future = %v", none)
}
})
}