Added in API level 30

Composition

class Composition
kotlin.Any
   ↳ android.os.VibrationEffect.Composition

A composition of haptic elements that are combined to be playable as a single VibrationEffect.

The haptic primitives are available as Composition.PRIMITIVE_* constants and can be added to a composition to create a custom vibration effect. Here is an example of an effect that grows in intensity and then dies off, with a longer rising portion for emphasis and an extra tick 100ms after: 

<code>VibrationEffect effect = VibrationEffect.startComposition()
      .addPrimitive(VibrationEffect.Composition.PRIMITIVE_SLOW_RISE, 0.5f)
      .addPrimitive(VibrationEffect.Composition.PRIMITIVE_QUICK_FALL, 0.5f)
      .addPrimitive(VibrationEffect.Composition.PRIMITIVE_TICK, 1.0f, 100)
      .compose();</code>

When choosing to play a composed effect, you should check that individual components are supported by the device by using Vibrator.arePrimitivesSupported.

Summary

Constants
static Int

The delay represents a pause in the composition between the end of the previous primitive and the beginning of the next one.
static Int

The delay represents an offset before starting this primitive, relative to the start time of the previous primitive in the composition.
static Int

This effect should produce a sharp, crisp click sensation.
static Int

This very short low frequency effect should produce a light crisp sensation intended to be used repetitively for dynamic feedback.
static Int

A haptic effect that simulates quick downwards movement with gravity.
static Int

A haptic effect that simulates quick upward movement against gravity.
static Int

A haptic effect that simulates slow upward movement against gravity.
static Int

A haptic effect that simulates spinning momentum.
static Int

A haptic effect that simulates downwards movement with gravity.
static Int

This very short effect should produce a light crisp sensation intended to be used repetitively for dynamic feedback.
Public methods
VibrationEffect.Composition
addPrimitive(primitiveId: Int)

Add a haptic primitive to the end of the current composition.
VibrationEffect.Composition
addPrimitive(primitiveId: Int, scale: Float)

Add a haptic primitive to the end of the current composition.
VibrationEffect.Composition
addPrimitive(primitiveId: Int, scale: Float, delay: Int)

Add a haptic primitive to the end of the current composition.
VibrationEffect.Composition
addPrimitive(primitiveId: Int, scale: Float, delay: Int, delayType: Int)

Add a haptic primitive to the end of the current composition.
VibrationEffect

Compose all of the added primitives together into a single VibrationEffect.

Constants

DELAY_TYPE_PAUSE

Added in API level Baklava
static val DELAY_TYPE_PAUSE: Int

The delay represents a pause in the composition between the end of the previous primitive and the beginning of the next one.

The primitive will start after the requested pause after the last primitive ended. The actual time the primitive will be played depends on the previous primitive's actual duration on the device hardware. This enables the combination of primitives to create more complex effects based on how close to each other they'll play. Here is an example: 

VibrationEffect popEffect = VibrationEffect.startComposition()
          .addPrimitive(PRIMITIVE_QUICK_RISE)
          .addPrimitive(PRIMITIVE_CLICK, 0.7, 50, DELAY_TYPE_PAUSE)
          .compose()
  
Value: 0

DELAY_TYPE_RELATIVE_START_OFFSET

Added in API level Baklava
static val DELAY_TYPE_RELATIVE_START_OFFSET: Int

The delay represents an offset before starting this primitive, relative to the start time of the previous primitive in the composition.

The primitive will start at the requested fixed time after the last primitive started, independently of that primitive's actual duration on the device hardware. This enables precise timings of primitives within a composition, ensuring they'll be played at the desired intervals. Here is an example: 

VibrationEffect.startComposition()
          .addPrimitive(PRIMITIVE_CLICK, 1.0)
          .addPrimitive(PRIMITIVE_TICK, 1.0, 20, DELAY_TYPE_RELATIVE_START_OFFSET)
          .addPrimitive(PRIMITIVE_THUD, 1.0, 80, DELAY_TYPE_RELATIVE_START_OFFSET)
          .compose()
Will be performed on the device as follows: 
0ms               20ms                     100ms
   PRIMITIVE_CLICK---PRIMITIVE_TICK-----------PRIMITIVE_THUD

A primitive will be dropped from the composition if it overlaps with previous ones.

Value: 1

PRIMITIVE_CLICK

Added in API level 30
static val PRIMITIVE_CLICK: Int

This effect should produce a sharp, crisp click sensation.

Value: 1

PRIMITIVE_LOW_TICK

Added in API level 31
static val PRIMITIVE_LOW_TICK: Int

This very short low frequency effect should produce a light crisp sensation intended to be used repetitively for dynamic feedback.

Value: 8

PRIMITIVE_QUICK_FALL

Added in API level 30
static val PRIMITIVE_QUICK_FALL: Int

A haptic effect that simulates quick downwards movement with gravity.

Value: 6

PRIMITIVE_QUICK_RISE

Added in API level 30
static val PRIMITIVE_QUICK_RISE: Int

A haptic effect that simulates quick upward movement against gravity.

Value: 4

PRIMITIVE_SLOW_RISE

Added in API level 30
static val PRIMITIVE_SLOW_RISE: Int

A haptic effect that simulates slow upward movement against gravity.

Value: 5

PRIMITIVE_SPIN

Added in API level 31
static val PRIMITIVE_SPIN: Int

A haptic effect that simulates spinning momentum.

Value: 3

PRIMITIVE_THUD

Added in API level 31
static val PRIMITIVE_THUD: Int

A haptic effect that simulates downwards movement with gravity. Often followed by extra energy of hitting and reverberation to augment physicality.

Value: 2

