soco.alarms module

This module contains classes relating to Sonos Alarms.

soco.alarms.is_valid_recurrence(text)

Check that text is a valid recurrence string.

A valid recurrence string is DAILY, ONCE, WEEKDAYS, WEEKENDS or of the form ON_DDDDDD where D is a number from 0-6 representing a day of the week (Sunday is 0), e.g. ON_034 meaning Sunday, Wednesday and Thursday

Parameters

text (str) – the recurrence string to check.

Returns

True if the recurrence string is valid, else False.

Return type

bool

Examples

>>> from soco.alarms import is_valid_recurrence
>>> is_valid_recurrence('WEEKENDS')
True
>>> is_valid_recurrence('')
False
>>> is_valid_recurrence('ON_132')  # Mon, Tue, Wed
True
>>> is_valid_recurrence('ON_666')  # Sat
True
>>> is_valid_recurrence('ON_3421') # Mon, Tue, Wed, Thur
True
>>> is_valid_recurrence('ON_123456789') # Too many digits
False

class soco.alarms.Alarms(*args, **kwargs)

A class representing all known Sonos Alarms.

Is a singleton and every Alarms() object will return the same instance.

Example use:

>>> get_alarms()
{469: <Alarm id:469@22:07:41 at 0x7f5198797dc0>,
 470: <Alarm id:470@22:07:46 at 0x7f5198797d60>}
>>> alarms = Alarms()
>>> alarms.update()
>>> alarms.alarms
{469: <Alarm id:469@22:07:41 at 0x7f5198797dc0>,
 470: <Alarm id:470@22:07:46 at 0x7f5198797d60>}
>>> for alarm in alarms:
...     alarm
...
<Alarm id:469@22:07:41 at 0x7f5198797dc0>
<Alarm id:470@22:07:46 at 0x7f5198797d60>
>>> alarms[470]
<Alarm id:470@22:07:46 at 0x7f5198797d60>
>>> new_alarm = Alarm(zone)
>>> new_alarm.save()
471
>>> new_alarm.recurrence = "ONCE"
>>> new_alarm.save()
471
>>> alarms.alarms
{469: <Alarm id:469@22:07:41 at 0x7f5198797dc0>,
 470: <Alarm id:470@22:07:46 at 0x7f5198797d60>,
 471: <Alarm id:471@22:08:40 at 0x7f51987f1b50>}
>>> alarms[470].remove()
>>> alarms.alarms
{469: <Alarm id:469@22:07:41 at 0x7f5198797dc0>,
 471: <Alarm id:471@22:08:40 at 0x7f51987f1b50>}
>>> for alarm in alarms:
...     alarm.remove()
...
>>> a.alarms
{}

Initialize the instance.

property last_alarm_list_version

Return last seen alarm list version.

get(alarm_id)

Return the alarm by ID or None.

update(zone=None)

Update all alarms and current alarm list version.

Raises

SoCoException – If the ‘CurrentAlarmListVersion’ value is unexpected. May occur if the provided zone is from a different household.

class soco.alarms.Alarm(zone, start_time=None, duration=None, recurrence='DAILY', enabled=True, program_uri=None, program_metadata='', play_mode='NORMAL', volume=20, include_linked_zones=False)

A class representing a Sonos Alarm.

Alarms may be created or updated and saved to, or removed from the Sonos system. An alarm is not automatically saved. Call save() to do that.

Parameters

• zone (SoCo) – The soco instance which will play the alarm.

• start_time (datetime.time, optional) – The alarm’s start time. Specify hours, minutes and seconds only. Defaults to the current time.

• duration (datetime.time, optional) – The alarm’s duration. Specify hours, minutes and seconds only. May be None for unlimited duration. Defaults to None.

• recurrence (str, optional) – A string representing how often the alarm should be triggered. Can be DAILY, ONCE, WEEKDAYS, WEEKENDS or of the form ON_DDDDDD where D is a number from 0-6 representing a day of the week (Sunday is 0), e.g. ON_034 meaning Sunday, Wednesday and Thursday. Defaults to DAILY.

• enabled (bool, optional) – True if alarm is enabled, False otherwise. Defaults to True.

• program_uri (str, optional) – The uri to play. If None, the built-in Sonos chime sound will be used. Defaults to None.

• program_metadata (str, optional) – The metadata associated with ‘program_uri’. Defaults to ‘’.

• play_mode (str, optional) – The play mode for the alarm. Can be one of NORMAL, SHUFFLE_NOREPEAT, SHUFFLE, REPEAT_ALL, REPEAT_ONE, SHUFFLE_REPEAT_ONE. Defaults to NORMAL.

• volume (int, optional) – The alarm’s volume (0-100). Defaults to 20.

• include_linked_zones (bool, optional) – True if the alarm should be played on the other speakers in the same group, False otherwise. Defaults to False.

update(**kwargs)

Update an existing Alarm instance using the same arguments as __init__.

property play_mode

The play mode for the alarm.

Can be one of NORMAL, SHUFFLE_NOREPEAT, SHUFFLE, REPEAT_ALL, REPEAT_ONE, SHUFFLE_REPEAT_ONE.

Type

str

property volume

The alarm’s volume (0-100).

Type

int

property recurrence

How often the alarm should be triggered.

Can be DAILY, ONCE, WEEKDAYS, WEEKENDS or of the form ON_DDDDDDD where D is a number from 0-7 representing a day of the week (Sunday is 0), e.g. ON_034 meaning Sunday, Wednesday and Thursday.

Type

str

save()

Save the alarm to the Sonos system.

Returns

The alarm ID, or None if no alarm was saved.

Return type

str

Raises

SoCoUPnPException – if the alarm cannot be created because there is already an alarm for this room at the specified time.

remove()

Remove the alarm from the Sonos system.

There is no need to call save. The Python instance is not deleted, and can be saved back to Sonos again if desired.

Returns

If the removal was sucessful.

Return type

bool

property alarm_id

The ID of the alarm, or None.

Type

str

soco.alarms.get_alarms(zone=None)

Get a set of all alarms known to the Sonos system.

Parameters

zone (soco.SoCo, optional) – a SoCo instance to query. If None, a random instance is used. Defaults to None.

Returns

A set of Alarm instances

Return type

set

soco.alarms.remove_alarm_by_id(zone, alarm_id)

Remove an alarm from the Sonos system by its ID.

Parameters

• zone (SoCo) – A SoCo instance, which can be any zone that belongs to the Sonos system in which the required alarm is defined.

• alarm_id (str) – The ID of the alarm to be removed.

Returns

True if the alarm is found and removed, False otherwise.

Return type

bool

soco.alarms.parse_alarm_payload(payload, zone)

Parse the XML payload response and return a dict of Alarm kwargs.