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
• Player size
• Logging
• Level discovery

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

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,
                playlistVideoIndex: 0,
                videos: [
                    {
                        videoId: "vp-player-videoId",
                        title: "Video Title",
                        thumbnailUrl: "the_video_thumbnail_path",
                        duration: 0 // video duration
                    },
                    {
                        vidoeId: "vp-player-videoId",
                        title: "Video Title",
                        thumbnailUrl: "the_video_thumbnail_path",
                        duration: 0 // video duration
                    },
                    {
                        vidoeId: "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	Determines which video in the playlist will be played first.
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.

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".

Level discovery

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.

Videos that recover this way 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 reuses the multiStream backoff settings: backoff, backoffMultiplier, backoffMax, and maxAttempts.