Implementing Album Art

Implementing Album Art

This page is no longer updated.

See Add album art on the Sonos developer portal for the latest documentation.

The screen shot below shows an example of a tablet showing the grid display type of album art for a music service.

The Sonos app displays album art in many different screens and sizes. Image size depends on the UI view and the size of the mobile device. For example:

  • A small thumbnail is used for browsing through music on a phone.
  • A large image is used on the Now Playing screen of a tablet.
  • A different image size is used for the hero view on both phones and tablets.

Most album art consists of photographs. Unlike line art, photographs are not scalable by the Sonos app. To make up for this, the Sonos app uses image substitution to show high-quality album art on every screen and device. 

To take advantage of image substitution, your service should provide Sonos with album art in multiple resolutions. Instead of resizing one image for all screens and situations, the Sonos app will rewrite the <albumArtURI> to use an image with the right resolution for each particular use.

For example, your service could provide a base <albumArtURI> with a resolution of 50 x 50. This is good in some situations, but won’t look good at all if it is used for the hero view on a listener’s iPad. If your service is using image substitution, the Sonos app will rewrite the <albumArtURI> to use a larger resolution that your service provides. The listener will enjoy the high-quality album art.

Sonos recommends that you provide the PNG or JPG images sized to the following resolutions:

  • 60 x 60
  • 80 x 80
  • 120 x 120
  • 180 x 180
  • 192 x 192
  • 200 x 200
  • 230 x 230
  • 300 x 300
  • 600 x 600
  • 640 x 640
  • 750 x 750
  • 1000 x 1000
  • 1242 x 1242
  • 1500 x 1500

If your service can’t provide all the resolutions, the Sonos app will choose the best available size for each particular use. Provide more sizes to reduce the amount of resizing the Sonos app has to do. Your listeners will appreciate it. Your PNG and JPG images should have a density of 72 DPI, see the Digital Asset Guideline Overview for details.

How the Sonos App Displays Album Art

The Sonos app sends a getMetadata request for album art as well as other metadata. Your service should return a URI reference to an image file for the album art as the value for the <albumArtURI> element. The <albumArtURI> element is a sub-element of <trackMetadata> and <mediaCollection> in your getMetadata response.

For example, Sonos sends a <getMetadata> request to your music service that might look something like this:

<soap:Envelope xmlns:soap="">
    <getMetadata xmlns="">

Your service might send a <getMetadata> response that has one or more <albumArtURI> elements for <trackMetadata>:

<soap:Envelope xmlns:soap="">
    <getMetadataResponse xmlns="">
            <artist>Saratoga Indiana</artist>
            <album>Forgiveness & Gratefulness</album>


Define your album artwork sizes using the <imageSizeMap> element in a <PresentationMap> of type ArtWorkSizeMap. The <imageSizeMap> sets the rules the Sonos app uses to pick the album art with the best resolution to display using <sizeEntry> elements.

Set a <sizeEntry> element for each size that you want to substitute. Set the size parameter of the <sizeEntry> element to the resolution size of the image that the Sonos app will request. Then set the substitution parameter to the substitution string. This should be a unique string for each size. See the sample presentation map below for an example.


<PresentationMap type="ArtWorkSizeMap">
      Sample URI:
      <sizeEntry size="180" substitution="_180.png"/>
      <sizeEntry size="300" substitution="_300.png"/>
      <sizeEntry size="600" substitution="_600.png"/>
      <sizeEntry size="1000" substitution="_1000.png"/>

The sample presentation map above shows that your service has provided four different album art sizes. Sonos will pick one of these sizes depending on the device a listener is using and the screen they are viewing. If the Sonos app is looking for a size that is not listed, it will use the next closest image that is listed.

The base <albumArtURI> is what your service first sends Sonos in a getMetadata response. You must include a <sizeEntry> for the base <albumArtURI> in your <imageSizeMap>. The Sonos app will use the rules set in the <imageSizeMap> to show the best available size for the screen and device. This might mean using the base URI for album art, or using substitution rules to rewrite the URI for a different size image URI.

This ArtWorkSizeMap shows that an <albumArtURI> with the string “_180.png” in it has a “size=180” for 180 x 180 images. To get a 600 x 600 image, the Sonos app will use string substitution to replace “_180.png” with “_600.png”.


