svrooij / sonos-api-docs Goto Github PK

View Code? Open in Web Editor NEW

32.0 4.0 7.0 652 KB

🔊 📖 Sonos api documentation for the local UPNP api and a generator to generate clients based on service discovery

Home Page: https://sonos.svrooij.io

License: MIT License

JavaScript 0.33% Batchfile 0.08% TypeScript 81.15% Handlebars 18.44%

sonos sonos-api upnp hacktoberfest

sonos-api-docs's Introduction

Unofficial Sonos docs

Sonos API documentation for the local UPNP API and a generator to generate clients and documentation based on service discovery

This library is in no way connected to 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/

Read documentation

Manually documented

The sonos services have no documentation, that is why we manually created a 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

You can use the generator to generate your own discovery files, but we also have the files available for download.

Player	Discovery file(s)
Sonos Play:1	S2
Sonos Play:3	S2
Sonos Play:5 (new)	S2
Sonos Playbar	S2
Sonos One	S2
Sonos One (mic)	S2
Sonos Beam	S2
Sonos Roam	S2
Sonos Sub	S2
SYMFONISK Bookshelf	S2
Sonos Play:5 (old)	S1

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 or you want to show your Sonos integration. Please join us in the discussions tab on this repository.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

_{Stephan van Rooij}
💻 📖 🤔 🚧

_{H. Klages}
📖

_{Sebastian Schuberth}
📖

_{Jason Kossis}
📖

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

sonos-api-docs's People

Contributors

Stargazers

Watchers

Forkers

sschuberth gauthierm koshisan joepv gabdug 4name mgeramb

sonos-api-docs's Issues

Documentation:

On the developer page, the second link return 404

For example this part is the source for the documentation you see on this >>>>PAGE.

parameter versus property

I suggest to rename "parameter" to "property" for the methods (in table header).
Reading parameter leads to create calls ..... .SetMute(0, true, 'Master') instead of using object with the properties

Documentation: Allowed values missing in play, GetMediaInfo, GetTransportInfo

See the following screen shots

Documentation: Eq variables

System info

Sonos version (S1 or S2): S1
Software version:

Service details

Service name: RenderingControl
Action name(s): GetEq, SetEq

Link to current documentation

Proposed change

SoCo/SoCo#780

Documentation: Communication - adding SSDP and plain http request

Link to current documentation

sonos-api-docs\docs\sonos-soap.md

Proposed change

Replace
'If you want to communicate with your sonos speakers on your local network you're forced to use SOAP in most cases.'

To communicate with your Sonos speakers on your local network use:

UDP Datagram and Simple Service Discovery Protocol (SSDP) at port 1900 to discover SONOS player
HTTP requests at port 1400 to scrape the UPnP service information or get a simple device status information
SOAP to call the SONOS services at port 1400 and subscribe to events
New secure RestURL at https://{ip}:1443/api (not covered in this documentation)

Interesting REST endpoints are:

http://{ip}:1400/status/info: playerId, serialNumber, groupId, householdId, capabilities, versions and more (JSON format)
http://{ip}:1400/status: several additional connection informoation
http://{ip}:1400/status/batterystatus: battery status for devices with battery (JSON format)
http://{ip}:1400/region.htm: to select a Wifi region out of USA/Canada, EU, CHINA, JAPAN, ISRAEL, RUSSIA, SOUTH KOREA
http://{ip}:1400/support/review: a list of all players with playerID and links to more information
http://{ip}:1400/xml/device_description.xml: see SONOS Services

Documentation: ContentDirectory Browse does not support Filter

System info

Sonos version (S1 or S2): S2
Software version: 14.20.1

Service details

Service name: ContentDirectory
Action name(s): Browse

Link to current documentation

https://sonos.svrooij.io/services/content-directory.html#browse

Proposed change

Documentation says for the parameter "Filter": "Which fields should be returned * for all."
I just tried multiple things (dc:title, +dc:title, title, ...) and was not able to get this working.
It seems to me that this field is required but actually does nothing. No matter what the value is set to,
always all fields will be returned.

Can anyone confirm this?
If this is actually the case, then this parameter is just a placeholder that is required.

Current Text: "Which fields should be returned * for all."
Proposed Text: "This parameter is just a placeholder. Its presence is required, but it is not functional"

help for the musicservice command shows placeholder

The help message for the musicservice command shows "describe the command here" instead of an actual description

error 714 issue

Hello when i try to set my URI file:///jffs/settings/savedqueues.rsq#26 with setAVTransportURI i receive this response

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/" s:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
    <s:Body>
        <s:Fault>
            <faultcode>s:Client</faultcode>
            <faultstring>UPnPError</faultstring>
            <detail>
                <UPnPError xmlns="urn:schemas-upnp-org:control-1-0">
                    <errorCode>714</errorCode>
                </UPnPError>
            </detail>
        </s:Fault>
    </s:Body>
