Player API actions

Player API actions

On the get started page you should have seen how to initialise the player API.

We briefly mentioned the second options parameter as part of getting started. That is applicable when you don't have an iframe already on your page and want the player API to dynamically add one. We provide a range of options to let you customise that behaviour. For example assuming we have a <div id="embed"></div> in our HTML already, as a minimum (as you must provide an id) we can call it like this:

<script>
var player = new Vidbeo.Player('embed', {
id: "examplevideoid"
});
</script>

Since that does not specify a width and height, the iframe it adds should fill the available width. That's because we default to a responsive embed, adding extra CSS rules to your provided element to make it fill the available space. You can customise that as you will see below.

The full list of options:

OptionTypeDefaultDescription
aspectratioString"16:9"The aspect ratio the player should show the content at: "16:9", "21:9", "4:3". This applies only if you also set responsive as true.
autoplayBooleanfalseShould the video start playing on-load?
colourString''A custom colour as a six-character hex such as "00b894"
controlsBooleantrueShould controls be shown?
buttonsString''If empty, the default buttons will be shown. That's what we recommend. You can override that by specifying a comma-separated string of button names. For example "main_play,play,progress,fullscreen"
dntBooleanfalseA 'Do Not Track' option. If set as true, analytics events normally sent by the player will not be sent
heightNumberN/AIf you would like to embed a video at a fixed size, provide its height, such as 360
idString''You must provide the unique ID of a video to embed: it will look something like uk1vabcde23445abcde
jwtString''A video can be set to require authentication, and you can provide that using a JSON Web Token (JWT). If used, you can provide that token in this field
keyboardBooleantrueEnable keyboard controls?
loopBooleanfalseShould the video restart when it ends?
mutedBooleanfalseShould the video be muted when it loads? You will likely need to set this as true if you set autoplay as true, as browsers usually block videos from auto-playing that are not muted
playsinlineBooleantrueOn mobile device, should the video play within the page (rather than automatically move into fullscreen mode)
preloadBooleantrueOn desktop (where this can be controlled) should the player buffer a short amount of the video on-load? This improves performance as the video can then start playing immediately but if the viewer does not play the video, it may waste a little data
qualityString'auto'We use a technique called ABR so that our player will automatically try to play the best quality based on the available connection speed. Which can vary. However on desktop (where this can be controlled) you may want to override that and force it to pick the highest available quality on-load. If so, set this as "highest"
responsiveBooleantrueMost modern sites adapt to the width of the screen to look great on both desktop and mobile. You therefore don't need to set a width or height value. If you would like to control the responsive behaviour yourself in your own CSS you must set this as false. That tells our player you will be handling its size and so it should not add its own CSS
tNumber0A time in seconds to skip forward to on-load
titleBooleanfalseShould the video's title be shown within the player?
trackString''If your video has subtitles or closed-captions, you may want them turned on immediately on-load. If so, set the language code of the one to use (as you may have multiple ones). For example to enable English captions on-load, set this as "en"
widthNumberN/AIf you would like to embed a video at a fixed size, provide its width, such as 640

Methods

Note: Since methods return a Promise you can handle/catch the response to see if the request succeeded. Our examples below demonstrate that. But you can simply call the method like player.play() without using a then or catch handler.

Actions

Play
play()

Play the video.

player.play().then(function() {
console.log('Success');
}).catch(function(error) {
console.error('Error', error);
});
Pause
pause()

Pause the video.

player.pause().then(function() {
console.log('Success');
}).catch(function(error) {
console.error('Error', error);
});
Ready
ready()

Check if the player is ready.

Note: You don't need to chain this yourself when calling other methods as we check the player is ready internally.

player.ready().then(function() {
console.log('Success');
}).catch(function(error) {
console.error('Error', error);
});
requestFullscreen
requestFullscreen()

Enter fullscreen mode.

Be aware that if you toggle fullscreen mode using an external button, that button will of course be covered up by the player once it goes fullscreen.

player.requestFullscreen().then(function() {
console.log('Success');
}).catch(function(error) {
console.error('Error', error);
});
exitFullscreen
exitFullscreen()

Exit fullscreen mode.

player.exitFullscreen().then(function() {
console.log('Success');
}).catch(function(error) {
console.error('Error', error);
});

Getters

These are the methods that return a value. Its type naturally depends on the method.

getColour
getColour()

Get the colour of the player, as a six-character hex. A blank value means the default colour is used. The value is a string.

For example: 74b9ff

player.getColour().then(function(data) {
console.log('Success', data);
}).catch(function(error) {
console.error('Error', error);
});
getCurrentTime
getCurrentTime()

Get the current time. The value is a number in seconds.

For example: 11.4

player.getCurrentTime().then(function(data) {
console.log('Success', data);
}).catch(function(error) {
console.error('Error', error);
});
getDuration
getDuration()

