Player

Getting Started

Our player give you control over your customer's video experience. Using our player API and options you can create a highly customized experience, integrating with your site however you'd like.

Player API Beta

The Vimeo OTT Player API allows programmatic control over playback. This includes common methods like play, pause, and volume. See the full list of available methods below. In addition, you can create custom interactions with your own UI by hooking into player events. See the full list of player events below.

Setup

There are just two things you'll need to include on your page to get started. The Vimeo OTT Player Embed (with the API enabled) and a reference to Vimeo OTT Player API JS in your document.

<!-- Vimeo OTT Player Embed -->
<!-- To enable the API, add api=1 to the URL of the iframe -->
<iframe id="video" src="https://embed.vhx.tv/videos/15?api=1" width="850" height="480" frameborder="0"  allow="autoplay; encrypted-media; fullscreen; picture-in-picture" allowfullscreen></iframe>

<!-- Vimeo OTT Player JS -->
<script src="https://cdn.vhx.tv/assets/player.js"></script>

Next, you simply initiate an instance of the Player API by referencing the iframe element's ID. All events and methods can be called on the returned player object.

var player = new VHX.Player('video');

// methods
player.play();
player.pause();

// events
player.on('play', function(event, data) {
  // the video has started playing
});

player.on('ended', function(event, data) {
  // the video has reached the end of playback
});

And that's it! There is no need to listen to or wait for a player ready event, as this is all handled and queued internally by Vimeo OTT Player JS.

Methods

All methods can be called directly on the player object.

var player = new VHX.Player('video');

// where methodName is any of the methods listed in the table below
player.methodName();
Method Description
bufferedPercent():Number Returns the percentage of the video that's been downloaded (0-1).
currentTime(time:Number):Number Sets or gets the current time of the player. Pass the playback spot in seconds to jump to a specific time. Returns the current time in seconds (up to 3 decimal places).
dispose() Removes the video player and all associated processes.
exitFullscreen() If in fullscreen mode, exits and returns the video to its normal size.
getSubtitles() Returns a stringified array of objects, containing information for all available subtitles.
getVideoDuration():Number Returns to total length of the video in seconds (up to 3 decimal places). Alias: duration()
hasMultipleResolutions():Boolean Returns whether the player has multiple different resolutions for the current video.
isFinished():Boolean Returns whether or not the player is finished playing a video. Alias: ended()
isFullscreen():Boolean Returns whether or not the player is in fullscreen mode.
isPlaying():Boolean Returns whether or not the player is currently playing a video.
isReadyToPlay():Boolean Returns whether or not the player is ready to play a video.
muted(is_muted:Boolean):Boolean A getter/setter for muting and unmuting the player. Passing true will mute the player. Passing false will unmute. Returns the current state.
pause() Pauses playback.
pauseAd() Pauses ad playback.
play() Starts playback.
remainingTime():Number Returns the time remaining in seconds (up to 3 decimals places).
resumeAd() Resumes ad playback.
seekToTime(time:Number) Sets playback to provided time in seconds. See also currentTime()
setSubtitle(language:String) Takes a string of the language you want to set as the current subtitle. Available subtitle languages are based on the object returned from the getSubtitles() function. If an empty string or null is passed, it unsets the current subtitle.
stop() Stops playback.
volume(volume:Number):Number A getter/setter for changing the player's volume. You can pass can decimal number between 0 and 1, where 1 is 100% volume. Returns the current volume (0-1).
currentSrc():String ⚠️ Deprecated. Returns the current url of the media file.
isCasting():Boolean ⚠️ Deprecated. Returns whether or not the player is current casting to a Chromecast enabled device or plugin.
paused():Boolean ⚠️ Deprecated in favor of `isPlaying`. Returns true or false, whether or not the player is currently paused.

Events

You can listen for events by using the on method of the player object.

var player = new VHX.Player('video');

