WaveformEnvelopeBuilder

Kotlin |Java

class WaveformEnvelopeBuilder

kotlin.Any
↳	android.os.VibrationEffect.WaveformEnvelopeBuilder

A builder for waveform effects described by its envelope.

Waveform effect envelopes are defined by one or more control points describing a target vibration amplitude and frequency, and a duration to reach those targets. The vibrator will perform smooth transitions between control points.

For example, the following code ramps a vibrator from off to full amplitude at 120Hz over 100ms, holds that state for 200ms, and then ramps back down over 100ms:

<code>VibrationEffect effect = new VibrationEffect.WaveformEnvelopeBuilder()
      .addControlPoint(1.0f, 120f, 100)
      .addControlPoint(1.0f, 120f, 200)
      .addControlPoint(0.0f, 120f, 100)
      .build();
  </code>

The builder automatically starts all effects at 0 amplitude.

It is crucial to ensure that the frequency range used in your effect is compatible with the device's capabilities. The framework will not play any frequencies that fall partially or completely outside the device's supported range. It will also not attempt to correct or modify these frequencies.

Therefore, it is strongly recommended that you design your haptic effects with the device's frequency profile in mind. You can obtain the supported frequency range and other relevant frequency-related information by getting the android.os.vibrator.VibratorFrequencyProfile using the Vibrator.getFrequencyProfile() method.

In addition to these limitations, when designing vibration patterns, it is important to consider the physical limitations of the vibration actuator. These limitations include factors such as the maximum number of control points allowed in an envelope effect, the minimum and maximum durations permitted for each control point, and the maximum overall duration of the effect. If a pattern exceeds the maximum number of allowed control points, the framework will automatically break down the effect to ensure it plays correctly.

You can use the following APIs to obtain these limits:

Maximum envelope control points: VibratorEnvelopeEffectInfo.getMaxSize()
Minimum control point duration: VibratorEnvelopeEffectInfo.getMinControlPointDurationMillis()
Maximum control point duration: VibratorEnvelopeEffectInfo.getMaxControlPointDurationMillis()
Maximum total effect duration: VibratorEnvelopeEffectInfo.getMaxDurationMillis()

Summary

Public constructors
`WaveformEnvelopeBuilder()`

Public methods
VibrationEffect.WaveformEnvelopeBuilder	`addControlPoint(amplitude: Float, frequencyHz: Float, durationMillis: Long)` Adds a new control point to the end of this waveform envelope.
VibrationEffect	`build()` Build the waveform as a single `VibrationEffect`.
VibrationEffect.WaveformEnvelopeBuilder	`setInitialFrequencyHz(initialFrequencyHz: Float)` Sets the initial frequency for the waveform in Hertz.

Public constructors

WaveformEnvelopeBuilder

Added in API level Baklava

WaveformEnvelopeBuilder()

Public methods

addControlPoint

Added in API level Baklava

fun addControlPoint(
    amplitude: Float, 
    frequencyHz: Float, 
    durationMillis: Long
): VibrationEffect.WaveformEnvelopeBuilder

Adds a new control point to the end of this waveform envelope.

Amplitude defines the vibrator's strength at this frequency, ranging from 0 (off) to 1 (maximum achievable strength). This value scales linearly with output strength, not perceived intensity. It's determined by the actuator response curve.

Frequency must be greater than zero and within the supported range. To determine the supported range, use Vibrator.getFrequencyProfile(). Creating effects using frequencies outside this range will result in the vibration not playing.

Time specifies the duration (in milliseconds) for the vibrator to smoothly transition from the previous control point to this new one. It must be greater than zero. To transition as quickly as possible, use VibratorEnvelopeEffectInfo.getMinControlPointDurationMillis().

Parameters
`amplitude`	Float: The amplitude value between 0 and 1, inclusive. 0 represents the vibrator being off, and 1 represents the maximum achievable amplitude at this frequency. Value is between 0 and 1 inclusive
`frequencyHz`	Float: The frequency in Hz, must be greater than zero. Value is 0 or greater
`durationMillis`	Long: The transition time in milliseconds. Value is a non-negative duration in milliseconds.

Return
`VibrationEffect.WaveformEnvelopeBuilder`	This value cannot be `null`.

build

Added in API level Baklava

fun build(): VibrationEffect

Build the waveform as a single VibrationEffect.

The WaveformEnvelopeBuilder object is still valid after this call, so you can continue adding more primitives to it and generating more VibrationEffects by calling this method again.

Return
`VibrationEffect`	The `VibrationEffect` resulting from the list of control points. This value cannot be `null`.

Exceptions
`java.lang.IllegalStateException`	if no control points were added to the builder.

setInitialFrequencyHz

Added in API level Baklava

fun setInitialFrequencyHz(initialFrequencyHz: Float): VibrationEffect.WaveformEnvelopeBuilder

Sets the initial frequency for the waveform in Hertz.

The effect will start vibrating at this frequency when it transitions to the amplitude and frequency defined by the first control point.

The frequency must be greater than zero and within the supported range. To determine the supported range, use Vibrator.getFrequencyProfile(). Creating effects using frequencies outside this range will result in the vibration not playing.

Parameters
`initialFrequencyHz`	Float: The starting frequency of the vibration, in Hz. Must be greater than zero. Value is 0 or greater

Return
`VibrationEffect.WaveformEnvelopeBuilder`	This value cannot be `null`.