Version 12 is the first release of Sonos S2. Sonos S2 is a new app and operating system (OS) that powers the next generation of products and experiences. See Sonos S2 Overview for details. The first-generation system has been named S1. See Components and interfaces for more details about the Sonos platform.

The Sonos API works on both S1 and S2 systems, but there are limitations if a listener has a split system comprising products in both systems. For example, listeners can’t group players in an S1 system with players in an S2 system. See Set up separate S1 and S2 Sonos systems for details.

If you operate a content service, you may need to make changes later to support how each version of the Sonos OS displays your content. We’ll describe these in future blog posts. For example, getAppLink requires different callback URLs depending on the app. See the link for details.

Control API updates

The Control API includes the following features:

• Set the queueAction in loadFavorite and loadPlaylist to control where to put the content in the Sonos queue, for example, at the end of the queue, replace the queue, or other actions. See the links for details.
• Updated playback policies. Removed canSkipWhilePaused as it was never implemented, added pauseAtEndOfQueue, refreshAuthWhilePaused, pauseOnDuck, and skipsRemaining. See Playback policy list for details.
• Fixed Create Token example. Should be {YourBase64EncodedClientId:SecretGoesHere} (with colon), not {Base64 clientid and secret} (without colon). See the link for details.
• Clarified that you may see undocumented parameters in responses and events and that your integration should not fail if it encounters them. See Control for details.
• Clarified the difference between Sonos favorites and content service favorites. Sonos favorites include any content favorited by listeners in the Sonos app. Content services can also expose their favorites in their integrations in the Sonos app. See favorites for details.
• You can disable the progress bar if your integration uses a cloud queue. To do so, use a durationMillis value of 0 (zero). See Playback Objects for details.
• Known issue: Sonos does not currently support the getPlaylist command.

SMAPI updates

SMAPI includes the following features and updates:

• Updated the maximum URI lengths for HLS. See Maximum supported URI lengths in HTTP Live Streaming (HLS) for details.
• You can define the default display types for item types. This can help simplify your integration, as well as provide a consistent browse experience for users. See Define display type for item type in Configure display types for details.
• Removed the requirement to support RFC 5746. See Security for details.
• Clarified that Sonos authentication errors have different requirements than general errors. See Handle auth errors and Error handling for details.
• Added some guidance about how Sonos sends multiple getMediaURI requests and best practices for handling them. See Handling multiple getMediaURI requests in getMediaURI for details.
• Clarified that the Sonos app displays the search results in the order you specify in the presentation map. See Add search for details.
• Added best practices for using strings for accessibility features. See Add strings for accessibility in Strings and localization for details.
• Added new callback URLs to getAppLink for the S1 and S2 apps. See link for details.
• Bug fix: The Sonos app was using the title key as the title for generic actions instead of using the string value of the title key. This resulted in a string like “ADD_FAVORITES” instead of “Add to Favorites.” The code now tries to perform a lookup on the title key and will fallback safely. See Add favorites and title under relatedActions in SMAPI object types for details.

Details on API credentials and events

We received a question asking about the Authorize credentials and for more details about how to Subscribe to events. This should help clarify those topics.

Your application uses the API key and secret (your credentials), not the customer, therefore you should not create a unique API key and secret for each customer. You create multiple API key and secret pairs, for example, if you wish to have one for your development app and one for your production app. There’s no maximum limit to the number of credentials you can create. 

Event callbacks

See Subscribe for the format of an event. Each event contains headers and a body describing exactly which customer household ID, namespace, and other values the event is for. Your app should receive all events on a single base callback URL and parse out the headers to understand which customer the event is for. The purpose of secondary callback URLs is not to specify one per customer, but to specify a backup for redundancy purposes. We do not currently support a redirect URI to a local device or app, for example, a redirect URI that opens an app on a device.

See Release notes for Sonos software for customer-facing features.

The Control API includes the following features as of version 11.0:

• You can now cancel audio clips with cancelAudioClip.
• The audioClip object shows the available error codes and states.
  • Removed ERROR_AUDIO_CLIP_DO_NOT_DISTURB, ERROR_AUDIO_CLIP_CANCEL,
    and ERROR_AUDIO_CLIP_EXPIRE. Added ERROR_AUDIO_CLIP_PAUSE_CONTENT_FAILED.
  • Removed PENDING audioClipState, added ERROR.
