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.

This guide takes you through creating a programmed radio service. You’ll learn:

  • Prerequisites to offering a programmed radio service
  • How to set up player endpoints using a manifest file
  • How Sonos players use the endpoints
  • How to set up skip enforcement
  • How to set up ratings
  • How to send music to listeners using a cloud queue

A sequence diagram at the beginning of each section shows the piece of the experience you’ll be building. Each section expands on the sequence diagram to create a fuller picture. At the end of the guide, you can review the complete diagram. To start, it’s pretty slim, with nothing but your devices:

Devices sequence diagram

Note: If the sequence diagrams are too hard to read, save them or open them in a new window to zoom and view.

This guide uses “http://localhost:3000” as the base URL of the cloud queue server. Replace it with a publicly accessible URL in your own implementation.


Here’s a key of some common terms used throughout:

  • Cloud queue—a cloud queue server, which is a list of content hosted by your service in the cloud.
  • Manifest file—a JSON manifest file containing URLs to endpoints for the Sonos player to access.
  • Player—Sonos player. See Components and interfaces for details.
  • Pmap—an XML presentation map file containing presentation styles for your content in Sonos.
  • Container—any group of tracks, such as an album, radio, or playlist. Programmed radio can use the trackList.program or station container type, depending on whether you want to enable listeners to favorite tracks or the whole station. See below for details.

Table of contents

Prerequisites and set up

Before you begin, you’ll need to:

  1. Set up a SMAPI server with object IDs. See Content Service: Get Started for details.
  2. Set up account matching. See Account matching for details.

Add a manifest file with endpoints for players to access

The first part of setting up a cloud queue server is creating a manifest for your service. This manifest is a one-stop-shop for all of your music service needs. It lists the location of your cloud queue endpoints and other resources. The player uses the manifest file to get these resources. Here’s an example:

The key endpoints here are radio, used for your radio endpoint, and presentationMap, used for ratings. See Customize display to read more about the presentation map.

Use the reporting endpoint to receive reports about SMAPI content playback. We’ll describe this in more detail in a future guide.

Use the strings endpoint to refer to the strings that the Sonos app presents to the user that are specific to your service, such as error strings. See Strings and Localization to read more about the strings file.

Set up a player with Custom SD

Once you have your manifest file, test it on your Sonos system using the custom service descriptor (Custom SD) website on the player. To access Custom SD on a player, go to http://<playerIP>:1400/customSD. See Test your service on Sonos with Custom SD for details.

Be sure to add the URI to the manifest file in the appropriate field and select the Support manifest file capability. Fill out the rest of the fields and press Submit to apply the changes. If everything worked properly, you should be able to see your service as an available service to add on the household.

Note that Custom SD only allows your service access to the specific local household to which you added it, not to all Sonos households. If you change the URI after you’ve submitted it, update the version number so that the player refreshes it.

Add cloud queue endpoints

In its most basic form, a cloud queue server contains four endpoints:

  1. GET /context
  2. GET /version
  3. POST /timePlayed
  4. GET /itemWindow

To get started, set up a basic HTTP server using your favorite language, such as with Express and Node.js or Typescript, Django and Python, or Ruby on Rails, with those 4 endpoints. Before going any further, you should make sure those endpoints are all functional, so that they can be the framework for your cloud queue server. Here’s an example using Express and Node.js:

How the player uses endpoints

The Sonos player uses the endpoint URL in the manifest and the container ID to generate the request URL. For example, with the following parameters:

If the Sonos listener started music using the Sonos app, the player would access the following endpoint URL to get the context:

The player would access the following endpoint URL to get an item window:

These endpoints are specific to each playlist or container ID. As a best practice, you should build your implementation so it can handle a flexible URL with the container ID as a parameter in it.

Add a context endpoint

The following section goes over the sequence shown below:

Context endpoint sequence diagram

The /context endpoint provides information about the state of the container, the container’s playback policies and associated metadata, and reporting options. Without the context, the player has no information about how to play what you are telling it to play. Note that playback policies are immutable for the context, regardless of version. This means that in order to change them, you must reload the cloud queue with the loadCloudQueue command. See the Loading Cloud Queue section below for details.

Here’s an example context request by the player:

Here’s an example cloud queue response:

See GET /context for more details about the /context endpoint and requirements.


As part of your context, you need to have a container object, which describes the collection of tracks your queue is representing.

For example, the container in the player’s response to GET /context was:

Players require the name and id keys and values.

The name describes the name of the container. The type of the container allows the player to dissect your context and item windows correctly. See the container playback object for more details about containers.

The id is the unique identifier for the container. See the MusicObjectId playback object for details.

