LiveConfiguration¶

One of the configuration fields present in the PlayerConfig, LiveConfiguration, is a set of live-related configuration options. Tweaking this configuration can allow you to achieve the desired performance when playing live content.

There are some other live-affecting params which are not inside the LiveConfiguration object, since they’re not exclusive for live content, such as BufferConfiguration.

Low latency¶

Our PRESTOplay SDK for Android is capable of playing CMAF Ultra-low latency streams. There is no special configuration for enabling this, if the stream is CMAF-LL compliant, it will be handled as such.

On the other hand, if you want to achieve the lowest possible latency, you should tweak some settings on the LiveConfiguration and the BufferConfiguration objects.

The PRESTOplay SDK for Android also provides some default low-latency-friendly values for these configurations. These can be set through the LowLatencyProfile. This configuration object receives an already built PlayerConfig and sets some config fields with the aim of reducing the latency.

You can tweak the LowLatencyProfile before applying it as well, through its Builder.

This snippet shows how to apply the LowLatencyProfile:

// Create player config, with url to play and other optional config
PlayerConfig cfg = new PlayerConfig.Builder("http://url.com/manifest.mpd").get();

// Apply the LowLatencyProfile to that config
cfg = new LowLatencyProfile.Builder().get().applyTo(cfg);

// Start playback
playerController.open(cfg);

Staying inside the Live Window¶

Live or streaming services usually make only a part of their Periods accessible at any specific point in time. The part of media which is accessible is defined by a segment list or by the buffer depth field. This is what is usually referred to as Live Window.

For this reason, if the player can’t keep up with the “speed” at which the Live Window moves ahead, it’s possible that playback stops after the player raises a fatal BehindLiveWindowException. Causes for this usually are network congestion at any point of the delivery chain.

To minimize the chances of a fatal exception being thrown for this cause, it is recommended not to start playback close to the beginning of the Live Window.

If you are in control of the media generation or packaging, we encourage a Live Window no shorter than 1 minute for most use cases. Note that increasing the buffer depth does not have an effect on the minimum achievable latency, and it simply provides extra resilience.

In the following sections you can find some suggested configurations which will help to avoid falling behind the Live Window.

openBundle.putParcelable(SdkConsts.INTENT_LIVE_CONFIGURATION, new LiveConfiguration.Builder()
        .liveEdgeLatencyMs(10_000)
.get());

openBundle.putParcelable(SdkConsts.INTENT_LIVE_CONFIGURATION, new LiveConfiguration.Builder()
        .liveEdgeLatencyMs(30_000)
        .catchupConfiguration(new CatchupConfiguration.Builder(CatchupConfiguration.TimeReference.MEDIA_END)
                .seek(50_000, 30_000)
        .get())
.get());

Setup and usage¶

In order to perform Trickplay playback, you’ll need to set a TrickplayConfiguration and then, whenever you want to use it, call PlayerController.enableTrickplayMode(boolean). You can call both methods during playback and changes should take effect immediately.

It is also possible to inform the TrickplayConfiguration through an Intent param when opening the PlayerController, or also in the PlayerConfig Builder; trickplayConfiguration(TrickplayConfiguration).

TrickplayConfiguration¶

The TrickplayConfiguration groups all the Trickplay-related settings. In it you can configure the playback speed, whether to keep audio enabled, and whether to use Trickplay-specific tracks, among other settings.

It is specially relevant the TrickplayConfiguration.speedupMode field. This field dictates which strategy to use for Trickplay playback.

Live Edge Catchup Types¶

The Live Edge Catchup feature presents two strategies:

• Speed. The player will speed up its playing rate once a configurable threshold is reached, and return to normal speed once a lower bound is reached.

• Seek. The player will perform a seek operation once the configurable upper threshold is reached.

Depending on the nature of the playing media one method may be preferred over the other one. If being as close to the live edge as possible is the most important in your use case, Seek mode may be preferred. For instance for a live sports broadcast. If, on the other hand, it’s crucial that the least amount of content is “lost” in the stream, Speed mode may be the best option. An example may be a live political debate.

