Sonos Music API - Conceptual Overviews

Add your service with customSD

You can add your service to your Sonos household for testing purposes using the custom service descriptor (customSD) form on a player. The capabilities on this form mirror the capabilities that you can make for your service in the Technical Configuration & Test Setup section of your service application in the Version Manager. To add your service to your Sonos household:

  1. Find the IP address of one of your players. See the Check my Sonos ID FAQ for details.
  2. Go to a web browser and type:
    http://{IP address of zone player}:1400/customsd.htm
  3. Fill out the form with information that is relevant to your service and click Submit (see below for details).
  4. On your Sonos app, click Add Music Services and look for your Service Name.
    If you marked your service as a Sonos Sound Lab, click Sonos Labs to see it.

 

Form Breakdown :

Form Field Description SMAPI Methods
SID An internal identifier for Sonos firmware. Valid values are 240-253, and 255 inclusive.
Note: when updating your service to a new version, use a different number than the one used before.
 
Service Name The name of your service. This name will be displayed on the Add Music Services menu and in the Music Browse and Universal Search results.  
Endpoint URL The non-SSL endpoint for your SMAPI service.  
Secure Endpoint URL The SSL endpoint for your SMAPI service. HTTPS is required. See TLS/SSL Security Overview for details.  
Polling Interval The number of seconds between each Sonos poll request. Sonos firmware leverages the polling technique to check for updates in browse content. See getLastUpdate for details. getLastUpdate
Authentication SOAP header policy
(the security schema your service will be using, see Authentication for details)
 
Session ID Allows the use of session IDs to authenticate a client implementation. The service grants a client a session ID, which the client passes in with various API methods, and which the service validates before carrying out the call. getSessionId
Anonymous No authentication will be used for the service, thereby allowing any user access.  
Device Link Allows every Sonos household to be uniquely identified by a device ID. A MAC address or some other hardware specific key or serial number is the basis for a device ID. Device IDs are sent in the SOAP envelope for every API method. getDevideLinkCode
getDeviceAuthToken
Application Link Your mobile or tablet app authenticates the user and authorizes Sonos to use their account in their household. The documentation for this feature is forthcoming. getAppLink (TBD)
Strings Table
Version The version number of your strings table XML file, which should start at 1. When testing with customSD, you must increment this number for controllers to pick up changes made to your strings table XML file. In production, let your Sonos representative know that we must increment this number.  
Uri The URL where your strings.xml file is hosted. See Strings and Localization for details.  
Presentation Map (required if you enabled the search capability)
Version The version number of your presentation map XML file, which should start at 1. When testing with customSD, you must increment this number for controllers to pick up changes made to your presentation map XML file. In production, let your Sonos representative know that we must increment this number.  
Uri The URL where your presentation map XML file is hosted. See Presentation Map for details.  
Container Type The location where your service is displayed in the Add Music Services menu. If you select "Music Service," your SMAPI Service will appear in the top-level list of services in the Add Services wizard of a Sonos app.

If you select "Sonos Sound Lab," your SMAPI Service will appear in Sonos Labs. In current (as of build 26.1-*) mobile controllers (iOS, Android), this adds a Beta label to your logo in the Service Catalog. In legacy mobile controllers (prior to build 26.1-*) or desktop controllers, Sonos CONTROL and CR100, this designation places your service one level below the top-level Add Music Services list in a container called Sound Labs.
 
Capabilities
Search Enables the ability for users to search your service. If your service offers this capability, enabling this will allow users to search for content via the Sonos app. Enabling this capability in the SMAPI Partner Application will also force the requirement of a presentation map. See the Implementing Unified Search tutorial for details. getMetadata("search")
search
Favorites: Adding/Removing Tracks Enables track favoriting in Sonos firmware. If your service offers this capability, enabling this will allow users to add tracks to their favorites folder via the Sonos app. See the Implementing Track or Album Favorites tutorial for details. createItem
deleteItem
Favorites: Adding/Removing Albums Enables album favoriting in Sonos firmware. If your service offers this capability, enabling this will allow users to add albums to their favorites folder via the Sonos app. See the Implementing Track or Album Favorites tutorial for details. createItem
deleteItem
User Content Playlists Enables Playlist Editing in Sonos firmware. If your service offers this capability, enabling this will allow users to create, update, and delete playlists via the Sonos app. See Playlist Editing for details. createContainer
deleteContainer
renameContainer
addToContainer
reorderContainer
removeFromContainer
Playback duration logging at track end Enables track playback reporting when the track has finished playing. A SMAPI Service will typically use this to gather playback data. setPlayedSeconds
Playback event logging during track play Enables track playback reporting while the track is currently playing. When playback is started, the <seconds> value is 0. On successive calls, it is the current number of seconds played since the beginning of playback. The SOAP response returns a value of how many seconds should elapse before the next report. A value of 0 indicates that no reporting should be issued after the track begins playing. Your SMAPI Service will typically use this to gather more granular playback information in the event partial playback triggers royalties or some other licensing condition. reportPlaySeconds
reportPlayStatus
Account Logging Enables account reporting in Sonos firmware. Every time an account is added to your service from a Sonos app, a report message will be sent to your service. reportAccountAction
Extended Metadata This capability is required and enables the Sonos app to make calls for extended metadata (such as album notes, artist biographies, ratings, or others) to enhance the browsing experience. See getExtendedMetadata for details. getExtendedMetadata
getExtendedMetadataText
Disable Alarm Support Selecting this will prevent content from your service from being used as a Sonos alarm. This is useful if you have transient streams (such as live events, limited-edition content, and others).  
Disable Multiple Account Support Note: You cannot disable multiple accounts support for a production service because it is a core system feature required by Sonos.
Selecting this prevents multiple users from associating their own account to a Sonos household. Instead, only one user account from your service will be able to be associated with a Sonos household. See the What is Multiple Account Support FAQ for details.
 
Support the ability to receive implicit or explicit actions for getMediaUri requests An action is:
  • Explicit if the track is playing based on an action initiated by a user, for example, when a user clicks play, seek, skip forward, or skip back.
  • Implicit if the track is playing automatically as it is the next in the queue.
getMediaURI
Include SMAPI context headers with all requests Sonos will include a <context> element within the SOAP header, for example, to send time zone information to your service. See Requests and Responses for details.  
Requires Device Certificate Sonos will include a <deviceCert> sub-element of the <credentials> element in the SOAP header. See Requests and Responses for details. getMediaURI
getContentKey
Include Zone Player IDs in credentials header Sonos will include the Sonos player ID for the player sending the request in a <zonePlayerId> sub-element of the <credentials> element in the SOAP header. See Requests and Responses for details.  
Add play context to reporting Sonos will include a <contextId> element with every setPlayedSeconds, reportPlayStatus, and reportPlaySeconds request. setPlayedSeconds
reportPlayStatus
reportPlaySeconds
Enable userInfo Enables players to send getUserInfo requests.  getUserInfo

Example: