Link Search Menu Expand Document


This library is hosted on Github, contributions are more then welcome.

  1. Fork library
  2. Install Pull
  3. Compile the library
  4. Run the tests
  5. Debugging
  6. Repository content
  7. Regenerate files
  8. Contributors ✨

Fork library

You should start by creating a fork. Or if you already had a fork sync the fork:

# Add the remote, call it "upstream": (only once)
git remote add upstream

# Fetch all the branches of that remote into remote-tracking branches,
# such as upstream/master:
git fetch upstream

# Make sure that you're on your master branch:
git checkout master

# Rewrite your master branch so that any commits of yours that
# aren't already in upstream/master are replayed on top of that
# other branch:
git rebase upstream/master

Install Pull

We like to use the Github pull application, to keep our beta branch and the forks up-to-date. You have to install this application yourself, but it will work automatically.

Compile the library

Before you can use this library is has to be compiled.

npm run install && npm run build

Run the tests

After changing something you should run the tests (as they are automatically run before your PR is accepted). Important code should be covered by tests, and is uploaded to

npm run test

or (to test against your actual device)

SONOS_HOST=192.168.x.x npm run test


This library has several VSCode tasks defined, be sure to create a .env file which is used in .vscode/launch.json file. If you open an example file and press F5 the example is run and you can set breakpoints in the sample code and in the TypeScript code.


You can also debug the tests.

This library makes use of node debug, if you want to see debug logs you can set the DEBUG environment variable to one of the following values. If you run the examples with the VSCode debug task, this variable is set to sonos:* so you should see all the logs.

Environment variable What will log
DEBUG=sonos:* See all debug logs.
DEBUG=sonos:device See all debug logs from the SonosDevice class.
DEBUG=sonos:service:* See all debug logs for all the various services (this is where most of the magic happens).
DEBUG=sonos:service:[service_name] See all debug logs for a specific service.
DEBUG=sonos:service:*:[ip] See all debug logs for all the various services for a single device (this is where most of the magic happens).
DEBUG=sonos:metadata See all debug logs for the metadata helper.

Repository content

  • docs/ These documentations
  • examples/ Several examples on how to use this library.
  • img/ Some static images used in the library
  • src/helpers/ Some useful typescript class, used everywhere in the library.
  • src/helpers/metadata-helper.ts This class will generate (actually guess) the needed metadata. Easily extended.
  • src/models/ Hand-crafted models used by the library.
  • src/services/ All automatic generated services.
  • src/services/base-service.ts Base service class, where all the generated services depend upon. This is where most of the magic happens.
  • src/index.ts Just an index to expose all classes that need to be exposed.
  • src/sonos-device-base.ts Generated SonosDeviceBase, to expose all the services in the derived class.
  • src/sonos-device-discovery.ts Async device discovery (by using SSDP, multicast)
  • src/sonos-device.ts SonosDevice class, this is the main entry point to control devices.
  • src/sonos-event-listener.ts Event listener, used for logical devices and for all sonos events.
  • src/sonos-manager.ts SonosManager class, logical devices.
  • tests/.. - All the tests, using the Jest framework.

Regenerate files

A lot of files in this library are generated, you can use the @svrooij/sonos-docs generator, with the template in the ./.generator/ts/ folder.

This will load the latest version of the manual documentation, and the latest version of the generated services. And at last regenerate the documentation and the services.

# Regenerate all services and documentation files.
npm run generate

Contributors ✨

All Contributors

Thanks goes to these wonderful people (emoji key):

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