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.

update_skipped(zone)[source]: Update the zone for any skipped alarms and move to main list if possible.

get_next_alarm_datetime(from_datetime=None, include_disabled=False, zone_uid=None)[source]

Get the next alarm trigger datetime.

Parameters:

from_datetime (datetime, optional) – a datetime to reference next alarms from. This argument filters by alarms on or after this exact time. Since alarms do not store timezone information, the output timezone will match this input argument. Defaults to datetime.now().
include_disabled (bool, optional) – If True then disabled alarms will be included in searching for the next alarm. Defaults to False.
zone_uid (str, optional) – If set the alarms will be filtered by zone with this UID. Defaults to None.

Returns:

The next alarm trigger datetime or None if disabled

Return type:

datetime

Note

Alarms in alarms_skipped (whose speaker was not registered at the time of the last update()) are not considered.

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, room_uuid=None)[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.
room_uuid (str, optional) – The UUID of the room/speaker this alarm belongs to. Set automatically when loading alarms from the Sonos system. Defaults to None.

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.
SoCoException – if zone is None (alarm was loaded for a speaker that was not yet registered). Call Alarms.update_skipped() with the zone once it is available before saving.

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

get_next_alarm_datetime(from_datetime=None, include_disabled=False)[source]

Get the next alarm trigger datetime.

Parameters:

from_datetime (datetime, optional) – a datetime to reference next alarms from. This argument filters by alarms on or after this exact time. Since alarms do not store timezone information, the output timezone will match this input argument. Defaults to datetime.now().
include_disabled (bool, optional) – If True then the next datetime will be computed even if the alarm is disabled. Defaults to False.

Returns:

The next alarm trigger datetime or None if disabled

Return type:

datetime

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.