alarm_volume_control 1.0.0

Flutter alarm plugin for iOS and Android with scheduling, ringing, vibration, notifications, and Android volume UI control.

alarm_volume_control

Flutter alarm plugin for iOS and Android with alarm scheduling, ringing, vibration, notifications, and volume control.

This package is based on the alarm package and adds an Android-focused volume experience: when an alarm rings and the plugin applies or enforces alarm volume, the system volume overlay is kept hidden.

Features

• Schedule, update, stop, and observe alarms from Dart.
• Ring alarms with bundled assets, app assets, local files, or the platform default alarm sound.
• Vibrate while ringing.
• Show alarm notifications with configurable title, body, icon, icon color, and stop action.
• Configure fixed volume, fade-in volume, custom fade steps, and enforced volume.
• Restore the previous device volume when the alarm stops.
• Hide the Android system volume UI while alarm volume is changed by the plugin.

Platform Support

Platform	Scheduling	Audio	Vibration	Notifications	Volume control
Android	Yes	Yes	Yes	Yes	Yes, with hidden system volume UI while the plugin changes volume
iOS	Yes, while iOS allows background execution	Yes	Yes	Yes	Yes, using the platform audio session behavior

Installation

flutter pub add alarm_volume_control

Then import the package:

import 'package:alarm_volume_control/alarm.dart';

Platform Setup

This plugin uses native alarm, notification, audio, and foreground-service APIs. Make sure your app is configured for each target platform.

Android

Add the required permissions and services to your Android app manifest according to the example app in this repository:

• SCHEDULE_EXACT_ALARM or USE_EXACT_ALARM, depending on your target SDK and Play Store policy.
• POST_NOTIFICATIONS on Android 13+ if you show notifications.
• FOREGROUND_SERVICE permissions required by your Android target SDK.
• The plugin receivers and foreground service declarations from the example manifest.

For reliable alarms, educate users to disable battery optimization for your app on Android devices that aggressively stop background work.

See help/INSTALL-ANDROID.md for a fuller setup checklist.

iOS

Enable the capabilities your app needs:

• Notifications permission must be requested by your app.
• Background audio is required for the plugin's iOS alarm behavior.
• Consider showing a warning notification when the app is killed, because iOS can terminate background work more aggressively than Android.

See help/INSTALL-IOS.md for the Xcode and AppDelegate setup.

Quick Start

Initialize the plugin before scheduling alarms:

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Alarm.init();

  runApp(const MyApp());
}

Schedule an alarm:

final alarmSettings = AlarmSettings(
  id: 42,
  dateTime: DateTime.now().add(const Duration(minutes: 1)),
  assetAudioPath: 'assets/alarm.mp3',
  loopAudio: true,
  vibrate: true,
  warningNotificationOnKill: true,
  androidFullScreenIntent: true,
  volumeSettings: VolumeSettings.fade(
    volume: 1,
    fadeDuration: const Duration(seconds: 10),
    volumeEnforced: true,
  ),
  notificationSettings: const NotificationSettings(
    title: 'Alarm',
    body: 'Time to wake up',
    stopButton: 'Stop',
    icon: 'notification_icon',
  ),
);

await Alarm.set(alarmSettings: alarmSettings);

Stop an alarm:

await Alarm.stop(42);

Listen when alarms start ringing:

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

Listen to alarm changes:

Alarm.updateStream.listen((_) async {
  final alarms = await Alarm.getAlarms();
  // Refresh your UI or local state.
});

AlarmSettings

Property	Type	Description
id	int	Unique alarm identifier.
dateTime	DateTime	Date and time when the alarm should ring.
assetAudioPath	String?	Audio path. Use an app asset, a local file path with the needed permission, or null for the platform default alarm sound.
loopAudio	bool	Repeats audio until the alarm is stopped.
vibrate	bool	Vibrates while ringing. If loopAudio is false, vibration stops when audio ends.
warningNotificationOnKill	bool	Shows a warning notification when the app is killed. Recommended on iOS.
androidFullScreenIntent	bool	Shows the alarm as a full-screen Android intent when possible.
allowAlarmOverlap	bool	Allows an alarm to ring while another alarm is already ringing. Disabled by default.
androidStopAlarmOnTermination	bool	Stops ringing alarms when the Android task is terminated.
payload	String?	Optional serialized data for your app.
notificationSettings	NotificationSettings	Notification title, body, icon, color, and actions.
volumeSettings	VolumeSettings	Alarm volume, fade, and enforcement settings.

NotificationSettings

Property	Type	Description
title	String	Alarm notification title.
body	String	Alarm notification body.
stopButton	String?	Text for the stop action. No stop button is shown when null.
icon	String?	Android notification icon resource name.
iconColor	Color?	Android notification icon color.
keepNotificationAfterAlarmEnds	bool	Keeps the notification after alarm audio ends on iOS.

VolumeSettings

Property	Type	Description
volume	double?	System volume for the alarm, from 0.0 to 1.0. Previous volume is restored after stop.
fadeDuration	Duration?	Duration for fading from low volume to the target volume.
fadeSteps	List<VolumeFadeStep>	Custom volume fade steps.
volumeEnforced	bool	Keeps resetting volume to the configured alarm volume while ringing.

Android volume UI behavior

On Android, this package sets and enforces alarm volume without showing the system volume overlay. This keeps the alarm experience quiet visually while still allowing the alarm to ring at the configured volume.

Use volumeEnforced: true when you want the alarm to stay at the configured volume even if the user presses hardware volume buttons while it rings.

volumeSettings: const VolumeSettings.fixed(
  volume: 1,
  volumeEnforced: true,
),

The previous volume is restored when the alarm stops. If multiple alarms are allowed to overlap, test your restore behavior carefully because each alarm can have its own volume settings.

Silent alarm with vibration only

To create a vibration-only alarm, set the volume to 0 and keep vibration enabled:

final alarmSettings = AlarmSettings(
  id: 7,
  dateTime: DateTime.now().add(const Duration(minutes: 1)),
  assetAudioPath: null,
  loopAudio: false,
  vibrate: true,
  volumeSettings: const VolumeSettings.fixed(volume: 0),
  notificationSettings: const NotificationSettings(
    title: 'Silent alarm',
    body: 'Vibration only',
  ),
);

Example

The example directory contains a complete Flutter app that demonstrates:

• Permission handling.
• Notification setup.
• Scheduling and editing alarms.
• Ringing UI.
• Volume settings.

Run it with:

cd example
flutter pub get
flutter run

Reliability Notes

Alarm behavior depends on platform rules:

• Android is generally more capable for exact alarms, but manufacturer battery optimization can still stop background work.
• iOS may stop alarms if the app is killed, the device restarts, or background execution is restricted.
• Do Not Disturb and notification settings can silence or hide notifications even when audio behavior still works.
• Always test on real devices before shipping alarm-critical flows.

Migration from alarm

Replace the dependency:

dependencies:
  alarm_volume_control: ^1.0.0

Then update imports:

import 'package:alarm_volume_control/alarm.dart';

The public Dart API is intentionally kept close to alarm 5.2.1. The main behavioral difference is the Android volume UI handling described above.

Logging

The package uses the logging package. Configure logging in your app if you want to inspect plugin events while developing.

Publishing Notes

Before publishing a fork, update these values in pubspec.yaml:

• repository
• issue_tracker
• package description, if your published package has a narrower purpose

Run this command before publishing:

dart pub publish --dry-run

Credits

This package is based on the open-source alarm package by Gregory Delattre and contributors. The package name and documentation were updated for the alarm_volume_control distribution, with an Android volume UI adjustment for a smoother ringing experience.