The groups object in the groups namespace describes the current set of logical players and groups in the household. Use the getGroups command to get a groups object.
Parameters
See the Control documentation for descriptions of parameters in the header. See the table below for descriptions of parameters in the body.
group object
Describes one group in a household.
| Parameter | Type | Value |
|---|---|---|
coordinatorId | string | The ID of the player acting as the group coordinator for the group. This is a playerId value. |
id | string | The ID of the group. |
playbackState | string | The playback state corresponding to the group. This is only sent back in the getGroups response as we otherwise you would receive a new groups event every time the playback state changed, which could be a lot of events! |
playerIds | array | The IDs of the primary players in the group. For example, only one player from each set of players bonded as a stereo pair or as satellites to a home theater setup. Each element is the ID of a player. This list includes the coordinatorId. |
name | string | The display name for the group, such as “Living Room” or “Kitchen + 2”. |
player object
Added in version 1.5.0. Describes one logical speaker in a household. A logical speaker could be a single stand-alone device or a set of bonded devices. For example, two players bonded as a stereo pair, two surrounds and a SUB bonded with a PLAYBAR in a home theater setup, or a player bonded with a SUB.
| Parameter | Type | Value |
|---|---|---|
apiVersion | string | The highest API version supported by the player. |
deviceIds | array | The IDs of all bonded devices corresponding to this logical player. |
icon | string | An identifier for the player icon. Set when the user chooses a pre-defined room for the player. You can map this to an icon to display in your app for the player. Values include, but aren't limited to, any of the following: - bathroom - den - foyer - garage - hallway - library - office - playroom - portableNote: Sonos sends “generic” if the user set up a custom room in the Sonos app. |
id | string | The ID of the player. |
minApiVersion | string | The lowest API version supported by the player. |
name | string | The display name for the player. For example, “Living Room”, “Kitchen”, or “Dining Room”. |
softwareVersion | string | The version of the software running on the device. |
webSocketUrl | string | The secure WebSocket URL for the device. See Connect for details. |
capabilities | capabilities | The set of capabilities provided by the player. |
capabilities
The set of capabilities provided by the player. For example, a player can be AIRPLAY capable and have LINE_IN capability.
| Value | Type | Description |
|---|---|---|
PLAYBACK | string | The player can produce audio. You can target it for playback. |
CLOUD | string | The player can send commands and receive events over the internet. |
HT_PLAYBACK | string | The player is a home theater source. It can reproduce the audio from a home theater system, typically delivered by S/PDIF or HDMI. |
HT_POWER_STATE | string | The player can control the home theater power state. For example, it can switch a connected TV on or off. |
AIRPLAY | string | Added in version 1.5.1. The player can host AirPlay streams. This capability is present when the device is advertising AirPlay support. |
LINE_IN | string | Added in version 1.6.0. The player has an analog line-in. See Using Line-In on Sonos on the Sonos Support site for more details about the line-in capabilities of our players. |
AUDIO_CLIP | string | Added in version 1.7.0. The device is capable of playing audio clip notifications. See the audioClip namespace for details. |
VOICE | string | Added in version 1.10.0. The device supports the voice namespace (not yet implemented). |
SPEAKER_DETECTION | string | Added in version 1.10.0. The component device is capable of detecting connected speaker drivers. |
FIXED_VOLUME | string | Added in version 1.11.1. The device supports fixed volume. See setPlayerSettings and the groups object for details. |
Example
{
"groups": [
{
"id": "RINCON_7BHBFF96BF5A34300", // PlayroomPlayerIdGroupId
"name": "Playroom",
"coordinatorId": "RINCON_8HJLQE01RW4B21097", // PlayroomPlayerId
"playbackState": "PLAYBACK_STATE_IDLE",
"playerIds": [
"RINCON_8HJLQE01RW4B21097" // PlayroomPlayerId
]
},
{
"id": "RINCON_A8E9677G21B091499", // MasterBRPlayerIdGroupId
"name": "Master Bedroom + 1",
"coordinatorId": "RINCON_Y6C3211GJ59H88131", // MasterBRPlayerId
"playbackState": "PLAYBACK_STATE_IDLE",
"playerIds": [
"RINCON_Y6C3211GJ59H88131", // MasterBRPlayerId
"RINCON_B8E9377C21G061890" // BackPorchPlayerId
]
},
{
"id": "RINCON_Z4H7803J17K741322", // FamilyRoomPlayerIdGroupId
"name": "Family Room + 2",
"coordinatorId": "RINCON_D7Y5432M12H127890", // FamilyRoomPlayerId
"playbackState": "PLAYBACK_STATE_IDLE",
"playerIds": [
"RINCON_A4E9395C21G061898", // KitchenPlayerId
"RINCON_C4T1256L09Q293216", // SunRoomPlayerId
"RINCON_D7Y5432M12H127890" // FamilyRoomPlayerId
]
},
],
"players": [
{
"id": "RINCON_8HJLQE01RW4B21097", // PlayroomPlayerId
"name": "Playroom",
"icon": "playroom",
"websocketUrl": "wss://192.168.55.135:1443/websocket/api",
"softwareVersion": "38.5-43170-DevPreview",
"deviceIds": [
"RINCON_8HJLQE01RW4B21097" // PlayroomPlayerId
],
"apiVersion": "1.0.0-DevPreview+1234",
"minApiVersion": "1.0.0",
"capabilities" : [
"PLAYBACK",
"CLOUD"
]
},
{
"id": "RINCON_Y6C3211GJ59H88131", // MasterBRPlayerId
"name": "Master Bedroom",
"icon": "masterbedroom",
"websocketUrl": "wss://192.168.55.176:1443/websocket/api",
"softwareVersion": "38.5-43170-DevPreview",
"deviceIds": [
"RINCON_Y6C3211GJ59H88131" // MasterBRPlayerId
],
"apiVersion": "1.0.0-DevPreview+1234",
"minApiVersion": "1.0.0",
"capabilities" : [
"PLAYBACK",
"CLOUD",
"AIRPLAY"
]
},
{
"id": "RINCON_B8E9377C21G061890", // BackPorchPlayerId
"name": "Back Porch",
"icon": "livingroom",
"websocketUrl": "wss://192.168.55.244:1443/websocket/api",
"softwareVersion": "38.5-43170-DevPreview",
"deviceIds": [
"RINCON_B8E9377C21G061890" // BackPorchPlayerId
],
"apiVersion": "1.0.0-DevPreview+1234",
"minApiVersion": "1.0.0",
"capabilities" : [
"PLAYBACK",
"CLOUD"
]
},
{
"id": "RINCON_A4E9395C21G061898", // KitchenPlayerId
"name": "Kitchen",
"icon": "kitchen",
"websocketUrl": "wss://192.168.55.241:1443/websocket/api",
"softwareVersion": "38.5-43170-DevPreview",
"deviceIds": [
"RINCON_A4E9395C21G061898", // KitchenPlayerId
"RINCON_B5R0432H68L104369" // KitchenRightPlayerId
],
"apiVersion": "1.0.0-DevPreview+1234",
"minApiVersion": "1.0.0",
"capabilities" : [
"PLAYBACK",
"CLOUD"
]
},
{
"id": "RINCON_C4T1256L09Q293216", // SunRoomPlayerId
"name": "Sun Room",
"icon": "kitchen",
"websocketUrl": "wss://192.168.55.187:1443/websocket/api",
"softwareVersion": "38.5-43170-DevPreview",
"deviceIds": [
"RINCON_C4T1256L09Q293216" // SunRoomPlayerId
],
"apiVersion": "1.0.0-DevPreview+1234",
"minApiVersion": "1.0.0",
"capabilities" : [
"PLAYBACK",
"CLOUD"
]
},
{
"id": "RINCON_D7Y5432M12H127890", // FamilyRoomPlayerId
"name": "Family Room",
"icon": "familyroom",
"websocketUrl": "wss://192.168.55.166:1443/websocket/api",
"softwareVersion": "38.5-43170-DevPreview",
"deviceIds": [
"RINCON_D7Y5432M12H127890", // FamilyRoomPlayerId
"RINCON_E6O0329J63L098571" // FamilyRoomSubPlayerId
],
"apiVersion": "1.0.0-DevPreview+1234",
"minApiVersion": "1.0.0",
"capabilities" : [
"PLAYBACK",
"CLOUD",
"AIRPLAY",
"HT_PLAYBACK",
"HT_POWER_STATE"
]
}
]
}
{
"groups": [
{
"id": "RINCON_7BHBFF96BF5A34300", // PlayroomPlayerIdGroupId
"name": "Playroom",
"coordinatorId": "RINCON_8HJLQE01RW4B21097", // PlayroomPlayerId
"playbackState": "PLAYBACK_STATE_IDLE",
"playerIds": [
"RINCON_8HJLQE01RW4B21097" // PlayroomPlayerId
]
},
{
"id": "RINCON_A8E9677G21B091499", // MasterBRPlayerIdGroupId
"name": "Master Bedroom + 1",
"coordinatorId": "RINCON_Y6C3211GJ59H88131", // MasterBRPlayerId
"playbackState": "PLAYBACK_STATE_IDLE",
"playerIds": [
"RINCON_Y6C3211GJ59H88131", // MasterBRPlayerId
"RINCON_B8E9377C21G061890" // BackPorchPlayerId
]
},
{
"id": "RINCON_Z4H7803J17K741322", // FamilyRoomPlayerIdGroupId
"name": "Family Room + 2",
"coordinatorId": "RINCON_D7Y5432M12H127890", // FamilyRoomPlayerId
"playbackState": "PLAYBACK_STATE_IDLE",
"playerIds": [
"RINCON_A4E9395C21G061898", // KitchenPlayerId
"RINCON_C4T1256L09Q293216", // SunRoomPlayerId
"RINCON_D7Y5432M12H127890" // FamilyRoomPlayerId
]
},
],
"players": [
{
"id": "RINCON_8HJLQE01RW4B21097", // PlayroomPlayerId
"name": "Playroom",
"icon": "playroom",
"websocketUrl": "wss://192.168.55.135:1443/websocket/api",
"softwareVersion": "38.5-43170-DevPreview",
"deviceIds": [
"RINCON_8HJLQE01RW4B21097" // PlayroomPlayerId
],
"apiVersion": "1.0.0-DevPreview+1234",
"minApiVersion": "1.0.0",
"capabilities" : [
"PLAYBACK",
"CLOUD"
]
},
{
"id": "RINCON_Y6C3211GJ59H88131", // MasterBRPlayerId
"name": "Master Bedroom",
"icon": "masterbedroom",
"websocketUrl": "wss://192.168.55.176:1443/websocket/api",
"softwareVersion": "38.5-43170-DevPreview",
"deviceIds": [
"RINCON_Y6C3211GJ59H88131" // MasterBRPlayerId
],
"apiVersion": "1.0.0-DevPreview+1234",
"minApiVersion": "1.0.0",
"capabilities" : [
"PLAYBACK",
"CLOUD",
"AIRPLAY"
]
},
{
"id": "RINCON_B8E9377C21G061890", // BackPorchPlayerId
"name": "Back Porch",
"icon": "livingroom",
"websocketUrl": "wss://192.168.55.244:1443/websocket/api",
"softwareVersion": "38.5-43170-DevPreview",
"deviceIds": [
"RINCON_B8E9377C21G061890" // BackPorchPlayerId
],
"apiVersion": "1.0.0-DevPreview+1234",
"minApiVersion": "1.0.0",
"capabilities" : [
"PLAYBACK",
"CLOUD"
]
},
{
"id": "RINCON_A4E9395C21G061898", // KitchenPlayerId
"name": "Kitchen",
"icon": "kitchen",
"websocketUrl": "wss://192.168.55.241:1443/websocket/api",
"softwareVersion": "38.5-43170-DevPreview",
"deviceIds": [
"RINCON_A4E9395C21G061898", // KitchenPlayerId
"RINCON_B5R0432H68L104369" // KitchenRightPlayerId
],
"apiVersion": "1.0.0-DevPreview+1234",
"minApiVersion": "1.0.0",
"capabilities" : [
"PLAYBACK",
"CLOUD"
]
},
{
"id": "RINCON_C4T1256L09Q293216", // SunRoomPlayerId
"name": "Sun Room",
"icon": "kitchen",
"websocketUrl": "wss://192.168.55.187:1443/websocket/api",
"softwareVersion": "38.5-43170-DevPreview",
"deviceIds": [
"RINCON_C4T1256L09Q293216" // SunRoomPlayerId
],
"apiVersion": "1.0.0-DevPreview+1234",
"minApiVersion": "1.0.0",
"capabilities" : [
"PLAYBACK",
"CLOUD"
]
},
{
"id": "RINCON_D7Y5432M12H127890", // FamilyRoomPlayerId
"name": "Family Room",
"icon": "familyroom",
"websocketUrl": "wss://192.168.55.166:1443/websocket/api",
"softwareVersion": "38.5-43170-DevPreview",
"deviceIds": [
"RINCON_D7Y5432M12H127890", // FamilyRoomPlayerId
"RINCON_E6O0329J63L098571" // FamilyRoomSubPlayerId
],
"apiVersion": "1.0.0-DevPreview+1234",
"minApiVersion": "1.0.0",
"capabilities" : [
"PLAYBACK",
"CLOUD",
"AIRPLAY",
"HT_PLAYBACK",
"HT_POWER_STATE"
]
}
]
}