Skip to main content

API Reference

Welcome to the VP Vertical Player API Reference section of this documentation. The VP Vertical 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 vpVerticalPlayer() by passing the ID of the div the player was set up on:

const player = vpVerticalPlayer("vp-vertical-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.
vpVerticalPlayer("vp-vertical-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 vpVerticalPlayer() 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 Vertical Player allows users to use methods for these purposes:

  • Control playback methods
  • Toggle methods
  • State methods
  • Get playback properties methods
  • Set playback properties methods
  • Playlist methods
  • Cue point methods
  • Continue watching methods

Control playback methods​

play()​

Plays the video.

pause()​

Pauses the video.

replay()​

Replays the video from the beginning.

seek(position)​

Jumps to the specified position within the currently playing video.

PARAMETERTYPEMANDATORYDESCRIPTION
positionNumberYesPosition 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.

seekToLive()​

Jumps to the live edge of a livestream. It does nothing on videos that are not live, or when playback is already at the edge.

nextVideo()​

Moves to the next video in the playlist. It does nothing on the last video, unless playlistLoop is enabled.

previousVideo()​

Moves to the previous video in the playlist. It does nothing on the first video, unless playlistLoop is enabled.

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.

toggleSubtitles()​

Turns subtitles on or off. Turning them on selects the track the player would pick by default, or the one the viewer last chose. It does nothing when the video has no subtitle tracks.

State methods​

isMuted()​

Returns a boolean indicating whether the audio on the video is currently muted.

isPlaying()​

Returns a boolean indicating whether the video is currently playing.

isFullscreen()​

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

isEnded()​

Returns a boolean indicating whether the current video has ended.

isFocused()​

Returns a boolean indicating whether the player is in a focused state caused by a user interaction.

isPaused()​

Returns a boolean indicating whether the video is currently paused.

getPlaybackState()​

Returns the current playback state as a string: playing, paused, buffering, or unknown if the player has no video yet.

Get playback properties methods​

getPosition()​

Returns the current playback position in seconds.

getDuration()​

Returns the duration of the current video in seconds.

getVolume()​

Returns the current volume as a number between 0 and 1.

getPlaybackRate()​

Returns the current playback speed, where 1 is normal speed.

Set playback properties methods​

setVideo(video)​

Sets the video for the video player.

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

setVolume(volume)​

Sets the volume of the player. Values outside the accepted range are clamped, and setting the volume to 0 also mutes the player. While an ad is playing, the volume is applied to the ad instead.

PARAMETERTYPEMANDATORYDESCRIPTION
volumeNumberYesThe volume to set, between 0 and 1.

setPlaybackRate(rate)​

Sets the playback speed of the current video.

PARAMETERTYPEMANDATORYDESCRIPTION
rateNumberYesThe speed to play at, where 1 is normal speed. Use one of the values from the playbackRates configuration so the settings menu stays in sync.

Playlist methods​

addVideos(videos)​

Appends videos to the end of the current playlist, which is how you build an endless feed. Listen for vp-playlist-near-end to know when to append more, and vp-playlist-appended to confirm they were added. If the viewer is mid-scroll, the videos are queued and added as soon as scrolling settles.

PARAMETERTYPEMANDATORYDESCRIPTION
videosArrayYesVideo objects to append, each shaped like config.video.
vpVerticalPlayer("divId").on("vp-playlist-near-end", () => {
    vpVerticalPlayer("divId").addVideos([{ videoId: "", file: "" }]);
});

Cue point methods​

setCuePoint(time, callback)​

Registers a callback to run once when playback reaches a given position.

PARAMETERTYPEMANDATORYDESCRIPTION
timeNumberYesPosition in seconds at which to run the callback.
callbackFunctionYesThe function to run when that position is reached.

Continue watching methods​

These two methods only return real data when continue watching is enabled for the player. Without it, they are inert.

getWatchTimes()​

Returns a promise resolving to the stored watch position for the current video, so you can restore where the viewer left off.

hasBeenWatched(assetDuration)​

Returns a boolean indicating whether the viewer has already watched enough of the video to count as watched.

PARAMETERTYPEMANDATORYDESCRIPTION
assetDurationNumberNoDuration of the video to compare the stored position against.