Get the duration of the video, once it's known. It will only be known once the video's metadata is loaded. The value is a number in seconds.

For example: 12

player.getDuration().then(function(data) {
console.log('Success', data);
}).catch(function(error) {
console.error('Error', error);
});
getEmbed
getEmbed()

Get an embed code for the video. It is a string which is a snippet of HTML.

player.getEmbed().then(function(data) {
console.log('Success', data);
}).catch(function(error) {
console.error('Error', error);
});
getEnded
getEnded()

Check if the video has ended. This is a boolean.

For example: false

player.getEnded().then(function(data) {
console.log('Success', data);
}).catch(function(error) {
console.error('Error', error);
});
getFullscreen
getFullscreen()

Check if the video is fullscreen. This is a boolean.

For example: false

player.getFullscreen().then(function(data) {
console.log('Success', data);
}).catch(function(error) {
console.error('Error', error);
});
getHeight
getHeight()

Get the height of the video (not the height it is embeddeed at). This is a number.

It is only known once the video's metadata has downloaded.

For example: 720

player.getHeight().then(function(data) {
console.log('Success', data);
}).catch(function(error) {
console.error('Error', error);
});
getId
getId()

Get the ID of the embedded video. This is a string.

For example: abcdefgh1234567

player.getId().then(function(data) {
console.log('Success', data);
}).catch(function(error) {
console.error('Error', error);
});
getLoop
getLoop()

Check if the video is set to loop (restart when it ends). This is a boolean.

For example: false

player.getLoop().then(function(data) {
console.log('Success', data);
}).catch(function(error) {
console.error('Error', error);
});
getMuted
getMuted()

Check if the video is muted. This is a boolean.

For example: false

player.getMuted().then(function(data) {
console.log('Success', data);
}).catch(function(error) {
console.error('Error', error);
});
getPaused
getPaused()

Check if the video is paused. This is a boolean.

For example: false

player.getPaused().then(function(data) {
console.log('Success', data);
}).catch(function(error) {
console.error('Error', error);
});
getPlaybackRate
getPlaybackRate()

Get the playback rate. It's returned as a number. The default is 1 (meaning 1x). The range is 0.5 to 2.

For example: 0.5

player.getPlaybackRate().then(function(data) {
console.log('Success', data);
}).catch(function(error) {
console.error('Error', error);
});
getPlayed
getPlayed()

Get the time period(s) during which the video has been played. This is a 2D array. All values are in seconds.

For example: [[0,4.367],[6,8.738]]

player.getPlayed().then(function(data) {
console.log('Success', data);
}).catch(function(error) {
console.error('Error', error);
});
getProgress
getProgress()

Get the part(s) of the video that have been buffered. The data is returned as a 2D array with the values in seconds.

For example: [[0,8]]

player.getBuffered().then(function(data) {
console.log('Success', data);
}).catch(function(error) {
console.error('Error', error);
});
getQualities
getQualities()

Get the available qualities/renditions. At a minimum there is an "auto" quality however once the video's metadata is loaded and so the qualities are known, you may want to manually set a particular quality to be used. You would send one of these values. Each value is a string.

For example: ["360p","720p","1080p","auto"]

player.getQualities().then(function(data) {
console.log('Success', data);
}).catch(function(error) {
console.error('Error', error);
});
getQuality
getQuality()

Get the currently selected quality/rendition. The default value is "auto" which means it is left up to the player to decide the quality (depending on the connection speed). However you may have manually selected a particular quality. The value is returned as a string.

For example: "720p"

player.getQuality().then(function(data) {
console.log('Success', data);
}).catch(function(error) {
console.error('Error', error);
});
getSeekable
getSeekable()

Get the time period(s) that are seekable within. This is a 2D array with each element being an array of [start,end]. All values are in seconds.

For example: [[0,11.4]]

player.getSeekable().then(function(data) {
console.log('Success', data);
}).catch(function(error) {
console.error('Error', error);
});
getSeeking
getSeeking()

Is the video currently seeking? The value is a boolean.

For example: false

player.getSeeking().then(function(data) {
console.log('Success', data);
}).catch(function(error) {
console.error('Error', error);
});
getTracks
getTracks()

Get the available subtitle/closed caption tracks. This is an array of objects. If the video does not have any tracks, it will be empty.

For example: [{"id":"abcdefgh1234567","kind":"captions","language":"en","label":"English","mode":"disabled"}]

player.getTracks().then(function(data) {
console.log('Success', data);
}).catch(function(error) {
console.error('Error', error);
});
getTitle
getTitle()

Get the title of the embedded video. It is a string.

For example: "Example video"

player.getTitle().then(function(data) {
console.log('Success', data);
}).catch(function(error) {
console.error('Error', error);
});
getUrl
getUrl()

Get a URL to the video that can be shared or emailed. It is a string.

