DRM preferences and security levels

The devices on which the player runs may support DRM key systems at different security levels. Four increasing security levels are defined:

1. OTVDRMSL_UNKNOWN

2. OTVDRMSL_SW

3. OTVDRMSL_HW_CRYPT

4. OTVDRMSL_HW_DECODE

The SDK provides mechanisms by which the application can specify its preferred DRM key system. An API is provided to find the security level of supported key systems on the device to aid selection of the preferred key system.

A DRM Key System is identified by a String. The String format is defined by EME, for example, “com.widevine.alpha”.
This API allows the Widevine and PlayReady key systems to be queried; the string constants WIDEVINE_KS and PLAYREADY_KS are provided for that purpose.

Setting the preferred DRM key system

The decision on which DRM system to use on any given stream is left for the application by providing the correct OTVMediaDrmCallback derived callback class. The application queries the device to find which DRM systems it supports and then decides which protected streams can be played on that device and the DRM protection to use.

Querying security level capabilities on the device

The OTVDRM class provides two overloads of getOTVDrmInfo() to query the device DRM capabilities:

• getOTVDrmInfo() checks the device's general capabilities for both Widevine and PlayReady, without checking support for specific codecs.

• getOTVDrmInfo, (@NonNull String xDrmName, @NonNull String xMediaType, @NonNull String xContentType) checks the device's support based on the arguments provided. If a secure decoder (its name suffixed with ".secure") is found for the given codec, the method will return a non-empty array. If an empty array is returned, it may still be possible to play this content using an insecure decoder, but this cannot be guaranteed; it is for the application to determine whether to attempt to play the content.

  • xDrmName is the EME-defined name of the key system to be queried. The constants WIDEVINE_KS and PLAYREADY_KS are provided for this, but an empty string may be passed to query both key systems.

  • xMediaType is the type of media track to be queried. The constants MEDIA_TYPE_AUDIO and MEDIA_TYPE_VIDEO are provided for this.

  • xContentType is a combination of MIME type and codec to be queried. It must be provided in the format "<mime-type>;codecs=<single-codec>".

    

    Despite the format, only a single video or audio codec must be provided. For example, querying a video codec and an audio codec will require two distinct method calls.

Example usages

OTVDrmInfo[] drmInfo = OTVDRM.getOTVDrmInfo(WIDEVINE_KS, MEDIA_TYPE_VIDEO, "video/mp4;codecs=hvc1.1.6.L120.b0");
// If supported at Widevine L1, drmInfo will contain one item:
// {name: com.widevine.alpha, Level: OTVDRMSL_HW_DECODE, Content Type: video/mp4;codecs=hvc1.1.6.L120.b0}
// If no secure decoder is found, drmInfo will be empty.

OTVDrmInfo[] drmInfo = OTVDRM.getOTVDrmInfo(WIDEVINE_KS, MEDIA_TYPE_VIDEO, "video/mp4;codecs=avc1.42E01E,mp4a.40.2");
// drmInfo will be empty; avc1.42E01E and mp4a.40.2 must be queried separately

Querying security level capabilities for a given stream

Typically, the application obtains the information regarding the DRM protection systems it uses from the stream metadata. If this information is not available, for DASH streams only, the SDK provides an MpdParser utility class that can extract the DRM support from the stream’s manifest Media Presentation Description (MPD) file. If the application has the .mpd file, the information can be extracted either by the DRM system’s UUID or its key-system name. The application provides the file text and its URL as Strings to MpdParser static methods:

    List<String> uuidList = MpdParser.getDrmUUIDsFromMpd(streamUrl, mpdText);
    List<String> supportedDrmTypes = MpdParser.getSupportedDrmTypesFromMpd(streamUrl, mpdText);

If the application only has the stream manifest’s URL, MpdParser can download the file and then parse it. The download is done asynchronously, and the application needs to provide a listener in MpdParser constructor:

    List<String> uuidList;
    List<String> supportedDrmTypes;
    MpdParser.MpdDownloadListener onMpdDownloadedListener = new MpdParser.MpdDownloadListener() {
      @Override
      public void onSuccess(@NonNull MpdParser mpdParser) {
        uuidList = mpdParser.getDrmUUIDs();
        supportedDrmTypes = mpdParser.getSupportedDrmTypes();
      }
 
      @Override
      public void onFail(@NonNull MpdParser mpdParser, @Nullable Throwable e) {
        // Error downloading the file...
      }
    };
    new MpdParser(streamUrl, onMpdDownloadedListener);

The list of UUIDs will include all DRM systems advertised by the manifest, whereas the list of supported DRM types will only include those systems supported by the SDK.