Pub Version Pub Likes Pub Points Pub Downloads

Alarm plugin for iOS and Android

This plugin offers a straightforward interface to set and cancel alarms on both iOS and Android devices. Using native code, it handles audio playback, vibrations, system volume, and notifications seamlessly.

📋 Table of contents

🔧 Installation steps
📖 How to use
📱 Example app
⏰ Alarm behaviour
📋 Logging
❓ FAQ
⚙️ Under the hood
✉️ Feature request
💙 Contributing

🔧 Installation steps

Please carefully follow these installation steps. They have been updated for plugin version 5.0.0.

iOS Setup

Android Setup

📖 How to use

Add to your pubspec.yaml:

flutter pub add alarm

First, you have to initialize the Alarm service in your main function:

WidgetsFlutterBinding.ensureInitialized();
await Alarm.init()

Then, you have to define your alarm settings:

final alarmSettings = AlarmSettings(
  id: 42,
  dateTime: dateTime,
  assetAudioPath: 'assets/alarm.mp3',
  loopAudio: true,
  vibrate: true,
  warningNotificationOnKill: Platform.isIOS,
  androidFullScreenIntent: true,
  volumeSettings: VolumeSettings.fade(
    volume: 0.8,
    fadeDuration: Duration(seconds: 5),
    volumeEnforced: true,
  ),
  notificationSettings: const NotificationSettings(
    title: 'This is the title',
    body: 'This is the body',
    stopButton: 'Stop the alarm',
    icon: 'notification_icon',
    iconColor: Color(0xff862778),
  ),
);

And finally set the alarm:

await Alarm.set(alarmSettings: alarmSettings)

AlarmSettings model

| Property | Type | Description | | --------------------------------------------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | int | Unique identifier of the alarm. | | dateTime | DateTime | The date and time you want your alarm to ring. | | assetAudioPath | String? | The path to you audio asset you want to use as ringtone. Can be a path in your assets folder or a local file path with Android permission. If null, the device's default alarm sound will be used. | | loopAudio | bool | If true, audio will repeat indefinitely until alarm is stopped. | | vibrate | bool | If true, device will vibrate indefinitely until alarm is stopped. If [loopAudio] is set to false, vibrations will stop when audio ends. | | warningNotificationOnKill | bool | Whether to show a notification when application is killed to warn the user that the alarm he set may not ring. Recommanded for iOS. Enabled by default. | | androidFullScreenIntent | bool | Whether to turn screen on when android alarm notification is triggered. Enabled by default. | | allowAlarmOverlap | bool | Whether the alarm should ring if another alarm is already ringing. Disabled by default. | | androidStopAlarmOnTermination | bool | Whether to stop the alarm when an Android task is terminated. Enabled by default. | | payload | String? | Optional data sent with the alarm. Caller handles serialization and parsing. | | notificationSettings | NotificationSettings | Settings for notification title, body, icon, icon color and action buttons (only stop at the moment). | | volumeSettings | VolumeSettings | Settings for alarm volume and fade durations. |

If you enabled warningNotificationOnKill, you can choose your own notification title and body by using this method before setting your alarms:

await Alarm.setWarningNotificationOnKill(title, body)

The property androidStopAlarmOnTermination works only on Android as on iOS the alarm is naturally stopped by the system when the app is terminated (as the native code can no longer run).

NotificationSettings model

| Property | Type | Description | | ------------------------------ | --------- | ---------------------------------------------------------------------------------- | | title | String | Title of the alarm notification. | | body | String | Body of the alarm notification. | | stopButton | String? | Text shown in the stop button of the alarm notification. Button not shown if null. | | icon | String? | Icon to display on the notification. Only customizable on Android. | | iconColor | Color? | Color of the notification icon. Only customizable on Android. | | keepNotificationAfterAlarmEnds | bool | Keeps the notification visible after the alarm sound ends. iOS only. |

VolumeSettings model

| Property | Type | Description | | -------------- | ---------------------- | ----------------------------------------------------------------------------------------------------------- | | volume | double? | Sets system volume level (0.0 to 1.0). Reverts on alarm stop. Defaults to current volume if null. | | fadeDuration | Duration? | Duration over which to fade the alarm ringtone. Null means no fade. | | fadeSteps | List<VolumeFadeStep> | Controls how the alarm volume will fade over time. | | volumeEnforced | bool | Automatically resets to the original alarm [volume] if the user attempts to adjust it. Disabled by default. |

This is how to stop/cancel your alarm:

await Alarm.stop(id)

This is how to run some code when alarm starts ringing.

Alarm.ringing.listen((AlarmSet alarmSet) {
  for (final alarm in alarmSet.alarms) {
    // yourOnRingCallback
  }
});

You can also listen to the Alarm.updateStream to know when an alarm is added, updated, or stopped.

To avoid unexpected behaviors, if you set an alarm for the same time, down to the second, as an existing one, the new alarm will replace the existing one.

📱 Example app

Don't hesitate to check out the example's code, and take a look at the app:

home edit

⏰ Alarm behaviour

| | Sound | Vibrate |

Alarm

Install / Use

README