For example: "https://watch.vidbeo.com/abcdefghiklmnop"

player.getUrl().then(function(data) {
console.log('Success', data);
}).catch(function(error) {
console.error('Error', error);
});
getVolume
getVolume()

Get the current volume. It is returned as a number between 0 and 1.

For example: 0.3

player.getVolume().then(function(data) {
console.log('Success', data);
}).catch(function(error) {
console.error('Error', error);
});
getWidth
getWidth()

Get the width of the video. This is only known once the video's metadata has been downloaded. It is returned as a number.

For example: 1920

player.getWidth().then(function(data) {
console.log('Success', data);
}).catch(function(error) {
console.error('Error', error);
});

Setters

For these methods you need to pass a value as its parameter.

setColour
setColour(colour: String)

Set the colour of the player. We generally use a neutral look which works well on most sites but you can apply an accent colour. It should be a six-character string using the hex format.

For example: 00ffff

Any returned data parameter will simply echo back the same colour.

player.setColour("00ffff").then(function(data) {
console.log('Success', data);
}).catch(function(error) {
console.error('Error', error);
});
setCurrentTime
setCurrentTime(time: Float)

Seek to a particular time. The value should be a time in seconds. It must be greater than 0, and less than the duration of the video

For example: 7

Any returned data parameter will simply echo back the same time.

player.setCurrentTime(7).then(function(data) {
console.log('Success', data);
}).catch(function(error) {
console.error('Error', error);
});
setLoop
setLoop(loop: Boolean)

Set whether the video should loop when it ends. The value should be a boolean.

For example: true

Any returned data parameter will simply echo back the same value.

player.setLoop(true).then(function(data) {
console.log('Success', data);
}).catch(function(error) {
console.error('Error', error);
});
setMuted
setMuted(muted: Boolean)

Set whether the video should be muted. The value should be a boolean.

For example: true

Any returned data parameter will simply echo back the same value.

player.setMuted(true).then(function(data) {
console.log('Success', data);
}).catch(function(error) {
console.error('Error', error);
});
setPlaybackRate
setPlaybackRate(rate: Float)

Set the playback speed. Since browsers do not reliably support some speeds, currently the value should be one of these numbers: 0.5, 1, 1.5, 2.

For example: 1.5

Any returned data parameter will simply echo back the same value.

player.setPlaybackRate(1.5).then(function(data) {
console.log('Success', data);
}).catch(function(error) {
console.error('Error', error);
});
setQuality
setQuality(quality: String)

Set the quality. The default is "auto" which leaves the player to optimise the quality based on the available connection speed. However you can manually set a quality (from those available, as reported by getQualities()) such as "1080p" to override that.

For example: 1080p

Any returned data parameter will simply echo back the same value.

player.setQuality("1080p").then(function(data) {
console.log('Success', data);
}).catch(function(error) {
console.error('Error', error);
});
setVolume
setVolume(volume: Float)

Set the volume. It should be a number between 0 and 1.

For example: 0.5

Any returned data parameter will simply echo back the same value.

player.setVolume(0.5).then(function(data) {
console.log('Success', data);
}).catch(function(error) {
console.error('Error', error);
});

Event listener

Use the on method to register a callback function and the off method to remove it. Unlike the methods above, these do not return a Promise.

on
on(event: String, callback: Function)

Here we are listening for the playing event. The second parameter needs to be a function. That is the callback which is run when that event is fired:

player.on('playing', function(data) {
console.log('playing', data);
});
off
off(event: String, callback: Function)

Here we are no longer listening for the playing event and want to remove all callbacks:

player.off('playing');

If you want to remove a specific callback function, pass that function as the optional second parameter:

const onPlaying = function(data) {
console.log('playing', data);
};
player.off('playing', onPlaying);

Available events

These are the events you can listen for along with an example of data passed to the callback you register using on().

Events return relevant data to give more detail about the state. You can of course subsequently use the get methods to return any additional data you need.

EventData typeExample data passed to callback
durationchangeObject{"duration":11.4}
endedObject{"seconds":11.4,"percentage":100}
fullscreenchangeObject{"fullscreen":true}
hotspotclickedObject{"id":"abcdefgh12345678","seconds":5}
loadedmetadataObject{"videoWidth":1920,"videoHeight":1080}
pauseObject{"seconds":7.235,"percentage":63.461}
playObject{"seconds":1.341,"percentage":11.761}
playingObject{"seconds":1.341,"percentage":11.767}
progressObject{"percentage":100}
qualitychangeObject{"quality":"720p"}
playbackratechangeObject{"playbackRate":1.5}
seekedObject{"seconds":5,"percentage":43.86}
seekingObject{"seconds":5,"percentage":43.86}
trackchangeObject{"language":"en"}
timeupdateObject{"seconds":7.648,"percentage":67.089}
volumechangeObject{"volume":0.82}