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
6.7 KiB
Playlists, mixes and radio
Lists of songs you make, and lists Sonda makes for you.
-
Playlists.
POST /playlistsmakes a playlist (a name and an optional description) andGET /playlistslists yours, the one changed last first.POST /playlists/{id}/tracksadds 1 to 500 songs at the end or at aposition,GET /playlists/{id}/trackslists them in order,PATCH /playlists/{id}/tracks/{item}moves one andDELETEtakes one out;PATCH /playlists/{id}renames andDELETE /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 answersplaylist_not_found, as one that does not exist. A song whose files were deleted or moved away stays in the playlist and showsavailable: 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-playlistskeeps a name, the rules, an order (random,most_played,least_played,recently_addedortitle) and a limit (50 by default, 500 at most);GET /smart-playlists/{id}/tracksgives 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_yearandmax_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/previewtries rules without keeping them, andPOST /smart-playlists/{id}/playlistkeeps 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, andGET /genreslists the genres to choose from. A random order stays the same for a day, and?variant=2gives another.GET /smart-playlists/{id}/coversandGET /smart-playlists/suggested/{key}/coverssay 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/suggestedlists 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}/tracksgives their songs andPOST /smart-playlists/suggested/{key}/playlistkeeps them as a playlist, andon-rotationis the songs you played most in the last 30 days andtop-yearthe same over a year, so they change as you listen; a copy of their rules becomes a smart playlist of your own withPOST /smart-playlists. A user can have 200. -
Mixes.
GET /mixeslists 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=2gives another;POST /mixes/{id}/playlistkeeps 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 /radiolists the stations andGET /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 onradio_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.