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
4.9 KiB
Covers, photos and descriptions
Pictures and text about your music. Everything here is built from your own files first; providers only add to it, and only when an admin turns them on.
-
Album covers.
GET /albums/{id}/coverserves the cover of an album from your own files: the picture embedded in them, or else acover,folder,front,albumoralbumartimage in the album's folder. It is built the first time it is asked for (a few at a time), scaled (?size=smallis 300 pixels,large1000) and kept in the data folder (storage.data_dir, you can delete it: covers are built again). A picture you replace in a folder is noticed within a week, or at once after a full rescan. When your files have no picture at all and an admin turned on thecoverartarchiveprovider, the cover is asked from the Cover Art Archive by the MusicBrainz release group id that the tags of the album's files carry (MUSICBRAINZ_RELEASEGROUPID; run a full rescan to read it for music you already indexed); your own files always come first, and only that id leaves the server. An album whose files have no id is looked up in MusicBrainz by its artist and title when themusicbrainzprovider is on too (see the list of what leaves your server). For an album split inCD1/Disc 2folders, the picture in the folder above is used. Nothing is sent anywhere unless you turned on thecoverartarchiveprovider (see External providers). It also takes?access_token=, so an<img>element can use it. To build the covers of the whole library in one go instead of one album at a time, an admin starts a background job like a scan:POST /library/covers(follow it withGET /library/covers, stop it withDELETE /library/covers;?refresh=truesearches every album again; it never replaces a cover by "no cover" because a disk was not mounted, and keeps the covers that came from the archive if you switched it off). -
Artist photos.
GET /artists/{id}/imageserves a free picture of an artist from Wikimedia Commons, andGET /artists/{id}/image/creditsays whose it is and under which licence, which you must show next to it. Only free licences are kept (public domain, CC0, CC BY, CC BY-SA): non-commercial, no-derivatives, fair-use and unknown ones are refused, because Sonda stores a copy (?size=smallis 300 pixels,large1000) in the data folder. With thecommonsprovider and themusicbrainzone turned on, Sonda follows ids and never a name: the artist's MusicBrainz id, the Wikidata item MusicBrainz links to it, the picture Wikidata names for it, and Commons for its licence. Many artists will have none. Kept for 30 days (a week when there is none) and removed, files included, with the provider's data. To look for the pictures of the whole library in one go, an admin starts a background job like a scan:POST /library/artist-images(follow it withGET /library/artist-images, stop it withDELETE /library/artist-images;?refresh=truesearches every artist again). It only goes through artists that have a MusicBrainz id, never replaces a picture by a failure, and ends at once, saying so, when a provider it needs is off. See External providers. -
Artist descriptions.
GET /artists/{id}/descriptionshows what Wikipedia says about an artist: a short text, with the page it comes from, a link to it and the licence (CC BY-SA 4.0), which you must show next to it. With thewikipediaprovider and themusicbrainzone turned on (the link to Wikidata comes from MusicBrainz), Sonda follows ids and never a name: the artist's MusicBrainz id, then the Wikidata item that MusicBrainz links to it, then the Wikipedia page that Wikidata names in the first of your languages ([wikipedia] languages, the code of that Wikipedia, for example["it", "en"]) that has one. An artist without a MusicBrainz id has no description. It is kept for 30 days and removed with the provider's data. To read the descriptions of the whole library in one go, an admin starts a background job like a scan:POST /library/descriptions(follow it withGET /library/descriptions, stop it withDELETE /library/descriptions;?refresh=truereads every artist again). It only goes through artists that have a MusicBrainz id, never replaces a description by a failure, and ends at once, saying so, when a provider it needs is off. See External providers. -
Tags.
GET /artists/{id}/tagsshows what Last.fm and MusicBrainz say kind of music an artist plays, each with its own weights, and the genres of the artist's own files, read offline. See External providers. -
Similar artists. With Last.fm turned on,
GET /artists/{id}/similarlists artists similar to an artist, and says which of them you already have. See External providers. Without it, Sonda makes no outbound network requests at all.