Key-per-track content

To test this feature and view the example code, please see the Android SDK 5 Example Code Quick Start guide.

A key-per-track content stream consists of multiple tracks, where some tracks use different keys to others. This feature is designed to use different keys for different usage rules applied to different tracks, such as audio or video qualities. It can play in two ways, depending on how the licence server is configured.

Licence server responds with the requested key only

The licence server is configured to respond with only the key specified in the request. To play streams like this, multisession must be enabled.

Enabling multisession

When using custom DRM callbacks with theOTVMediaDrmCallbackinterface, this is done in the implementation of the isMultiSession() method.

import nagra.otv.sdk.drm.OTVMediaDrmCallback;

public class CustomDrmCallback implements OTVMediaDrmCallback {
    …
    public boolean isMultisession() {
        return true;
    }
    …
}

If using the convenience callbacks that have OTVCommonMediaDrmCallback as a parent, it can be set with setMultiSession().

import nagra.otv.sdk.drm.OTVCommonMediaDrmCallback;
import nagra.otv.sdk.drm.OTVHttpMediaDrmCallback;

public class MediaPlayer {
    …
    public MediaPlayer() {
        …
        OTVCommonMediaDrmCallback callback = new OTVHttpMediaDrmCallback();
        callback.setMultiSession(true);
        …
    }
    …
}

Licence server responds with all keys for the content

The licence server is configured so that when it receives a request for one key, it responds with all keys for the content. The player can handle this without any special configuration (for example, keeping multisession disabled). However, some player configuration parameters are available to optimise your track selection.

Selecting the correct track

When multiple tracks are available to choose from in a stream, some tracks may not be usable depending on:

• The codecs supported by the device.

• The device's supported DRM system and security level.

• The licence given to the customer.

The CONNECT Player SDK attempts to prevent a wrong track selection that would yield a playback error. Given the stream, the licence and the device, the Player ascertains where possible, which of the available tracks are playable and presents only the valid ones to the application.

This capability applies to the Video tracks for DASH streams only.

The key-per-track-robustness example demonstrates how three configuration parameters in the OTVConfigurarion class can assist in selecting:

• setVideoTrackLabel(String xVideoTrackLabel)
  DASH manifests may optionally associate each track (AdaptationSet) with a label to uniquely identify them. If a playable track with an associated label matches the preferred one - it will be selected. If there is no match, this preference is silently ignored. Its default value is an empty string, meaning there is no preference.

• setPreferredVideoTrack(int xPreferredVideoTrack)
  Instructs the player which of the available playable tracks to select:

  • VIDEO_TRACK_BITRATE_UNSET (default value) - no preference.

  • VIDEO_TRACK_BITRATE_HIGHEST - pick the playable track with the highest bitrate.

  • VIDEO_TRACK_BITRATE_LOWEST - pick the playable track with the lowest bitrate.

These two configurations can work for all clear and encrypted multiple video streams to indicate the default video track during player configuration just before beginning playback.

• setAutoVideoTrackSwitch(boolean xOverrideTrackAutoSwitching)
  Unlike the previous two, this parameter applies only to Key Per Track streams. This switch is enabled by default; some limitations apply:

  • Due to limitations of the PlayReady DRM system on Android devices, this parameter is not supported for PlayReady. It is only supported for Widevine and Connect DRM.

  • For Widevine, auto-switch is only supported from API 23 (Android 6.0) onwards.

Note that initially, the preferred video track is selected as per setPreferredVideoTrack(). If that value is invalid, the auto-switch (if enabled) is triggered.

• When auto-switch is true, a video track will be automatically switched to another valid video track with the highest bitrate

• When auto-switch is false, the Player lets the application decide which track to select. It sends a MediaPlayer.OnInfoListener.onInfo(MediaPlayer var1, int var2, int var3) notification with the following values:

  • what (var2) = OTVMediaPlayer.MEDIA_INFO_METADATA_UPDATE

  • extra (var3) = OTVMediaPlayer.MEDIA_INFO_METADATA_EXTRA_TRACKS_CHANGED

The key-per-track-robustness example shows how the above parameters can be configured, how to listen to track change events, and how to catch track errors. The example stream has three tracks: SD, HD and UHD, but the token provided yields keys only for the SD and HD tracks.

Offline playback

As only one licence is stored for offline playback, key-per-track content configured for the licence server responds with the requested key only is currently unsupported.