Frequently Asked Questions

General

What kind of music services are eligible to be added to the Sonos Platform?

Sonos Labs is intended for licensed and legal music services such as on demand, subscription, cloud-based access models and radio streaming services.
 

What is Multiple Account Support?

Sonos provides multiple account support for music services. Each person in a household with an account on your music service can add it to Sonos to play the music they love. This brings more listeners to your service as users set up their own personal accounts to stream music rather than being confined to one default account for the Sonos household.

Support for multiple accounts is a core system feature required by Sonos. A music service account becomes the default on the controller that was used to set it up. All searches and features (such as the ability to like tracks) on that controller will use the default account. Users can choose which account to use as the default. For details, see the Music Services and Sonos FAQ "How do I switch between accounts" on the Sonos Support site or see your controller app product guide documentation.

TECHNICAL EVALUATION

WHAT AUDIO SAMPLE RATES AND CODECS ARE SUPPORTED BY SONOS MUSIC PLAYERS USING SMAPI?

A full list of supported audio formats including codecs, file formats, mime-types, bit rates, and transport methods can be found  on the Audio Formats page of the Sonos Music API - Getting Started Guide.
 

WHAT LANGUAGES DOES SONOS SUPPORT FOR LOCALIZATION?

English, French, Italian, German, Spanish, Dutch, Japanese, Chinese, Swedish, Danish, and Norwegian. Note that Sonos users make their language selection independently of their current locale, so we urge all music service partners to translate all "static text" (i.e., all text except the album/artist/track metadata) into these languages.
 

WHAT FLAVOR OF SSL DO YOU SUPPORT?

We support TLS v1. We act as our own Certificate Authority (CA) and self-sign the client certificates used by our firmware. See the TLS/SSL Security Overview for details.
 

DOES SONOS SUPPORT REST?

Music services built using the Sonos Music API are based on SOAP. However, if you have internal back end services that are REST-based, you can implement your SMAPI service as a mediation layer that maps SMAPI SOAP methods to your REST back-end.  
 
Note the Sonos Music API is based on SOAP primarily because our Zone Players rely heavily on UPnP for internal communication. UPnP is a protocol built on SOAP so it was a natural fit to choose SOAP for SMAPI.
 

WHAT IS THE BEST SERVER STRUCTURE TO SUPPORT MY SERVICE WORLDWIDE?

In general, you are implementing a SOAP service that wraps your own back-end services.  You should consider the service for Sonos devices to be a mediation service, and architect it according to your internal service-oriented architectural standards.
 
Ideally, it offers some sort of edge caching, and global DNS distribution with load balancing to deliver a high level of uptime. It is common to implement the mediation layer on its own technology stack (software and hardware), and implement a caching layer to reduce the latency that is common in mediation layers.
 
Please see our SLA/performance requirements to help guide you in building your infrastructure.
 

DO I NEED A DEVELOPER KEY TO USE THE SONOS MUSIC API?

No. To get started all you need to do is download the WSDL, read the documentation, and implement your web service.
 

WHAT PROGRAMMING LANGUAGE AND/OR WEB SERVICE PLATFORM DO YOU SUGGEST?

Internally at Sonos, we have successfully deployed music service mediation layers in C#, PHP, Ruby and Java. Having a language that can ingest a WSDL and generate code is a plus.
 

DOES SONOS SUPPORT TRACK SHARING BETWEEN USERS?

Two users of the same music service can share tracks, assuming the service provides some mechanism for sharing track IDs between users.
 

CAN I MAKE MY SERVICE AVAILABLE TO SONOS USERS WHENEVER I'M READY?

No. You can make your service available within your development environment, but any mass distribution of your service to Sonos users (even under NDA) requires Sonos approval.
 

SONOS SYSTEM ARCHITECTURE

WHAT ARE THE MODEL NAMES AND CAPABILITIES OF EACH SONOS SYSTEM COMPONENT?

Please learn more by reading the Sonos product guides
 

HOW DO SONOS SYSTEM COMPONENTS COMMUNICATE WITH EACH OTHER?

Please learn more by reading the Getting Started Guide.
 

DOES ANY SONOS EQUIPMENT STORE THE MUSIC THAT IS PLAYED?

No. All music is streamed directly out of each Sonos player. There is some amount of internal buffering in RAM on the player, but this is merely to avoid music interruptions on an unreliable network.
 

DO SONOS CONTROLLER APPS CACHE INFORMATION?

Yes. The controller applications will cache music metadata, album art (jpg/png), and search results. The amount of data that is cached varies between controller application platform, and is subject to the amount of RAM present in each device.
 

