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 the OTVPlayerConfiguration.Builder() object whose values are set before it is used to construct the OTVPlayerConfiguration object. The configuration object is then 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() setTunnelingEnabled()`
Buffering	`setMinBufferMs()` `setMaxBufferMs()` `setBufferForPlaybackMs()` `setBufferForPlaybackAfterRebufferMs()`
Override KeepScreenOn	setOverrideKeepScreenOn()

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);
// Override KeepScreenOn
configBuilder.setOverrideKeepScreenOn(true);

// 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);

Overriding KeepScreenOn behaviour

The SDK KeepScreenOn behaviour is by default:

The screen will be on when content is playing and will not go to ambient (screen saver) mode even after the user inactivity timeout.
The screen will go to ambient mode after the user inactivity timeout when content playback is paused or completed.

You can override this behaviour in the OTVPlayerConfiguration.

The application needs to set the overrideKeepScreenOn configuration flag using the OTVPlayerConfiguration.Builder API setOverrideKeepScreenOn.

JAVA

OTVPlayerConfiguration.Builder configBuilder = new OTVPlayerConfiguration.Builder();
// override KeepScreenOn as the application wants to handle the KeepScreenOn logic
configBuilder.setOverrideKeepScreenOn(true);

//Build the player configuration and pass it to OTVVideoView
OTVPlayerConfiguration config = configBuilder.build();
// Here videoView is the instance of OTVVideoView.
videoView.setPlayerConfiguration(config);

Provide a preferred language for audio/subtitle tracks

To override the default behaviour for audio/subtitle track selection, a preferred language can be provided via an IETF BCP 47 tag through the OTVPlayerConfiguration.setPreferredAudioLanguage() and OTVPlayerConfiguration.setPreferredTextLanguage() API.

JAVA

private final OTVPlayerConfiguration trackSelectionConfiguration =
  new OTVPlayerConfiguration.Builder()
    .setPreferredTextLanguage(PREFERRED_LANGUAGE)
    .setPreferredAudioLanguage(PREFERRED_LANGUAGE)
    .build();  //Build the player configuration and pass it to OTVVideoView

// Here videoView is the instance of OTVVideoView.
videoView.setPlayerConfiguration(trackSelectionConfiguration);