[API Request] Endpoint to retrieve additional images and booklet for an album

[dweymouth]

Type of change

API Clarification

Proposal description

Many users maintain additional images in their libraries other than the album cover, such as an alternate cover(s), CD image, tray (back) image, booket (which may be a PDF or a series of images), etc. It would be nice for Subsonic clients to support showing these additional assets. Some discussion is needed on exactly what the API should look like, but I think we should support the following asset types:

• Alternate cover(s)
• Back (aka tray)
• Disc
• Booklet (either a PDF or a series of images)
• Matrix (scan of manufacturing codes printed around the CD spindle hole)

Backward compatibility impact

No response

Backward compatibility

• No backward compatibility impact.

API details

Since many/most of these may not be present for a given album, the API should return a response object indicating which of these alternate images are present. e.g.

getAlbumImages (or getAlbumAssets)

{
    "alternate covers": [],
    "back": "some-ID-or-URL",
    "matrix": "",
    "disc": "",
    "booklet": {
        "type": "PDF", // or "Images"
        "pdfURL": "http[s]://my-server/some/path/to/booklet.pdf",
        "images": [ "some-ID-or-URL", ...], // mutually exclusive with pdfURL
    }
}

This also allows a server to not support this feature by simply returning no image ID or url for all of the image types (or an entirely empty response). Up for discussion is whether the alternate images should be specified with download URLs, or IDs that could be passed to the existing getCoverArt API (to allow for image resizing).

Security impacts

No response

Potential issues

No response

Alternative solutions

No response

[spl0k]

Some (myself included) will argue than the tray isn't the back. The back is... well... the back of the package while the tray is what you might see behind the medium once you opened the package. This most often applies to CD releases.
While we're talking terminology, I would advise against using "disc" here but rather use "medium". Music isn't distributed only on discs and other medium types can also have their own art besides the usual cover art.
Maybe we can draw inspiration from MusicBrainz cover art types, even though their types don't cover every case. For example gatefold covers' inside can't easily be represented with those types.

Regarding the endpoint name (and the object to which it applies) I'm not sure I would restrict this to albums only. Some digital releases have the usual cover art, sometimes with a booklet (case covered here), but on this album each individual track can have its own art. Though this could handled by the already existing field on tracks.
Example here: https://theflashbulb.bandcamp.com/album/opus-at-the-end-of-everything (click on each individual track)

I would rather return ids instead of URLs, to be consistent with the way the API references the resources it can serve.

[Tolriq]

I think this should be a little more generic in the approach to cover most and future use cases.

IMO I would see that returned as an asset field from the getAlbumInfo request no need for a new one.

I'd see it as an array of assets with asset definition being generic enough so something like :

{
....
"assets" : [
     {
          "name": "covers",  // Well knowns names or not
           "type": "image",  // TBD, image, files, ...
           "ressources": [ 
              { "type" : "covertArt", "value": "a cover art id" },
              { "type" : "url", "value": "an url" },
            ]
     }
  ]
}

Then use some well know names for the common case, while still allowing servers to server more data if necessary.