Vibrator


public abstract class Vibrator
extends Object

java.lang.Object
   ↳ android.os.Vibrator


Class that operates the vibrator on the device.

If your process exits, any vibration you started will stop.

Summary

Constants

int VIBRATION_EFFECT_SUPPORT_NO

Vibration effect support: unsupported

This effect is not natively supported by the underlying hardware, although the system may still play a fallback vibration.

int VIBRATION_EFFECT_SUPPORT_UNKNOWN

Vibration effect support: unknown

The hardware doesn't report its supported effects, so we can't determine whether the effect is supported or not.

int VIBRATION_EFFECT_SUPPORT_YES

Vibration effect support: supported

This effect is supported by the underlying hardware.

Public methods

final int areAllEffectsSupported(int... effectIds)

Query whether the vibrator supports all the given effects.

final boolean areAllPrimitivesSupported(int... primitiveIds)

Query whether the vibrator supports all of the given primitives.

int[] areEffectsSupported(int... effectIds)

Query whether the vibrator natively supports the given effects.

boolean[] arePrimitivesSupported(int... primitiveIds)

Query whether the vibrator supports the given primitives.

abstract void cancel()

Turn the vibrator off.

int getId()

Return the ID of this vibrator.

int[] getPrimitiveDurations(int... primitiveIds)

Query the estimated durations of the given primitives.

float getQFactor()

Gets the Q factor of the vibrator.

float getResonantFrequency()

Gets the resonant frequency of the vibrator, if applicable.

abstract boolean hasAmplitudeControl()

Check whether the vibrator has amplitude control.

abstract boolean hasVibrator()

Check whether the hardware has a vibrator.

void vibrate(long milliseconds)

This method was deprecated in API level 26. Use vibrate(android.os.VibrationEffect) instead.

void vibrate(VibrationEffect vibe, VibrationAttributes attributes)

Vibrate with a given effect.

void vibrate(long[] pattern, int repeat)

This method was deprecated in API level 26. Use vibrate(android.os.VibrationEffect) instead.

void vibrate(VibrationEffect vibe, AudioAttributes attributes)

This method was deprecated in API level 33. Use vibrate(android.os.VibrationEffect, android.os.VibrationAttributes) instead.

void vibrate(long milliseconds, AudioAttributes attributes)

This method was deprecated in API level 26. Use vibrate(android.os.VibrationEffect, android.os.VibrationAttributes) instead.

void vibrate(VibrationEffect vibe)

Vibrate with a given effect.

void vibrate(long[] pattern, int repeat, AudioAttributes attributes)

This method was deprecated in API level 26. Use vibrate(android.os.VibrationEffect, android.os.VibrationAttributes) instead.

Inherited methods

Constants

VIBRATION_EFFECT_SUPPORT_NO

Added in API level 30
public static final int VIBRATION_EFFECT_SUPPORT_NO

Vibration effect support: unsupported

This effect is not natively supported by the underlying hardware, although the system may still play a fallback vibration.

Constant Value: 2 (0x00000002)

VIBRATION_EFFECT_SUPPORT_UNKNOWN

Added in API level 30
public static final int VIBRATION_EFFECT_SUPPORT_UNKNOWN

Vibration effect support: unknown

The hardware doesn't report its supported effects, so we can't determine whether the effect is supported or not.

Constant Value: 0 (0x00000000)

VIBRATION_EFFECT_SUPPORT_YES

Added in API level 30
public static final int VIBRATION_EFFECT_SUPPORT_YES

Vibration effect support: supported

This effect is supported by the underlying hardware.

Constant Value: 1 (0x00000001)

Public methods

areAllEffectsSupported

Added in API level 30
public final int areAllEffectsSupported (int... effectIds)

Query whether the vibrator supports all the given effects. If no argument is provided this method will always return VIBRATION_EFFECT_SUPPORT_YES.

If an effect is not supported, the system may still automatically fall back to a simpler vibration instead, which is not optimised for the specific device, however vibration isn't guaranteed in this case.

If the result is VIBRATION_EFFECT_SUPPORT_YES, all effects in the query are supported by the hardware.

