Added in [version 37.2](https://developer.android.com/topic/libraries/support-library/revisions) Summary: [Ctors](https://developer.android.com/reference/android/os/VibrationEffect.Builder#pubctors) \| [Methods](https://developer.android.com/reference/android/os/VibrationEffect.Builder#pubmethods) \| [Inherited Methods](https://developer.android.com/reference/android/os/VibrationEffect.Builder#inhmethods)

# VibrationEffect.Builder

*** ** * ** ***


`
public
static
final

class
VibrationEffect.Builder
`


`

extends https://developer.android.com/reference/java/lang/Object


`

`


`

|---|---|
| [java.lang.Object](https://developer.android.com/reference/java/lang/Object) ||
| ↳ | android.os.VibrationEffect.Builder |

<br />

*** ** * ** ***

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

This API is the preferred alternative to `https://developer.android.com/reference/android/os/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 `https://developer.android.com/reference/android/os/VibrationEffect.Envelope`s, `https://developer.android.com/reference/android/os/VibrationEffect.Preset`s, and existing `https://developer.android.com/reference/android/os/VibrationEffect`s (as `https://developer.android.com/reference/android/os/VibrationEffect.Event`s) to create a complex waveform. Each element is added
with a specified `startTimeMillis`. Note that the use of legacy `https://developer.android.com/reference/android/os/VibrationEffect`s is not recommended here.

Additionally, a repeating part can be set using `https://developer.android.com/reference/android/os/VibrationEffect.Builder#setRepeatingEffect(long,%20android.os.VibrationEffect,%20long)`. 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
`https://developer.android.com/reference/android/os/VibrationEffect.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](https://source.android.com/docs/core/interaction/haptics/haptics-implement).

**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 `https://developer.android.com/reference/android/os/VibrationEffect.Envelope`s) or a minimum duration (1ms) for device-dependent elements (like `https://developer.android.com/reference/android/os/VibrationEffect.Preset`s).
If a potential overlap is detected at build time, an `https://developer.android.com/reference/java/lang/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 ||
|---|---|
| ` https://developer.android.com/reference/android/os/VibrationEffect.Builder#Builder()() ` Creates an empty `https://developer.android.com/reference/android/os/VibrationEffect.Builder` to compose a new `https://developer.android.com/reference/android/os/VibrationEffect`. |
| ` https://developer.android.com/reference/android/os/VibrationEffect.Builder#Builder(android.os.VibrationEffect)(https://developer.android.com/reference/android/os/VibrationEffect effect) ` Creates a `https://developer.android.com/reference/android/os/VibrationEffect.Builder` initialized with a copy of an existing `https://developer.android.com/reference/android/os/VibrationEffect`. |

| ### Public methods ||
|---|---|
| ` https://developer.android.com/reference/android/os/VibrationEffect.Builder` | ` https://developer.android.com/reference/android/os/VibrationEffect.Builder#addEnvelope(long,%20android.os.VibrationEffect.Envelope)(long startTimeMillis, https://developer.android.com/reference/android/os/VibrationEffect.Envelope envelope) ` Adds a haptic `https://developer.android.com/reference/android/os/VibrationEffect.Envelope` to the composition. |
| ` https://developer.android.com/reference/android/os/VibrationEffect.Builder` | ` https://developer.android.com/reference/android/os/VibrationEffect.Builder#addEvents(long,%20java.util.List<android.os.VibrationEffect.Event>)(long startTimeShiftMillis, https://developer.android.com/reference/java/util/List<https://developer.android.com/reference/android/os/VibrationEffect.Event> events) ` Adds a list of existing `https://developer.android.com/reference/android/os/VibrationEffect.Event`s to the composition. |
| ` https://developer.android.com/reference/android/os/VibrationEffect.Builder` | ` https://developer.android.com/reference/android/os/VibrationEffect.Builder#addPreset(long,%20android.os.VibrationEffect.Preset)(long startTimeMillis, https://developer.android.com/reference/android/os/VibrationEffect.Preset preset) ` Adds a predefined haptic `https://developer.android.com/reference/android/os/VibrationEffect.Preset` to the composition. |
| ` https://developer.android.com/reference/android/os/VibrationEffect` | ` https://developer.android.com/reference/android/os/VibrationEffect.Builder#build()() ` Builds the composed `https://developer.android.com/reference/android/os/VibrationEffect`. |
| ` https://developer.android.com/reference/android/os/VibrationEffect.Builder` | ` https://developer.android.com/reference/android/os/VibrationEffect.Builder#setRepeatingEffect(long,%20android.os.VibrationEffect,%20long)(long startTimeMillis, https://developer.android.com/reference/android/os/VibrationEffect effect, long durationMillis) ` Adds a repeating haptic effect to the composition. |

### Inherited methods

From class `

https://developer.android.com/reference/java/lang/Object

` `


https://developer.android.com/reference/java/lang/Object` `
https://developer.android.com/reference/java/lang/Object#clone()()
`

Creates and returns a copy of this object.


`


boolean` `
https://developer.android.com/reference/java/lang/Object#equals(java.lang.Object)(https://developer.android.com/reference/java/lang/Object obj)
`

Indicates whether some other object is "equal to" this one.


`


void` `
https://developer.android.com/reference/java/lang/Object#finalize()()
`

Called by the garbage collector on an object when garbage collection
determines that there are no more references to the object.


`


final

https://developer.android.com/reference/java/lang/Class<?>` `
https://developer.android.com/reference/java/lang/Object#getClass()()
`

Returns the runtime class of this `Object`.


`


int` `
https://developer.android.com/reference/java/lang/Object#hashCode()()
`

Returns a hash code value for the object.


`


final

void` `
https://developer.android.com/reference/java/lang/Object#notify()()
`

Wakes up a single thread that is waiting on this object's
monitor.


`


final

void` `
https://developer.android.com/reference/java/lang/Object#notifyAll()()
`

Wakes up all threads that are waiting on this object's monitor.


`


https://developer.android.com/reference/java/lang/String` `
https://developer.android.com/reference/java/lang/Object#toString()()
`

Returns a string representation of the object.


`


final

void` `
https://developer.android.com/reference/java/lang/Object#wait(long,%20int)(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` `
https://developer.android.com/reference/java/lang/Object#wait(long)(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` `
https://developer.android.com/reference/java/lang/Object#wait()()
`

Causes the current thread to wait until it is awakened, typically
by being *notified* or *interrupted*.


## Public constructors

### Builder

Added in [version 37.2](https://developer.android.com/topic/libraries/support-library/revisions)

```
public Builder ()
```

Creates an empty `https://developer.android.com/reference/android/os/VibrationEffect.Builder` to compose a new `https://developer.android.com/reference/android/os/VibrationEffect`.

<br />

### Builder

Added in [version 37.2](https://developer.android.com/topic/libraries/support-library/revisions)

```
public Builder (VibrationEffect effect)
```

Creates a `https://developer.android.com/reference/android/os/VibrationEffect.Builder` initialized with a copy of an existing `https://developer.android.com/reference/android/os/VibrationEffect`.

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

<br />

| Parameters ||
|---|---|
| `effect` | `VibrationEffect`: The `https://developer.android.com/reference/android/os/VibrationEffect` to initialize this builder with. This value cannot be `null`. <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalStateException` | if the `effect` is repeating. |
| `https://developer.android.com/reference/java/lang/NullPointerException` | if the provided `effect` is null. |

## Public methods

### addEnvelope

Added in [version 37.2](https://developer.android.com/topic/libraries/support-library/revisions)

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

Adds a haptic `https://developer.android.com/reference/android/os/VibrationEffect.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 `https://developer.android.com/reference/android/os/VibrationEffect.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
`https://developer.android.com/reference/android/os/VibrationEffect.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 `https://developer.android.com/reference/android/os/VibrationEffect.BasicEnvelopeBuilder`

will have fallback support.

<br />

| 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. <br /> |
| `envelope` | `VibrationEffect.Envelope`: The `https://developer.android.com/reference/android/os/VibrationEffect.Envelope` to add. This value cannot be `null`. <br /> |

| Returns ||
|---|---|
| `https://developer.android.com/reference/android/os/VibrationEffect.Builder` | This `https://developer.android.com/reference/android/os/VibrationEffect.Builder` object. This value cannot be `null`. <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalArgumentException` | if adding the envelope would result in overlapping haptic elements. |
| `https://developer.android.com/reference/java/lang/NullPointerException` | if the provided `envelope` is null. |

### addEvents

Added in [version 37.2](https://developer.android.com/topic/libraries/support-library/revisions)

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

Adds a list of existing `https://developer.android.com/reference/android/os/VibrationEffect.Event`s 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 `https://developer.android.com/reference/android/os/VibrationEffect#getEvents()` on non-repeating
effects.

<br />

| 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. <br /> |
| `events` | `List`: The list of events to add. This value cannot be `null`. <br /> |

| Returns ||
|---|---|
| `https://developer.android.com/reference/android/os/VibrationEffect.Builder` | This `https://developer.android.com/reference/android/os/VibrationEffect.Builder` object. This value cannot be `null`. <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalArgumentException` | if `startTimeShiftMillis` is negative or if adding any of the events would result in overlapping haptic elements. |
| `https://developer.android.com/reference/java/lang/NullPointerException` | if the provided `events` list is null. |

### addPreset

Added in [version 37.2](https://developer.android.com/topic/libraries/support-library/revisions)

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

Adds a predefined haptic `https://developer.android.com/reference/android/os/VibrationEffect.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 `https://developer.android.com/reference/android/os/VibrationEffect.Preset`
can be device-dependent. It is the caller's responsibility to choose an
appropriate `startTimeMillis` to avoid unintended overlaps.

<br />

| 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. <br /> |
| `preset` | `VibrationEffect.Preset`: The `https://developer.android.com/reference/android/os/VibrationEffect.Preset` to add. This value cannot be `null`. <br /> |

| Returns ||
|---|---|
| `https://developer.android.com/reference/android/os/VibrationEffect.Builder` | This `https://developer.android.com/reference/android/os/VibrationEffect.Builder` object. This value cannot be `null`. <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalArgumentException` | if adding the preset would result in overlapping haptic elements. |
| `https://developer.android.com/reference/java/lang/NullPointerException` | if the provided `preset` is null. |

### build

Added in [version 37.2](https://developer.android.com/topic/libraries/support-library/revisions)

```
public VibrationEffect build ()
```

Builds the composed `https://developer.android.com/reference/android/os/VibrationEffect`.

This method finalizes the composition of all added elements (Envelopes, Presets,
Events) and returns a single `https://developer.android.com/reference/android/os/VibrationEffect` that can be played by the vibrator.

The `https://developer.android.com/reference/android/os/VibrationEffect.Builder` object is still valid after this call, so you can
continue adding more elements to it and generate more `https://developer.android.com/reference/android/os/VibrationEffect`s by
calling this method again.

Automatic fallback will be supported for the built `https://developer.android.com/reference/android/os/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 `https://developer.android.com/reference/android/os/VibrationEffect.WaveformEnvelopeBuilder`).

<br />

| Returns ||
|---|---|
| `https://developer.android.com/reference/android/os/VibrationEffect` | The resulting `https://developer.android.com/reference/android/os/VibrationEffect`. This value cannot be `null`. <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalArgumentException` | if the validation of the composed effect fails (e.g., due to timing issues, invalid haptic element parameters). |
| `https://developer.android.com/reference/java/lang/IllegalStateException` | if the composition is empty. |

### setRepeatingEffect

Added in [version 37.2](https://developer.android.com/topic/libraries/support-library/revisions)

```
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.

<br />

| 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. <br /> |
| `effect` | `VibrationEffect`: The non-repeating `https://developer.android.com/reference/android/os/VibrationEffect` to be repeated. This value cannot be `null`. <br /> |
| `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. <br /> |

| Returns ||
|---|---|
| `https://developer.android.com/reference/android/os/VibrationEffect.Builder` | This `https://developer.android.com/reference/android/os/VibrationEffect.Builder` object. This value cannot be `null`. <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalArgumentException` | if the provided effect is already repeating, if `startTimeMillis` is negative, or if `durationMillis` is not positive. |
| `https://developer.android.com/reference/java/lang/IllegalStateException` | if a repeating effect has already been set, or if other elements are added after this call. |
| `https://developer.android.com/reference/java/lang/NullPointerException` | if the provided `effect` is null. |