Configuration

This section outlines the available configuration options for VP Vertical Player. The player is highly customizable, offering a variety of settings to tailor the playback experience.

Configuration Overview

To configure the player, you need to provide a configuration object with the desired settings.

const configuration = {
    video:{
        ...
    },
    config:{
        ...
    }
}
vpVerticalPlayer("div").setup(configuration);

Below is a breakdown of the available configuration options.

Player video Configurations

Basic Video Options

PROPERTY	DESCRIPTION
video Object	This object contains in itself all of the properties shown below.
videoId string	Unique ID of the video.
file string	Video source URL. Supports HLS (.m3u8) streams and standalone .mp4, .m4v, and .webm files.
mp4QualitiesUrl string	URL to a .gjp4 metadata document describing the MP4 renditions. When mp4QualityMode is on and this is set, the player fetches the qualities from it and ignores mp4Qualities and mp4DeriveQualities.
mp4Qualities array	MP4 quality renditions that you provide. When mp4QualityMode is on and mp4QualitiesUrl is empty, the player switches quality using this list; the player does not generate it. See the element properties below.
title string	Video title.
description string	Video description.
author string	Video author. Displayed when showAuthor is enabled.
publishDate string	Publish date. Displayed when showPublishDate is enabled.
thumbnail string	Thumbnail image URL.
shareUrl string	URL for sharing.
live boolean	Indicates if the video is a live stream.
duration int	Video duration in seconds. Populated automatically by the player.

mp4Qualities element

Provide mp4Qualities when your source is standalone MP4 files (not HLS) but you still want viewers to choose between multiple quality levels. The player treats the list like a simplified HLS playlist: it picks a starting quality from the viewer's estimated bandwidth and lets them switch quality from the settings menu. Each entry describes one rendition.

Each element in the mp4Qualities array has these properties:

PROPERTY	DESCRIPTION
url string	MP4 file URL for this quality rendition.
height int	Rendition height in pixels. Used as the quality label (for example 720 shows as "720p").
bitrate int	Average bitrate in bits per second. Used to pick the starting quality from the estimated bandwidth.

Example:

"mp4Qualities": [{ "url": "https://cdn.vpplayer.tech/.../720p.mp4", "height": 720, "bitrate": 2500000 }]

Tracks (Subtitles)

PROPERTY	DESCRIPTION
tracks array	List of subtitle tracks.

Each element in the tracks array has these properties:

PROPERTY	DESCRIPTION
file string	Subtitle file URL. Supports .vtt and .srt (SRT is converted automatically).
lang string	Language code, for example en.
label string	Display name shown in the subtitles menu, for example "English".

Example:

"tracks": [{"file": "https://cdn.vpplayer.tech/subtitles/en.srt", "lang": "en", "label": "English"}]

Playlist

Playlist mode turns the player into a sequence of videos the viewer moves through with the next and previous controls.

There are two ways to populate the playlist:

• Hosted playlist - set playlistId to a playlist ID provided by VP, and the player fetches that playlist from our backend.
• Manual list - provide your own videos array.

If both are set, the hosted playlistId takes precedence.

PROPERTY	DESCRIPTION
state boolean	Turns on playlist mode. The other playlist fields apply only when this is true.
playlistId string	Playlist identifier. If it is an ID provided by VP, the player fetches that hosted playlist from our backend; otherwise it is treated as a unique ID for your playlist.
videos array	A list of videos you supply, used when you are not loading a hosted playlist via playlistId.
playlistVideoIndex int	Zero-based index of the video to start on. Defaults to 0 (first video).

Each element in the videos array is a video object with the same properties as a single video (for example file, videoId, title, thumbnail).

Manual list:

"playlist": {
  "state": true,
  "playlistVideoIndex": 0,
  "videos": [
    { "videoId": "abc", "file": "https://.../1.m3u8", "title": "First", "thumbnail": "https://.../1.jpg" },
    { "videoId": "def", "file": "https://.../2.m3u8", "title": "Second", "thumbnail": "https://.../2.jpg" }
  ]
}

Hosted playlist:

"playlist": { "state": true, "playlistId": "your-vp-playlist-id" }

Video Locking

Video locking gates the video after a set amount of playback. When the viewer reaches the lock point, playback stops and the player shows the locked (paywall) screen. Useful for previews and paywalled content.

PROPERTY	DESCRIPTION
isEnabled boolean	Turns on video locking.
type string	How value is interpreted: seconds or percentage.
value int	How much of the video plays before it locks: a number of seconds (when type is seconds), or a percent of the duration (when type is percentage). Use 0 to lock immediately.

