-
-
Notifications
You must be signed in to change notification settings - Fork 11
Expand file tree
/
Copy pathdocumentation.json
More file actions
510 lines (510 loc) · 23.3 KB
/
documentation.json
File metadata and controls
510 lines (510 loc) · 23.3 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
{
"$schema": "https://sonos.svrooij.io/schema/documentation.json",
"language": "EN",
"license": "MIT",
"services": {
"AlarmClockService": {
"description": "Control the sonos alarms and times",
"actions": {
"CreateAlarm": {
"description": "Create a single alarm, all properties are required",
"params": {
"StartLocalTime": "The start time as `hh:mm:ss`",
"Duration": "The duration as `hh:mm:ss`",
"Recurrence": "Repeat this alarm on",
"Enabled": "Alarm enabled after creation",
"RoomUUID": "The UUID of the speaker you want this alarm for",
"ProgramURI": "The sound uri",
"ProgramMetaData": "The sound metadata, can be empty string",
"PlayMode": "Alarm play mode",
"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": {
"description": "Delete an alarm",
"params": {
"ID": "The Alarm ID from ListAlarms"
}
},
"ListAlarms": {
"description": "Get the AlarmList as XML",
"params": {
"CurrentAlarmList": "xml string, see remarks"
},
"remarks": "Some libraries also provide a ListAndParseAlarms where the alarm list xml is parsed"
},
"UpdateAlarm": {
"description": "Update an alarm, all parameters are required.",
"params": {
"ID": "The ID of the alarm see ListAlarms",
"StartLocalTime": "The start time as `hh:mm:ss`",
"Duration": "The duration as `hh:mm:ss`",
"Recurrence": "Repeat this alarm on",
"Enabled": "Alarm enabled after creation",
"RoomUUID": "The UUID of the speaker you want this alarm for",
"ProgramURI": "The sound uri",
"ProgramMetaData": "The sound metadata, can be empty string",
"PlayMode": "Alarm play mode",
"Volume": "Volume between 0 and 100",
"IncludeLinkedZones": "Should grouped players also play the alarm?"
},
"remarks": "Some libraries support PatchAlarm where you can update a single parameter"
}
},
"errors": [{ "code": 801, "description": "Duplicate alarm time" }]
},
"AudioInService": {
"description": "Control line in"
},
"AVTransportService": {
"description": "Service that controls stuff related to transport (play/pause/next/special URLs)",
"actions": {
"AddURIToQueue": {
"description": "Adds songs to the SONOS queue",
"remarks": "In NORMAL play mode the songs are added prior to the specified `DesiredFirstTrackNumberEnqueued`.",
"params": {
"DesiredFirstTrackNumberEnqueued": "use `0` to add at the end or `1` to insert at the beginning"
}
},
"BecomeCoordinatorOfStandaloneGroup": {
"description": "Leave the current group and revert to a single player."
},
"ConfigureSleepTimer": {
"description": "Stop playing after set sleep timer or cancel",
"remarks":"Send to non-coordinator returns error code 800",
"params": {
"NewSleepTimerDuration": "Time to stop after, as `hh:mm:ss` or empty string to cancel"
}
},
"DelegateGroupCoordinationTo": {
"description": "Delegates the coordinator role to another player in the same group",
"remarks":"Send to non-coordinator has no results - should be avoided.",
"params": {
"NewCoordinator": "uuid of the new coordinator - must be in same group",
"RejoinGroup": "Should former coordinator rejoin the group?"
}
},
"GetCrossfadeMode": {
"description": "Get crossfade mode",
"remarks":"Send to non-coordinator may return wrong value as only the coordinator value in a group"
},
"GetCurrentTransportActions": {
"description": "Get current transport actions such as Set, Stop, Pause, Play, X_DLNA_SeekTime, Next, X_DLNA_SeekTrackNr",
"remarks":"Send to non-coordinator returns only `Start` and `Stop` since it cannot control the stream."
},
"GetMediaInfo": {
"description": "Get information about the current playing media (queue)"
},
"GetPositionInfo": {
"description": "Get information about current position (position in queue and time in current song)"
},
"GetRemainingSleepTimerDuration": {
"description": "Get time left on sleeptimer.",
"remarks":"Send to non-coordinator returns error code 800",
"params": {
"RemainingSleepTimerDuration": "Format hh:mm:ss or empty string if not set"
}
},
"GetTransportInfo": {
"description": "Get current transport status, speed and state such as PLAYING, STOPPED, PLAYING, PAUSED_PLAYBACK, TRANSITIONING, NO_MEDIA_PRESENT",
"remarks":"Send to non-coordinator always returns PLAYING"
},
"GetTransportSettings": {
"description": "Get transport settings",
"remarks":"Send to non-coordinator returns the settings of it's queue"
},
"Next": {
"description": "Go to next song",
"remarks": "Possibly not supported at the moment see GetCurrentTransportActions"
},
"Pause": {
"description": "Pause playback"
},
"Play": {
"description": "Start playing the set TransportURI",
"params": {
"Speed": "Play speed usually 1, can be a fraction of 1"
}
},
"Previous": {
"description": "Go to previous song",
"remarks": "Possibly not supported at the moment see GetCurrentTransportActions"
},
"RemoveAllTracksFromQueue": {
"description": "Flushes the SONOS queue.",
"remarks":"If queue is already empty it throw error 804. Send to non-coordinator returns error code 800."
},
"RemoveTrackRangeFromQueue": {
"description": "Removes the specified range of songs from the SONOS queue.",
"params": {
"UpdateID": "Leave blank",
"StartingIndex": "between 1 and queue-length"
}
},
"SaveQueue": {
"description": "Saves the current SONOS queue as a SONOS playlist and outputs objectID",
"remarks":"Send to non-coordinator returns error code 800",
"params": {
"Title": "SONOS playlist title",
"ObjectID": "Leave blank"
}
},
"Seek": {
"description": "Seek track in queue, time delta or absolute time in song",
"remarks":"Returns error code 701 in case that content does not support Seek or send to non-coordinator",
"params": {
"Unit": "What to seek",
"Target": "Position of track in queue (start at 1) or `hh:mm:ss` for `REL_TIME` or `+/-hh:mm:ss` for `TIME_DELTA`"
}
},
"SetAVTransportURI": {
"description": "Set the transport URI to a song, a stream, the queue, another player-rincon and a lot more",
"remarks":"If set to another player RINCON, the player is grouped with that one.",
"params": {
"CurrentURI": "The new TransportURI - its a special SONOS format",
"CurrentURIMetaData": "Track Metadata, see MetadataHelper.GuessTrack to guess based on track uri"
}
},
"SetCrossfadeMode": {
"description": "Set crossfade mode",
"remarks":"Send to non-coordinator returns error code 800. Same for content, which does not support crossfade mode."
},
"SetPlayMode": {
"description": "Set the PlayMode",
"remarks":"Send to non-coordinator returns error code 712. If SONOS queue is not activated returns error code 712.",
"params": {
"NewPlayMode": "New playmode"
}
},
"SnoozeAlarm": {
"description": "Snooze the current alarm for some time.",
"params": {
"Duration": "Snooze time as `hh:mm:ss`, 10 minutes = 00:10:00"
}
},
"Stop": {
"description": "Stop playback"
}
},
"errors": [
{ "code": 701, "description": "Transition not available" },
{ "code": 702, "description": "No content" },
{ "code": 703, "description": "Read error" },
{ "code": 704, "description": "Format not supported for playback" },
{ "code": 705, "description": "Transport is locked" },
{ "code": 706, "description": "Write error" },
{ "code": 707, "description": "Media protected or not writeable" },
{ "code": 708, "description": "Format not supported for recording" },
{ "code": 709, "description": "Media is full" },
{ "code": 710, "description": "Seek mode not supported" },
{ "code": 711, "description": "Illegal seek target" },
{ "code": 712, "description": "Play mode not supported" },
{ "code": 713, "description": "Record quality not supported" },
{ "code": 714, "description": "Illegal MIME-Type" },
{ "code": 715, "description": "Content busy" },
{ "code": 716, "description": "Resource not found" },
{ "code": 717, "description": "Play speed not supported" },
{ "code": 718, "description": "Invalid InstanceID" },
{ "code": 737, "description": "No dns configured" },
{ "code": 738, "description": "Bad domain" },
{ "code": 739, "description": "Server error" },
{ "code": 800, "description": "Command not supported or not a coordinator" }
]
},
"ConnectionManagerService": {
"description": "Services related to connections and protocols"
},
"ContentDirectoryService": {
"description": "Browse for local content",
"actions": {
"Browse": {
"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), queue(Q:)). 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` / `FV:2` / `Q:`/ `R:0/0` / `R:0/1` / `S:` / `SQ:`) 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. Using 0 is equivalent to 1,000",
"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 `'`. (2) Some libraries support a BrowseAndParse, so you don't have to parse the xml."
},
"GetAlbumArtistDisplayOption": {
"description": "Get the current album art display option such as `WMP`, `ITUNES` or `NONE`"
},
"RefreshShareIndex": {
"description": "Updates the music library (share) index",
"params": {
"AlbumArtistDisplayOption": "`WMP`, `ITUNES` or `NONE`"
}
}
},
"errors": [
{ "code": 701, "description": "No such object" },
{ "code": 702, "description": "Invalid CurrentTagValue" },
{ "code": 703, "description": "Invalid NewTagValue" },
{ "code": 704, "description": "Required tag" },
{ "code": 705, "description": "Read-only tag" },
{ "code": 706, "description": "Parameter mismatch" },
{ "code": 708, "description": "Invalid search criteria" },
{ "code": 709, "description": "Invalid sort criteria" },
{ "code": 710, "description": "No such container" },
{ "code": 711, "description": "Restricted object" },
{ "code": 712, "description": "Bad metadata" },
{ "code": 713, "description": "Restricted parent object" },
{ "code": 714, "description": "No such source resource" },
{ "code": 715, "description": "Resource access denied" },
{ "code": 716, "description": "Transfer busy" },
{ "code": 717, "description": "No such file transfer" },
{ "code": 718, "description": "No such destination resource" },
{ "code": 719, "description": "Destination resource access denied" },
{ "code": 720, "description": "Cannot process the request" }
]
},
"DevicePropertiesService": {
"description": "Modify device properties, like LED status and stereo pairs",
"actions": {
"AddHTSatellite": {
"description": "Adds satellites and/or a sub woofer to a (main) player. The satellites become hidden. The main player RINCON_* is mandatory. RR: right - rear, LF: left - front, SW: subwoofer",
"params": {
"HTSatChanMapSet": "example: `RINCON_000PPP1400:LF,RF;RINCON_000RRR1400:RR;RINCON_000SSS1400:LR;RINCON_000QQQ1400:SW`"
},
"remarks": "Not all speakers support satellites or sub woofer. Satellites should be of same type (e.g. Play:1)"
},
"GetButtonLockState": {
"description": "Get the current button lock state"
},
"GetLEDState": {
"description": "Get the current LED state"
},
"GetZoneInfo": {
"description": "Get information about this specific speaker",
"params": {
"HTAudioIn": "SPDIF input, `0` not connected / `2` stereo / `7` Dolby 2.0 / `18` dolby 5.1 / `21` not listening / `22` silence"
}
},
"CreateStereoPair": {
"description": "Create a stereo pair (left, right speakers), right one becomes hidden",
"params": {
"ChannelMapSet": "example: `RINCON_B8E9375831C001400:LF,LF;RINCON_000E58FE3AEA01400:RF,RF`"
},
"remarks": "Not all speakers support StereoPairs"
},
"RemoveHTSatellite": {
"description": "Removes a satellite or a sub woofer from (main) player. The satellite becomes visible.",
"params": {
"SatRoomUUID": "example: `RINCON_000RRR1400`"
},
"remarks": "Not all speakers support satellites or sub woofer. Multiples RINCON_* are not allowed."
},
"SeparateStereoPair": {
"description": "Separate a stereo pair",
"params": {
"ChannelMapSet": "example: `RINCON_B8E9375831C001400:LF,LF;RINCON_000E58FE3AEA01400:RF,RF`"
},
"remarks": "Not all speakers support StereoPairs"
},
"SetButtonLockState": {
"description": "Set the button lock state"
},
"SetLEDState": {
"description": "Set the LED state"
}
}
},
"GroupManagementService": {
"description": "Services related to groups"
},
"GroupRenderingControlService": {
"description": "Volume related controls for groups",
"actions": {
"GetGroupMute": {
"description": "Get the group mute state.",
"remarks": "Should be send to coordinator only"
},
"GetGroupVolume": {
"description": "Get the group volume.",
"remarks": "Should be send to coordinator only"
},
"SetGroupMute": {
"description": "(Un-/)Mute the entire group",
"remarks": "Should be send to coordinator only"
},
"SetGroupVolume": {
"description": "Change group volume. Players volume will be changed proportionally based on last snapshot",
"remarks": "Should be send to coordinator only",
"params": {
"DesiredVolume": "New volume between 0 and 100"
}
},
"SetRelativeGroupVolume": {
"description": "Relatively change group volume - returns final group volume. Players volume will be changed proportionally based on last snapshot",
"remarks": "Should be send to coordinator only",
"params": {
"Adjustment": "Number between -100 and +100"
}
},
"SnapshotGroupVolume": {
"description": "Creates a new group volume snapshot, the volume ratio between all players. It is used by SetGroupVolume and SetRelativeGroupVolume",
"remarks": "Should be send to coordinator only"
}
},
"errors": [
{ "code": 701, "description": "Player isn't the coordinator" }
]
},
"HTControlService": {
"description": "Service related to the TV remote control"
},
"MusicServicesService": {
"description": "Access to external music services, like Spotify or Youtube Music",
"actions": {
"ListAvailableServices": {
"description": "Load music service list as xml",
"remarks": "Some libraries also support ListAndParseAvailableServices"
}
}
},
"QueueService": {
"description": "Modify and browse queues"
},
"QPlayService": {
"description": "Services related to Chinese Tencent Qplay service"
},
"RenderingControlService": {
"description": "Volume related controls",
"actions": {
"GetBass": {
"description": "Get bass level between -10 and 10"
},
"GetEQ": {
"description": "Get equalizer value",
"params": {
"EQType": "Allowed values `DialogLevel` (string, 1–4 on supported devices: 1 = low, 2 = medium, 3 = high, 4 = max) / `SpeechEnhanceEnabled` (bool) / `MusicSurroundLevel` (-15/+15) / `NightMode` (bool) / `SubGain` (-10/+10) / `SurroundEnable` (bool) / `SurroundLevel` (-15/+15) / `SurroundMode` (0 = ambient, 1 = full) / `HeightChannelLevel` (-10/+10)",
"CurrentValue": "Booleans return `1` / `0`; `DialogLevel` returns a string value representing the dialog intensity level, rest return number as specified"
},
"remarks": "Not all EQ types are available on every speaker"
},
"GetLoudness": {
"description": "Whether or not Loudness is on"
},
"GetTreble": {
"description": "Get treble",
"params": {
"CurrentTreble": "Number between -10 and 10"
}
},
"GetVolume": {
"description": "Get volume",
"params": {
"CurrentVolume": "Number between 0 and 100"
}
},
"SetBass": {
"description": "Set bass level, between -10 and 10"
},
"SetEQ": {
"description": "Set equalizer value for different types",
"params": {
"EQType": "Allowed values `DialogLevel` (string, 1–4 on supported devices: 1 = low, 2 = medium, 3 = high, 4 = max) / `SpeechEnhanceEnabled` (bool) / `MusicSurroundLevel` (-15/+15) / `NightMode` (bool) / `SubGain` (-10/+10) / `SurroundEnable` (bool) / `SurroundLevel` (-15/+15) / `SurroundMode` (0 = ambient, 1 = full) / `HeightChannelLevel` (-10/+10)",
"DesiredValue": "Booleans return `1` / `0`; `DialogLevel` returns a string value representing the dialog intensity levels, rest number as specified"
},
"remarks": "On newer devices (e.g. Arc Ultra), dialog enhancement on/off is controlled via `SpeechEnhanceEnabled`, while `DialogLevel` represents the intensity level (1 = low, 2 = medium, 3 = high, 4 = max) and does not return 0 when disabled. Not all EQ types are available on every speaker. Not supported by all speakers, TV related"
},
"SetLoudness": {
"description": "Set loudness on / off"
},
"SetTreble": {
"description": "Set treble level",
"params": {
"DesiredTreble": "between -10 and 10"
}
}
},
"variables": [
{
"name": "HeightChannelLevel",
"dataType": "ui4"
}
]
},
"SystemPropertiesService": {
"description": "Manage system-wide settings, mainly account stuff",
"actions": {
"GetString": {
"description": "Get a saved string.",
"params": {
"VariableName": "The key for this variable"
},
"remarks": "Strings are saved in the system with SetString, every speaker should return the same data. Will error when not existing"
},
"Remove": {
"description": "Remove a saved string",
"params": {
"VariableName": "The key for this variable"
},
"remarks": "Not sure what happens if you call this with a VariableName that doesn't exists."
},
"SetString": {
"description": "Save a string in the system",
"params": {
"VariableName": "The key for this variable, use something unique"
},
"remarks": "Strings are saved in the system, retrieve values with GetString."
}
}
},
"ZoneGroupTopologyService": {
"description": "Zone config stuff, eg getting all the configured sonos zones",
"actions": {
"GetZoneGroupAttributes": {
"description": "Get information about the current Zone"
},
"GetZoneGroupState": {
"description": "Get all the Sonos groups, (as XML)",
"params": {
"ZoneGroupState": "xml string, see remarks"
},
"remarks": "Some libraries also support GetParsedZoneGroupState that parses the xml for you."
}
}
}
},
"errors": [
{ "code": 400, "description": "Bad request" },
{ "code": 401, "description": "Invalid action" },
{ "code": 402, "description": "Invalid args" },
{ "code": 404, "description": "Invalid var" },
{ "code": 412, "description": "Precondition failed" },
{ "code": 501, "description": "Action failed" },
{ "code": 600, "description": "Argument value invalid" },
{ "code": 601, "description": "Argument value out of range" },
{ "code": 602, "description": "Optional action not implemented" },
{ "code": 603, "description": "Out of memory" },
{ "code": 604, "description": "Human intervention required" },
{ "code": 605, "description": "String argument too long" },
{ "code": 606, "description": "Action not authorized" },
{ "code": 607, "description": "Signature failure" },
{ "code": 608, "description": "Signature missing" },
{ "code": 609, "description": "Not encrypted" },
{ "code": 610, "description": "Invalid sequence" },
{ "code": 611, "description": "Invalid control URL" },
{ "code": 612, "description": "No such session" }
]
}