API Reference

Welcome to the VP Player API Reference section of this documentation. The VP Player API allows you to enhance the functionality of your video player and create interactive experiences for users. By using the API, you can customize the behavior of your videos and create unique user experiences using the available methods and properties.

Calling methods

Every method on this page is called on a player instance, which you get from vpPlayer() by passing the ID of the div the player was set up on:

const player = vpPlayer("vp-player");

player.setup(configuration).then(() => {
    player.play();
    player.setVolume(0.5);
});

// Passing the same ID anywhere else returns that same instance,
// so you can reach the player without keeping the variable around.
vpPlayer("vp-player").pause();

Because setup() is asynchronous, wait for it to resolve before calling other methods.

If there is only one player on the page, you can call vpPlayer() with no arguments and it returns that player. Both forms appear in the examples below and are interchangeable when the page has a single player.

Methods

VP Player allows users to use methods for these purposes:

• Control playback methods
• Toggle methods
• State methods
• Get playback properties methods
• Set playback properties methods

Control playback methods

play()

Plays the video.

pause()

Pauses the video.

forward()

Seeks forward within the current video by the skipAmount configuration value, which is 10 seconds by default and accepts values between 5 and 30. Videos of 60 seconds or shorter always step by 5 seconds.

rewind()

Seeks backward within the current video, using the same interval as forward().

replay()

Replays the video from the beginning.

seek(position)

Jumps to the specified position within the currently playing video.

PARAMETER	TYPE	MANDATORY	DESCRIPTION
position	Number	Yes	The position to seek to, in seconds.

mute()

Mutes the audio on the video.

unmute()

Unmutes the audio on the video.

enterFullScreen()

Enters full screen mode for the video.

exitFullScreen()

Exits full screen mode for the video.

destroy()

Destroys the video player instance, removing it from the DOM.

Toggle methods

togglePlay()

Toggles the play/pause state of the video based on the current state.

toggleMute()

Toggles the mute/unmute state of the audio on the video.

State methods

isMuted()

Returns a boolean indicating whether the audio on the video is currently muted. While an ad is playing, this reports the ad's muted state instead of the video's.

Returns: Boolean

isPlaying()

Returns a boolean indicating whether the video is currently playing. While an ad is playing, this reports whether the ad is playing.

Returns: Boolean — or null if the player has no video loaded yet.

isPaused()

Returns a boolean indicating whether the video is currently paused.

Returns: Boolean — or null if the player has no video loaded yet.

isFullScreen()

Returns a boolean indicating whether the video is currently in full screen mode.

Returns: Boolean

isFloating()

Returns a boolean indicating whether the player is currently floating.

Returns: Boolean

isPictureInPictureActive()

Returns a boolean indicating whether picture-in-picture mode is active.

Returns: Boolean

isAutoQuality()

Returns a boolean indicating whether the player is selecting the quality level automatically.

Returns: Boolean

isHLSSupported()

Returns a boolean indicating whether the current browser supports HLS playback.

Returns: Boolean

hasBeenWatched(assetDuration)

Checks whether the current video has been watched beyond the threshold, which is 90% of its duration. Requires continue watching to be enabled and a valid userId set on the player.

PARAMETER	TYPE	MANDATORY	DESCRIPTION
assetDuration	Number	No	The total duration of the video in seconds. If not provided, uses the current video's duration.

Returns: Boolean — true if the user has watched more than 90% of the video, false otherwise.

tip

For a complete guide on setting up continue watching, see Continue Watching.

Get playback properties methods

getPosition()

Returns the viewer's current position in the media file, in seconds. What the value represents depends on the type of media, as described below.

MEDIA TYPE	RETURNED VALUE
VOD	The current playback position in the file, in seconds.
Live	How long the current stream has been playing, in seconds.

Returns: Number — or null if the player has no video loaded yet.

getWatchTimes(userId, assetId)

Retrieves watch time information for a user and optionally a specific video. Requires continue watching to be enabled and a valid userId set on the player.

PARAMETER	TYPE	MANDATORY	DESCRIPTION
userId	String	No	User ID to query. Defaults to the current player's userId.
assetId	String	No	Specific video/asset ID to query. If omitted, returns all watch times for the user.

Returns:

• If assetId is provided: Promise<Number> — the watch time position in seconds, or 0 if it could not be retrieved.
• If assetId is omitted: Promise<Asset[]> — an array of all watched assets with their positions, or an empty array if it could not be retrieved.

// Get all watched videos for the current user
const allWatchedVideos = await player.getWatchTimes();

// Get watch time for a specific user and video
const watchTime = await player.getWatchTimes("user-123", "video-456");

tip

For a complete guide on setting up continue watching, see Continue Watching.

getBuffered()

Returns how much of the video has been buffered, as a percentage from 0 to 100.

Returns: Number

getVolume()

Returns the current volume of the audio on the video, as a number between 0 and 1. While an ad is playing, this reports the ad's volume instead of the video's.

Returns: Number

getContainer()

