soco.groups module

This module contains classes and functionality relating to Sonos Groups.

class soco.groups.ZoneGroup(uid, coordinator, members=None)[source]

A class representing a Sonos Group. It looks like this:

ZoneGroup(
    uid='RINCON_000FD584236D01400:58',
    coordinator=SoCo("192.168.1.101"),
    members={SoCo("192.168.1.101"), SoCo("192.168.1.102")}
)

Any SoCo instance can tell you what group it is in:

>>> device = soco.discovery.any_soco()
>>> device.group
ZoneGroup(
    uid='RINCON_000FD584236D01400:58',
    coordinator=SoCo("192.168.1.101"),
    members={SoCo("192.168.1.101"), SoCo("192.168.1.102")}
)

From there, you can find the coordinator for the current group:

>>> device.group.coordinator
SoCo("192.168.1.101")

or, for example, its name:

>>> device.group.coordinator.player_name
Kitchen

or a set of the members:

>>> device.group.members
{SoCo("192.168.1.101"), SoCo("192.168.1.102")}

For convenience, ZoneGroup is also a container:

>>> for player in device.group:
...   print player.player_name
Living Room
Kitchen

If you need it, you can get an iterator over all groups on the network:

>>> device.all_groups
<generator object all_groups at 0x108cf0c30>

A consistent readable label for the group members can be returned with the label and short_label properties.

Properties are available to get and set the group volume and the group mute state, and the set_relative_volume() method can be used to make relative adjustments to the group volume, e.g.:

>>> device.group.volume = 25
>>> device.group.volume
25
>>> device.group.set_relative_volume(-10)
15
>>> device.group.mute
>>> False
>>> device.group.mute = True
>>> device.group.mute
True

Parameters

uid (str) – The unique Sonos ID for this group, eg RINCON_000FD584236D01400:5.
coordinator (SoCo) – The SoCo instance representing the coordinator of this group.
members (Iterable[SoCo]) – An iterable containing SoCo instances which represent the members of this group.

uid: The unique Sonos ID for this group

coordinator: The SoCo instance which coordinates this group

members: A set of SoCo instances which are members of the group

property label

A description of the group.

>>> device.group.label
'Kitchen, Living Room'

Type: str

property short_label

A short description of the group.

>>> device.group.short_label
'Kitchen + 1'

Type: str

property volume

The volume of the group.

An integer between 0 and 100.

Type: int

property mute

The mute state for the group.

True or False.

Type: bool

set_relative_volume(relative_group_volume)[source]

Adjust the group volume up or down by a relative amount.

If the adjustment causes the volume to overshoot the maximum value of 100, the volume will be set to 100. If the adjustment causes the volume to undershoot the minimum value of 0, the volume will be set to 0.

Note that this method is an alternative to using addition and subtraction assignment operators (+=, -=) on the volume property of a ZoneGroup instance. These operators perform the same function as set_relative_volume() but require two network calls per operation instead of one.

Parameters: relative_group_volume (int) – The relative volume adjustment. Can be positive or negative.
Returns: The new group volume setting.
Return type: int
Raises: ValueError – If relative_group_volume cannot be cast as an integer.