• We recommend that you provide the User-Agent HTTP Header to all requests as a best practice so that Sonos knows who is sending the request. See Send HTTP headers; send parameters in the body in the Control documentation for details.
• Made it easier to find the latest Cloud Queue API version supported. See the Cloud Queue API page for details.
• Clarified the difference between loadStreamUrl and loadCloudQueue. Use loadStreamUrl to load a live stream that does not end. Use loadCloudQueue to load a set list of tracks or a playlist.
• You no longer need to send the X-Sonos-API-Key in Control API request headers to the Sonos cloud. The access token is enough to authenticate your request. The API-key is also known as your client credentials. Use these credentials to authenticate with users. Once your app authenticates with the user, use the access token in all of your requests. See Authorize for details.
• A detailed description of the lifetime of an event subscription. Subscriptions last for a period of three days. Sonos cleans up most subscriptions 30 seconds after the target has gone, except for subscriptions to the groups and favorites namespaces. See Subscribe for details.
• Users can request that Sonos remove connections to your connected product to deactivate it on their Sonos system. Sonos will add a user interface for this at a later date.
• If your app sends invalid player IDs in the createGroup or setGroupMembers commands, or the modifyGroupMembers command to add players to the group, it sends an ERROR_INVALID_PARAMETER error with the list of invalid player IDs. See globalError and groups for details.

SMAPI updates

SMAPI includes the following features and updates:

• We moved all of the documentation from Sonos Labs to the developer portal. See Content Service: Add Features for a list of the features and links to how to add them. If you’re a new content service partner, start developing your integration by following the Content Service: Get Started.
• Sonos deprecated the python Self-Test for content partners. When you submit your service for review, add “N/A” in the Self-Test configuration file and Self-Test Summary Report HTML file fields. See C: Quality assurance and performance in the Submit your service documentation for details.
• If you have a manifest file URL, enter it in the String Resource XML File field. See Submit your service for details.
• Users can add programmed radio tracks or stations to favorites. See How favorites work in Add programmed radio for details.
• We no longer send getLastUpdate requests if the user is not browsing your content. This should limit the amount of requests sent to your server.

SMAPI documentation fixes and updates:

• Set up image substitution for album art section in Add album art had malformed sample XML code.
• Fixed typo in Create lists. The albumsList itemType should be albumList. Also changed the albumsList displayType example to listOfAlbums to eliminate confusion with itemType.
• Typo in SMAPI object types and Add playlists. The renamable property should be renameable.
• In Add reporting, clarified that endpoints require the version number somewhere in the URL, the example uses v2.1, and partners can also use the latest version of the cloud queue.

SMAPI known issues:

• There’s a bug in how the Sonos app displays string text for the title entry in an action under relatedActions. See Add actions for details. As a workaround, bypass the strings file and hard code the text that you want to display for the action. Sonos correctly replaces strings for relatedBrowse and relatedText actions.
• Sonos players don’t respect the AuthTokenExpired Fault for getMediaURI when the mimeType is audio/m3u8.

See Release notes for Sonos software for customer-facing features.

Updates in Sonos version 10.4:

• Users can disable connected products from the Sonos app. See Users can remove connections in Authorize for details. We’re rolling this out in stages, so you may not see it in your Sonos app.
• Audio Clip works on the Sonos One, Amp, Play:5 (gen 2), Beam, One SL, Move, as well as the SYMFONISK table lamp with WiFi and SYMFONISK WiFi bookshelf speakers. See the audioClip namespace for details.
• When testing your service integration, you can enter the non-SSL endpoint, such as an IP address on your local network in the Secure Endpoint URL on the Custom service descriptor page when adding your service to a player. But you’ll need a secure endpoint in order to submit your application; the endpoint must be a valid hostname that matches the certificate. See the Test your service on Sonos with Custom SD section in Test your service for details.
• Fixed typos in Subscribe examples. In the Subscribe to events section, line 2 was missing /api/ segment. Correct line should be:
  Host: api.ws.sonos.com/control/api/v1
• The httpAuthorization parameter in loadAudioClip can now handle a value up to 512 bytes. Previously it was limited to 128 bytes.
• We’re in the process of consolidating all of our content service partner documentation onto this portal. We added the following documentation:  Supported audio formats, HTTP Live Streaming (HLS), Add pagination, Add play/shuffle all, Add search, Strings and localization.

Known issues:

• The Sonos Play:1 does not support audio clips. This release introduced a bug that includes the AUDIO_CLIP capability in the player object for the Play:1.

See Release notes for Sonos software for customer-facing features.

In Sonos version 10.3, we added the following:

• Add podcasts — a guide on how to add podcasts to Sonos. Once you’ve created your SMAPI integration, you can follow the guidelines on this page to add podcasts.
• SMAPI object types — added the podcast object types to this page, including new mediaCollection, mediaMetadata, and trackMetadata elements.
  • For mediaCollection: removed book & bookId, added isEphemeral, podcast, podcastId, positionInformation, producer, producerId, releaseDate, semanticType, and total elements.
  • For mediaMetadata: updated string maximum values, added semanticType, isEphemeral, positionInformation, and releaseDate elements, added program to itemType.
  • For trackMetadata, added: producer, producerId, podcast, podcastId, host, and hostId.
  • For positionInformation: added isCompleted.
