Link Search Menu Expand Document

Unofficial Sonos Docs

Sonos api documentation Github Issues Sonos2mqtt Sonos cli Sonos typescript this library

Support me on Github Follow on Twitter

Sonos api documentation for the local UPNP api and a generator to generate clients and documentation based on service discovery

This library is in no way connected to Sonos. It’s just a set of text files to document a hidden and unsupported api.


Check-out the (generated) documentation about all the SONOS UPNP services

Manually documented

The sonos services have no documentation, that is way we manually created a documentation.json file. To easily add documentation to all services (that are generated with the generator). And it’s json so you can easily use it yourself.

This file has a documentation json schema which means VS Code will guide you when editing this file.

Update documentation

If you change the documentation file or if you did service discovery for a new device. You can update the documentation files with the following commands:

# Go to generation folder
cd generator/sonos-docs

# Generate intermediate file
npm run intermediate
# or ./bin/run combine --docsFile=../../docs/documentation.json  --folder=data

# Generate documentation
npm run docs
# or ./bin/run generate docs ../../docs


You can find the generator here and use it to generate your own Sonos client in your preferred language.

Device discovery files

You can use the generator to generate your own discovery files, but we also have the files available for download.

Player Discovery file(s)
Sonos Play:1 S2
Sonos Play:3 S2
Sonos Play:5 (old) S1
Sonos Play:5 (new) S2
Sonos Playbar S2
Sonos One S2
Sonos Beam S2
Sonos Roam S2
Sonos Sub S2

These files toghether with the documentation file, are combined to a extensive JSON file, that is used as an input for the generator.


The generator uses handlebars.js templates to generate the documentation/strong typed clients. Check-out the docs template as a sample to develop your own templates.

A template is a folder with a template.json file, that describes the template and specifies what templates should be used to either generate an index (all services in a single file), or a seperate file for each service. The template.json also has a json schema so VS Code will guide you when creating your own template.


If you have any questions or you want to show your Sonos integration. Please join us in the discussions tab on this repository.

Contributors ✨

All Contributors

Thanks goes to these wonderful people (emoji key):

This project follows the all-contributors specification. Contributions of any kind welcome!