Components and interfaces

The Sonos home sound system allows users to access and play music wirelessly from a variety of sources throughout their home. The system consists of:

Players: Speakers, organized into groups that can play audio. Users can group players to play the same audio in a synchronized way. Or users can play different things on different players at the same time.
Sonos app: An app to control the Sonos system. The Sonos app is available for mobile devices, tablets, and computers.
Music services: Services (such as yours) that process requests to browse, play, rate music, and offer other features.

The diagram below shows the Sonos platform's clients, services, servers and other components and how they interact by using the Sonos APIs.

Components

The Sonos system can include the following components.

Sonos app

The Sonos app is a Sonos Music API (SMAPI) client to your SMAPI service. It uses SMAPI to connect the user to your content catalog metadata (songs, albums, artists, and so on). Users add your service in the Sonos app.

Once, added, they can browse or search your catalog and play your content on Sonos. Sonos uses SMAPI to make multiple requests for more information from your service.

Listeners also use the Sonos app to control the Sonos system, such as to add or group Sonos players.

Sonos players

Sonos players are the core components in the Sonos sound platform. The following Sonos products are players:

Arc
Five
Move
One
One SL
Beam
Port
Amp

See the Sonos website for details.

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. See Supported audio content for details. Media can be streamed from an online music service or from a library on a local network. Sonos players are always identified in groups, even if a group has only one player. All players in a group play the same audio, synchronized.

Sonos players can communicate with many different entities including:

Other players
The Sonos app
SMAPI and Cloud Queue API services from your integration
Third-party apps and devices
Media servers

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.The Sonos app can talk to players.

Players are SMAPI clients that request playback information from your SMAPI service. Although the Sonos app (via user input) may provide the initial play request, the player then communicates with your service for playback details. Players are also Cloud Queue API clients that request playback information from your Cloud Queue service. Sonos players also host the Control API service where apps and devices communicate as clients to control players. Finally, once a player gets a URI for content, it is a Media client that connects directly to the Media server to stream the content.

Partner content service

As the Content Service provider, you host the SMAPI service and Cloud Queue API service to send content and playback information to the Sonos system.

See Key requirements to see what you need to begin your content service integration.

Partner content app

To control Sonos players, your app and other partner apps become Control API clients. Your app authenticates with listener households through the Sonos Control API Cloud service. See Control Sonos Players for details.

After you've built your Sonos content service integration, see Play audio to learn how to use your SMAPI integration with a cloud queue.

Partner servers

Your partner servers provide a host for your audio content (Media server) as well as hosting for your SMAPI and Cloud Queue API services. The media server could be part of a larger content delivery network (CDN) that serves media to Sonos players and other devices.

S2 platform

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. 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.

Application programming interfaces

The Sonos system supports the following programming interfaces.

Sonos Music API (SMAPI)

The Sonos Music API (SMAPI) is designed to allow Sonos to communicate with your music service. It is a platform independent, language independent Web services API built on Simple Object Access Protocol (SOAP). Sonos is the client of this API, sending requests via SMAPI. You implement servers to service those requests, allowing your customers to access their own personal accounts at your services via Sonos apps and hardware. This is different from the usual setup where you as the customer would use an API to build a client interface to a server maintained by the API maintainer.

Sonos Control API

The Sonos Control API provides your app or devices the ability to directly control Sonos players. Note that your content service must be integrated with Sonos before you can control Sonos players.

Sonos Cloud Queue API

The Sonos Cloud Queue API provides a queue of audio tracks in the cloud that can be loaded and played in a playback session on a group of players. The Sonos cloud queue is described more in Play audio.