Time reference¶

Additionally, the Live Edge Catchup behaviour can be configured to act relative to two time references:

• Media end. The specified thresholds in the CatchupConfiguration will be relative to the media end. This mode allows for precise control over how much behind the “live edge” the playback position lays.

• Buffer ahead. The specified thresholds in the CatchupConfiguration will look at the amount of buffer remaining. A good use case of this mode would be with low or ultra-low latency streams. By using the buffer health, the player won’t try to catch up if there’s not enough media to play.

Thresholds behaviour¶

The CatchupConfiguration defines a set of configurable thresholds. The thresholds are always relative to either the media end, or the buffer ahead end position. These specify exactly how the catchup mechanism works:

• Upper threshold. Defines when the catchup mechanism is triggered or started.

• Lower threshold. Defines when the catchup speeds down to normal speed, or where the player seeks to in case the Seek type is configured.

• Fallback threshold. Only applicable if the Catchup is configured with the Speed type. If this threshold is exceeded, the player will seek to it.

Configuration¶

CatchupConfiguration is part of the LiveConfiguration object, and can be set before calling PlayerController.open(...). Here are two example configurations.

The following configuration example uses the Speed catchup type, with BUFFER_AHEAD as time reference. It will start speeding up as soon as the buffer is 3 seconds long, at a speed of 10% faster than normal. And will speed down back to normal speed once there is only 1 second of content in the buffer left. This is an example of an aggressive configuration with a ultra-low latency use case in mind.

bundle.putParcelable(SdkConsts.INTENT_LIVE_CONFIGURATION, new LiveConfiguration.Builder()
        //.liveEdgeLatencyMs(1_000)
        //...
        .catchupConfiguration(new CatchupConfiguration.Builder(CatchupConfiguration.TimeReference.BUFFER_AHEAD)
                .speed(1_000, 3_000, 20_000, 1.1f)
            .get())
    .get());
// ...
playerController.open(bundle);

The next example uses the Seek catchup type, and also the MEDIA_END time reference. As soon as the playhead falls behind 50 seconds from the media end, it will seek to 10 seconds behind the media end. This will prevent the media from falling behind the live window (assuming a live window of 1 minute) and at the same time recovering to a point near the live edge through a seek operation. Note that it’s very likely that the seek operation triggered by this configuration will trigger a Buffering event, since there probably won’t be Buffered data at the seek location.

playbackBundle.putParcelable(SdkConsts.INTENT_LIVE_CONFIGURATION, new LiveConfiguration.Builder()
        //.liveEdgeLatencyMs(10_000)
        //...
        .catchupConfiguration(new CatchupConfiguration.Builder(CatchupConfiguration.TimeReference.MEDIA_END)
                .seek(10_000, 50_000)
            .get())
    .get());
// ...
playerController.open(bundle);

Callback¶

The application can optionally register a CatchupListener in the PlayerController. This callback will provide hook points whenever any relevant catchup operation takes place.

final CatchupListener catchupListener = new CatchupListener() {

    @Override
    public void onCatchupStarted(float speed) {
        Log.i(TAG, "Catchup Speed mode started with speed: " + speed);
    }

    @Override
    public void onCatchupEnded() {
        Log.i(TAG, "Catchup Speed mode ended");
    }

    @Override
    public void onCatchupSeek(CatchupConfiguration.Type type) {
        if (type == CatchupConfiguration.Type.SPEED) {
            Log.i(TAG, "Catchup seek due to fallback");
        } else if (type == CatchupConfiguration.Type.SEEK) {
            Log.i(TAG, "Catchup seek due to SEEK type");
        }
    }
};

playerController.addCatchupListener(catchupListener);
// ...
playerController.open(...);

HDMI cable connection¶

