Reference / @open-music-sdk/util-artwork / artworkUrl

Function: artworkUrl()

function artworkUrl(
   artwork, 
   width, 
   options?
): string;

Defined in: artwork.ts:315

The URL of an artwork image width CSS pixels wide: the template with {w} and {h} filled in.

The image keeps the artwork's own shape unless height says otherwise, and is never asked for larger than the artwork comes. The URL is the one the API gave, spelled as a browser would read it, with numbers put in.

How the size is chosen:

• A box that asks for more than the artwork has is shrunk in its own shape, as near as whole pixels allow. No side is asked for past 10,000 pixels, where Apple's image server stops.
• With a height, what "more" means depends on the crop. A crop that fills the box needs the artwork to cover it both ways. bb stands the whole image inside the box, so the box is shrunk only once the image inside it would be larger than the artwork: a 1500 pixel cover in a 1200 by 300 slot is offered boxes up to 6000x1500. cc makes a square of the box's longer side, so that square is asked for, no longer than the artwork's shorter side.
• Sizes are rounded, and never below one pixel a side, so a box shrunk very far ends squarer than it began. A height that follows from the width is rounded up, so the image comes back the full width asked for.

How the URL is spelled: white space is dropped from its ends, tabs and line breaks from anywhere, and a space inside is written %20, as a browser reads a src. A comma at either end, which a srcset would take for a separator, is kept by writing ./ before it or an empty # after it, or %2C where it is in the fragment already. None of this changes what is requested, so all three functions give the same URL, and a check you make on this one holds for the srcset too.

Where it points is not checked unless hosts says where it may: artwork that did not come straight from Apple's API can hold any URL, which an <img> will request, a link will run if it is javascript:, and a server-side fetch will follow into your own network.

Parameters

artwork

tArtworkSource

The artwork as the API gave it: the URL template and, where it says, how large the image comes.

width

number

How wide the image is shown, in CSS pixels.

options?

tArtworkOptions = {}

The height, the format, the crop, and where the URL may point.

Returns

string

The URL of the image, ready for src.

Throws

TypeError if artwork is not an object with a url, options is not an object, width or height is not a number above 0 and at most 2^53 - 1 (so Infinity is refused), format or crop is not one the image server takes, hosts is not a list of host names, or, with hosts, the URL is not https on one of them.