VibrationEffect.Envelope.BeatingEnvelopeBuilder

public static final class VibrationEffect.Envelope.BeatingEnvelopeBuilder
extends Object

java.lang.Object
   ↳ android.os.VibrationEffect.Envelope.BeatingEnvelopeBuilder

A builder to help users create rich and expressive beating vibrations, taking beats per second, vibration sharpness, and an amplitude scale envelope as input. Beats per second is the frequency of the beats, i.e., the number of beats per second. The sharpness defines the crispness of the vibration. The amplitude scale envelope defines the overall strength of the beats, which transitions from a starting amplitude scale to an ending amplitude scale over the specified duration.

Beats Per Second: The beating frequency in Hz, i.e., how many beats per second. It must be greater than zero. It is recommended to keep this value within the range of (0, 25] Hz. This ensures that the beating effect will have a more aligned and consistent behavior across different Android devices with basic envelope support.

Sharpness: Defines the crispness of the vibration, maps to the carrier frequency of the vibration, ranging from 0 (smoothest) to 1 (sharpest), inclusive. A value of VibrationEffect.RESONANT_FREQUENCY_SHARPNESS is mapped to the device's resonant frequency.

AmplitudeScale: Defines the overall strength of the vibration, ranging from 0 (off) to 1 (maximum achievable strength). The scale control points draw the envelope of the beats' peak amplitude. The envelope always starts at 0 scale, and must end with 0 scale.

DurationMillis: Defines the transition time (in milliseconds) from the previous control point to this new one. It must be strictly positive (greater than zero).

For example, the following code creates a beating vibration effect with a snappy sharpness and 8 beats per second. The amplitude scale ramps up to 0.8 over 500ms, stays at 0.8 for 500ms, and then ramps down to 0 (off) over 500ms: 

VibrationEffect.Envelope envelope =
    new VibrationEffect.Envelope.BeatingEnvelopeBuilder(/* sharpness= *\/ 0.8f,
            /* beatsPerSecond= *\/ 8.0f)
        .addControlPoint(0.8f, 500)
        .addControlPoint(0.8f, 500)
        .addControlPoint(0.0f, 500)
        .build();
VibrationEffect effect = new VibrationEffect.Builder()
    .addEnvelope(/* startTimeMillis= *\/ 0, envelope)
    .build();

Summary

Nested classes

class VibrationEffect.Envelope.BeatingEnvelopeBuilder.ControlPoint

 

Public constructors

BeatingEnvelopeBuilder(float sharpness, float beatsPerSecond)

Creates a new BeatingEnvelopeBuilder with the specified sharpness and beats per second.

Public methods

VibrationEffect.Envelope.BeatingEnvelopeBuilder addControlPoint(float amplitudeScale, long durationMillis)

Adds a new control point to the end of this beating envelope.

VibrationEffect.Envelope build()

Build the beating envelope as a single Envelope.

Inherited methods

Public constructors

BeatingEnvelopeBuilder

Added in API level 10000 
public BeatingEnvelopeBuilder (float sharpness, 
                float beatsPerSecond)

Creates a new BeatingEnvelopeBuilder with the specified sharpness and beats per second.

Parameters
sharpness float: The sharpness of the vibration, ranging from 0 (smoothest) to 1 (sharpest).
Value is between 0.0f and 1.0f inclusive
beatsPerSecond float: The beating frequency in Hz. Must be strictly positive.
Value is 0.0f or greater

Public methods

addControlPoint

Added in API level 10000 
public VibrationEffect.Envelope.BeatingEnvelopeBuilder addControlPoint (float amplitudeScale, 
                long durationMillis)

Adds a new control point to the end of this beating envelope.

Amplitude scale defines the overall strength of the vibration, ranging from 0 (off) to 1 (maximum achievable strength).

Time specifies the duration (in milliseconds) for the vibrator to smoothly transition from the previous control point to this new one. It must be strictly positive (greater than zero).

Parameters
amplitudeScale float: The target vibration amplitude scale, ranging from 0 (off) to 1 (maximum strength), inclusive.
Value is between 0.0f and 1.0f inclusive
durationMillis long: The transition time in milliseconds. Must be strictly positive.
Value is 1 or greater.
Value is a non-negative duration in milliseconds.
Returns
VibrationEffect.Envelope.BeatingEnvelopeBuilder This BeatingEnvelopeBuilder object.
This value cannot be null.

build

Added in API level 10000 
public VibrationEffect.Envelope build ()

Build the beating envelope as a single Envelope.

Returns
VibrationEffect.Envelope The Envelope resulting from the list of control points.
This value cannot be null.
Throws
IllegalStateException if no control points were added to the builder, or if the last control point does not end at zero amplitude scale.