During the playback, PlayerController is listening to HDMI connection change (ACTION_HDMI_AUDIO_PLUG event) and pauses the playback when HDMI is disconnected. The playback is able to continue afterwards when un-paused. Some devices also send ACTION_HDMI_AUDIO_PLUG event when HDMI display is turned on and off and the SDK will handle it in the same way. This logics can be disabled by unsetting PlayerSDK.PAUSE_ON_HDMI_DISCONNECTED option.

DRM license can additionally specify digital output protection by requiring a particular HDCP level. Trying to play a content with required HDCP level exceeding the level supported by device or display results in fatal CastLabsPlayerException with TYPE_VIDEO_DECRYPTION_ERROR.

Disconnecting HDMI cable changes HDCP level as well, but the change is detected by the SDK which saves the current playback and releases PlayerController with CastLabsPlayerException, TYPE_HDCP_CONNECTION_WARNING. When HDMI is connected back, the playback will be restored by the SDK automatically. This logics can be disabled by unsetting PlayerSDK.FORCE_HDCP_EXCEPTION option.

HDMI display on and off¶

There is no way for the SDK to know HDMI display state in order to handle it appropriately. It is recommended that HDMI CEC is enabled where possible to handle application’s playback activity lifecycle which in its turn handles the playback lifecycle. If there is no way to rely on HDMI CEC then the application is recommended to close the playback upon receiving CastlabsPlayerException, TYPE_HDCP_CONNECTION_WARNING.

HDCP exception timeout¶

Starting the playback and installing DRM keys may take less time than setting HDCP connection and level. To handle this case, PlayerSDK.HDCP_EXCEPTION_TIMEOUT_MS is defined, making the playback to wait for HDCP completing its setup. If HDCP level is neither ready nor sufficient after the timeout then fatal CastLabsPlayerException is raised with TYPE_VIDEO_DECRYPTION_ERROR.

Initialization Behavior¶

The PRESTOplay SDK for Android enables uninterrupted initialization, even if the Widevine Content Decryption Module (CDM) becomes unresponsive. When the first PlayerController is opened after an SDK initialization with a drmConfiguration, it will wait for the DRM capabilities information to be retrieved for up to 10 seconds. During this time, the player will be in the “Preparing” state without blocking the main thread.

It is important to note that this timeout is measured from the SDK initialization call until the first instance of opening a controller after such initialization. The results of this operation will be cached, so subsequent playback sessions will not need to wait for this process.

The initialization process is typically fast and does not block other operations, such as calling PlayerController.open. However, calling these operations in quick succession might lead to a longer than expected startup time for the first playback.

DRM capabilities detection¶

In order to determine which DRM systems are available, the PRESTOplay SDK for Android performs a system check. It has been observed that under unknown circumstances, CDMs sometimes become unresponsive.

Once the DRM capabilities information is successfully retrieved, different outcomes can occur depending on the usage of the SDK and the configuration:

• Widevine is present: Playback proceeds as expected using the Widevine DRM system.

• Widevine is not present: This can indicate that Widevine is either not supported or the CDM service is unresponsive.

  • Manual Force of Widevine in DrmConfiguration: If Widevine has been manually forced in the DrmConfiguration, a fatal error will be thrown upon calling controller.open since the Widevine DRM system is unavailable.

  • BestAvailable DRM in DrmConfiguration: If BestAvailable has been specified in the DrmConfiguration, and another DRM system is available on the device, playback will proceed using that alternative system.

Recommendations¶

To handle potential Widevine CDM unresponsiveness, we recommend the following actions:

1. Register our OMA plugin when initializing the SDK.

2. Specify BestAvailable as the DRM system in the DrmConfiguration.

By adopting these measures, if the Widevine CDM is indeed unresponsive, playback can still be achieved using an alternative DRM system.

Please note that since OMA is a software DRM implementation, it may have similar licensing restrictions as Widevine L3. These restrictions could impact the available renditions, such as being limited to 720p or similar resolutions. The specific limitations ultimately depend on the licensing policy configuration set in the DRM backend.