Sonos Music API - Getting Started Guide

How Sonos players work

Sonos players are the core components in the Sonos sound platform. Players contain your service's SMAPI client. The following Sonos products are players:

  • PLAY:1
  • PLAY:3
  • PLAY:5
  • Sonos One

Sonos products such as the BOOST or SUB are not considered to be players. The BOOST cannot play media at all, and the SUB can only play media when bonded to a player.

Players do many things, most importantly they play media. Media is playable content such as a radio stream, programmed radio, or content a user selects on-demand. Media can be streamed from an online music service or from a library on a local network.

Sonos players forward media to other Sonos players, receive commands, relay state, control other players, temporarily buffer content, index a user's local music library, and can upgrade when new firmware is available. The Sonos One can also take voice commands.

Sonos players can communicate with many different entities. The Sonos app can talk to players. Third-party apps, media servers, and the cloud can all talk to players.

How we make your service available to players

Before we can make your service available on Sonos, we need to validate it. See Integrating a Music Service with Sonos for details about what you need to do to get your service ready for a beta and then a general release on Sonos. 

When your service is ready for a beta release, we will add it to an online service catalog that Sonos players poll. The catalog stores information you give us in the version manager, such as the technical configuration and the countries where your service is available. When your service is in this catalog, it will be available for listeners to add to their Sonos systems depending on the location that they registered their Sonos system to and its firmware. If a listener registered their Sonos system in a country where your service isn’t available, they won’t be able to add it to their Sonos system. Similarly, if your service on Sonos requires a newer firmware version than a player is running, your service won’t be available to add. Listeners can update their firmware by updating their Sonos app and system. See How to update your Sonos system for details.

During the beta, your service is available to any listeners that meet its location and firmware requirements. We give your service the beta label in the Sonos app for iOS or Android and list it in the Sonos Labs container in Sonos apps for Mac or PC. This is to let users know that we are testing your service and everything might not be working perfectly yet.

Note that Sonos players aren’t necessarily located in the countries where they have been registered. Users may move after registering their players or provide incorrect information when registering. You may want to implement some form of Geo-IP filtering to ensure that tracks are only streamed in the proper locations.

Until your service is ready for a beta or general release, you can add it to a player for testing using the custom service descriptor. See Test your service on Sonos for details. 

How players stream Media

Sonos players stream media from your service using HTTP requests. Your service provides media URIs for players to call in your SMAPI getMediaURI responses. The number of seconds of audio a player can buffer varies depending on encoding and bitrate.  Certain encodings, such as WAV or FLAC, have a high bitrate; requiring many more bytes to generate a second of audio.  This results in some files having more audio buffered than others. 

After a player gets the URI for a track from your getMediaURI response, it sends an HTTP GET request to retrieve the track. For some encodings (such as MP3 and MP4), the player may need to send multiple requests during buffering. Subsequent requests will include a Range header so the player can request a specific portion of data. Players also send Range headers to request specific parts of a track in situations where a listener is scrubbing (seeking to a time within a track). It is important that your service doesn’t change this URI partway through a player’s requests or the request will fail. Once a player finishes buffering a track, it will get the URI for the next song (via your getMediaURI response) and begin buffering that before it has finished playing the current track.

See Streaming basics for details.

Media comes as tracks, programmed radio, and streaming radio

Sonos players can stream three different categories of audio. These are tracks, programmed radio, and streaming radio.

  • Tracks are finite-length audio files.
  • Programmed radio is a continuous stream of tracks, often based around a specific artist or genre. It usually has limited seeking capabilities and users can't select specific tracks to play. Services may limit the number of songs that a listener can skip.
  • Streaming radio is a continuous stream of audio being provided (an infinite-length audio file) where the listener has no seeking capabilities. Streaming radio is very much like traditional broadcast radio but over the internet. 

Streaming radio with non-HLS M3U playlists

Your service can stream radio by providing Sonos with a non-HLS M3U playlist. Sonos players will stream from an M3U playlist in order, switching to the next stream when a stream fails. When a player switches streams, it will not know in advance if the new stream is a lower or higher bitrate or a different codec. 

For details about streaming with HLS, see HTTP Live Streaming (HLS).