Jekyll One

QuickSearch

Vimeo offered an API (Application Programming Interface) called the Vimeo Player API, which allowed developers to interact with and control Vimeo videos embedded on websites or applications.

The Vimeo Player API provides various functionalities and methods for developers to customize and enhance the Vimeo video playback experience.

30-60 Minutes to read

The Vimeo Player API allows you to interact with and control an embedded Vimeo Player. Some common use cases for the Vimeo Player API:

Controlling Playback

Developers could use the API to start, pause, seek, or stop video playback programmatically.

Customizing Player Appearance

The API allowed developers to customize the appearance of the Vimeo player, such as changing the color scheme, adding custom controls, and creating custom overlays.

Listening to Events

Developers could set up event listeners to respond to various player events, such as when a video starts playing, finishes playing, or encounters an error.

Retrieving Video Information

The API enabled developers to fetch information about the currently loaded video, such as its title, duration, and metadata.

Autoplay and Looping

Developers could use the API to enable autoplay and looping of Vimeo videos, depending on their specific requirements.

Analytics Integration

The API provided hooks for integrating video analytics and tracking user interactions with Vimeo videos.

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.

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', () => {
    console.log('played the video!');
  });
  player.getVideoTitle().then((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 Private, 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', () => {
    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).

If the video privacy settings are Private, 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 id="handstick" data-vimeo-id="19231868" data-vimeo-width="640"></div>
<div id="playertwo" data-vimeo-url="https://player.vimeo.com/video/76979871?h=8272103f6e"></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', () => {
    console.log('played the handstick video!');
  });
  const playerTwoPlayer = new Vimeo.Player('playertwo');
  playerTwoPlayer.on('play', () => {
    console.log('played the player 2.0 video!');
  });
</script>

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, browser-window—​new are Private, 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 id="made-in-ny" data-vimeo-id="59777392" data-vimeo-defer></div>
<div id="handstick" data-vimeo-id="19231868" data-vimeo-defer data-vimeo-width="500"></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. A complete list of embed options can be found in Vimeo’s official SDK documentation.

Option Default Description

id or url

NO defaults

The ID or the URL of the video on Vimeo. You must supply one of these values to identify the video.

When the video’s privacy setting is Unlisted, you must use the URL, and the URL must include the h parameter. For more information, see our introductory guide.

airplay

true

Whether AirPlay is enabled in the embeddable player.

AirPlay is a wireless streaming technology developed by Apple. In the context of video players like Vimeo, AirPlay wouldn’t be directly built into Vimeo itself (as Vimeo isn’t an Apple product).

However, if you’re using Vimeo on an Apple device (iPhone, iPad, Mac) and you want to watch the video on a larger screen, you might be able to use AirPlay to stream the video from your device to an AirPlay-compatible devices.

audio_tracks

true

Whether multiple audio tracks can appear in the embeddable player.

This option has no effect if your video doesn’t have additional audio tracks uploaded to it.

autopause

true

Whether to pause the current video when another.

Vimeo video on the same page starts to play. Set this value to false to permit simultaneous playback of all the videos on the page. This option has no effect if you’ve disabled cookies in your browser, either through browser settings or with an extension or plugin.

autoplay

false

Whether to start playback of the video automatically.

This feature might not work on all devices.

background

false

Whether the player is in background mode, which hides the playback controls, enables autoplay, and loops the video.

byline

true

Whether to display the video owner’s name.

cc

true

Whether closed captions are enabled in the embeddable player.

This option has no effect if your video doesn’t have captions or subtitles.

chapter_id

NO defaults

The chapter by ID to start playback at.

chapters

true

Whether chapters are enabled in the embeddable player.

This option has no effect if your video doesn’t have chapters set.

chromecast

true

Whether the Chromecast button appears in the embeddable player.

color

NO defaults

The hexadecimal accent color value of the playback controls, which is normally 00ADEF. The embed settings of the video might override this value. For more information about player colors, refer to the colors option.

colors

NO defaults

The hexadecimal color values of the player. The embed settings of the video might override these values. The order of the player colors is [Primary, Accent, Text/Icon, Background], with corresponding default values of ["000000", "00ADEF", "FFFFFF", "000000"].

controls

true

Whether to display the player’s interactive elements, including the play bar and sharing buttons.

Set this option to false for a chromeless experience. To control playback when the play/pause button is hidden, set autoplay to true, use keyboard controls (which remain active), or implement our player SDK.

dnt

false

Whether to prevent the player from tracking session data, including cookies.

