Alarm Portal

[Mikenux]

Notes

• This portal does not necessarily replace what is done for version 2 of the notification portal.
• What is presented in this proposal is subject to discussion. Any limitation may be reduced or removed if justified.

Target Apps

The targets are apps that use alarm clocks (i.e. alarms that ring at specific times).

Currently, only classic alarm clocks (i.e. alarms that ring at a specific time and can be snoozed) are targeted here. Other types of alarms may be added in the future, with discussion.

Goals

• Clearly identify what an alarm is compared to another (scheduled) activity of an app.
• Use this identification to save power and/or computing resources by deferring other (scheduled) activities of an app, while still allowing alarms to ring.
• Use this identification to limit potential abuse of alarm use by an app.
• If relevant, make alarms ring without their app being launched if launching an app consumes energy.
• Maybe have a single toggle to allow alarm notifications in Do Not Disturb mode (as a mode to not be visually disturbed by notifications), since this portal imposes limits. It depends on what can be said in the system settings user interface.

Requirements

• The portal must send information about alarm properties and automatic application startup to the relevant system components.

Classic Alarm

Add Classic Alarm

"AddClassicAlarm" is a method to register a classic alarm clock.

This method can be used only if the app is focused.

An app adds an alarm using the following properties:

• name. Alarm name. Mandatory.
• description. Description of the alarm. Optional.
• ringtone. Play a ringtone for the alarm. Mandatory. Note that the system may use its own audio file for playback, depending on the ringtone option used by the app (see below) and its state (e.g. a power saving mode that does not allow much app activity or the unavailability of an Internet connection).
  • default. Use the system default ringtone.
  • file. Audio file that the app has access to. The audio file format must be supported by the portal.
  • app. Play sound on the app side. If "app" is used, it must also be specified "local" for local playback, or "internet" for playback of a stream from the Internet.
• vibration_pattern. Play a vibration pattern for the alarm. Optional. The app probably needs access to the vibration device first. TODO.
• light_pattern. Play a light pattern using screen brightness or LEDs, with or without colors. Optional. The app probably needs access to screen brightness and/or LED devices first. TODO.
• days. Days the alarm must ring. Mandatory.
• ringing_time. Time at which the alarm must ring. Mandatory.
• ringing_duration. Duration during which the alarm must ring. Mandatory.
• snooze_duration. How long the alarm snoozes before ringing again. Duration in minutes which cannot exceed 15 minutes (maybe less?). If left blank or the value is 0 (zero), a default value is used. Optional.
• ringing_number. Number of times the alarm can be repeated (relative to snooze). Optional.
• activation_state. "on" to indicate the alarm must ring, or "off" to indicate the alarm must not ring. Mandatory.
• show_app_action. Action to invoke to show the alarm in the app when it is ringing or snoozing. The app is expected to open a window in which the ringing or snoozing alarm is displayed with options to stop or snooze the alarm. Optional.
• sensitivity_session. Sensitivity of alarm notification content within user session. TODO.
• sensitivity_lockscreen. Sensitivity of alarm notification content displayed on the lockscreen. TODO.

When an alarm is added, the portal returns the following response to the app:

• alarm_id. Alarm ID determined by the portal for the alarm just added.

Only one alarm can be added at a time. An app can only add another alarm after receiving the "alarm_id" of a previously added alarm.

"app" option of the "ringtone" property

An app can only use this option if its sound can be reliably muted by the system and the app does not have any permissions to override this muting.

Alarm Ringing and App Autostart

• An alarm added with its "activation_state" property set to "on" rings at its ringing time.
• If an alarm has its "ringtone" property set to the "app" option, the app is launched [duration to be defined] before its ringing time if it is not already running. The app automatically starts hidden (if possible) and its sound is muted before its ringing time. It also must be ready to be killed after the user activates the "Stop" action from an alarm notification (see below).
• When an alarm sounds, a "ringing" notification (or equivalent) is displayed (see below).

"Ringing" Notification

This notification is presented to the user with the following properties:

• name.
• description.
• day. The current day the alarm is ringing.
• ringing_time. If the alarm rings again, the ringing time is displayed as the original ringing time.
• ringing_duration. For this property, a countdown based on this duration is recommended.
• ringing_number. The number of rings minus the number of times the alarm has already rang.

It is presented at the time the alarm rings and when the alarm snooze duration has elapsed ("snooze_duration" property). If the alarm rings again, the current ringing time (taken from the system clock) is also displayed.

The system plays the ringtone or the app plays its sound. For apps that play sound themselves, if the system does not detect any sound output from the app or if the app uses the "internet" option of the "app" option, it plays a default ringtone.