Example:

"videoLocking": { "isEnabled": true, "type": "seconds", "value": 30 }

Advertising

The player supports two kinds of ads: video ads (VAST) played through Google IMA between videos, and a display banner served through Google Publisher Tags (GPT). Set advertising to true to enable ads; the ads settings below apply only when it is on.

PROPERTY	DESCRIPTION
advertising boolean	Enables ads for the video.

Ads

The ads object holds all ad settings.

PROPERTY	DESCRIPTION
frequency object	How often video ads play. See below.
initialDelay object	When the first video ad becomes eligible. See below.
maxCap int	Maximum number of ads per session. 0 means unlimited.
adBreaks array	VAST ad breaks. Each break has an adTagUrl (an array of VAST tag URLs tried in order as a fallback). Multiple breaks are used in rotation across successive ads.
banner object	Display banner (GPT) settings. See below.

Each element in adBreaks has an adTagUrl property: an array of VAST ad tag URLs, tried in order as a fallback.

"adBreaks": [
  {
    "adTagUrl": [
      "https://pubads.g.doubleclick.net/gampad/ads?iu=/21775744923/external/single_preroll_skippable&sz=640x480&ciu_szs=300x250%2C728x90&gdfp_req=1&output=vast&unviewed_position_start=1&env=vp&correlator="
    ]
  }
]

frequency

PROPERTY	DESCRIPTION
type string	videos - plays an ad every N videos.
value int	Number of videos between ads.

initialDelay

PROPERTY	DESCRIPTION
type string	videos - the first ad becomes eligible after N videos.
value int	Number of videos before the first ad.

banner

The banner is a display ad served through Google Publisher Tags (GPT).

PROPERTY	DESCRIPTION
adUnitPath string	GPT ad unit path for the banner.
sizes array	Allowed banner sizes, for example [[300, 250], [728, 90]].

A complete ads object:

"ads": {
  "frequency": { "type": "videos", "value": 3 },
  "initialDelay": { "type": "videos", "value": 1 },
  "maxCap": 5,
  "adBreaks": [
    {
      "adTagUrl": [
        "https://pubads.g.doubleclick.net/gampad/ads?iu=/21775744923/external/single_preroll_skippable&sz=640x480&ciu_szs=300x250%2C728x90&gdfp_req=1&output=vast&unviewed_position_start=1&env=vp&correlator="
      ]
    }
  ],
  "banner": {
    "adUnitPath": "/1234567/your-banner-unit",
    "sizes": [[300, 250], [728, 90]]
  }
}

Player config Configurations

Most settings below are individual config properties. When a section is marked grouped under an object (for example the size object), those properties are nested under that key, like config.size: { ... }.

General Settings

PROPERTY	DESCRIPTION
muted boolean	Starts the player muted.
autoplay boolean	Starts next video playback automatically.
volume float	Default volume (0.0 - 1.0).
pauseOtherVideos boolean	Pauses other players on the page.
loop boolean	Loops the video.
soundSubtitleInversion boolean	Shows subtitles while the video is muted and hides them when it is unmuted. Turns off automatically once the viewer selects a subtitle manually.
autoHideOverlay boolean	Hides the overlay (controls) during playback and shows it on interaction. The overlay is not hidden while the video is paused.
playlistLoop boolean	Loops the playlist, returning to the first video after the last.
swipeToSkip boolean	Lets the viewer swipe to skip an ad. Enabled by default.
focusOnAutostart boolean	Scrolls to and focuses the player when it autostarts (first play only).
viewMode string	Layout mode: normal, external-actions, or page-fill. See below.

viewMode options (desktop only; mobile always uses normal):

• normal (default) - standard vertical player layout.
• external-actions - moves the side action buttons outside the player frame.
• page-fill - the player fills its parent container and enables the ambient background effect.

Player Size

Grouped under the size object.

PROPERTY	DESCRIPTION
sizeType string	Size mode: responsive (fills its container) or fixed (uses the height below). Defaults to responsive.
height int	Player height in pixels. Applies only when sizeType is fixed.

Autostart Settings

Autostart and autopause are controlled by three independent config objects: autostartOnLoad, autostartOnViewable, and autopauseOnViewable.

autostartOnLoad

Starts playback as soon as the video loads (first video only).

PROPERTY	DESCRIPTION
state boolean	Enables autostart on load.
onMobile boolean	Allows autostart on mobile devices.
percentageViewable float	Required viewable percentage (0.0 - 1.0).

autostartOnViewable

