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.

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.
maxRedirects int	Maximum number of VAST wrapper redirects followed before giving up. `0` uses the IMA SDK default.
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,
  "maxRedirects": 4,
  "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.

Keyboard Shortcuts

Focus Mode on VP Player

You can use keyboard shortcuts when the player is in focus to control playback:

Spacebar / K - Play or pause playback
J / L - Seek backward or forward
Left Arrow / Right Arrow - Seek backward or forward
Up Arrow / Down Arrow - Go to the previous or next video
C - Toggle subtitles on or off
M - Mute or unmute
F - Enter or exit fullscreen

Seek steps are 5 seconds for videos of 30 seconds or less, and 10 seconds otherwise.

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"
  },
  "month": {
    "jan": "Jan",
    "feb": "Feb",
    "mar": "Mar",
    "apr": "Apr",
    "may": "May",
    "jun": "Jun",
    "jul": "Jul",
    "aug": "Aug",
    "sep": "Sep",
    "oct": "Oct",
    "nov": "Nov",
    "dec": "Dec"
  },
  "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 month object holds the abbreviated month names used when the absolute publish date is shown. Together with locale, it controls how the publish date is formatted for the viewer.

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.

Publish dates without a timezone offset are interpreted as UTC, so the displayed date stays consistent across viewer time zones.

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.

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,
      "maxRedirects": 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"
      },
      "month": {
        "jan": "Jan",
        "feb": "Feb",
        "mar": "Mar",
        "apr": "Apr",
        "may": "May",
        "jun": "Jun",
        "jul": "Jul",
        "aug": "Aug",
        "sep": "Sep",
        "oct": "Oct",
        "nov": "Nov",
        "dec": "Dec"
      },
      "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.

VP Apps

VP Player

VP Live

VP Stream

Content Monetization

Experience Curation

Revenue Increase

Gjirafatech Integrations

Frequently Asked Questions

Documentation

Blog

Configuration

Configuration Overview​

Player video Configurations​

Basic Video Options​

mp4Qualities element​

Tracks (Subtitles)​

Playlist​

Video Locking​

Advertising​

Ads​

frequency​

initialDelay​

banner​

Player config Configurations​

General Settings​

Player Size​

Autostart Settings​

autostartOnLoad​

autostartOnViewable​

autopauseOnViewable​

Controls​

Keyboard Shortcuts​

Playback Rates​

Localization​

Skin Customization​

buttons​

seekbar​

Content Display​

Recommendations​

MP4 Quality Mode​

Social Sharing​

Logo​

Font​

Full Configuration Template:​

Configuration Overview

Player `video` Configurations

Basic Video Options

`mp4Qualities` element

Tracks (Subtitles)

Playlist

Video Locking

Advertising

Ads

`frequency`

`initialDelay`

`banner`

Player `config` Configurations

General Settings

Player Size

Autostart Settings

`autostartOnLoad`

`autostartOnViewable`

`autopauseOnViewable`

Controls

Keyboard Shortcuts

Playback Rates

Localization

Skin Customization

`buttons`

`seekbar`

Content Display

Recommendations

MP4 Quality Mode

Social Sharing

Logo

Font

Full Configuration Template: