Added in API level 10000

Summary: Ctors | Methods | Inherited Methods

VibrationEffect.Builder

---

Kotlin |Java

public static final class VibrationEffect.Builder
extends Object

java.lang.Object
↳	android.os.VibrationEffect.Builder

---

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.

Summary

Public constructors
Builder() Creates an empty Builder to compose a new VibrationEffect.
Builder(VibrationEffect effect) Creates a Builder initialized with a copy of an existing VibrationEffect.

Public methods
VibrationEffect.Builder	addEnvelope(long startTimeMillis, VibrationEffect.Envelope envelope) Adds a haptic Envelope to the composition.
VibrationEffect.Builder	addEvents(long startTimeShiftMillis, List<VibrationEffect.Event> events) Adds a list of existing Events to the composition.
VibrationEffect.Builder	addPreset(long startTimeMillis, VibrationEffect.Preset preset) Adds a predefined haptic Preset to the composition.
VibrationEffect	build() Builds the composed VibrationEffect.
VibrationEffect.Builder	setRepeatingEffect(long startTimeMillis, VibrationEffect effect, long durationMillis) Adds a repeating haptic effect to the composition.

Inherited methods

From class java.lang.Object Object clone() Creates and returns a copy of this object. boolean equals(Object obj) Indicates whether some other object is "equal to" this one. void finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. final Class<?> getClass() Returns the runtime class of this Object. int hashCode() Returns a hash code value for the object. final void notify() Wakes up a single thread that is waiting on this object's monitor. final void notifyAll() Wakes up all threads that are waiting on this object's monitor. String toString() Returns a string representation of the object. final void wait(long timeoutMillis, int nanos) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait(long timeoutMillis) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait() Causes the current thread to wait until it is awakened, typically by being notified or interrupted.

Public constructors

Builder

Added in API level 10000

public Builder ()

Creates an empty Builder to compose a new VibrationEffect.

Builder

Added in API level 10000

public Builder (VibrationEffect effect)

Creates a Builder initialized with a copy of an existing VibrationEffect.

Initializes the builder by copying the sequence of events from the provided effect.

Parameters
effect	VibrationEffect: The VibrationEffect to initialize this builder with. This value cannot be null.

Throws
IllegalStateException	if the effect is repeating.
NullPointerException	if the provided effect is null.

Public methods

addEnvelope

Added in API level 10000

public VibrationEffect.Builder addEnvelope (long startTimeMillis, 
                VibrationEffect.Envelope envelope)

Adds a haptic Envelope to the composition.

The startTimeMillis is the time in milliseconds from the start of the composition being built. The envelope will be scheduled to start at this time.

The builder performs best-effort validation to prevent overlaps with previously added elements. The duration of an Envelope is generally well-defined, but care should still be taken with the startTimeMillis to ensure correct sequencing with other elements.

Fallback Support: If the envelope is created using WaveformEnvelopeBuilder, fallback support is not provided. If the device does not support the envelope, the entire vibration effect may fail to play. Envelopes created using BasicEnvelopeBuilder or Envelope.BeatingEnvelopeBuilder will have fallback support.

Parameters
startTimeMillis	long: The time in milliseconds from the start of the composition to start the envelope. Value is a non-negative duration in milliseconds.
envelope	VibrationEffect.Envelope: The Envelope to add. This value cannot be null.

Returns
VibrationEffect.Builder	This Builder object. This value cannot be null.

Throws
IllegalArgumentException	if adding the envelope would result in overlapping haptic elements.
NullPointerException	if the provided envelope is null.

addEvents

Added in API level 10000

public VibrationEffect.Builder addEvents (long startTimeShiftMillis, 
                List<VibrationEffect.Event> events)

Adds a list of existing Events to the composition.

Each event in the list has a start time relative to the start of the composition it was retrieved from. The startTimeShiftMillis parameter is added to the start time of each event in the list, effectively shifting the whole block of events forward or backward in the timeline of this builder.

