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

Minimum Buffer should always be less than Maximum Buffer.
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 lets viewers see a preview image of video frames while scrubbing or seeking.

The Player calculates the corresponding thumbnail image from a sprite sheet or WebVTT track for any given playhead position.

Choose the approach that matches the data you receive from playback authorization:

Auto-derived configuration from a sprite URL: Use deriveSpriteKeyframe from @quickplay/content-authorization when playback authorization returns only a sprite URL. This approach returns KeyframeMetadata derived from the tile dimensions and count encoded in the filename.
Explicit configuration with a template URL: Use this when playback authorization already returns KeyframeMetadata, or when you need to provide a template URL with the ~index~ token and an explicit ThumbnailPreviewConfiguration object.
WebVTT thumbnail preview: Use this when your stream provides trickplay thumbnails in a WebVTT track.

Setup thumbnail preview

Approach 1: Auto-derived configuration from sprite URL

Use deriveSpriteKeyframe from @quickplay/content-authorization when playback authorization returns only a sprite URL and does not return KeyframeMetadata.

export interface KeyframeMetadata {
  name?: string;
  ia: string[];
  frequency: number;
  width: number;
  height: number;
  rows: number;
  columns: number;
}

import { deriveSpriteKeyframe } from '@quickplay/content-authorization';

const spriteUrl =
  'https://sprite.example.com/images/content_192_108_5.jpg';

const keyframeMetadata: KeyframeMetadata = deriveSpriteKeyframe(spriteUrl);

if (keyframeMetadata) {
  const thumbnailPreviewConfiguration = {
    numRows: keyframeMetadata.rows,
    numColumns: keyframeMetadata.columns,
    thumbnailWidth: keyframeMetadata.width,
    thumbnailHeight: keyframeMetadata.height,
    keyframeDuration: keyframeMetadata.frequency,
  };

  playerBuilder.enableThumbnailPreview(
    spriteUrl,
    thumbnailPreviewConfiguration
  );
}

Keyframe filename convention

deriveSpriteKeyframe requires the filename (before the file extension) to contain at least four underscore-separated segments, where the last three segments represent numerical dimensions:

Component	Description	Example
Width	Width (in pixels) of each thumbnail tile.	`192`
Height	Height (in pixels) of each thumbnail tile.	`108`
Tile count	Total number of thumbnail tiles in the sprite sheet.	`5`

For example, video_preview_IND_192_108_5.jpg yields width: 192, height: 108, columns: 100, rows: 1 (Math.ceil(5 / 100)), and frequency: 16.

Approach 2: Manual configuration with template URL

Use this approach when thumbnail sprites are distributed across multiple files using a template URL with the ~index~ placeholder.

Create `ThumbnailPreviewConfiguration`

ThumbnailPreviewConfiguration describes the layout and dimensions of each image in the sprite.

Name	Type	Required	Description
`numColumns`	`number`	No	Number of columns in each sprite image.
`numRows`	`number`	No	Number of rows in each sprite image.
`keyframeDuration`	`number`	No	Duration (in seconds) represented by each thumbnail image.
`thumbnailWidth`	`number`	No	Width (in pixels) of each thumbnail image.
`thumbnailHeight`	`number`	No	Height (in pixels) of each thumbnail image.
`totalSpriteIndices`	`number`	No	Total number of sprite files available across the content duration.

const thumbnailPreviewConfiguration = {
  numRows: 10,
  numColumns: 10,
  thumbnailWidth: 192,
  thumbnailHeight: 108,
  keyframeDuration: 16,
  totalSpriteIndices: 5,
};

Pass configuration to `PlayerBuilder`

Pass the template sprite URL and the configuration to enableThumbnailPreview on your PlayerBuilder instance before building the player:

Parameter	Type	Required	Description
`spriteURL`	`string`	Yes	Fully formed sprite image URL containing the `~index~` placeholder. The player calculates the sprite index from the playhead position and replaces `~index~` to fetch the sprite.
`thumbnailPreviewConfiguration`	`ThumbnailPreviewConfiguration`	No	Sprite dimensions and keyframe interval metadata.

const spriteUrl =
  'https://images.example.com/thumbnails/movie-~index~.jpg?width=1600';

playerBuilder.enableThumbnailPreview(
  spriteUrl,
  thumbnailPreviewConfiguration
);

Approach 3: WebVTT thumbnail preview

If your stream uses WebVTT tracks for trickplay thumbnails, supply the WebVTT URL to webVTTThumbnailPreview:

playerBuilder.webVTTThumbnailPreview(
  'https://images.example.com/thumbnails/track.vtt'
);

Implement thumbnail preview

After building and loading the player, retrieve thumbnail metadata for any seek position using the getThumbnail method on the Player instance.

Call `getThumbnail`

Pass the desired playhead position in seconds to getThumbnail:

Parameter	Type	Description
`position`	`number`	Playhead position (in seconds) for which to fetch the thumbnail.

const thumbnailPreviewMetadata = await player.getThumbnail(position);

`ThumbnailPreviewMetadata`

The returned metadata contains the coordinates and sprite URL needed to render the preview image:

Property	Type	Description
`thumbnailRowIndex`	`number`	Row index of the thumbnail tile within the sprite sheet.
`thumbnailColumnIndex`	`number`	Column index of the thumbnail tile within the sprite sheet.
`totalRows`	`number`	Total number of rows in the sprite image.
`totalColumns`	`number`	Total number of columns in the sprite image.
`spriteUrl`	`string`	URL of the sprite image for the given position.

CSS styling

Apply the returned metadata to style your thumbnail preview container:

CSS property	Value calculation
`width`	Container width in pixels (for example, `192px`).
`height`	Container height in pixels (for example, `108px`).
`background-image`	`url(${thumbnailPreviewMetadata.spriteUrl})`
`background-position`	`-${thumbnailPreviewMetadata.thumbnailColumnIndex * width}px -${thumbnailPreviewMetadata.thumbnailRowIndex * height}px`
`background-size`	`${thumbnailPreviewMetadata.totalColumns * width}px ${thumbnailPreviewMetadata.totalRows * height}px`

Note: Calling player.getThumbnail(position) is typically wired to a scrub bar hover or drag listener to update the thumbnail image as the viewer scrubs through the video.

Setting Max and Min Bitrate​

Setting Buffer configuration​

Minimum Buffer​

Maximum Buffer​

Buffer Behind​

Setting Initial Playback Time​

Setting Network configuration​

Network Retries​

Network Timeout​

Playback Buffer Timeout (ms)​

Trick Play​

Subtitle styling​

Thumbnail preview​

Setup thumbnail preview​

Approach 1: Auto-derived configuration from sprite URL​

Keyframe filename convention​

Approach 2: Manual configuration with template URL​

Create ThumbnailPreviewConfiguration​

Pass configuration to PlayerBuilder​

Approach 3: WebVTT thumbnail preview​

Implement thumbnail preview​

Call getThumbnail​

ThumbnailPreviewMetadata​

CSS styling​