{"id":18217422,"url":"https://github.com/ebaauw/homebridge-zp","last_synced_at":"2026-03-14T11:30:20.736Z","repository":{"id":44457127,"uuid":"74269470","full_name":"ebaauw/homebridge-zp","owner":"ebaauw","description":"Homebridge plugin for Sonos ZonePlayer","archived":false,"fork":false,"pushed_at":"2025-04-25T12:42:44.000Z","size":1647,"stargazers_count":246,"open_issues_count":6,"forks_count":20,"subscribers_count":16,"default_branch":"main","last_synced_at":"2025-04-25T12:52:06.497Z","etag":null,"topics":["homebridge-plugin","homekit","sonos","sonos-zoneplayer","zoneplayer"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ebaauw.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["ebaauw"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":["https://www.paypal.me/ebaauw/EUR"]}},"created_at":"2016-11-20T11:26:39.000Z","updated_at":"2025-04-25T12:42:01.000Z","dependencies_parsed_at":"2023-12-10T12:32:47.981Z","dependency_job_id":"a02335cb-cdfa-4c42-8631-e7a7e2c49003","html_url":"https://github.com/ebaauw/homebridge-zp","commit_stats":{"total_commits":858,"total_committers":7,"mean_commits":"122.57142857142857","dds":0.05710955710955712,"last_synced_commit":"bb5421deed91607b0a961986505251c1a0b6f8ca"},"previous_names":[],"tags_count":169,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ebaauw%2Fhomebridge-zp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ebaauw%2Fhomebridge-zp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ebaauw%2Fhomebridge-zp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ebaauw%2Fhomebridge-zp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ebaauw","download_url":"https://codeload.github.com/ebaauw/homebridge-zp/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254414456,"owners_count":22067262,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["homebridge-plugin","homekit","sonos","sonos-zoneplayer","zoneplayer"],"created_at":"2024-11-03T17:05:20.137Z","updated_at":"2026-01-12T15:04:53.623Z","avatar_url":"https://github.com/ebaauw.png","language":"JavaScript","funding_links":["https://github.com/sponsors/ebaauw","https://www.paypal.me/ebaauw/EUR"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"homebridge-zp.png\" height=\"200px\" alt=\"Homebridge ZP Logo\"\u003e\n\u003c/p\u003e\n\u003cspan align=\"center\"\u003e\n\n# Homebridge ZP\n[![Downloads](https://img.shields.io/npm/dt/homebridge-zp.svg)](https://www.npmjs.com/package/homebridge-zp)\n[![Version](https://img.shields.io/npm/v/homebridge-zp.svg)](https://www.npmjs.com/package/homebridge-zp)\n[![Homebridge Discord](https://img.shields.io/discord/432663330281226270?color=728ED5\u0026logo=discord\u0026label=discord)](https://discord.gg/3qFgFMk)\n[![verified-by-homebridge](https://badgen.net/badge/homebridge/verified/purple)](https://github.com/homebridge/homebridge/wiki/Verified-Plugins)\n\n[![GitHub issues](https://img.shields.io/github/issues/ebaauw/homebridge-zp)](https://github.com/ebaauw/homebridge-zp/issues)\n[![GitHub pull requests](https://img.shields.io/github/issues-pr/ebaauw/homebridge-zp)](https://github.com/ebaauw/homebridge-zp/pulls)\n[![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen)](https://standardjs.com)\n\n\u003c/span\u003e\n\n## Homebridge plugin for Sonos Zone Players\nCopyright © 2016-2026 Erik Baauw. All rights reserved.\n\nThis [Homebridge](https://github.com/homebridge/homebridge) plugin exposes [Sonos](http://www.sonos.com) zone players to Apple's [HomeKit](http://www.apple.com/ios/home/).\nIt provides the following features:\n- Automatic discovery of [Sonos zones](#zones), taking into account stereo pairs and home theatre setup;\n- Support for [Sonos groups](#groups), created through the Sonos app;\n- Control from HomeKit of play/pause, sleep timer, next/previous track, volume, and mute per Sonos group;\n- Control from HomeKit of input selection per group, from Sonos favourites and local sources, like Airplay, Line-In, TV;\n- Optional control from HomeKit of volume, mute, balance, bass, treble, loudness, and home theatre audio settings per Sonos zone;\n- Optional control from HomeKit for Sonos zones leaving Sonos groups, and for Sonos zones creating/joining one Sonos group;\n- Optional control from HomeKit to enable/disable Sonos alarms;\n- Real-time monitoring from HomeKit of state per Sonos group and, optionally, per Sonos zone.\nLike the Sonos app, Homebridge ZP subscribes to zone player events to receive notifications;\n- Optional control from HomeKit for the status LED and child lock per zone player.\nNote that Sonos doesn't support events for these, so Homebridge ZP cannot provide real-time monitoring for this;\n- Includes a [command-line tool](#command-line-tool), for controlling Sonos zone players and for troubleshooting.\n\n## Contents\n\n* [Prerequisites](#prerequisites)\n* [Zones](#zones)\n* [Groups](#groups)\n* [Speakers](#speakers)\n* [Command-Line Tool](#command-line-tool)\n* [Installation](#installation)\n* [Configuration](#configuration)\n* [Troubleshooting](#troubleshooting)\n* [Caveats](#caveats)\n\n### Prerequisites\nYou need a server to run Homebridge.\nThis can be anything running [Node.js](https://nodejs.org): from a Raspberry Pi, a NAS system, or an always-on PC running Linux, macOS, or Windows.\nSee the [Homebridge Wiki](https://github.com/homebridge/homebridge/wiki) for details.\nI run Homebridge ZP on a Raspberry Pi 3B+.\n\nTo interact with HomeKit, you need Siri or a HomeKit app on an iPhone, Apple Watch, iPad, iPod Touch, or Apple TV (4th generation or later).\nI recommend to use the latest released versions of iOS, watchOS, and tvOS.  \nPlease note that Siri and even Apple's [Home](https://support.apple.com/en-us/HT204893) app still provide only limited HomeKit support.\nTo use the full features of Homebridge Zp, you might want to check out some other HomeKit apps, like the [Eve](https://www.evehome.com/en/eve-app) app (free) or Matthias Hochgatterer's [Home+](https://hochgatterer.me/home/) app (paid).\n\nAs Sonos uses UPnP to discover the zone players, the server running Homebridge must be on the same subnet as your Sonos zone players.\nAs HomeKit uses Bonjour to discover Homebridge, the server running Homebridge must be on the same subnet as your iDevices running HomeKit.\nFor remote access and for HomeKit automations, you need to setup an Apple TV (4th generation or later), HomePod, or iPad as [home hub](https://support.apple.com/en-us/HT207057).\n\n### Zones\nHomebridge ZP creates an accessory per Sonos zone, named after the zone, e.g. *Living Room Sonos* for the *Living Room* zone.\nBy default, this accessory contains a single `Switch` service, with the same name as the accessory.  The standard `On` characteristic is used for play/pause control.\nAdditional characteristics control volume, select input, change track, etc.\nHowever, neither Apple's Home app nor Siri support these.\n\nTo control the volume from Apple's Home app and/or Siri, the type of the service, as well as the type of characteristic used for volume can be changed from `config.json`, see [**Configuration**](#configuration) and [issue #10](https://github.com/ebaauw/homebridge-zp/issues/10).\nNote that speaker support in Apple's Home app is based on the AirPlay2 protocol.\nDespite the \"HomeKit\" branding, technically, this has nothing to do with HomeKit.\nNo Homebridge plugin can expose speakers that look like AirPlay2 speakers in the Home app.\nAlso note that these Airplay2 speakers cannot be accessed by other HomeKit apps.\n\nWhen `\"tv\": true` is set in `config.json`, Homebridge ZP creates an additional *Television* accessory per zone, allowing input selection from Apple's Home app and control from the *Remote* widget.\nNote that Apple has imposed some technical restrictions on *Television* accessories:\n- They cannot be bridged; they need to be paired to HomeKit individually;\n- They cannot be accessed by HomeKit apps; only from Apple's Home app.\n\n### Groups\nWhen you combine multiple Sonos zones into one Sonos group, e.g. *Living Room* and *Kitchen*, the Sonos app shows them as a single room, like *Living Room + 1*, with shared control for play/pause, music source, and (group) volume and mute.\nWhen this group is broken, each zone forms a separate standalone group, containing only that zone.\nThe Sonos app shows each standalone group as a separate room, with separate control per room for play/pause, music source, and (zone) volume and mute.\n\nIf Homebridge ZP would mimic this behaviour, dynamically creating and deleting accessories for groups, HomeKit would lose the assignment to HomeKit rooms, groups, scenes, and automations, every time an accessory is deleted.\nConsequently, you would have to reconfigure HomeKit each time you group or ungroup Sonos zones.\n\nTo overcome this, Homebridge ZP creates an accessory and corresponding service for each Sonos zone.  This service actually controls the Sonos *group* the zone is in rather than the zone.\nWhen separated, the *Living Room Sonos* service controls the standalone *Living Room* group, consisting of only the *Living Room* zone; and the *Kitchen Sonos* service controls the standalone *Kitchen* group, consisting of only the *Kitchen* zone.\nWhen grouped, both the *Living Room Sonos* service and the *Kitchen Sonos* service control the multi-zone *Living Room + 1* group, containing both the *Living Room* and *Kitchen* zones.\nThe `Sonos Group` characteristic indicates which group the zone belongs to, by showing the name of the group coordinator zone, like: *Living Room*.\n\nSo, when grouped, adjusting the volume of the *Living Room Sonos* service changes the volume on both the *Living Room* and *Kitchen* zones. The same happens if you adjust the volume of the *Kitchen Sonos* service.\nWhen ungrouped, changing the volume of the *Living Room Sonos* accessory only affects the *Living Room* zone, and changing the volume of the *Kitchen Sonos* service only affects the the *Kitchen* zone.\n\n### Speakers\nTo change the volume of an individual zone in a multi-zone group, an additional `Volume` characteristic is needed for the zone, next to the `Volume` characteristic for the group.\nAs HomeKit doesn't support multiple characteristics of the same type per service, it actually requires an additional service.\nBy specifying `\"speakers\": true` in `config.json`, Homebridge ZP creates an additional *Speakers* service for each zone accessory, to control the individual zone.  This service is named after the zone as well, in our example: *Living Room Speakers*.\n\nThe *Speakers* service `On` characteristic is used to join, or leave a Sonos group.\n`On` is set, when the zone is a member of other zone's group.\nIt is cleared, when the zone is the coordinator of it's own group (either standalone or with other zones as member).\nBy setting `On`, the zone will join groups with the target coordinator.\nThe target coordinator is set using the `Sonos Coordinator` characteristic in the *Sonos* service.\nBy clearing `On`, the zone will leave the group and become coordinator of a standalone group.\n\nAdditional characteristics for `Volume`, `Mute`, `Bass`, `Treble`, `Loudness`, and home theatre audio control the corresponding zone attributes.\nNote that these are custom characteristics, except for `Volume`.  They might not be supported by all HomeKit apps, see [Caveats](#caveats).\n\nLike the *Sonos* service, the type of the *Speakers* service can be changed in `config.json` from the default `Switch`, as well as the type of characteristic used for volume, see [Configuration](#configuration).\n\n### Command-Line Tool\nHomebridge ZP includes a command-line tool, `zp`, to interact with your Sonos Zone Players from the command line.\nIt takes a `-h` or `--help` argument to provide a brief overview of its functionality and command-line arguments.\n\n### Installation\nTo install Homebridge ZP:\n- Follow the instructions on the [Homebridge Wiki](https://github.com/homebridge/homebridge/wiki) to install Node.js and Homebridge;\n- Install the Homebridge ZP plugin through Homebridge Config UI X or manually by:\n  ```\n  $ sudo npm -g i homebridge-zp\n  ```\n- Edit `config.json` and add the `ZP` platform provided by Homebridge ZP, see [**Configuration**](#configuration).\n\n### Configuration\nIn Homebridge's `config.json` you need to specify Homebridge ZP as a platform plugin:\n```json\n  \"platforms\": [\n    {\n      \"platform\": \"ZP\"\n    }\n  ]\n```\nThe following optional parameters can be added to modify Homebridge ZP's behaviour:\n\nKey | Default | Description\n--- | ------- | -----------\n`alarms` | `false` | Flag whether to expose an additional service per Sonos alarm.\n`brightness` | `false` | Flag whether to expose volume as `Brightness` when `service` is `\"switch\"` or `\"speaker\"`.  Setting this flag enables volume control from Siri, but not from Apple's Home app.\n`excludeAirPlay` | `false` | Flag whether not to expose zone players that support Airplay, since they natively show up in Apple's Home app.\u003cbr\u003eNote that if you only have newer zome players that support Airplay, enabling this option will essentially disable the plugin, as all zones will be hidden from Homekit.\n`heartrate` | (disabled) | Interval (in seconds) to poll zone players when `leds` is set.\n`leds` | `false` | Flag whether to expose an additional *Lightbulb* service per zone for the status LED.  This also supports locking the physical controls.\n`maxFavourites` | 96 | The number of preconfigured stations for a TV accessory, to be mapped to Sonos favourites.\n`mdns` | `true` | Enable zone player discovery through mDNS.\n`port` | `0` _(random)_ | The port for the web server Homebridge ZP creates to receive notifications from Sonos zone players.\n`resetTimeout` | `500` | Timeout (in milliseconds) to reset input (e.g. _Change Volume_).\n`service` | `\"switch\"` | Defines what type of service and volume characteristic Homebridge ZP uses.  Possible values are: `\"switch\"` for `Switch` and `Volume`; `\"speaker\"` for `Speaker` and `Volume`; `\"light\"` for `LightBulb` and `Brightness`; and `\"fan\"` for `Fan` and `Rotation Speed`.  Selecting `\"light\"` or `\"fan\"` enables changing the Sonos volume from Siri and from Apple's Home app.  Selecting `\"speaker\"` results in a *not supported* accessory in Apple's Home app.\n`speakers` | `false` | Flag whether to expose a second *Speakers* service per zone, in addition to the standard *Sonos* service, see [Speakers](#speakers).  You might want to set this if you're using Sonos groups in a configuration of multiple Sonos zones.\n`subscriptionTimeout` | `30` | The duration (in minutes) of the subscriptions Homebridge ZP creates with each zone player.\n`timeout` | `15` | The timeout (in seconds) to wait for a response from a Sonos zone player.\n`tv` | `false` | Create an additional, non-bridged TV accessory for each zone.\u003cbr\u003eNote that each TV accessory needs to be paired with HomeKit separately, using the same pin as for Homebridge, as specified in `config.json`.\n`tvIdPrefix` | `TV` | Prefix for serial number of TV accessories, to enable multiple instances of Homebridge ZP on the same network.\n\nBelow is an example `config.json` that exposes the *Sonos* and *Speakers* service as a HomeKit `Speaker` and volume as `Brightness`, so it can be controlled from Siri:\n```json\n  \"platforms\": [\n    {\n      \"platform\": \"ZP\",\n      \"service\": \"speaker\",\n      \"brightness\": true,\n      \"speakers\": true\n    }\n  ]\n```\n\n#### Split Sonos System\nIf you have a split Sonos system, Homebridge ZP will expose both the S2 and the S1 zone players.\nOf course you can only group S2 zone players with other S2 zone players; and S1 zone players with other S1 zone players.  \nThe same restriction applies when you have multiple Sonos households on your network: you can only group zone players with other zone players in the same household.\n\n### Troubleshooting\n\n#### Check Dependencies\nIf you run into Homebridge startup issues, please double-check what versions of Node.js and of Homebridge have been installed.\nHomebridge ZP has been developed and tested using the [latest LTS](https://nodejs.org/en/about/releases/) version of Node.js and the [latest](https://www.npmjs.com/package/homebridge) version of Homebridge.\nOther versions might or might not work - I simply don't have the bandwidth to test these.\n\n#### Run Homebridge ZP Solo\nIf you run into Homebridge startup issues, please run a separate instance of Homebridge with only Homebridge ZP (and Homebridge Config UI X) enabled in `config.json`.\nThis way, you can determine whether the issue is related to Homebridge ZP itself, or to the interaction of multiple Homebridge plugins in your setup.\nYou can start this separate instance of Homebridge on a different system, as a different user, or from a different user directory (specified by the `-U` flag).\nMake sure to use a different Homebridge `name`, `username`, and (if running on the same system) `port` in the `config.json` for each instance.\n\n#### Debug Log File\nHomebridge ZP outputs an info message for each HomeKit characteristic value it sets and for each HomeKit characteristic value change notification it receives.\nWhen Homebridge is started with `-D`, Homebridge ZP outputs a debug message for each request it makes to a Sonos zone player and for each zone player notification event it receives.\n\nTo capture these messages into a log file do the following:\n- If you're running Homebridge as a service, stop that service;\n- Run Homebridge manually, capturing the output into a file, by issuing:\n  ```\n  $ homebridge -CD 2\u003e\u00261 | tee homebridge.log\n  ```\n- Interact with your devices, through their native app and or through HomeKit to trigger the issue;\n- Hit interrupt (ctrl-C) to stop Homebridge;\n- If you're running Homebridge as a service, restart the service;\n- Compress the log file by issuing:\n  ```\n  $ gzip homebridge.log\n  ```\n\n#### Web Server\nLike the Sonos app, Homebridge ZP subscribes to the zone player events to be notified in real-time of changes.  It creates a web server to receive these notifications.  The IP address and port number for this listener are logged in a debug message, e.g.\n```\n[1/1/2020, 11:58:35 AM] [Sonos] listening on http://192.168.x.x:58004/notify\n```\nTo check whether the listener is reachable from the network, open this URL in your web browser.  You should see an overview of the active subscriptions per zone player.\n\n#### Getting Help\nIf you have a question, please post a message to the **#zp** channel of the Homebridge community on [Discord](https://discord.gg/3qFgFMk).\n\nIf you encounter a problem, please open an issue on [GitHub](https://github.com/ebaauw/homebridge-zp/issues).\nPlease **attach** a copy of `homebridge.log.gz` to the issue, see [**Debug Log File**](#debug-log-file).\nPlease do **not** copy/paste large amounts of log output.\n\n### Caveats\nHomebridge ZP is a hobby project of mine, provided as-is, with no warranty whatsoever.  I've been running it successfully at my home for years, but your mileage might vary.\n\nThe HomeKit terminology needs some getting used to.\nAn _accessory_ more or less corresponds to a physical device, accessible from your iOS device over WiFi or Bluetooth.\nA _bridge_ (like Homebridge) is an accessory that provides access to other, bridged, accessories.\nAn accessory might provide multiple _services_.\nEach service corresponds to a virtual device (like a lightbulb, switch, motion sensor, ..., but also: a programmable switch button, accessory information, battery status).\nSiri interacts with services, not with accessories.\nA service contains one or more _characteristics_.\nA characteristic is like a service attribute, which might be read or written by HomeKit apps.\nYou might want to checkout Apple's [HomeKit Accessory Simulator](https://developer.apple.com/documentation/homekit/testing_your_app_with_the_homekit_accessory_simulator), which is distributed as an additional tool for `Xcode`.\n\nThe Sonos terminology needs some getting used to.\nA _zone_ corresponds to a physical room.\nIt consists of a single zone player, two zone players configured as a stereo pair, or a home theatre setup (e.g. a PlayBar with separate surround speakers).\nTypically, zone setup is static; you would only change it when physically re-arranging your zone players between rooms.\nA _zone group_ is a collection of one or more zones, playing the same music in sync.\nA zone group is controlled by its _coordinator_ zone.\nTypically, groups are dynamic, you add and/or remove zones to/from a group when listening to your music.\nControls for play/pause and music source act on a zone group.\nControls for volume and mute act on a zone group or on a single zone.\nControls for bass, treble, and loudness act on a single zone.\nNote that Sonos uses the term _room_ ambiguously: on the Sonos app main screen it corresponds to a zone group, but in the Room Settings it corresponds to a zone.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Febaauw%2Fhomebridge-zp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Febaauw%2Fhomebridge-zp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Febaauw%2Fhomebridge-zp/lists"}