VibrationEffect.Builder Class

Definition

[Android.Runtime.Register("android/os/VibrationEffect$Builder", ApiSince=37, DoNotGenerateAcw=true)]
public sealed class VibrationEffect.Builder : Java.Lang.Object

[<Android.Runtime.Register("android/os/VibrationEffect$Builder", ApiSince=37, DoNotGenerateAcw=true)>]
type VibrationEffect.Builder = class
    inherit Object

Inheritance

Object

JavaObject

Object

VibrationEffect.Builder

Attributes

RegisterAttribute

Remarks

A builder for composing haptic effects by sequencing various haptic elements.

This API is the preferred alternative to VibrationEffect.Composition for creating complex vibration effects. It offers more flexibility for creating haptic patterns by allowing multiple elements to be scheduled at specific points in a timeline.

This builder allows you to add Envelopes, Presets, and existing VibrationEffects (as Events) to create a complex waveform. Each element is added with a specified startTimeMillis. Note that the use of legacy VibrationEffects is not recommended here.

Additionally, a repeating part can be set using setRepeatingEffect(long,VibrationEffect,long). Once a repeating effect is set, no more haptic elements can be added to the composition.

Fallback Support: Vibrations created by this builder will provide fallback support if the device does not support the requested haptic elements.

Note that fallback support is not provided for envelope effects created by WaveformEnvelopeBuilder, even when they are added to this builder. For such effects, if the device does not support PWLE effects or the requested frequencies, the vibration will not play.

For more details about the background of haptics implementation and how OEMs support these effects, see the Android Haptics Implementation Guidelines.

Timing and Alignment: The startTimeMillis is the time in milliseconds from the start of the composition being built. Elements must be added in increasing order of their start times.

The framework provides best-effort timing support during playback. If a previous event is still playing back when the next event's specified start time is reached, the framework will automatically shift the next event to the next earliest slot. This guarantees that no haptic feedback is dropped and events do not overlap in the actual playback (they will play sequentially instead).

However, this automatic shifting can introduce timing drift. To ensure that the actual playback timing aligns as closely as possible with your specified timeline, the builder performs best-effort validation at build time to help you avoid scheduling elements too close together. This validation uses known durations of some elements (like Envelopes) or a minimum duration (1ms) for device-dependent elements (like Presets). If a potential overlap is detected at build time, an IllegalArgumentException is thrown.

Because the actual duration of some elements is only fully known at runtime on the physical device, developers should still be mindful when sequencing elements with variable durations to ensure the best alignment between the designed and actual playback timing.

Android reference for android.os.VibrationEffect.Builder.

Portions of this page are modifications based on work created and shared by the Android Open Source Project and used according to terms described in the Creative Commons 2.5 Attribution License.