Multihaptic

https://github.com/xfqwdsj/multihaptic
Admin
Multihaptic is a Kotlin multiplatform library that provides haptic feedback support across Android,...
Tokens:5,292
Snippets:26
Trust Score:9.4
License:MIT
Update:7 months ago
Show doc for...
Tokens:
Raw
### Install Multihaptic Dependencies (Kotlin)

Source: https://context7.com/xfqwdsj/multihaptic/llms.txt

Add the necessary Multihaptic library dependencies to your Kotlin Multiplatform project's build.gradle.kts file. This includes core functionality, Compose Multiplatform support, and platform-specific DSLs.

```kotlin
// build.gradle.kts
dependencies {
    implementation("top.ltfan.multihaptic:multihaptic-core:<version>") // Core functionality
    implementation("top.ltfan.multihaptic:multihaptic-compose:<version>") // Compose Multiplatform support
    implementation("top.ltfan.multihaptic:multihaptic-platform-dsl:<version>") // Platform-specific DSLs
}
```

```toml
# gradle/libs.versions.toml
[versions]
multihaptic = "<version>"

[libraries]
multihaptic = { module = "top.ltfan.multihaptic:multihaptic-core", version.ref = "multihaptic" }
multihaptic-compose = { module = "top.ltfan.multihaptic:multihaptic-compose", version.ref = "multihaptic" }
multihaptic-platformDsl = { module = "top.ltfan.multihaptic:multihaptic-platform-dsl", version.ref = "multihaptic" }
```

--------------------------------

### Configure Gradle Dependencies for multihaptic

Source: https://github.com/xfqwdsj/multihaptic/blob/main/README.md

Instructions for adding multihaptic dependencies to a Kotlin Multiplatform project using either build.gradle.kts or Gradle Version Catalogs.

```kotlin
dependencies {
    implementation("top.ltfan.multihaptic:multihaptic-core:<version>")
    implementation("top.ltfan.multihaptic:multihaptic-compose:<version>")
    implementation("top.ltfan.multihaptic:multihaptic-platform-dsl:<version>")
}
```

```toml
[versions]
multihaptic = "<version>"

[libraries]
multihaptic = { module = "top.ltfan.multihaptic:multihaptic-core", version.ref = "multihaptic" }
multihaptic-compose = { module = "top.ltfan.multihaptic:multihaptic-compose", version.ref = "multihaptic" }
multihaptic-platformDsl = { module = "top.ltfan.multihaptic:multihaptic-platform-dsl", version.ref = "multihaptic" }
```

--------------------------------

### Create Predefined Haptic Effects

Source: https://github.com/xfqwdsj/multihaptic/blob/main/README.md

Demonstrates how to use the HapticEffect DSL to define standard vibration patterns like clicks, thuds, and ticks with configurable intensity and timing.

```kotlin
HapticEffect {
    predefined(PrimitiveType.Click) {
        scale = .5f
    }
    predefined(PrimitiveType.Thud) {
        scale = .8f
        delay = 100.milliseconds
        delayType = DelayType.Pause
    }
    predefined(PrimitiveType.Tick) {
        scale = .3f
        delay = 50.milliseconds
        delayType = DelayType.RelativeStartOffset
    }
    lowTick {
        delay = 30.milliseconds
    }
    quickRise
}
```

--------------------------------

### Create Custom Haptic Effects

Source: https://github.com/xfqwdsj/multihaptic/blob/main/README.md

Shows how to define custom haptic effects using intensity and sharpness curves over time, including fallback mechanisms.

```kotlin
HapticEffect {
    custom {
        fallback = PrimitiveType.Spin
        curves {
            intensity {
                0f at 0.milliseconds
                1f at 5.milliseconds
                0f at 10.milliseconds
            }
            sharpness {
                .3f at 0.milliseconds
            }
        }
    }
}
```

--------------------------------

### Apple Core Haptics Pattern DSL

Source: https://context7.com/xfqwdsj/multihaptic/llms.txt

