groups > groups

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.

Parameter Type Value
groups group A list of groups in the household. Each element is a group object.
players player A list of the players in the household. Each element is a player object.

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 any of the following:

  • bathroom
  • bedroom
  • den
  • diningroom
  • familyroom
  • foyer
  • garage
  • garden
  • generic
  • guestroom
  • hallway
  • kitchen
  • library
  • livingroom
  • masterbedroom
  • mediaroom
  • office
  • patio
  • playroom
  • pool
  • tvroom
  • portable

Note: 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