Android SDK 3.x to Gen 4 Migration Guide

This page details the changes required to migrate from the NMP Android Native SDK or the Android NexStreaming SDK to the OpenTV Player Android SDK based on OpenTV Player (Gen 4). Also, some modern devices may have problems decoding particular streams. In such cases, forcing software decoding at the expense of a higher CPU usage may be a solution.

OpenTV Player is also referred to as the NAGRA Media Player or NMP

New features

Device calibration

OpenTV Player currently uses software decoding, and to ensure a smooth playback user experience on all devices, the bitrate can be dynamically controlled using device calibration.

The default configuration file (profiles.json) should be packaged within the application's res/raw folder. However, you can overwrite it using the following API:

CODE

  // nagra.nmp.sdk.calibration
  DeviceCalibration.setConfiguration(String jsonData);

Device bitrate calibration/configuration is applied by default. However, you can use the following API to deactivate it:

CODE

  /**
   * Enables device calibration.
   *
   * Allows the device to limit the bitrate at which it consumes
   * content to improve playback performance.
   *
   * @note Calibration is enabled by default
   */
   DeviceCalibration.enable();

  /**
   * Disables device calibration.
   *
   * Remove any limitation on device content consumption.
   *
   * @note Calibration is enabled by default
   */
   DeviceCalibration.disable();

  Changes

Initialisation

For the OpenTV Player Android SDK based on OpenTV Player, the following code shows how to load the SDK and should be implemented within the application entry point activity onCreate() method:

CODE

    /**
     * Class to load the NAGRA Player SDK
     */
    NMPSDK.load(getApplicationContext());

If you are migrating from the NMP SDK for Android based on the NexStreaming player, the following initialisation call is no longer necessary:

CODE

public void init(Context context, String strRenderMode, int logLevel, int colorDepth);

If you are migrating from the NMP SDK for Android based on the Native player, the following class has been removed and no longer needs to be used:

CODE

public class   NMPSDKManager

From OpenTV Player for Android SDK version 4.8.0 onwards, all player-related .so files are packaged inside the nmpsdk.jar file. You must delete all old versions of the player-related *.so files from the integration application when migrating to SDK version 4.8.0 or later.

Performance-based bitrate adaptation

To ensure a smooth playback user experience on all devices and less impact from device background applications and services, OpenTV Player provides a feature called "Performance-based bitrate adaptation" that adapts the playing video bitrate based on dropped video frames in a certain period. This feature is disabled by default. To enable the feature, use the following code:

CODE

   // nagra.nmp.sdk.NMPVideoView
   NMPVideoView.setTrackDown(boolean enabled);

If the current playing bitrate is too high for a lower-powered device, frames might be dropped during playback. To adjust the threshold of how many frames are skipped before the player steps down to the next available lower bitrate, you can use the following API:

CODE

  // nagra.nmp.sdk.NMPVideoView
  NMPVideoView.setTrackDownThreshold(float ratio);

For example, if the expected frames per second of the playing video is 25 fps and five frames were skipped, a threshold ratio of >=0.20 triggers performance-based bitrate adaptation.

Watch content

NMPMediaPlayer

This is no longer a public class – it cannot be used to watch content directly. Integrators must use NMPVideoView to watch content.

However, some information still requires a reference from NMPMediaPlayer:

Static events and error constants.
Additional interfaces for the listener.

NMPVideoView

This no longer extends android.widget.VideoView – it now extends android.widget.RelativeLayout.

Tracks

With the removal of NMPMediaPlayer, some new methods have been added to NMPVideoView, among which the following methods control track access:

CODE

NMPTrackInfo[]     getNMPTrackInfo ();
void               selectTrack (int index);
void               deselectTrack (int index);

All track-related operations should be performed using these methods. In particular, CC608 and CC708 tracks are now displayed as tracks and are selectable like a standard audio track instead of using dedicated methods. Also, the NMPTrackInfo class is now directly part of the nagra.nmp.sdk package.

Program date and time

The program date and time accessor have been simplified by returning a standard Date object and can now be queried using the following method:

CODE

Date getCurrentDate();

The notification linked to the program date and time changes has also been removed. All information of that kind is now refactored as part of the standard OnInfoListener.

CODE

