soco.alarms module

This module contains classes relating to Sonos Alarms.

soco.alarms.is_valid_recurrence(text)[source]

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)[source]

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)[source]: Return the alarm by ID or None.

update(zone=None)[source]

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)[source]

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)[source]: 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()[source]

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()[source]

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)[source]

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)[source]

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)[source]: Parse the XML payload response and return a dict of Alarm kwargs.