Android - Vibration, Vibrator, VibrationEffect example

App can vibrate the device through VibratorService.

There were API changes for each Android version, and we will introduce all the implementation methods of the old SDK to the latest (Android 12 or higher) SDK.

If your app is compiled with SDK API 30 (Android 12) or higher, you don`t have to look at the Legacy example or look at the Android 12 example code.

1. Vibrator SDK API History

So far, we have summarized the changes in the Vibrator API according to the Android version update.

1.1 Android O (API 26)

In versions below Android O (API 26), Vibrator was provided, and vibration was generated using the following APIs. These APIs have been deprecated in Android O.

• Vibrator.vibrate(long milliseconds)
• Vibrator.vibrate(long[] pattern, int repeat)

1.2 Android O (API 26) or higher, Android 11 (API 30) or higher

In Android O (API 26) or higher, Vibrate() API that receives VibrationEffect as an argument has been added, and it is recommended to use this to generate vibration.

• Vibrator.vibrate(VibrationEffect vibe)

1.3 Android 12 (API 31)

In Android 12, Vibrator is deprecated. Instead, the VibratorManager was added. You will need to use VibratorManager in the future.

2. Example: Generate vibration using vibrate() (below API 26)

For each Target SDK API, I will introduce examples of generating vibration.

A Vibrator object can be obtained like this:

val vibrator = getSystemService(Context.VIBRATOR_SERVICE) as Vibrator

The Vibrator.vibrator() API provides the following functions.

• Vibration (1 time)
• Pattern vibration (1 time)
• Repeating vibration

The full code can be found at GitHub - Vibration.

2.1 Vibration (1 time)

If you pass the time as an argument to vibrate(), vibration is generated for that time. The unit of time is milliseconds.

If I run the following code, I get one 200ms vibration.

val vibrator = getSystemService(Context.VIBRATOR_SERVICE) as Vibrator
vibrator.vibrate(200) // 200 ms

2.2 Pattern vibration (1 time)

If you pass the pattern array as a factor as follows, vibration is generated with the input pattern. The second argument means repeat, 0 means repeat, and -1 means do not repeat.

val vibrator = getSystemService(Context.VIBRATOR_SERVICE) as Vibrator
val pattern = longArrayOf(100, 200, 100, 200, 100, 200)
vibrator.vibrate(pattern, -1)

In the array of pattern, even Index means waiting time, odd Index means the time the vibration occurs.

Index 0: 100  // wait for 100ms
Index 1: 200  // vibrate for 200ms
Index 2: 100  // wait for 100ms
Index 3: 200  // vibrate for 200ms
Index 4: 100  // wait for 100ms
Index 5: 200  // vibrate for 200ms

2.3 Repeating vibration

The code below generates pattern vibration and repeats it. The argument Repeat = 0 means to repeat over and over.

val vibrator = getSystemService(Context.VIBRATOR_SERVICE) as Vibrator
val pattern = longArrayOf(100, 200, 100, 200, 100, 200)
vibrator.vibrate(pattern, 0)

To stop it, you can call cancel() like this:

val vibrator = getSystemService(Context.VIBRATOR_SERVICE) as Vibrator
vibrator.cancel()

2.4 Cancel vibration

To stop the loop or cancel the vibration, you can call cancel() like this:

val vibrator = getSystemService(Context.VIBRATOR_SERVICE) as Vibrator
vibrator.cancel()

3. Example: Vibration generation using VibrationEffect (API 26 or higher, API 30 or lower)

VibrationEffect provides the following creation methods:

• VibrationEffect.createOneShot()
• VibrationEffect.createWaveform()

You can see the project for this example in GitHub - Vibration.

3.1 Vibration generation (1 time)

To generate vibrations without a pattern, you need to create a VibrationEffect with VibrationEffect.createOneShot().

val vibrator = getSystemService(Context.VIBRATOR_SERVICE) as Vibrator
val effect = VibrationEffect.createOneShot(
        200, VibrationEffect.DEFAULT_AMPLITUDE)
vibrator.vibrate(effect)

The first argument is the vibration time to generate, in milliseconds. The second argument is the vibration strength, and a value of 1 ~ 255 should be passed. You can pass DEFAULT_AMPLITUDE to use the default vibration strength.

3.2 Pattern vibration (1 time)

To generate vibration with a pattern, you need to create a VibrationEffect with Vibrator.createWaveform().

The pattern (timing) is passed to the first argument of createWaveform(), the second argument is Repeat, -1 means no repetition, and more than 0 means repeat.

val vibrator = getSystemService(Context.VIBRATOR_SERVICE) as Vibrator
val timing = longArrayOf(100, 200, 100, 200, 100, 200)
val effect = VibrationEffect.createWaveform(timing, -1)
vibrator.vibrate(effect)

The even index of the pattern array is the waiting time, and the odd index is the time the vibration occurs.

Index 0: 100  // wait for 100ms
Index 1: 200  // vibrate for 200ms
Index 2: 100  // wait for 100ms
Index 3: 200  // vibrate for 200ms
Index 4: 100  // wait for 100ms
Index 5: 200  // vibrate for 200ms

3.3 Pattern (vibration intensity control) Vibration generation (1 time)

You can also adjust the vibration intensity of the transmitted pattern.

Pass an array of amplitudes like this:

val vibrator = getSystemService(Context.VIBRATOR_SERVICE) as Vibrator
val timing = longArrayOf(100, 200, 100, 200, 100, 200)
val amplitudes = intArrayOf(0, 50, 0, 100, 0, 200)
val effect = VibrationEffect.createWaveform(timing, amplitudes, -1)
vibrator.vibrate(effect)

Both the vibration pattern and the vibration intensity array must be the same length. Index 0 of the pattern corresponds to Index 0 of the vibration intensity.

That is, it behaves like this:

Index 0: 100  // wait for 100ms, Amplitude: 0
Index 1: 200  // vibrate for 200ms, Amplitude: 50
Index 2: 100  // wait for 100ms, Amplitude: 0
Index 3: 200  // vibrate for 200ms, Amplitude: 50
Index 4: 100  // wait for 100ms, Amplitude: 0
Index 5: 200  // vibrate for 200ms, Amplitude: 50

3.4 Repeating vibration

The last argument to createWaveform() determines whether to repeat the vibration. -1 means no repeat, 0 or higher means repeating from the index of the pattern to the end of the array.

That is, if you pass the repeat factor to 0 in the code below, pattern vibration is generated once and repeats infinitely from the 0th Index to the last. (Index 0 -> 1 -> 2 -> 3 -> 4 -> 5 -> 0 -> 1 -> 2 -> 3 -> 4 -> 5 -> 0 -> 1 ...)

val timing = longArrayOf(100, 200, 100, 200, 100, 200)
val amp = intArrayOf(0, 50, 0, 100, 0, 200)
val effect = VibrationEffect.createWaveform(timing, amp, 0)
vibrator.vibrate(effect)

If 4 is passed as the repeat factor, the pattern vibration is generated once, and Index 4 to 5 are repeated infinitely. (Index 0 -> 1 -> 2 -> 3 -> 4 -> 5 -> 4 -> 5 -> 4 -> 5 -> 4 ...)

val timing = longArrayOf(100, 200, 100, 200, 100, 200)
val amp = intArrayOf(0, 50, 0, 100, 0, 200)
val effect = VibrationEffect.createWaveform(timing, amp, 4)
vibrator.vibrate(effect)

3.5 Cancel vibration

To stop the loop or cancel the vibration, you can call cancel() like this:

val vibrator = getSystemService(Context.VIBRATOR_SERVICE) as Vibrator
vibrator.cancel()

4. Example: Vibration generation using VibrationManager of Android 12 (API 31 or higher)

VibratorManager was added in Android 12, you can import VibratorManager like this:

private val vibratorManager: VibratorManager by lazy {
    getSystemService(Context.VIBRATOR_MANAGER_SERVICE) as VibratorManager
}

You can see the project for this example in [GitHub - VibratorManagerInAndroid12] (https://github.com/codechacha/VibratorManagerInAndroid12).

4.1 Vibration generation (1 time)

If you run the following code, you will get one 500 ms vibration.

val vibrationEffect = VibrationEffect.createOneShot(
    500L,
    VibrationEffect.DEFAULT_AMPLITUDE
)
val combinedVibration = CombinedVibration.createParallel(vibrationEffect)
vibratorManager.vibrate(combinedVibration)

The first argument is the vibration time to generate, in milliseconds. The second parameter is the vibration strength, and a value between 1 and 255 must be passed. To use the default vibration strength, pass DEFAULT_AMPLITUDE.

4.2 Pattern vibration (1 time)

The code below generates one vibration in the pattern.

val timing = longArrayOf(100, 200, 100, 200, 100, 200)
val vibrationEffect = VibrationEffect.createWaveform(timing, -1)
val combinedVibration = CombinedVibration.createParallel(vibrationEffect)
vibratorManager.vibrate(combinedVibration)

The pattern (timing) is passed to the first argument of createWaveform(), the second argument is repeat, -1 means no repeat, and 0 or more means repeat.

The even index of the pattern array is the waiting time, and the odd index is the time the vibration occurs.

Index 0: 100  // wait for 100ms
Index 1: 200  // vibrate for 200ms
Index 2: 100  // wait for 100ms
Index 3: 200  // vibrate for 200ms
Index 4: 100  // wait for 100ms
Index 5: 200  // vibrate for 200ms

4.3 Pattern (vibration intensity control) (1 time)

You can also adjust the vibration intensity of the transmitted pattern. Pass an array of vibration amplitudes like this: The argument repeat = -1 means not to repeat.

val timing = longArrayOf(100, 200, 100, 200, 100, 200)
val amplitudes = intArrayOf(0, 50, 0, 100, 0, 200)
val vibrationEffect = VibrationEffect.createWaveform(timing, amplitudes, -1)
val combinedVibration = CombinedVibration.createParallel(vibrationEffect)
vibratorManager.vibrate(combinedVibration)

Both the vibration pattern and the vibration intensity array must be the same length. Index 0 of the pattern corresponds to Index 0 of the vibration intensity.

That is, it behaves like this:

Index 0: 100  // wait for 100ms, Amplitude: 0
Index 1: 200  // vibrate for 200ms, Amplitude: 50
Index 2: 100  // wait for 100ms, Amplitude: 0
Index 3: 200  // vibrate for 200ms, Amplitude: 50
Index 4: 100  // wait for 100ms, Amplitude: 0
Index 5: 200  // vibrate for 200ms, Amplitude: 50

4.4 Repeating vibration

If you pass a repeat factor of 0 or more, it repeats the vibration.

For example, if you pass the repeat factor to 0 in the code below, pattern vibration is generated once and repeats infinitely from the 0th Index to the last. (Index 0 -> 1 -> 2 -> 3 -> 4 -> 5 -> 0 -> 1 -> 2 -> 3 -> 4 -> 5 -> 0 -> 1 ...)

val timing = longArrayOf(100, 200, 100, 200, 100, 200)
val amplitudes = intArrayOf(0, 50, 0, 100, 0, 200)
val vibrationEffect = VibrationEffect.createWaveform(timing, amplitudes, 0)
val combinedVibration = CombinedVibration.createParallel(vibrationEffect)
vibratorManager.vibrate(combinedVibration)

If 4 is passed as the repeat factor, the pattern vibration is generated once, and Index 4 to 5 are repeated infinitely. (Index 0 -> 1 -> 2 -> 3 -> 4 -> 5 -> 4 -> 5 -> 4 -> 5 -> 4 ...)

val timing = longArrayOf(100, 200, 100, 200, 100, 200)
val amplitudes = intArrayOf(0, 50, 0, 100, 0, 200)
val vibrationEffect = VibrationEffect.createWaveform(timing, amplitudes, 4)
val combinedVibration = CombinedVibration.createParallel(vibrationEffect)
vibratorManager.vibrate(combinedVibration)

4.5 Cancel vibration

You can cancel an active vibration by calling cancel().

vibratorManager.cancel()