Configuration

This document provides basic configurations for the VP Player and its basic features. For the full configuration options, see the documentation. The following configurations are covered:

• Video details
• Playlist
• Subtitle tracks
• Player size
• Logging
• Preparing screen
• Level discovery
• Buffer stall handling
• Timed links

Video details

You can set up the video details for the player, which can be used by the player for various features based on the configuration. Here is an example of how to set up the video details:

vpPlayer("video-details-vp").setup({
    video: {
        file: "the_video_file_path",
        title: "",
        description: "",
        publishDate: "",
        duration: 0,
        description: "",
        thumbnail: "",
        filmstrip: "",
        author: "",
        source: "",
        tags: []
    }
});

PROPERTY	DESCRIPTION
video Object	This object contains in itself all of the properties shown below.
videoId string	The ID of the video.
assetId string	The ID used to setup DRM support.
fpsCertificateUrl string	The URL of to the FPS (Fair Play Streaming) Certificate.
fairPlayLicenseUrl string	The URL of the FairPlay license server. Falls back to drmLicenseUrl when not set.
widevineLicenseUrl string	The URL of the Widevine License. Falls back to drmLicenseUrl when not set.
drmLicenseUrl string	The unified DRM license URL, used as a fallback when the platform-specific license URLs (fairPlayLicenseUrl, widevineLicenseUrl) are not set.
title string	The title of the video.
description string	The description of the video.
file string	The URL of a single video file or live stream (mp4, m3u8).
filmstrip string	The URL of an image that the player will use to display a preview when seeking. (Must be 10x10 and 16:9 for now).
thumbnail string	The URL of an image that serves as a thumbnail when the video has not started playing.
tracks Array	Array of track objects that specify the different subtitles that the media item has. See Subtitle tracks.
duration int	The duration of the video.
live boolean	A boolean indicating whether the video is live.
liveType number	A string - realtime, slowtv, etc.
advertising boolean	A boolean indicating whether ads are on for the video.
related string	This property represents the link of a playlist which will be parsed so that it can be played by the video player.
timedLinks Array	Array of timestamped clickable links shown over the video. See Timed links.

Playlists

You can set up a playlist on the player, which will automatically play the next video in the playlist after the current video ends. Here is an example of how to set up a playlist:

vpPlayer('playlsit-vp').setup({
        projectId: "vp-player-projectId",
        config: {
            configId: "vp-player-configId",
            highlightCurrentVideo: true,
            controls: {
                relatedButton: true
            },
            showRelatedOnPause: {
                state: true,
                onMobile: false,
                from: 0.9,
            }
        },
        video: {
            file: 'the_video_file_path',
            playlist: {
                state: true,
                videos: [
                    {
                        videoId: "vp-player-videoId",
                        title: "Video Title",
                        thumbnailUrl: "the_video_thumbnail_path",
                        duration: 0 // video duration
                    },
                    {
                        videoId: "vp-player-videoId",
                        title: "Video Title",
                        thumbnailUrl: "the_video_thumbnail_path",
                        duration: 0, // video duration
                        startTime: 30 // this video starts 30 seconds in
                    },
                    {
                        videoId: "vp-player-videoId",
                        title: "Video Title",
                        thumbnailUrl: "the_video_thumbnail_path",
                        duration: 0 // video duration
                    },
                ]
            }
        }
    });

PROPERTY	DESCRIPTION
playlist Object	An object which is used to setup a playlist of videos in the player.
state boolean	Determines whether the playlist should be setup by the player.
playlistId string	Allows the use of a playlist which has already been created on vpPlayer admin (takes priority over the videos array).
playlistVideoIndex int	The index of the currently playing video within the playlist. The player derives it from the video it is playing, so setting it in the configuration has no effect — to choose which video plays first, set that video on the video object.
highlightCurrentVideo boolean	Determines whether the current video being played should be highlighted in the playlist popup. Note that this property is set on the config object, not on the playlist object.
algorithm string	If there is no playlistId and no videos array, then this algorithm will be used to determine what playlist to show.
title string	Sets title for the playlist being used.
videos array[object]	An array of objects following the same specified requirements of the video object used for the setup of the player.
startTime int	Set on an individual entry of the videos array, the position in seconds at which that video starts playing. It applies to every entry that carries it, not only to the first video of the playlist. Defaults to 0.