Keep in mind that setting this argument to true also blocks video stats.

end_time

NO defaults

In Segmented Playback mode, the time in seconds where playback ends for the video. Setting this field enables Segmented Playback mode, where the video is presented as a segment of the original as defined by this field and the start_time field, with a duration in seconds equal to end_time minus start_time. If start_time is omitted, the start time defaults to 0.

fullscreen

true

Whether to show the fullscreen button in the embeddable player.

height

NO defaults

The height of the video in pixels.

interactive_markers

true

Whether to display markers representing the timestamp where hotspots appear on an interactive video.

interactive_params

NO defaults

Key-value pairs representing dynamic parameters that are utilized on interactive videos with dynamic elements, such as title=my-video,subtitle=interactive.

keyboard

true

Whether to enable keyboard input to trigger player events. This setting doesn’t affect tab control.

loop

false

Whether to restart the video automatically after reaching the end.

maxheight

NO defaults

The height of the video in pixels, where the video won’t exceed its native height, no matter the value of this field.

maxwidth

NO defaults

The width of the video in pixels, where the video won’t exceed its native width, no matter the value of this field.

muted

false

Whether the video is muted upon loading. The true value is required for the autoplay behavior in some browsers.

pip

true

Whether to include the picture-in-picture button among the player controls and enable the Picture-in-Picture API, where supported.

play_button_position

auto

The position of the play button within the embeddable player. Other possible values include bottom and center.

playsinline

true

Whether the video plays inline on supported mobile devices.

To force the device to play the video in fullscreen mode instead, set this value to false.

portrait

true

Whether to display the video owners portrait.

progress_bar

true

Whether to show the progress bar in the embeddable player.

quality

auto

The playback quality of the video.

Use auto for the best possible quality given available bandwidth and other factors. You can also specify 360p, 540p, 720p, 1080p, 2k, and 4k.

quality_selector

true

Whether to show the quality selector in the embeddable player.

responsive

false

Whether to return a responsive embed code, or one that provides intelligent adjustments based on viewing conditions.

This option is recommend for mobile-optimized sites.

speed

false

Whether to include playback speed among the player preferences.

start_time

0

In Segmented Playback mode, the time in seconds where playback starts for the video; see the end_time field for more information.

texttrack

NO defaults

The text track to display with the video.

Specify the text track by its language code (en), the language code and locale (en-US), or the language code and kind (en.captions).

For this argument to work, the video must already have a text track of the given type. See the Help Center or Working with Text Track Uploads for more information.

To enable automatically generated closed captions instead, provide the value en-x-autogen. Please note that, at the present time, automatic captions are always in English.

title

true

Whether to display the video’s title.

transcript

true

Whether transcript controls can appear in the embeddable player.

transparent

true

Whether the responsive player and transparent background are enabled.

vimeo_logo

true

Whether to show the Vimeo logo in the embeddable player.

volume

true

Whether to show the volume selector in the embeddable player.

watch_full_video

true

Whether to show the Watch Full Video button when Segmented Playback mode is enabled.

See start_time and end_time above for more information.

width

NO defaults

The width of the video in pixels.

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(() =>{
  // the track was disabled
}).catch((error) => {
  // an error occurred
});

Promises for getters are resolved with the value of the property:

