sonda/docs/features/playlists.md
tgiachi 11077f40e1
All checks were successful
release / release (push) Successful in 36s
release / base (push) Has been skipped
release / image (amd64) (push) Has been skipped
release / image (arm64) (push) Has been skipped
release / manifest (push) Has been skipped
docs: split the README into pages under docs/
The README had grown to about 500 lines. It now holds the intro, a quick
start and an index, and the rest lives in docs/.

- docs: add docs/README.md as the index of all pages
- docs: move install, configuration, demo, providers, OpenSubsonic, API,
  security and backups, web app, Android app and development/releases
  to their own pages, text unchanged
- docs: split the feature list into five pages under docs/features/
- docs: rewrite internal anchors as links between the new pages
- chore: add docs to .dockerignore, next to README.md
2026-11-17 14:50:52 +01:00

6.7 KiB

Playlists, mixes and radio

Features · Sonda

Lists of songs you make, and lists Sonda makes for you.

  • Playlists. POST /playlists makes a playlist (a name and an optional description) and GET /playlists lists yours, the one changed last first. POST /playlists/{id}/tracks adds 1 to 500 songs at the end or at a position, GET /playlists/{id}/tracks lists them in order, PATCH /playlists/{id}/tracks/{item} moves one and DELETE takes one out; PATCH /playlists/{id} renames and DELETE /playlists/{id} deletes (the songs stay in the library). A song can be in a playlist more than once, which is why each place has its own item id. A playlist is yours alone: someone else's answers playlist_not_found, as one that does not exist. A song whose files were deleted or moved away stays in the playlist and shows available: false; it plays again when the files come back and a scan finds them. Each playlist says which albums stand for it (album_ids: up to 4 albums that have a cover, in the order they first appear in it, each once), for a picture made of their covers; nothing is fetched for it. A user can have 1000 playlists of up to 10000 songs. Nothing is shared and nothing leaves your server.

  • Smart playlists. A smart playlist is a set of rules instead of a list of songs, worked out again every time you open it, so new songs and your listening change it by themselves. POST /smart-playlists keeps a name, the rules, an order (random, most_played, least_played, recently_added or title) and a limit (50 by default, 500 at most); GET /smart-playlists/{id}/tracks gives the songs now. Every rule that is set must hold: genres, artists and albums (is, or is not), file formats and a minimum bitrate (about the same file), added in the last N days (by the date of the file), never played, played or not played in the last N days, played at least N times (optionally counting only the plays of the last N days, which is what makes the songs in rotation lately and the top of the year), skipped or not skipped lately, only artists you like or without the ones you avoid, the length of the song, and the year it came out (min_year and max_year, both included: 1980 to 1989 is the eighties). The year comes from the tags of the file (the original date first, then the date); a song with no year never matches a year rule, and the files indexed before this existed have none until a full rescan (POST /library/scan?full=true) reads their tags again. POST /smart-playlists/preview tries rules without keeping them, and POST /smart-playlists/{id}/playlist keeps what you see as a normal playlist (a copy). Only the rules are stored; the songs come from the files and from your own history, nothing is sent to a provider, and a smart playlist is yours alone, and GET /genres lists the genres to choose from. A random order stays the same for a day, and ?variant=2 gives another. GET /smart-playlists/{id}/covers and GET /smart-playlists/suggested/{key}/covers say which albums stand for one (up to 4 that have a cover, in the order of the songs it gives now), for its picture; they are apart from the songs so that the list of smart playlists shows at once and each card fills in its cover when it arrives. Some are there without anybody making them: GET /smart-playlists/suggested lists a fixed set (recently-added, on-rotation, top-year, most-played, never-played, forgotten, high-quality, long-tracks), the same rules for everyone and worked out on your own library and history, nothing stored; GET /smart-playlists/suggested/{key}/tracks gives their songs and POST /smart-playlists/suggested/{key}/playlist keeps them as a playlist, and on-rotation is the songs you played most in the last 30 days and top-year the same over a year, so they change as you listen; a copy of their rules becomes a smart playlist of your own with POST /smart-playlists. A user can have 200.

  • Mixes. GET /mixes lists playlists that Sonda makes for you, like the mixes of a streaming service, from what you listen to and from the genres of your music: one mix for each genre of your library that has at least 30 songs by 4 artists (the genres you play most first), and, once you have some listening history, Your favourites (the artists you like: the ones you play, and the ones you marked with a heart) and Rediscover (artists you like and have not played for a month); New to you is the songs you never played. GET /mixes/{id} gives a mix of up to 50 songs, at most 3 by one artist and never two of the same artist in a row. They are picked by weighted chance: the artists you play weigh more and songs you skipped lately or artists you avoid are left out. A mix stays the same for a day, and ?variant=2 gives another; POST /mixes/{id}/playlist keeps the one you are looking at as a playlist of your own. A mix is worked out when you ask for it, from your own history and the genre tags of your files: nothing is stored and nothing is sent to a provider. The id of a genre mix has the genre in it (genre:hard rock), so it is percent-encoded in the path. Each mix says which albums stand for it (album_ids: up to 4 albums that have a cover, by different artists, with most of the songs the mix draws from), for a picture made of their covers; the covers are the ones the library already has, so a mix has a picture once the covers of its albums were looked up (browsing the albums, or the covers job), and none is fetched for it.

  • Radio. Stations that Sonda makes by itself from your music, with nothing to set up, and without end: Everything, one for each decade that has at least 30 songs by 4 artists (from the year in the tags), and the mixes you have (one for each genre, Your favourites, Rediscover, New to you), plus the radio of an artist from its page. GET /radio lists the stations and GET /radio/{id} gives up to 50 songs of one, other songs every time it is asked, picked like a mix (your taste and your hearts count, nothing skipped lately, at most 3 by one artist); artist:<id> is the station of an artist (their songs weigh four times as much, with the songs of the two genres most of theirs have). The web app has a Radio page and a Start radio button on every artist, and its player asks for more songs by itself before the queue runs out. Apps that speak OpenSubsonic see each station as a playlist called Radio · Rock, with other songs every time it is opened (an app has no way to play a radio that never ends), but only when you turn on radio_in_apps (PATCH /me/settings; in Settings, Show the radio stations in apps): there are about two dozen of them, so it is off until you ask. Nothing is stored and nothing leaves the server.