Constructs Apple Core Haptics patterns for iOS, macOS, tvOS, and watchOS using a Kotlin DSL. Supports transient and continuous events, with detailed control over intensity, sharpness, attack, decay, and release times, including time-based curves. Requires experimental and beta interop APIs.

```kotlin
import platform.CoreHaptics.dsl.*
import kotlin.time.Duration.Companion.milliseconds

@OptIn(ExperimentalForeignApi::class, BetaInteropApi::class)
fun createHapticPattern(): CHHapticPattern {
    return CHHapticPattern {
        events {
            // Transient event - brief impulse
            transient {
                intensity = 0.8f
                sharpness = 1f
            }

            // Transient at specific time
            transient(20.milliseconds)

            // Continuous event - sustained vibration
            continuous

            // Continuous with full configuration
            continuous(
                duration = 200.milliseconds,
                relativeTime = 50.milliseconds
            ) {
                intensity = 0.6f
                sharpness = 0.5f
                attackTime = 10.milliseconds
                decayTime = 50.milliseconds
                releaseTime = Duration.ZERO
                sustained = true
            }
        }

        curves {
            // Intensity curve over time
            intensity {
                0.2f at 0.milliseconds
                1f at 100.milliseconds
                0.5f at 200.milliseconds
            }

            // Sharpness curve
            sharpness {
                0.4f at 20.milliseconds
            }

            // Attack time curve
            attackTime {
                0f at 0.milliseconds
                0.5f at 100.milliseconds
            }

            // Decay time curve
            decayTime {
                0.3f at 50.milliseconds
            }

            // Release time curve
            releaseTime {
                0f at 0.milliseconds
                1f at 150.milliseconds
            }
        }
    }
}
```

--------------------------------

### Vibrator Interface for Playing Haptics in Kotlin

Source: https://context7.com/xfqwdsj/multihaptic/llms.txt

Illustrates using the Vibrator interface in Kotlin to play haptic effects and check device capabilities. It includes methods for vibrating with predefined effects or inline builders, and for canceling vibrations.

```kotlin
import top.ltfan.multihaptic.HapticEffect
import top.ltfan.multihaptic.PrimitiveType
import top.ltfan.multihaptic.vibrator.Vibrator

fun playHaptics(vibrator: Vibrator) {
    // Check if vibration is supported
    if (vibrator.isVibrationSupported) {
        // Play a pre-built effect
        val effect = HapticEffect {
            click { scale = 0.8f }
            tick { delay = 50.milliseconds }
        }
        vibrator.vibrate(effect)

        // Or build inline using the builder DSL
        vibrator.vibrate {
            thud { scale = 0.6f }
            quickRise
        }

        // Cancel any ongoing vibration
        vibrator.cancel()
    }
}
```

--------------------------------

### Implement Cross-Platform Haptic Effects in Kotlin

Source: https://context7.com/xfqwdsj/multihaptic/llms.txt

Shows how to check for vibration support and define effects that gracefully fallback to primitive types on platforms where custom curves are not supported.

```kotlin
import top.ltfan.multihaptic.HapticEffect
import top.ltfan.multihaptic.PrimitiveType
import top.ltfan.multihaptic.vibrator.Vibrator

fun demonstratePlatformSupport(vibrator: Vibrator) {
    val supported = vibrator.isVibrationSupported

    val crossPlatformEffect = HapticEffect {
        click { scale = 0.8f }

        custom {
            fallback = PrimitiveType.Thud
            curves {
                intensity {
                    0f at 0.milliseconds
                    1f at 20.milliseconds
                    0f at 50.milliseconds
                }
                sharpness { 0.5f at 0.milliseconds }
            }
        }
    }

    vibrator.vibrate(crossPlatformEffect)
}
```

--------------------------------

### Define HapticCurves with Keyframes in Kotlin

Source: https://context7.com/xfqwdsj/multihaptic/llms.txt

Demonstrates how to construct custom haptic intensity and sharpness curves using the HapticCurves.Builder DSL. It shows both manual keyframe assignment and the use of HapticEffect blocks for complex timing.

