This Flutter plugin provides a simple and easy-to-use interface for setting and canceling alarms on iOS and Android devices. It utilizes the android_alarm_manager_plus
plugin for Android and the native iOS AVAudioPlayer
class.
Please carefully follow these installation steps. They have been updated for plugin version 2.0.0
.
Add to your pubspec.yaml:
flutter pub add alarm
First, you have to initialize the Alarm service in your main
function:
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,
volumeMax: true,
fadeDuration: 3.0,
notificationTitle: 'This is the title',
notificationBody: 'This is the body',
enableNotificationOnKill: true,
);
And finally set the alarm:
await Alarm.set(alarmSettings: alarmSettings)
Property | Type | Description |
---|---|---|
id | int | Unique identifier of the alarm. |
alarmDateTime | DateTime | The date and time you want your alarm to ring. |
assetAudio | String | The path to you audio asset you want to use as ringtone. Can be a path in your assets folder or a downloaded local file path. |
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. |
volumeMax | bool | If true, set system volume to maximum when [dateTime] is reached. Set back to previous volume when alarm is stopped. |
fadeDuration | double | Duration, in seconds, over which to fade the alarm volume. Set to 0 by default, which means no fade. |
notificationTitle | String | The title of the notification triggered when alarm rings if app is on background. |
notificationBody | String | The body of the notification. |
enableNotificationOnKill | bool | Whether to show a notification when application is killed to warn the user that the alarm he set may not ring. Enabled by default. |
stopOnNotificationOpen | bool | Whether to stop the alarm when opening the received notification. Disabled by default. |
androidFullScreenIntent | bool | Whether to turn screen on when android alarm notification is triggered. Enabled by default. |
The notification shown on alarm ring can be disabled simply by ignoring the parameters notificationTitle
and notificationBody
. However, if you want a notification to be triggered, you will have to provide both of them.
If you enabled enableNotificationOnKill
, you can chose your own notification title and body by using this method:
await Alarm.setNotificationOnAppKillContent(title, body)
This is how to stop/cancel your alarm:
await Alarm.stop(id)
This is how to run some code when alarm starts ringing. We implemented it as a stream so even if your app was previously killed, your custom callback can still be triggered.
Alarm.ringStream.stream.listen((_) => yourOnRingCallback());
To avoid unexpected behaviors, if you set an alarm for the same time as an existing one, the new alarm will replace the existing one.
Don't hesitate to check out the example's code, and take a look at the app:
Sound | Vibrate | Volume max | Notification | |
---|---|---|---|---|
Locked screen | ✅ | ✅ | ✅ | ✅ |
Silent / Mute | ✅ | ✅ | ✅ | ✅ |
Do not disturb | ✅ | ✅ | ✅ | Silenced |
Sleep mode | ✅ | ✅ | ✅ | Silenced |
While playing other media | ✅ | ✅ | ✅ | ✅ |
App killed | ❌ | ❌ | ❌ | ✅ |
Silenced: Means that the notification is not shown directly on the top of the screen. You have to go in your notification center to see it.
Several factors could prevent your alarm from ringing:
Some Android manufacturers prefer battery life over proper functionality of your apps. Check out dontkillmyapp.com to find out about more about optimizations done by different vendors, and potential workarounds. Most common solution is to educate users to disable battery optimization settings. Source: android_alarm_manager_plus FAQ
The more time the app spends in the background, the higher the chance the OS might stop it from running due to memory or battery optimizations. Here's how you can optimize:
Uses oneShotAt
from the android_alarm_manager_plus
plugin with a two-way communication isolated callback to start/stop the alarm.
Keeps the app awake using a silent AVAudioPlayer
until alarm rings. When in the background, it also uses Background App Refresh
to periodically ensure the app is still active.
If you have a feature request, just open an issue explaining clearly what you want and if you convince me I will develop it for you.
We welcome contributions to this plugin! If you would like to make a change or add a new feature, please follow these steps:
flutter format
to ensure that your code is correctly formatted.These are some features that I have in mind that could be useful:
ffigen
and jnigen
binding generators to call native code more efficiently instead of using method channels.Thank you for considering contributing to this plugin. Your help is greatly appreciated!
❤️ Let me know if you like the plugin by liking it on pub.dev and starring the repo on Github 🙂
Run this command:
With Flutter:
$ flutter pub add alarm
This will add a line like this to your package's pubspec.yaml (and run an implicit flutter pub get
):
dependencies:
alarm: ^2.1.0
Alternatively, your editor might support flutter pub get
. Check the docs for your editor to learn more.
Now in your Dart code, you can use:
import 'package:alarm/alarm.dart';
import 'dart:async';
import 'package:alarm_example/screens/home.dart';
import 'package:flutter/material.dart';
import 'package:alarm/alarm.dart';
import 'package:flutter/services.dart';
Future<void> main() async {
WidgetsFlutterBinding.ensureInitialized();
SystemChrome.setPreferredOrientations([DeviceOrientation.portraitUp]);
await Alarm.init(showDebugLogs: true);
runApp(const MaterialApp(home: ExampleAlarmHomeScreen()));
}
Download details:
Author: gdelataillade.me
Source: https://github.com/gdelataillade/alarm