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.

New features in versions 10.5, 10.6, & 11.0

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.

Sonos version 10.4 platform 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 formatsHTTP Live Streaming (HLS)Add paginationAdd play/shuffle allAdd searchStrings 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.

Sonos version 10.3 API update

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 isEphemeralpodcast, podcastId, positionInformation, producer, producerId, releaseDatesemanticType, and total elements.
    • For mediaMetadata: updated string maximum values, added semanticTypeisEphemeral, positionInformation, and releaseDate elements, added program to itemType.
    • For trackMetadata, added: producer, producerIdpodcast, podcastIdhost, 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.

Known Issues

  • SMAPI sample server — Runs on Java SE Development Kit 8. May not work with other versions of Java.

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

Sonos version 10.2 API update

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.

Sonos version 10.1 API update

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.

Sonos version 10.0 API update

In Sonos version 10.0, you can now:

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.

Sonos version 9.3 API update

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:

Note: This namespace is experimental. Some of the functionality may not yet work as documented. For example, the AUDIO_CLIP capability in the player object has not yet been released, so you won’t be able to tell which players support audio clips and which do not. Currently, the only players that support audio clips are the Sonos One and the Beam. See the groups object for details about capabilities.

We’ll let you know when we’ve added more functionality. Keep an eye on this blog for details.


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!

The Real Industry + Sonos Challenge

This fall Sonos partnered with Real Industry to challenge university students at University of Washington and local Boston area schools to answer the following question: How do we design or build an experience that delivers the right sound, at the right moment, into people’s lives?

We were excited to have the opportunity to work with some great students in two different cities. We understand that an open platform provides the tools to build experiences that we cannot even think of. With this challenge, what better way to tap into the minds of college students! These college students really blew us away with the different ideas and integrations they planned and built. Their enthusiasm is contagious and we left the workshop with some fire in our belly to continue our work on the Sound Platform.

At Sonos, we are aiming to meet with more developers in person to gauge your interest and to make sure you have the opportunity to meet Matt and I. We enjoy engaging with the developer community and we want to make working with the Sound Platform as enjoyable as possible. In the end, we are all here to make some great experiences on Sonos.

The Challenge

Matt and I, along with several Sonos colleagues, were honored to chat to students in these locations about the Sound Platform and the experiences they can build to solve real problems. Many students took on the challenge to answer: “How do we design or build an experience that delivers the right sound, at the right moment, into peoples lives?” While brainstorming in the room, there were many ideas thrown around such as making the morning routine easier and more enjoyable, sharing music when discovering through Sonos, announcing class schedules over Sonos, different party mode features and the list goes on!

We wanted the students to be as creative as possible with their integrations. Not only were we judging their coding expertise, we challenged them to think of the development process as a whole. From ideation and product management to design and research. In the end, all of the students who submitted really impressed us with their innovation and thoughtful thinking.

The Result

Several Sonos colleagues got together to review the submissions at the end of October to determine the winner. We had a lot of interesting submissions that we really enjoyed looking over. We were particularly interested in how well students pitched their ideas to us, explain the problem they were solving and in the end demo what they built.

A few students jumped straight into their integrations, giving us details of what they built and the tools utilized to build it. Where they fell short is they didn’t give us an indication of what problem they were solving or who would benefit from their integration. Although they had some great ideas, the challenge was to build an integration that fit into people’s lives, they fell short on providing some of these details.

Many students jumped straight to interviewing their peers and family members, they thought through the UI and the user flow, these are all great characteristics of a good experience. In the end, their storytelling was much more impactful when presenting their working demo. After considering all of the options, it was a unanimous vote to pick the following teams for their projects. Not only did these students build great experiences, they really thought about the problem they were solving and delivered well.

OurSound

At Tufts University, a group of three students: Chris Markus, Electrical Engineering, Katie Elliott, Electrical Engineering and Allie Lam, Applied Math/Music Technology created OurSound.

The team took on the challenge of eliminating the awkwardness of picking a song that everyone likes at a party or even in the office. Their app plays the perfect music automatically based on music libraries of everyone in the room and mood filters the host sets to play directly to Sonos. The OurSound team utilized Google’s Flutter SDK, Spotify API and Sonos API to rate danceability, vocality and familiarity to play a playlist for everyone in the room to enjoy. Check out their winning video below:

Feel.io

At University of Washington, a group of 5 students: Xu Yan, Computer Science, Zoe Zou, Master in Science and Technology Innovation, Hal Zhang, Electrical Engineering, Michael Radenbaugh, Electrical Engineering and Padraic Casserly, Technology Innovation, Bio-Chemistry created Feel.io.

As the team stated, “Humming or singing is just a feeling set to music.” By saying the wake word Feel.io, the artificial intelligence algorithm will listen to your humming, go through the music library in the cloud and play your particular song or a closely matched genre. The Feel.io team utilized snowboy Hotword Detection, Latent factor analysis system and Sonos API to play music on your speakers. Take a look at their winning video below:

Interested in starting your career at Sonos?

We offer a range of student internships and full-time opportunities. At Sonos, you are empowered to take charge of your own career, applying your education to innovate boldly and collaborate with some of the greatest in the industry. Begin your career at a place where your voice matters in helping us further our mission to listen and live better. Summer intern opportunities will be posted by January 1, 2019. To learn more about life at Sonos, visit us here