For example, if an event within the list has a start time of 50ms, and startTimeShiftMillis is 100ms, the event will be shifted to start at 150ms within this builder's timeline.

All events will be added and validated according to the builder's timing rules, with best-effort checks to prevent overlaps being introduced by the shift.

You can get events by calling VibrationEffect.getEvents() on non-repeating effects.

Parameters
startTimeShiftMillis	long: The non-negative time in milliseconds to add to the start time of each event in the provided list. Value is a non-negative duration in milliseconds.
events	List: The list of events to add. This value cannot be null.

Returns
VibrationEffect.Builder	This Builder object. This value cannot be null.

Throws
IllegalArgumentException	if startTimeShiftMillis is negative or if adding any of the events would result in overlapping haptic elements.
NullPointerException	if the provided events list is null.

addPreset

Added in API level 10000

public VibrationEffect.Builder addPreset (long startTimeMillis, 
                VibrationEffect.Preset preset)

Adds a predefined haptic Preset to the composition.

The startTimeMillis is the time in milliseconds from the start of the composition being built. The preset will be scheduled to start at this time.

The builder performs best-effort validation to prevent overlaps with previously added elements. However, the exact duration of a Preset can be device-dependent. It is the caller's responsibility to choose an appropriate startTimeMillis to avoid unintended overlaps.

Parameters
startTimeMillis	long: The time in milliseconds from the start of the composition to start the preset. Value is a non-negative duration in milliseconds.
preset	VibrationEffect.Preset: The Preset to add. This value cannot be null.

Returns
VibrationEffect.Builder	This Builder object. This value cannot be null.

Throws
IllegalArgumentException	if adding the preset would result in overlapping haptic elements.
NullPointerException	if the provided preset is null.

build

Added in API level 10000

public VibrationEffect build ()

Builds the composed VibrationEffect.

This method finalizes the composition of all added elements (Envelopes, Presets, Events) and returns a single VibrationEffect that can be played by the vibrator.

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

Automatic fallback will be supported for the built VibrationEffect. If the device does not support some of the composed haptic elements, they will be automatically mapped to fallback effects at runtime (except for elements that explicitly do not support fallback, such as envelopes from WaveformEnvelopeBuilder).

Returns
VibrationEffect	The resulting VibrationEffect. This value cannot be null.

Throws
IllegalArgumentException	if the validation of the composed effect fails (e.g., due to timing issues, invalid haptic element parameters).
IllegalStateException	if the composition is empty.

setRepeatingEffect

Added in API level 10000

public VibrationEffect.Builder setRepeatingEffect (long startTimeMillis, 
                VibrationEffect effect, 
                long durationMillis)

Adds a repeating haptic effect to the composition.

The startTimeMillis is the time in milliseconds from the start of the composition being built. The repeating effect will be scheduled to start at this time.

The durationMillis specifies the total length of one repeat cycle. If the provided effect has a shorter natural duration (the time from the start of the first segment to the end of the last segment), a pause (silence) will be added at the end of each cycle to fill the remaining time. For example, if the effect lasts 150ms and durationMillis is 1000ms, then the effect will play once and be followed by an 850ms pause before repeating again.

After this method is called, no more haptic elements can be added to the composition.

Parameters
startTimeMillis	long: The non-negative time in milliseconds from the start of the composition to start the repeating effect. Value is a non-negative duration in milliseconds.
effect	VibrationEffect: The non-repeating VibrationEffect to be repeated. This value cannot be null.
durationMillis	long: The positive total duration of each repeat cycle, including any trailing pause. Must be greater than or equal to the duration of the effect if the duration is known; otherwise, a best-effort check based on the estimated duration is performed to prevent impossible values. Value is 1 or greater. Value is a non-negative duration in milliseconds.

Returns
VibrationEffect.Builder	This Builder object. This value cannot be null.

Throws
IllegalArgumentException	if the provided effect is already repeating, if startTimeMillis is negative, or if durationMillis is not positive.
IllegalStateException	if a repeating effect has already been set, or if other elements are added after this call.
NullPointerException	if the provided effect is null.