If you want listeners to be able to play your containers using the Sonos app via SMAPI, you’ll need to add a MusicObjectId to your container so that your SMAPI implementation knows what container the user wants to play. See Load a cloud queue using a manifest file below for details.

Playback Policies

Playback policies describe the policies for playback of a container or a track. There are two different kinds of playback policies, policies for playback contexts, used in containers and policies for individual items. See Set playback policies to learn more. Because context policies are immutable, most of the policy work for your radio implementation will be done at the item level.

Item-level playback policies always take precedence over context-level policies. Skip enforcement relies heavily on item playback policies. Read more about skip enforcement in the section below.

Add a version endpoint

The player polls the /version endpoint frequently to discover whether there has been a change to your cloud queue server. For example, reordering of tracks or updates to the state of container types, metadata, or playback policies. If there has been a change, it will send a new /context or /itemWindow request. To determine which information the player should update, there are two version fields your cloud queue should return:

  • contextVersion—indicates a change in container metadata, such as the name of the playlist.
  • queueVersion—indicates a change in the contents of the queue, such as order of tracks.

Here’s a sample request:

Here’s a sample response. For example, if you made a change to the context, such as changing a container name, but didn’t change the queue, you would update the contextVersion in your response:

By examining the versions and taking note of the change, the player knows to fetch a new context from your /context endpoint. See GET /version for more details.

Add an itemWindow endpoint

This section goes over adding an /itemWindow endpoint:

itemWindow sequence diagram

Players use the /itemWindow endpoint to discover what to play. The endpoint returns a window of content, such as radio, playlists, and other content. See GET /itemWindow for more details. Players also use the /itemWindow to learn the skip enforcement policies for each item or container of items. See Set up skip enforcement, below, for details.

Here’s a sample request:

And a sample response:

Your cloud queue should return 10 items for optimal buffering. Each item contains:

  • A unique ID
  • A track with all of the relevant metadata. See the track playback object for details.
  • The playback policies specific to that track. See Playback policy list for details. Note that the playback policies for a specific track always take precedence over the playback policies from the container.
  • An optional itemId. If this exists and it’s not empty, be sure to return an item window that contains that item ID.

See the item playback object for more details about items.

Tracks vs. Advertisements

An advertisement, or ad, is a track with specific playback policies to prevent skipping and other actions.

Here’s an example of some typical track playback policies, assuming the user has some skips remaining:

Here’s an example of ad playback policies:

Note that the canSkip playback policy should always be false for an ad, so that the user can’t skip it. Additionally, you can optionally have isVisible set to false so that Sonos doesn’t event the metadata for an ad to other listeners. See Playback Object policies for more details.

If the context playback policies allow for canSkipBack, then the ad should also overwrite canSkipBack with: "canSkipBack": false.


Now that the player has a window of tracks from the /itemWindow, it still needs to know which track in the window to play. The windowPlayhead identifies the track and the location within the track to play. This allows for continuity of control because your service can keep track of the listener location within the content and start playback on a different device if the listener pauses it and resumes it elsewhere. The windowPlayhead enables the listener to immediately begin listening from where they left off in the content. This makes their listening experience smoother and more consistent. Be sure that if you have a windowPlayhead, it is pointing towards a track that is in the windowPlayhead that you are sending.

If the player requested an item window without a windowPlayhead, it plays the items in the window from the beginning.


The listener is in the middle of listening to “Paradise By The Dashboard Lights” by Meat Loaf on your app on their mobile device. To be precise, they’re 33,123 milliseconds into the content. They want to continue listening on Sonos. They use the Control API features in your app to choose a Sonos player to continue the music. The Sonos player asks for the context and an item window. You’ve included their position in the windowPlayhead object in your item window. The Sonos player resumes playing the song at this position. Here’s the itemWindow:

The windowPlayhead is a PositionInformation playback object. See the PositionInformation playback object for more details about windowPlayhead.

Add a timePlayed endpoint

Now you can add a time played endpoint:

timePlayed sequence diagram

Players report track usage to the /timePlayed endpoint. You can use this information to keep track of how long each track has played, for example, to pay royalties. Players post asynchronously to the /timePlayed endpoint. Do not rely on them for playback information or skip enforcement.

There are two types of reports:

  1. Update. The player sends you updates on a regular basis. When you return context information to the player in a /context endpoint response, you can specify a periodicIntervalMillis value for the player to POST a /timePlayed report with the specified regularity. Additionally, the player POSTs an initial update /timePlayed report near the beginning of a track.
  2. Final. The player sends a final report every time the listener skips or finishes a track. Don’t use this value to implement skip enforcement. See below for how to implement skip enforcement.

Example /timePlayed report:

Note: When you enable the “support manifest file” capability, you must implement /timePlayed for all type of on-demand content (radio, audiobooks, on-demand tracks, and streams). Sonos players will no longer send SMAPI report requests. See Add reporting for details. See Add capabilities for details about capabilities.

