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, the app uses:

A large image on the Now Playing screen.

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="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <getMetadata xmlns="http://www.sonos.com/Services/1.1">
      <id>category:popular</id>
      <index>0</index>
      <count>100</count>
    </getMetadata>
  </soap:Body>
</soap:Envelope>

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

<soap:Body>

<id>category:popular</id>

</getMetadata>

</soap:Body>

</soap:Envelope>

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

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <getMetadataResponse xmlns="http://www.sonos.com/Services/1.1">
      <getMetadataResult>
      ...
        <mediaMetadata>
          <id>track0001</id>
          <mimeType>audio/x-ms-wma</mimeType>
          <itemType>track</itemType>
          <trackMetadata>
            <albumId>album0001</albumId>
            <duration>253</duration>
            <artistId>artist0001</artistId>
            <artist>Saratoga Indiana</artist>
            <album>Forgiveness & Gratefulness</album>
            <albumArtURI>http://yourmusicservice.example.com/track0001_180.jpg</albumArtURI>
          </trackMetadata>
        </mediaMetadata>
      ...
      </getMetadataResult>
    </getMetadataResponse>
  </soap:Body>
</soap:Envelope>

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

<soap:Body>

...

<id>track0001</id>

<mimeType>audio/x-ms-wma</mimeType>

<itemType>track</itemType>

<albumId>album0001</albumId>

<artistId>artist0001</artistId>

<artist>Saratoga Indiana</artist>

<album>Forgiveness & Gratefulness</album>

<albumArtURI>http://yourmusicservice.example.com/track0001_180.jpg</albumArtURI>

</trackMetadata>

</mediaMetadata>

...

</getMetadataResult>

</getMetadataResponse>

</soap:Body>

</soap:Envelope>

Provide images in multiple resolutions

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.

Use image substitution for album art

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.

Set the substitution rules in the presentation map

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.

For example, if you sent the following albumArtURI for album art:

http://yourmusicservice.example.com/cdn-directory/aa-id_180.png

1	http://yourmusicservice.example.com/cdn-directory/aa-id_180.png

The Sonos app would use this image for album art if you do not provide any substitution rules.

If the listener is viewing a larger screen, the Sonos app makes the appropriate substitution. It will follow the substitution rules you have set and replace the “_180.png” from the URI with “_600.png” to get the following albumArtURI and a much better visual experience for the listener:

http://yourmusicservice.example.com/cdn-directory/aa-id_600.png

1	http://yourmusicservice.example.com/cdn-directory/aa-id_600.png

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

Set up image substitution for album art

To set up image substitution for album art, 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. For example:

<PresentationMap type="ArtWorkSizeMap">
  <Match>
    <!--
      Sample URI: http://yourmusicservice.example.com/cdn-directory/aa-id_180.png
      -->    
    <imageSizeMap>
      <sizeEntry size="180" substitution="_180.png"/>
      <sizeEntry size="300" substitution="_300.png"/>
      <sizeEntry size="600" substitution="_600.png"/>
      <sizeEntry size="1000" substitution="_1000.png"/>
    </imageSizeMap>
  </Match>
</PresentationMap>

<Match>

<!--

Sample URI: http://yourmusicservice.example.com/cdn-directory/aa-id_180.png

-->

</imageSizeMap>

</Match>

</PresentationMap>

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”.

Create a default album art image

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.

Use square album art for the best experience. If the album art is not square, the Sonos app centers it in the album view and crops it into a square for display.

Dark mode for default album art

Please make sure Default Album Art meet the following guidelines:

DO provide solid color image that works for light and dark backgrounds
DON’T have your default album art match light (#D8D8D8) or dark (#262626) background colors.

NOTE Sonos displays a default placeholder image if you do not provide default 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 authentication using getAppLink. See Add authentication for details.

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

<trackMetadata>
  <albumId>album0001</albumId>
  <duration>253</duration>
  <artistId>artist0001</artistId>
  <artist>Saratoga Indiana</artist>
  <album>Forgiveness & Gratefulness</album>
  <albumArtURI requiresAuthentication="true">http://yourmusicservice.example.com/track0001_180.jpg</albumArtURI>
</trackMetadata>

<albumId>album0001</albumId>

<artistId>artist0001</artistId>

<artist>Saratoga Indiana</artist>

<album>Forgiveness & Gratefulness</album>

<albumArtURI requiresAuthentication="true">http://yourmusicservice.example.com/track0001_180.jpg</albumArtURI>

</trackMetadata>

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 getDeviceAuthToken.
X-AuthToken: The authorization token (authToken) provided in the response of getDeviceAuthToken.

Sample request

<header>
  <credentials>
  ...
    <loginToken>
      <token>e6b223650341d</token>
      <key>ExampleKey</key>
      <householdId>ExampleHouseholdID</householdID>
    </loginToken>
 </credentials
</header>

...

<key>ExampleKey</key>

<householdId>ExampleHouseholdID</householdID>

</loginToken>

</credentials

</header>

See getDeviceAuthToken for details.