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
• Generating Images from the Artwork Object
  • Using the Artwork Web Component
  • Using formatArtworkURL to Generate Image URLs

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;
Copy

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"
}
Copy

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>
Copy

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>
Copy

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"
Copy