Added in [API level 36](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) Summary: [Ctors](https://developer.android.com/reference/android/os/VibrationEffect.WaveformEnvelopeBuilder#pubctors) \| [Methods](https://developer.android.com/reference/android/os/VibrationEffect.WaveformEnvelopeBuilder#pubmethods) \| [Inherited Methods](https://developer.android.com/reference/android/os/VibrationEffect.WaveformEnvelopeBuilder#inhmethods)

# VibrationEffect.WaveformEnvelopeBuilder

*** ** * ** ***


`
public
static
final

class
VibrationEffect.WaveformEnvelopeBuilder
`


`

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


`

`


`

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

<br />

*** ** * ** ***

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:

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

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 effects containing frequencies that
fall outside the device's supported range. It will also not attempt to correct or modify
these frequencies.

**Fallback Support:** Effects built by this builder (or envelopes created from it
and added to `https://developer.android.com/reference/android/os/VibrationEffect.Builder`) do not support automatic haptics fallback.
If the device does not support PWLE effects or the requested frequencies, the vibration
will not play.

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
`https://developer.android.com/reference/android/os/vibrator/VibratorFrequencyProfile` using the
`https://developer.android.com/reference/android/os/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: `https://developer.android.com/reference/android/os/vibrator/VibratorEnvelopeEffectInfo#getMaxSize()`
- Minimum control point duration: `https://developer.android.com/reference/android/os/vibrator/VibratorEnvelopeEffectInfo#getMinControlPointDurationMillis()`
- Maximum control point duration: `https://developer.android.com/reference/android/os/vibrator/VibratorEnvelopeEffectInfo#getMaxControlPointDurationMillis()`
- Maximum total effect duration: `https://developer.android.com/reference/android/os/vibrator/VibratorEnvelopeEffectInfo#getMaxDurationMillis()`

<br />

## Summary

| ### Public constructors ||
|---|---|
| ` https://developer.android.com/reference/android/os/VibrationEffect.WaveformEnvelopeBuilder#WaveformEnvelopeBuilder()() ` |

| ### Public methods ||
|---|---|
| ` https://developer.android.com/reference/android/os/VibrationEffect.WaveformEnvelopeBuilder` | ` https://developer.android.com/reference/android/os/VibrationEffect.WaveformEnvelopeBuilder#addControlPoint(float,%20float,%20long)(float amplitude, float frequencyHz, long durationMillis) ` Adds a new control point to the end of this waveform envelope. |
| ` https://developer.android.com/reference/android/os/VibrationEffect` | ` https://developer.android.com/reference/android/os/VibrationEffect.WaveformEnvelopeBuilder#build()() ` Build the waveform as a single `https://developer.android.com/reference/android/os/VibrationEffect`. |
| ` https://developer.android.com/reference/android/os/VibrationEffect.WaveformEnvelopeBuilder` | ` https://developer.android.com/reference/android/os/VibrationEffect.WaveformEnvelopeBuilder#setInitialFrequencyHz(float)(float initialFrequencyHz) ` Sets the initial frequency for the waveform in Hertz. |

### 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

### WaveformEnvelopeBuilder

Added in [API level 36](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

```
public WaveformEnvelopeBuilder ()
```

<br />

<br />

## Public methods

### addControlPoint

Added in [API level 36](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

```
public VibrationEffect.WaveformEnvelopeBuilder addControlPoint (float amplitude, 
                float frequencyHz, 
                long durationMillis)
```

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 `https://developer.android.com/reference/android/os/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
`https://developer.android.com/reference/android/os/vibrator/VibratorEnvelopeEffectInfo#getMinControlPointDurationMillis()`.

<br />

| 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.0f and 1.0f inclusive <br /> |
| `frequencyHz` | `float`: The frequency in Hz, must be greater than zero. Value is 0.0f or greater <br /> |
| `durationMillis` | `long`: The transition time in milliseconds. Value is a non-negative duration in milliseconds. <br /> |

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

### build

Added in [API level 36](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

```
public VibrationEffect build ()
```

Build the waveform as a single `https://developer.android.com/reference/android/os/VibrationEffect`.

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

<br />

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

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalStateException` | if no control points were added to the builder. |

### setInitialFrequencyHz

Added in [API level 36](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

```
public VibrationEffect.WaveformEnvelopeBuilder setInitialFrequencyHz (float initialFrequencyHz)
```

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 `https://developer.android.com/reference/android/os/Vibrator#getFrequencyProfile()`. Creating
effects using frequencies outside this range will result in the vibration not playing.

<br />

| Parameters ||
|---|---|
| `initialFrequencyHz` | `float`: The starting frequency of the vibration, in Hz. Must be greater than zero. Value is 0.0f or greater <br /> |

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