Media3 NAGRA PRM Extension Integration Guide

The following procedures describe how to create a new Android application and use Media3 with this extension SDK to play a NAGRA PRM encrypted video stream.

Prerequisites

Tools

The following development tools need to be installed; the number in square brackets denotes the earliest supported version of the software verified by NAGRA.

• Java SDK – download the JDK [Java v17] from http://www.oracle.com/technetwork/java/javase/downloads/index.html.

• Android Studio – download the latest version of Android Studio from http://developer.android.com/sdk/index.html.

• An Android STB which has built-in support for NAGRA PRM decryption

Dependencies

The external library dependency androidx.media3:media3-exoplayer:1.4.1 is required for Media3. Dependencies for other features are listed under the relevant feature description.

Product release files

NAGRA supplies the following files as part of your release:

• media3-prm-extension-<SW_VERSION>-sdk-integration.aar
  Use this file is used for integration activities. It is necessary for producing debug logs from the native part of the application.

• media3-prm-extension-<SW_VERSION>-sdk-production.aar
  This file replaces the integration version when the finished application is ready to be deployed.

• You will also need the PRM Operational Vault file opvault.json.

Integration process

We recommend you perform integration of NAGRA PRM Extension in the following stages:

• In conjunction with the Media3 NAGRA PRM Extension Example Code Quick Start guide, use the code examples to explore and test the features of the extension.

• Using this guide, create your basic player, following the steps described below.

• Develop your code to add encrypted playback and other features to the player.

• When development is complete, replace the integration file with the production version. Carry out final testing and submit to the Play Store.

Creating the project

Use the following procedure to create a new Android Studio project to build the basic player for app development:

1. Create a suitable directory and extract the SDK zip file to it. Rename the sdk-integration.aar file otvsdk.aar.

   The sdk-production.aar file is used to build the production version.

2. In Android Studio, create a new Basic Activity project.

   In the wizard, set the Minimum API level to 21 (Android 5.0 Lollipop).

3. In the new project, ensure the Android view is selected, and then select app > manifests, and open the AndroidManifest.xml file. Add the following permission before the <application> tag.

   JAVA

   <uses-permission android:name="android.permission.INTERNET"/>

4. Switch to Project view, expand app and copy the otvsdk.aar file into the \common\libs directory.

Next step: add Media3 NAGRA PRM Extension to your application

Adding Media3 NAGRA PRM Extension to your application

Update the build.gradle

