As part of Mozillas WebAPI effort, we have been working with bringing a Vibration API to all devices that support it.

The idea with the Vibration API is to be able to give the user a notification, in a game or other use case, by telling the device to vibrate. It accesses the native vibrator and tells it how long it should vibrate.

Examples

The way to do this is quite simple – in this example the parameter is how long it should vibrate, i.e. the number of milliseconds:

navigator.mozVibrate(1000);

Another way of controlling vibration is giving a vibration pattern, switching between vibrating and being still. The odd parameters in the list is vibration time, the even ones are pauses:

navigator.mozVibrate([200, 100, 200, 100]);

And if you want to stop the vibration, you can simply call the mozVibrate method with an argument of 0 or an empty pattern, like this:

navigator.mozVibrate(0);
navigator.mozVibrate([]);

Try it out!

If you want to try this out right now, you can do so in Firefox Aurora, which is planned to become Firefox 11. Currently, it naturally only works on devices that support vibration, which means Firefox on (most) Android phones.

Note: a possbile caveat could be if you have haptic feedback turned on on your Android device, which then might cancel out the vibration.

Demo

I put together a little demo where you can see the code needed and test it in place. Please play around with this and let us know what you think!

Edit: Our temporary implementation name was Vibrator API, but since it gave the wrong impression, we now call it Vibration API – which is also more in line with the W3C Vibration API draft.

31 comments

