New features in versions 11.1, 11.2 (S1), & 12.0 (S2)

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.