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:

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.

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:


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"


play():void Plays the video.
pause():void Pauses the video.
paused():Boolean Returns false if the video is playing, true otherwise.
seekTo(seconds:Number):void Seeks to the specified point in the video. Will maintain the same playing/paused state. The Flash player will not seek past the loaded point, while the HTML player will seek to that spot regardless of how much of the video has been loaded.
unload():void Reverts the player back to the initial state.
getCurrentTime():Number Returns the elapsed time of the video in seconds. Accurate to 3 decimal places.
getDuration():Number Returns the duration of the video in seconds. Accurate to 3 decimal places after the video’s metadata has been loaded.
getVideoEmbedCode():String Returns the iframe embed code for the video.
getVideoHeight():Number Returns the native height of the video.
getVideoWidth():Number Returns the native width of the video.
getVideoUrl():String Returns the Vimeo URL of the video.
getColor():String Returns the hex color of the player.
setColor(color:String):void Sets the hex color of the player. Accepts both short and long hex codes.
setLoop(loop:Boolean):void Toggles loop on or off.
getVolume():Number Returns the player’s current volume, a number between 0 and 1.
setVolume(volume:Number):void Sets the volume of the player. Accepts a number between 0 and 1.
addEventListener(event:StringUtility, listener:String):void Adds a listener function for the specified event. listener is the name of the function to call when that event fires. If you’re using Froogaloop, this is handled in a different way. See the example above for details.

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.



Fired automatically when the player is ready to accept commands.

Do not try to add listeners or call functions before receiving this event.

When using the Flash Embed Code, the player will attempt to call vimeo_player_loaded(). You can change this using the js_ready flashvar. If a player_id has been set, it will be passed to that function as the first parameter.


Fired as the video is loading. Includes the percent loaded and the duration of the video. This also includes bytes loaded and bytes total in the Flash player.

The percent value differs between the Flash and HTML players. In Flash, it is the percentage of total bytes loaded, while in the HTML player, it is the percentage of the duration.


Fired as the video is playing. Includes seconds, percentage played, and the total duration.

play Fired when the video begins to play.
pause Fired when the video pauses.
finish Fires when the video playback reaches the end.

Fired when the user seeks. Includes seconds and percentage.



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.


Flash HTML
Desktop Mobile Desktop Touch Mobile
setColor() *
getDuration() *
getVideoUrl() *
getVideoEmbedCode() *

* Only available before play.


Flash HTML
Desktop Mobile Desktop Touch Mobile