• Add programmed radio — Clarified that you can use notifyUserIntent but it’s not required for skip enforcement. See the Set up skip enforcement section for details.
• favorites & playlists namespaces —  Recommended that you use these two namespaces together if using them. The Sonos app combines the results of these two namespaces in different swimlanes on the “My Sonos” tab. If you don’t use these together, Sonos listeners may think some of their content is missing in your integration.
• audioClip namespace — Audio Clip will work on the upcoming SYMFONISK table lamp with WiFi speaker and SYMFONISK WiFi bookshelf speaker created in collaboration with IKEA in the next software release.
• Error handling — Added a table of default errors to the Default error messages section.
• Control — Added description of householdId:
  

  Each household is represented by a householdId. The householdId is stable with one exception. The value will change if players are moved to a different network. For example, if a user moves some players from a household to a different network, the players that were moved will use a different householdId. If all of the players in a household are moved to a different network, the householdId will remain the same.

• groups namespace — clarified operation of commands:
  

  When creating or modifying groups, the group info response only includes the list of players in the final group. It doesn’t include a flag to show whether the changes match the original desired group or not. This could lead to partial successes.

  Additionally, this command may trigger significant player-to-player communication over the LAN. In some cases, you may not receive a response.

  As a best practice, check the final set of players returned by the command, either in the group info response, or by getting a list of players in the group.

Fixed bugs

• Sonos didn’t send a groupVolume event for volume changes initiated by Airplay. This has been fixed.

See Release notes for Sonos software for customer-facing features.

In Sonos version 10.2, we added the following:

• Add programmed radio — With programmed radio, you can offer a generated sequence of tracks to listeners. You can generate tracks based on user preferences. Listeners can steer content by rating or skipping tracks. You can set polices to control the number of times listeners can skip content. You can also include ads that listeners cannot skip. You can offer programmed radio that follows Digital Millennium Copyright Act (DMCA) requirements.
• Add reporting — Sonos players can send reports to your service for certain actions. These reports may be useful to comply with monetization policies from content owners or to meet DMCA requirements. This replaces SMAPI reporting.
• Download the Sonos WSDL — Added the Sonos WSDL to the SOAP requests and responses section. The Sonos Web Services Description Language (WSDL) file defines the SOAP endpoints, requests, and responses used by Sonos players and apps. Content Service partners can use the WSDL for development and testing. It was previously hosted on Sonos Labs.
• trackList.program — Added this new container type to identify a programmed list of tracks, such as on a programmed radio station. Programmed radio periodically updates the finite list of tracks to give the perception of an infinite list of tracks. See Add programmed radio for details.
• Submit your service — Instead of a “beta” phase, we have a “preview” phase that better describes the release process for Content Service partners.
• Bug fix: On the playerSettings page, we incorrectly stated that the Beam supports monoMode. It is not the Beam that supports this mode, but the Amp.

See Release notes for Sonos software for customer-facing features.

In Sonos version 10.1:

• Players with API version 1.11.1 support fragmented MP4.
• In POST /timePlayed, players use the reportId to send unique UUIDs for the currently heard track.
• The playlistId, playlist id, favoriteId and favorite id values now have a maximum length of 36 bytes instead of 64 bytes.
• FIXED_VOLUME value added to capabilities array in the player object. Players with this capability support FIXED and PASS_THROUGH volume modes. See setPlayerSettings and the groups object for details.

See Release notes for Sonos software for customer-facing features.

We look forward to what you will build.

In Sonos version 10.0, you can now:

• Cancel audio clips with the cancelAudioClip command (edit: sorry, this is not yet implemented).
• Set the volume of audio clips sent in the loadAudioClip command.
• Pass a string in the Authorization header when fetching the streamUrl for an audio clip in the loadAudioClip command.
• Set the priority for an audio clip in the loadAudioClip command.
• Poll for metadata changes with the getMetadataStatus command.
• getOptions and setOptions for nightMode and enhanceDialog for homeTheater.
• Find out if a player is ducking audio using the isDucking playbackStatus.
• Read about other available playback actions in the playbackStatus.
• Get started using the Sonos Music API, if you’re a content service provider who wants to integrate with Sonos.

We don’t return the resource_owner in the Create Token response, so we removed it from the documentation.

See Release notes for Sonos software for customer-facing features.

We hope you enjoy these changes and look forward to seeing what you build with them.

In Sonos version 9.3, we added subscribe and unsubscribe commands to the audioClip namespace and made some updates. We also added a settings namespace. See Release notes for Sonos software for customer-facing features.

Audio clip

We made the following updates:

• You can subscribe and unsubscribe to the audioClip namespace to receive audioClipStatus events.
• The status parameter in the audioClip object lets you know whether the clip is scheduled for playback, is currently playing, has played, or has been dismissed.

Settings

You can use the setPlayerSettings command to change playerSettings. For example:

• Change the volumeMode to PASS_THROUGH a Sonos device such as the Amp or Connect.
• Change the volumeScalingFactor to limit the maximum volume for Sonos players.
• Turn on monoMode for a pair of Sonos players.
• Disable WiFi on a Sonos player (wifiDisable).

Soon you will be able to use getPlayerSettings to see the current values for these settings. Watch this space for an update on when you can use this command.

We hope you enjoy these changes and look forward to seeing what you build with them!