Adding Content Service features

You can integrate with Sonos to:

Display your content metadata in apps that connect to the Sonos system.
Playback your content on Sonos.
Control Sonos speakers.

These words, content, playback, and control, best describe the main features of the APIs that you can use to integrate with Sonos.

Content

You can access content on any device connected to the Sonos system. For example, on the Sonos app on iOS, Android, or desktop devices; hardware controls on speakers; and hardware devices created by third-party Connected Home partners. Many of these devices may display your content metadata, such as track titles, artist names, or album art. Use the Content features of the Sonos Music API (SMAPI) to display your content metadata on these control devices.

The Content features of SMAPI also make your content browsable. The Sonos system always knows what's playing and can share that information out to other devices, no matter what they are. These features lay out the structure and contents of your catalog. They provide details on the music, podcasts, audiobooks, and other sounds available for playback.

You must implement the Content features of SMAPI in order to integrate with Sonos.

Authenticate accounts

Sonos players authenticate users with your service so that you know which user accounts are playing back content and to ensure the security of your licensed or proprietary content. Authentication is also useful to offer personalized content to your users. If you don't serve any licensed content or if you want anyone to access your content without an account, you can also integrate with Sonos without enabling authentication. See Add authentication for details.

Sonos can play multiple streams from the same account in different rooms. Your service should support this as it provides the best experience for Sonos listeners.

Browse and search

Listeners find music in different ways, for example, by exploring content by artist, genre, or other category. You can add your own browse hierarchy to enable listeners to explore the content offered by your service. SMAPI also supports search and alphabetical scrolling functionality. See Content on Sonos for details.

Display content metadata

SMAPI enables you to display your content in the Sonos app with its associated metadata, such as album, artist, and track name for songs, or show, host, and description for podcasts. It enables partners who display what's playing on Sonos to attribute your content to your service.

Personalize content

Many different people in the household can use Sonos. One person can play their own content through their own Sonos app without having to use the same account as someone else in their household. These multiple accounts work seamlessly in the Sonos app. Listeners can personalize content with favorites, playlists, and ratings. For example, Sonos listeners can:

Pin their favorite items to My Sonos in the Sonos app. They can also add items to Sonos playlists that will show up on My Sonos. Sonos offers these actions to listeners by default. You can also add more actions for listeners. See Add actions for details.
Add items to favorites or playlists on your service. See Add playlists and Add favorites for details.
Rate tracks on your service within the Sonos app. See Add ratings for details.

Playback

Naturally, the main reason you'd want to integrate with Sonos is to playback your content. The Playback APIs enable you to do this. They are central to every Sonos experience. Sonos players also use the Playback APIs to report playback status to your service. For example, the length of time that Sonos played the track. The Playback APIs work with the Content features of SMAPI to offer a complete Sonos experience to users. With these APIs, you can choose content and play it back on Sonos, across multiple control surfaces.

Playback content

Sonos is not a music service; it serves content from other sources, such as your service. Sonos players do not store content except for short snip-its during buffering. Players support multiple formats, including MP3s using HTTP streaming, Windows Media Audio using MMS, and others. See Supported audio formats and Streaming basics for details.

Sonos also supports many different types of content, including individual tracks that you can select and queue up on demand, streaming radio, and spoken word such as audiobooks and podcasts. Sonos also supports policy-based programmed radio.

Create policy-based programmed radio

Players can support dynamic, policy-based programmed radio with playback policies. This enables you to create playback policies to enforce rules on content playback, for example, if you want to enforce the rules of the Digital Millennium Copyright Act (DMCA). It also enables you to create programmed radio stations that react to user preferences. For example, create streaming content that changes based on how a user rated the current playing song. If they liked it, use it to seed other content. If they don't, skip the song, throw away the rest of the content, and seed the rest of the content based on whatever they liked before. See Add programmed radio for details.

Report playback duration and status

Sonos players can report an assortment of data back to your service, including the total duration of playback, time since the track began playback, total aggregate time for which a player played a track, and cumulative number of seconds for which a player played a track.

You can also choose to receive reports about user events, such as when a user chose to stop or pause playback or skip tracks. You can receive a report when an account has been successfully added to a Sonos system. And when there have been radio stream failures. See Add reporting for details.

Control

You can also offer the ability to control Sonos speakers within your own app. This lets you keep users within the custom experience that you've designed for them in your native app, while also letting them take advantage of the powerful audio quality of the Sonos Home Sound System. Once you've created your content and playback solution, you can add the Control API features to add Sonos capabilities to your app.

Discover and manage groups

Players always work in groups, even if there's only one player in the group, so the first thing that your app must do is discover all of the players and groups available in a household. Once you've connected to a player, you can continue to discover and manage groups using the groups namespace (a namespace describes a set of related commands and events).

Display content metadata

Just as you can use the content features of SMAPI to display your content metadata in the Sonos app, you can use the Control API to send content metadata to other control apps in the Sonos system. You can use the same IDs for content that you use in SMAPI, and leverage your SMAPI implementation to get content metadata.

Since Sonos can play content from many different sources, we stress the importance of attributing the sources of content. Our partners must display this information if they have an interface. You can send this metadata, such as the artist, album, and name for a song, the author of a book, or the name of a podcast, to Sonos to display it on other control devices.

Control playback and volume

Your native app can control sound playback. For example, you can start, stop, or pause sound on Sonos. You can skip from one song, podcast show, or audiobook chapter to another. Or you can seek within the content. You can also set the position of the playhead to start playing at a certain time within the content. This enables you to keep your users within your native app experience while also enabling them to directly control your content on Sonos speakers.

The control features have limits — for example, you could have a playback policy that doesn't allow songs to be skipped. In that case, users would not be able to skip songs, and partners would not be able to bypass this policy.

Your integration can also control the volume of groups or individual players.