The Sonos app uses image substitution to deliver a high-quality visual experience for every screen and device that listeners are using. Set the substitution rules for images in the presentation map. When the Sonos app requests album art, it will look at these rules to see if there is a value to substitute in the <albumArtURI> for the image. If there is, the app will use the substitution rules to rewrite the URI to get an image of the appropriate size.

So, for example, if you sent the following <albumArtURI>:

The Sonos app would use this image for any album art if you do not provide any substitution rules. If you had set substitution rules, the Sonos app would choose the best size available for each particular use.

For example, you have set your substitution rules and your service sends the above URI. If a size 120 x 120 album art image is right for the situation, Sonos will use this URI. If the listener is viewing a larger screen, maybe the Hero view where a 120 x 120 wouldn’t look good if it was enlarged to fit, the Sonos app makes the appropriate substitution. It will follow the substitution rules you have set and replace the “_120.png” from the URI with “_600.png” to get the following <albumArtURI> and a much better visual experience for the listener:

If you did not provide a 600 x 600 image, the Sonos app would pick the closest image that you provide and resize it.


We recommend you create a default album art image and return its URI whenever you don't have specific album art to return in a response. If you leave the <albumArtURI> element empty, the Sonos app will use its default album art image shown below.

Sonos default album art

Album art can be square, as shown in the recommended sizes, or it can be rectangular. The album view extends the artwork from one edge of the screen to the other. If the album art is not square, the Sonos app centers it in the album view and crops it into a square when a listener scrolls down to reveal the entire album art image. Here's an example of the album view scrolled up:

Self-test & review

Use the Self-Test Suite to validate your presentation map configuration. The script verifies that the correct nodes are present in the presentation map file. It also verifies that the image substitutions configured in the presentation map work, images can be downloaded, and images are the correct size.

Below is the output from a service that has implemented hi-res album art, in test case 3 and 4:

$ python ./ --config my_service.cfg

SUITE Summary Report Files: SummaryReport.html and Presentation-map-Validation.txt
SUITE Detailed Debug Log File: Presentation-map-Validation-DEBUG.log
SUITE Start *test suite* 'Presentation map Validation' at Monday, March 31, 2014 06:30 AM 
INFO -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  
INFO Start Test Case: 1 Albumart test_custom_browse_icon_configuration
INFO Skipping size check for size 0 because the substitution can be anything
PASS 1 Albumart test_custom_browse_icon_configuration
INFO -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  
INFO Start Test Case: 2 Albumart test_custom_browse_icon_schema
PASS 2 Albumart test_custom_browse_icon_schema
INFO -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  
INFO Start Test Case: 3 Albumart test_hi_res_album_art_configuration
PASS 3 Albumart test_hi_res_album_art_configuration
INFO -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  
INFO Start Test Case: 4 Albumart test_token_inside_substitution
PASS 4 Albumart test_token_inside_substitution
SUITE Summary: Passed. Passed: 4, Failed: 0.

This particular fixture of the Self-Test produces additional debug output in the form of an HTML file that links to the Album Art reviewed by the Self-Test. Use your browser to load the file at $selftest_directory/content_workflow/albumart/Service Name.html. This file contains standard references to each resolution of Album Art configured in the presentation map.

You can also perform manual verification by hosting the presentation map, enabling your service using customsd.htm, and pointing to your hosted presentation map. Then use a Sonos app to manually test your album art.

Album Art Authentication (optional)

If your CDN requires authentication to access album art, you will need to do some further configuration. This feature is only available for services supporting DeviceLink authentication.

To enable Sonos apps to pass authentication credentials as HTTP Headers in a request for album art, you must add the requiresAuthentication attribute with a value of "true" to the <albumArtURI> element that is returned in <trackMetadata> responses (or streamMetadata as appropriate). For example:

Sample Response

  <artist>Saratoga Indiana</artist>
  <album>Forgiveness & Gratefulness</album>
  <albumArtURI requiresAuthentication="true"></albumArtURI>

When the requireAuthentication attribute is set to true as shown above, Sonos apps include the DeviceLink credentials in an HTTPS get request against the URI specified in <albumArtURI>. These credentials will be found in the associated headers:

  • X-HouseHoldId: The household ID of the sonos system.
  • X-AuthKey: The authorization key provided in the response of getDeviceLinkAuthToken.
  • X-AuthToken: The authorization token (authToken) provided in the response of getDeviceLinkAuthToken.



See getDeviceAuthToken documentation for details.