```kotlin
import top.ltfan.multihaptic.HapticCurves
import kotlin.time.Duration.Companion.milliseconds

// Build haptic curves manually
val curves = HapticCurves.Builder().apply {
    intensity {
        0f at 0.milliseconds
        1f at 25.milliseconds
        0.5f at 50.milliseconds
        0f at 100.milliseconds
    }
    sharpness {
        1f at 0.milliseconds
        0.3f at 100.milliseconds
    }
}.build()

// Alternative: add keyframes individually
val curvesAlt = HapticCurves.Builder().apply {
    intensity(0.milliseconds, 0f)
    intensity(25.milliseconds, 1f)
    intensity(50.milliseconds, 0.5f)

    sharpness(0f) // At time zero
    sharpness(100.milliseconds, 0.3f)
}.build()

// Using in a HapticEffect
val effectWithCurves = HapticEffect {
    custom(duration = 100.milliseconds) {
        clickFallback
        curves {
            intensity {
                +HapticCurves.Keyframe(0.milliseconds, 0f)
                +HapticCurves.Keyframe(50.milliseconds, 1f)
                +HapticCurves.Keyframe(100.milliseconds, 0f)
            }
            sharpness {
                add {
                    time = 0.milliseconds
                    value = 0.8f
                }
            }
        }
    }
}
```

--------------------------------

### Build Predefined Haptic Effects (Kotlin)

Source: https://context7.com/xfqwdsj/multihaptic/llms.txt

Compose haptic feedback using the HapticEffect DSL with predefined primitive types like Click, Thud, and Tick. Configure scale, delay, and timing for each primitive to create complex haptic sequences.

```kotlin
import top.ltfan.multihaptic.HapticEffect
import top.ltfan.multihaptic.PrimitiveType
import top.ltfan.multihaptic.DelayType
import kotlin.time.Duration.Companion.milliseconds

// Create a haptic effect with multiple primitives
val effect = HapticEffect {
    // Using the predefined function with configuration block
    predefined(PrimitiveType.Click) {
        scale = 0.5f // Adjust intensity (0.0 to 1.0)
    }

    predefined(PrimitiveType.Thud) {
        scale = 0.8f
        delay = 100.milliseconds // Delay before this effect
        delayType = DelayType.Pause // Pause after previous effect ends
    }

    predefined(PrimitiveType.Tick) {
        scale = 0.3f
        delay = 50.milliseconds
        delayType = DelayType.RelativeStartOffset // Relative to previous start
    }

    // Shorthand methods for common primitives
    lowTick {
        delay = 30.milliseconds
    }

    quickRise // With default parameters
    click     // Simple click
    thud      // Heavy feedback
    spin      // Spinning momentum
    slowRise  // Gradual rise
    quickFall // Quick descent
    tick      // Light tick
}
```

--------------------------------

### Compose Integration with rememberVibrator in Kotlin

Source: https://context7.com/xfqwdsj/multihaptic/llms.txt

Shows how to integrate haptic feedback into Jetpack Compose applications using the `rememberVibrator` composable in Kotlin. This allows obtaining a platform-appropriate Vibrator instance within composables.

```kotlin
import androidx.compose.foundation.layout.Button
import androidx.compose.material.Text
import androidx.compose.runtime.Composable
import top.ltfan.multihaptic.compose.rememberVibrator
import top.ltfan.multihaptic.PrimitiveType

@Composable
fun HapticButton() {
    val vibrator = rememberVibrator()

    Button(onClick = {
        vibrator.vibrate {
            click { scale = 0.7f }
        }
    }) {
        Text("Tap for haptic feedback")
    }
}

@Composable
fun FeedbackDemo() {
    val vibrator = rememberVibrator()

    Column {
        Button(onClick = {
            vibrator.vibrate {
                predefined(PrimitiveType.Click)
            }
        }) {
            Text("Click")
        }

        Button(onClick = {
            vibrator.vibrate {
                thud { scale = 1f }
            }
        }) {
            Text("Heavy Impact")
        }

        Button(onClick = {
            vibrator.vibrate {
                quickRise
                tick { delay = 30.milliseconds }
                tick { delay = 30.milliseconds }
                tick { delay = 30.milliseconds }
            }
        }) {
            Text("Rising Ticks")
        }
    }
}
```

