Advanced Player Configuration

PlaybackOptions encapsulates most of the different configurations of the Player that can be leveraged to customize the player behaviour. It is an optional parameter that provides granular control over many aspects of playback.

Best practice

The Player already has default values for all the PlaybackOptions, which are reliably optimal for most scenarios. It is recommended to override the default behaviour only to enforce any specific tried and tested behaviour, as invalid or inexact values can adversely affect the playback experience.

It is recommended to make all of these properties remotely configurable to ensure the ability to tweak playback behaviour remotely.

Initialize PlaybackOptions

It can be passed to the player using PlayerBuilder and cannot be changed after the playback has started.

let playbackOptions = {
    maxBuffer: 30,
};

playerBuilder
    .mediaElement(videoElement)
    .mediaUrl(contentUrl)
    .drmLicenseUrl(drmLicenseUrl)
    .drmScheme(drmScheme)
    .mediaType(playbackAsset.mediaType)
    .certificate(certificate)
    .playbackOptions(playbackOptions)
    .logger(logger)
    .build()    

Buffering Strategy

The various aspects of the default buffering strategy can be configured using the below-mentioned properties. Changing these values can affect the video start time and re-buffering ratio of the player.

Property Name	Type	Default Value	Description
minBuffer	number	2	Min buffer time (seconds) required to start playback; affects startup and rebuffering (must be less than max buffer; overridden by DASH manifest's minBufferTime if greater).
maxBuffer	number	10	Max buffer time (seconds) to be buffered ahead of playhead (must be greater than or equal to minBuffer).
bufferBehind	number	30	The maximum number of seconds of content that the StreamingEngine will keep in buffer behind the playhead
ignoreMinBufferTime	boolean	false	This setting enables player configuration to override manifest for rebuffering behavior. When enabled, the DASH parser disregards the minBufferTime specified in the manifest.

const playbackOptions = {
    minBuffer: 2,
    maxBuffer: 10,
    bufferBehind: 30,
    ignoreMinBufferTime: false, 
}

playerBuilder.playbackOptions(playbackOptions)
    

Initial Track Selection

The player bitrate selection based on previous network information provided by underlying browser. To dictates the preferred bit rate at start of the playback ensure the useNetworkInformation as false. Only then player will pick the bitrate we set using preferredBitrate, it can be passed to playbackOptions to override the default estimate and start with a better suited track. This can also help in optimizing video start time.

Property Name	Type	Default Value	Description
useNetworkInformation	boolean	true	Represents initial network bandwidth, in bits per second, that the player will attempt to use on startup for the optimal track variant selection.
preferredBitrate	number	NA	The preferredBitrate to use if there is not enough data, in bit/sec. Some browsers implement the Network Information API, which allows retrieving information about a users network connection

const playbackOptions = {
    useNetworkInformation: false
    preferredBitrate: 250000, 
}

playerBuilder.playbackOptions(playbackOptions)
    

Network Configurations

The amount of time the player is supposed to wait before considering a network call as failed can be configured using the below-mentioned properties.

Property Name	Type	Default Value	Description
stallTimeout	number	30	stall timeout in sec, after which we abort
connectionTimeout	number	30	connectiontimeout in sec, after which we abort
networkTimeout	number	30	Abort network requests after this amount of time, in seconds.
bufferTimeoutMs	number	40000	This allows to set a timeout in milliseconds ex: 40000 (40 sec), to handle the indefinite buffering on playback.
networkRetries	number	2	Indicates The maximum number of times the request should be retried before fail
retryDelay	number	1	the retry delay in seconds between retries

const playbackOptions = {
    stallTimeout: false
    connectionTimeout: 30, 
    networkTimeout: 30 ,
    bufferTimeoutMs: 40000,
    networkRetries: 2,
    retryDelay: 1,
}

playerBuilder.playbackOptions(playbackOptions)

Stall Configurations

Streaming stalls, where playback freezes momentarily, can disrupt the viewing experience. These configuration helps effectively handle stall on playback.

Property Name	Type	Default Value	Description
stallSkip	number	0.1	The number of seconds that the player will skip forward when a stall has been detected. If 0, the player will pause and immediately play instead of seeking. A value of 0 is recommended and provided as default on TV platforms (WebOS, Tizen, Chromecast, etc).
stallThershold	number	1	The maximum number of seconds that may elapse without the playhead moving (when playback is expected) before it will be labeled as a stall.
stallEnabled	boolean	true	When set to true, the stall detector logic will run. If the playhead stops moving for stallThreshold seconds, the player will either seek or pause/play to resolve the stall, depending on the value of stallSkip.

Adaptive Track Selection Strategy

The below-mentioned properties can be modified to dictate the strategy of the player to be employed when selecting tracks i.e. switching up / down in quality after the playback starts.

Property Name	Type	Default Value	Description
minTotalBytes	number	12e3	Minimum number of bytes sampled before we trust the estimate.
minBytes	number	16e3	Minimum number of bytes, under which samples are discarded Our models do not include latency information, so connection startup time (time to first byte) is considered part of the download time. Because of this, we should ignore very small downloads which would cause our estimate to be too low
fastHalfLife	number	2	The quantity of prior samples (by weight) used when creating a new estimate, in seconds.
slowHalfLife	number	5	The quantity of prior samples (by weight) used when creating a new estimate, in seconds.
bandwidthUpgradeTarget	number	0.85	The fraction of the estimated bandwidth which we should try to use when upgrading.
bandwidthDowngradeTarget	number	0.95	The largest fraction of the estimated bandwidth we should use. We should downgrade to avoid this.
switchInterval	number	8	The minimum amount of time that must pass between switches, in seconds.

const playbackOptions = {
    minTotalBytes: 128000,
    minBytes: 16000,
    fastHalfLife: 2,
    slowHalfLife: 5, 
    bandwidthUpgradeTarget: 0.85
    bandwidthDowngradeTarget: 0.95
    switchInterval: 8
}

playerBuilder.playbackOptions(playbackOptions)
    

Latency / Start position in Live streams

Presentation delay is the player constantly maintains the gap between player and live origin/server
By default, the presentation delay is determined by suggestedPresenationDelay provided in the manifest. It prevents the player from frequent buffering.

Property Name	Type	Default	Description
ignoreSuggestedPresentationDelay	boolean	false	The target offset time from live edge in milliseconds. The player will attempt to get as close as possible to this live offset during playback. If this property is set, the value calculated from the manifest will be ignored.
defaultPresentationDelay	Number	DASH Streams: 1.5 x minBufferTime specified in Manifest HLS Streams: Duration of 3 segments	The delay prevents the player goes into frequent buffering, maintain the delay from live origin. so player can build up adequate buffer.

 
const playbackOptions = {
    ignoreSuggestedPresentationDelay: true 
    defaultPresentationDelay: 25.6
}

playerBuilder.playbackOptions(playbackOptions)

Advanced DRM configurations

The Widevine DRM Level 3 (L3) offers a less secure playback environment compared to Levels 1 (L1) and 2 (L2). This is because L3 relies solely on software-based decryption, making it susceptible to screen recording or capture on some devices.

Enhancing Security with Robustness Levels

• HW_SECURE_ALL
• HW_SECURE_DECODE
• SW_SECURE_CRYPTO
• SW_SECURE_DECODE

Property Name	Type	Default	Description
videoRobustness	string	NA	The target offset time from live edge in milliseconds. The player will attempt to get as close as possible to this live offset during playback. If this property is set, the value calculated from the manifest will be ignored.
audioRobustness	string	NA	The minimum playback speed the player can use to fall back when trying to reach the target live offset.

 
playbackOptions.advancedDrmConfiguration = {
    videoRobustness: 'HW_SECURE_DECODE',
    audioRobustness: 'SW_SECURE_CRYPTO',
};
      
playerBuilder.playbackOptions(playbackOptions)

Precision Live Streming with SSAI

Target Live offset is the position in the Live window that the player tries to consistently play at, behind the live edge.
By default, the target offset is calculated from the properties of the manifest such as suggestedPresentationDelay, minBufferTime, etc.

Property Name	Type	Default	Description
autoCorrectDrift	boolean	true	If true, ignore the availabilityStartTime in the manifest and instead use the segments to determine the live edge. This allows us to play streams that have a lot of drift. If false, we can't play content where the manifest specifies segments in the future.
clockSyncUri	string	NA	An individual client's clock can be potentially very far off, but even small inaccuracies can have a big impact on playback. If the UTCTiming element is present in the manifest, the client can synchronize its clock by that. If not, the configured clockSyncUri will be used as a fallback

 
playbackOptions = {
    autoCorrectDrift: false,
    clockSyncUri: 'https://time.akamai.com/?iso',
};
      
playerBuilder.playbackOptions(playbackOptions)

Closed Caption Configuration

Property Name	Type	Default	Description
segmentRelativeVttTiming	boolean	false	To calculate VTT text timings relative to the segment start instead of relative to the period start (which is the default).
forceTransmuxTS	boolean	false	Transmux TS content even if not strictly necessary for the assets to be played, If this is true. Player currently only supports CEA 708 captions by transmuxing, so this value is necessary for enabling them on platforms with native TS support like Edge or Chromecast.

 
playbackOptions = {
    segmentRelativeVttTiming: true,
    forceTransmuxTS: false,
};
      
playerBuilder.playbackOptions(playbackOptions)

Dynamic playback quality control

This section introduces the player.restrictQuality() function, designed to enhance user experience by dynamically adjusting video quality based on the video element's size on the screen. This feature ensures quality with optimal bandwidth selection, considerably useful on (eg: multi view, pip, mobile browser). Default is false.

 
const player = playerBuilder
    .mediaElement(videoElement)
    .mediaUrl(contentUrl)
    .drmLicenseUrl(drmLicenseUrl)
    .drmScheme(drmScheme)
    .mediaType(playbackAsset.mediaType)
    .certificate(certificate)
    .playbackOptions(playbackOptions)
    .logger(logger)
    .build() 
      
       
// When the player enters PiP mode, Multi-view, Mobile browsers eg:(iPhone, iPad, Android)
    player.restrictQuality(true)  

// when the player exiting PiP mode, Multi-view, Mobile browsers eg:(iPhone, iPad, Android)
    player.restrictQuality(false) 

Preferred Video/Audio Codecs

This configuration dictates the player to pick the configured codecs in prioirty over others on playback.

Property Name	Type	Default	Description
preferredVideoCodecs	string[]	NA	The list of preferred video codecs, in order of highest to lowest priority.
preferredAudioCodecs	string[]	NA	The list of preferred audio codecs, in order of highest to lowest priority

 
playbackOptions = {
    preferredVideoCodecs: ['vp09', 'avc1.640028']; 
    preferredAudioCodecs:  ['mp4a.40.2']
};
      
playerBuilder.playbackOptions(playbackOptions)

Preferred Keysystems

Property Name	Type	Default	Description
preferredKeySystems	string[]	NA	If no key system is preferred, or no preferred key systems is valid, we'll fall back to the original behavior of choosing the first key system with configured license server url in the manifest.

 
playbackOptions = {
    preferredKeySystems : ['com.widevine.alpha', 'com.microsoft.playready']; 
};
      
playerBuilder.playbackOptions(playbackOptions)

Network Error Handling and Retry Strategies

This setting enhances the player's resilience against network errors (http-errors or network drops).

Property Name	Type	Default	Description
infiniteRetriesOnNetworkError	boolean	false	Allows player to retry infinite times during http-error or network drop. If true will retry the streams infinite times.

 
playbackOptions = {
    infiniteRetriesOnNetworkError: false; 
};
      
playerBuilder.playbackOptions(playbackOptions)