National Library of New Zealand
Harvested by the National Library of New Zealand on: Aug 24 2011 at 11:17:17 GMT
Search boxes and external links may not function. Having trouble viewing this page? Click here
Close Minimize Help
Wayback Machine

Overview

The JavaScript API allows you to control the Vimeo embedded player with JavaScript. There are a number of useful functions including, play, pause, seek, change volume, and more.

Getting Started

Note: you'll need to have this 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.

Flash Embed Code

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();

Universal Embed Code

This is our fancy new embed code that includes support for many devices. It looks like this:

<iframe src="http://player.vimeo.com/video/VIDEO_ID" width="400" height="225" frameborder="0"></iframe>

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, you can give each player a player_id to tell them apart:

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

Gotchas

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 the following browsers: Internet Explorer 8+, Firefox 3+, Safari 4+, Chrome, and Opera 9+.

Because of the complexities involved with postMessage, we've written a JS mini-library that does all the hard work for you! You can find it on the downloads page or you can see some examples below.

API Reference

Calling API methods differs between our two different embed methods. When using the Flash Embed Code, you can call these 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). Values are returned directly from the function call.

Note: all functions should be prefixed with api_ when using the Flash Embed Code.

When using the Universal Embed Code, you can call these by sending a serialized JSON object with postMessage() to the <iframe>. The following format should be used: (Omit the value key if the method requires no value.)

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

Data received from functions follows the same format, but with the addition of player_id if you've set one.

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; accurate to the second before the metadata has 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:String, listener:String):void
Adds a listener function for the specified event. listener is the name of the function to call when that event fires. This method differs slightly when using our Froogaloop library with the Universal Embed code, see below for details.

Events

All events return the same data format, with differing data depending on the event. If an event has no specific data, like play, the data key will not be returned at all.

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

The following events are available to listen to:

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

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

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

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

{"seconds":"4.308", "percent":"0.012", "duration":"359.000"}
play
Fired when the video begins to play.
pause
Fired when the video pauses.
finish
Fires when the video playback reaches the end.
seek

Fired when the user seeks. Includes seconds and percentage.

{"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

Flash HTML
Desktop Mobile Desktop Touch Mobile
play()
pause()
seek()
unload()
setLoop()
getCurrentTime()
getVolume()
setVolume()
setColor() ✓*
getDuration() ✓*
getVideoUrl() ✓*
getVideoEmbedCode() ✓*
addEventListener()

* Only available before play.

Events

Flash HTML
Desktop Mobile Desktop Touch Mobile
ready
loadProgress
playProgress
play
pause
finish
seek

Examples

We've created a page where you can test out the JavaScript API with our Universal Embed code. The example page and Froogaloop library are also available for download on GitHub.

JavaScript example and Froogaloop library on GitHub

Player API Playground on Vimeo