1. In Project view, select app > src and open the build.gradle file. In the android block, change the minSdkVersion to 21.

   JAVA

     android {
       compileSdkVersion 31
       defaultConfig {
         applicationId "com.example.myapplication"
         minSdkVersion 21
         targetSdkVersion 30
       ...

2. Add the following lines to the android block:

   JAVA

   compileOptions {
     sourceCompatibility JavaVersion.VERSION_1_8
     targetCompatibility JavaVersion.VERSION_1_8
   }

3. In the dependencies block:

   1. Change the implementation fileTree(dir: 'libs', include: ['*.jar']) filetype to ['*.aar'].

   2. Add the dependency:

      JAVA

      dependencies {
        implementation fileTree(dir: 'libs', include: ['*.aar'])
        implementation("androidx.media3:media3-exoplayer:1.4.1")
        implementation("androidx.media3:media3-ui:1.4.1")
      }

      On completion, sync the build.gradle.

Edit the MainActivity.java

Add the minimum amount of code to enable playback of a single clear stream (identified by a hard-coded string) as soon as the app starts.

1. Select app > src > main > java > [filename] and open the MainActivity.java file. Add the following imports:

   JAVA

   import com.nagra.prm.NagraDefaultMediaSourceFactory;

2. Below the line public class MainActivity extends AppCompatActivity { add:

   JAVA

   static final String  TAG = "MainActivity";
   protected PlayerView mPlayerView;
   private String       mVideoURI = "https://d3bqrzf9w11pn3.cloudfront.net/basic_dash_bbb_clear/bbb_public.mpd";

3. Replace the contents of the onCreate method with following to set a reference to the video view and load the SDK.

   JAVA

   @Override
   protected void onCreate(Bundle savedInstanceState) {
     super.onCreate(savedInstanceState);
     setContentView(R.layout.activity_main);
     mPlayerView = findViewById(R.id.media3_playerView);
   }

4. Add the following to set the Android onStart method, set the stream and start it.

   JAVA

   @Override
   public void onStart()
   {
     super.onStart();
     ExoPlayer.Builder playerBuilder =
         new ExoPlayer.Builder(/* context= */ this)
             .setMediaSourceFactory(new NagraDefaultMediaSourceFactory(this));
     ExoPlayer player = playerBuilder.build();
     mPlayerView.setPlayer(player);
     player.setMediaItem(MediaItem.fromUri(mVideoURI));
     player.setPlayWhenReady(true);
     player.prepare();
   }

5. Add the following to set the Android onPause method, to pause the playback.

   JAVA

   @Override
   public void onPause()
   {
     super.onPause();
     if(mPlayerView != null)
     {
       mPlayerView.getPlayer().pause();
     }
   }

6. Add the following to set the Android onResume method, to start/resume playback.

   JAVA

   @Override
   public void onResume()
   {
     super.onResume();
     if(mPlayerView != null)
     {
       mPlayerView.getPlayer().play();
     }
   }

Add a PlayerView to the layout

1. Select app > src > main > res > layout and open the activity_main.xml file.

2. In the Text view window, create a androidx.media3.ui.PlayerView by replacing the contents with:

   XML

   <?xml version="1.0" encoding="utf-8"?>
   <FrameLayout
       xmlns:android="http://schemas.android.com/apk/res/android"
       xmlns:tools="http://schemas.android.com/tools"
       android:id="@+id/fyame"
       android:layout_width="match_parent"
       android:layout_height="match_parent"
       tools:context=".MainActivity">
   
       <androidx.media3.ui.PlayerView
         android:id="@+id/media3_playerView"
         android:layout_width="match_parent"
         android:layout_height="match_parent"
         android:layout_centerInParent="true"/>
   </FrameLayout>

Next step: you should now be able to run the app in clear playback mode.

Running the application

1. Connect an Android device via USB.

   This device must be running Android 5.0 (Lollipop) or later with USB debugging enabled. If USB debugging is not possible, the device may support debugging over WiFi; see https://developer.android.com/studio/command-line/adb#wireless/for details.

2. In Android Studio, select Run > Run 'app' or click the Run button. At the Select Deployment Target window, click OK.

3. The build commences, and on successful completion, the stream should play on the device.

If the build fails, see the next section

Debugging

Using Android Studio debugger

With the sdk-integration.aar, you can use breakpoints and view variable values in Android Studio debugger. You cannot place breakpoints within the library code itself.

Logging levels

The code within the SDK outputs text logs that can be viewed through the logcat window of Android Studio or using the logcat ADB command line. You can control the verbosity of most of the SDK log outputs through the NagraLog.setLogLevel(int logLevel) static method. The available levels are:

• LOG_LEVEL_INFO (1)

• LOG_LEVEL_DEBUG (2)

• LOG_LEVEL_VERBOSE (3)

For example, NagraLog.setLogLevel(NagraLog.LOG_LEVEL_INFO); will only enable LOG_LEVEL_INFO messages but not LOG_LEVEL_DEBUG or LOG_LEVEL_VERBOSE.

The default debug levels set are LOG_LEVEL_INFO for the production.aar, and LOG_LEVEL_VERBOSE for the sdk-integration.aar.

Capturing the logs

You can capture the output logs into a log file for later analysis. Using the Android Debug Bridge (ADB) and its internal logcat command, capture the records into a file from the terminal's command-line (cmd in Windows, Terminal on a Mac). When raising a ticket with NAGRA, you may be requested to provide a log capture. In such cases you would be asked to:

• Capture logs from before the application is launched until it is terminated.

• Have log verbosity set to LOG_LEVEL_VERBOSE (3)

• Configure the log capture to include timestamps; for example:

  BASH

  adb -d logcat -v threadtime > \path\to\logfile.log

Adding Player features

Having created your app with basic (clear) playback, you can now add the required features to it.

Encrypted playback

• Media3 NAGRA PRM Extension: Playing NAGRA PRM protected content with the Connect MediaDrm plugin

• Media3 NAGRA PRM Extension: Playing NAGRA Connect DRM protected content from device local storage with the Connect MediaDrm plugin

Building the production version

When code development is complete, create the production version for final testing and submission to the Play Store.

1. Unzip the sdk-production.aar file, and as with the sdk-production.aar file, rename it otvsdk.aar.

2. Replace the existing (integration) otvsdk.aar file with the production version above.

3. Build and run the application as before.

Debugging will not be available for the production version.