Sonos Music API - Getting Started Guide

Feature Overview

The Sonos Music API specifies a web service implemented using SOAP. It has a very small surface area – a content provider can implement a service using only five methods (getMetadata, getExtendedMetadata, getMediaMetadata, getLastUpdate and getMediaURI).  The Sonos Music API covers the following functional areas: authentication, browsing and search, content transport and codecs, and user customization (or personalization). We also want to make sure that you offer a great user experience for your users and Sonos users alike.

Authentication

The Sonos Music API provides a way for devices to authenticate using a username and password if your music service requires a login to access your content hierarchy or streams. If you do not require any authentication, you can create a SMAPI implementation for anonymous access as well. See Implementing Authentication for more details.

Browsing and Search

Consumers like to explore content by artist, genre, etc. Service providers add their own browse hierarchy to allow consumers to explore the content offered by a music service. The Sonos Music API also supports optional search and alphabetical scrolling functionality.

Browsing is implemented by the getMetadata, getExtendedMetadata, getMediaMetadata and getLastUpdate methods. Search is implemented by the search method. Alphabetical scrolling is implemented by the getScrollIndices method.

Content Transport and Codecs

The Sonos Music API is agnostic about the transport used for delivering content and about how the content is encoded. Content can be delivered as MP3s using HTTP streaming, Windows Media Audio using MMS, etc.  Streaming is implemented by the getMediaURI method. See audio formats and streaming basics in the getting started guide for more details.

User Customization

Content providers may want to allow users to customize their content, such as by creating custom playlists.  The Sonos Music API supports this with general “item” management functions. Customization is implemented by the createItem and deleteItem methods. See the personalization section in the getting started guide for more details.

User Experience

You may have your own desktop application software, Web browser, or mobile app front end for users of your service (a "thick" client environment). SMAPI was created to enable your service to integrate in the "thin" client environment of the Sonos app. However, your users may access your service in both of these environments. For example, listeners may create playlists on their desktop client (a thick client) and then stream them using their device. Alternatively, a user may use a thick client to purchase content for playback on a device. These thick client experiences occur outside of SMAPI.

The final user experience of how a device interacts with a service is a collaborative design process.  Constraints and special requirements often arise around how the content hierarchy is presented, what codecs are supported, etc. These kinds of special needs are beyond the scope of an open specification such as the Sonos Music API. However, we want to make sure that you offer a similar experience in your thick client environment as in the SMAPI thin client environment. We will work with you during the application process to be sure that there is parity between the experiences offered in these environments.