Merge pull request #44 from svrooij/feat/sample-value

Sample values

.github/ISSUE_TEMPLATE/config.yml

@@ -1 +1,8 @@
 blank_issues_enabled: false
+contact_links:
+  - name: Questions
+    url: https://github.com/svrooij/sonos-api-docs/discussions/categories/q-a
+    about: Please ask and answer questions here.
+  - name: All discussions
+    url: https://github.com/svrooij/sonos-api-docs/discussions
+    about: General discussions about the Sonos API.

README.md

@@ -1,6 +1,6 @@
 # Unofficial Sonos docs
 
-[![Sonos api documentation][badge_sonos-docs]][link_sonos-docs]
+[![Sonos API documentation][badge_sonos-docs]][link_sonos-docs]
 [![Github Issues][badge_issues]][link_issues]
 [![Sonos2mqtt][badge_sonos-mqtt]][link_sonos-mqtt]
 [![Sonos cli][badge_sonos-cli]][link_sonos-cli]
@@ -9,21 +9,21 @@
 [![Support me on Github][badge_sponsor]][link_sponsor]
 [![Follow on Twitter][badge_twitter]][link_twitter]
 
-Sonos api documentation for the local UPNP api and a [generator](https://github.com/svrooij/sonos-api-docs/tree/main/generator/sonos-docs) to generate clients and documentation based on service discovery
+Sonos API documentation for the local UPNP API and a [generator](https://github.com/svrooij/sonos-api-docs/tree/main/generator/sonos-docs) to generate clients and documentation based on service discovery
 
-This library is in no way connected to [Sonos](//en.wikipedia.org/wiki/Sonos). It's just a set of text files to document a hidden and **unsupported** api.
+This library is in no way connected to [Sonos](//en.wikipedia.org/wiki/Sonos). It's just a set of text files to document a hidden and **unsupported** API.
 
 ## Documentation
 
 Check-out the (generated) documentation about all the SONOS UPNP services [svrooij.io/sonos-api-docs/services/](https://sonos.svrooij.io/services/)
 
-[![Sonos api documentation][badge_sonos-docs]][link_sonos-docs]
+[![Sonos API documentation][badge_sonos-docs]][link_sonos-docs]
 
 [Read documentation](https://sonos.svrooij.io/)
 
 ### Manually documented
 
-The [sonos services](https://svrooij.io/sonos-api-docs/services/) have no documentation, that is why we manually created a [documentation.json](http://svrooij.io/sonos-api-docs/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.
+The [sonos services](https://sonos.svrooij.io/services/) have no documentation, that is why we manually created a [documentation.json](https://github.com/svrooij/sonos-api-docs/blob/main/docs/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.
 
 ### Device discovery files
 
@@ -45,6 +45,10 @@ You can use the generator to generate your own discovery files, but we also have
 
 These files together with the documentation file, are combined to a extensive JSON file, that is used as an input for the generator.
 
+## Community
+
+If you have any [questions](https://github.com/svrooij/sonos-api-docs/discussions/categories/q-a) or you want to [show](https://github.com/svrooij/sonos-api-docs/discussions/categories/show-and-tell) your Sonos integration. Please join us in the [discussions](https://github.com/svrooij/sonos-api-docs/discussions) tab on this repository.
+
 ## Contributors ✨
 
 <!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
@@ -81,7 +85,6 @@ specification. Contributions of any kind welcome!
 [badge_sponsor]: https://img.shields.io/github/sponsors/svrooij?logo=github&style=for-the-badge
 [badge_twitter]: https://img.shields.io/twitter/follow/svrooij?logo=twitter&style=for-the-badge
 
-
 [link_sponsor]: https://github.com/sponsors/svrooij
 [link_issues]: https://github.com/svrooij/sonos-api-docs/issues
 [link_sonos-cli]: https://github.com/svrooij/sonos-cli

docs/developers.md

@@ -55,7 +55,7 @@ For example [this part](https://github.com/svrooij/sonos-api-docs/blob/25aad3a3a
 
 We build a custom [generator](https://github.com/svrooij/sonos-api-docs/tree/main/generator/sonos-docs) to do several things.
 
-### Discover services from sonos speaker
+### Discover services from Sonos speaker
 
 You can use the generator to generate [device discovery files]({{ '/#device-discovery-files' | relative_url }}). For each model we generated a discovery json, as available on main page. We generate this file by parsing the device discovery document available at `http://{sonos_ip}:1400/xml/device_description.xml`. Not every model has the same services, but it seems that if a service is available it's the same as all other models that have that service.
 
@@ -74,9 +74,11 @@ npm install
 ./bin/run services {sonos-ip}
 ```
 
+Please help us out occasionally by running this command on your own Sonos speaker and send us the resulting file. This way we can keep the discovery files up to date. This command will automatically update the discovery files in the `data` folder. These files are used as an input for the generator. Having up to date discovery files will help us to keep the documentation up to date. All personal identifiable information is removed from the discovery files.
+
 ### Combine discovery files and documentation
 
-If you changed the [documentation.json](#documentation.json) file or if you added/updated discovery files, you need to combine the two into one file, the **.cache/combined.json** file.
+If you changed the [documentation.json](./documentation.json) file or if you added/updated discovery files, you need to combine the two into one file, the **.cache/combined.json** file.
 
 This file is the result of the the manual documentation and the device discovery files. This file is almost 8000 lines of json at the moment, which is why it is ignored in git.
 Being able to inspect this json file should really help in debugging the generator.
@@ -101,7 +103,7 @@ npx @svrooij/sonos-docs combine --docsFile=./docs/documentation.json --folder=./
 
 ### Regenerate documentation
 
-Once you generated the **combined.json** file, you can use the generator to (re)generate the [service documentation]({{ '/services' | relative_url }}). This step is mandatory if you changed either the **documentation.json** or if you added/updated one of the discovery files. 
+Once you generated the **combined.json** file, you can use the generator to (re)generate the [service documentation]({{ '/services' | relative_url }}). This step is mandatory if you changed either the **documentation.json** or if you added/updated one of the discovery files.
 
 The resulting files, are **not to be changed manually**, since changes will get lost upon the next generation.
 
@@ -135,7 +137,7 @@ The template.json file gives some basic information about the template, the auth
 1. File usage `index`, will use the data from intermediate.json as input to produce **one file**.
 2. File usage `service`, will use the data from each service to produce **one file per service**, be sure to use `{snService}` or `{service}` in the **outputFile**.
 
-Be sure to check out the [docs template](https://github.com/svrooij/sonos-api-docs/tree/main/generator/sonos-docs/templates/docs) to get started. Or the [ts template](https://github.com/svrooij/sonos-api-docs/tree/main/generator/sonos-docs/templates/ts), which is used to generate [sonos-ts](https://svrooij.io/node-sonos-ts/).
+Be sure to check out the [docs template](https://github.com/svrooij/sonos-api-docs/tree/main/generator/sonos-docs/templates/docs) to get started. Or the [ts template](https://github.com/svrooij/node-sonos-ts/tree/master/.generator/ts), which is used to generate [Sonos typescript](https://sonos-ts.svrooij.io/).
 
 
 ```bash

docs/documentation.json

@@ -20,6 +20,19 @@
             "Volume": "Volume between 0 and 100",
             "IncludeLinkedZones": "Should grouped players also play the alarm?",
             "AssignedID": "The ID of the new alarm"
+          },
+          "sample": {
+            "StartLocalTime": "07:00:00",
+            "Duration": "00:30:00",
+            "Recurrence": "DAILY",
+            "Enabled": "1",
+            "RoomUUID": "RINCON_000E58FE3AEA01400",
+            "ProgramURI": "x-rincon-buzzer:0",
+            "ProgramMetaData": "",
+            "PlayMode": "NORMAL",
+            "Volume": "20",
+            "IncludeLinkedZones": "1",
+            "AssignedID": "1"
           }
         },
         "DestroyAlarm": {
@@ -59,7 +72,7 @@
       "description": "Control line in"
     },
     "AVTransportService": {
-      "description": "Service that controls stuff related to transport (play/pause/next/special urls)",
+      "description": "Service that controls stuff related to transport (play/pause/next/special URLs)",
       "actions": {
         "AddURIToQueue": {
           "description": "Adds songs to the SONOS queue",

docs/index.md

@@ -38,7 +38,7 @@ This file has a [documentation json schema](https://sonos.svrooij.io/schema/docu
 
 ### Update documentation
 
-If you change the [documentation](#manual-documentation-file) file or if you did service discovery for a new device. You can update the documentation files with the following commands:
+If you change the [documentation](#manually-documented) file or if you did service discovery for a new device. You can update the documentation files with the following commands:
 
 ```shell
 # Go to generation folder
@@ -55,7 +55,7 @@ npm run docs
 
 ## Generator
 
-You can find the generator [here](https://github.com/svrooij/sonos-api-docs/tree/main/generator/sonos-docs) and use it to generate your own sonos client in your preferred language.
+You can find the generator [here](https://github.com/svrooij/sonos-api-docs/tree/main/generator/sonos-docs) and use it to generate your own Sonos client in your preferred language.
 
 ### Device discovery files
 
@@ -84,9 +84,7 @@ The template.json also has a [json schema](https://svrooij.io/sonos-api-docs/sch
 
 ## Community
 
-[![Join us on Discord][badge_discord]][link_discord]
-
-If you need help building an app that talks to your sonos speakers, or you want to share some of your findings. [Join us on Discord][link_discord].
+If you have any [questions](https://github.com/svrooij/sonos-api-docs/discussions/categories/q-a) or you want to [show](https://github.com/svrooij/sonos-api-docs/discussions/categories/show-and-tell) your Sonos integration. Please join us in the [discussions](https://github.com/svrooij/sonos-api-docs/discussions) tab on this repository.
 
 ## Contributors ✨
 

docs/music-services.md

@@ -245,7 +245,7 @@ You should get a response that looks like this (Spofity result):
 
 This results in:
 
-- `regUrl` this is the url you should visit in the browser, it will ask you to login.
+- `regUrl` this is the URL you should visit in the browser, it will ask you to login.
 - `linkCode` this is sometimes needed to fill in on the page. And you'll need it for the next step.
 
 #### AppLink - Step 2
@@ -338,7 +338,7 @@ With the following body:
 
 This will results in a response with at least the following data:
 
-- `regUrl` this is the url you should visit in the browser, it will ask you to login.
+- `regUrl` this is the URL you should visit in the browser, it will ask you to login.
 - `linkCode` this is sometimes needed to fill in on the page. And you'll need it for the next step.
 
 Continue with [applink - step 2](#applink---step-2) after visiting the **regUrl** in the browser.

docs/schema/documentation.json

@@ -51,6 +51,16 @@
           },
           "type": "object"
         },
+        "sample": {
+          "title": "Sample values",
+          "description": "Sample values for the parameters",
+          "additionalProperties": {
+            "title": "Value",
+            "description": "Working value, by it name as key",
+            "type": "string"
+          },
+          "type": "object"
+        },
         "remarks": {
           "title": "Action remarks",
           "description": "Remarks about this action",

docs/services/alarm-clock.md

@@ -55,16 +55,16 @@ Action body:
 
 ```xml
 <u:CreateAlarm xmlns:u="urn:schemas-upnp-org:service:AlarmClock:1">
-  <StartLocalTime>string</StartLocalTime>
-  <Duration>string</Duration>
-  <Recurrence>string</Recurrence>
-  <Enabled>boolean</Enabled>
-  <RoomUUID>string</RoomUUID>
-  <ProgramURI>string</ProgramURI>
+  <StartLocalTime>07:00:00</StartLocalTime>
+  <Duration>00:30:00</Duration>
+  <Recurrence>DAILY</Recurrence>
+  <Enabled>1</Enabled>
+  <RoomUUID>RINCON_000E58FE3AEA01400</RoomUUID>
+  <ProgramURI>x-rincon-buzzer:0</ProgramURI>
   <ProgramMetaData>string</ProgramMetaData>
-  <PlayMode>string</PlayMode>
-  <Volume>ui2</Volume>
-  <IncludeLinkedZones>boolean</IncludeLinkedZones>
+  <PlayMode>NORMAL</PlayMode>
+  <Volume>20</Volume>
+  <IncludeLinkedZones>1</IncludeLinkedZones>
 </u:CreateAlarm>
 ```
 
@@ -450,15 +450,15 @@ This file is automatically generated with [@svrooij/sonos-docs](https://github.c
 
 | Device | Software generation | Software version | Discovery date |
 |:-------|:--------------------|:-----------------|:---------------|
-| `Sonos Play:1 (S1)` | S2 | 72.2-40060 | 2023-05-22T16:39:21.190Z |
+| `Sonos Play:1 (S1)` | S2 | 77.4-49290 | 2024-02-13T15:56:06.184Z |
 | `Sonos One (S13)` | S2 | 63.2-90210 | 2021-07-21T23:31:19.273Z |
 | `Sonos Beam (S14)` | S2 | 64.3-19080 | 2021-08-18T06:04:08.308Z |
-| `Sonos One (S18)` | S2 | 72.2-40060 | 2023-05-22T16:38:38.243Z |
+| `Sonos One (S18)` | S2 | 77.4-49290 | 2024-02-13T15:55:36.464Z |
 | `SYMFONISK Bookshelf (S21)` | S2 | 66.4-23300 | 2022-01-01T11:41:01.361Z |
 | `Sonos Roam (S27)` | S2 | 63.2-90210 | 2021-07-21T23:31:31.207Z |
 | `Sonos Play:3 (S3)` | S2 | 64.3-19080 | 2021-08-18T06:09:36.692Z |
-| `SYMFONISK Bookshelf (S33)` | S2 | 72.2-40060 | 2023-05-22T16:39:16.679Z |
+| `SYMFONISK Bookshelf (S33)` | S2 | 77.4-49290 | 2024-02-13T15:55:24.423Z |
 | `Sonos One SL (S38)` | S2 | 72.2-40060 | 2023-05-22T16:39:25.503Z |
 | `Sonos Play:5 (S6)` | S2 | 64.3-19080 | 2021-08-18T06:06:35.970Z |
-| `Sonos Playbar (S9)` | S2 | 72.2-40060 | 2023-05-22T16:38:57.120Z |
+| `Sonos Playbar (S9)` | S2 | 77.4-49290 | 2024-02-13T15:55:46.307Z |
 | `Sonos Sub (Sub)` | S2 | 63.2-90210 | 2021-07-21T23:31:40.304Z |

docs/services/av-transport.md

@@ -6,7 +6,7 @@ parent: Sonos Services
 # AVTransport service
 {: .no_toc }
 
-Service that controls stuff related to transport (play/pause/next/special urls)
+Service that controls stuff related to transport (play/pause/next/special URLs)
 
 The AVTransport service is available on these models: `Sonos Play:1 (S1) S2` / `Sonos One (S13) S2` / `Sonos Beam (S14) S2` / `Sonos One (S18) S2` / `SYMFONISK Bookshelf (S21) S2` / `Sonos Roam (S27) S2` / `Sonos Play:3 (S3) S2` / `SYMFONISK Bookshelf (S33) S2` / `Sonos One SL (S38) S2` / `Sonos Play:5 (S6) S2` / `Sonos Playbar (S9) S2` / `Sonos Sub (Sub) S2`.
 
@@ -1224,15 +1224,15 @@ This file is automatically generated with [@svrooij/sonos-docs](https://github.c
 
 | Device | Software generation | Software version | Discovery date |
 |:-------|:--------------------|:-----------------|:---------------|
-| `Sonos Play:1 (S1)` | S2 | 72.2-40060 | 2023-05-22T16:39:21.190Z |
+| `Sonos Play:1 (S1)` | S2 | 77.4-49290 | 2024-02-13T15:56:06.184Z |
 | `Sonos One (S13)` | S2 | 63.2-90210 | 2021-07-21T23:31:19.273Z |
 | `Sonos Beam (S14)` | S2 | 64.3-19080 | 2021-08-18T06:04:08.308Z |
-| `Sonos One (S18)` | S2 | 72.2-40060 | 2023-05-22T16:38:38.243Z |
+| `Sonos One (S18)` | S2 | 77.4-49290 | 2024-02-13T15:55:36.464Z |
 | `SYMFONISK Bookshelf (S21)` | S2 | 66.4-23300 | 2022-01-01T11:41:01.361Z |
 | `Sonos Roam (S27)` | S2 | 63.2-90210 | 2021-07-21T23:31:31.207Z |
 | `Sonos Play:3 (S3)` | S2 | 64.3-19080 | 2021-08-18T06:09:36.692Z |
-| `SYMFONISK Bookshelf (S33)` | S2 | 72.2-40060 | 2023-05-22T16:39:16.679Z |
+| `SYMFONISK Bookshelf (S33)` | S2 | 77.4-49290 | 2024-02-13T15:55:24.423Z |
 | `Sonos One SL (S38)` | S2 | 72.2-40060 | 2023-05-22T16:39:25.503Z |
 | `Sonos Play:5 (S6)` | S2 | 64.3-19080 | 2021-08-18T06:06:35.970Z |
-| `Sonos Playbar (S9)` | S2 | 72.2-40060 | 2023-05-22T16:38:57.120Z |
+| `Sonos Playbar (S9)` | S2 | 77.4-49290 | 2024-02-13T15:55:46.307Z |
 | `Sonos Sub (Sub)` | S2 | 63.2-90210 | 2021-07-21T23:31:40.304Z |

docs/services/connection-manager.md

@@ -140,15 +140,15 @@ This file is automatically generated with [@svrooij/sonos-docs](https://github.c
 
 | Device | Software generation | Software version | Discovery date |
 |:-------|:--------------------|:-----------------|:---------------|
-| `Sonos Play:1 (S1)` | S2 | 72.2-40060 | 2023-05-22T16:39:21.190Z |
+| `Sonos Play:1 (S1)` | S2 | 77.4-49290 | 2024-02-13T15:56:06.184Z |
 | `Sonos One (S13)` | S2 | 63.2-90210 | 2021-07-21T23:31:19.273Z |
 | `Sonos Beam (S14)` | S2 | 64.3-19080 | 2021-08-18T06:04:08.308Z |
-| `Sonos One (S18)` | S2 | 72.2-40060 | 2023-05-22T16:38:38.243Z |
+| `Sonos One (S18)` | S2 | 77.4-49290 | 2024-02-13T15:55:36.464Z |
 | `SYMFONISK Bookshelf (S21)` | S2 | 66.4-23300 | 2022-01-01T11:41:01.361Z |
 | `Sonos Roam (S27)` | S2 | 63.2-90210 | 2021-07-21T23:31:31.207Z |
 | `Sonos Play:3 (S3)` | S2 | 64.3-19080 | 2021-08-18T06:09:36.692Z |
-| `SYMFONISK Bookshelf (S33)` | S2 | 72.2-40060 | 2023-05-22T16:39:16.679Z |
+| `SYMFONISK Bookshelf (S33)` | S2 | 77.4-49290 | 2024-02-13T15:55:24.423Z |
 | `Sonos One SL (S38)` | S2 | 72.2-40060 | 2023-05-22T16:39:25.503Z |
 | `Sonos Play:5 (S6)` | S2 | 64.3-19080 | 2021-08-18T06:06:35.970Z |
-| `Sonos Playbar (S9)` | S2 | 72.2-40060 | 2023-05-22T16:38:57.120Z |
+| `Sonos Playbar (S9)` | S2 | 77.4-49290 | 2024-02-13T15:55:46.307Z |
 | `Sonos Sub (Sub)` | S2 | 63.2-90210 | 2021-07-21T23:31:40.304Z |

docs/services/content-directory.md

@@ -435,15 +435,15 @@ This file is automatically generated with [@svrooij/sonos-docs](https://github.c
 
 | Device | Software generation | Software version | Discovery date |
 |:-------|:--------------------|:-----------------|:---------------|
-| `Sonos Play:1 (S1)` | S2 | 72.2-40060 | 2023-05-22T16:39:21.190Z |
+| `Sonos Play:1 (S1)` | S2 | 77.4-49290 | 2024-02-13T15:56:06.184Z |
 | `Sonos One (S13)` | S2 | 63.2-90210 | 2021-07-21T23:31:19.273Z |
 | `Sonos Beam (S14)` | S2 | 64.3-19080 | 2021-08-18T06:04:08.308Z |
-| `Sonos One (S18)` | S2 | 72.2-40060 | 2023-05-22T16:38:38.243Z |
+| `Sonos One (S18)` | S2 | 77.4-49290 | 2024-02-13T15:55:36.464Z |
 | `SYMFONISK Bookshelf (S21)` | S2 | 66.4-23300 | 2022-01-01T11:41:01.361Z |
 | `Sonos Roam (S27)` | S2 | 63.2-90210 | 2021-07-21T23:31:31.207Z |
 | `Sonos Play:3 (S3)` | S2 | 64.3-19080 | 2021-08-18T06:09:36.692Z |
-| `SYMFONISK Bookshelf (S33)` | S2 | 72.2-40060 | 2023-05-22T16:39:16.679Z |
+| `SYMFONISK Bookshelf (S33)` | S2 | 77.4-49290 | 2024-02-13T15:55:24.423Z |
 | `Sonos One SL (S38)` | S2 | 72.2-40060 | 2023-05-22T16:39:25.503Z |
 | `Sonos Play:5 (S6)` | S2 | 64.3-19080 | 2021-08-18T06:06:35.970Z |
-| `Sonos Playbar (S9)` | S2 | 72.2-40060 | 2023-05-22T16:38:57.120Z |
+| `Sonos Playbar (S9)` | S2 | 77.4-49290 | 2024-02-13T15:55:46.307Z |
 | `Sonos Sub (Sub)` | S2 | 63.2-90210 | 2021-07-21T23:31:40.304Z |

docs/services/device-properties.md

@@ -679,15 +679,15 @@ This file is automatically generated with [@svrooij/sonos-docs](https://github.c
 
 | Device | Software generation | Software version | Discovery date |
 |:-------|:--------------------|:-----------------|:---------------|
-| `Sonos Play:1 (S1)` | S2 | 72.2-40060 | 2023-05-22T16:39:21.190Z |
+| `Sonos Play:1 (S1)` | S2 | 77.4-49290 | 2024-02-13T15:56:06.184Z |
 | `Sonos One (S13)` | S2 | 63.2-90210 | 2021-07-21T23:31:19.273Z |
 | `Sonos Beam (S14)` | S2 | 64.3-19080 | 2021-08-18T06:04:08.308Z |
-| `Sonos One (S18)` | S2 | 72.2-40060 | 2023-05-22T16:38:38.243Z |
+| `Sonos One (S18)` | S2 | 77.4-49290 | 2024-02-13T15:55:36.464Z |
 | `SYMFONISK Bookshelf (S21)` | S2 | 66.4-23300 | 2022-01-01T11:41:01.361Z |
 | `Sonos Roam (S27)` | S2 | 63.2-90210 | 2021-07-21T23:31:31.207Z |
 | `Sonos Play:3 (S3)` | S2 | 64.3-19080 | 2021-08-18T06:09:36.692Z |
-| `SYMFONISK Bookshelf (S33)` | S2 | 72.2-40060 | 2023-05-22T16:39:16.679Z |
+| `SYMFONISK Bookshelf (S33)` | S2 | 77.4-49290 | 2024-02-13T15:55:24.423Z |
 | `Sonos One SL (S38)` | S2 | 72.2-40060 | 2023-05-22T16:39:25.503Z |
 | `Sonos Play:5 (S6)` | S2 | 64.3-19080 | 2021-08-18T06:06:35.970Z |
-| `Sonos Playbar (S9)` | S2 | 72.2-40060 | 2023-05-22T16:38:57.120Z |
+| `Sonos Playbar (S9)` | S2 | 77.4-49290 | 2024-02-13T15:55:46.307Z |
 | `Sonos Sub (Sub)` | S2 | 63.2-90210 | 2021-07-21T23:31:40.304Z |