PRIMITIVE_TICK

Added in API level 30
static val PRIMITIVE_TICK: Int

This very short effect should produce a light crisp sensation intended to be used repetitively for dynamic feedback.

Value: 7

Public methods

addPrimitive

Added in API level 30
fun addPrimitive(primitiveId: Int): VibrationEffect.Composition

Add a haptic primitive to the end of the current composition.

Similar to addPrimitive(int,float,int), but with no delay and a default scale applied.

Parameters
primitiveId Int: The primitive to add Value is android.os.VibrationEffect.Composition#PRIMITIVE_CLICK, android.os.VibrationEffect.Composition#PRIMITIVE_THUD, android.os.VibrationEffect.Composition#PRIMITIVE_SPIN, android.os.VibrationEffect.Composition#PRIMITIVE_QUICK_RISE, android.os.VibrationEffect.Composition#PRIMITIVE_SLOW_RISE, android.os.VibrationEffect.Composition#PRIMITIVE_QUICK_FALL, android.os.VibrationEffect.Composition#PRIMITIVE_TICK, or android.os.VibrationEffect.Composition#PRIMITIVE_LOW_TICK
Return
VibrationEffect.Composition This Composition object to enable adding multiple elements in one chain. This value cannot be null.

addPrimitive

Added in API level 30
fun addPrimitive(
    primitiveId: Int, 
    scale: Float
): VibrationEffect.Composition

Add a haptic primitive to the end of the current composition.

Similar to addPrimitive(int,float,int), but with no delay.

Parameters
primitiveId Int: The primitive to add Value is android.os.VibrationEffect.Composition#PRIMITIVE_CLICK, android.os.VibrationEffect.Composition#PRIMITIVE_THUD, android.os.VibrationEffect.Composition#PRIMITIVE_SPIN, android.os.VibrationEffect.Composition#PRIMITIVE_QUICK_RISE, android.os.VibrationEffect.Composition#PRIMITIVE_SLOW_RISE, android.os.VibrationEffect.Composition#PRIMITIVE_QUICK_FALL, android.os.VibrationEffect.Composition#PRIMITIVE_TICK, or android.os.VibrationEffect.Composition#PRIMITIVE_LOW_TICK
scale Float: The scale to apply to the intensity of the primitive. Value is between 0f and 1f inclusive
Return
VibrationEffect.Composition This Composition object to enable adding multiple elements in one chain. This value cannot be null.

addPrimitive

Added in API level 30
fun addPrimitive(
    primitiveId: Int, 
    scale: Float, 
    delay: Int
): VibrationEffect.Composition

Add a haptic primitive to the end of the current composition.

Similar to addPrimitive(int,float,int,int), but default delay type applied is DELAY_TYPE_PAUSE.

Parameters
primitiveId Int: The primitive to add Value is android.os.VibrationEffect.Composition#PRIMITIVE_CLICK, android.os.VibrationEffect.Composition#PRIMITIVE_THUD, android.os.VibrationEffect.Composition#PRIMITIVE_SPIN, android.os.VibrationEffect.Composition#PRIMITIVE_QUICK_RISE, android.os.VibrationEffect.Composition#PRIMITIVE_SLOW_RISE, android.os.VibrationEffect.Composition#PRIMITIVE_QUICK_FALL, android.os.VibrationEffect.Composition#PRIMITIVE_TICK, or android.os.VibrationEffect.Composition#PRIMITIVE_LOW_TICK
scale Float: The scale to apply to the intensity of the primitive. Value is between 0f and 1f inclusive
delay Int: The amount of time in milliseconds to wait between the end of the last primitive and the beginning of this one (i.e. a pause in the composition). Value is 0 or greater
Return
VibrationEffect.Composition This Composition object to enable adding multiple elements in one chain. This value cannot be null.

addPrimitive

Added in API level Baklava
fun addPrimitive(
    primitiveId: Int, 
    scale: Float, 
    delay: Int, 
    delayType: Int
): VibrationEffect.Composition

Add a haptic primitive to the end of the current composition.

Parameters
primitiveId Int: The primitive to add Value is android.os.VibrationEffect.Composition#PRIMITIVE_CLICK, android.os.VibrationEffect.Composition#PRIMITIVE_THUD, android.os.VibrationEffect.Composition#PRIMITIVE_SPIN, android.os.VibrationEffect.Composition#PRIMITIVE_QUICK_RISE, android.os.VibrationEffect.Composition#PRIMITIVE_SLOW_RISE, android.os.VibrationEffect.Composition#PRIMITIVE_QUICK_FALL, android.os.VibrationEffect.Composition#PRIMITIVE_TICK, or android.os.VibrationEffect.Composition#PRIMITIVE_LOW_TICK
scale Float: The scale to apply to the intensity of the primitive. Value is between 0f and 1f inclusive
delay Int: The amount of time in milliseconds to wait before playing this primitive, as defined by the given delayType. Value is 0 or greater
delayType Int: The type of delay to be applied, e.g. a pause between last primitive and this one or a start offset. Value is android.os.VibrationEffect.Composition#DELAY_TYPE_PAUSE, or android.os.VibrationEffect.Composition#DELAY_TYPE_RELATIVE_START_OFFSET
Return
VibrationEffect.Composition This Composition object to enable adding multiple elements in one chain. This value cannot be null.

compose

Added in API level 30
fun compose(): VibrationEffect

Compose all of the added primitives together into a single VibrationEffect.

The Composition object is still valid after this call, so you can continue adding more primitives to it and generating more VibrationEffects by calling this method again.

Return
VibrationEffect The VibrationEffect resulting from the composition of the primitives. This value cannot be null.