JavaScript API

Getting Started

You’ll need to be running on a web server instead of opening the file directly in your browser. Flash and JS security restrictions will prevent the API from working when run locally.

The JavaScript API works in different ways depending on how the player is embedded. Check out each section below for the details of the differences between embedding codes. For more information on how to embed our player, see the embedding page.

Universal Embed Code

This is our fancy new embed code that includes support for many devices.

With the Universal Embed Code, the only way to interact with the player is by using window.postMessage. postMessage is a relatively new development, so it’s only available in Internet Explorer 8+, Firefox 3+, Safari 4+, Chrome, and Opera 9+.

To turn the API on, add api=1 to the URL of the iframe, like this:

http://player.vimeo.com/video/VIDEO_ID?api=1

If you’re embedding and controlling multiple players on a page or using our JS API library (Froogaloop), you should give each player a player_id that matches the id of the iframe element.

http://player.vimeo.com/video/VIDEO_ID?api=1&player_id=vimeoplayer

Calling the API with Froogaloop

Because of the complexities involved with postMessage, we’ve written a JS mini-library called Froogaloop that does all the hard work for you! You can find it on our GitHub page. Here is a quick example of how to use Froogaloop to listen for when the video finishes:

Calling the API Manually

If you’d rather not use Froogaloop, here’s how to call the API manually. You interact with the player by sending a serialized JSON object with postMessage() to the <iframe>. The following format should be used:

{
        "method": "methodName",
        "value": "value"
    }

Omit the value key if the method requires no value.

Here’s an example that will listen for some events and update the status text:

More Examples

We also have two more examples for you! Our JavaScript API Playground is an easy way to play around with all of the available API methods, and the Simple Player API Example is a simpler version with a bunch of comments to help you out.

Flash Embed Code

This version of the embed code is deprecated. Learn more.

This is the standard embed code for Flash that we’ve all come to love. The API is turned off by default for performance reasons, so to turn the API on, add api=1 to the flashvars like this:

<param name="flashvars" value="api=1" />

To communicate with the Flash player, you can call the functions directly on a reference to the <object> tag (you can get this by calling document.getElementById(), or using an equivalent function in your JS library of choice). Here’s a quick example of how to play a video:

document.getElementById('vimeo_player').api_play();

All methods should be prefixed with api_ when using the Flash Embed Code.

To add a listener for the finish event:

document.getElementById('vimeo_player').api_addEventListener('finish', function(event) {
        // do stuff here
    });

API Reference

Universal Embed Method Specification

When posting a message to the player via postMessage(), you should send a serialized object like this one:

{
        "method": "methodName",
        "value": "value"
    }

Methods

Remember, all methods should be prefixed with api_ when using the Flash Embed Code.

Universal Embed Event Specification

All events return a serialized version of an object in the following format:

{
        "event": "eventName",
        "player_id": "player_id",
        "data": {}
    }

Some events return data as defined in the table below. If the event does not return extra data (event and player_id are always returned), the data key will not be part of the object. For example, the play event returns no data key.

Events

{
        "percent":"0.326",
        "bytesLoaded":"32159909",
        "bytesTotal":"98650027",
        "duration":"365.507"
    }

{
        "seconds":"4.308",
        "percent":"0.012",
        "duration":"359.000"
    }

{
        "seconds":"192.622",
        "percent":"0.527",
        "duration":"365.507"
    }

Compatibility

We try hard to keep the JS API consistent across all of our various players, but sometimes it is not technically possible to do so. Below is a chart of our different players and which API methods are available.

Functions

* Only available before play.

Events