Nancy Hernandez – Developer Advocate – Currently listening to Despicable by grandson

Sonos on IFTTT: How We Did It and Why It Matters

Sonos has always had a focus on creating meaningful partnerships. From music services to voice to our Works With Sonos certification program, we want to listen to our favorite audio content whenever and wherever. The launch of the Sonos sound platform in September opened up a world of new possibilities, with three main goals in mind – creating new opportunities for our partners, making our platform more open for developers, and providing listeners with natural and personal experiences. Unfortunately, if someone doesn’t know how to code, it doesn’t matter how open or useful our platform is – that’s where IFTTT comes in.

IFTTT is such a natural fit for us, and our users have been asking for us to integrate with them for years. The launch of our open cloud-based Control API made this a possibility – and we wanted to get this out as soon as possible. A Sonos service on IFTTT lines up with so many of our values at Sonos, allowing us to integrate with hundreds of services, including Nest, Philips Hue, Ring, GE Smart Appliances, allowing our listeners to use their Sonos in completely new and groundbreaking ways.

If you’re unfamiliar with IFTTT, here’s a quick rundown of what it is: IFTTT has integrated with hundreds of different products, websites and content providers, called services. They have millions of users using their product today that allow you to create applets, that consist of an “if” portion referred to as a trigger and a “then” portion, or action. For example, if someone rings my doorbell, then tweet “Somebody’s at my door”. With IFTTT, anyone can create incredibly useful additions to their system which would be complicated to code from the ground up.

How We Did It

Essentially, IFTTT acts as a translator between our API and IFTTT users. In order to make this possible, we created IFTTT-specific endpoints in order to feed info from your Sonos system to IFTTT (to build lists of players & favorites, for example), and from IFTTT to your system. For example, this command which resumes playback on a group called RINCON_00012345678001400:0 may look something like this.

In IFTTT, a similar request may look like this.

 

We’ve done this for a total of 11 actions for our beta release. Our most popular actions are Play Favorite, which allows listeners to play a preselected Sonos favorite on a chosen group, and Pause, which pauses a specified player, or group.

Challenges

What is the best way to show how powerful our API is while maintaining simplicity and ease of use? The biggest challenges we faced stemmed from the understanding that IFTTT users don’t have as much freedom as a developer working directly with our APIs. We needed to make sure to balance having enough options when enabling actions without overcomplicating.

In this process, we made a few particularly difficult decisions.

One issue we wanted to address was an “Everywhere” option within our IFTTT applets. In our desktop and mobile controllers, we have the option to instantly group all speakers. For our IFTTT integration, we needed to think carefully about when our listeners would utilize this functionality. We could make room grouping its own Action, or add it in as an option within certain Actions. For example, it made total sense to group all speakers when pausing, but would anyone want to resume all of their speakers at one time? We decided to have three options for room grouping – one single specified player, the group containing the specified player, or everywhere.

While we believe having room grouping options (as opposed to Actions) is a better implementation, we quickly realized that we approached it from the wrong angle. The current process in creating an Applet to play a favorite playlist on all your speakers is:

  • IF (Trigger)
  • [whatever trigger you want to use e.g. location, button]
  • THEN (Action)
    • Play Favorite
      1. What favorite do you want to play?
      2. Where do you want to play? (Kitchen, Dining Room, Bedroom)
      3. Include grouped rooms? (this room only, include grouped rooms, everywhere)

If you’re trying to play everywhere, you first have to select a single speaker, and we are considering moving the Everywhere option to the “Where do you want to play?” selection (Kitchen, Dining Room, Bedroom, everywhere).

Volume controls also fall into a similar category. We currently have Volume (Up, Down, Set, Mute, and Unmute) as standalone actions, but a Set Volume option in the Play Favorite Action could be useful for routines, alarms, or an instant party. IFTTT has a great feedback mechanism built in, and we’ve been reading and understanding how Sonos users would connect their system to their smart home.

All in all, we’re incredibly proud to have launched our Sonos service on IFTTT. Our goal is to make this the best experience possible, and trying to best understand what it means for Sonos to be the sound of the connected home.

Why We’re Excited

Sonos is focused on helping our listeners to listen better. Our open sound platform allows integrations that were previously unimaginable, and allows anyone to build and create novel experiences. Kind of. We understand “anyone” is actually limited to people who have the time, skill, and motivation. With IFTTT, listeners can easily choose and enable exactly what they believe will enhance their Sonos experience.

Our plan is to keep the IFTTT experience parallel to our APIs on our platform. Our new playlists API makes it possible to pick and play any of your Sonos playlists. And our new audioClip API allows for short audio clips and notifications to be played over your Sonos system. Imagine your Sonos speakers being able to notify you when your laundry is complete, when someone rings your doorbell, or even read aloud tweets you’re mentioned in. As our platform continues to grow and improve, our IFTTT integration will too. We’re excited to see what you’ll build! Check out our favorite IFTTT applets here:

Start Sonos When I Come Home
Start My Sonos Favorite Using the Button Widget
Reduce the Volume When Someone Rings My Ring Doorbell

Seth Goldstein – Senior Development Manager-Cloud Platform – Currently listening to Hands Up Head Down by Sure Sure
Tarush Mohanti – Product Manager-Cloud Platform – Currently listening to Final Credits by Midland