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.BasicEnvelopeBuilder#pubctors) \| [Methods](https://developer.android.com/reference/android/os/VibrationEffect.BasicEnvelopeBuilder#pubmethods) \| [Inherited Methods](https://developer.android.com/reference/android/os/VibrationEffect.BasicEnvelopeBuilder#inhmethods)
# VibrationEffect.BasicEnvelopeBuilder
*** ** * ** ***
`
public
static
final
class
VibrationEffect.BasicEnvelopeBuilder
`
`
extends https://developer.android.com/reference/java/lang/Object
`
`
`
|---|---|
| [java.lang.Object](https://developer.android.com/reference/java/lang/Object) ||
| ↳ | android.os.VibrationEffect.BasicEnvelopeBuilder |
*** ** * ** ***
A builder for waveform effects defined by their envelope, designed to provide a consistent
haptic perception across devices with varying capabilities.
This builder simplifies the creation of waveform effects by automatically adapting them
to different devices based on their capabilities. Effects are defined by control points
specifying target vibration intensity and sharpness, along with durations to reach those
targets. The vibrator will smoothly transition between these control points.
**Intensity:** Defines the overall strength of the vibration, ranging from
0 (off) to 1 (maximum achievable strength). Higher values result in stronger
vibrations. Supported intensity values guarantee sensitivity levels (SL) above
10 dB SL to ensure human perception.
**Sharpness:** Defines the crispness of the vibration, ranging from 0 to 1.
Lower values produce smoother vibrations, while higher values create a sharper,
more snappy sensation. Sharpness is mapped to its equivalent frequency within
the device's supported frequency range.
While this builder handles most of the adaptation logic, it does come with some
limitations:
- It may not use the full range of frequencies
- It's restricted to a frequency range that can generate output of at least 10 db SL
- Effects must end with a zero intensity control point. Failure to end at a zero intensity control point will result in an `https://developer.android.com/reference/java/lang/IllegalStateException`.
The builder automatically starts all effects at 0 intensity.
To avoid these limitations and to have more control over the effects output, use
`https://developer.android.com/reference/android/os/VibrationEffect.WaveformEnvelopeBuilder`, where direct amplitude and frequency values can be used.
For optimal cross-device consistency, it's recommended to limit the number of control
points to a maximum of 16. However this is not mandatory, and if a pattern exceeds the
maximum number of allowed control points, the framework will automatically break down the
effect to ensure it plays correctly.
For example, the following code creates a vibration effect that ramps up the intensity
from a low-pitched to a high-pitched strong vibration over 500ms and then ramps it down to
0 (off) over 100ms:
VibrationEffect effect = new VibrationEffect.BasicEnvelopeBuilder()
.setInitialSharpness(0.0f)
.addControlPoint(1.0f, 1.0f, 500)
.addControlPoint(0.0f, 1.0f, 100)
.build();
## Summary
| ### Public constructors ||
|---|---|
| ` https://developer.android.com/reference/android/os/VibrationEffect.BasicEnvelopeBuilder#BasicEnvelopeBuilder()() ` |
| ### Public methods ||
|---|---|
| ` https://developer.android.com/reference/android/os/VibrationEffect.BasicEnvelopeBuilder` | ` https://developer.android.com/reference/android/os/VibrationEffect.BasicEnvelopeBuilder#addControlPoint(float,%20float,%20long)(float intensity, float sharpness, 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.BasicEnvelopeBuilder#build()() ` Build the waveform as a single `https://developer.android.com/reference/android/os/VibrationEffect`. |
| ` https://developer.android.com/reference/android/os/VibrationEffect.BasicEnvelopeBuilder` | ` https://developer.android.com/reference/android/os/VibrationEffect.BasicEnvelopeBuilder#setInitialSharpness(float)(float initialSharpness) ` Sets the initial sharpness for the basic envelope effect. |
### 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
### BasicEnvelopeBuilder
Added in [API level 36](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public BasicEnvelopeBuilder ()
```
## Public methods
### addControlPoint
Added in [API level 36](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public VibrationEffect.BasicEnvelopeBuilder addControlPoint (float intensity,
float sharpness,
long durationMillis)
```
Adds a new control point to the end of this waveform envelope.
Intensity defines the overall strength of the vibration, ranging from 0 (off) to 1
(maximum achievable strength). Higher values translate to stronger vibrations.
Sharpness defines the crispness of the vibration, ranging from 0 to 1. Lower
values translate to smoother vibrations, while higher values create a sharper more snappy
sensation. This value is mapped to the supported frequency range of the device.
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()`.
| Parameters ||
|---|---|
| `intensity` | `float`: The target vibration intensity, ranging from 0 (off) to 1 (maximum strength). Value is between 0.0f and 1.0f inclusive
|
| `sharpness` | `float`: The target sharpness, ranging from 0 (smoothest) to 1 (sharpest). Value is between 0.0f and 1.0f inclusive
|
| `durationMillis` | `long`: The transition time in milliseconds. Value is a non-negative duration in milliseconds.
|
| Returns ||
|---|---|
| `https://developer.android.com/reference/android/os/VibrationEffect.BasicEnvelopeBuilder` | This value cannot be `null`.
|
### 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.BasicEnvelopeBuilder` 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.
| 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`.
|
| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalStateException` | if the last control point does not end at zero intensity. |
### setInitialSharpness
Added in [API level 36](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public VibrationEffect.BasicEnvelopeBuilder setInitialSharpness (float initialSharpness)
```
Sets the initial sharpness for the basic envelope effect.
The effect will start vibrating at this sharpness when it transitions to the
intensity and sharpness defined by the first control point.
The sharpness defines the crispness of the vibration, ranging from 0 to 1. Lower
values translate to smoother vibrations, while higher values create a sharper more snappy
sensation. This value is mapped to the supported frequency range of the device.
| Parameters ||
|---|---|
| `initialSharpness` | `float`: The starting sharpness of the vibration in the range of \[0, 1\]. Value is between 0.0f and 1.0f inclusive
|
| Returns ||
|---|---|
| `https://developer.android.com/reference/android/os/VibrationEffect.BasicEnvelopeBuilder` | This value cannot be `null`.
|