Set up skip enforcement

To enable skip enforcement, your context playback policies must include the following:

The canSkip playback policy forces the player to fetch a new /itemWindow on each skip. You don’t need the notifyUserIntent playback policy to get this information. But if you want to get notified about user interactions, you can add it. The notifyUserIntent playback policy sends a GET /itemWindow request with a reason that shows the user action. See playback policy list for details.

You must include the limitedSkipsState object in all /itemWindow responses. See Set playback policies for details about providing listeners with a limited ability to skip tracks.

Here’s an example:

Let’s assume Meat Loaf Radio has a skip limit of 2. Here’s a sequence diagram of the requests and responses:

Skip enforcement sequence diagram

There are many different cases for skip enforcement. Here is each case, with what the limitedSkipsState in the /itemWindow response should look like. Keep in mind that if the canSkip policy is true in the context, you will get a new /itemWindow request on each skip.

One skip remaining

Here’s the /itemWindow response with one skip remaining:

No skips remaining, but allow one more skip

Here’s the /itemWindow response if the listener has no more skips left but you want to allow one more skip before sending a SKIP_LIMIT_REACHED errorCode:

No skips remaining

Here’s the /itemWindow response, if there are no skips remaining:

Replenish the number of skips available

Naturally, you eventually want to replenish the number of skips you want to allow in your container after some time. This is where you can update the queue version in your /version endpoint response to notify the player of changes to the queue. The player polls your /version endpoint frequently, so when you want to replenish the skip limit, change the queue version. When the player detects this change via the /version endpoint, it fetches a new /itemWindow:

Skip replenish sequence diagram

Additionally, every time the player requests a new /itemWindow is an opportunity to replenish skips.

If your cloud queue server enables listeners to skip tracks after a negative rating, such as a skip on a thumbs down, and the user has run out of skips, don’t return a windowPlayhead object. Sonos speakers honor the windowPlayhead position even if the skipLimitReached is true in the limitedSkipsState.


You can enable listeners to rate tracks to steer your programmed radio solution to offer songs that listeners want to hear, while reducing songs that they don’t want to hear. The rating response is almost identical to the itemWindow response. See Add ratings for details.

If the player wants to notify the cloud queue server about a rating, it will post to the rating endpoint using the following syntax:

For example:

The rating object has a type, for example, THUMBSUP or STAR. It also has a state, such as RATED or UNRATED.

For example, if the user gave a THUMBSDOWN to Track id=CQTrack:1, the player would send the following:

Your cloud queue would respond with:

The itemId in the URL is the item that the user is rating, while the itemId in the payload is the id of the track that is currently being heard. If these IDs are different, such as if the user is rating at the end of the track, make sure that you do not return a windowPlayhead in the response, as it will cause an interruption in the playback.

Additionally, always make sure that the your response to  GET /itemWindow is centered around the currently heard track ID.

How the Sonos app displays ratings

The Sonos app uses the presentation map to display ratings. Here’s an example of a presentation map for ratings:

Note the state and type attributes. The following sequence diagram shows how the presentation map above links with the rating command:

Rating sequence diagram

Using ratings to skip a track

To skip a track after the listener has rated it negatively, for example with a THUMBSDOWN rating, simply return a windowPlayhead with the updated itemId in the returned response of the rating post. The player will immediately begin playing the new track.

Do not include a windowPlayhead object in your returned window items if you do not want the player to change what it’s playing.

Removing a rating

Here’s an example of how a listener could remove the rating from a track, to return it to the unrated state:

Remove rating sequence diagram

How the Sonos app loads a cloud queue

When you set up the speaker with Custom SD as described earlier, you included an Endpoint URL and Secure Endpoint URL containing the location of your SMAPI server. For simplicity’s sake, you should use the same URL for your cloud queue server that you used for your SMAPI server.

When a listener browses to a track on the Sonos app and plays it, the player creates its own playback session and makes its own calls to the cloud queue server, using the links described in your manifest. Each item in the returned itemWindow has an objectId and a serviceId, which the player uses to get the mediaUri, metadata, and extendedMetadata.

The sequence diagram below shows the steps taken by the app to load a cloud queue:

Load cloud queue sequence diagram

How favorites work

Use the trackList.program or station container type to set the behavior of the favorites feature for programmed radio. See Add favorites for details about this feature.

  • Use trackList.program to let listeners add individual tracks to their favorites in My Sonos.
  • Use station to let listeners add the station to their favorites in My Sonos. If you use the station container type, you must also support the Extended Metadata for radios capability. See Add capabilities for details.

Sequence diagram overview

Here’s the full sequence diagram from the sections above:

Sequence diagram review