Sonos Music API - Getting Started Guide

Presentation Maps

The Presentation Map is an XML configuration file that enables you to customize certain presentation and functional aspects of your music service in Sonos firmware. You should host this file and enter its URL in the "Technical Configuration" section on the version set up form. When published, the URL is provided to Sonos Controllers allowing them to download the file when a customer adds your service to their household. Note that this URL should not exceed 64-characters.

The Presentation Map allows configuration of:

  • Unified Search
  • Hi-Res Custom Browse Icons
  • Hi-Res Album Art
  • SMAPI Ratings
  • Menu Item Overrides
  • Browse Options

Please review the sample presentation map XML file in the downloadable Self-Test for an example of a fully configured Presentation Map.

Unified Search

If your service supports the SMAPI Search capability, then you must configure Unified Search in a presentation map. This configuration tells the Sonos Controller what types of searches you support. Please review the documentation describing the implementation in our Unified Search tutorial.

Hi-Res Custom Browse Icons

If your service supports custom browse icons, by overloading the albumArtURI node of a mediaCollection, you must configure Hi-Res Custom Browse icons within your presentation map. You must implement two styles of icons, and you must configure a set of substitution rules that allows the Sonos Controller to select and display the correct Icon depending on OS platform and Sonos Controller version. Please review the documentation describing the implementation in our Hi-Res Custom Browse Icons tutorial.

Hi-Res Album Art

If your service delivers album art for music that is playing (visible on the Now Playing Screen), you must configure Hi-Res Album Art within your presentation map. You must configure a set of substitution rules that allows the Sonos Controller to select and display the correct album Art depending on OS platform and Sonos Controller version. Please review the documentation describing the implementation in our Hi-Res Album Art tutorial.

SMAPI Ratings

If your service allows a listener to rate a track or stream, then you must configure Ratings within your presentation map. This configuration dictates the ratings UX for the Now Playing screen on the Sonos Controller. The presentation map configuration includes definition of the icons to be used in the UX, what tags the Sonos Controller should look for when determining which Icon to show, and what values will be submitted in the rateItem() SMAPI call when a listener clicks, or taps one of the Icons in the Now Playing screen. Please review the documentation describing the implementation in our Implementing listener ratings tutorial.

Info View Menu Overrides

If your service has implemented the ability to start up a radio stream related to the current item playing, you can override the default strings in the Sonos app that display in the Info View. For instance, the default string "Start Radio" can be changed to “Go To Radio” or something more appropriate for your service. Please review the documentation describing the implementation in Adding related play radio streams.

Browse Options

BrowseOptions allow you to override certain standard browse behaviors of Sonos Controllers. At the moment, the only BrowseOption you can configure is the “count” attribute of getMetadata and search requests. By default, all getMetadata requests from Sonos Controllers ask for 100 items to be returned (CR200 asks for 500). You can increase or decrease this value based on your preference:

<?xml version="1.0" encoding="utf-8" ?>
<Presentation>
    <!-- BrowseOptions allow for an override of standard
         browse operations in the controller. The setting
         below will force the controller to ask for 250
         items in each getMedata request. -->
    <BrowseOptions PageSize="250" />
</Presentation>