Starts playback when the player becomes viewable in the viewport.

PROPERTY	DESCRIPTION
state boolean	Enables autostart when viewable.
onMobile boolean	Allows viewable autostart on mobile devices.
percentageViewable float	Viewable percentage (0.0 - 1.0) required to trigger autostart.
removeAfterPlay boolean	Stops re-triggering autostart after the first play (for example when scrolling back to the player).

autopauseOnViewable

Pauses playback when the player is no longer sufficiently viewable.

PROPERTY	DESCRIPTION
state boolean	Enables autopause when not viewable.
onMobile boolean	Allows viewable autopause on mobile devices.
percentageViewable float	Viewable percentage (0.0 - 1.0) below which playback pauses.

Controls

Grouped under the controls object.

PROPERTY	DESCRIPTION
fullscreen boolean	Fullscreen button visibility.
share boolean	Share button visibility.
text boolean	Text display visibility.
seekbar boolean	Seekbar visibility.
settings boolean	Settings menu visibility.
time boolean	Time display visibility.
arrows boolean	Previous/next navigation arrows visibility.

Playback Rates

Supported playback speeds:

[0.25, 0.5, 0.75, 1, 1.25, 1.5, 1.75, 2]

Localization

Grouped under the lang object.

Language options for UI elements:

{
  "locale": "en",
  "controls": {
    "play": "Play",
    "pause": "Pause",
    "more": "more",
    "less": "less",
    "previous": "Previous",
    "next": "Next",
    "volume": "Volume",
    "mute": "Mute",
    "unmute": "Unmute",
    "settings": "Settings",
    "fullscreen": "Fullscreen",
    "minimize": "Exit Fullscreen",
    "live": "Live"
  },
  "settings": {
    "quality": "Quality",
    "subtitles": "Subtitles",
    "autoplay": "Autoplay",
    "playbackRate": "Speed",
    "auto": "Auto",
    "off": "Off",
    "normal": "Normal",
    "share": "Share",
    "copyLink": "Or copy link",
    "copy": "Copy",
    "close": "Close"
  },
  "ads": {
    "adLabel": "Ad"
  },
  "hints": {
    "swipeForMore": "Swipe for more"
  },
  "time": {
    "minuteAgoSingular": "{{n}} minute ago",
    "minuteAgoPlural": "{{n}} minutes ago",
    "hourAgoSingular": "{{n}} hour ago",
    "hourAgoPlural": "{{n}} hours ago",
    "yesterday": "Yesterday"
  }
}

The hints object localizes the swipe navigation hint shown to viewers. The time object localizes the relative publish date labels used when showRelativePublishDate is enabled; the {{n}} placeholder is replaced with the number of minutes or hours.

Skin Customization

Grouped under the skin object.

PROPERTY	DESCRIPTION
background string	Player background color.
text string	Text color.
buttons object	Button styles. See below.
seekbar object	Seekbar styles. See below.

buttons

PROPERTY	DESCRIPTION
icon string	Buttons icon color.
background string	Buttons background color.

seekbar

PROPERTY	DESCRIPTION
rail string	Seekbar rail color.
buffer string	Seekbar buffer color.
progress string	Seekbar progress color.
dragger string	Seekbar dragger color.

Content Display

PROPERTY	DESCRIPTION
showAuthor boolean	Displays the video author.
showPublishDate boolean	Displays the video publish date.
showRelativePublishDate boolean	Shows the publish date as relative time (for example "2 hours ago") instead of an absolute date.

Recommendations

PROPERTY	DESCRIPTION
recommended boolean	Enables recommended playlist mode.
recommendedId string	ID of the recommended playlist to load.

MP4 Quality Mode

PROPERTY	DESCRIPTION
mp4QualityMode boolean	Enables MP4 quality selection between predefined renditions.
mp4DeriveQualities boolean	Derives MP4 qualities from the .gjp4 metadata endpoint when video.mp4QualitiesUrl and video.mp4Qualities are both empty.

Social Sharing

PROPERTY	DESCRIPTION
socialMedia array	List of social platforms shown in the share menu.

Supported platforms: facebook, twitter (alias of x), x, reddit, pinterest, linkedin, tumblr, blogger, messenger, whatsapp, instagram, webshare.

"socialMedia": ["facebook", "x", "whatsapp", "linkedin"]

Note: instagram is shown on mobile devices only, and webshare requires the browser to support the Web Share API (it is added automatically when available).

Logo

Grouped under the logo object.

