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-7 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_777')  # 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-7 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 = None

The alarm’s start time.

Type:datetime.time
duration = None

The alarm’s duration.

Type:datetime.time
enabled = None

True if the alarm is enabled, else False.

Type:bool
program_uri = None
program_metadata = None

The uri to play.

Type:str
include_linked_zones = None

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

Type:bool
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
volume

The alarm’s volume (0-100).

Type:int
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.

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.

soco.alarms.get_alarms(zone=None)[source]

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

Parameters:zone (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.