Sonos API

SOAP over HTTP

The Sonos app communicates to the zone players using a local API. This API is based on SOAP over HTTP; each zone player provides a web server (on port 1400) to receive API requests. The request and response payloads consist of XML, enclosed in SOAP envelopes. The zone players in a household communicate with each other using the same API.

As far as I know, there's no formal documentation of the Sonos API available online, but it is fully described on the zone player itself, in line with the Universal Plug & Play (UPnP) standard, see Universal Plug and Play below.

Homebridge ZP uses this API as well; ZpClient provides a JavaScript interface to this API, at least to the part that's relevant to Homebridge ZP. The zp command-line utility provides a JSON-based command-line interface to this API, issue zp --help for more info. ZpXmlParser takes care of the XML to JavaScript translation of the response and notification payloads.

The API provides request/response calls (using POST) to control a zone player, and event notifications (using NOTIFY) to report the state of a zone player. The zone players in a household sync their configurations (topology, music sources, favourites) using event notifications.

To receive event notifications, you need to setup a web server that accepts the NOTIFY command. The URI of this web server is passed to the zone player when subscribing (using SUBSCRIBE). The web server The Sonos app also implements such a web server. So do Homebridge ZP, and, when needed, zp. This web server is provided by ZpListener.

Diagnostics

The web server on a zone player also serves some diagnostics pages, see https://bsteiner.info/articles/hidden-sonos-interface. Unfortunately, this functionality has been reduced. The zone players no longer provide the debug page to show what subscriptions have been made. Also, the reboot feature has been disabled. Some other info is still available at http://x.x.x.x:1400/status and at http://x.x.x.x:1400/support/review.

Universal Plug and Play

Technically, a zone player follows the Universal Plug and Play (UPnP) protocol.

Discovery

Zone players are discovered using UPnP. To search for zone players, use:

$ npx upnp -z

To monitor zone player device announcements, use:

$ npx upnp -dz

Device Description

The UPnP device announcement contains a link to the device description, in /xml/device_description.xml, which lists the devices and services the zone player provides. Each zone player provides up to three devices: a ZonePlayer, a MediaServer, and a MediaRenderer. The MediaRenderer handles connecting to and playing music streams. The MediaServer provides a directory of available music streams, like your music library and favourites. The ZonePlayer handles the interaction with other zone players, setting up music services, and alarms.

To view the device description, translated to JSON, use:

$ zp -H xx.xx.xx.xx description

Services

Each device provides a number of services, described in the corresponding service control point definition (SCDP), in /xml/service1.xml. Each service provides a control endpoint, /device/service/Control for sending SOAP actions, and an event subscription endpoint, /device/service/Event for subscribing to event notifications. A controller needs to provide a web server to receive these event notifications.

To view the device description including the service control point definitions, translated to JSON, use:

$ zp -H xx.xx.xx.xx description -S

Like the Sonos app, Homebridge ZP subscribes to the zone players, to show real-time updates of the zone player state. It uses the following services:

Device	Service	Used for
ZonePlayer	AlarmClock	Managing alarms.
ZonePlayer	DeviceProperties	Managing LED and physical button lock state.
ZonePlayer	GroupManagement	Discovering zone groups.
ZonePlayer	ZoneGroupTopology	Discovering the topology (stereo pairs, home theatre setups).
MediaRenderer	AVTransport	Controlling the input per zone group, including joining/leaving groups.
MediaRenderer	GroupRenderingControl	Controlling volume per zone group.
MediaRenderer	RenderingControl	Controlling volume and equaliser settings per zone.
MediaServer	ContentDirectory	Discovering Sonos favourites.

To see which services by which zone players Homebridge ZP has subscribed to, look for a line in the Homebridge log:

[7/30/2019, 5:36:51 PM] [ZP] listening on http://0.0.0.0:57532/notify

and open that URL in your web browser on the server running Homebridge. If you use a web browser on a different host, replace 0.0.0.0 by the IP address of the server running Homebridge.

To see which SOAP actions Homebridge ZP sends to each zone player, and which events it receives, run Homebridge with debug mode enabled. The Log Level characteristic determines the level of detail of the debug messages issued:

Log Level	Description
1	List the calls made and responses and events received, but without any payload.
2	List the payload translated to JSON.
3	List the XML payload as sent to or received by the zone player.

For zp specify -D for log level 1, -DD for level 2, or -DDD for level 3.

To monitor the events a zone player issues, run:

$ zp -H xx.xx.xx.xx eventlog