void setOnInfoListener (OnInfoListener listener);
boolean onInfo(MediaPlayer mp, int what, int extra):
Using what as NMPMediaPlayer.MEDIA_INFO_METADATA_UPDATE, and extra as NMPMediaPlayer.MEDIA_INFO_METADATA_EXTRA_CURRENT_DATE.

If you are migrating from the NMP SDK for Android based on the NexStreaming player, the following class and method have been removed and no longer need to be used:

CODE

public class NMPMediaPlayer.ProgramTime
public int getProgramTime (NMPMediaPlayer.ProgramTime tProgramTime);

Timed metadata

The timed metadata interface has been revisited to align with the platform API. The following classes must not be used to retrieve timed metadata associated with a content:

CODE

public static interface NMPMediaPlayer
.OnNMPTimedMetadataAvailableListener
public class NMPTimedMetaData

The following classes are therefore no longer available:

CODE

public static interface NMPMediaPlayer.OnTimedMetaRenderRenderListener
public class NMPID3TagInformation
public class NMPID3TagText

Removed APIs

The following APIs have been removed from NMPVideoView of the OpenTV Player SDK:

CODE

public String getContentID() ;
public int    getAudioAverageBitrate();
public int    getCurrentPlaybackBandwidth();
public int    getProgramTime (NMPMediaPlayer.ProgramTime tProgramTime);
public int    getVideoAverageBitrate() ;
public int    resolveAdjustedSize(int desiredSize, int measureSpec);
public int    setCC608Channel(int nChannel);
public int    setCC708Service(int serviceNo);
public void   enableWebVTT(boolean enable);
public void   initialize(FrameLayout layout);
public void   initialize(String strRenderMode, int logLevel);
public void   release();
public void   setCCBackgroundColor(NMPClosedCaption.CaptionColor bgColor);
public void   setCCBackgroundOpacity(int bgOpacity);
public void   setCCCharacterColor(NMPClosedCaption.CaptionColor characterColor);
public void   setCCCharacterFont(CaptionFont[] characterFonts);
public void   setCCCharacterOpacity(int characterOpacity);
public void   setCCCharacterSize(float characterSize);
public void   setCCEdgeColor(NMPClosedCaption.CaptionColor edgeColor);
public void   setCCEdgeType(NMPVideoView.CCEdgeAttribute edgeType);
public void   setCCWindowColor(NMPClosedCaption.CaptionColor windowColor);
public void   setCCWindowOpacity(int opacity);
public void   setKeyFormat(String keyFormat);
public void   setOnPlaybackBandwidthChangedListener(OnPlaybackBandwidthChangedListener listener);
public void   setOnProgramTimeListener (NMPMediaPlayer.OnProgramTimeListener l);
public void   setOnTimedMetaRenderRenderListener (NMPMediaPlayer.OnTimedMetaRenderRenderListener l);
public void   setWebVTTTextSize(float size);
public void   setWebVTTTextSizeRate(int sizeRate);
public void   suspend();

Specific changes for NMP Android Native SDK

Removed classes

The following classes have been removed:

CODE

public interface NMPMediaPlayer.IGLRendererListener
public interface NMPMediaPlayer.OnDiscontinuityExistListener
public interface NMPMediaPlayer.OnPlaybackBandwidthChangedListener
public interface NMPMediaPlayer.OnProgramTimeListener
public interface NMPMediaPlayer.OnTextRenderInitListener
public interface NMPMediaPlayer.OnTextRenderRenderListener
public interface NMPMediaPlayer.OnTimedMetaRenderRenderListener
public interface NMPMediaPlayer.OnVideoRenderCreateListener
public interface NMPMediaPlayer.OnVideoRenderDeleteListener
public interface NMPMediaPlayer.OnVideoRenderPreparedListener
public interface NMPMediaPlayer.OnVideoRenderRenderListener

Package name change

The Download to Go module's package name has changed from nagra.android.sdk.download to nagra.nmp.sdk.download.

Specific changes for Android NexStreaming SDK

Device information

The OpenTV Player now offers a new package called nagra.nmp.sdk.info, which contains, among other things, device and secure player static information via the DeviceInformation and SecurePlayer classes.

Removed class

The NMPSDKSettings class has been removed.

Package name change

The package name has changed from nagra.android.sdk. to nagra.nmp.sdk.