Returns the container element for the video player.

Returns: Element — or null if the player has not been set up yet.

getDuration()

Returns the total length of the media file, in seconds. What the value represents depends on the type of media, as described below.

MEDIA TYPE	RETURNED VALUE
VOD	The length of the file, in seconds.
Live	The maximum number of seconds the player can seek, or Infinity.

Returns: Number — or null if the player has no video loaded yet.

getQualityLevels()

Returns the quality levels available for the video. Each level includes its width, height, and bitrate.

Returns: Array — empty for videos that are not using adaptive streaming.

getCurrentQuality()

Returns the index of the current quality level of the video.

Returns: Number — or null if the video is not using adaptive streaming.

getVideoInfo()

Returns metadata about the current video.

FIELD	TYPE	DESCRIPTION
title	String	Title of the video.
description	String	Description of the video.
author	String	Author of the video.
duration	Number	Duration of the video, in seconds.
tags	Array	Tags assigned to the video.
publishDate	String	Date the video was published.
customParameters	Object	Custom parameters set on the video.

Returns: Object — or null if the player has no video loaded yet.

getLiveEdge()

Returns the position of the live edge of a livestream, in seconds.

Returns: Number

getTotalWatchSeconds()

Returns how many seconds the viewer has watched of the current video. Only actual playback counts, so time spent paused, buffering, on a custom screen, or watching an ad is excluded. The count restarts when the video changes.

Returns: Number

getSegmentWatchSeconds()

Returns how many seconds the viewer has watched since the last watch state event, which the player sends every 10 seconds. It counts playback the same way getTotalWatchSeconds() does.

Returns: Number

isViewable()

Returns a boolean indicating whether the player is viewable within the current viewport. A player that is in full screen or embedded is always considered viewable.

Returns: Boolean

Set playback properties methods

setVideo(video)

Sets the video object of the player, which immediately starts playback. The video you pass is merged into a clean default configuration, so any options you set previously through setConfig() are not carried over.

const video = {
    // configuration of video object from config.video
};
vpPlayer().setVideo(video);

PARAMETER	TYPE	MANDATORY	DESCRIPTION
video	JSON	Yes	Video object with data about the video as specified on the full configuration.

tip

A playlist is set through this method as well, by including a playlist object in the video object you pass. It follows the same format as the playlist in the setup() method, so it can be given as a playlist ID, a videos array, or a related link.

setConfig(config)

Sets one or more player configuration properties after the player has already been set up. The object you pass is merged into the player's current configuration, and the player is then set up again with the result.

const config = {
    // configuration object from config
};
vpPlayer().setConfig(config);

PARAMETER	TYPE	MANDATORY	DESCRIPTION
config	JSON	Yes	Config object with player properties as specified in the full configuration.

setVolume(volume)

Sets the volume for the audio on the video, from 0 to 1.

const volume = 0.5;
vpPlayer().setVolume(volume);

PARAMETER	TYPE	MANDATORY	DESCRIPTION
volume	Number	Yes	The volume of the video, as a double number from 0 to 1.

setPlaybackRate(rate)

Sets the playback speed of the current video, accepting values from 0.1 to 10. Use one of the values from the playbackRates configuration so that the settings menu stays in sync.

vpPlayer().setPlaybackRate(1.5);

PARAMETER	TYPE	MANDATORY	DESCRIPTION
rate	Number	Yes	The speed to play at, where 1 is normal speed.

setUserId(userId, save)

Sets a unique user ID that is used for analytics tracking and continue watching functionality. Must be called after player setup.

const player = vpPlayer("vp-player");
player.setup(config).then(() => {
    player.setUserId("user-123", true);
});

PARAMETER	TYPE	MANDATORY	DESCRIPTION
userId	String	Yes	The unique identifier for the user. Must be a non-empty string.
save	Boolean	No	If true, saves the user ID to localStorage (under the key vpUserId) for persistent use across sessions. Defaults to false.

Returns: Boolean — true if successful, false if the userId is invalid or localStorage is not accessible.

tip

For a complete guide on setting up user ID and continue watching, see Continue Watching.

setCurrentQuality(index)

Sets the current quality level for the video. Index 0 is the lowest quality, and the highest index depends on the number of video qualities available.

const index = 2;
vpPlayer().setCurrentQuality(index);

PARAMETER	TYPE	MANDATORY	DESCRIPTION
index	Number	Yes	The index of the quality level to switch to.

setLevelToAuto()

Sets the quality level for the video to auto, which automatically adjusts based on the user's device and connection.

setCuePoint(cue, callback)

Sets a custom function to be called at the specified time during video playback. If you register more than one callback at the same position, all of them run.

const cue = 10;
const callback = () => {
    console.log("Reached 10 seconds");
};

vpPlayer().setCuePoint(cue, callback);

PARAMETER	TYPE	MANDATORY	DESCRIPTION
cue	Number	Yes	The position of the video in seconds which will trigger the function.
callback	Function	Yes	The callback that will be called on the set cue.