HOW ARE TRACKS STORED IN SONOS PLAYLISTS?

A Sonos user may save the contents of their music queue into a playlist that is stored on the Sonos system. This playlist does not contain the actual audio for each track, nor does it contain the actual streaming URI for each track. Rather, it contains an encoded identifier the represents which much service provided the track, the track's MIME type, and track ID within that service.
 

WHAT ARE THE MAXIMUM NUMBER OF ZONES THAT CAN PLAY CONCURRENT STREAMS?

Each Sonos household can have a maximum of 32 zones, each playing its own stream.
 

SONOS API ARCHITECTURE

HOW DOES AUTHENTICATION WORK IN THE SONOS MUSIC API?

You may choose 3 ways to implement authentication:
 
  1. Anonymous. In this mode the Sonos user need not provide any credentials, and their system will communicate with your web service without any attempt to log-in or obtain any kind of session token.
  2. Session ID. In this mode, the Sonos system will pass the username and password (via getSessionId preferably over HTTPS), and expect a session token (up to 64 characters) to be returned. All subsequent calls will include the session token in a custom SOAP header. Sessions may expire using any business rules as you see fit, when a Sonos system gets a report of an expired session it will attempt to log-in again.
  3. Username and password. In this mode, the Sonos system will pass the username and password in a SOAP header with every call.  (This mode is deprecated, but still supported in our firmware.)
 
In all authentication modes, every API request includes a unique device ID, and the device provider (Sonos, in this case) within the SOAP header.
 

WHICH RESPONSE FORMATS ARE SUPPORTED?

All SOAP responses should be in UTF-8 XML. For longer responses, it is strongly suggested that the response is sent using GZip encoding.
 

MY SERVICE CAN PROVIDE CONTAINERS, OR PROVIDE SEARCH RESULTS, CONSISTING OF MANY THOUSANDS OF ITEMS. WILL THE SONOS SYSTEM EVER ASK FOR ALL OF THEM AT ONCE?

No. All Sonos APIs that return collections include input parameters specifying a starting index and a count. Your web service replies with an actual returned count (can be less than the requested count), and also provides a total number of items (so that the Sonos system can request successive ranges of items).
 

WHAT IS THE DEVICE ID THAT IS PROVIDED IN THE SOAP HEADER?

This device ID is a unique ID of a randomly selected Sonos player in the customer's household. This ID is established once when the customer sets up their system and is very unlikely to change. Music services should use this ID to designate a single "instance" of a Sonos device.
 

MUSIC LICENSING BUSINESS RULES

OUR MUSIC LICENSING RULES INCLUDE LIMITS ON HOW MANY SONGS CAN BE PLAYED SIMULTANEOUSLY FROM THE SAME ACCOUNT. HOW CAN I PROGRAM THESE RULES INTO MY SONOS API IMPLEMENTATION?

SMAPI provides a specific SOAP fault code, DeviceLimit, to handle this situation.  If a Sonos player attempts to start playing a new track, and the service returns DeviceLimit, the player will "blacklist" the service and skip over all tracks in the queue from the service.  The blacklist rule will be lifted the next time the user presses [Play].
 

MY SERVICE ISN'T AVAILABLE WORLDWIDE. CAN I RESTRICT USERS BY IP ADDRESS?

Yes. For IP addresses in territories you do not support, you can throw the Client.UnsupportedTerritory SOAP Fault.
 

MY SERVICE IS AVAILABLE IN MULTIPLE TERRITORIES, AND SOME CONTENT IS AVAILABLE IN SOME TERRITORIES BUT NOT IN OTHERS. HOW DO I MAKE SURE NOT TO PLAY CONTENT WHICH SHOULDN'T BE PLAYABLE?

The most straight-forward way to address this is to check the territory the user account is in against the territory licensing for a given asset. If the territory is licensed, set canPlay equal to TRUE, if not, set canPlay to FALSE. Please see the documentation for the trackMetadata entity and/or the mediaCollection entity for more information.
 

DEVELOPMENT HOW-TO'S

HOW TO: IMPLEMENT THE BARE MINIMUM TO GET A SERVICE UP AND RUNNING.