note

A playlist entry's startTime applies every time the player reaches that entry, including when the viewer navigates back to it. This is unlike the ?vpv=&vpt= deep link, which is a one-shot entry point per page load.

Subtitle tracks

Subtitles are supplied as an array of track objects on the video.tracks property. WebVTT files are used directly, and SRT files are converted as they load. Here is an example of how to set up subtitle tracks:

vpPlayer("vp-player-subtitles").setup({
    video: {
        file: "the_video_file_path",
        tracks: [
            {
                file: "the_subtitle_file_path",
                lang: "en",
                label: "English"
            },
            {
                file: "the_subtitle_file_path",
                lang: "sq",
                label: "Albanian"
            }
        ]
    }
});

PROPERTY	DESCRIPTION
tracks array[object]	An array of subtitle track objects, each one given with the three properties below.
file string	The URL of the subtitle file, in either WebVTT or SRT format.
lang string	The language code of the track, for example en.
label string	The name shown for the track in the settings menu, for example English.

Subtitles start off, and the viewer turns them on from the settings menu or with the C key. When the player selects a track on its own, it prefers the first usable track whose label does not contain "auto-generated", and falls back to the first usable one.

note

A track with no file, or an SRT track whose file cannot be loaded or converted, is skipped and marked unavailable rather than being attached as an empty track. The remaining tracks keep working, and a warning is logged on the subtitle channel — see Logging. Subtitles are removed from the settings menu only when every track is unavailable.

Player size

The VP Player allows you to set the size of the player either through the DIV container or by setting the size properties directly in the config.size property. You can set a FIXED size or a RESPONSIVE size. Here are examples of how to set the player size:

vpPlayer('vp-player-fixed').setup({
    config: {
        size: {
            sizeType: "FIXED",
            width: 500,
            height: 500
        }
    },
    video: {
        file: 'the_video_file_path',
    }
});


vpPlayer('vp-player-responsive').setup({
    config: {
        size: {
            sizeType: "RESPONSIVE",
            aspectRatio: "16:9"
        }
    },
    video: {
        file: 'the_video_file_path',
    }
});

PROPERTY	DESCRIPTION
size Object	An object that contains information about the size of the video file.
sizeType string	A property that indicates the type of the size of the video file. This can either be FIXED or RESPONSIVE.
aspectRatio string	A property that inidcates the aspect ratio of the video file. This can be 16:9, 4:3, 1:1, etc.
width number	An integer specifying the width of the player.
height number	An integer specifying the height of the player.

If the size type is set to "FIXED", you can set the width and height of the player in pixels by specifying the width and height properties, respectively. For example:

config: {
    size: {
        sizeType: "FIXED",
        width: 640,
        height: 360
    }
}

If the size type is set to "RESPONSIVE", you can set the aspect ratio of the player using the aspectRatio property. The aspect ratio is specified as a string in the format W:H, where W is the width and H is the height. For example, to set the aspect ratio to 1:1, you would use:

config: {
    size: {
        sizeType: "RESPONSIVE",
        aspectRatio: "1:1"
    }
}

The VP Player will then automatically adjust the size of the player to maintain this aspect ratio as the size of the container element changes.

Logging

The player includes a per-channel logging system that can help you debug issues during integration. Logging is configured through the top-level logging property (a sibling of video and config). Each subsystem of the player logs to its own channel, and every channel can have its own log level. Here is an example of how to set up logging:

