vol_spotter 0.2.1

A Flutter plugin for detecting physical button presses (volume up, volume down, power) on Android and iOS with configurable event interception.

vol_spotter

A Flutter plugin for detecting physical button presses on Android, iOS, macOS, and Windows.

Detect Volume Up, Volume Down, and Power button events with optional interception (consume the hardware event so the system volume doesn't change).

Platform Support

Feature	Android	iOS	macOS	Windows
Volume Up detection	Yes	Yes	Yes	Yes
Volume Down detection	Yes	Yes	Yes	Yes
Power button detection	Yes	Yes	Yes	Yes
Volume interception (consume event)	Yes	Yes	Yes	Yes
pressed and released actions	Yes	pressed only	Yes	Yes
Minimum OS version	API 19	iOS 13.0	10.14	Windows 10

Getting Started

flutter pub add vol_spotter

Usage

Listen for button events

import 'package:vol_spotter/vol_spotter.dart';

final volSpotter = const VolSpotter();

// Start listening (call once)
await volSpotter.startListening();

// React to events
volSpotter.buttonEvents.listen((event) {
  if (event.action is! ButtonPressed) return;

  switch (event.button) {
    case VolumeUpButton():
      print('Volume Up pressed');
    case VolumeDownButton():
      print('Volume Down pressed');
    case PowerButton():
      print('Power button pressed');
  }
});

// Stop when done
await volSpotter.stopListening();

Intercept volume events

When interceptVolumeEvents is true, hardware volume changes are consumed so the system volume stays unchanged and the app receives the raw button press instead.

await volSpotter.startListening(
  config: const VolSpotterConfig(interceptVolumeEvents: true),
);

Full counter example

The plugin ships with a counter demo where Volume Up increments, Volume Down decrements, and Power resets. See example/lib/main.dart.

Models

The plugin uses Dart 3 sealed classes for type-safe pattern matching.

Class	Variants
PhysicalButton	VolumeUpButton, VolumeDownButton, PowerButton
ButtonAction	ButtonPressed, ButtonReleased
ButtonEvent	Combines a PhysicalButton + ButtonAction
VolSpotterConfig	interceptVolumeEvents, interceptPowerEvents

Architecture

vol_spotter follows the federated plugin pattern:

Package	Purpose
vol_spotter	App-facing API
vol_spotter_platform_interface	Shared interface and models
vol_spotter_android	Android implementation
vol_spotter_ios	iOS implementation
vol_spotter_macos	macOS implementation
vol_spotter_windows	Windows implementation
vol_spotter_linux	Linux stub
vol_spotter_web	Web stub

Platform Details

Android

• Volume: intercepts KEYCODE_VOLUME_UP / KEYCODE_VOLUME_DOWN via a Window.Callback proxy. Emits both pressed and released actions.
• Power: listens for ACTION_SCREEN_OFF via BroadcastReceiver. Emits pressed only.
• Requires an active Activity (works automatically when the Flutter engine is attached).

iOS

• Volume: observes AVAudioSession.outputVolume via KVO. A hidden MPVolumeView suppresses the system HUD and resets the slider when interception is enabled.
• Power: observes protectedDataWillBecomeUnavailableNotification for screen lock detection.
• Only ButtonPressed is emitted (iOS KVO fires once per press with no separate release event).
• Volume boundary detection uses a 1/128 offset to keep the volume away from 0.0/1.0 so subsequent presses are always detected.

macOS

• Volume: uses CGEvent taps to intercept media key events (NX_KEYTYPE_SOUND_UP / NX_KEYTYPE_SOUND_DOWN). Emits both pressed and released actions.
• Power: observes NSWorkspace.willSleepNotification for sleep/power button detection.
• Requires the Accessibility permission for event tap interception (macOS will prompt the user).

Windows

• Volume: uses a low-level keyboard hook (WH_KEYBOARD_LL) to intercept VK_VOLUME_UP / VK_VOLUME_DOWN. Emits both pressed and released actions.
• Power: listens for WM_POWERBROADCAST messages for suspend/power button detection.

Known Limitations

• Power button cannot be consumed on any platform. interceptPowerEvents is observe-only.
• iOS volume interception may cause a brief visual flicker as the hidden slider resets.
• iOS simulator: volume buttons are available under Hardware > Volume Up / Volume Down, but behavior may differ from a physical device.
• macOS: requires Accessibility permission to be granted by the user for event tap to work.
• Linux / Web: stub implementations only. startListening() throws UnsupportedError.

Requirements

	Minimum
Flutter	3.10.0
Dart	3.0.0
Android	API 19
iOS	13.0
macOS	10.14
Windows	10

Credits

Created and maintained by @Crdzbird.

License

This project is licensed under the MIT License. See the LICENSE file for details.