Implementing Custom Browse Icons

Implementing Custom Browse Icons

Custom browse icons are images that your service uses to represent a category, genre, or other container type in the Sonos app. They are often used in the root browse of a music service. For example, the screen below shows the same custom browse icon used for Playlists, Artists, Albums, and other categories.

The Sonos app is available on many different devices so it displays your browse icons on a variety of screen sizes. Listeners browsing your service on a phone will see a smaller image than those using a tablet. Browse icons in your root menu are often larger than those shown in the next container level.

The icon that looks good browsing on a phone might not look as good to a listener who is looking at your root menu on a tablet. Therefore, the Sonos app uses image substitution to ensure that your custom browse icons look good on every screen and device. To take advantage of image substitution, your service should provide Sonos with browse icons in multiple sizes.

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.

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 the Custom Browse Icon Guidelines or download the Service Logo and Custom Browse Icon Templates for details on the supported sizes and image formats.

HOW THE SONOS APP DISPLAYS CUSTOM 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:

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

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

DEFINE BROWSE ICON SIZES IN YOUR PRESENTATION MAP

Define your browse icon sizes using the <browseIconSizeMap> element in a <PresentationMap> of type BrowseIconSizeMap. The <browseIconSizeMap> sets the rules the Sonos app uses to pick the icon image with the best resolution to display using <sizeEntry> elements. Set a <sizeEntry> element for each of your browse icon sizes. Set the size parameter of <sizeEntry> element to the resolution size of the browse icon that Sonos 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="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.

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 Digital Asset Guidelines 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. This may not be the best visual experience for listeners. We recommend setting up substitution rules. Your listeners will appreciate it.

HOW THE SONOS APP USES IMAGE SUBSTITUTION

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.

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

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

The Sonos app uses this image for the browse icon if you do not provide any substitution rules. This image may look good in the Sonos app on a PC or Mac, but it may not look good in the Sonos app on a phone or tablet. If you had set substitution rules, the Sonos app would choose the best available size for each particular use.

For example, let’s say that you set substitution rules and your service sends the above URI. If a listener is using the Sonos app on a PC, Sonos will use this URI. 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

This provides your listeners with a much better visual experience when using both your music service and the Sonos app.

Self-test and review

Use the automated self-test to validate the presentation map configuration for custom browse icons. Download and run the self-test in the Python Self-Test Suite on the Sonos Labs main page.

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. You can also perform manual verification by hosting the presentation map, enabling your service using customsd.htm, and pointing to your hosted presentation map.

albumart.py test output for SVG custom browse icons

Below is the output of the albumart.py test in the self-test suite from a service that has implemented custom browse icons using the SVG format. Note we have no way of knowing what the default resolution actually is so we skip that verification. Also, the Python Image Library does not support SVG, so we skip the pixel resolution verification.

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 Wednesday, March 26, 2014 06:18 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
INFO https://sonos.musicservice.com/icons/popular40.svg PIL does not support svg so skipping size validation
INFO https://sonos.musicservice.com/icons/popular290.svg PIL does not support svg so skipping size validation
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
SKIP 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: 3, Failed: 0.

ALBUMART.PY TEST OUTPUT FOR PNG CUSTOM BROWSE ICONS

Below is the output of the albumart.py test in the self-test suite from a service that has implemented custom browse icons using the PNG format. Note we have no way of knowing what the default resolution actually is so we skip that verification. All other substitution rules are checked to make sure the image returned is the resolution specified in the substitution rule.

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 Wednesday, March 26, 2014 06:12 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.