The notification has the actions "Snooze", "Stop" and "Show App" (see the "Actions" section below) as buttons and is displayed until an action is activated. The snooze duration is shown on the "Snooze" button.

"Snooze" Notification

This notification is presented briefly with the following properties:

• name.
• description.
• day. The current day the alarm is ringing.
• ringing_time. This is displayed as the original ringing time.
• snooze_duration. For this property, a countdown based on this duration is recommended.
• ringing_number. The number of rings minus the number of times the alarm has already rang.

If wanted, the time when the alarm will ring again ("original alarm ringing time" plus "snooze duration") without user action can also be displayed.

No sound is played when this notification is presented. The "Snooze" notification is accessible from the notification tray.

The notification has the actions "Snooze More", "Stop" and "Show App" (see the "Actions" section below) as buttons and is displayed until an action is activated. The snooze duration is shown on the "Snooze More" button.

When the snooze duration has elapsed, the alarm rings again with a "Ringing" notification, unless the "ringing_number" property is set to "1".

Actions

Actions are managed by the portal. An app cannot decide whether to display them or not.

Snooze / Snooze More

When the "Snooze" or "Snooze More" action is activated, it does the following:

• The sound is no longer played or is muted until the snooze duration has elapsed. If the sound comes from a file, the system stops playing it. If it comes from the app, the sound is muted.
• A Snooze notification is displayed (see relevant section above).
• A "snoozed" signal is sent (see the "Signals" section below).

Stop

When the "Stop" action is activated, a "stop" signal is sent (see "Signals" section below), the alarm notification is removed and the alarm cannot ring again.

Show App

When the "Show App" action is activated, the action defined in the "show-app-action" property of the alarm is used. If nothing is defined, the app is simply launched and presented to the user. From the app, it is expected that the user can trigger snooze and stop actions. When one of these actions is triggered from the app, it uses the "SetAlarmState" method to set the "snoozed" or "stopped" state for the currently active alarm (see the "Set Alarm State" section below).

Additionally, the application cannot modify:

• the currently active alarm until it sets its alarm state to "stopped";
• the other alarms until it sets the state of the currently active alarm to "snoozed".

Signals

There are two signals: "snoozed" and "stopped". The relevant signal is sent to the app if it is running. If the app is not running, the signal is stored and will be sent when the app is launched. This lets the app know that an alarm has actually rang or been snoozed to update its user interface accordingly.

Set Alarm State

The "SetAlarmState" is a method for setting the alarm states of an already added alarm.

This method can only be used if the app is focused.

The following properties are used:

• alarm_id. Alarm ID given by the portal. It is required for setting any state.
• activation_state. "on" to indicate the alarm must ring, or "off" to indicate the alarm must not ring. This changes the value of alarm's "activation_state" property.
• classic_state. See the "States Specific to Classic Alarms" section below.

States Specific to Classic Alarms

For classic alarms, there is the "classic_state" with which two states can be set:

• snoozed. Tell the alarm to snooze. The "alarm_id" must correspond to that of an alarm currently ringing and belonging to the app. When used, the portal sends a Snooze notification (see the relevant section above).
• stopped. Tell the alarm to stop. The "alarm_id" must correspond to that of an alarm currently ringing and belonging to the app. When used, the notification for the specified alarm is removed and the alarm cannot ring again.

Play System Ringtone

"PlaySystemRingtone" is a method to play the default ringtone used by the system.

This method can only be used if the app is focused.

It provides the following options:

• play. Play the ringtone.
• pause. Pause ringtone playback.
• stop. Stop playing the ringtone.

Alarm Manager

An alarm manager is used to manage alarms. There are two types of management which are described in the subsections below.

"Too Many!" Management

The "Too Many!" management detects when too many alarms are added and/or activated. When this is the case, the portal notifies the user.

The portal notifies the user when the following global conditions (i.e. not per application) are met directly or after closing an app:

• If more than 1 alarm is added or activated within a 5 minute window.
• If more than 2 alarms are added or activated within a 15 minute window.
• If more than 3 alarms are added or activated within a 30, 45 and 60 minute window.
• If more than 8 alarms are added or activated in a 24 hour time window.

The first three conditions are checked from midnight to midnight every 60 minutes. The last one is global.

The portal notifies with a window presenting all the added and/or activated alarms (regardless of the app). Alarms are displayed with their name, ringing time, ringtone, on/off state and the app they belong to, with their description possibly behind a button. They are sorted by ringing time. When this window is displayed, the app is not allowed to add or activate an alarm, and no "alarm_id" is returned to the application.

