Vimeo Player API
The Vimeo Player API allows you to interact with and control an embedded Vimeo Player.
Installation
You can install the Vimeo Player API through either npm:
npm install @vimeo/player
Alternatively, you can reference an up‐to‐date version on our CDN:
<script src="https://player.vimeo.com/api/player.js"></script>
Warning: when used with RequireJS it's required to load the script dynamically via the RequireJS load system. http://www.requirejs.org/docs/api.html#jsfiles
Getting Started
In order to control the Vimeo player, you need a player to control. There are a few ways to get a player:
Pre-existing player
Already have a player on the page? Pass the element to the Vimeo.Player
constructor and you’re ready to go.
<iframe src="https://player.vimeo.com/video/76979871?h=8272103f6e" width="640" height="360" frameborder="0" allowfullscreen allow="autoplay; encrypted-media"></iframe>
<script src="https://player.vimeo.com/api/player.js"></script>
<script>
const iframe = document.querySelector('iframe');
const player = new Vimeo.Player(iframe);
player.on('play', function() {
console.log('played the video!');
});
player.getVideoTitle().then(function(title) {
console.log('title:', title);
});
</script>
Create with a video id or url
You can use the library to make the embed for you. All you need is an empty element and the video id or vimeo.com url (and optional embed options).
NOTE: If the video privacy settings are "Unlisted", instead of providing an id
property, you will need to provide the full video URL as a url
property and include the h
parameter.
<div id="made-in-ny"></div>
<script src="https://player.vimeo.com/api/player.js"></script>
<script>
const options = {
id: 59777392,
width: 640,
loop: true
};
const player = new Vimeo.Player('made-in-ny', options);
player.setVolume(0);
player.on('play', function() {
console.log('played the video!');
});
</script>
Automatically with HTML attributes
When the library loads, it will scan your page for elements with Vimeo
attributes. Each element must have at least a data-vimeo-id
or
data-vimeo-url
attribute in order for the embed to be created automatically.
You can also add attributes for any of the embed options,
prefixed with data-vimeo
(data-vimeo-portrait="false"
, for example).
NOTE: If the video privacy settings are "Unlisted", instead of providing a data-vimeo-id
attribute, you will need to provide the full video URL in a data-vimeo-url
attribute and include the h
parameter.
<div data-vimeo-id="19231868" data-vimeo-width="640" id="handstick"></div>
<div data-vimeo-url="https://player.vimeo.com/video/76979871?h=8272103f6e" id="playertwo"></div>
<script src="https://player.vimeo.com/api/player.js"></script>
<script>
// If you want to control the embeds, you’ll need to create a Player object.
// You can pass either the `<div>` or the `<iframe>` created inside the div.
const handstickPlayer = new Vimeo.Player('handstick');
handstickPlayer.on('play', function() {
console.log('played the handstick video!');
});
const playerTwoPlayer = new Vimeo.Player('playertwo');
playerTwoPlayer.on('play', function() {
console.log('played the player 2.0 video!');
});
</script>
Browser Support
The Player API library is supported in IE 11+, Chrome, Firefox, Safari, and Opera.
Migrate from Froogaloop
Using our old Froogaloop library? See the migration doc for details on how to update your code to use this library.
Using with a module bundler
If you’re using a module bundler like webpack or
rollup, the exported object will be the Player
constructor (unlike the browser where it is attached to window.Vimeo
):
import Player from '@vimeo/player';
const player = new Player('handstick', {
id: 19231868,
width: 640
});
player.on('play', function() {
console.log('played the video!');
});
Similarly, if you’re using RequireJS in the browser, it will also import the Player constructor directly:
<iframe src="https://player.vimeo.com/video/76979871?h=8272103f6e" width="640" height="360" frameborder="0" allowfullscreen allow="autoplay; encrypted-media"></iframe>
<script>
require(['https://player.vimeo.com/api/player.js'], function (Player) {
const iframe = document.querySelector('iframe');
const player = new Player(iframe);
player.on('play', function() {
console.log('played the video!');
});
});
</script>
Table of Contents
- Create a Player
- Embed Options
- Methods
- on
- off
- loadVideo
- ready
- enableTextTrack
- disableTextTrack
- pause
- play
- unload
- destroy
- requestFullscreen
- exitFullscreen
- getFullscreen
- requestPictureInPicture
- exitPictureInPicture
- getPictureInPicture
- remotePlaybackPrompt
- getRemotePlaybackAvailability
- getRemotePlaybackState
- getAutopause
- setAutopause
- getBuffered
- getChapters
- getCurrentChapter
- getColor
- getColors
- setColor
- setColors
- addCuePoint
- removeCuePoint
- getCuePoints
- getCurrentTime
- setCurrentTime
- getDuration
- getEnded
- getLoop
- setLoop
- getMuted
- setMuted
- getPaused
- getPlaybackRate
- setPlaybackRate
- getPlayed
- getSeekable
- getSeeking
- getTextTracks
- getVideoEmbedCode
- getVideoId
- getVideoTitle
- getVideoWidth
- getVideoHeight
- getVideoUrl
- getVolume
- setVolume
- setTimingSrc
- getQualities
- getQuality
- setQuality
- getCameraProps
- setCameraProps
- Events
- play
- playing
- pause
- ended
- timeupdate
- progress
- seeking
- seeked
- texttrackchange
- chapterchange
- cuechange
- cuepoint
- volumechange
- playbackratechange
- bufferstart
- bufferend
- error
- loaded
- durationchange
- fullscreenchange
- qualitychange
- camerachange
- resize
- enterpictureinpicture
- leavepictureinpicture
- remoteplaybackavailabilitychange
- remoteplaybackconnecting
- remoteplaybackconnect
- remoteplaybackdisconnect
- interactivehotspotclicked
- interactiveoverlaypanelclicked
Create a Player
The Vimeo.Player
object wraps an iframe so you can interact with and control a
Vimeo Player embed.
Existing embed
If you already have a Vimeo <iframe>
on your page, pass that element into the
constructor to get a Player
object. You can also use jQuery to select the
element, or pass a string that matches the id
of the <iframe>
.
// Select with the DOM API
const iframe = document.querySelector('iframe');
const iframePlayer = new Vimeo.Player(iframe);
// Select with jQuery
// If multiple elements are selected, it will use the first element.
const jqueryPlayer = new Vimeo.Player($('iframe'));
// Select with the `<iframe>`’s id
// Assumes that there is an <iframe id="player1"> on the page.
const idPlayer = new Vimeo.Player('player1');
Create an embed
Pass any element and an options object to the Vimeo.Player
constructor to make
an embed inside that element. The options object should consist of either an
id
or url
and any other embed options for the embed.
NOTE: If the video privacy settings are "Unlisted", instead of providing an id
property, you will need to provide the full video URL as a url
property and include the h
parameter.
<div id="made-in-ny"></div>
<script src="https://player.vimeo.com/api/player.js"></script>
<script>
const options = {
id: 59777392,
width: 640,
loop: true
};
// Will create inside the made-in-ny div:
// <iframe src="https://player.vimeo.com/video/59777392?h=ab882a04fd&loop=1" width="640" height="360" frameborder="0" allowfullscreen allow="autoplay; encrypted-media"></iframe>
const madeInNy = new Vimeo.Player('made-in-ny', options);
</script>
Embed options will also be read from the data-vimeo-*
attributes. Attributes
on the element will override any defined in the options object passed to the
constructor (similar to how the style
attribute overrides styles defined in
CSS).
Elements with a data-vimeo-id
or data-vimeo-url
attribute will have embeds
created automatically when the player API library is loaded. You can use the
data-vimeo-defer
attribute to prevent that from happening and create the embed
at a later time. This is useful for situations where the player embed wouldn’t
be visible right away, but only after some action was taken by the user (a
lightbox opened from clicking on a thumbnail, for example).
<div data-vimeo-id="59777392" data-vimeo-defer id="made-in-ny"></div>
<div data-vimeo-id="19231868" data-vimeo-defer data-vimeo-width="500" id="handstick"></div>
<script src="https://player.vimeo.com/api/player.js"></script>
<script>
const options = {
width: 640,
loop: true
};
// Will create inside the made-in-ny div:
// <iframe src="https://player.vimeo.com/video/59777392?h=ab882a04fd&loop=1" width="640" height="360" frameborder="0" allowfullscreen allow="autoplay; encrypted-media"></iframe>
const madeInNy = new Vimeo.Player('made-in-ny', options);
// Will create inside the handstick div:
// <iframe src="https://player.vimeo.com/video/19231868?h=1034d5269b&loop=1" width="500" height="281" frameborder="0" allowfullscreen allow="autoplay; encrypted-media"></iframe>
const handstick = new Vimeo.Player(document.getElementById('handstick'), options);
</script>
Embed Options
These options are available to be appended to the query string of the player URL, used as data-vimeo-
attributes on elements, or included as
an object passed to the Vimeo.Player
constructor. The complete list of embed options can be found in our official SDK documentation.
Methods
You can call methods on the player by calling the function on the Player object:
player.play();
All methods, except for on()
and off()
return a
Promise. The Promise may
or may not resolve with a value, depending on the specific method.
player.disableTextTrack().then(function() {
// the track was disabled
}).catch(function(error) {
// an error occurred
});
Promises for getters are resolved with the value of the property:
player.getLoop().then(function(loop) {
// whether or not the player is set to loop
});
Promises for setters are resolved with the value set, or rejected with an error if the set fails. For example:
player.setColor('#00adef').then(function(color) {
// the color that was set
}).catch(function(error) {
// an error occurred setting the color
});
on(event: string, callback: function): void
Add an event listener for the specified event. Will call the callback with a
single parameter, data
, that contains the data for that event. See
events below for