advanced_haptics 0.0.6 copy "advanced_haptics: ^0.0.6" to clipboard
advanced_haptics: ^0.0.6 copied to clipboard

A Flutter plugin for playing advanced, custom haptic feedback patterns on Android and iOS, including waveforms and Core Haptics .ahap files.


Advanced Haptics #

A Flutter plugin for playing powerful, custom haptic feedback patterns. This package provides a unified API to access Android's VibrationEffect.createWaveform and iOS's Core Haptics with .ahap files, enabling developers to create rich, game-style tactile feedback.

pub version license

Features #

  • Unified API: A single, easy-to-use Dart API for both platforms.
  • Android Waveform Support: Full control over vibration timings and amplitudes using Android's native VibrationEffect.
  • iOS Core Haptics: Play complex, custom patterns on iOS using .ahap (Apple Haptic and Audio Pattern) files.
  • Device Capability Check: Check if a device supports advanced, amplitude-controlled haptics.
  • Pre-defined Patterns: Simple, ready-to-use patterns like success.
  • Fallback Support: Provides sensible fallback behavior on older devices or platforms without full support.

Platform Support #

Feature Android (8.0+, API 26+) iOS (13.0+) Notes
Waveform ✅ Native ✅ Emulated iOS emulation is a best-effort and less precise than native.
.ahap Patterns 🟡 Fallback ✅ Native Requires iPhone 8 or newer. Not supported on iPad.
Amplitude Control ✅ Native ✅ Native Requires iPhone 8 or newer.
Pre-defined ✅ Supported ✅ Supported Requires iPhone 8 or newer for custom feel.

Key Limitations & Considerations #

Please read these limitations carefully to understand what to expect on each platform.

Android

  • API Level Requirement: Advanced waveform control with amplitude (playWaveform) requires Android 8.0 (API level 26) or higher. On older versions, calls will fail.
  • Hardware Variance: The quality and intensity of haptic feedback can vary significantly between Android device manufacturers (e.g., Samsung vs. Google Pixel vs. OnePlus). Always test on a range of target devices.

iOS

  • Hardware Requirement: Core Haptics is only supported on iPhone 8 and newer models. The plugin will not produce custom feedback on older iPhones (e.g., iPhone 7) or any iPad models. The hasCustomHapticsSupport() method will correctly return false on these devices.
  • OS Requirement: The plugin requires iOS 13.0 or higher.
  • Waveform Emulation: The playWaveform method on iOS is a best-effort emulation of Android's native feature. It is created by sequencing a series of transient haptic taps. It will not be as precise or feel the same as on Android. For the best experience on iOS, always prefer using .ahap files.

Getting Started #

1. Installation #

Add advanced_haptics to your project's pubspec.yaml file:

dependencies:
  advanced_haptics: ^0.0.1 # Replace with the latest version

Then, run flutter pub get in your terminal.

2. Android Setup (API 26+) #

Add the VIBRATE permission to your AndroidManifest.xml file, located at android/app/src/main/AndroidManifest.xml.

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.your_app">

    <!-- Add this line -->
    <uses-permission android:name="android.permission.VIBRATE"/>

   <application ...>
       ...
   </application>
</manifest>

3. iOS Setup (iOS 13+, iPhone 8+) #

For iOS, you need to include any .ahap files you wish to play in your project assets. See the section below on how to create these files. Once created, add them to your pubspec.yaml:

flutter:
  uses-material-design: true
  assets:
    - assets/haptics/ # Add the folder containing your .ahap files

Make sure the files are placed in the corresponding folder in your project (e.g., assets/haptics/my_pattern.ahap).


Creating .ahap Files for iOS #

An .ahap (Apple Haptic and Audio Pattern) file is a JSON file with a specific structure that describes a sequence of haptic events. You cannot generate these from a simple command-line tool; they must be authored.

For most users, a visual tool is the easiest and most intuitive method.

Captain AHAP is a third-party app for macOS that provides a timeline-based editor. It allows for live previewing of haptics on a connected iPhone, which is invaluable for iterating on your patterns.

2. Manually Writing the JSON (Advanced) #

You can also create .ahap files by hand in any text editor.

Key Concepts:

  • HapticIntensity: How strong the vibration is (0.0 to 1.0).
  • HapticSharpness: How "sharp" or "dull" it feels. High values are crisp taps; low values are soft rumbles (0.0 to 1.0).
  • HapticTransient: An instantaneous "tap" event.
  • HapticContinuous: A vibration that lasts for a specified EventDuration.

Example: A Single, Sharp Tap (sharp_tap.ahap)

{
    "Version": 1,
    "Pattern": [
        {
            "Event": {
                "Time": 0.0,
                "EventType": "HapticTransient",
                "EventParameters": [
                    { "ParameterID": "HapticIntensity", "ParameterValue": 1.0 },
                    { "ParameterID": "HapticSharpness", "ParameterValue": 1.0 }
                ]
            }
        }
    ]
}

For more details, refer to Apple's official documentation on representing haptic patterns.


Usage #

Import the package in your Dart file:

import 'package:advanced_haptics/advanced_haptics.dart';

Checking for Device Support #

It's good practice to check if the device can play custom haptics before calling other methods.

final bool canVibrate = await AdvancedHaptics.hasCustomHapticsSupport();
if (canVibrate) {
  print("This device supports custom haptics!");
}

Playing a Pre-defined Pattern #

// Plays a quick double-tap success feedback
await AdvancedHaptics.success();

Playing a Custom Waveform (Android-focused) #

Create a custom vibration by defining a pattern of timings and amplitudes.

  • timings: A list of durations in milliseconds. The pattern is [delay, vibrate, pause, vibrate, ...].
  • amplitudes: A list of intensities (0-255). Must be the same length as timings. Use 0 for pauses.
final timings = [0, 100, 200, 300];
final amplitudes = [0, 150, 0, 255];
await AdvancedHaptics.playWaveform(timings, amplitudes);

Playing an .ahap File (iOS-focused) #

For the richest experience on iOS, play a custom .ahap file.

// Make sure 'assets/haptics/rumble.ahap' is declared in your pubspec.yaml
await AdvancedHaptics.playAhap('assets/haptics/rumble.ahap');

Stopping Vibrations #

await AdvancedHaptics.stop();

API Reference #

Method Description
Future<bool> hasCustomHapticsSupport() Checks if the device supports amplitude-controlled haptics.
Future<void> playWaveform(List<int> timings, List<int> amplitudes) Plays a custom waveform pattern.
Future<void> playAhap(String ahapPath) Plays a .ahap file on iOS with a fallback on Android.
Future<void> success() Plays a predefined "success" haptic.
Future<void> stop() Stops any currently playing haptic feedback.

Contributing #

Contributions are welcome! If you find a bug or have a feature request, please open an issue. If you want to contribute code, please feel free to fork the repository and submit a pull request.

License #

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

2
likes
150
points
207
downloads

Publisher

unverified uploader

Weekly Downloads

A Flutter plugin for playing advanced, custom haptic feedback patterns on Android and iOS, including waveforms and Core Haptics .ahap files.

Repository (GitHub)
View/report issues

Documentation

API reference

License

MIT (license)

Dependencies

flutter, plugin_platform_interface

More

Packages that depend on advanced_haptics

Packages that implement advanced_haptics