--------------------------------

### Delay Types for Haptic Timing in Kotlin

Source: https://context7.com/xfqwdsj/multihaptic/llms.txt

Demonstrates how to control delays between haptic primitives using DelayType in Kotlin. Supports DelayType.Pause for sequential execution and DelayType.RelativeStartOffset for timed offsets.

```kotlin
import top.ltfan.multihaptic.HapticEffect
import top.ltfan.multihaptic.PrimitiveType
import top.ltfan.multihaptic.DelayType
import kotlin.time.Duration.Companion.milliseconds

// DelayType.Pause - Wait after previous effect ends
val pauseExample = HapticEffect {
    predefined(PrimitiveType.QuickRise)
    predefined(PrimitiveType.Click, 0.7f, 50.milliseconds, DelayType.Pause)
    // Click starts 50ms after QuickRise ends
}

// DelayType.RelativeStartOffset - Fixed time after previous starts
val offsetExample = HapticEffect {
    predefined(PrimitiveType.Click, 1f)
    predefined(PrimitiveType.Tick, 1f, 20.milliseconds, DelayType.RelativeStartOffset)
    predefined(PrimitiveType.Thud, 1f, 80.milliseconds, DelayType.RelativeStartOffset)
    // Timeline: Click@0ms, Tick@20ms, Thud@80ms
}
```

--------------------------------

### Android Envelope and Waveform Effects DSL

Source: https://context7.com/xfqwdsj/multihaptic/llms.txt

Enables creation of advanced envelope and waveform haptic effects on Android, requiring API level 35 (BAKLAVA). It allows fine-grained control over intensity, sharpness, and frequency, with safety checks for vibrator support. Includes helper functions for safe vibrator access.

```kotlin
import android.content.Context
import android.os.VibrationEffect
import platform.android.dsl.*
import kotlin.time.Duration.Companion.milliseconds

// Basic envelope effect with intensity and sharpness control
@RequiresApi(Build.VERSION_CODES.BAKLAVA)
fun Context.createEnvelopeEffect(): VibrationEffect? {
    if (withVibratorOrNull { this?.areEnvelopeEffectsSupported() } != true) return null

    return envelopeVibrationEffect {
        point(0.5f, 1f) after 10.milliseconds  // Intensity 0.5, sharpness 1.0
        point(0.9f, 1f) at 20.milliseconds     // Ramp to 0.9 intensity
    }
}

// Waveform effect with frequency control
@RequiresApi(Build.VERSION_CODES.BAKLAVA)
fun Context.createWaveformEffect(): VibrationEffect? {
    return tryWithVibrator {
        if (!areEnvelopeEffectsSupported()) return@tryWithVibrator null

        waveformVibrationEffect {
            point(0.5f, 300f) after 10.milliseconds // Amplitude 0.5, 300Hz
            point(0.9f, 500f) at 20.milliseconds    // Amplitude 0.9, 500Hz
        }
    }
}

// Using Context helpers for safe vibrator access
fun Context.playHaptic() {
    withVibratorOrNull { vibrator ->
        vibrator?.vibrate(VibrationEffect.createOneShot(50, 100))
    }

    tryWithVibrator(
        failed = { println("Vibrator not available") }
    ) {
        vibrate(VibrationEffect.createOneShot(50, 100))
    }
}
```

--------------------------------

### Build Custom Haptic Effects with Curves (Kotlin)

Source: https://context7.com/xfqwdsj/multihaptic/llms.txt

Create advanced custom haptic effects by defining intensity and sharpness curves. This allows for fine-grained control over the haptic feedback, with fallbacks for platforms that do not support custom curves.

