Skip to main content

Player Configuration

Setting Max and Min Bitrate

Configures the Player's variant adaptation logic with the passed maximum bitrate constraint and minimum bitrate constraint.

// Configuring max Video and Audio Bitrate
const MAX_BITRATE_BPS = 780000;
player.maxBitrate = MAX_BITRATE_BPS;
// Configuring mix Video and Audio Bitrate
const MIN_BITRATE_BPS = 140000;
player.minBitrate = MIN_BITRATE_BPS;

Setting Buffer configuration

The duration of media that must be buffered for playback to start or resume following a user action such as a seek, in seconds.

Minimum Buffer

The number of seconds the content has to be buffered before playback starts. This affects both buffering at startup and re-buffering later during playback.

For example, if this is set to 15, buffering state remains until the content is 15 seconds buffered.

const MINIMUM_BUFFER_IN_SECONDS = 5;

const player = window.playerBuilder
.mediaElement(videoElement)
.mediaUrl(contentUrl.value)
.playbackOptions({
autoPlayOnLoad: false,
minBuffer: MINIMUM_BUFFER_IN_SECONDS,
})
.build();

Maximum Buffer

The number of seconds of content that the StreamingEngine will attempt to buffer ahead of the playhead. This value must be greater than or equal to the minBuffer.

const MAXIMUM_BUFFER_IN_SECONDS = 10;

const player = window.playerBuilder
.mediaElement(videoElement)
.mediaUrl(contentUrl.value)
.playbackOptions({
autoPlayOnLoad: false,
maxBuffer: MAXIMUM_BUFFER_IN_SECONDS,
})
.build();

Buffer Behind

The maximum number of seconds of content that will be kept in buffer behind the playhead when it appends a new media segment.

const BUFFER_BEHIND_IN_SECONDS = 10;

const player = window.playerBuilder
.mediaElement(videoElement)
.mediaUrl(contentUrl.value)
.playbackOptions({
autoPlayOnLoad: false,
bufferBehind: BUFFER_BEHIND_IN_SECONDS,
})
.build();
info
  1. Minimum Buffer should always be less than Maximum Buffer.
  2. If DASH manifest's minBufferTime is greater it overrides Minimum Buffer.

Setting Initial Playback Time

The initial time from which player should start playback.

const INITIAL_PLAYBACK_TIME_SECONDS = 2;
const playerBuilder = flPlayer.createPlayerBuilder();
const player = window.playerBuilder
.mediaElement(videoElement)
.mediaUrl(contentUrl.value)
.playbackOptions({
autoPlayOnLoad: false,
initialPlaybackTime: INITIAL_PLAYBACK_TIME_SECONDS,
preferredAudioLanguage: 'fr',
preferredTextLanguage: 'fr',
})
.build();

Setting Network configuration

Library allows user to configure the network request retries and network timeout

Network Retries

Indicates The maximum number of times the request should be retried before failing it.

const NETWORK_RETRIES = 3;

const player = window.playerBuilder
.mediaElement(videoElement)
.mediaUrl(contentUrl)
.playbackOptions({
networkRetries: NETWORK_RETRIES,
})
.build();

Network Timeout

Player abort network requests after the given amount of time, in seconds.

const NETWORK_TIMEOUT = 15;

const player = window.playerBuilder
.mediaElement(videoElement)
.mediaUrl(contentUrl)
.playbackOptions({
networkTimeout: NETWORK_TIMEOUT,
})
.build();

Playback Buffer Timeout (ms)

To ensure uninterrupted playback, the player will terminate playback with a buffer timeout error (code: 0x400215) if it cannot download enough data within a set time limit. This timeout is ideally set higher than network stall or connection timeouts (e.g., greater than 30000 milliseconds) to avoid premature termination due to temporary network fluctuations.

const BUFFER_TIMEOUT_IN_Ms = 60000; // 60 seconds

const player = window.playerBuilder
.mediaElement(videoElement)
.mediaUrl(contentUrl.value)
.playbackOptions({
autoPlayOnLoad: false,
bufferTimeoutMs: BUFFER_TIMEOUT_IN_Ms,
})
.build();

Trick Play

The factor by which playback should be sped up.