You can build a fully functioning service by implement just 5 of the Sonos Music API methods:
  1. getSessionId. The Sonos system will call this when a user adds your service to their system, passing in the username and password, and your service returns a session token.
  2. getMetadata. This allows Sonos users to browse music in a container hierarchy. The Sonos system passes in a container ID, and your service replies with XML containing the contents of the container.
  3. getExtendedMetadata. This allows Sonos users to view additional content for a given album, artist, or track. The Sonos system passes in an item ID, and your service replies with XML containing the representation of the item.
  4. getMediaMetadata. This allows the Sonos system to get metadata about particular tracks or streams.  The Sonos system passes in a track or stream ID, and your service replies with XML describing it.
  5. getStreamingURI. This allows the Sonos system to play music. The Sonos system passes in a track or stream ID, and your service replies with an URI pointing to an actual audio stream.
  6. getLastUpdate.  This allows the Sonos system to refresh the music catalog in a timely fashion.
 

HOW TO: IMPLEMENT SEARCH.

See the Implementing Universal Search tutorial for details.
 

HOW TO: MAKE YOUR SERVICE VISIBLE TO YOUR SONOS DEVELOPMENT SYSTEM.

Instructions for doing this may be found here.


HOW TO: REPORT ERRORS BACK TO THE USER.

SMAPI uses a set of predefined SOAP fault codes to indicate error conditions.  A listing of these fault codes, and the error messages they trigger under various conditions, can be found here.
 
Additionally, SMAPI allows a service to provide customized error conditions for situations where the usual fault codes do not apply.  More information can be found here.
 

HOW TO: IMPLEMENT ALPHABETIC SCROLLING AKA "POWER SCROLL"

This capability is provided by the getScrollIndices method, documented here.
 

HOW TO: ENABLE 2-LINE DISPLAY OF TRACKS, ALBUMS AND ARTISTS

The Sonos controller apps inspect the itemType of various music containers to determine whether or not a 2-line display for the item should be used. In general, the following container types will implement two-line display: trackList, albumList, and playList.
 

HOW TO: PRESENT ADDITIONAL METADATA TO SONOS USERS, SUCH AS ARTIST BIOS OR ALBUM REVIEWS.

This capability is provided by the getExtendedMetdata method, documented here.
 

HOW TO: ENFORCE SKIP-LIMITS FOR PROGRAMMED RADIO STATIONS.

Sonos players play programmed radio stations by fetching small segments of tracks, getting the next segment as the current one is nearly complete.  To prevent the user from skipping tracks, simply return canSkip=false in the trackMetadata that you return. For more detail on implementing programmed radio, read our API documentation.
 

HOW TO: Allow users to MANAGE a PERSONALIZED CONTENT collection.

Implement createItem, deleteItem and getLastUpdate, set up your custom service descriptor by checking Favorites: Adding/Removing Tracks, Albums, and Artists as appropriate. Be sure to set the Polling interval to something reasonable like 300 seconds (5 minutes).
 

Testing

Are there any automated quality tests?

Yes, the Python Self-Test Suite is available in the QUALITY & TESTING TOOLS SUITE section.
 

What are the appropriate test plans?

The appropriate test plan is the Sonos Labs Self-Test Plan found in the QUALITY & TESTING TOOLS SUITE section. This document outlines the required tests that should be executed by all Content Service Providers prior to official submission. The Sonos SQA team is more than happy to provide guidance and answer any questions regarding the test plan.
 

TROUBLESHOOTING

WHY IS MY ALBUM ART NOT APPEARING IN MY SONOS CONTROLLER APP?

Verify that your image format is either JPG or PNG.  Also, verify that you are delivering a Content Length header for your image resources. Finally, verify that your album art images aren't bigger than our specified maximum permitted size.
 

WHEN I PLAY AUDIO USING MY SERVICE, IT FREQUENTLY SKIPS OR DROPS OUT. WHAT COULD BE GOING ON?

You may be experiencing network connectivity issues.
 

WHY WOULD TRACKS FAIL TO PLAY IN SONOS?

Although there are numerous issues that might cause this to happen, there are two that are more common than others. If getMediaMetadata is not implemented correctly, the Sonos firmware will display a "Cannot add to queue" error. Specifically, be sure that the MIME type returned by getMediaMetadata matches the actual stream type you are delivering.
 
If there is a streaming error, the firmware will also show an error in the diagnostic trace file.
 

HOW DO I CONTACT SONOS FOR DEVELOPER SUPPORT?

For developer support, check the "sonos" tag on Stack Overflow.

 

About the Beta Program

How long is the Beta process?

The Beta process typically lasts between 2 and 4 weeks, but exiting Beta is at Sonos’ discretion.
Some factors that play a part in this decision are:
  1. Number of users and active engagement
  2. Service Performance
  3. Feedback
  4. Resolution of open issues