</s:Envelope>

i don't what is it and how can i fix this issue. Can you help me?

Thank you

Documentation:

In documentation.json I can see my changes for "Browse" but not on the web side.

          "description": "Browse for content: Music library (A), share(S:), Sonos playlists(SQ:), Sonos favorites(FV:2), radio stations(R:0/0), radio shows(R:0/1). Recommendation: Send one request, check the 'TotalMatches' and - if necessary - do additional requests with higher 'StartingIndex'. In case of duplicates only the first is returned! Example: albums with same title, even if artists are different",
          "params": {
            "ObjectID": "The search query, ['A:ARTIST','A:ALBUMARTIST','A:ALBUM','A:GENRE','A:COMPOSER','A:TRACKS','A:PLAYLISTS', 'S:', 'SQ:', 'FV:2', 'R:0/0', 'R:0/1'] with optionally ':search+query' behind it.",
            "BrowseFlag": "How to browse",
            "Filter": "Which fields should be returned `*` for all.",
            "StartingIndex": "Paging, where to start, usually 0",
            "RequestedCount": "Paging, number of items, maximum is 1,000. This parameter does NOT restrict the number of items being searched (filter) but only the number being returned. ",
            "SortCriteria": "Sort the results based on metadata fields. `+upnp:artist,+dc:title` for sorting on artist then on title.",
            "Result": "Encoded DIDL-Lite XML. See remark (2)"
          },
          "remarks": "(1) If the title contains an apostrophe the returned uri will contain a `&apos;`. (2) Some libraries support a BrowseAndParse, so you don't have to parse the xml."
        }

Supplemental event properties

    @svrooij just did the re-generation, thank you!

One thing I noted was, it wiped away rendering control service's HeightChannelLevel that I added in this pr, which makes sense. It doesn't come back in the discovery doc, though it does actually get returned in the real world (I tested this).

Along these lines, is there a mechanism in place to supplement events properties that don't come back in the discovery doc?

Originally posted by @jkossis in svrooij/node-sonos-ts#172 (comment)

Documentation: Play:5 should be S2 (seems to be my discovery file)

System info

File: index.md

I guess it must be S2 and not S1.

| Sonos Play:5 (new) | S1 |

Generate insomnia file

Insomnia is a really nice tool to test http calls. How cool would it be if there was a generated file that supports all the sonos calls.