When reviewing alarms, the user has two options:

• Deletion of alarms. The user can delete alarms from an app if they notices one that should not have been added or activated, or has an incorrect on/off state. The option is to delete all alarms from an app if any of them is suspicious. Deleting alarms from an app means that the portal permanently blocks any addition and activation of alarms from this app.
• Approval of alarms. If the user considers that all the alarms are correct, after possibly deleting some of them, they can approves them. Upon approval and if no alarms have been deleted, the portal returns an "alarm_id" for an added alarm or emits a "done" signal for an activated alarm. If an alarm has been deleted, the portal informs the user that the app can no longer add or activate alarms, and no "alarm_id" is returned or no "done" signal is emitted.

Note that it is possible to separate the review of added alarms without displaying their on/off state from activated alarms. In this case, this is done in two steps. When added alarms are deleted, they do not appear when displaying activated alarms.

Activation Conflict Management

Activation conflict management consists of detecting activated alarms (i.e. "on" state) whose ringing times conflict and allowing the user to resolve them.

When the ringing times of the alarms conflict, a window is displayed to present them to the user with their names (and their description possibly behind a button), their ringtone and the app to which they belong. Alarms are sorted by ringing time.

There are two possible actions:

• Merge alarms. This allows alarms to be merged to have only one ringtone instead of several at the same time. The user chooses one of the specified alarm ringtones if any or the default system ringtone. The "app" option to play audio on the app side is not available when merging. Merging alarms means that they will be presented as a single notification displaying all alarms with their respective descriptions and actions.
• Delete alarms. The user has the option to delete alarms from an app if they notices one that should not have been activated. The option is to delete all alarms from an app if any of them is suspicious.

When the user has validated the merges and/or deletions, the portal emits a "done" signal to the app if its alarm has not been deleted. If the app alarm has been deleted, the portal permanently blocks any addition and activation of alarms from this app and does not emit a "done" signal. In case an alarm using app-side sound playback is merged, the app will still start automatically, but with its sound muted until its alarm is stopped.

Conflicting Alarms Due to Snoozing

When alarms ring at the same time due to snoozing, no window to manage the conflict is displayed. Instead, the sound level of alarms is manipulated. If an alarm rings for the first time due to its ringing time, reduce the sound level of alarms that ring again after snoozing. If all alarms have been snoozed and ring again at the same time, lower the sound level of all except the alarm with the latest ringing time. To lower the sound level of alarms played on the app side, the relevant apps need an audio portal or other mechanism; Otherwise, use the sound played by an app as the highest sound level.

Lowering sound volumes for conflicting alarms due to snoozing can be included in the portal for a cross-desktop user experience. However, this is not required and can be done by desktop environments based on their preferences.

Too Many and Conflicting Alarms

If there are too many alarms and conflicting activated alarms at the same time, first display the "too many alarms" window, then the "conflicting alarms" window.

Classic Alarm: "Notification" Drawn Over App

When an alarm rings or snoozes, the relevant notification can be displayed over the app when it is running, focused, or opened from the "Show App" action. The "Sow App" action can instead be an action to display an enlarged notification. This allows all actions to be reliable. However, offering customization options is necessary and to be defined.

This removes from the proposal:

• The "show_app_action" property of the "AddClassicAlarm" method.
• The "classic_state" option and the states specific to classic alarms of the "SetAlarmState" method.

Questions

• Is registration of all alarms necessary? As it stands, only registering the alarms that must ring is necessary. However, this is necessary if presenting alarms to activate and deactivate them from, for example, a widget is wanted. This would also avoid having to add and remove alarms each time; it would just be a matter of activating/deactivating them (this argument does not seem strong to me). Note that this user experience question is aimed more at desktop environment developers.
• Is the "ringing_number" property of a classic alarm necessary compared to no repetition limitation?
• The snooze duration cannot exceed 15 minutes. Is it a correct value?
• What duration to use to automatically start an app before its ringing time?
• What should happen when the ringing duration of an alarm has elapsed and the user takes no action? Should the alarm be stopped or snoozed? Or should the app choose the user experience? What is the point of having an alarm that automatically stops if the user does nothing?
• Are there any other conditions needed for "Too Many!" management? Other limitations are welcome.
• Should a "Change Management" be included that would inform about the deletion and deactivation of alarms?
• What do you think about drawing a "notification" over an app?

[Mikenux]

Updates to the proposal

[Mikenux]

Update 1 - use the "edited" button in the proposal post:

• Clarifications.
• Added signals in conflict management.
• Added a question about the snooze duration.