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.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.

Example

>>> device = discovery.any_soco()
>>> # create an alarm with default properties
>>> alarm = Alarm(device)
>>> print alarm.volume
20
>>> print get_alarms()
set([])
>>> # save the alarm to the Sonos system
>>> alarm.save()
>>> print get_alarms()
set([<Alarm id:88@15:26:15 at 0x107abb090>])
>>> # update the alarm
>>> alarm.recurrence = "ONCE"
>>> # Save it again for the change to take effect
>>> alarm.save()
>>> # Remove it
>>> alarm.remove()
>>> print get_alarms()
set([])

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.

start_time

The alarm’s start time.

Type: datetime.time

duration

The alarm’s duration.

Type: datetime.time

enabled

True if the alarm is enabled, else False.

Type: bool

program_uri

program_metadata

The uri to play.

Type: str

include_linked_zones

True if the alarm should be played on the other speakers in the same group, False otherwise.

Type: bool

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.

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

Note

Any existing Alarm instance will have its attributes updated to those currently stored on the Sonos system.

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