If the result is VIBRATION_EFFECT_SUPPORT_NO, at least one of the effects in the query is not supported, and using them may fall back to an un-optimized vibration or no vibration.

If the result is VIBRATION_EFFECT_SUPPORT_UNKNOWN, the system doesn't know whether all the effects are supported. It may support any or all of the queried effects, but there's no way to programmatically know whether a vibrate(VibrationEffect) call will successfully cause a vibration. It's guaranteed, however, that none of the queried effects are definitively unsupported by the hardware.

Use areEffectsSupported(int) to get individual results for each effect.

Parameters
effectIds int: Which effects to query for. This value cannot be null. Value is VibrationEffect.EFFECT_TICK, VibrationEffect.EFFECT_CLICK, VibrationEffect.EFFECT_HEAVY_CLICK, or VibrationEffect.EFFECT_DOUBLE_CLICK

Returns
int Whether all specified effects are natively supported by the device. Empty query defaults to VIBRATION_EFFECT_SUPPORT_YES. Value is VIBRATION_EFFECT_SUPPORT_UNKNOWN, VIBRATION_EFFECT_SUPPORT_YES, or VIBRATION_EFFECT_SUPPORT_NO

areAllPrimitivesSupported

Added in API level 30
public final boolean areAllPrimitivesSupported (int... primitiveIds)

Query whether the vibrator supports all of the given primitives. If no argument is provided this method will always return true.

If a primitive is not supported by the device, then no vibration will occur if it is played.

Use arePrimitivesSupported(int) to get individual results for each primitive.

Parameters
primitiveIds int: Which primitives to query for. This value cannot be null. Value is VibrationEffect.Composition.PRIMITIVE_CLICK, VibrationEffect.Composition.PRIMITIVE_THUD, VibrationEffect.Composition.PRIMITIVE_SPIN, VibrationEffect.Composition.PRIMITIVE_QUICK_RISE, VibrationEffect.Composition.PRIMITIVE_SLOW_RISE, VibrationEffect.Composition.PRIMITIVE_QUICK_FALL, VibrationEffect.Composition.PRIMITIVE_TICK, or VibrationEffect.Composition.PRIMITIVE_LOW_TICK

Returns
boolean Whether all specified primitives are supported. Empty query defaults to true.

areEffectsSupported

Added in API level 30
public int[] areEffectsSupported (int... effectIds)

Query whether the vibrator natively supports the given effects.

If an effect is not supported, the system may still automatically fall back to playing a simpler vibration instead, which is not optimised for the specific device. This includes the unknown case, which can't be determined in advance, that will dynamically attempt to fall back if the optimised effect fails to play.

The returned array will be the same length as the query array and the value at a given index will contain VIBRATION_EFFECT_SUPPORT_YES if the effect at that same index in the querying array is supported, VIBRATION_EFFECT_SUPPORT_NO if it isn't supported, or VIBRATION_EFFECT_SUPPORT_UNKNOWN if the system can't determine whether it's supported or not, as some hardware doesn't report its effect capabilities.

Use areAllEffectsSupported(int) to get a single combined result, or for convenience when querying exactly one effect.

Parameters
effectIds int: Which effects to query for. This value cannot be null. Value is VibrationEffect.EFFECT_TICK, VibrationEffect.EFFECT_CLICK, VibrationEffect.EFFECT_HEAVY_CLICK, or VibrationEffect.EFFECT_DOUBLE_CLICK

Returns
int[] An array containing the systems current knowledge about whether the given effects are natively supported by the device, or not. This value cannot be null. Value is VIBRATION_EFFECT_SUPPORT_UNKNOWN, VIBRATION_EFFECT_SUPPORT_YES, or VIBRATION_EFFECT_SUPPORT_NO

arePrimitivesSupported

Added in API level 30
public boolean[] arePrimitivesSupported (int... primitiveIds)

Query whether the vibrator supports the given primitives. The returned array will be the same length as the query array and the value at a given index will contain whether the effect at that same index in the querying array is supported or not.

If a primitive is not supported by the device, then no vibration will occur if it is played.

Use areAllPrimitivesSupported(int) to get a single combined result, or for convenience when querying exactly one primitive.

