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-7 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_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 beNone
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-7 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
.
-
start_time
= None¶ datetime.time
– The alarm’s start time.
-
duration
= None¶ datetime.time
– The alarm’s duration.
-
program_uri
= None¶
-
include_linked_zones
= None¶ bool
–True
if the alarm should be played on the other speakers in the same group,False
otherwise.
-
play_mode
¶ str
– The play mode for the alarm.Can be one of
NORMAL
,SHUFFLE_NOREPEAT
,SHUFFLE
,REPEAT_ALL
,REPEAT_ONE
,SHUFFLE_REPEAT_ONE
.
-
recurrence
¶ str
– 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.
-
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.
- zone (
-
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 toNone
.Returns: A set of Alarm
instancesReturn type: set Note
Any existing
Alarm
instance will have its attributes updated to those currently stored on the Sonos system.