Sonos Music API - Getting Started Guide

About this document

The SMAPI Getting Started Guide is designed to help you integrate your music service with Sonos using the Sonos Music API and makes certain assumptions about you as readers. We assume that you are a developer working with a music service. This guide explains what a music service is and the different options available to music services in SMAPI. It also provides basic information about the development process and requirements as well as the registration, validation, and launch processes at Sonos.


In order to understand this documentation, you must already know the following:

  1. XML - you should have a basic understanding of how XML works, how to insert information into a defined XML structure, and how to interpret requests received in XML
  2. XML Namespaces - you should understand what an XML namespace is, how to define XML namespaces, and how to reference them within XML structures
  3. Audio - you should know what the major types of audio file formats are, what codecs are and how to use them, how audio files store metadata, and other technical elements required to process and manipulate audio files.


This documentation does not assume the use of any particular programming language. However, you should be capable of interpreting HTTP requests and formatting HTTP responses in the language you choose to use. You should be able to serialize and deserialize data as well as manipulate, filter, and sort that data. Essentially, you are free to select any languages, frameworks, tools, and libraries so long as you can use them to fulfill the contract of the defined APIs.


Typographic Conventions

This book will use the following typographic conventions:

Typeface Meaning
[square brackets] indicates "square brackets" is a variable
<angle brackets> indicates "angle brackets" is an XML element
bold indicates "bold" is a literal value. not used in code or syntax
indicates "monospace" is code or syntax.
red text indicates "red text" is a link


In general, the expected values of variables will be explained after their use. However, several variables that are used repeatedly throughout this documentation are defined below to avoid duplication.


Common Variables

The following variables will be used throughout the entire document. They will not be redefined each time they are used.

Variable Meaning
[soap] the defined namespace prefix pointing to the public URI of the SOAP WSDL definitions (
[ns] the defined namespace prefix pointing to the public URI of the Sonos WSDL definitions (




Sonos uses a very specific set of terminology to describe its hardware, software, and API features. For instance, the term "player" refers to a speaker built by Sonos and not the software controlling it which is called a controller. For a list of terms you are expected to know and apply appropriately, please see the glossary.