Sonos Music API - Getting Started Guide

SMAPI Overview

The Sonos Music API (SMAPI) is based on the SOAP Version 1.1 specification. A client can access SOAP services over HTTP 1.1 and HTTPS, and can optionally include support for client side certificates. The service is described using WSDL (Web Services Description Language) and XSD (XML Schema Definition). For more information on these standards, see www.w3c.org/2002/ws. 

Example HTTP Header

POST /AcmeMusic/ServiceTest1.asmx
HTTP/1.1 CONNECTION: close
HOST: 10.0.2.112:8080
CONTENT-LENGTH: 335
CONTENT-TYPE: text/xml; charset="utf-8"
SOAPACTION: http://www.sonos.com/Services/1.1#getMetadata

A SMAPI client must support handling response sent encoded gzip compression. To return the message result using gzip compression, the CONTENT-ENCODING header would be specified as:

CONTENT-ENCODING: gzip

Metadata and Collections – General Information

One of the primary functions of the music service is to supply metadata about artists, albums, composers, playlists, genres, programmed stations, and tracks.  As such, the service will define a metadata schema with the following minimum features:

Artist

  • Artist ID unique within the service
  • Artist Name

Album

  • Album ID unique within the service
  • Album Name

Composer

  • Composer ID unique within the service
  • Composer Name

Playlist

  • Playlist ID unique within the service
  • Playlist Name

Genre

  • Genre ID unique within the service
  • Genre Name

Programmed Station

  • Programmed Station ID unique within the service
  • Programmed Station Name

Track

  • Track ID unique within the service
  • Track Title
  • Artist Name who recorded the track (for a track on a "Various Artists" album, this is the "track artist", not "Various Artists")
  • Album Name from which the track came
  • Track Duration (in seconds)
  • URL of album art image

IDs should be alphanumeric strings of a reasonable length (128 characters max, 64 preferable).  These IDs must not change once they are established.  For example, if Track IDs are renumbered, playlists that the user has created within their client application will be irreparably broken.

The service will also frequently return collections of the above metadata items:

  • Whenever a collection is to be returned, the API call that requests the collection must support partial enumeration, in particular an "index" and a "count" parameter.  This allows the clients to request, for example, items 0-99 in a long collection with thousands of items, by passing index = 0 and count= 100.  If insufficient items exist in the overall collection to satisfy the "Requested Count", all items up to the end of the collection must be returned.  The "Starting Index" is 0-based; that is, the first item in the collection is item 0.
  • Whenever the server returns a collection, the response must include the "Total Number of Items" in the collection.  This is the total number of items in the overall collection, not the number of items returned.  For example, when requesting items 0-19 of a 100 item collection, and when requesting items 20-39, Total Number of Items should be 100 in both responses.

When a collection is sorted alphabetically, the sort must use a straight case-insensitive string comparison on the title of the items.  We have found that editorially defined sorts that don't necessarily use the first letter of the word (e.g. Michael Jackson sorts with the 'J's) are visually confusing when the user must scroll through a long collection. When a collection is sorted alphabetically, it must also be possible to issue the getScrollIndices message on that collection.

A Note about SMAPI IDs

Please note that all SMAPI IDs are URL-encoded in our firmware. Keep in mind all strings in our firmware use a NULL character ('\0') to terminate the string. You must take these caveats into account when your IDs are approaching the character limit described in our documentation.

For example, this contrived SMAPI ID:

my_service:track:track_id_with_umläut_goes_here

will be url-encoded in firmware and stored as:

my_service%3Atrack%3Atrack_id_with_uml%C3%A4ut_goes_here

With the NULL terminator, the total length of that string will be 57 characters as opposed to the 47 characters originally passed in the SOAP Envelope.