Post a comment
  1. Mustafa wrote on January 26th, 2012 at 7:32 am:

    Cool API its just ‘hard’ to remain serious when reading it :D

    Reply

    1. Robert Nyman wrote on January 26th, 2012 at 12:57 pm:

      It’s a temporary name, though, and will probably be Vibration, in line with W3C: http://www.w3.org/TR/vibration/

      Reply

  2. DaveC wrote on January 26th, 2012 at 7:40 am:

    Wow!… The a Vibrator API… my wife might finally take an interest in what I do!! ;)

    (Sorry couldn’t resist!)

    Reply

    1. Robert Nyman wrote on January 26th, 2012 at 12:59 pm:

      The name will likely be changed, though. It’s just a temporary one.

      Reply

  3. why wrote on January 26th, 2012 at 7:59 am:

    i dont get the point of giving an array where i could give a “rest” style signature, which could be solved as an array with a simple [].slice.call(arguments) …

    Reply

    1. Robert Nyman wrote on January 26th, 2012 at 8:48 am:

      In the future, there might might be more parameters – like the number a pattern should be repeated – so just having numbers wouldn’t do then.

      Reply

  4. Me wrote on January 26th, 2012 at 8:19 am:

    Didn”t work…

    Reply

    1. Robert Nyman wrote on January 26th, 2012 at 8:49 am:

      If you give us more information about what didn’t work, on which device and version of Firefox, we might be able to help.

      Reply

  5. Justin Lebar wrote on January 26th, 2012 at 8:34 am:

    And if you want to stop the vibration, you can simply call the mozVibrate method with an undefined argument, 0, null or empty pattern, like this:

    A null or undefined argument will cause mozVibrate to throw an error. 0 or [] works as intended.

    Reply

    1. Robert Nyman wrote on January 26th, 2012 at 8:50 am:

      True, for now. My understanding, though, is that those other two are supposed to work as well.

      Reply

      1. Justin Lebar wrote on January 26th, 2012 at 8:52 am:

        Nope.

        http://hg.mozilla.org/mozilla-central/file/e758551e3924/dom/base/Navigator.cpp#l672

        Reply

        1. Robert Nyman wrote on January 26th, 2012 at 8:56 am:

          Right, that has changed then. Looking at the W3C work, based on Mozilla’s, states that it would work: http://www.w3.org/TR/vibration/

          I’ll update the post to remove it then. Any reasoning for why it wouldn’t work would also be interesting, if you know more about it.

          Reply

  6. Justin Lebar wrote on January 26th, 2012 at 9:06 am:

    There’s a really long thread in the w3c list about this, but the gist is, it’s hard to make null and undefined work with how WebIDL is specified, so we dropped them.

    (Also, accepting undefined would mean that vibrate() makes the device stop vibrating, which is pretty weird.)

    The big comment taken from Mozilla’s source in the vibrator spec should be removed. It’s non-normative, old, incorrect, and misleading.

    I’ve e-mailed the spec’s author to try to get this clarified.

    Reply

    1. Robert Nyman wrote on January 26th, 2012 at 9:09 am:

      I understand.
      Thanks for the clarification!

      Reply

  7. mike nowak wrote on January 26th, 2012 at 9:21 am:

    > Currently, it naturally only works on devices that support vibration, which means Firefox on (most) Android phones.

    Any plans on integrating it with the progressing game-pad support API? Seems like a natural fit there.

    Reply

    1. Rob Hawkes wrote on January 26th, 2012 at 10:03 am:

      Hi Mike, there is work currently ongoing to bring what is known right now as rumble support to the gamepad. Right now it’s a different implementation to the Vibrator API but we’re aware that we need to find a common ground somewhere.

      Here are some links to the progress on gamepad rumble support:
      - http://blog.robothaus.org/2011/12/09/gamepad-vibration-zero-to-hero/
      - https://bugzilla.mozilla.org/show_bug.cgi?id=680289

      Reply

  8. Pete wrote on January 26th, 2012 at 9:59 am:

    “noticifaction” isn’t spelled quite right…

    Reply

    1. Robert Nyman wrote on January 26th, 2012 at 10:01 am:

      Thanks, I fixed that now. :-)

      Reply

  9. Max wrote on January 27th, 2012 at 1:41 am:

    Hej,

    thanks for the status update. I just installed Aurora and ran some tests, especially the ones written by John Hammink. One of these (or the combination of them?) led my phone to vibrate endlessly.

    Even when I killed the Aurora app the phone still vibrated and only stopped after several seconds (in which I nearly approached the point of rebooting).

    I couldn’t find any discussion or sth. about the security considerations relating to the Vibration API, even the W3C doesn’t mention such aspects in http://www.w3.org/TR/vibration/ .

    How is the Firefox team’s attitude towards these implications? At least https://wiki.mozilla.org/Security/Firefox/Fennec/WebVibrator#Threat_Brainstorming mentions some aspects but these don’t seem to be solved.

    Cheers!
    Max

    Reply

    1. Robert Nyman wrote on January 27th, 2012 at 2:49 am:

      Hi,

      Thanks for asking and testing!
      John’s test might not be entirely 1:1 with the current implementation, since it was a couple of months ago they were written, but I can confirm that something like that could happen.

      When it comes to security, I know that things like the tab should be visible has been discussed. I’ll ask someone in the team to reply, but also, feel free to discuss it in the WebAPI mailing list.

      Reply

    2. Justin Lebar wrote on January 27th, 2012 at 7:39 am:

      Max, can you please file a bug on this? This shouldn’t happen, but I need some more information to understand what’s going wrong.

      http://bugzilla.mozilla.org

      Reply

    3. Jonas Sicking wrote on January 30th, 2012 at 1:31 am:

      The security model for the vibration API is that we turn off the vibrator as soon as the user switches tabs or leaves/closes the page. In other words, if a page turns on the vibrator and the user is annoyed or worried about battery usage, simply leaving or closing whatever page the user is currently looking at should turn off the vibrator.

      So you can’t end up with the situation that happens in flash right now that “I have 50 tabs open and one of them is playing some sound, but I have no idea which”. A background tab can never turn on the vibrator. If the vibrator is on, it’s because of the page you are looking at right now. Just close it and the vibrator will turn off.

      Reply

  10. Adrian von Gegerfelt wrote on January 27th, 2012 at 5:48 am:

    What about the intensity of the vibration?

    Being a jQuery fan, I can’t help but think that adding lots of parameters if you wish to add pauses is a bit messy, I’d rather have something like

    vibrate[time,intensity]
    [something similar to wait()]
    vibrate[time,intensity]

    or like jQuery would do it with animation:

    navigator.vibrate(time, intensity).delay(time).vibrate(time, intensity).delay(time) etc…

    Reply

    1. Justin Lebar wrote on January 27th, 2012 at 7:38 am:

      Most hardware supports just one vibration intensity, so that’s what we started with.

      Reply

  11. Max wrote on January 27th, 2012 at 7:56 am:

    Justin,

    I’m gonna try to reproduce it and then file a bug. I’ll post the URL here when I’m done.

    Reply

    1. Robert Nyman wrote on January 30th, 2012 at 11:54 pm:

      Thank you!

      Reply

  12. Max wrote on January 30th, 2012 at 2:43 am:

    Jonas,

    that was what I expected but as I stated in my comment didn’t experience. I killed the app and the vibrator stayed on for some seconds. I still have to reproduce it, though.

    Max

    Reply

    1. Robert Nyman wrote on January 30th, 2012 at 11:53 pm:

      Yes, Jonas’ reply was more in general to your question about security implications for the Vibration API.

      Reply

  13. Pavel Pavlov wrote on February 1st, 2012 at 6:27 am:

    How do you turn it offf !? ..Please reply ASAP !

    Reply

    1. Robert Nyman wrote on February 1st, 2012 at 6:34 am:

      Do you mean programmatically (which is covered in the blog post) or as an end user?

      Reply

  14. Ollie Parsley wrote on February 22nd, 2012 at 2:54 pm:

    FYI, I just released a simple wrapper JS wrapper for the API called Vibrate.js. http://vibratejs.com

    Ollie

    Reply

Add your comment

  1.