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 formON_DDDDDD
whereD
is a number from 0-6 representing a day of the week (Sunday is 0), e.g.ON_034
meaning Sunday, Wednesday and ThursdayParameters: text (str) – the recurrence string to check. Returns: True
if the recurrence string is valid, elseFalse
.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
[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.
-
last_alarm_list_version
¶ Return last seen alarm list version.
-
-
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 toNone
. - recurrence (str, optional) – A string representing how
often the alarm should be triggered. Can be
DAILY
,ONCE
,WEEKDAYS
,WEEKENDS
or of the formON_DDDDDD
whereD
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 toDAILY
. - enabled (bool, optional) –
True
if alarm is enabled,False
otherwise. Defaults toTrue
. - program_uri (str, optional) – The uri to play. If
None
, the built-in Sonos chime sound will be used. Defaults toNone
. - 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 toNORMAL
. - 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 toFalse
.
-
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
-
recurrence
¶ How often the alarm should be triggered.
Can be
DAILY
,ONCE
,WEEKDAYS
,WEEKENDS
or of the formON_DDDDDDD
whereD
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.
- zone (
-
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
instancesReturn type: set