Vimeo Player API

Most methods on the Player object return a Promise.

• Getters: Promises resolve with the value of the property.
• Setters: Promises resolve with the value set, or reject with an error if the operation fails.
• Exceptions: Methods like play() and pause() may reject with PasswordError or PrivacyError if the video is protected.

Note: On iOS and some mobile devices, play() cannot be triggered programmatically until the user has interacted with the player.

// Example of a setter
player.setColor('#00adef').then(function(color) {
    // the color that was set
}).catch(function(error) {
    // an error occurred
});

// Example of a getter
player.getLoop().then(function(loop) {
    // whether or not the player is set to loop
});

You can sync a Timing Object to the player using setTimingSrc(). This allows real-time synchronization between the video and external data.

Installation:

npm install @vimeo/player timing-object

import Player from '@vimeo/player';
import {TimingObject} from 'timing-object';

const player = new Player('handstick', {
    id: 19231868,
    width: 640
});

const timingObject = new TimingObject();

// Updates to timingObject will reflect in the player
player.setTimingSrc(timingObject);

// Updates to the player will reflect in the timingObject
player.setTimingSrc(timingObject, {role: 'controller'});

If a Vimeo player (an <iframe>) is already present on your page, you can gain control over it by passing that element to the Vimeo.Player constructor. This allows you to listen to player events and call API methods on the existing embed.

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

You can install the Vimeo Player API via npm for use in module bundlers, or reference the latest version directly from the Vimeo CDN using a <script> tag.

Note for RequireJS users: You must load the script dynamically using the RequireJS load system.

npm install @vimeo/player

<script src="https://player.vimeo.com/api/player.js"></script>

The JS API library no longer requires you to wait for the ready event to begin using the player. You can remove the ready handler entirely and call .on() directly. If you prefer to keep setup code within a ready handler, use the player.ready() promise.

// Old Froogaloop
froogaloop.addEvent('ready', function() {
    froogaloop.addEvent('pause', onPause);
});

// New Vimeo Player (Recommended)
player.on('pause', onPause);

// New Vimeo Player (Using ready promise)
player.ready().then(function() {
    player.on('pause', onPause);
});

When using a module bundler like webpack or rollup, the package exports the Player constructor directly. You can import it and instantiate a new player by passing an element ID or an options object.

import Player from '@vimeo/player';

const player = new Player('handstick', {
    id: 19231868,
    width: 640
});

player.on('play', function() {
    console.log('played the video!');
});

You can use the library to generate a new embed by providing an empty HTML element (via its id) and an options object containing the video id or url.

Important for Unlisted videos: If a video's privacy settings are set to "Unlisted", you must provide the full video URL via the url property (including the h parameter) instead of using the id property.

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

All methods, getters, and setters are now functions directly on the Player object rather than being passed as strings to an .api() function. Crucially, all methods now return a Promise, so you should append a .catch() to handle potential errors.

// Old Froogaloop
froogaloop.api('getVideoUrl', function(url) {
    console.log('url:', url);
});

froogaloop.api('setColor', '00adef');

froogaloop.api('play');

// New Vimeo Player
player.getVideoUrl().then(function(url) {
    console.log('url:', url);
}).catch(function(error) {
    console.error('error:', error.name);
});

player.setColor('00adef').then(function(color) {
    console.log('color set to:', color);
}).catch(function(error) {
    console.error('error setting color:', error.name);
});

player.play().catch(function(error) {
    console.error('error playing the video:', error.name);
});

If you are using RequireJS in the browser, the library will also import the Player constructor directly in the callback function.

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