Advanced player configuration

The CONNECT Player SDK 5 can be configured with several settings before playback using the OTVPlayerConfiguration class. These settings range from the basic - for example, setting minimum and maximum video resolution - to advanced settings that will have a more subtle effect on user experience, such as setting the minimum duration of buffered data required before the player can switch to a higher quality video track.

Each setting in OTVPlayerConfiguration is optional, with player defaults used for those that are unchanged. For example, if no maximum bitrate is set, its default is Integer.MAX_VALUE which is effectively unlimited.

The OTVPlayerConfiguration is created using a "builder" object - OTVPlayerConfiguration.Builder() - whose values are set before it is used to construct the OTVPlayerConfiguration object. The configuration object is then is passed to the OTVVideoView using the OTVVideoView#setPlayerConfiguration() method.

The builder's configuration setting methods can be broken down into the following categories:

Adaptive bitrate selection	`setMinDurationForQualityIncreaseMs()` `setMaxDurationForQualityDecreaseMs()` `setMinDurationToRetainAfterDiscardMs()` `setBandwidthFraction()` `setBufferedFractionToLiveEdgeForQualityIncrease()`
HTTP data source	`setConnectTimeoutMillis()` `setReadTimeoutMillis()` `setAllowCrossProtocolRedirects()` `setMinimumLoadableRetryCount()`
DASH live start	`setLivePresentationDelayMs()` `setLivePresentationDelayOverridesManifest()`
HLS live start	`setStartSegmentIndex()`
Track selection	`setMinVideoWidth()` `setMaxVideoWidth()` `setMinVideoHeight()` `setMaxVideoHeight()` `setMinVideoFrameRate()` `setMaxVideoFrameRate()` `setMinVideoBitrate()` `setMaxVideoBitrate()` `setMaxAudioChannelCount()` `setMaxAudioBitrate()` `setExceedAudioConstraintsIfNecessary()` `setAllowAudioMixedMimeTypeAdaptiveness()` `setAllowAudioMixedSampleRateAdaptiveness()` `setAllowAudioMixedChannelCountAdaptiveness()`
Buffering	`setMinBufferMs()` `setMaxBufferMs()` `setBufferForPlaybackMs()` `setBufferForPlaybackAfterRebufferMs()`

Example code

The following example shows a selection of configuration settings covering different aspects of player behaviour. The OTVPlayerConfiguration object is then built and passed to the OTVVideoView where it will take effect when playback starts:

JAVA

OTVPlayerConfiguration.Builder configBuilder = new OTVPlayerConfiguration.Builder();

// Adaptive bitrate selection
configBuilder.setMinDurationForQualityIncreaseMs(5000);
configBuilder.setBandwidthFraction(0.75f);
// HTTP data source
configBuilder.setConnectTimeoutMillis(2000);
// Audio
configBuilder.setMaxAudioChannelCount(6);
// Video
configBuilder.setMaxVideoWidth(1920);
configBuilder.setMaxVideoHeight(1080);
// Buffer
configBuilder.setMinBufferMs(30000);

// Player configuration is built and passed to an OTVVideoView instance prior to playback
OTVPlayerConfiguration config = configBuilder.build();
videoView.setPlayerConfiguration(config);
videoView.setVideoPath(streamUrl);
videoView.start();

OTVVideoView resolution and bitrate overrides

Three OTVPlayerConfiguration methods - setMaxVideoWidth() , setMaxVideoHeight and setMaxVideoBitrate - will be overridden if their equivalent method in OTVVideoView - setMaxResolution() and setMaxBandwidth() - is called at any point, as long as the values passed to the methods are valid. If the OTVVideoView methods are called with invalid values, such as a zero or negative bitrate, the OTVPlayerConfiguration value will be used.

The following examples provide a clear demonstration.

setMaxResolution() values are both valid. The player's maximum video resolution will be 1920 x 1080:

CODE

otvVideoView.setMaxResolution(1920, 1080);

OTVPlayerConfiguration.Builder configBuilder = new OTVPlayerConfiguration.Builder();
configBuilder.setMaxVideoWidth(1280); // overridden by 1920
configBuilder.setMaxVideoHeight(720); // overridden by 1080

setMaxResolution() values are not valid (0 and negative). The player's maximum video resolution will be 1280 x 720:

CODE

otvVideoView.setMaxResolution(0, -1080);

OTVPlayerConfiguration.Builder configBuilder = new OTVPlayerConfiguration.Builder();
configBuilder.setMaxVideoWidth(1280); // Used - because 0 width is invalid
configBuilder.setMaxVideoHeight(720); // Used - because a negative height is not valid

setMaxResolution() width is valid, but the height is not. The player's maximum video resolution will be 1920 x 720.

CODE

otvVideoView.setMaxResolution(1920, 0); // 1920 is a valid width, but 0 is not a valid height

OTVPlayerConfiguration.Builder configBuilder = new OTVPlayerConfiguration.Builder();
configBuilder.setMaxVideoWidth(1280); // Not used - overridden by 1920
configBuilder.setMaxVideoHeight(720); // Used - 0 is not a valid height to override this

Overriding a DASH manifest's suggestedPresentationDelay

A DASH manifest may contain a suggestedPresentationDelay value, which by default will take priority over the value set by setLivePresentationDelayMs(). To enable the OTVPlayerConfiguration to override the manifest's value, setLivePresentationDelayOverridesManifest(true)must be called in addition to setLivePresentationDelayMs().

If setLivePresentationDelayOverridesManifest(true) is not called, suggestedPresentationDelay will be used when it is present; when it is absent, the setLivePresentationDelayMs() value will be used.

JAVA

OTVPlayerConfiguration.Builder configBuilder = new OTVPlayerConfiguration.Builder();
configBuilder.setLivePresentationDelayMs(30000); 
configBuilder.setLivePresentationDelayOverridesManifest(true);