{
  "_type": "export",
  "__export_format": 4,
  "__export_date": "2021-01-12T23:23:00.857Z",
  "__export_source": "insomnia.desktop.app:v2020.5.2",
  "resources": [{
    "_id": "req_e7a219407cf24786b74ecc314c5fc102",
    "parentId": "fld_27e2408455d542fda75753d78d3afa0c",
    "modified": 1610493481306,
    "created": 1610492647833,
    "url": "http://{{ _.host }}:{{ _.port }}/AlarmClock/Control",
    "name": "ListAlarms",
    "description": "",
    "method": "POST",
    "body": {
      "mimeType": "application/xml",
      "text": "<?xml version=\"1.0\" encoding=\"utf-8\"?>\n<s:Envelope\n\txmlns:s=\"http://schemas.xmlsoap.org/soap/envelope/\" s:encodingStyle=\"http://schemas.xmlsoap.org/soap/encoding/\">\n\t<s:Body>\n\t\t<u:ListAlarms\n\t\t\txmlns:u=\"urn:schemas-upnp-org:service:AlarmClock:1\">\n\t\t</u:ListAlarms>\n\t</s:Body>\n</s:Envelope>"
    },
    "parameters": [],
    "headers": [{
      "name": "soapaction",
      "value": "\"urn:schemas-upnp-org:service:AlarmClock:1#ListAlarms\"",
      "description": "",
      "id": "pair_60631ab9449d46988c9842657261e024"
    }, {
      "name": "Content-Type",
      "value": "text/xml; charset=\"utf-8\"",
      "id": "pair_6827448929584270ba4a32570d33169c"
    }],
    "authentication": {},
    "metaSortKey": -1610492647833,
    "isPrivate": false,
    "settingStoreCookies": true,
    "settingSendCookies": true,
    "settingDisableRenderRequestBody": false,
    "settingEncodeUrl": true,
    "settingRebuildPath": true,
    "settingFollowRedirects": "global",
    "_type": "request"
  }, {
    "_id": "fld_27e2408455d542fda75753d78d3afa0c",
    "parentId": "wrk_66c9e68fadd74802b8df737b6b353052",
    "modified": 1610492628004,
    "created": 1610492628004,
    "name": "AlarmClockService",
    "description": "",
    "environment": {},
    "environmentPropertyOrder": null,
    "metaSortKey": -1610492628004,
    "_type": "request_group"
  }, {
    "_id": "wrk_66c9e68fadd74802b8df737b6b353052",
    "parentId": null,
    "modified": 1610492519291,
    "created": 1610492519291,
    "name": "Sonos",
    "description": "",
    "scope": null,
    "_type": "workspace"
  }, {
    "_id": "req_adf99e4a7994451dadb7495852a4c4ae",
    "parentId": "fld_06782a916bb94693839bfc88cab7c01f",
    "modified": 1610493747034,
    "created": 1610493210414,
    "url": "http://{{ _.host }}:{{ _.port }}/MediaRenderer/AVTransport/Control",
    "name": "Play",
    "description": "Start playback",
    "method": "POST",
    "body": {
      "mimeType": "application/xml",
      "text": "<?xml version=\"1.0\" encoding=\"utf-8\"?>\n<s:Envelope\n\txmlns:s=\"http://schemas.xmlsoap.org/soap/envelope/\" s:encodingStyle=\"http://schemas.xmlsoap.org/soap/encoding/\">\n\t<s:Body>\n\t\t<u:Play\n\t\t\txmlns:u=\"urn:schemas-upnp-org:service:AVTransport:1\">\n\t\t\t<InstanceID>0</InstanceID>\n\t\t\t<Speed>1</Speed>\n\t\t</u:Play>\n\t</s:Body>\n</s:Envelope>"
    },
    "parameters": [],
    "headers": [{
      "name": "soapaction",
      "value": "\"urn:schemas-upnp-org:service:AVTransport:1#Play\"",
      "description": "",
      "id": "pair_60631ab9449d46988c9842657261e024"
    }, {
      "name": "Content-Type",
      "value": "text/xml; charset=\"utf-8\"",
      "id": "pair_6827448929584270ba4a32570d33169c"
    }],
    "authentication": {},
    "metaSortKey": -1610492647833,
    "isPrivate": false,
    "settingStoreCookies": false,
    "settingSendCookies": false,
    "settingDisableRenderRequestBody": false,
    "settingEncodeUrl": false,
    "settingRebuildPath": false,
    "settingFollowRedirects": "off",
    "_type": "request"
  }, {
    "_id": "fld_06782a916bb94693839bfc88cab7c01f",
    "parentId": "wrk_66c9e68fadd74802b8df737b6b353052",
    "modified": 1610493210412,
    "created": 1610493210412,
    "name": "AVTransport",
    "description": "",
    "environment": {},
    "environmentPropertyOrder": null,
    "metaSortKey": -1610488229724,
    "_type": "request_group"
  }, {
    "_id": "env_09b1f7945fda3ec533c4d8586c26f9b9e22bf647",
    "parentId": "wrk_66c9e68fadd74802b8df737b6b353052",
    "modified": 1610492560174,
    "created": 1610492519359,
    "name": "Base Environment",
    "data": {
      "host": "192.168.96.56",
      "port": 1400
    },
    "dataPropertyOrder": {
      "&": ["host", "port"]
    },
    "color": null,
    "isPrivate": false,
    "metaSortKey": 1610492519359,
    "_type": "environment"
  }, {
    "_id": "jar_09b1f7945fda3ec533c4d8586c26f9b9e22bf647",
    "parentId": "wrk_66c9e68fadd74802b8df737b6b353052",
    "modified": 1610492519361,
    "created": 1610492519361,
    "name": "Default Jar",
    "cookies": [],
    "_type": "cookie_jar"
  }, {
    "_id": "spc_f9a8d654359a4ff189db18bb022b5862",
    "parentId": "wrk_66c9e68fadd74802b8df737b6b353052",
    "modified": 1610492519302,
    "created": 1610492519302,
    "fileName": "Sonos",
    "contents": "",
    "contentType": "yaml",
    "_type": "api_spec"
  }]
}

svrooij / sonos-api-docs Goto Github PK

sonos-api-docs's Introduction

Unofficial Sonos docs

Documentation

Manually documented

Device discovery files

Community

Contributors ✨

sonos-api-docs's People

Contributors

Stargazers

Watchers

Forkers

sonos-api-docs's Issues

System info

Service details

Link to current documentation

Proposed change

Link to current documentation

Proposed change

System info

Service details

Link to current documentation

Proposed change

System info

System info

Service details

Link to current documentation

Proposed change

Recommend Projects

Recommend Topics

Recommend Org