vpPlayer("vp-player-logging").setup({
    video: {
        file: "the_video_file_path"
    },
    logging: {
        level: "warn",
        channels: {
            hls: "debug",
            ads: "silent"
        },
        ringBufferSize: 0,
        readUrlParam: true,
        readStorageKey: true
    }
});

PROPERTY	DESCRIPTION
logging Object	This object contains in itself all of the properties shown below.
level string	The global log level. Can be "silent", "error", "warn", "info", "debug" or "trace". Each level also emits everything more severe than itself, e.g. "warn" emits warnings and errors. Defaults to "silent".
channels Object	Per-channel log level overrides. Available channels: core, lifecycle, hls, manifest, ads, analytics, casting, drm, subtitle, controls, floating, multistream, network. A channel set to "inherit" (or omitted) falls back to the global level.
ringBufferSize int	The maximum number of log entries kept in memory. Set to 0 to disable the buffer.
readUrlParam boolean	Determines whether the player honors the ?vpdebug=... URL parameter, which overrides the configured log levels.
readStorageKey boolean	Determines whether the player honors the vp:debug localStorage key, which overrides the configured log levels.

tip

You can enable logging without changing the configuration by appending ?vpdebug=... to the page URL or setting the vp:debug localStorage key. The value is a comma-separated list: * enables all channels at "debug", hls,ads enables only those channels at "debug", and *:info,hls:trace sets the global level to "info" with the hls channel at "trace".

Preparing screen

When a video that is still being encoded is opened, its playback URL returns a 403 error. If handle403AsGeoBlocked is set to false, the player does not treat the error as a geo-blocking issue — instead it shows the preparing screen and polls the playback URL in the background until the video becomes available, then starts playback automatically. This applies to VOD only, and only when no alternative playbackUrls are configured.

The top-level preparing property (a sibling of video and config) controls how long the player keeps waiting and how often it polls. Polling backs off exponentially from backoff up to backoffMax, and each individual delay is randomized between half and one and a half times that value so that many viewers opening the same video do not poll in lockstep. When maxDuration elapses, the player stops waiting and shows the error screen.

vpPlayer("vp-player-preparing").setup({
    video: {
        file: "the_video_file_path"
    },
    config: {
        handle403AsGeoBlocked: false
    },
    preparing: {
        enabled: true,
        maxDuration: 1800000,
        maxAttempts: 200,
        backoff: 5000,
        backoffMultiplier: 2,
        backoffMax: 30000,
        probeTimeout: 10000
    }
});

PROPERTY	DESCRIPTION
preparing Object	This object contains in itself all of the properties shown below.
enabled boolean	Determines whether a video that is still encoding shows the preparing screen. When set to false the player shows its normal error screen instead. Defaults to true.
maxDuration int	The maximum time in milliseconds the player keeps showing the preparing screen before giving up and showing the error screen. Defaults to 1800000 (30 minutes).
maxAttempts int	A safety ceiling on the number of polls. maxDuration is the primary limit and is normally reached first; this only takes effect if the backoff settings are lowered enough to fit more polls into the same window. Defaults to 200.
backoff int	The time in milliseconds before the first poll. Defaults to 5000.
backoffMultiplier int	The factor the delay is multiplied by after each unsuccessful poll. Defaults to 2.
backoffMax int	The maximum time in milliseconds between polls. Defaults to 30000.
probeTimeout int	The time in milliseconds after which an unanswered poll is aborted and treated as unsuccessful. Defaults to 10000.

Level discovery

Videos that recover through the preparing screen usually start with only the qualities that have finished encoding. The top-level levelDiscovery property (a sibling of video and config) controls how the player discovers the remaining qualities: after playback starts, the player periodically refetches the master playlist and adds newly encoded qualities to the quality selector without interrupting playback.

note

Level discovery is exclusively linked to the preparing screen — it only runs for videos that have NOT started playing normally and recovered through it. Videos that start normally already load with their full set of qualities, so this feature has no effect on them. It also does not apply to live streams.

