This specification defines an API that provides access to the vibration mechanism of the hosting device. Vibration is a form of tactile feedback.

This document represents the consensus of the group on the scope and features of the Vibration API. It should be noted that the group is aware of more advanced use cases that cannot be realised using this simpler first version. The intent is to address them in a future revision.

Introduction

The Vibration API defines a means for web developers to programmatically provide tactile feedback in the form of vibration. The API is designed to tackle high-value use cases related to gaming, and is not meant to be used as a generic notification mechanism.

This specification defines conformance criteria that apply to a single product: the user agent that implements the interfaces that it contains.

Implementations that use ECMAScript to implement the APIs defined in this specification must implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [[!WEBIDL]], as this specification uses that specification and terminology.

Vibration Interface

void vibrate()
unsigned long time
Vibration time in milliseconds.
void vibrate()
unsigned long[] pattern
A vibration pattern represented by a list of time entries. Odd entries represent vibration time in milliseconds, even entries still periods in milliseconds between the vibrations.

The vibrate() method, when invoked, MUST run the algorithm for processing vibration patterns.

The rules for processing vibration patterns are as given in the following algorithm:

  1. If the hidden attribute [[!PAGE-VISIBILITY]] is set to true, abort these steps.
  2. Let pattern be the value of the first argument.
  3. If pattern is 0, or an empty list, cancel the pre-existing instance of the processing vibration patterns algorithm, if any, and abort these steps.
  4. If pattern is a list, proceed to the next step. Otherwise run the following substeps:
    1. Let list be an initially empty list, and add pattern to list.
    2. Let pattern be list.
  5. If any entry of pattern exceeds an implementation-dependent limit, then the user agent MAY throw a NotSupportedError exception [[!DOM4]] and abort these steps.
  6. If the length of pattern is even, then remove the last entry in pattern.
  7. If the length of pattern exceeds an implementation dependent limit, the user agent MAY throw a NotSupportedError exception [[!DOM4]] and abort these steps.
  8. Cancel the pre-existing instance of the processing vibration patterns algorithm, if any.
  9. An implementation MAY abort the algorithm at this point.
    For example, an implementation might abort the algorithm because the user has set a preference indicating that pages at a given origin should never be able to vibrate the device, or an implementation might cap the total amount of time a page may cause the device to vibrate and reject requests in excess of this limit.
  10. For each time in pattern, run the following substeps:
    1. If the index of time is even (the earliest even entry has index 0), vibrate the device for time milliseconds.
    2. Otherwise pause [[!HTML5]] for time milliseconds.

When the visibilitychange event [[!PAGE-VISIBILITY]] is dispatched at the Document, the user agent MUST run the following steps:

  1. If the hidden attribute [[!PAGE-VISIBILITY]] is set to true, the user agent MUST suppress the vibration produced by running the pre-existing instance of the processing vibration patterns algorithm, if any.
  2. If the hidden attribute [[!PAGE-VISIBILITY]] is set to false, the user agent MUST restore the vibration produced by running the pre-existing instance of the processing vibration patterns algorithm, if any.

If the device does not provide a vibration mechanism, or it is disabled, the user agent MUST silently ignore any invocations of the vibrate() method.

Examples

In the following example the device vibrates for 1 second: 

          // vibrate for 1 second
          navigator.vibrate(1000);
          
          // or alternatively
          navigator.vibrate([1000]);

In the following example the device vibrates for 1 second, is still for 0.5 seconds, and vibrates again for 2 seconds: 

          navigator.vibrate([1000, 500, 2000]);

The following example cancels any existing vibrations: 

            navigator.vibrate(0);
            
            // or alternatively
            navigator.vibrate([]);

Acknowledgements

The group is deeply indebted to Mounir Lamouri, Jonas Sicking, and the Mozilla WebAPI team in general for providing the WebVibrator prototype as an initial input.