Skip to content
On this page

Actions

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

On that page we briefly mentioned the options parameter. That is applicable when you don't have an iframe already on your page and want our 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 could call it like this:

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

These are the available 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

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.

Methods

play()

Play the video.

javascript
player
  .play()
  .then(function () {
    console.log("Success");
  })
  .catch(function (error) {
    console.error("Error", error);
  });

pause()

Pause the video.

javascript
player
  .pause()
  .then(function () {
    console.log("Success");
  })
  .catch(function (error) {
    console.error("Error", error);
  });

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.

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

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.

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

exitFullscreen()

Exit fullscreen mode.

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

Getters

These are the methods that return a value.

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

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

getCurrentTime()

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

For example: 11.4

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

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

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

getEmbed()

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

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

getEnded()

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

For example: false

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

getFullscreen()

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

For example: false

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

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

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

getId()

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

For example: abcdefgh1234567

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

getLoop()

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

For example: false

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

getMuted()

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

For example: false

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

getPaused()

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

For example: false

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

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

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

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

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

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

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

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

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

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"

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

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

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

getSeeking()

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

For example: false

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

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"}]

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

getTitle()

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

For example: "Example video"

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

getUrl()

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

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

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

getVolume()

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

For example: 0.3

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

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

javascript
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(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.

javascript
player
  .setColour("00ffff")
  .then(function (data) {
    console.log("Success", data);
  })
  .catch(function (error) {
    console.error("Error", error);
  });

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.

javascript
player
  .setCurrentTime(7)
  .then(function (data) {
    console.log("Success", data);
  })
  .catch(function (error) {
    console.error("Error", error);
  });

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.

javascript
player
  .setLoop(true)
  .then(function (data) {
    console.log("Success", data);
  })
  .catch(function (error) {
    console.error("Error", error);
  });

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.

javascript
player
  .setMuted(true)
  .then(function (data) {
    console.log("Success", data);
  })
  .catch(function (error) {
    console.error("Error", error);
  });

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.

javascript
player
  .setPlaybackRate(1.5)
  .then(function (data) {
    console.log("Success", data);
  })
  .catch(function (error) {
    console.error("Error", error);
  });

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.

javascript
player
  .setQuality("1080p")
  .then(function (data) {
    console.log("Success", data);
  })
  .catch(function (error) {
    console.error("Error", error);
  });

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.

javascript
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(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:

javascript
player.on("playing", function (data) {
  console.log("playing", data);
});

off(event: String, callback: Function)

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

javascript
player.off("playing");

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

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

Available events

These are all 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}