sonda/docs/features/artwork.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

4.9 KiB

Covers, photos and descriptions

Features · Sonda

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}/cover serves the cover of an album from your own files: the picture embedded in them, or else a cover, folder, front, album or albumart image in the album's folder. It is built the first time it is asked for (a few at a time), scaled (?size=small is 300 pixels, large 1000) 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 the coverartarchive provider, 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 the musicbrainz provider is on too (see the list of what leaves your server). For an album split in CD1/Disc 2 folders, the picture in the folder above is used. Nothing is sent anywhere unless you turned on the coverartarchive provider (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 with GET /library/covers, stop it with DELETE /library/covers; ?refresh=true searches 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}/image serves a free picture of an artist from Wikimedia Commons, and GET /artists/{id}/image/credit says 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=small is 300 pixels, large 1000) in the data folder. With the commons provider and the musicbrainz one 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 with GET /library/artist-images, stop it with DELETE /library/artist-images; ?refresh=true searches 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}/description shows 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 the wikipedia provider and the musicbrainz one 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 with GET /library/descriptions, stop it with DELETE /library/descriptions; ?refresh=true reads 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}/tags shows 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}/similar lists 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.