Sonos Music API - Getting Started Guide


SMAPI offers several ways to personalize the listening experience for users. Three of the most common personalization features are playlists, ratings, and favorites. In general, Sonos expects your SMAPI service to implement the same personalization features that are available via other client interfaces to your music service.


Sonos allows users to construct their personal playlists containing individual tracks offered by your on-demand music service. Users may have multiple playlists and may organize their playlists into folders.

SMAPI provides API calls to create, delete, rename, and reorder playlists. All playlists must be organized underneath a main playlists container at the root level of your hierarchy. Playlists must be retrievable using getMetadata("playlists") and subsequent getMetadata calls following the hierarchy as desired from there.

More information about playlists and the related API calls is available in Adding your playlists to Sonos


Ratings allow users to provide feedback about the tracks they like or dislike within your smart radio or on demand music service. SMAPI supports multiple types of ratings; the specifics are defined by your service configuration. Most rating options are boolean states of individual icons (represented by rating values 0 and 1). However, multiple icons can be used together to form a set of related rating states (such as a thumbs up/thumbs down pair or a set of stars that collectively determine a numerical rating).

How ratings affect the music playing experience is up to your service, but there is an expectation that smart radio stations will give preference of some sort to tracks that users rate positively and avoid or lower the frequency of tracks that they rate down in some fashion. In addition, your service may choose to immediately skip to the next track when a user gives the current track a negative rating.

More information about ratings and how to implement them is available in the Implementing listener ratings


Favorites allow users to indicate that a particular track or album is one they particularly like and would be happy to hear again in the future. If your service implements favorites, users are given an option to add each track or album to their favorites list and also to remove existing favorites from the list. 

More information about favorites and how to implement them is available in Integrating your service favorites with Sonos.

Keeping Personalized Content in Sync

Your music service must handle the case of a user using both Sonos and other mechanisms for playing content from your service. Any personalization changes made in one client should be reflected in the other client with as short of a delay as possible. In Sonos, getLastUpdate is used to signal that the Sonos app should invalidate the cached personalized content and fetch it again.