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 Thursday- Parameters
text (str) – the recurrence string to check.
- Returns
- Return type
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.
- 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.
- 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 toFalse
.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
- 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
.
- 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
- property 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
- save()[source]
Save the alarm to the Sonos system.
- Returns
The alarm ID, or
None
if no alarm was saved.- Return type
- 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.- Returns
If the removal was sucessful.
- Return type
- 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 toFalse
.
- Returns
The next alarm trigger datetime or None if disabled
- Return type
datetime