/**
* The factor by which playback should be sped up.
* Must be greater than zero.
* 1.0 indicates normal speed
*/
player.playbackRate = 2.0; // Renders in 2X mode.

Subtitle styling

Subtitle styles can be changed by using the below css classes. Respective css classes can be added and removed from the video element in order to see the visual effects.

video.teal-text-color::cue {
color: rgb(0, 177, 172);
}
video.red-text-color::cue {
color: rgb(183, 32, 37);
}
video.yellow-text-color::cue {
color: rgb(255, 212, 81);
}
video.grey-text-color::cue {
color: rgb(162, 165, 164);
}

video.small-text-size::cue {
font-size: 14px;
}
video.medium-text-size::cue {
font-size: 22px;
}
video.large-text-size::cue {
font-size: 32px;
}

video.line-height-1_2::cue {
line-height: 1;
}

video.line-height-1_5::cue {
line-height: 1.5;
}

video.line-height-2::cue {
line-height: 2;
}
const classList = videoElement.classList;
classList.remove('large-text-size', 'small-text-size');
classList.add('medium-text-size');

Thumbnail Preview

Thumbnail Preview is a functionality that allows users to see a preview image of the video while seeking.

The Player uses a series of images woven into a sprite from a given URL which is used to retrieve the corresponding image for a given playhead position.

Setup Thumbnail Preview

Create ThumbnailPreviewConfiguration

ThumbnailPreviewConfiguration describes the dimensions and duration of each image in a given sprite.

NameTypeRequiredDescription
noOfcolumnsnumberfalseThe number of columns in each sprite image.
noOfRowsnumberfalseThe number of rows in each sprite image.
keyFrameDurationnumberfalseThe time (in seconds) that each thumbnail in each sprite image corresponds to.
thumbnailWidthnumberfalseThe width (in pixels) of each thumbnail in each sprite image.
thumbnailHeightnumberfalseThe height (in pixels) of each thumbnail in each sprite image.
totalSpriteIndicesnumberfalseThe total number of sprites available for the total duration of the content.
let thumbnailPreviewConfiguration = {
numRows: rows,
numColumns: columns,
thumbnailWidth: width,
thumbnailHeight: height,
keyframeDuration: frequency,
totalSpriteIndices: sizeOfArrayOfItems
}

Pass information to PlayerBuilder

Thumbnail Preview is an optional feature that can be opted into by passing the required information to enableThumbnailPreview of the corresponding PlayerBuilder (See Player creation) instance.

NameTypeRequired?Description
spriteURLStringTrueThe fully formed sprite image URL that combines the endpoint URL and generic name, which includes the flag ~index~. Player calculates the sprite index based on given position and replaces ~index~ with the index to construct the sprite URL.
thumbnailPreviewConfigurationThumbnailPreviewConfigurationFalseThe ThumbnailPreviewConfiguration instance that holds the required metadata for sprite images.
playerBuilder.enableThumbnailPreview(
spriteURL,
thumbnailPreviewConfiguration
)

Implement Thumbnail Preview

The metadata for a particular position can be obtained by calling the getThumbnail extension API on the Player instance. The API returns the metadata for the given position.

ParameterTypeDescription
positionnumberThe position of the playhead for which the thumbnail is to be retrieved, in seconds.

ThumbnailPreviewMetadata

ParameterTypeDescription
thumbnailRowIndexnumberthumbnailSprite row index for corresponding seekPoint.
thumbnailColumnIndexnumberthumbnailSprite column index for corresponding seekPoint.
totalRowsnumbertotal number of rows in the sprite image.
totalColumnsnumbertotal number of columns in the sprite image.
spriteUrlstringurl consisting of the sprite image.
const thumbnailPreviewMetadata = player.getThumbnail(position)

CSS styling

stylesvalues
widthwidth of the container in px eg: 192px
heightheight of the container in px eg: 108px
background-position${thumbnailPreviewMetadata.thumbnailRowIndex * width}px ${thumbnailPreviewMetadata.thumbnailColumnIndex * height}px
background-image${thumbnailPreviewMetadata.spriteUrl}
background-size${thumbnailPreviewMetadata.totalRows * width}px ${thumbnailPreviewMetadata.totalColumns * height}px

This function is typically called in tandem with a scrub bar listener attached to the Player which listens to all the seeking activity from the user.