vol_spotter #

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

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

Features #

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.

Architecture #

vol_spotter follows the federated plugin pattern:

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.

Known Limitations #

• Power button cannot be consumed on either 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.

Requirements #

Credits #

Created and maintained by @Crdzbird.

License #

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