```kotlin
import top.ltfan.multihaptic.HapticEffect
import top.ltfan.multihaptic.PrimitiveType
import kotlin.time.Duration.Companion.milliseconds

val customEffect = HapticEffect {
    custom {
        // Specify a fallback for platforms without custom curve support
        fallback = PrimitiveType.Spin
        // Or use shorthand: spinFallback, clickFallback, thudFallback, etc.

        curves {
            intensity {
                0f at 0.milliseconds   // Start with no intensity
                1f at 5.milliseconds   // Ramp up to full intensity
                0f at 10.milliseconds  // Fade back to zero
            }
            sharpness {
                0.3f at 0.milliseconds // Constant low sharpness
            }
        }
    }
}

// Combine predefined and custom effects
val combinedEffect = HapticEffect {
    click { scale = 0.7f }

    custom(duration = 100.milliseconds) {
        tickFallback
        delay = 50.milliseconds
        delayType = DelayType.Pause

        curves {
            intensity {
                0.2f at 0.milliseconds
                1f at 50.milliseconds
                0.5f at 100.milliseconds
            }
            sharpness {
                1f at 0.milliseconds
                0.3f at 100.milliseconds
            }
        }
    }
}
```

--------------------------------

### Haptic Primitive Types in Kotlin

Source: https://context7.com/xfqwdsj/multihaptic/llms.txt

Defines available primitive types for predefined haptic effects in Kotlin. Each type has a characteristic duration and sensation, such as Click, Thud, Spin, and Tick.

```kotlin
import top.ltfan.multihaptic.PrimitiveType

// Click - Sharp, crisp click sensation (50ms)
PrimitiveType.Click

// Thud - Downward movement with gravity, heavy impact (80ms)
PrimitiveType.Thud

// Spin - Simulates spinning momentum (120ms)
PrimitiveType.Spin

// QuickRise - Quick upward movement against gravity (50ms)
PrimitiveType.QuickRise

// SlowRise - Slow upward movement against gravity (200ms)
PrimitiveType.SlowRise

// QuickFall - Quick downward movement with gravity (60ms)
PrimitiveType.QuickFall

// Tick - Very short, light crisp sensation for dynamic feedback (10ms)
PrimitiveType.Tick

// LowTick - Very short, low frequency crisp sensation (20ms)
PrimitiveType.LowTick
```

--------------------------------

### Android Composed Vibration Effects DSL

Source: https://context7.com/xfqwdsj/multihaptic/llms.txt

Defines composed vibration effects on Android using a Kotlin DSL. Supports various predefined effects like click, thud, spin, and rise/fall, with options for scaling and relative timing. Requires API level 29 or higher for composed effects and API level 26 for amplitude-based effects.

```kotlin
import android.os.VibrationEffect
import platform.android.dsl.*
import kotlin.time.Duration.Companion.milliseconds

// Composed vibration with multiple primitives
@RequiresApi(Build.VERSION_CODES.R)
fun createComposedEffect(): VibrationEffect {
    return composedVibrationEffect {
        click
        click { scale = 0.5f }
        thud
        spin
        quickRise
        slowRise
        quickFall
        tick
        lowTick {
            delay = 50.milliseconds
            relativeStartOffsetDelay // Use relative timing
        }
    }
}

// Amplitude-based waveform
@RequiresApi(Build.VERSION_CODES.O)
fun createAmplitudeEffect(): VibrationEffect {
    return amplitudeVibrationEffect {
        60 at 0.milliseconds    // Start at amplitude 60
        80 at 10.milliseconds   // Increase to 80
        100 at 20.milliseconds  // Peak at 100
    }
}

// On-off pattern vibration
@RequiresApi(Build.VERSION_CODES.O)
fun createOnOffEffect(): VibrationEffect {
    return onOffVibrationEffect {
        range(10.milliseconds..20.milliseconds)  // On from 10-20ms
        range(30.milliseconds..40.milliseconds)  // On from 30-40ms
        pattern(10.milliseconds, 10.milliseconds) // Off 10ms, on 10ms
    }
}
```
Tokens:
Raw