What's New (developer release notes)

What's New (developer release notes)

When Sonos releases new software, we share release notes with our users. Click the Software Version number in the table below to open these release notes. Click a link in the New Features and Updates section to learn how to add new functionality to your SMAPI service. See below for details about software version and build numbers.

If you're new to SMAPI, be sure to check out the Sonos Music API - Getting Started Guide.

Software Version New Features and Updates
  • We’ve heard your questions about how players stream content and what makes your service available in a listener’s Sonos app. We added How Sonos players work to the Getting started guide to answer these questions.
  • We’ve also updated HTTP Live Streaming (HLS) with information about how players stream HLS content. This includes information about how players adjust content bitrates and how they retry after failures.
  • Updated the Sonos WSDL.
  • Your service can allow users to filter out explicit content in the Sonos app. Explicit content includes content that has excessive profanities, inappropriate references, or a Parental Advisory warning label. Implement this feature to give your listeners the option to prevent playing explicit content from your service on Sonos. See Tag and filter explicit content for details.
  • We’ve made changes to our authentication documents:
  • We added a sample request and response for a radio stream for <streamMetadata> to getMediaMetadata. If your SMAPI service returns <streamMetadata>, it should return this in getMetadata and getMediaMetadata responses.
  • Updated the TLS/SSL security overview with the following:
    • Added a note about testing HTTP access to your SMAPI SOAP service to secure your content.
    • Added a list of common reasons for SSL handshake failures.
    • Noted that the results of the ssl_validation tests in the Self-Test Suite are only valid if DNS and TCP are working. You can also see Debugging Self-Test failures for details. 
  • Your service can tag explicit content for your listeners that use the Sonos app. Explicit content includes content that has excessive profanities, inappropriate references, or a Parental Advisory warning label. Explicit tagging enables you to label this content with an "E" in the Sonos app. See Tag explicit content for details on how to tag explicit content for your listeners. See getMetadata for details about the <tags> and <explicit> elements used for explicit tagging.
  • Updated the Sonos WSDL and Python self-test suite. Also fixed a bug in the self-test that was causing issues validating SVGs.
  • Updated list of certificate authorities trusted by Sonos players. Added support for "GlobalSign Root CA - R3". See TSL/SSL security overview for details.
  • The response results in the tables for some APIs didn't match what we showed in the examples. We fixed these to match the examples. See getExtendedMetadata, getMediaMetadata, and getSessionID for details.
  • Some of the custom browse icon size guidelines were incorrect in the "CUSTOM BROWSE ICONS - PNGs" image but were correct in the table. For example, one icon listed 112x112 as the background size and 68x68 for icon size when it should have been 56x56. We fixed this image. See Custom Browse Icon Guidelines for details.
  • Sonos gets user information like the nickname and a hashed account ID for users of your service to provide customization options. The full capabilities will be available in a future release. See getUserInfo and getDeviceAuthToken for details. To enable getUserInfo see Add your service with CustomSD.
  • We recommend that you be aware of any restrictions when using content or APIs from third-parties. See Music service requirements for details.
  • We added more details about what Sonos apps and players send in User-Agent HTTP headers. These headers can be used to get build information or to tell if a player or an app is sending the request. See Requests and responses for details.
  • We added a line to better clarify that the Sonos public namespace URI includes the SMAPI version number, 1.1. The URI is http://www.sonos.com/Services/1.1. See Requests and responses or Introduction to SOAP for details.
  • The getMetadata <mimeType> element used to be optional. This is now required in responses for Sonos players to accurately play content. See getMetadata for details.
  • We added some details about image formats. See the Digital Asset Guideline Overview for more information on the following:
    • Don't use SVG <text> and <mask> elements or hidden layers in your line art because they can cause display problems in the Sonos app.
    • PNG and JPG files should be saved at 72 DPI.
  • Sonos players send a final setPlayedSeconds report after 30 minutes of no playback activity. See setPlayedSeconds for details and Reporting, HTTP Live Streaming (HLS), and Saving and Resuming Play Position for context.
  • We've updated the list of Certificate Authorities supported by Sonos players. We now support SecureTrust CA. We no longer support GeoTrust Primary Certification Authority - G3 and Go Daddy Class 2 Certification Authority.  See TLS/SSL Security Overview for the complete list. We've also added ECDHE cipher suites as part of the Future Requirements on this page.
  • Updated the Sonos WSDL and Python Self-Test Suite.
  • Please note, the security tests in the Python Self-Test Suite will only run if your OpenSSL library is version 1.0.1 or later.  See TLS/SSL Security Overview for details.


  • Resumable Content - Users can resume listening to audiobooks and individual tracks like podcasts. These new Types of Supported Content include the new audiobook <itemType>, described in SMAPI itemTypes. For implementation details, see Saving and Resuming Play Position.
  • HTTP live streaming (HLS) - You can now stream content to Sonos from an ordinary Web server over HTTP using HTTP Live Streaming. Sonos supports two types of HLS: streaming HLS for live radio and on-demand HLS for programmed radio or individual tracks. For details, see HTTP Live Streaming (HLS).
  • Streaming Media Encryption - You can now add encryption to specific content to enhance your digital rights management (DRM) security. The Sonos player and your service exchange security information with getMediaURI for streaming tracks, or with the new getContentKey for HTTP live streaming (HLS). For details, see Encrypting Content for Digital Rights Management (DRM).
  • Reporting - See the Reporting overview and the Status Reporting APIs for details on the following new features:
    • The paused status was added to reportPlayStatus for resumable content.
    • Players will now send reportPlaySeconds requests after a song has played for at least one second and at a specified interval (by default, about every 60 seconds).
    • Players will send setPlayedSeconds requests to report the number of milliseconds a song has played.
    • An <offsetMillis> parameter was added to the above three APIs (only sent for resumable content).
    • Players can also send a context ID for the above three API to provide information about where the track was playing from (if you enable this capability flag).
  • Security - See TLS/SSL Security for details on the following:
    • As of version 6.3, Sonos now supports TLS version 1.1 and TLS version 1.2 of Transport Layer Security. Some buggy TLS 1.0 servers may have problems with TLS 1.2 ClientHello messages.
    • The list of Certificate Authority certificates trusted by Sonos products has been updated.
    • Updates have been done to the tests Sonos runs against your service to ensure that your service supports our certificate security requirements.
  • getMetadata - Resumable content and HLS required updates to getMetadata.
  • getExtendedMetadata - As of version 6.3, Sonos players call getExtendedMetadata with any <itemType>.
  • The Sonos Music API WSDL and the Python Self-Test Suite have been updated.
  • When users add multiple accounts, they will set up a name for their account. This used to be called the "nickname" for the account, now it is simply called the "name" of the account. See What is Multiple Account Support in the FAQ for details about multiple accounts.
  • A new document describes the entire process of integrating with Sonos. See Integrating a Music Service with Sonos to understand the phases a partner goes through from starting development to a GA release of a music service on Sonos. 
  • Added a note in reportPlayStatus that other play statuses are forthcoming in future releases. Be sure to develop your implementation so that you handle them or ignore them, but don't fail on them.
  • Audio Formats - updated with the AAC codec profiles that we support and HLS support information.
  • getExtendedMetadata - we recommend that you add support for these requests on program and playlist itemTypes as these will be used in an upcoming release.
  • getMetadata - be sure that string types that will display to the user such as title, artist, and album do not include newlines ("/n").
  • Digital Asset Guideline Overview - do not use SVG <text> elements in your line art because they can cause display problems in the Sonos app.
  • Universal search - now you can display search requests from multiple libraries on your service.
  • customSD - described the following new capabilities:
    • Include SMAPI context headers with all requests.
    • Requires Device Certificate.
    • Include Zone Player IDs in credentials header.
    • Add play context to reporting.
  • Getting Started: Requests and Responses - you can now get time zone context from players and controllers in the SOAP header.
  • Getting Started: Authentication - deprecated <deviceId> and documented new sub-elements of the <credentials> element.
  • Glossary - updates to deviceId, household, and player definitions.
  • setPlayedSeconds - you can receive the context from where a track was added with the <contextId> sub-element.
  • reportPlaySeconds - you can set the length of time to poll for this report by returning an <interval>. You can also receive the context with <contextId>.
  • reportPlayStatus - You can receive context with <contextId>.
  • Customizing hero view - you can customize lines and thumbnails for child elements in the hero view.
  • Customizing the first container - you can customize the appearance of the first container of your music service (the page users see when they first browse into your service).
  • Customizing Item Display: Overview - updated description of hero view.
  • Customized Info View - described how to change the "Start Radio" string.
  • Updates to TLS/SSL Security Overview page:
    • Removed RC4 cipher requirements as they are insecure.
    • Added future requirements.
    • Added GeoTrust Primary Certification Authority.
    • Added descriptions of SSL tests in Python Self-Test Suite.
  • In getLastUpdate, return pollInterval to set the amount of time that the player should wait before polling again. Download the updated WSDL or see the documentation link above for details.
  • No new features for SMAPI developers.
  • You can customize how the Sonos controller app displays items using display types.
  • The XML string file and presentation map URLs should not exceed 64 characters. See Strings and Localization and SMAPI Presentation Maps for details.
  • The follwing new fields were added to getMetadata: containsFavorite, isFavorite, and displayType. See the getMetadata documentation for details.
  • Read about how to implement custom radio in the Customized Info View section.
5.3.2, 5.3.1, 5.3


Software version and build numbers

Our software release version numbers consist of a major number followed by one or many minor release numbers separated by periods. For example, "6.3.2". You can find the latest release version on the Sonos software release page, or by clicking a link in the first column of the table above.

Our build numbering scheme is:


Usually these are all numbers, but sometimes <buildNumber> includes letters. In this documentation, we sometimes omit the period and hyphen when referring to build numbers.

Adding New Features in Beta

As we continue to develop SMAPI, we add new features in updated WSDLs. You can implement these features during beta releases for testing, so that you can turn them on during the general availability release. If we are offering a beta, you'll be able to download the WSDL below.

To implement a new feature when it is in beta:

  1. Download the Sonos WSDL (Beta) (link not available when there is no beta).
  2. Rename it to Sonos.wsdl.
  3. Replace the WSDL in your current implementation with this one.
  4. Download the Python Self-Test Suite (if you haven't already) and replace the WSDL in the smapi\content\workflow folder with this one.
  5. Add the feature using the new elements in the WSDL.

To implement a new feature after it has been released, add the feature as documented.