Merge pull request #84 from svrooij/beta

External Music services, Events and more

.eslintrc.js

@@ -21,6 +21,7 @@ module.exports =  {
     "max-len":"off",
     "no-console": "off",
     "no-return-await": "off",
+    "linebreak-style": "off"
   },
   overrides: [
     {
@@ -47,7 +48,8 @@ module.exports =  {
     {
       files: ['src/services/*.ts'],
       rules: {
-        'import/order': 'warn'
+        'import/order': 'warn',
+        'no-multiple-empty-lines': 'warn'
       }
     },
     {

README.md

@@ -1,34 +1,42 @@
-# Node Sonos (the typescript version)
+# Sonos (the typescript version)
 
-[![Support me on Github][badge_sponsor]][link_sponsor]
+[![Sonos typescript this library][badge_sonos-typescript]][link_sonos-typescript]
 [![npm][badge_npm]][link_npm]
+[![Sonos api documentation][badge_sonos-docs]][link_sonos-docs]
+[![Sonos2mqtt][badge_sonos-mqtt]][link_sonos-mqtt]
+[![Sonos cli][badge_sonos-cli]][link_sonos-cli]
+[![Join us on Discord][badge_discord]][link_discord]
+[![Support me on Github][badge_sponsor]][link_sponsor]
+
 [![Run tests and publish][badge_build]][link_build]
 [![github issues][badge_issues]][link_issues]
 [![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)
-[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)
+[![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)
 
-A node library to control a sonos device, written in Typescript. See [here](#improvements-over-node-sonos) why I've build it while there already is a sonos library written in node.
+Typescript library to control your sonos speakers. Can be used in other typescript (or node) apps.
 
+---
 ## Key features
 
-- [x] Auto [generated](./src/generator), strongly typed Sonos client.
-- [x] Auto discovery or one know device as starting point.
+- [x] Auto generated client (supporting all features the normal app does). [Sonos api documentation and generator](https://svrooij.io/sonos-api-docs/)
+- [x] Auto discovery or one known device as starting point.
 - [x] Support for logical devices (grouped speakers) from the start.
 - [x] Access to all (generated) services.
 - [x] Sonos device class with extra functionality.
 - [x] Strongly typed service events.
-- [x] Strongly typed extra events.
-- [x] Easier implementing [metadata generation](./src/helpers/metadata-helper.ts).
+- [x] Easier implemented [metadata generation](./src/helpers/metadata-helper.ts).
 
-## Usage
+## Documentation
 
 To 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).
 
 See **[Documentation](https://svrooij.github.io/node-sonos-ts/getting-started.html)**
 
-[![Documentation](./img/book.png)](https://svrooij.github.io/node-sonos-ts/getting-started.html)
+[![Sonos typescript this library][badge_sonos-typescript]][link_sonos-typescript] [![Join us on Discord][badge_discord]][link_discord]
+
+If you need help using this library, [join us on discord][link_discord].
 
-## Use Sonos manager
+## Use Sonos manager (recommended)
 
 This library is developed with Sonos groups in mind. We created a **SonosManager** to discover all known groups and keep track of changes to them.
 
@@ -56,7 +64,7 @@ manager.InitializeFromDevice(process.env.SONOS_HOST || '192.168.96.56')
   .catch(console.error)
 ```
 
-## or control single device
+### Single sonos speaker (no manager)
 
 If 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.
 
@@ -71,10 +79,6 @@ sonos.LoadDeviceData()
   .catch(console.error)
 ```
 
-## Documentation
-
-See what else you can do with this library in the [documentation](https://svrooij.github.io/node-sonos-ts/sonos-device)
-
 ## Text to speech
 
 A lot of people want to send text to sonos to use for notifications (or a welcome message in your B&B). 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.
@@ -116,14 +120,20 @@ Also using this library, but not in the list? Send a PR.
 
 ## Contributing
 
+[![Sonos api documentation][badge_sonos-docs]][link_sonos-docs]
+[![Sonos2mqtt][badge_sonos-mqtt]][link_sonos-mqtt]
+[![Sonos cli][badge_sonos-cli]][link_sonos-cli]
+[![Sonos typescript this library][badge_sonos-typescript]][link_sonos-typescript]
+[![Join us on Discord][badge_discord]][link_discord]
+
 You 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.
 
+### Support new music service
+
 If 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).
 It 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.
 The values you'll be looking for are `ProtocolInfo`, `TrackUri`, `UpnpClass`, `ItemID` and `ParentID`.
 
-Currently I'm also looking for a way to add documentation to the automatic generated services, so if you got any ideas, be sure to let me know.
-
 [![Support me on Github][badge_sponsor]][link_sponsor]
 
 ## Contributors ✨
@@ -172,41 +182,30 @@ have a mocha test (in test folder) open.
 
 ### Service generator
 
-I've created a one-liner to regenerate all the generated services.
-`SONOS_HOST=192.168.x.x npm run gen-srv`.
-
-You can also checkout the documentation on the awesome [service generator](./src/generator/).
-This can also be used as a source to generate a client for some other language.
-
-## Improvements over [node-sonos](https://github.com/bencevans/node-sonos)
+Most 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.
 
-The original [node-sonos](https://github.com/bencevans/node-sonos) is started a
-long time ago, before async programming in node, which I'm a contributor as well.
-Some design decisions cannot be fixed without breaking compatibility with all
-the applications using it. For instance the `.play()` function serves multiple
-purposes, starting playback and switching urls. A lot of applications depend on it,
-and they would all break if I would remove support for it.
-
-This new library is build from the ground up using `node-fetch` for the requests
-and `fast-xml-parser` for the xml stuff.
-
-One of the most important parts of this new library is the [**service-generator**](./src/generator/),
-it parses the `/xml/device_description.xml` file from the sonos device.
-And generates a strong typed service class for it.
-This means that this library will support everything the sonos controller can do.
-And it also means that it will tell your which parameters it expects.
 
 ### Big thanks to all the original contributors
 
 Creating a library from scratch is quite hard, and I'm using a lot of stuff from
-the original library. That wouldn't exists without the [contributors](https://github.com/bencevans/node-sonos/graphs/contributors).
+[node-sonos](https://github.com/bencevans/node-sonos/). That wouldn't exists without the [contributors](https://github.com/bencevans/node-sonos/graphs/contributors).
 
-[badge_sponsor]: https://img.shields.io/badge/Sponsor-on%20Github-red
-[badge_issues]: https://img.shields.io/github/issues/svrooij/node-sonos-ts
-[badge_npm]: https://img.shields.io/npm/v/@svrooij/sonos
 [badge_build]: https://github.com/svrooij/node-sonos-ts/workflows/Run%20tests%20and%20publish/badge.svg
+[badge_discord]: https://img.shields.io/discord/782374564054564875?style=flat-square
+[badge_issues]: https://img.shields.io/github/issues/svrooij/node-sonos-ts?style=flat-square
+[badge_npm]: https://img.shields.io/npm/v/@svrooij/sonos?style=flat-square
+[badge_sonos-cli]: https://img.shields.io/badge/sonos-cli-blue?style=flat-square
+[badge_sonos-docs]: https://img.shields.io/badge/sonos-api-blue?style=flat-square
+[badge_sonos-mqtt]: https://img.shields.io/badge/sonos-mqtt-blue?style=flat-square
+[badge_sonos-typescript]: https://img.shields.io/badge/sonos-typescript-blue?style=flat-square
+[badge_sponsor]: https://img.shields.io/badge/Sponsor-on%20Github-red?style=flat-square
 
-[link_sponsor]: https://github.com/sponsors/svrooij
+[link_build]: https://github.com/svrooij/node-sonos-ts/actions
+[link_discord]: https://discord.gg/VMtG6Ft36J
 [link_issues]: https://github.com/svrooij/node-sonos-ts/issues
 [link_npm]: https://www.npmjs.com/package/@svrooij/sonos
-[link_build]: https://github.com/svrooij/node-sonos-ts/actions
+[link_sonos-cli]: https://github.com/svrooij/sonos-cli
+[link_sonos-docs]: https://svrooij.io/sonos-api-docs
+[link_sonos-mqtt]: https://svrooij.io/sonos2mqtt
+[link_sonos-typescript]: https://svrooij.io/node-sonos-ts
+[link_sponsor]: https://github.com/sponsors/svrooij

docs/development.md

@@ -78,7 +78,6 @@ If you run the examples with the VSCode debug task, this variable is set to `son
 - **docs/** These documentations
 - **examples/** Several examples on how to use this library.
 - **img/** Some static images used in the library
-- **src/generator/** The client generator (written in node). It's used to generate all the services and the base device.
 - **src/helpers/** Some usefull typesscript 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.

docs/getting-started.md

@@ -46,7 +46,7 @@ manager.InitializeFromDevice(process.env.SONOS_HOST || '192.168.96.56')
   .catch(console.error)
 ```
 
-## or control single device
+### or control single device
 
 If 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.
 
@@ -60,3 +60,20 @@ sonos.LoadDeviceData()
   })
   .catch(console.error)
 ```
+
+## Debugging issues
+
+This library uses the [debug](https://www.npmjs.com/package/debug) library. If you want a lot more information about what is happening you can turn on all debug messages by setting the environment variable `DEBUG` to `sonos:*`.
+
+All logging information might be a bit overkill, it you set `DEBUG` to `sonos:eventListener` you will only receive log information from the event listener.
+
+| Debug setting | What is logged |
+|---------------|----------------|
+| `sonos:*` | Everything is logged to the console |
+| `sonos:eventListener` | Messages about the event listener |
+| `sonos:metadata` | Messages about the MetaDataHelper |
+| `sonos:service:*` | All services logs will be emitted |
+| `sonos:service:{serviceName}:*` | All logs about a specific service will be emitted |
+| `sonos:service:{serviceName}:{ip}` | All messages for a specific service for a specific speaker. |
+
+Check out the debug library for more configuration options. You can also combine several instructions with a `,` or just remove a spefic event with `-` in front.

docs/index.md

@@ -10,25 +10,41 @@ permalink: /
 
 # Sonos (typescript / node)
 
+[![Sonos api documentation][badge_sonos-docs]][link_sonos-docs]
+[![Sonos2mqtt][badge_sonos-mqtt]][link_sonos-mqtt]
+[![Sonos cli][badge_sonos-cli]][link_sonos-cli]
+[![Sonos typescript this library][badge_sonos-typescript]][link_sonos-typescript]
+[![Join us on Discord][badge_discord]][link_discord]
 [![Support me on Github][badge_sponsor]][link_sponsor]
+
 [![npm][badge_npm]][link_npm]
-[![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)
-[![travis][badge_travis]][link_travis]
+[![Run tests and publish][badge_build]][link_build]
 [![github issues][badge_issues]][link_issues]
+[![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)
 [![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)
 
-This library is in no way connected to [Sonos](//en.wikipedia.org/wiki/Sonos). It's just a library to control their speakers from TypeScript (or Node).
+Typescript library to control your sonos speakers. Can be used in other typescript (or node) apps.
+
+This library is in no way connected to [Sonos](//en.wikipedia.org/wiki/Sonos).
 
 ## Key features
 
-- [Auto-generated](//github.com/svrooij/node-sonos-ts/src/generator), strongly typed Sonos client.
-- Auto discovery or one known device as starting point.
-- Support for logical devices (grouped speakers) from the start.
-- Access to all (generated) services.
-- Sonos device class with extra functionality.
-- Strongly typed service events.
-- Strongly typed extra events.
-- Easier implementing  [metadata generation](//github.com/svrooij/node-sonos-ts/src/helpers/metadata-helper.ts).
+- [x] Auto generated client (supporting all features the normal app does). [Sonos api documentation and generator](https://svrooij.io/sonos-api-docs/)
+- [x] Auto discovery or one known device as starting point.
+- [x] Support for logical devices (grouped speakers) from the start.
+- [x] Access to all (generated) services.
+- [x] Sonos device class with extra functionality.
+- [x] Strongly typed service events.
+- [x] Easier implemented [metadata generation](https://github.com/svrooij/node-sonos-ts/blob/master/src/helpers/metadata-helper.ts).
+
+## Get Started
+
+To 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](https://github.com/svrooij/node-sonos-ts/tree/master/examples) you still need to use node (or typescript).
+
+See **[Documentation](https://svrooij.github.io/node-sonos-ts/getting-started.html)**
+
+[![Sonos typescript this library][badge_sonos-typescript]][link_sonos-typescript]
+[![Join us on Discord][badge_discord]][link_discord]
 
 ## Packages using node-sonos-ts
 
@@ -71,12 +87,22 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
 This project follows the [all-contributors](https://github.com/all-contributors/all-contributors)
 specification. Contributions of any kind welcome!
 
-[badge_sponsor]: https://img.shields.io/badge/Sponsor-on%20Github-red
-[badge_issues]: https://img.shields.io/github/issues/svrooij/node-sonos-ts
-[badge_npm]: https://img.shields.io/npm/v/@svrooij/sonos
-[badge_travis]: https://img.shields.io/travis/svrooij/node-sonos-ts
-
-[link_sponsor]: https://github.com/sponsors/svrooij
+[badge_build]: https://github.com/svrooij/node-sonos-ts/workflows/Run%20tests%20and%20publish/badge.svg
+[badge_discord]: https://img.shields.io/discord/782374564054564875?style=flat-square
+[badge_issues]: https://img.shields.io/github/issues/svrooij/node-sonos-ts?style=flat-square
+[badge_npm]: https://img.shields.io/npm/v/@svrooij/sonos?style=flat-square
+[badge_sonos-cli]: https://img.shields.io/badge/sonos-cli-blue?style=flat-square
+[badge_sonos-docs]: https://img.shields.io/badge/sonos-api-blue?style=flat-square
+[badge_sonos-mqtt]: https://img.shields.io/badge/sonos-mqtt-blue?style=flat-square
+[badge_sonos-typescript]: https://img.shields.io/badge/sonos-typescript-blue?style=flat-square
+[badge_sponsor]: https://img.shields.io/badge/Sponsor-on%20Github-red?style=flat-square
+
+[link_build]: https://github.com/svrooij/node-sonos-ts/actions
+[link_discord]: https://discord.gg/VMtG6Ft36J
 [link_issues]: https://github.com/svrooij/node-sonos-ts/issues
 [link_npm]: https://www.npmjs.com/package/@svrooij/sonos
-[link_travis]: https://travis-ci.org/svrooij/node-sonos-ts
+[link_sonos-cli]: https://github.com/svrooij/sonos-cli
+[link_sonos-docs]: https://svrooij.io/sonos-api-docs
+[link_sonos-mqtt]: https://svrooij.io/sonos2mqtt
+[link_sonos-typescript]: https://svrooij.io/node-sonos-ts
+[link_sponsor]: https://github.com/sponsors/svrooij