{"id":16243304,"url":"https://github.com/svrooij/node-sonos-ts","last_synced_at":"2025-04-09T13:07:45.945Z","repository":{"id":35936693,"uuid":"219065768","full_name":"svrooij/node-sonos-ts","owner":"svrooij","description":":speaker: Sonos control library, use this library in your own appliction.","archived":false,"fork":false,"pushed_at":"2024-06-13T19:22:11.000Z","size":1545,"stargazers_count":81,"open_issues_count":5,"forks_count":18,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-10-11T14:13:57.010Z","etag":null,"topics":["hacktoberfest","home-automation","sonos","sonos-controller"],"latest_commit_sha":null,"homepage":"https://sonos-ts.svrooij.io/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/svrooij.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":"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":"svrooij"}},"created_at":"2019-11-01T21:33:31.000Z","updated_at":"2024-09-19T16:05:39.000Z","dependencies_parsed_at":"2024-06-18T17:11:15.226Z","dependency_job_id":"4609751e-c2ac-4bdd-b0e0-4417d9981ac0","html_url":"https://github.com/svrooij/node-sonos-ts","commit_stats":{"total_commits":243,"total_committers":11,"mean_commits":22.09090909090909,"dds":0.5349794238683128,"last_synced_commit":"de5e822a952666380a5acf81bc7ae1e0678abcfd"},"previous_names":[],"tags_count":80,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/svrooij%2Fnode-sonos-ts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/svrooij%2Fnode-sonos-ts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/svrooij%2Fnode-sonos-ts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/svrooij%2Fnode-sonos-ts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/svrooij","download_url":"https://codeload.github.com/svrooij/node-sonos-ts/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248045232,"owners_count":21038553,"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":["hacktoberfest","home-automation","sonos","sonos-controller"],"created_at":"2024-10-10T14:14:27.662Z","updated_at":"2025-04-09T13:07:45.707Z","avatar_url":"https://github.com/svrooij.png","language":"TypeScript","funding_links":["https://github.com/sponsors/svrooij"],"categories":[],"sub_categories":[],"readme":"# Sonos (the typescript version)\n\n[![Sonos typescript this library][badge_sonos-typescript]][link_sonos-typescript]\n[![npm][badge_npm]][link_npm]\n[![Sonos api documentation][badge_sonos-docs]][link_sonos-docs]\n[![Sonos2mqtt][badge_sonos-mqtt]][link_sonos-mqtt]\n[![Sonos cli][badge_sonos-cli]][link_sonos-cli]\n[![Join us on Discord][badge_discord]][link_discord]\n[![Support me on Github][badge_sponsor]][link_sponsor]\n\n[![Run tests and publish][badge_build]][link_build]\n[![github issues][badge_issues]][link_issues]\n[![Coverage Status](https://coveralls.io/repos/github/svrooij/node-sonos-ts/badge.svg?branch=master)](https://coveralls.io/github/svrooij/node-sonos-ts?branch=master)\n[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](//github.com/semantic-release/semantic-release)\n\nTypescript library to control your sonos speakers. Can be used in other typescript (or node) apps.\n\n---\n## Key features\n\n- [x] Auto generated client (supporting all features the normal app does). [Sonos api documentation and generator](https://svrooij.io/sonos-api-docs/)\n- [x] Auto discovery or one known device as starting point.\n- [x] Support for logical devices (grouped speakers) from the start.\n- [x] Access to all (generated) services.\n- [x] Sonos device class with extra functionality.\n- [x] Strongly typed service events.\n- [x] Easier implemented [metadata generation](./src/helpers/metadata-helper.ts).\n\n## Documentation\n\nTo use the library just add it to your project. `npm install @svrooij/sonos`. And start using it. This library isn't meant to be used by itself, as you see in the [examples](./examples) you still need to use node (or typescript).\n\nSee **[Documentation](https://svrooij.github.io/node-sonos-ts/getting-started.html)**\n\n[![Sonos typescript this library][badge_sonos-typescript]][link_sonos-typescript] [![Join us on Discord][badge_discord]][link_discord]\n\nIf you need help using this library, [join us on discord][link_discord].\n\n## Use Sonos manager (recommended)\n\nThis library is developed with Sonos groups in mind. We created a **SonosManager** to discover all known groups and keep track of changes to them.\n\n```js\nconst SonosManager = require('@svrooij/sonos').SonosManager\nconst manager = new SonosManager()\nmanager.InitializeWithDiscovery(10)\n  .then(console.log)\n  .then(() =\u003e {\n    manager.Devices.forEach(d =\u003e console.log('Device %s (%s) is joined in %s', d.Name, d.uuid, d.GroupName))\n  })\n  .catch(console.error)\n```\n\nIn some network situations (or Docker usage) SSDP won't work, but you can also start the manager if you know one (static) IP of a single speaker.\n\n```js\nconst SonosManager = require('@svrooij/sonos').SonosManager\nconst manager = new SonosManager()\nmanager.InitializeFromDevice(process.env.SONOS_HOST || '192.168.96.56')\n  .then(console.log)\n  .then(() =\u003e {\n    manager.Devices.forEach(d =\u003e console.log('Device %s (%s) is joined in %s', d.Name, d.uuid, d.GroupName))\n  })\n  .catch(console.error)\n```\n\n### Single sonos speaker (no manager)\n\nIf you just want to control a single device and don't want to use the SonosManager, you can also create a instance of **SonosDevice**, but you'll be missing the group options.\n\n```js\nconst SonosDevice = require('@svrooij/sonos').SonosDevice\n\nconst sonos = new SonosDevice(process.env.SONOS_HOST || '192.168.96.56')\nsonos.LoadDeviceData()\n  .then(success =\u003e {\n    console.log(sonos.Name)\n  })\n  .catch(console.error)\n```\n\n## Text to speech\n\nA lot of people want to send text to sonos to use for notifications (or a welcome message in your B\u0026B). This library has support for text-to-speech but you'll need a text-to-speech endpoint. To keep this library as clean as possible, the text-to-speech server is build in a seperate package. See [node-sonos-tts-polly](https://github.com/svrooij/node-sonos-tts-polly) for a text-to-speech server that uses Amazon Polly for speech generation.\n\nFor my [sponsors](link_sponsor) I've setup a hosted version, so if you don't want to setup your own server, you know what to do.\n\nThe text-to-speech works as following:\n\n1. Request the TTS endpoint what the url of the supplied text is.\n2. If the server doesn't have this file, it will generate the mp3 file on the fly.\n3. The TTS endpoint returns the url of the mp3.\n4. We call the regular `.PlayNotification({})` command, with the tts url.\n\nYou can also set the endpoint with the `SONOS_TTS_ENDPOINT` environment variable, so you don't have to supply it every time. The default language can be set with the environment variable `SONOS_TTS_LANG`.\n\nThe server I've build is based on Amazon Polly, but I invite eveybody to build their own if you want to support an other tts service.\n\n```JavaScript\nconst SonosDevice = require('../lib').SonosDevice\nconst sonos = new SonosDevice(process.env.SONOS_HOST || '192.168.96.56')\nsonos.PlayTTS({ text: 'Someone at the front-door', lang: 'en-US', gender: 'male', volume: 50, endpoint: 'https://your.tts.endpoint/api/generate' })\n  .then(played =\u003e {\n    console.log('Played notification %o', played)\n    // Timeout to allow event subscriptions to cancel.\n    setTimeout(() =\u003e {\n      process.exit(0)\n    }, 500)\n  })\n```\n\n## Others using node-sonos-ts\n\n|Name|Maintainer|Description|\n|----|----------|----------|\n|[sonos2mqtt](https://github.com/svrooij/sonos2mqtt)|[@svrooij](https://github.com/svrooij)|A bridge between sonos and mqtt, so you can control all your sonos devices right from your mqtt server|\n|[sonos-cli](https://github.com/svrooij/sonos-cli)|[@svrooij](https://github.com/svrooij)|An experimental command line interface for your sonos devices.|\n\nAlso using this library, but not in the list? Send a PR.\n\n## Contributing\n\n[![Sonos api documentation][badge_sonos-docs]][link_sonos-docs]\n[![Sonos2mqtt][badge_sonos-mqtt]][link_sonos-mqtt]\n[![Sonos cli][badge_sonos-cli]][link_sonos-cli]\n[![Sonos typescript this library][badge_sonos-typescript]][link_sonos-typescript]\n[![Join us on Discord][badge_discord]][link_discord]\n\nYou can contribute in many ways. Asking good questions, solving bugs, sponsoring me on github. This library is build in my spare time, so don't be rude about it.\n\n### Support new music service\n\nIf you're using a music service that currently isn't supported for metadata generation, you should check out the [metadata generator](./src/helpers/metadata-helper.ts).\nIt works by taking an url (which you can get by running the [get-position-info sample](./examples/get-position-info.js)). And generating a **Track** for it. Use the information out the console to get the right values.\nThe values you'll be looking for are `ProtocolInfo`, `TrackUri`, `UpnpClass`, `ItemID` and `ParentID`.\n\n[![Support me on Github][badge_sponsor]][link_sponsor]\n\n## Contributors ✨\n\n\u003c!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section --\u003e\n[![All Contributors](https://img.shields.io/badge/all_contributors-3-orange.svg?style=flat-square)](#contributors-)\n\u003c!-- ALL-CONTRIBUTORS-BADGE:END --\u003e\n\nThanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --\u003e\n\u003c!-- prettier-ignore-start --\u003e\n\u003c!-- markdownlint-disable --\u003e\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"https://svrooij.nl\"\u003e\u003cimg src=\"https://avatars2.githubusercontent.com/u/1292510?v=4\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eStephan van Rooij\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/svrooij/node-sonos-ts/commits?author=svrooij\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"https://github.com/svrooij/node-sonos-ts/commits?author=svrooij\" title=\"Documentation\"\u003e📖\u003c/a\u003e \u003ca href=\"#ideas-svrooij\" title=\"Ideas, Planning, \u0026 Feedback\"\u003e🤔\u003c/a\u003e \u003ca href=\"#maintenance-svrooij\" title=\"Maintenance\"\u003e🚧\u003c/a\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"https://github.com/cheanrod\"\u003e\u003cimg src=\"https://avatars3.githubusercontent.com/u/35066927?v=4\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eSven Werner\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/svrooij/node-sonos-ts/commits?author=cheanrod\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"https://github.com/hklages\"\u003e\u003cimg src=\"https://avatars3.githubusercontent.com/u/17273119?v=4\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eH. Klages\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/svrooij/node-sonos-ts/commits?author=hklages\" title=\"Documentation\"\u003e📖\u003c/a\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n\u003c!-- markdownlint-enable --\u003e\n\u003c!-- prettier-ignore-end --\u003e\n\u003c!-- ALL-CONTRIBUTORS-LIST:END --\u003e\n\nThis project follows the [all-contributors](https://github.com/all-contributors/all-contributors)\nspecification. Contributions of any kind welcome!\n\n## Developer section\n\nThis will contain usefull information if you want to fix a bug you've found in\nthis library. You always start with cloning the repo and doing a\n`npm install`\nin the folder. I like consistancy so everything is in a specific order :wink:.\n\n### Running example code\n\nThis library has two VSCode launch configurations.\n\nOne for running the current open example, you can set breakpoints in the example\nfile and in the typescript code! Be sure to change the IP to your own in `.vscode/launch.json`,\nso you don't have to edit all the example files.\n\nAnd it has a launch configuration to run the current Mocha test file, be sure to\nhave a mocha test (in test folder) open.\n\n### Service generator\n\nMost of this library is generated by the [generator](https://github.com/svrooij/sonos-api-docs/tree/main/generator/sonos-docs). You can use the generator in your own project. Or just use the service file. I could use some help improving the code of the generator.\n\n\n### Big thanks to all the original contributors\n\nCreating a library from scratch is quite hard, and I'm using a lot of stuff from\n[node-sonos](https://github.com/bencevans/node-sonos/). That wouldn't exists without the [contributors](https://github.com/bencevans/node-sonos/graphs/contributors).\n\n[badge_build]: https://github.com/svrooij/node-sonos-ts/workflows/Run%20tests%20and%20publish/badge.svg\n[badge_discord]: https://img.shields.io/discord/782374564054564875?style=flat-square\n[badge_issues]: https://img.shields.io/github/issues/svrooij/node-sonos-ts?style=flat-square\n[badge_npm]: https://img.shields.io/npm/v/@svrooij/sonos?style=flat-square\n[badge_sonos-cli]: https://img.shields.io/badge/sonos-cli-blue?style=flat-square\n[badge_sonos-docs]: https://img.shields.io/badge/sonos-api-blue?style=flat-square\n[badge_sonos-mqtt]: https://img.shields.io/badge/sonos-mqtt-blue?style=flat-square\n[badge_sonos-typescript]: https://img.shields.io/badge/sonos-typescript-blue?style=flat-square\n[badge_sponsor]: https://img.shields.io/badge/Sponsor-on%20Github-red?style=flat-square\n\n[link_build]: https://github.com/svrooij/node-sonos-ts/actions\n[link_discord]: https://discord.gg/VMtG6Ft36J\n[link_issues]: https://github.com/svrooij/node-sonos-ts/issues\n[link_npm]: https://www.npmjs.com/package/@svrooij/sonos\n[link_sonos-cli]: https://github.com/svrooij/sonos-cli\n[link_sonos-docs]: https://svrooij.io/sonos-api-docs\n[link_sonos-mqtt]: https://svrooij.io/sonos2mqtt\n[link_sonos-typescript]: https://svrooij.io/node-sonos-ts\n[link_sponsor]: https://github.com/sponsors/svrooij","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsvrooij%2Fnode-sonos-ts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsvrooij%2Fnode-sonos-ts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsvrooij%2Fnode-sonos-ts/lists"}