This guide goes over the following:

Overview

Artwork consists of line art or photographs, depending on the image type. The Sonos app displays album art, custom browse icons, ratings icons, and service logo image types. Your content service sends these to the Sonos app to render. See below for more details about these image types.

Album art

Photographs associated with an album, artist, playlist, or trackMetadata object. See Add album art for details.

Custom browse icons

Line art that can represent a category, genre, or other container type in the Sonos app. For example, you can use these items in your root browse screen to show the initial categories that a listener can choose from. See Add browse icons for details.

Ratings icons

Ratings icons are line art images that represent the ratings state available to or chosen by the listener. See Add ratings for details.

Service logos

Service logos are line art images that represent your service in the music catalog. Listeners see this logo when searching for your content service to add it to their Sonos system. They then see the logo once they’ve added your service and they want to use it. Service logos represent your brand in the Sonos app. See Add logos for details.

Dark Mode

Sonos is adding support for dark mode on iOS and Android. The Sonos apps will follow the device app theme by default and users will be able to change the app theme via their Sonos App Settings (Settings>App Preferences>Appearance).

Sonos apps

Version 5 of the Sonos app introduced a redesign that can use the high resolution displays of iOS and Android devices.

The Windows and MacOS apps, and discontinued Sonos hardware controllers (such as the Sonos CONTROL/CR200) are considered legacy controllers. These controllers still use images in PNG format. Therefore, you must submit your logos in PNG format as well.

The table below lists the supported Sonos apps and image formats. Click a link in the product column to read the product documentation.

Sonos Apps	Description	Product	Image Format
WDCR	Windows desktop app (legacy user interface)	Sonos app for Mac or PC	PNG
MDCR	Mac OS desktop app (legacy user interface)	Sonos app for Mac or PC	PNG
ICR	iOS app	Sonos app for mobile devices	SVG
ACR ACR-HDPI	Android app for tablets and phones	Sonos app for mobile devices	SVG
CR200	Custom Sonos controller (legacy user interface)	Sonos CONTROL (CR200) PDF	PNG

Save PNG and JPG files at 72 DPI

Photographs need to be delivered in specific sizes, in JPG or PNG format, and with a density of 72 DPI. Files that specify a different DPI setting may not display correctly in every Sonos app.

Save as SVG Basic 1.1 Profile

It is important that you save Scalable Vector Graphic (SVG) images in the SVG Basic 1.1 profile. See the W3C recommendation for further details about this SVG profile. Also, do not use SVG <text> and <mask> elements or hidden layers in your line art because they can cause display problems in the Sonos app.

Validate your SVG using the W3C Markup Validation service. Be sure that the ‘Document Type’ is specifically set to SVG 1.1 Basic.

Your logos must pass validation before you submit your service for certification by Sonos.

Use image substitution for art and icons

Artwork appears in many different sizes, depending on the device and where the the Sonos app shows the art. Therefore, the Sonos app uses image substitution to deliver a high-quality visual experience for every instance. Album art and custom browse icons use similar image substitution rules since they both use the albumArtURI element to display images. Sonos scales artwork by taking the largest size above what is required by the app and downsampling it.

Image substitution and album art

Set the substitution rules for images in the presentation map (see Customize display for details). 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.

Image substitution and custom browse icons

The above applies to custom browse icons as well.

The Sonos app would use the URI for the following image for the browse icon if you do not provide any substitution rules:

http://yourservice.example.com/icons/playlists_legacy.png

1	http://yourservice.example.com/icons/playlists_legacy.png

If the listener is using a phone or tablet, the Sonos app follows the substitution rules you set and replaces the “_legacy.png” with one of the SVG images, depending on the device and screen. For a small screen, it might substitute the “_legacy.png” in the albumArtURI for “_40.svg”, resulting in the following URI:

http://yourservice.example.com/icons/playlists_40.svg

1	http://yourservice.example.com/icons/playlists_40.svg

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</code> <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</code> <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>

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

Set up image substitution for custom browse icons

To set up image substitution for custom browse icons, define your icon artwork sizes using the browseIconSizeMap element in a PresentationMap of type BrowseIconSizeMap. The imageSizeMap sets the rules the Sonos app uses to pick the custom browse icon with the best resolution to display using sizeEntry elements.

<PresentationMap type="BrowseIconSizeMap">
    <Match>
        <browseIconSizeMap>
            <sizeEntry size="0" substitution="_legacy.png"/>
            <sizeEntry size="40" substitution="_40.svg"/>
            <sizeEntry size="290" substitution="_290.svg"/>
        </browseIconSizeMap>
    </Match>
</PresentationMap>

<Match>

</browseIconSizeMap>

</Match>

</PresentationMap>

The sample presentation map above shows that your service provides browse icons in three sizes. The Sonos app on Mac or PC will use the PNG image for your browse icons. The Sonos app on phones and tablets will use your substitution rules to choose the appropriate SVG image for your browse icons.

Note that the legacy icon is listed with a size of zero. Sonos requires this configuration to display custom browse icons on the Sonos app for MacOS and PC. It’s important that you specify this legacy icon as it’s the only one used by the Sonos app for Mac and PC. The Sonos app for mobile devices can handle high resolution images, so they’re more apt to use image substitution to display browse icons.

The base albumArtURI is the URI that your service sends Sonos in a getMetadata response. Use the PNG image format on the Sonos app for Windows and MacOS. See Sonos apps, above, for details.

Custom browse icons on the Sonos app for mobile devices uses the rules set in the browseIconSizeMap. These rules describe how the app should rewrite the URI for the appropriate SVG image.

If you do not provide SVG images or substitution rules, the Sonos app will resize the legacy PNG image as needed. This may not be the best visual experience for listeners. We recommend setting up substitution rules. Your listeners will appreciate it.

Logo for Sonos website

Provide an image that our Web team can scale and use on the Sonos site. Ideally, this image should satisfy the following requirements:

Width: about 300px
Height: about 100px
Format: .ai or .eps
Transparent background