feat(smart): smart playlists made for everybody, without making them

- A fixed set that is there with no setup: recently added, never played, most played, not heard for a while, high quality files and long tracks. The rules are the same for everyone and are worked out on each one's own library and history, like the mixes; nothing is stored, so they follow the library.
- GET /smart-playlists/suggested, GET /smart-playlists/suggested/{key}/tracks and POST /smart-playlists/suggested/{key}/playlist.
- The Smart playlists page begins with them, with names and descriptions in the language of the page. A suggested one can be played, shuffled again, kept as a playlist, or made one's own: a copy of its rules opens in the editor.
This commit is contained in:
tgiachi 2026-11-13 10:06:58 +01:00
commit 17f70d582d
7 changed files with 920 additions and 28 deletions

View file

@ -1034,6 +1034,17 @@ func (c *contract) smartPlaylists(t *testing.T, token string) {
t.Helper()
rules := map[string]any{"genres": []string{"synthwave"}, "formats": []string{"flac"}, "never_played": true}
c.expect(c.call("GET", "/smart-playlists", "", nil), 401, "smart playlists without a token", "unauthorized")
sug := c.expect(c.call("GET", "/smart-playlists/suggested", token, nil), 200, "the suggested smart playlists")
if len(sug["items"].([]any)) < 5 {
t.Fatalf("suggested = %v", sug)
}
c.expect(c.call("GET", "/smart-playlists/suggested/never-played/tracks", token, nil), 200, "the songs of a suggested one")
c.expect(c.call("GET", "/smart-playlists/suggested/never-played/tracks?variant=-1", token, nil), 400, "a negative variant", "invalid_input")
c.expect(c.call("GET", "/smart-playlists/suggested/nonsense/tracks", token, nil), 404, "an unknown suggested one", "suggested_not_found")
c.expect(c.call("POST", "/smart-playlists/suggested/never-played/playlist", token, map[string]any{"name": "Fresh ears", "variant": 1}), 201, "keep a suggested one")
c.expect(c.call("POST", "/smart-playlists/suggested/never-played/playlist", token, nil), 201, "keep a suggested one with no body")
c.expect(c.call("POST", "/smart-playlists/suggested/high-quality/playlist", token, nil), 422, "keep a suggested one with no songs", "smart_playlist_empty")
c.expect(c.call("POST", "/smart-playlists/suggested/nonsense/playlist", token, nil), 404, "keep an unknown suggested one", "suggested_not_found")
genres := c.expect(c.call("GET", "/genres", token, nil), 200, "the genres of the library")
if len(genres["items"].([]any)) == 0 {
t.Fatalf("genres = %v", genres)

View file

@ -248,3 +248,74 @@ func (h *smartHandlers) genres(c *gin.Context) {
}
c.JSON(http.StatusOK, gin.H{"items": items})
}
type suggestedJSON struct {
Key string `json:"key"`
Rules smart.Rules `json:"rules"`
Sort string `json:"sort"`
Limit int `json:"limit"`
}
func toSuggestedJSON(s smart.SuggestedPlaylist) suggestedJSON {
return suggestedJSON{Key: s.Key, Rules: s.Rules, Sort: string(s.Sort), Limit: s.Limit}
}
// suggestedList gives the smart playlists that Sonda makes for everybody: a fixed set, with no songs in it.
func (h *smartHandlers) suggestedList(c *gin.Context) {
list := smart.Suggested()
out := make([]suggestedJSON, len(list))
for i, s := range list {
out[i] = toSuggestedJSON(s)
}
c.JSON(http.StatusOK, gin.H{"items": out})
}
func writeSuggestedError(c *gin.Context, err error) {
if errors.Is(err, smart.ErrNotFound) {
writeError(c, http.StatusNotFound, "suggested_not_found", "no such suggested smart playlist")
return
}
writeSmartError(c, err)
}
// suggestedTracks works the songs of a suggested smart playlist out for the signed-in user.
func (h *smartHandlers) suggestedTracks(c *gin.Context) {
variant, ok := variantOf(c)
if !ok {
return
}
_, tracks, err := h.svc.SuggestedTracks(c.Request.Context(), currentUserID(c), c.Param("key"), variant)
if err != nil {
writeSuggestedError(c, err)
return
}
c.JSON(http.StatusOK, smartTracksJSON{Variant: variant, Tracks: toTracksJSON(tracks)})
}
// suggestedSave makes a normal playlist of the songs a suggested smart playlist gives now.
func (h *smartHandlers) suggestedSave(c *gin.Context) {
var req saveSmartRequest
if c.Request.ContentLength != 0 && !bindJSON(c, &req) {
return
}
variant := 0
if req.Variant != nil {
variant = *req.Variant
}
user := currentUserID(c)
key := c.Param("key")
_, tracks, err := h.svc.SuggestedTracks(c.Request.Context(), user, key, variant)
if err != nil {
writeSuggestedError(c, err)
return
}
if len(tracks) == 0 {
writeError(c, http.StatusUnprocessableEntity, "smart_playlist_empty", "the rules give no songs to save")
return
}
name := strings.TrimSpace(req.Name)
if name == "" {
name = key // a client says the name in its language; this is only for one that does not
}
keepAsPlaylist(c, h.playlists, user, name, tracks)
}

View file

@ -117,6 +117,7 @@ type smartService interface {
Tracks(ctx context.Context, userID, id int64, variant int) (smart.SmartPlaylist, []catalog.Track, error)
Preview(ctx context.Context, userID int64, in smart.Input, variant int) ([]catalog.Track, error)
Genres(ctx context.Context) ([]smart.GenreCount, error)
SuggestedTracks(ctx context.Context, userID int64, key string, variant int) (smart.SuggestedPlaylist, []catalog.Track, error)
}
type feedbackService interface {
@ -282,6 +283,9 @@ func NewRouter(d Deps) *gin.Engine {
protected.GET("/smart-playlists", sm.list)
protected.POST("/smart-playlists", sm.create)
protected.POST("/smart-playlists/preview", sm.preview)
protected.GET("/smart-playlists/suggested", sm.suggestedList)
protected.GET("/smart-playlists/suggested/:key/tracks", sm.suggestedTracks)
protected.POST("/smart-playlists/suggested/:key/playlist", sm.suggestedSave)
protected.GET("/smart-playlists/:id", sm.get)
protected.PATCH("/smart-playlists/:id", sm.update)
protected.DELETE("/smart-playlists/:id", sm.remove)

View file

@ -32,7 +32,7 @@ func smartTracks(t *testing.T, m *mixAPI, id int, query string) []float64 {
func TestSmartPlaylistRoutesNeedASignedInUser(t *testing.T) {
m := newMixAPI(t)
for _, rt := range []struct{ method, path string }{
{"GET", "/api/v1/genres"}, {"GET", sp}, {"POST", sp}, {"POST", sp + "/preview"}, {"GET", sp + "/1"}, {"PATCH", sp + "/1"}, {"DELETE", sp + "/1"},
{"GET", "/api/v1/genres"}, {"GET", sp + "/suggested"}, {"GET", sp + "/suggested/never-played/tracks"}, {"POST", sp + "/suggested/never-played/playlist"}, {"GET", sp}, {"POST", sp}, {"POST", sp + "/preview"}, {"GET", sp + "/1"}, {"PATCH", sp + "/1"}, {"DELETE", sp + "/1"},
{"GET", sp + "/1/tracks"}, {"POST", sp + "/1/playlist"},
} {
if r := do(t, m.h, rt.method, rt.path, "", nil); r.Code != http.StatusUnauthorized {
@ -279,3 +279,72 @@ func TestTheGenresOfTheLibraryAreListedBiggestFirst(t *testing.T) {
t.Errorf("genres = %v", items)
}
}
func TestSuggestedSmartPlaylistsAreThereForEveryoneWithTheirRules(t *testing.T) {
m := newMixAPI(t)
r := do(t, m.h, "GET", sp+"/suggested", m.alice, nil)
if r.Code != http.StatusOK {
t.Fatalf("suggested: %d %v", r.Code, r.Body)
}
byKey := map[string]map[string]any{}
for _, x := range r.Body["items"].([]any) {
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"} {
if byKey[key] == nil {
t.Errorf("%s is missing from %v", key, byKey)
}
}
never := byKey["never-played"]
if never["sort"] != "random" || never["limit"] != float64(50) || never["rules"].(map[string]any)["never_played"] != true {
t.Errorf("never-played = %v", never)
}
// The list of mine does not have them: they are not stored.
if list := do(t, m.h, "GET", sp, m.alice, nil); list.Body["total"] != float64(0) {
t.Errorf("my smart playlists = %v", list.Body)
}
}
func TestTheSongsOfASuggestedSmartPlaylistAreWorkedOutForTheListener(t *testing.T) {
m := newMixAPI(t)
r := do(t, m.h, "GET", sp+"/suggested/never-played/tracks", m.alice, nil)
if r.Code != http.StatusOK || r.Body["variant"] != float64(0) || len(trackIDs(t, r)) != 50 {
t.Fatalf("never-played: %d, %d songs", r.Code, len(trackIDs(t, r)))
}
first := trackIDs(t, r)
if again := trackIDs(t, do(t, m.h, "GET", sp+"/suggested/never-played/tracks", m.alice, nil)); !slices.Equal(first, again) {
t.Error("the same day gave other songs")
}
if v := trackIDs(t, do(t, m.h, "GET", sp+"/suggested/never-played/tracks?variant=1", m.alice, nil)); slices.Equal(first, v) {
t.Error("another variant gave the same songs")
}
// Nothing was played, so there is no most played, and the library has no 900 kbps file.
if got := trackIDs(t, do(t, m.h, "GET", sp+"/suggested/most-played/tracks", m.alice, nil)); len(got) != 0 {
t.Errorf("most-played with no history = %v", got)
}
if r := do(t, m.h, "GET", sp+"/suggested/nonsense/tracks", m.alice, nil); r.Code != http.StatusNotFound || errCode(r) != "suggested_not_found" {
t.Errorf("unknown key: %d %v", r.Code, r.Body)
}
if r := do(t, m.h, "GET", sp+"/suggested/never-played/tracks?variant=-1", m.alice, nil); r.Code != http.StatusBadRequest {
t.Errorf("negative variant: %d", r.Code)
}
}
func TestASuggestedSmartPlaylistIsKeptAsAPlaylist(t *testing.T) {
m := newMixAPI(t)
shown := trackIDs(t, do(t, m.h, "GET", sp+"/suggested/never-played/tracks?variant=2", m.alice, nil))
r := do(t, m.h, "POST", sp+"/suggested/never-played/playlist", m.alice, map[string]any{"name": "Fresh ears", "variant": 2})
if r.Code != http.StatusCreated || r.Body["name"] != "Fresh ears" || r.Body["track_count"] != float64(len(shown)) {
t.Fatalf("save: %d %v", r.Code, r.Body)
}
if r := do(t, m.h, "POST", sp+"/suggested/never-played/playlist", m.alice, nil); r.Code != http.StatusCreated || r.Body["name"] != "never-played" {
t.Errorf("save with no body: %d %v", r.Code, r.Body)
}
if r := do(t, m.h, "POST", sp+"/suggested/most-played/playlist", m.alice, nil); r.Code != http.StatusUnprocessableEntity || errCode(r) != "smart_playlist_empty" {
t.Errorf("save of an empty one: %d %v", r.Code, r.Body)
}
if r := do(t, m.h, "POST", sp+"/suggested/nonsense/playlist", m.alice, nil); r.Code != http.StatusNotFound || errCode(r) != "suggested_not_found" {
t.Errorf("unknown key: %d %v", r.Code, r.Body)
}
}

View file

@ -1378,6 +1378,84 @@ paths:
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
/smart-playlists/suggested:
get:
tags: [Smart playlists]
operationId: listSuggestedSmartPlaylists
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).
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: []}]
responses:
'200':
description: The suggested smart playlists.
content:
application/json:
schema: {$ref: '#/components/schemas/SuggestedSmartPlaylistList'}
'401': {$ref: '#/components/responses/Unauthorized'}
/smart-playlists/suggested/{key}/tracks:
parameters:
- {$ref: '#/components/parameters/SuggestedKey'}
get:
tags: [Smart playlists]
operationId: getSuggestedSmartPlaylistTracks
summary: The songs of a suggested smart playlist, now
description: |
Works the rules out for you, as `GET /smart-playlists/{id}/tracks` does for yours. With the random order
the songs stay the same all day, and another `variant` gives other ones.
security: [{bearerAuth: []}]
parameters:
- name: variant
in: query
description: Other songs for the random order, from 0 (the songs of the day) up.
schema: {type: integer, minimum: 0, maximum: 1000000, default: 0}
responses:
'200':
description: The songs.
content:
application/json:
schema: {$ref: '#/components/schemas/SmartTracks'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404': {$ref: '#/components/responses/SuggestedNotFound'}
/smart-playlists/suggested/{key}/playlist:
parameters:
- {$ref: '#/components/parameters/SuggestedKey'}
post:
tags: [Smart playlists]
operationId: saveSuggestedSmartPlaylist
summary: Keep a suggested smart playlist as a playlist
description: |
Makes a playlist of your own with the songs that `variant` gives now, in the same order. It is a copy,
and is yours to edit. The body is optional; without a name the playlist is called by the `key`.
security: [{bearerAuth: []}]
requestBody:
required: false
content:
application/json:
schema: {$ref: '#/components/schemas/SaveSmartPlaylist'}
responses:
'201':
description: The playlist.
content:
application/json:
schema: {$ref: '#/components/schemas/Playlist'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404': {$ref: '#/components/responses/SuggestedNotFound'}
'409': {$ref: '#/components/responses/PlaylistLimit'}
'422':
description: The rules give no songs to save (`smart_playlist_empty`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/smart-playlists/{id}:
parameters:
- {$ref: '#/components/parameters/Id'}
@ -2705,6 +2783,12 @@ components:
name: offset
in: query
schema: {type: integer, minimum: 0, default: 0}
SuggestedKey:
name: key
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]}
MixId:
name: id
in: path
@ -2761,6 +2845,11 @@ components:
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
SuggestedNotFound:
description: No such suggested smart playlist (`suggested_not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
SmartPlaylistNotFound:
description: No such smart playlist, or it is somebody else's (`smart_playlist_not_found`).
content:
@ -3455,6 +3544,25 @@ components:
min_duration_sec: {type: integer, minimum: 0, maximum: 86400}
max_duration_sec: {type: integer, minimum: 0, maximum: 86400}
SuggestedSmartPlaylist:
type: object
additionalProperties: false
required: [key, rules, sort, limit]
properties:
key: {type: string, enum: [recently-added, never-played, most-played, forgotten, high-quality, long-tracks]}
rules: {$ref: '#/components/schemas/SmartRules'}
sort: {$ref: '#/components/schemas/SmartSort'}
limit: {type: integer, minimum: 1, maximum: 500}
SuggestedSmartPlaylistList:
type: object
additionalProperties: false
required: [items]
properties:
items:
type: array
items: {$ref: '#/components/schemas/SuggestedSmartPlaylist'}
SmartSort:
type: string
enum: [random, most_played, least_played, recently_added, title]

View file

@ -517,3 +517,81 @@ func TestGenresMergeSpellingsLeaveOutWhatIsNotAGenreAndCountTheBiggestFirst(t *t
t.Errorf("got %v, want %v", got, want)
}
}
// ---- the suggested ones ----
func TestSuggestedAreAFixedSetOfValidRules(t *testing.T) {
list := Suggested()
if len(list) < 5 {
t.Fatalf("%d suggested smart playlists", len(list))
}
seen := map[string]bool{}
for _, s := range list {
if s.Key == "" || seen[s.Key] {
t.Errorf("key %q is empty or repeated", s.Key)
}
seen[s.Key] = true
in, err := clean(Input{Rules: s.Rules, Sort: s.Sort, Limit: s.Limit})
if err != nil {
t.Errorf("%s: %v", s.Key, err)
}
if in.Sort != s.Sort || in.Limit != s.Limit || s.Limit < 1 {
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"} {
if !seen[want] {
t.Errorf("%s is missing", want)
}
}
// A caller cannot change the set by changing what it was given.
list[0].Rules.Genres = []string{"x"}
if got := Suggested()[0].Rules.Genres; len(got) != 0 {
t.Errorf("the set was changed: %v", got)
}
}
func TestSuggestedSongsAreWorkedOutFromTheirRulesForTheListener(t *testing.T) {
st := newStore()
st.cands = songs(6)
st.history = map[int64]History{1: {Plays: 4, LastPlayed: daysAgo(2)}, 2: {Plays: 1, LastPlayed: daysAgo(200)}}
svc := newService(st, taste.Learned{})
got, tracks, err := svc.SuggestedTracks(context.Background(), 1, "never-played", 0)
if err != nil || got.Key != "never-played" {
t.Fatalf("%+v, %v", got, err)
}
if ids := ids(tracks); slices.Contains(ids, 1) || slices.Contains(ids, 2) || len(ids) != 4 {
t.Errorf("never played = %v: songs 1 and 2 were played", ids)
}
_, tracks, _ = svc.SuggestedTracks(context.Background(), 1, "forgotten", 0)
if got := ids(tracks); !slices.Equal(got, []int64{2}) {
t.Errorf("forgotten = %v, want the song played once 200 days ago", got)
}
_, tracks, _ = svc.SuggestedTracks(context.Background(), 1, "most-played", 0)
if got := ids(tracks); !slices.Equal(got, []int64{1, 2}) {
t.Errorf("most played = %v, want the played ones, the most first", got)
}
_, tracks, _ = svc.SuggestedTracks(context.Background(), 1, "recently-added", 0)
if got := ids(tracks); len(got) == 0 || got[0] != 1 {
t.Errorf("recently added = %v, want the newest first", got)
}
if _, _, err := svc.SuggestedTracks(context.Background(), 1, "nonsense", 0); !errors.Is(err, ErrNotFound) {
t.Errorf("unknown key: %v", err)
}
if _, _, err := svc.SuggestedTracks(context.Background(), 1, "never-played", MaxVariant+1); !errors.Is(err, ErrInvalidInput) {
t.Errorf("variant: %v", err)
}
}
func TestEachSuggestedRandomOrderIsItsOwn(t *testing.T) {
st := newStore()
st.cands = songs(60)
svc := newService(st, taste.Learned{})
_, a, _ := svc.SuggestedTracks(context.Background(), 1, "never-played", 0)
_, b, _ := svc.SuggestedTracks(context.Background(), 1, "long-tracks", 0)
st.cands = songs(60)
if slices.Equal(ids(a), ids(b)) {
t.Error("two suggested playlists with the same candidates gave the same order")
}
}

View file

@ -0,0 +1,55 @@
package smart
import (
"context"
"slices"
"codeberg.org/squidd/sonda/internal/catalog"
)
// SuggestedPlaylist is a smart playlist that Sonda makes for everybody, with no need to ask: the rules are the
// same for every user and are worked out on each one's own library and history, when it is opened. Nothing is
// stored for it, so it follows the library, and a client says its name in its own language from the key.
type SuggestedPlaylist struct {
Key string // "recently-added", "never-played"...
Rules Rules
Sort Sort
Limit int
}
// suggested is the set. Its rules are valid ones (a test checks it), and a copy of one is a smart playlist
// 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: "most-played", Rules: Rules{MinPlays: 1}, Sort: SortMostPlayed, 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},
}
// Suggested returns the suggested smart playlists. The list is a copy: changing it changes nothing.
func Suggested() []SuggestedPlaylist {
out := make([]SuggestedPlaylist, len(suggested))
for i, s := range suggested {
s.Rules.Genres = slices.Clone(s.Rules.Genres)
out[i] = s
}
return out
}
// SuggestedTracks works the songs of a suggested smart playlist out for the user. variant 0 is the songs of
// the day; with a random order another number gives other ones. An unknown key is ErrNotFound.
func (s *Service) SuggestedTracks(ctx context.Context, userID int64, key string, variant int) (SuggestedPlaylist, []catalog.Track, error) {
if err := checkVariant(variant); err != nil {
return SuggestedPlaylist{}, nil, err
}
i := slices.IndexFunc(suggested, func(x SuggestedPlaylist) bool { return x.Key == key })
if i < 0 {
return SuggestedPlaylist{}, nil, ErrNotFound
}
sg := suggested[i]
// The seed has an id of its own, below 0 so that it is never one of a kept playlist.
tracks, err := s.run(ctx, userID, -int64(i+1), sg.Rules, sg.Sort, sg.Limit, variant)
return Suggested()[i], tracks, err
}