hapticlabs_player

A cross-platform Flutter plugin for advanced haptic feedback playback on Android and iOS devices.

See Hapticlabs for our tool for designing haptic effects.

This project is hosted here on GitHub.

Features

  • Play custom haptic signals on Android and iOS
  • Play predefined haptic effects

Installation

Add to your pubspec.yaml:

dependencies:
  hapticlabs_player: 0.1.0

Then run:

flutter pub get

Usage

Note: See also the example for a complete Flutter app demonstrating usage.

Import the package:

import 'package:hapticlabs_player/hapticlabs_player.dart';

Basic Example

final player = HapticlabsPlayer();

// Play haptic file (Android: .hac, iOS: .ahap)
await player.playHaptics(
    androidPath: 'sample.hac',
    iosPath: 'sample.ahap',
);

// Play predefined effect
await player.playPredefinedHaptics(
    androidEffect: AndroidPredefinedHapticEffect.click,
    iosEffect: IOSPredefinedHapticEffect.success,
);

Android Extensions

import 'package:hapticlabs_player/hapticlabs_player_android.dart';

final player = HapticlabsPlayer();

// Play HLA file
await player.playHLA('sample.hla');

// Preload and unload files
await player.preload('sample.hac');
await player.unload('sample.hac');

// Query device haptic capabilities
final capabilities = await player.getAndroidConstants();

iOS Extensions

import 'package:hapticlabs_player/hapticlabs_player_ios.dart';

final player = HapticlabsPlayer();

// Play AHAP file
await player.playAHAP('Bundle/sample.ahap');

// Mute/unmute haptics or audio
await player.setHapticsMute(true);
await player.setAudioMute(true);

final isMuted = await player.isHapticsMuted();

API Reference

HapticlabsPlayer class (cross-platform)

A cross-platform haptic feedback player for Android and iOS devices.

Future<void> playHaptics({String? androidPath, String? iosPath})

Plays haptic feedback using the provided file paths for Android and iOS.

  • androidPath: Path to a .hac file for Android. Can be absolute (starting with /) or relative to the app's assets root.
  • iosPath: Path to an .ahap file for iOS. Can be absolute (starting with /) or relative to the app's main bundle root.

Deprecated: For Android, you may also provide a directory with the following structure:

directoryPath
├── lvl1
│   └── main.hla
│   └── optionalAudio.wav
├── lvl2
│   └── main.hla
│   └── optionalAudio.wav
└── lvl3
    └── main.ogg

It is recommended to use .hac files instead of directories for Android.

Returns a Future that completes when the haptic playback has terminated.

Future<void> playPredefinedHaptics({AndroidPredefinedHapticEffect? androidEffect, IOSPredefinedHapticEffect? iosEffect})

Plays predefined haptic effects for Android and iOS devices.

  • androidEffect: The predefined haptic effect to play on Android devices.
  • iosEffect: The predefined haptic effect to play on iOS devices.

Returns a Future that completes when the haptic playback has started.

For additional platform-specific methods, see the Android and iOS extension documentation above.

AndroidHapticlabsPlayer extension

Note: While there are many functions available for playing haptics on Android devices, the cross-platform playHaptics method is sufficient and recommended for most use cases. Use preload to address latency issues.

To use the Android-specific API, import:

import 'package:hapticlabs_player/hapticlabs_player_ios.dart';

Future<void> playHLA(String path)

Plays an HLA file from the specified path.

  • path: The file path to the .hla file. Can be absolute (starting with /) or relative to the app's assets root.

Returns a Future that completes when the haptic playback has terminated.

Future<void> playOGG(String path)

Plays an OGG file from the specified path.

  • path: The file path to the .ogg file. Can be absolute (starting with /) or relative to the app's assets root.

Returns a Future that completes when the haptic playback has terminated.

Future<void> playHAC(String path)

Plays a HAC file from the specified path.

  • path: The file path to the .hac file. Can be absolute (starting with /) or relative to the app's assets root.

Returns a Future that completes when the haptic playback has terminated.

Future<void> preload(String path)

Preloads a HAC file from the specified path to reduce latency for later playback through playHaptics or playHAC.

  • path: The file path to the .hac file. Can be absolute (starting with /) or relative to the app's assets root.

Returns a Future that completes when the HAC file has started preloading.

Future<void> preloadOGG(String path)

Preloads an OGG file from the specified path to reduce latency for later playback through playOGG.

  • path: The file path to the .ogg file. Can be absolute (starting with /) or relative to the app's assets root.

Returns a Future that completes when the OGG file has started preloading.

Future<void> unload(String path)

Unloads a previously preloaded HAC file from the specified path.

  • path: The file path to the .hac file. Can be absolute (starting with /) or relative to the app's assets root.

Returns a Future that completes when the HAC file has been unloaded.

Future<void> unloadOGG(String path)

Unloads a previously preloaded OGG file from the specified path.

  • path: The file path to the .ogg file. Can be absolute (starting with /) or relative to the app's assets root.

Returns a Future that completes when the OGG file has been unloaded.

Future<void> unloadAll()

Unloads all previously preloaded HAC and OGG files.

Returns a Future that completes when all preloaded files have been unloaded.

Future<AndroidHapticCapabilities> getAndroidConstants()

Retrieves Android-specific haptic capabilities and constants.

Returns a Future that completes with an AndroidHapticCapabilities object containing the device's haptic capabilities:


class AndroidHapticCapabilities {
  final int hapticSupportLevel;
  final bool areOnOffHapticsSupported;
  final bool areAmplitudeControlHapticsSupported;
  final bool areAudioCoupledHapticsSupported;
  final bool areEnvelopeHapticsSupported;
  final double? resonanceFrequency;
  final double? qFactor;
  final double? minFrequency;
  final double? maxFrequency;
  final double? maxAcceleration;
  final Map<int, double>? frequencyResponse;
  final int? envelopeControlPointMinDurationMillis;
  final int? envelopeControlPointMaxDurationMillis;
  final int? envelopeMaxDurationMillis;
  final int? envelopeMaxControlPointCount;
}

IOSHapticlabsPlayer extension

To use the iOS-specific API, import:

import 'package:hapticlabs_player/hapticlabs_player_ios.dart';

Future<void> playAHAP(String path)

Plays an AHAP file from the specified path.

  • path: The file path to the .ahap file. Can be absolute (starting with /) or relative to the app's main bundle root.

Returns a Future that completes when the haptic playback has terminated.

Future<void> setHapticsMute(bool mute)

Sets whether haptics defined by AHAP files should be muted.

  • mute: Whether to mute haptics defined by AHAP files.

Returns a Future that completes when the mute setting has been applied.

Future<bool> isHapticsMuted()

Checks whether haptics defined by AHAP files are currently muted.

Returns a Future that completes with true if haptics are muted, and false otherwise.

Future<void> setAudioMute(bool mute)

Sets whether audio playback defined by AHAP files should be muted.

  • mute: Whether to mute audio playback defined by AHAP files.

Returns a Future that completes when the mute setting has been applied.

Future<bool> isAudioMuted()

Checks whether audio playback defined by AHAP files is currently muted.

Returns a Future that completes with true if audio is muted, and false otherwise.

File Formats

Example

See example/ for a complete Flutter app demonstrating usage.

License

See LICENSE.

Libraries

hapticlabs_player
hapticlabs_player_android
hapticlabs_player_ios
hapticlabs_player_method_channel
hapticlabs_player_platform_interface