No Preview

Sorry, but you either have no stories or none are selected somehow.

If the problem persists, check the browser console, or the terminal you've run Storybook from.

Article

Album Art & Images

MusicKit on the Web makes it easy to add images for content from the Apple Music Catalog, for example album covers or playlist art.

The Apple Music API responses will often contain Artwork Objects, which can be used to render these images in your app. There are also various values related to the image, such as colors pulled algorithmically from the image contents that can be used for content-specific designs in your app.

Quick Links


The Artwork object

See: Apple Music API: Artwork

Artwork objects are found on responses from the Apple Music API, usually under the attributes.artwork property for a resource.

const { data: { data: [album] } } = await music.api.music('/v1/catalog/{{storefrontId}}/albums/1560735414');
const artwork = album.attributes.artwork;

Here is an example of the Artwork object from an Apple Music API response:

"artwork": {
    "width": 3000,
    "height": 3000,
    "url": "https://is1-ssl.mzstatic.com/image/thumb/Music125/v4/33/fd/32/33fd32b1-0e43-9b4a-8ed6-19643f23544e/21UMGIM26092.rgb.jpg/{w}x{h}bb.jpg",
    "bgColor": "675f9a",
    "textColor1": "f3f6fb",
    "textColor2": "fbeaf0",
    "textColor3": "d7d8e8",
    "textColor4": "decedf"
}

Generating Images from the Artwork Object


Using the Artwork Web Component

See: Reference : Web Components : Artwork

The <apple-music-artwork> component will handle the width and height replacement, set a background color to show while artwork is loading, and supply different image sources for different device pixel ratios. Your app just needs to determine the desired display width, and configure the component appropriately.

Example

In the example below, the <apple-music-artwork> component uses the above example Artwork object from the Apple Music API. The width attribute is setting the desired display width, which the web component uses to create a <picture> tag with the various dimensions needed to support modern Retina displays seamlessly.

<apple-music-artwork alt="Lorem Ipsum" width="250"></apple-music-artwork>
<script>
  const artworkElement = document.querySelector('apple-music-artwork');
  artworkElement.source = album.attributes.artwork;
</script>

You can also provide just the URL property as the source, which will result in a generic background color, and requires passing the width attribute still to determine the display dimensions.

<apple-music-artwork
  alt="Lorem Ipsum"
  source="https://is1-ssl.mzstatic.com/image/thumb/Music125/v4/33/fd/32/33fd32b1-0e43-9b4a-8ed6-19643f23544e/21UMGIM26092.rgb.jpg/{w}x{h}bb.jpg"
  width="250"
></apple-music-artwork>

Example of the rendered artwork component:


Using formatArtworkURL to Generate Image URLs

The formatArtworkURL method takes an Artwork object, and an optional height and width. It returns a URL string that can be used as an image source.

If the width or height arguments are not passed, this method will use the maximum values, which come from the Artwork object itself.


const imgSrc = MusicKit.formatArtworkURL(artwork, 200, 200);
console.log(imgSrc);
// "https://is1-ssl.mzstatic.com/image/thumb/Music125/v4/33/fd/32/33fd32b1-0e43-9b4a-8ed6-19643f23544e/21UMGIM26092.rgb.jpg/200x200bb.jpg"