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 VHX 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 VHX Player Embed (with the API enabled) and a reference to VHX Player API JS in your document.

<!-- VHX 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?autoplay=1&api=1" width="850" height="480" frameborder="0" webkitAllowFullScreen mozallowfullscreen allowFullScreen></iframe>

<!-- VHX 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 VHX 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
isReadyToPlay():Boolean Returns whether or not the player is ready to play a video.
isCasting():Boolean Returns whether or not the player is current casting to a Chromecast enabled device or plugin.
isPlaying():Boolean Returns whether or not the player is currently playing a video.
isFinished():Boolean Returns whether or not the player is finished playing a video. Alias: ended()
hasMultipleResolutions():Boolean Returns whether the player has multiple different resolutions for the current video.
bufferedPercent():Number Returns the percentage of the video that's been downloaded (0-1).
currentSrc():String Returns the current url of the media file.
seekToTime(time:Number) Sets playback to provided time in seconds. See also currentTime()
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).
getVideoDuration():Number Returns to total length of the video in seconds (up to 3 decimal places). Alias: duration()
isFullscreen():Boolean Returns whether or not the player is in fullscreen mode.
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.
paused():Boolean Returns true or false, whether or not the player is currently paused.
remainingTime():Number Returns the time remaining in seconds (up to 3 decimals places).
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).
exitFullscreen() If in fullscreen mode, exits and returns the video to its normal size.
play() Starts playback.
stop() Stops playback.
pause() Pauses playback.
pauseAd() Pauses ad playback.
resumeAd() Resumes ad playback.
getSubtitles() Returns a stringified array of objects, containing information for all available subtitles.
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 no string or null is passed, it unsets the current subtitle.

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

<!-- VHX Player Embed -->
<iframe src="https://embed.vhx.tv/videos/15" width="850" height="480" frameborder="0" webkitAllowFullScreen mozallowfullscreen allowFullScreen></iframe>

<!-- customize player features via query params -->
<iframe src="https://embed.vhx.tv/videos/15?color=ffffff&api=1&sharing=1" width="850" height="480" frameborder="0" webkitAllowFullScreen mozallowfullscreen allowFullScreen></iframe>

Query Parameters

Parameter Description
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 VHX Dashboard.
api=1
0 or 1
Enable or disable the player API. If not included, defaults to 0.
sharing=1
0 or 1
Enable or disable the sharing overlay. If not included defaults to 0.
auto=1
0 or 1
Enable or disable autoplay on page load. If not included, defaults to 0.
referrer=url
An encoded and valid URL.
Provide a referral address.
title=1
0 or 1
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.
context=url
An encoded and valid URL.
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.
back=string
An encoded string.
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.
adlink=url
A valid URL.
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 VHX Admin.
adparams=string
An encoded string.
Overrides params set in the IMA SDK call. If not included, player will determine the params from client data provided in the VHX Admin.

Developer Support

We're always happy to help out with code or answer any questions you might have. Get in touch on our Slack Channel or email us at api@vhx.tv.

VHX Support on Slack