player.getLoop().then((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((color) => {
  // the color that was set
}).catch((error) => {
  // an error occurred setting the color
});

on()

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

Type: void
Parameters: event: string, callback: function

const onPlay = (data) => {
  // data is an object containing properties specific to that event
};
player.on('play', onPlay);

off()

Remove an event listener for the specified event. Will remove all listeners for that event if a callback isn’t passed, or only that specific callback if it is passed.

Type: void
Parameters: event: string, callback: function

const onPlay = (data) => {
  // data is an object containing properties specific to that event
};
player.on('play', onPlay);
// If later on you decide that you don’t need to listen for play anymore.
player.off('play', onPlay);
// Alternatively, `off` can be called with just the event name to remove all
// listeners.
player.off('play');

loadVideo()

Load a new video into this embed. The promise will be resolved if the video is successfully loaded, or it will be rejected if it could not be loaded.

Promise<number|object, (TypeError|PasswordError|Error)>
Parameters: options: number|string|object

If the video privacy settings are Private, instead of providing an id argument, you will need to provide the full video URL as a url argument and include the h parameter.

player.loadVideo(76979871).then((id) => {
// the video successfully loaded
}).catch((error) => {
  switch (error.name) {
    case 'TypeError':
      // the id was not a number
      break;
    case 'PasswordError':
      // the video is password-protected and the viewer needs to enter the
      // password first
      break;
    case 'PrivacyError':
      // the video is password-protected or private
      break;
    default:
      // some other error occurred
      break;
  }
});

ready()

Trigger a function when the player iframe has initialized. You do not need to wait for ready to trigger to begin adding event listeners or calling other methods.

Promise<void, Error>

player.ready().then(() => {
  // the player is ready
});

enableTextTrack()

Enable the text track with the specified language, and optionally the specified kind (captions or subtitles).

When set via the API, the track language will not change the viewer’s stored preference.

Promise<object, (InvalidTrackLanguageError|InvalidTrackError|Error)>
Parameters: language: string

player.enableTextTrack('en').then((track) => {
  // track.language = the iso code for the language
  // track.kind = 'captions' or 'subtitles'
  // track.label = the human-readable label
}).catch((error) => {
  switch (error.name) {
    case 'InvalidTrackLanguageError':
      // no track was available with the specified language
      break;
    case 'InvalidTrackError':
      // no track was available with the specified language and kind
      break;
    default:
      // some other error occurred
      break;
  }
});

disableTextTrack()

Disable the currently-active text track.

Promise<void, Error>

player.disableTextTrack().then(() => {
  // the track was disabled
}).catch((error) => {
  // an error occurred
});

pause()

Pause the video if it’s playing.

Promise<void, (PasswordError|PrivacyError|Error)>

player.pause().then(() => {
// the video was paused
}).catch((error) => {
  switch (error.name) {
    case 'PasswordError':
      // the video is password-protected and the viewer needs to enter the
      // password first
      break;
    case 'PrivacyError':
      // the video is private
      break;
    default:
      // some other error occurred
      break;
  }
});

play()

Play the video if it’s paused.

On iOS and some other mobile devices, you cannot programmatically trigger play. Once the viewer has tapped on the play button in the player, however, you will be able to use this function.

Promise<void, (PasswordError|PrivacyError|Error)>

player.play().then(() => {
// the video was played
}).catch((error) => {
  switch (error.name) {
    case 'PasswordError':
      // the video is password-protected and the viewer needs to enter the
      // password first
      break;
    case 'PrivacyError':
      // the video is private
      break;
    default:
      // some other error occurred
      break;
    }
});

unload()

Return the internal player (iframe) to its initial state.

Promise<void, Error>

player.unload().then(() => {
  // the video was unloaded
}).catch((error) => {
  // an error occurred
});

destroy()

Cleanup the player and remove it from the DOM. It won’t be usable and a new one should be constructed in order to do any operations.

Promise<void, Error>

player.destroy().then(() => {
  // the player was destroyed
}).catch((error) => {
  // an error occurred
});

requestFullscreen()

Request the player enters fullscreen.

Promise<void, Error>

player.requestFullscreen().then(() => {
  // the player entered fullscreen
}).catch((error) => {
  // an error occurred
});

exitFullscreen()

Request the player exits fullscreen.

Promise<void, Error>

player.exitFullscreen().then(() => {
  // the player exits fullscreen
}).catch((error) => {
  // an error occurred
});

getFullscreen()

Checks whether the player is currently fullscreen.

Promise<boolean, Error>

player.getFullscreen().then((fullscreen) => {
  // fullscreen = whether fullscreen is turned on or off
}).catch((error) => {
  // an error occurred
});

requestPictureInPicture()

Request the player enters picture-in-picture.

Promise<void, Error>

player.requestPictureInPicture().then(() => {
  // the player entered picture-in-picture
}).catch((error) => {
  // an error occurred
});

exitPictureInPicture()

Request the player exits picture-in-picture.

Promise<void, Error>

player.exitPictureInPicture().then(() => {
  // the player exits picture-in-picture
}).catch((error) => {
  // an error occurred
});

getPictureInPicture

Checks whether the player is currently picture-in-picture.

Promise<boolean, Error>

player.getPictureInPicture().then((pip) => {
  // pip = whether picture-in-picture is turned on or off
}).catch((error) => {
  // an error occurred
});

remotePlaybackPrompt()

Prompt the viewer to activate or deactivate a remote playback device, if one is available.

Promise<void, Error>

This method may require user interaction directly with the player before working properly and must be triggered by a user interaction. It is best to wait for initial playback before calling this method.

player.remotePlaybackPrompt().then(() => {
// viewer has been prompted
}).catch((error) => {
  switch (error.name) {
    case 'NotFoundError':
      // remote playback is not supported or there is no device available
      break;
    default:
      // some other error occurred
      break;
  }
});

getRemotePlaybackAvailability()

Checks if there is a remote playback device available.

Promise<string, Error>

player.getRemotePlaybackAvailability().then((remotePlaybackAvailable) => {
  // remotePlaybackAvailable = whether there is a remote playback device available or not
}).catch((error) => {
  // an error occurred
})

getRemotePlaybackState()

Get the current state of remote playback. Can be one of connecting, connected, or disconnected. These values are equivalent to the state values in the Remote Playback API.

Promise<boolean, Error>

player.getRemotePlaybackState().then((remotePlaybackState) => {
  // remotePlaybackState === 'connecting': player is attempting to connect to the remote device
  // remotePlaybackState === 'connected': player successfully connected and is playing on the remote playback device
  // remotePlaybackState === 'disconnected': player is not connected to a remote playback device
}).catch((error) => {
  // an error occurred
})

getAutopause()

Get the autopause behavior for this player.

Promise<boolean, (UnsupportedError|Error)>

player.getAutopause().then((autopause) => {
  // autopause = whether autopause is turned on or off
}).catch((error) => {
  switch (error.name) {
    case 'UnsupportedError':
      // Autopause is not supported with the current player or browser
      break;
    default:
      // some other error occurred
      break;
  }
});

setAutopause()

Enable or disable the autopause behavior of this player. By default, when another video is played in the same browser, this player will automatically pause. Unless you have a specific reason for doing so, we recommend that you leave autopause set to the default what equals to true.

Promise<boolean, (UnsupportedError|Error)>
Parameters: autopause: boolean

player.setAutopause(false).then((autopause) => {
  // autopause was turned off
}).catch((error) => {
  switch (error.name) {
    case 'UnsupportedError':
      // Autopause is not supported with the current player or browser
      break;
    default:
      // some other error occurred
      break;
  }
});

getBuffered()

Get the buffered time ranges of the video.

Promise<array, Error>

player.getBuffered().then((buffered) => {
  // buffered = an array of the buffered video time ranges.
}).catch((error) => {
  // an error occurred
});

getChapters()

Get an array of the chapters that are on the video.

Promise<array, Error>

player.getChapters().then((chapters) => {
  // chapters = an array of chapters objects
}).catch((error) => {
  // an error occurred
});

Each chapters object looks like this:

{
  "startTime":  15,
  "title":      "Chapter Title",
  "index":      1
}

getCurrentChapter()

Get the current chapter. A chapter is current when the currentTime of the video is equal to or after its startTime and before the startTime of the next chapter or the end of the video.

Promise<object, Error>

player.getCurrentChapter().then((chapter) => {
  // chapter = a chapter object
}).catch((error) => {
  // an error occurred
});

getColor()

Get the accent color for this player. Note that this is deprecated in place of getColors.

Promise<string, Error>

player.getColor().then((color) => {
  // color = the hex color of the player
}).catch((error) => {
  // an error occurred
});

getColors()

Get all colors used for this player. The return value is an array of primary, accent, text/icon, and background.

Promise<string[], Error>

player.getColors().then((colors) => {
  // colors = [primary, accent, text/icon, background]
}).catch((error) => {
  // an error occurred
});

setColor()

Set the accent color of this player to a hex or rgb string. Setting the color may fail if the owner of the video has set their embed preferences to force a specific color. Note that this setter is deprecated and should be replaced with setColors.

Promise<string, (ContrastError|TypeError|Error)>
Parameters: color: string

player.setColor('#00adef').then((color) => {
  // color was successfully set
}).catch((error) => {
  switch (error.name) {
    case 'TypeError':
      // the string was not a valid hex or rgb color
      break;
    case 'EmbedSettingsError':
      // the owner of the video has chosen to use a specific color
      break;
    default:
      // some other error occurred
      break;
  }
});

setColors()

Set all colors of this player with an array of hex values. Setting the color may fail if the owner of the video has set their embed preferences to force a specific color.

Promise<string[], (ContrastError|TypeError|Error)>
Parameters: color: string[]

player.setColors(['abc', 'def', '123', '456']).then((color) => {
  // colors were successfully set
  // Array order: [primary, accent, text/icon, background]
}).catch((error) => {
  switch (error.name) {
    case 'TypeError':
      // the string was not a valid hex or rgb color
      break;
    case 'EmbedSettingsError':
      // the owner of the video has chosen to use a specific color
      break;
    default:
      // some other error occurred
      break;
  }
});

addCuePoint()

Add a cue point to the player. Cue points fire a cuepoint event when the currentTime of the video passes the specified time.

Cue points should be accurate to within a tenth of a second, but the precision may vary based on browser or environment.

Promise<string, (UnsupportedError|RangeError|Error)>
Parameters: time: number, data: object

player.addCuePoint(15, {
  customKey: 'customValue'
}).then((id) => {
  // cue point was added successfully
}).catch((error) => {
  switch (error.name) {
    case 'UnsupportedError':
      // cue points are not supported with the current player or browser
      break;
    case 'RangeError':
      // the time was less than 0 or greater than the video’s duration
      break;
    default:
      // some other error occurred
      break;
  }
});

removeCuePoint()

Remove the specified cue point using the id returned from addCuePoint() or from getCuePoints().

Promise<string, (UnsupportedError|InvalidCuePoint|Error)>
Parameters: id: string

player.removeCuePoint('09ecf4e4-b587-42cf-ad9f-e666b679c9ab').then((id) => {
  // cue point was removed successfully
}).catch((error) => {
  switch (error.name) {
    case 'UnsupportedError':
      // cue points are not supported with the current player or browser
      break;
    case 'InvalidCuePoint':
      // a cue point with the id passed wasn’t found
      break;
    default:
      // some other error occurred
      break;
  }
});

getCuePoints()

Get an array of the cue points that have been added to the video.

Promise<array, (UnsupportedError|Error)>

player.getCuePoints().then((cuePoints) => {
  // cuePoints = an array of cue point objects
}).catch((error) => {
  switch (error.name) {
    case 'UnsupportedError':
      // cue points are not supported with the current player or browser
      break;
    default:
      // some other error occurred
      break;
  }
});

Each cue point object looks like this:

{
  "time": 15,
  "data": {
      "customKey": "customValue"
  },
  "id": "09ecf4e4-b587-42cf-ad9f-e666b679c9ab"
}

getCurrentTime()

Get the current playback position in seconds.

Promise<number, Error>

player.getCurrentTime().then((seconds) => {
  // seconds = the current playback position
}).catch((error) => {
  // an error occurred
});

setCurrentTime()

Set the current playback position in seconds. Once playback has started, if the player was paused, it will remain paused. Likewise, if the player was playing, it will resume playing once the video has buffered. Setting the current time before playback has started will cause playback to start.

You can provide an accurate time and the player will attempt to seek to as close to that time as possible. The exact time will be the fulfilled value of the promise.

Promise<number, (RangeError|Error)>
Parameters: seconds: number

player.setCurrentTime(30.456).then((seconds) => {
  // seconds = the actual time that the player seeked to
}).catch((error) => {
  switch (error.name) {
    case 'RangeError':
      // the time was less than 0 or greater than the video’s duration
      break;
    default:
      // some other error occurred
      break;
  }
});

getDuration()

Get the duration of the video in seconds. It will be rounded to the nearest second before playback begins, and to the nearest thousandth of a second after playback begins.

Promise<number, Error>

player.getDuration().then((duration) => {
  // duration = the duration of the video in seconds
}).catch((error) => {
  // an error occurred
});

getEnded()

Get the ended state of the video. The video has ended if currentTime === duration.

Promise<boolean, Error>

player.getEnded().then((ended) => {
  // ended = whether or not the video has ended
}).catch((error) => {
  // an error occurred
});

getLoop()

Get the loop state of the player.

Promise<boolean, Error>

player.getLoop().then((loop) => {
  // loop = whether loop is turned on or not
}).catch((error) => {
  // an error occurred
});

setLoop()

Set the loop state of the player. When set to true, the player will start over immediately once playback ends.

when loop is turned on, the ended event will not fire.

Promise<boolean, Error>
Parameters: loop: boolean

player.setLoop(true).then((loop) => {
  // loop was turned on
}).catch((error) => {
  // an error occurred
});

getMuted()

Get the muted state of the player.

Promise<boolean, Error>

player.getMuted().then((muted) => {
  // muted = whether muted is turned on or not
}).catch((error) => {
  // an error occurred
});

setMuted()

Set the muted state of the player. When set to true, the player volume will be muted.

Promise<boolean, Error>
Parameters: muted: boolean

player.setMuted(true).then((muted) => {
  // muted was turned on
}).catch((error) => {
  // an error occurred
});

getPaused()

Get the paused state of the player.

Promise<boolean, Error>

player.getPaused().then((paused) => {
  // paused = whether or not the player is paused
}).catch((error) => {
  // an error occurred
});

getPlaybackRate()

Get the playback rate of the player on a scale from 0 to 2.

Promise<number, Error>

player.getPlaybackRate().then((playbackRate) => {
  // playbackRate = a numeric value of the current playback rate
}).catch((error) => {
  // an error occurred
});

setPlaybackRate()

Set the playback rate of the player on a scale from 0 to 2 available only to PRO and Business accounts. When set via the API, the playback rate will not be synchronized to other players or stored as the viewer’s preference.

Promise<number, (RangeError|Error)>
Parameters: playbackRate: number

player.setPlaybackRate(0.5).then((playbackRate) => {
  // playback rate was set
}).catch((error) => {
  switch (error.name) {
    case 'RangeError':
      // the playback rate was less than 0 or greater than 2
      break;
    default:
      // some other error occurred
      break;
  }
});

getPlayed()

Get the played time ranges of the video.

Promise<array, Error>

player.getPlayed().then((played) => {
  // played = array values of the played video time ranges.
}).catch((error) => {
  // an error occurred
});

getSeekable()

Get the video time ranges that are seekable.

Promise<array, Error>

player.getSeekable().then((seekable) => {
  // seekable = array values of the seekable video time ranges.
}).catch((error) => {
  // an error occurred
});

getSeeking()

Get if the player is currently seeking.

Promise<boolean, Error>

player.getSeeking().then((seeking) => {
  // seeking = whether the player is seeking or not
}).catch((error) => {
  // an error occurred
});

getTextTracks()

Get an array of the text tracks that exist for the video.

Promise<object[], Error>

player.getTextTracks().then((tracks) => {
  // tracks = an array of track objects
}).catch((error) => {
  // an error occurred
});

Each track object looks like this:

{
    "label":    "English CC",
    "language": "en",
    "kind":     "captions",
    "mode":     "showing"
}

Kind can be either captions or subtitles. The mode can be either showing or disabled. Only one track can be showing at any given time; the rest will be disabled.

getVideoEmbedCode()

Get the <iframe> embed code for the video.

Promise<string, Error>

player.getVideoEmbedCode().then((embedCode) => {
  // embedCode = <iframe> embed code
}).catch((error) => {
  // an error occurred
});

getVideoId()

Get the id of the video.

Promise<number, Error>

player.getVideoId().then((id) => {
  // id = the video id
}).catch((error) => {
  // an error occurred
});

getVideoTitle()

Get the title of the video.

Promise<string, Error>

player.getVideoTitle().then((title) => {
  // title = the title of the video
}).catch((error) => {
  // an error occurred
});

getVideoWidth()

Get the native width of the currently‐playing video. The width of the highest resolution available will be used before playback begins.

Promise<number, Error>

player.getVideoWidth().then((width) => {
  // width = the width of the video that is currently playing
}).catch((error) => {
  // an error occurred
});

getVideoHeight()

Get the native height of the currently‐playing video. The height of the highest resolution available will be used before playback begins.

Promise<number, Error>

player.getVideoHeight().then((height) => {
  // height = the height of the video that is currently playing
}).catch((error) => {
  // an error occurred
});

To get both the width and height, you can do this:

Promise.all([player.getVideoWidth(), player.getVideoHeight()]).then((dimensions) => {
  var width  = dimensions[0];
  var height = dimensions[1];
});

getVideoUrl()

Get the vimeo.com url for the video.

Promise<string, (PrivacyError|Error)>

player.getVideoUrl().then((url) => {
  // url = the vimeo.com url for the video
}).catch((error) => {
  switch (error.name) {
    case 'PrivacyError':
      // the url isn’t available because of the video’s privacy setting
      break;
    default:
      // some other error occurred
      break;
  }
});

getVolume()

Get the current volume level of the player on a scale from 0 to 1. Most mobile devices do not support an independent volume from the system volume. In those cases, this method will always return 1.

Promise<number, Error>

player.getVolume().then((volume) => {
  // volume = the volume level of the player
}).catch((error) => {
  // an error occurred
});

setVolume()

Set the volume of the player on a scale from 0 to 1. When set via the API, the volume level will not be synchronized to other players or stored as the viewer’s preference.

Most mobile devices (including iOS and Android) do not support setting the volume because the volume is controlled at the system level. An error will not be triggered in that situation.

Promise<number, (RangeError|Error)>
Parameters: volume: number

player.setVolume(0.5).then((volume) => {
  // volume was set
}).catch((error) => {
  switch (error.name) {
    case 'RangeError':
      // the volume was less than 0 or greater than 1
      break;
    default:
      // some other error occurred
      break;
  }
});

setTimingSrc()

Syncs a Timing Object to the video player. See timingobject for reference.

Promise<TimingSrcConnector>
Parameters: timingObject: TimingObject, options?: TimingSrcConnectorOptions

npm install @vimeo/player timing-object
<div id="handstick"></div>
import Player from '@vimeo/player';
import {TimingObject} from 'timing-object';
const player = new Player('handstick', {
  id:    19231868,
  width: 640
});
const timingObject = new TimingObject();
player.setTimingSrc(timingObject)
// any update to the timing object will reflect in the player
player.setTimingSrc(timingObject, {role: 'controller'})
// any update to the player will reflect in the timing object

See this demo app which syncs video playback in real-time for all viewers.

getQualities()

Get the available qualities of the current video.

Promise<object[], Error>

player.getQualities().then((qualities) => {
// qualities = an array of quality objects
}).catch((error) => {
// an error occurred
});

Each quality object looks like this:

{
  "label":  "4K",
  "id":     "2160p",
  "active": true
}

getQuality()

Get the current selected quality.

Promise<string, Error>

player.getQuality().then((quality) => {
  // quality = the current selected quality
}).catch((error) => {
  // an error occurred
});

setQuality()

Set the quality of the video. Available to Plus, PRO and Business accounts.

Promise<string, (TypeError|Error)>
Parameters: quality: string

player.setQuality('720p').then((quality) => {
  // quality was successfully set
}).catch((error) => {
  switch (error.name) {
    case 'TypeError':
      // the quality selected is not valid
      break;
    default:
      // some other error occurred
      break;
  }
});

getCameraProps()

Get the current camera properties for a 360° video.

Promise<object, Error>

player.getCameraProps().then((cameraProps) => {
  // cameraProps = the current camera properties
}).catch((error) => {
  // an error occurred
});

Each cameraProps object looks like this:

{
  "yaw":    360,
  "pitch":  90,
  "roll":   180,
  "fov":    45
}

setCameraProps()

Set the camera properties for a 360° video.

Promise<object, (RangeError|Error)>
Parameters: cameraProps: object

player.setCameraProps({
  "yaw":    360, // Number between 0 and 360, left and right.
  "pitch":  90,// Number between -90 and 90, up and down.
  "roll":   180,// Number between -180 and 180.
  "fov":    45   // The field of view in degrees.
}).then((cameraProps) => {
  // cameraProps was successfully set
}).catch((error) => {
  switch (error.name) {
    case 'RangeError':
      // one of the camera properties is out of range
      break;
    default:
      // some other error occurred
      break;
  }
});

Events

You can listen for events in the player by attaching a callback using .on():

player.on('eventName', (data) => {
  // data is an object containing properties specific to that event
});

The events are equivalent to the HTML5 video events (except for cuechange, which is slightly different).

To remove a listener, call .off() with the callback function:

var callback = () => {};
player.off('eventName', callback);

If you pass only an event name, all listeners for that event will be removed.

play

Triggered when video playback is initiated.

{
  duration:   61.857
  percent:    0
  seconds:    0
}

playing

Triggered when the video starts playing.

{
  duration:   61.857
  percent:    0
  seconds:    0
}

pause

Triggered when the video pauses.

{
  duration:   61.857
  percent:    0
  seconds:    0
}

ended

Triggered any time the video playback reaches the end.

when loop is turned on, the ended event will not fire.

{
  duration:   61.857
  percent:    1
  seconds:    61.857
}

timeupdate

Triggered as the currentTime of the video updates. It generally fires every 250ms, but it may vary depending on the browser.

{
  duration:   61.857
  percent:    0.049
  seconds:    3.034
}

progress

Triggered as the video is loaded. Reports back the amount of the video that has been buffered.

{
  duration:   61.857
  percent:    0.502
  seconds:    31.052
}

seeking

Triggered when the player starts seeking to a specific time. A timeupdate event will also be fired at the same time.

{
  duration:   61.857
  percent:    0.485
  seconds:    30
}

seeked

Triggered when the player seeks to a specific time. A timeupdate event will also be fired at the same time.

{
  duration:   61.857
  percent:    0.485
  seconds:    30
}

texttrackchange

Triggered when the active text track (captions/subtitles) changes. The values will be null if text tracks are turned off.

{
  kind:     "captions",
  label:    "English CC",
  language: "en"
}

chapterchange

Triggered when the current chapter changes.

{
  startTime:    15,
  title:        "Chapter 1",
  index:        1
}

The index property of each chapter is the place it holds in the order of all the chapters. It starts at 1.

cuechange

Triggered when the active cue for the current text track changes. It also fires when the active text track changes. There may be multiple cues active.

{
  cues: [
    {
      html: "<i>Here at Vimeo, there's always <br>one thing on our minds:</i>",
      text: "<i>Here at Vimeo, there's always ↵one thing on our minds:</i>"
    }
  ],
  kind:     "captions",
  label:    "English CC",
  language: "en"
}

The text property of each cue is the raw value parsed from the caption or subtitle file. The html property contains the HTML that the Player renders for that cue.

cuepoint

Triggered when the current time hits a registered cue point.

{
  time: 15,
  data: {
    customKey: 'customValue'
  },
  id: "40f5722b-09aa-4060-a887-3c81aaa37cce"
}

The data property will be the custom data provided in the addCuePoint() call, or an empty object if none was provided.

volumechange

Triggered when the volume in the player changes. Some devices do not support setting the volume of the video independently from the system volume, so this event will never fire on those devices.

{
  volume: 0.5
}

playbackratechange

Triggered when the playback rate of the video in the player changes. The ability to change rate can be disabled by the creator and the event will not fire for those videos. The new playback rate is returned with the event.

{
  playbackRate: 1.5
}

bufferstart

Triggered when buffering starts in the player. This is also triggered during preload and while seeking. There is no associated data with this event.

bufferend

Triggered when buffering ends in the player. This is also triggered at the end of preload and seeking. There is no associated data with this event.

error

Triggered when some kind of error is generated in the player. In general if you are using this API library, you should use .catch() on each method call instead of globally listening for error events.

If the error was generated from a method call, the name of that method will be included.

{
  message:  "#984220 does not meet minimum contrast ratio. We recommend using brighter colors. (You could try #d35e30 instead.) See WCAG 2.0 guidelines: https://www.w3.org/TR/WCAG/#visual-audio-contrast"
  method:   "setColor"
  name:     "ContrastError"
}

loaded

Triggered when a new video is loaded in the player.

{
  id: 76979871
}

durationchange

Triggered when the duration attribute has been updated.

{
  duration: 60
}

fullscreenchange

Triggered when the player enters or exits fullscreen.

{
  fullscreen: true
}

qualitychange

Triggered when the set quality changes.

{
  quality: '720p'
}

camerachange

Triggered when any of the camera properties change for 360° videos.

{
  yaw:     270,
  pitch:   90,
  roll:    0,
  fov:     45
}

resize

Triggered when the intrinsic size of the media changes.

{
  videoWidth: 1280,
  videoHeight: 720
}

enterpictureinpicture

Triggered when the player enters picture-in-picture.

leavepictureinpicture

Triggered when the player leaves picture-in-picture.

remoteplaybackavailabilitychange

Triggered when the availability of remote playback changes.

Listening for this event is equivalent to the RemotePlayback.watchAvailability() API, except that there is no cancelWatchAvailability(). You can remove the listener for this event instead.

remoteplaybackconnecting

Triggered when the player is attempting to connect to a remote playback device.

remoteplaybackconnect

Triggered when the player has successfully connected to a remote playback device.

remoteplaybackdisconnect

Triggered when the player has disconnected from a remote playback device.

interactivehotspotclicked

Triggered when a hotspot is clicked.

{
  action: 'seek', // event, none, overlay, seek, url
  actionPreference: {
    pauseOnAction:    false, // on `event`, `overlay`, `seek`, `url` action
    overlayId:        864334, // on `overlay` action
    seekTo:           30, // on `seek` action
    url:              'https://your-url.com', // on `url` action
  },
  currentTime:        15.585,
  customPayloadData:  null,
  hotspotId:          8148223
}

interactiveoverlaypanelclicked

Triggered when the overlay panel (buttons or images) within the interactive overlay is clicked.

{
  action: 'seek', // clickthrough, close, event, none, seek
  actionPreference: {
    pauseOnAction:    true, // on `close`, `seek` action
    seekTo:           30, // on `seek` action
    url:              'https://your-url.com', // on `clickthrough` action
  },
  currentTime:        25.67,
  customPayloadData:  null,
  overlayId:          864334,
  panelId:            'c47193a0-8320-4572-9bcd-8425851b36e9'
}