Your service can use browse icons to represent a category, genre, or other container type in the Sonos app. For example, in the root browse container. The image below shows an example of browse icons for items in a container.
This guide goes over:
Create custom browse icons
First, determine the custom icons you would like to use for your service on Sonos. For example, you may want to offer different icons for browsing Artist, Albums, and Playlists or maybe you want to have icons for custom categories such as Favorites, Trending, or Featured.
Next, create icons in the required sizes. See below for details.
How the Sonos app displays browse icons
The Sonos app sends a getMetadata request for browse icons as well as other metadata. Your service should return a URI reference to an image file for the custom browse icon as the value for the albumArtURI element. The albumArtURI element is a sub-element of trackMetadata and mediaCollection in your getMetadata response. Custom browse icons will most likely be used with mediaCollection elements and not trackMetadata.
For example, Sonos sends a getMetadata request to your music service that might look something like this:
|
1 2 3 4 5 6 7 8 9 |
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <getMetadata xmlns="http://www.sonos.com/Services/1.1"> <id>root</id> <index>0</index> <count>100</count> </getMetadata> </soap:Body> </soap:Envelope> |
Your service would send a getMetadata response that has one or more albumArtURI elements for mediaCollection:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <getMetadataResponse xmlns="http://www.sonos.com/Services/1.1"> <getMetadataResult> ... <ns:mediaCollection> <ns:id>browse:playlists</ns:id> <ns:itemType>playlist</ns:itemType> <ns:title>Playlists</ns:title> <ns:canPlay>false</ns:canPlay> <ns:albumArtURI> https://yourservice.example.com/icons/playlists_legacy.png</ns:albumArtURI> </ns:mediaCollection> ... </getMetadataResult> </getMetadataResponse> </soap:Body> </soap:Envelope> |
Use image substitution for browse icons
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 a browse icon image, 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.
Set the substitution rules in the presentation map
Set the substitution rules for browse icons in the presentation map. When the Sonos app requests browse icons, 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.
The Sonos app would use the URI for the following image for the browse icon if you do not provide any substitution rules:
|
1 |
http://yourservice.example.com/icons/playlists_legacy.png |
We suggest that you use a suffix, such as “_legacy.png” to identify the default image that Sonos apps will use as the base albumArtURI on legacy devices. The base albumArtURI is the URI that your service sends Sonos in a getMetadata response. This must be the PNG image image to use on the Sonos app for Windows and MacOS (see Add images for details).
The Sonos app on phones and tablets will use the rules set in the browseIconSizeMap to 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. Since this may not be the best visual experience for listeners, we recommend setting up substitution rules.
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:
|
1 |
http://yourservice.example.com/icons/playlists_40.svg |
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.
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:
|
1 2 3 4 5 6 7 8 9 |
<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> |
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: 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 use image substitution to display browse icons.
Test your browse icons
You should test your service to verify that the correct nodes are present in the presentation map file, that the image substitutions configured in the presentation map work, images can be downloaded, and images are the correct size. To do this, host the presentation map, enable your service using customsd.htm, and point to your hosted presentation map. See Test your service for details.
Sonos app image formats
Custom browse icons are displayed in different sizes and formats, depending on the app. iOS and Android apps require SVGs, while Windows, and Mac apps require PNGs. While you can provide PNGs for your custom browse icons for all apps, we encourage you to use SVGs as they are easier to scale and will be used by all apps in the future.
iOS and Android image formats (SVG)
While you can submit images in PNG or SVG format, we prefer SVG format. This is because the Sonos app for mobile devices can easily scale SVG formatted images to different sizes.
Please make sure the browse icons meet the following guidelines:
- DO provide a transparent, single color icon
- DO check that your icon passes WCAG AA for light (#D8D8D8) and dark (#262626) backgrounds. https://webaim.org/resources/contrastchecker/
- You may (optionally) add a solid background color to your browse icons
NOTE We currently add a default background (#D8D8D8) color to icons on dark and light modes. This means in light mode, if you provide a transparent image with no background, it will render as transparent (See examples above). This is provided today to ensure readability but should not be relied on. You should ensure your images are readable on both a light and dark background.
See Add images for details on how to save SVG icons for proper display on Sonos apps.
iOS and Android image formats (PNG)
See below for the iOS and Android custom browse icons in PNG format.
Note that while you can provide these icons in PNG format, you may have to update them to SVG when they are no longer supported.
Windows, Mac, and legacy Controller image formats (PNG)
You must also include custom assets that match the visual language of legacy firmware in the field, such as the Sonos app for Mac and PC.
Provide an 80×80 icon in PNG format, as shown above, for the Sonos app on legacy devices. Add a suffix, such as “_legacy.png”, to identify these as legacy browse icons so these apps can use it in image substitution. See Set up image substitution for custom browse icons for details on how these apps use the legacy browse icon.