Dev Portal

Add browse icons

Your service can use browse icons to represent a category, genre, or other container type in the Sonos app. The image below shows an example of browse icons for items in a container.

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:

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

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 on the Browse Options page of your Integration Submission Form. 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 Browse Options

Set the substitution rules for browse icons in Browse Options. 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:

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:

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, use the Image Replacement Rules section on the Browse Options page of the Integration Submission Form.

There, you can use regex patterns and replacement text to which icons should be replaced in specific situations.

⚠️

Legacy icon configuration

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.

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.

All images should adherer to the following:


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. You can use a tool like WebAIM to test your icon's contrast.
  • Optionally, you may add a solid background color to your browse icons.

📘

Default background

Sonos currently adds 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 currently provided 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 80x80 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.

Updated 2 days ago