Vibration API

W3C Working Draft 17 November 2011

This version:
Latest published version:
Latest editor's draft:
Anssi Kostiainen, Nokia


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

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This document represents the early 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.

This document was published by the Device APIs Working Group as a First Public Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-device-apis@w3.org (subscribe, archives). All feedback is welcome.

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

Table of Contents

1. Introduction

This section is non-normative.

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.

2. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words must, must not, required, should, should not, recommended, may, and optional in this specification are to be interpreted as described in [RFC2119].

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

3. Vibration Interface

Navigator implements Vibration;

All instances of the Navigator type are defined to also implement the Vibration interface.

interface Vibration {
    void vibrate (optional unsigned long time) raises (NotSupportedError);
    void vibrate (optional unsigned long[] pattern) raises (NotSupportedError);

3.1 Methods

timeunsigned long Vibration time in milliseconds.
NOT_SUPPORTED_ERR (9) The time argument exceeds an implementation dependent limit.
Return type: void
patternunsigned long[] 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.
NOT_SUPPORTED_ERR (9) The length of the pattern argument exceeds an implementation-dependent limit, or one or more entries in the pattern argument exceed an implementation dependent limit.
Return type: void

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 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.

4. Examples

This section is non-normative.

This specification is inspired by Mozilla's Web Vibrator prototype. Below is an excerpt extracted from the source code to be more readily available:

 * Pulse the device's vibrator, if it has one.  If the device does not have a
 * vibrator, this function does nothing.
 * mozVibrate takes one optional argument.  The argument specifies how long
 * to vibrate for, or it gives a pattern of vibrator-on/vibrator-off timings.
 * If a vibration pattern is in effect when this function is called, this
 * call will overwrite the existing pattern, if this call successfully
 * completes.
 * We handle the argument to mozVibrate as follows.
 * - If the argument is undefined, null, 0, or the empty list, we cancel any
 *   outstanding vibration pattern; that is, we stop the device from vibrating.
 * - Otherwise, if the argument X is not a list, we treat it as though it's
 *   the singleton list [X] and then proceed as below.
 * - If the argument is a list (or if we wrapped it as a list above), then we
 *   try to convert each element in the list to an integer, by first
 *   converting it to a number and then rounding.  If we cannot convert any
 *   element to an integer, or if any of the integers are negative, we throw
 *   an illegal value exception.
 *   This list of integers specifies a vibration pattern.  Given a list of
 *   numbers
 *      [a_1, b_1, a_2, b_2, ..., a_n]
 *   the device will vibrate for a_1 milliseconds, then be still for b_1
 *   milliseconds, then vibrate for a_2 milliseconds, and so on.
 *   The list may contain an even or an odd number of elements, but if you
 *   pass an even number of elements (that is, if your list ends with b_n
 *   instead of a_n), the final element doesn't specify anything meaningful.
 *   We may throw an illegal value exception if the vibration pattern is too
 *   long, or if any of its elements is too large.
 void mozVibrate([optional] in jsval aPattern);

In the following example the device vibrates for 1 second:

// vibrate for 1 second

// or alternatively

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:


// or alternatively

A. Acknowledgements

Thanks to the Mozilla WebAPI team for providing the WebVibrator prototype as an initial input.

B. References

B.1 Normative references

Anne van Kesteren; Ms2ger. DOM4. 7 September 2011. W3C Editor's Draft. (Work in progress.) URL: http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html
Ian Hickson; David Hyatt. HTML5. 25 May 2011. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/html5
J. Mann; A. Jain. Page Visibility. 26 September 2011. W3C Editor's Draft. (Work in progress.) URL: http://dvcs.w3.org/hg/webperf/raw-file/tip/specs/PageVisibility/Overview.html
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt

B.2 Informative references

No informative references.