PROPERTY	DESCRIPTION
state boolean	Enables the custom logo overlay.
file string	Logo image URL.
onClickURL string	URL opened when the logo is clicked.

Font

Grouped under the font object.

PROPERTY	DESCRIPTION
family string	Font family name.
url string	Font stylesheet URL (for example a Google Fonts URL).

Full Configuration Template:

{
  "video": {
    "videoId": "",
    "file": "",
    "mp4QualitiesUrl": "",
    "mp4Qualities": [],
    "title": "",
    "description": "",
    "author": "",
    "publishDate": "",
    "thumbnail": "",
    "shareUrl": "",
    "live": false,
    "duration": 0,
    "tracks": [],
    "playlist": {
      "state": false,
      "playlistId": "",
      "playlistVideoIndex": 0,
      "videos": []
    },
    "videoLocking": {
      "isEnabled": false,
      "type": "seconds",
      "value": 0
    },
    "advertising": false,
    "ads": {
      "frequency": {
        "type": "",
        "value": 0
      },
      "initialDelay": {
        "type": "",
        "value": 0
      },
      "maxCap": 0,
      "adBreaks": [],
      "banner": {
        "adUnitPath": "",
        "sizes": []
      }
    }
  },
  "config": {
    "configId": "",
    "muted": false,
    "autoplay": false,
    "volume": 0.6,
    "pauseOtherVideos": true,
    "loop": false,
    "playlistLoop": false,
    "soundSubtitleInversion": false,
    "viewMode": "normal",
    "recommended": false,
    "recommendedId": "",
    "swipeToSkip": true,
    "showAuthor": false,
    "showPublishDate": false,
    "showRelativePublishDate": true,
    "size": {
      "sizeType": "responsive",
      "height": 650
    },
    "autostartOnLoad": {
      "state": false,
      "onMobile": false,
      "percentageViewable": 0.5
    },
    "autostartOnViewable": {
      "state": false,
      "onMobile": false,
      "percentageViewable": 0.5,
      "removeAfterPlay": false
    },
    "autopauseOnViewable": {
      "state": false,
      "onMobile": false,
      "percentageViewable": 0.5
    },
    "focusOnAutostart": true,
    "socialMedia": [],
    "playbackRates": [0.25, 0.5, 0.75, 1, 1.25, 1.5, 1.75, 2],
    "autoHideOverlay": true,
    "mp4QualityMode": false,
    "mp4DeriveQualities": false,
    "controls": {
      "fullscreen": false,
      "share": true,
      "text": true,
      "seekbar": true,
      "settings": true,
      "time": true,
      "arrows": true
    },
    "lang": {
      "locale": "",
      "controls": {
        "play": "Play",
        "pause": "Pause",
        "more": "more",
        "less": "less",
        "previous": "Previous",
        "next": "Next",
        "volume": "Volume",
        "mute": "Mute",
        "unmute": "Unmute",
        "settings": "Settings",
        "fullscreen": "Fullscreen",
        "minimize": "Exit Fullscreen",
        "live": "Live"
      },
      "settings": {
        "quality": "Quality",
        "subtitles": "Subtitles",
        "autoplay": "Autoplay",
        "playbackRate": "Speed",
        "auto": "Auto",
        "off": "Off",
        "normal": "Normal",
        "share": "Share",
        "copyLink": "Or copy link",
        "copy": "Copy",
        "close": "Close"
      },
      "ads": {
        "adLabel": "Ad"
      },
      "hints": {
        "swipeForMore": "Swipe for more"
      },
      "time": {
        "minuteAgoSingular": "{{n}} minute ago",
        "minuteAgoPlural": "{{n}} minutes ago",
        "hourAgoSingular": "{{n}} hour ago",
        "hourAgoPlural": "{{n}} hours ago",
        "yesterday": "Yesterday"
      }
    },
    "logo": {
      "state": false,
      "file": "",
      "onClickURL": ""
    },
    "skin": {
      "background": "#14161a",
      "text": "#ffffff",
      "buttons": {
        "icon": "#ffffff",
        "background": "rgba(0, 0, 0, 0.25)"
      },
      "seekbar": {
        "rail": "rgba(255, 255, 255, 0)",
        "buffer": "rgba(255, 255, 255, 0)",
        "progress": "rgba(255, 255, 255, 0.50)",
        "dragger": "#ffffff"
      }
    },
    "font": {
      "family": "Roboto",
      "url": "https://fonts.googleapis.com/css2?family=Roboto:wght@300;400;500;600&display=swap"
    }
  }
}

With these configurations, you can fully customize the VP Vertical Player to meet your needs.