Sonos Music API - Glossary

Sonos Music API - Glossary

The following terminology is used to describe components of the Sonos system and the Sonos Music APIs.

container - an object containing a group of items potentially including both single elements and other containers. Containers are similar to folders or directories in file systems; they serve to create hierarchical trees and to keep like items together. Both playlists and albums are containers that contain track items.

controller - the software provided by Sonos to control music from Sonos players. Controllers are available for Windows, Macintosh, iOS devices, and Android devices.

device - any piece of hardware used as part of the Sonos system. Most devices are players, but Sonos also supports other types of devices that do not directly interact with SMAPI.

device ID - The device ID is an identifier equivalent to a Sonos device registered by an authenticated user when they set up their household. This identifier can change, depending on the devices in a user's household. This is deprecated; your service can ignore it.

deviceLink - Sonos recommends using app or browser authentication, but existing DeviceLink implementations will continue to work. DeviceLink is a two-step authentication method that first generates a code for the requesting household then generates a user-specific token to uniquely identify the user within the household when that user logs in to the service via a link embedding the code from the first step. This token is then supplied with all subsequent API calls as the user identification. User tokens can be generated with a time limit if desired and the music service generating the tokens may choose to allow Sonos to refresh expired tokens automatically or to require users to reauthenticate with the service when the token expires. OAuth 2.0 is completely compatible with deviceLink and may be used to generate and verify the requested tokens.

group - a set of linked players capable of playing the same music synchronously. Groups can consist of one or several players within the same household; each household can support up to 32 groups. Groups are defined and manipulated from a Sonos controller. SMAPI does not generally care about groups or how players are grouped together.

household - a distinct house, apartment, office, store, or hotel room where Sonos has been installed. A household consists of a network of players that can be controlled and grouped or ungrouped from a controller. A single physical location may have more than one household defined in Sonos. A household cannot contain more than 32 devices each of which must be on the same IP subnet. Each household has a unique household ID. Household IDs are a central part of the deviceLink authentication process. The <householdId> element is typically used to hold this value in SMAPI calls. The household ID is set up automatically when a household is created and will only change with a factory reset; typically a sequence of API calls from a user will all use the same household ID.

ID – an identifier of a specific element or set of elements of the system. Sonos uses a variety of IDs to represent different elements of the system. Some IDs represent physical locations or hardware, some represent users or user activity, and some represent items within a music service. The most common IDs are household IDs, device IDs, and item IDs.

item - an object representing a specific thing or set of things being requested by a Sonos controller or returned by a Sonos music service. Containers are also items. The specific item varies in context and may be a track, an artist, a search category, an album, or any number of other things. Each item has an item ID to uniquely identify it within the system. The <id> element is typically used to hold an item ID in SMAPI calls. Once set, the ID of a particular item should not be changed. However, the value of an <id> element with API calls is likely to change repeatedly as new content is requested and returned.

parent ID - The parent ID is used only within the context of playlists and allows users to have a tree of playlists rather than flat playlist files all sitting in the playlist root. For example, a user could define a folk playlist folder and then have traditional, modern, and singer-songwriter playlists underneath folk. In this case, the ID of the folk playlist folder is the parent ID of the three playlists. The <parentId> element is typically used to hold a parent ID in SMAPI calls. The value of a <parentId> element should map to a valid item ID and is likely to change repeatedly as new content is requested and returned.

playera Sonos product that enables music to play (PLAY:1®, PLAY:3®, PLAY:5®, PLAYBAR®, CONNECT™, and CONNECT:AMP™).

seed ID - The seed ID is used to indicate the ID of a track to automatically add to a new playlist (the user is seeding the playlist with that track). The <seedId> element is typically used to hold a seed ID in SMAPI calls. The value of a <seedId> element should map to a valid item ID and is likely to change repeatedly as new content is requested and returned.

session ID - Sonos recommends using app or browser authentication, but supports existing implementations that use session-based user logins. 

user ID - There is no specific element or concept of user IDs in SMAPI itself, but it is assumed that each user is represented by some sort of identifier within your music service. The OAuth token or session ID associated with calls made by authenticated users should be mapped to that user ID in your service.

update ID - Update IDs are not currently used in SMAPI but are defined for a few endpoints and reserved for future use. You may ignore any <updateId> elements you see while exploring the API.

update token - an identifier that indicates the last time either catalog content or a user’s personal content (favorites, likes, ratings, etc.) was modified. This functions much like an eTag, providing a way for client controllers to determine if they need to refresh their content or have the most current stuff available.