BeatingEnvelopeBuilder

Kotlin |Java

class BeatingEnvelopeBuilder

kotlin.Any
↳	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 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:

<code>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();
  </code>

Summary

Nested classes
	`ControlPoint`

Public constructors
`BeatingEnvelopeBuilder(sharpness: Float, beatsPerSecond: Float)` Creates a new `BeatingEnvelopeBuilder` with the specified sharpness and beats per second.

Public methods
VibrationEffect.Envelope.BeatingEnvelopeBuilder	`addControlPoint(amplitudeScale: Float, durationMillis: Long)` Adds a new control point to the end of this beating envelope.
VibrationEffect.Envelope	`build()` Build the beating envelope as a single `Envelope`.

Public constructors

BeatingEnvelopeBuilder

Added in API level 10000

BeatingEnvelopeBuilder(
    sharpness: Float, 
    beatsPerSecond: Float)

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

fun addControlPoint(
    amplitudeScale: Float, 
    durationMillis: Long
): VibrationEffect.Envelope.BeatingEnvelopeBuilder

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.

Return
`VibrationEffect.Envelope.BeatingEnvelopeBuilder`	This `BeatingEnvelopeBuilder` object. This value cannot be `null`.

build

Added in API level 10000

fun build(): VibrationEffect.Envelope

Build the beating envelope as a single Envelope.

Return
`VibrationEffect.Envelope`	The `Envelope` resulting from the list of control points. This value cannot be `null`.

Exceptions
`java.lang.IllegalStateException`	if no control points were added to the builder, or if the last control point does not end at zero amplitude scale.