// where event_name is any of the events listed in the table below
player.on('event_name', function(event, data) {
 // do something
});
Event Description
ended
callback(event)
Fired when playback has completed.
fullscreenchange
callback(event)
Fired when the player has switched to fullscreen mode.
loadeddata
callback(event)
Fired when the first frame of the media has finished loading.
loadedmetadata
callback(event)
Fired when the media's metadata has finished loading.
loadstart
callback(event)
Fired when loading of the media begins.
pause
callback(event)
Fired when playback is paused.
play
callback(event)
Fired when playback starts after having been paused.
waiting
callback(event)
Fired when the requested operation (such as playback) is delayed pending the completion of another operation (such as a seek).
durationchange
callback(event, duration)
Fired when the metadata has loaded or changed, indicating a change in duration of the media. This is sent, for example, when the media has loaded enough that the duration is known.
seeked
callback(event, current_time, duration)
Fired when a seek operation has completed.
seeking
callback(event, current_time, duration)
Fired when a seek operation has begun.
timeupdate
callback(event, current_time, duration)
Fired when the current time of the player changes.
volumechange
callback(event, volume, is_muted)
Fired when the volume of the player has been changed (both when the volume is set or muted).
resume
callback(event)
Fired when playback has resumed.
startbuffering
callback(event)
Fired when the player has started buffering the video.
endbuffering
callback(event)
Fired when the player has finished buffering the video.
adstart
callback(event)
Fired when an ad has started.
adfinish
callback(event)
Fired when an ad has finished.
adfail
callback(event)
Fired when an ad has failed for whatever reason.
adskip
callback(event)
Fired when the user skips the ad.
error
callback(event)
Fired when player throws an error for whatever reason.

Player Options

As shown below, you can customize the way your player looks and its enabled features by adding query parameters to the source of the iframe.

Embed

<!-- Vimeo OTT Player Embed -->
<iframe src="https://embed.vhx.tv/videos/15" width="850" height="480" frameborder="0" allow="autoplay; encrypted-media; fullscreen; picture-in-picture" allowfullscreen></iframe>

<!-- customize player features via query params -->
<iframe src="https://embed.vhx.tv/videos/15?color=ffffff&api=1" width="850" height="480" frameborder="0" allow="autoplay; encrypted-media; fullscreen; picture-in-picture" allowfullscreen></iframe>

Query Parameters

Parameter Description
api=1
0 or 1
Enable or disable the player API. If not included, defaults to 0.
auto=1
0 or 1
Enable or disable autoplay on page load. If not included, defaults to 0.
chromeless=1
0 or 1
Enable or disable the player's default controls. Set to 1 to hide the controls. If not included, defaults to 0.
color=ffffff
A valid 3 or 6 digit hexademical
Sets the color of the player. Do not include the # sign. If not included, the color defaults to your site color as set in the Vimeo OTT Dashboard.
muted=1
0 or 1
Whether the video is muted upon loading. The true value is required for the autoplay behavior in some browsers. If not included, defaults to 0.
referrer=url
An encoded and valid URL.
Provide a referral address.
adlink=url
A valid URL.
⚠️ Deprecated. Overrides URL set within player where advertisement data is pulled from. If not included, player will determine the advertising URL from client data provided in the Vimeo OTT Admin.
adparams=string
An encoded string.
⚠️ Deprecated. Overrides params set in the IMA SDK call. If not included, player will determine the params from client data provided in the Vimeo OTT Admin.
back=string
An encoded string.
⚠️ Deprecated. Custom text for the back link if context (see above) is provided. The back link text will be in the format "Back to {custom text}". The back link shows up on the top left of the player (beneath the title if a title is present). The back link shows up when the player is paused or on hover while playing. If not included, defaults to not showing a back link.
context=url
An encoded and valid URL.
⚠️ Deprecated. Enables a back link on the top left of the player that shows when the player is paused or on hover while playing. If not included, defaults to not showing a back link.
disableadcontrols=0
0 or 1
⚠️ Deprecated. Enable or disable controls display on advertisements, if ads are enabled and shown.
hideadcountdown=0
0 or 1
⚠️ Deprecated. Enable or disable countdown display on advertisements, if ads are enabled and shown.
prerolltimeout=string
Integer, representing milliseconds
⚠️ Deprecated. Overrides ad timeout set in the player, which defaults to 100 milliseconds.
sharing=1
0 or 1
⚠️ Deprecated. Enable or disable the sharing overlay. If not included defaults to 0.
title=1
0 or 1
⚠️ Deprecated. Enables a title on the top left of the player that shows when the player is paused or on hover while playing. If not included, defaults to 1 and shows the title of the video.
volume=100
Integer, 0 to 100
⚠️ Deprecated. Sets the initial volume on the player. Integer value must be between 0 and 100. Defaults to 100.

Developer Support

We're always happy to help! Please submit any questions here.