vpPlayer("vp-player-level-discovery").setup({
    video: {
        file: "the_video_file_path"
    },
    config: {
        handle403AsGeoBlocked: false
    },
    levelDiscovery: {
        enabled: true,
        interval: 30000,
        maxStableTicks: 5
    }
});

PROPERTY	DESCRIPTION
levelDiscovery Object	This object contains in itself all of the properties shown below.
enabled boolean	Determines whether the player looks for newly encoded qualities after recovering from the preparing screen. Defaults to true.
interval int	The time in milliseconds between each master playlist refetch. Defaults to 30000.
maxStableTicks int	The number of consecutive refetches with no new qualities after which the player stops polling. Defaults to 5.

tip

The polling cadence of the preparing screen itself is configured separately, under the top-level preparing property described above.

Buffer stall handling

When playback stops because the buffer runs empty (a buffer stall), the player waits for the buffer to recover on its own. If it does not recover within bufferStallTimeout milliseconds, the player attempts a recovery — switching to another stream when switchOnBufferStallError is enabled and alternative playbackUrls are available, otherwise recovering the media error in place.

By default the player waits 8 seconds (8000 ms). If buffer stalls are happening too often — for example on unstable networks where short stalls usually recover by themselves — you can increase this timeout so the player is less aggressive about switching streams. Likewise, you can lower it if you want faster failover. Here is an example of how to set it up:

vpPlayer("vp-player-buffer-stall").setup({
    video: {
        file: "the_video_file_path"
    },
    multiStream: {
        bufferStallTimeout: 15000,
        switchOnBufferStallError: true
    }
});

PROPERTY	DESCRIPTION
multiStream Object	This object contains in itself all of the properties shown below.
bufferStallTimeout int	The time in milliseconds the player waits after a buffer stall before attempting recovery (stream switch or media error recovery). Defaults to 8000.
switchOnBufferStallError boolean	Determines whether the player switches to another stream when a buffer stall does not recover within the timeout. Defaults to true.

tip

If the buffer recovers before the timeout expires, the pending recovery is cancelled and playback continues on the current stream — increasing bufferStallTimeout only affects stalls that persist.

Timed links

Timed links are clickable links that appear over the video at the times you choose. They are set per video through the video.timedLinks array, and the player shows one link at a time, switching with a short animation as playback reaches each link's time. Here is an example of how to set up timed links:

vpPlayer("vp-player-timed-links").setup({
    video: {
        file: "the_video_file_path",
        timedLinks: [
            {
                title: "Discover VP Player",
                url: "https://vp.gjirafa.tech/platform/vpplayer"
            },
            {
                title: "Try the interactive demo",
                url: "https://vp.gjirafa.tech/interactive-demo",
                time: 30,
                duration: 20
            }
        ]
    },
    config: {
        controls: {
            timedLinks: true
        }
    }
});

PROPERTY	DESCRIPTION
timedLinks Array	An array of link objects set on the video object. Each object holds the properties shown below.
title string	The text shown on the link.
url string	The destination, opened in a new tab. A URL without a scheme is treated as https. Links without a valid URL are ignored.
time int	The time in seconds from which the link is shown. Defaults to 0.
duration int	The time in seconds the link stays visible. Leave it out to keep the link visible until another link replaces it or the video ends.

Only one link is visible at a time. When several links cover the current playback position, the one with the latest time is shown, so seeking backwards brings an earlier link back and a replay shows the links again. Links are shown in the bottom right corner, above the control bar, and are hidden while an ad is playing. A few seconds after appearing, the link shrinks to an icon-only button so it takes up less of the picture, and the title stays available by hovering it. On small players it is always shown as an icon-only button.

note

Timed links can be switched off for a whole player with the controls.timedLinks property, which is set on config.controls rather than on the video and is on by default. It is documented with the other player controls under Controls.

note

On live streams there is no timeline to cue against, so only links with a time of 0 are shown and duration is ignored.

tip

If a logo is placed in the bottom right corner, timed links are moved to the top right so the two do not overlap.