Parameters
primitiveIds int: Which primitives to query for. This value cannot be null. Value is VibrationEffect.Composition.PRIMITIVE_CLICK, VibrationEffect.Composition.PRIMITIVE_THUD, VibrationEffect.Composition.PRIMITIVE_SPIN, VibrationEffect.Composition.PRIMITIVE_QUICK_RISE, VibrationEffect.Composition.PRIMITIVE_SLOW_RISE, VibrationEffect.Composition.PRIMITIVE_QUICK_FALL, VibrationEffect.Composition.PRIMITIVE_TICK, or VibrationEffect.Composition.PRIMITIVE_LOW_TICK

Returns
boolean[] Whether the primitives are supported. This value cannot be null.

cancel

Added in API level 1
public abstract void cancel ()

Turn the vibrator off.
Requires Manifest.permission.VIBRATE

getId

Added in API level 31
public int getId ()

Return the ID of this vibrator.

Returns
int A non-negative integer representing the id of the vibrator controlled by this service, or -1 this service is not attached to any physical vibrator.

getPrimitiveDurations

Added in API level 31
public int[] getPrimitiveDurations (int... primitiveIds)

Query the estimated durations of the given primitives.

The returned array will be the same length as the query array and the value at a given index will contain the duration in milliseconds of the effect at the same index in the querying array.

The duration will be positive for primitives that are supported and zero for the unsupported ones, in correspondence with arePrimitivesSupported(int).

Parameters
primitiveIds int: Which primitives to query for. This value cannot be null. Value is VibrationEffect.Composition.PRIMITIVE_CLICK, VibrationEffect.Composition.PRIMITIVE_THUD, VibrationEffect.Composition.PRIMITIVE_SPIN, VibrationEffect.Composition.PRIMITIVE_QUICK_RISE, VibrationEffect.Composition.PRIMITIVE_SLOW_RISE, VibrationEffect.Composition.PRIMITIVE_QUICK_FALL, VibrationEffect.Composition.PRIMITIVE_TICK, or VibrationEffect.Composition.PRIMITIVE_LOW_TICK

Returns
int[] The duration of each primitive, with zeroes for primitives that are not supported. This value cannot be null.

getQFactor

Added in API level 34
public float getQFactor ()

Gets the Q factor of the vibrator.

Returns
float the Q factor of the vibrator, or NaN if it's unknown, not applicable, or if this vibrator is a composite of multiple physical devices with different Q factors.

getResonantFrequency

Added in API level 34
public float getResonantFrequency ()

Gets the resonant frequency of the vibrator, if applicable.

Returns
float the resonant frequency of the vibrator, or NaN if it's unknown, not applicable, or if this vibrator is a composite of multiple physical devices with different frequencies.

hasAmplitudeControl

Added in API level 26
public abstract boolean hasAmplitudeControl ()

Check whether the vibrator has amplitude control.

Returns
boolean True if the hardware can control the amplitude of the vibrations, otherwise false.

hasVibrator

Added in API level 11
public abstract boolean hasVibrator ()

Check whether the hardware has a vibrator.

Returns
boolean True if the hardware has a vibrator, else false.

vibrate

Added in API level 1
Deprecated in API level 26
public void vibrate (long milliseconds)

This method was deprecated in API level 26.
Use vibrate(android.os.VibrationEffect) instead.

Vibrate constantly for the specified period of time.

The app should be in the foreground for the vibration to happen.


Requires Manifest.permission.VIBRATE

Parameters
milliseconds long: The number of milliseconds to vibrate.

vibrate

Added in API level 33
public void vibrate (VibrationEffect vibe, 
                VibrationAttributes attributes)

Vibrate with a given effect.

The app should be in the foreground for the vibration to happen. Background apps should specify a ringtone, notification or alarm usage in order to vibrate.


Requires Manifest.permission.VIBRATE

Parameters
vibe VibrationEffect: VibrationEffect describing the vibration to be performed. This value cannot be null.

attributes VibrationAttributes: VibrationAttributes corresponding to the vibration. For example, specify VibrationAttributes#USAGE_ALARM for alarm vibrations or VibrationAttributes#USAGE_RINGTONE for vibrations associated with incoming calls. This value cannot be null.

vibrate

Added in API level 1
Deprecated in API level 26
public void vibrate (long[] pattern, 
                int repeat)

This method was deprecated in API level 26.
Use vibrate(android.os.VibrationEffect) instead.

Vibrate with a given pattern.

Pass in an array of ints that are the durations for which to turn on or off the vibrator in milliseconds. The first value indicates the number of milliseconds to wait before turning the vibrator on. The next value indicates the number of milliseconds for which to keep the vibrator on before turning it off. Subsequent values alternate between durations in milliseconds to turn the vibrator off or to turn the vibrator on.

To cause the pattern to repeat, pass the index into the pattern array at which to start the repeat, or -1 to disable repeating.

The app should be in the foreground for the vibration to happen.


Requires Manifest.permission.VIBRATE

Parameters
pattern long: an array of longs of times for which to turn the vibrator on or off.

repeat int: the index into pattern at which to repeat, or -1 if you don't want to repeat.

vibrate

Added in API level 26
Deprecated in API level 33
public void vibrate (VibrationEffect vibe, 
                AudioAttributes attributes)

This method was deprecated in API level 33.
Use vibrate(android.os.VibrationEffect, android.os.VibrationAttributes) instead.

Vibrate with a given effect.

The app should be in the foreground for the vibration to happen. Background apps should specify a ringtone, notification or alarm usage in order to vibrate.


Requires Manifest.permission.VIBRATE

Parameters
vibe VibrationEffect: VibrationEffect describing the vibration to be performed.

attributes AudioAttributes: AudioAttributes corresponding to the vibration. For example, specify AudioAttributes#USAGE_ALARM for alarm vibrations or AudioAttributes#USAGE_NOTIFICATION_RINGTONE for vibrations associated with incoming calls.

vibrate

Added in API level 21
Deprecated in API level 26
public void vibrate (long milliseconds, 
                AudioAttributes attributes)

This method was deprecated in API level 26.
Use vibrate(android.os.VibrationEffect, android.os.VibrationAttributes) instead.

Vibrate constantly for the specified period of time.

The app should be in the foreground for the vibration to happen. Background apps should specify a ringtone, notification or alarm usage in order to vibrate.


Requires Manifest.permission.VIBRATE

Parameters
milliseconds long: The number of milliseconds to vibrate.

attributes AudioAttributes: AudioAttributes corresponding to the vibration. For example, specify AudioAttributes#USAGE_ALARM for alarm vibrations or AudioAttributes#USAGE_NOTIFICATION_RINGTONE for vibrations associated with incoming calls.

vibrate

Added in API level 26
public void vibrate (VibrationEffect vibe)

Vibrate with a given effect.

The app should be in the foreground for the vibration to happen.


Requires Manifest.permission.VIBRATE

Parameters
vibe VibrationEffect: VibrationEffect describing the vibration to be performed.

vibrate

Added in API level 21
Deprecated in API level 26
public void vibrate (long[] pattern, 
                int repeat, 
                AudioAttributes attributes)

This method was deprecated in API level 26.
Use vibrate(android.os.VibrationEffect, android.os.VibrationAttributes) instead.

Vibrate with a given pattern.

Pass in an array of ints that are the durations for which to turn on or off the vibrator in milliseconds. The first value indicates the number of milliseconds to wait before turning the vibrator on. The next value indicates the number of milliseconds for which to keep the vibrator on before turning it off. Subsequent values alternate between durations in milliseconds to turn the vibrator off or to turn the vibrator on.

To cause the pattern to repeat, pass the index into the pattern array at which to start the repeat, or -1 to disable repeating.

The app should be in the foreground for the vibration to happen. Background apps should specify a ringtone, notification or alarm usage in order to vibrate.


Requires Manifest.permission.VIBRATE

Parameters
pattern long: an array of longs of times for which to turn the vibrator on or off.

repeat int: the index into pattern at which to repeat, or -1 if you don't want to repeat.

attributes AudioAttributes: AudioAttributes corresponding to the vibration. For example, specify AudioAttributes#USAGE_ALARM for alarm vibrations or AudioAttributes#USAGE_NOTIFICATION_RINGTONE for vibrations associated with incoming calls.