Monitor Android MediaPlayer

This documents integration instructions for Android's MediaPlayer class. This integration supports Android 4.2 (API level 17) and newer, though older versions of Android have spotty support for streaming protocols such as HLS and Dash.

The Mux integration with MediaPlayer is built on top of Mux's core Java SDK, and the full code can be seen here: muxinc/mux-stats-sdk-mediaplayer.

Features

The following data can be collected by the Mux Data SDK when you use the Android Media Player SDK, as described below.

Supported Features:

• Engagement metrics
• Quality of Experience Metrics
• Available for deployment from a package manager

Video Quality metrics are not available.

1Install the Mux Data SDK

The easiest way to get the AAR is to download the latest version from: muxinc/mux-stats-sdk-mediaplayer releases.

If you would prefer to build it yourself, first clone the repo. Then, you can do one of the following:

1. Open the project in Android Studio and build the release variant of the MuxMediaPlayer module. You can then Find the AAR in mux-stats-sdk-mediaplayer/MuxMediaPlayer/build/outputs/aar/MuxMediaPlayer-release.aar
2. Build the AAR directly:

./gradlew :MuxMediaPlayer:assembleRelease

We recommend using Android Studio's new module tool which can be accessed via File > New > New Module.... Select the Import .JAR/.AAR Package and then select the mux.aar that you downloaded or built. This should correctly configure the IDE as well as modify your build configuration (Gradle/Maven).

For an example integration, you can see the demo application within this repo which integrates Mux into the MediaPlayer demo application.

2Initialize the monitor with your MediaPlayer instance

Get your ENV_KEY from the Mux environments dashboard.

First, create the CustomerPlayerData and CustomerVideoData objects as appropriate for your current playback, and be sure to set your ENV_KEY.

import com.mux.stats.core.models.CustomerPlayerData;
import com.mux.stats.core.models.CustomerVideoData;
// ...
CustomerPlayerData customerPlayerData = new CustomerPlayerData();
customerPlayerData.setEnvironmentKey("ENV_KEY");
CustomerVideoData customerVideoData = new CustomerVideoData();
customerVideoData.setVideoTitle("My great video");

Next, Create the MuxStatsMediaPlayer object by passing your Android Context (typically your Activity), the MediaPlayer instance, a player name, and the customer data objects.

import com.mux.stats.sdk.muxstats.mediaplayer.MuxStatsMediaPlayer;
...
muxStatsMediaPlayer = new MuxStatsMediaPlayer(this, player, "demo-player", customerPlayerData, customerVideoData);

In order to correctly monitor if the player is full-screen, provide the screen size to the MuxStatsMediaPlayer instance.

Point size = new Point();
getWindowManager().getDefaultDisplay().getSize(size);
muxStatsMediaPlayer.setScreenSize(size.x, size.y);

In order to determine a number of viewer context values as well as track the size of the video player, set the player view.

muxStatsMediaPlayer.setPlayerView(playerView);

To allow MuxStatsMediaPlayer to listen for various MediaPlayer events, add it as a listener. MediaPlayer only allows single listeners, so if your activity or application also needs to listen to these events, use the helper methods to wrap your listener implementation with MuxStatsMediaPlayer's listener implementation.

player.setOnCompletionListener(muxStatsMediaPlayer.getOnCompletionListener(myCompletionListener));
player.setOnErrorListener(muxStatsMediaPlayer.getOnErrorListener(myErrorListener));
player.setOnPreparedListener(muxStatsMediaPlayer.getOnPreparedListener(this));
player.setOnInfoListener(muxStatsMediaPlayer.getOnInfoListener(null));  // No wrapped listener.
player.setOnSeekCompleteListener(muxStatsMediaPlayer.getOnSeekCompleteListener(null));  // No wrapped listener.
player.setOnVideoSizeChangedListener(muxStatsMediaPlayer.getOnVideoSizeChangedListener(myVideoSizeChangedListener));

Finally, when you are destroying the player, call the MuxStatsMediaPlayer.release() method.

muxStatsMediaPlayer.release()

3Set up required events

MediaPlayer does not provide listener callbacks for all necessary events, so you must add explicit calls into MuxStatsMediaPlayer at the same time that certain MediaPlayer methods are invoked:

• start: view docs
• pause: view docs
• seekTo: view docs

For example, in the demo, a MediaController view is used to control the MediaPlayer instance, and the appropriate MuxStatsMediaPlayer methods are invoked in the MediaPlayerControl implementation used to link the two instances.

private class MediaPlayerControl implements MediaController.MediaPlayerControl,
        MediaPlayer.OnBufferingUpdateListener {
    @Override
    public void start() {
        if (player != null) {
            player.start();
            muxStats.play();
        }
    }

    @Override
    public void pause() {
        if (player != null) {
            player.pause();
            muxStats.pause();
        }
    }

    @Override
    public void seekTo(int pos) {
        if (player != null) {
            player.seekTo(pos);
            muxStats.seeking();
        }
    }
}

After you've integrated, start playing a video in your player. A few minutes after you stop watching, you'll see the results in your Mux data dashboard. Login to the dashboard and find the environment that corresponds to your env_key and look for video views.

4Make your data actionable

In the MediaPlayer SDK, options are provided via the CustomerPlayerData and CustomerVideoData objects.

All metadata details except for envKey are optional, however you'll be able to compare and see more interesting results as you include more details. This gives you more metrics and metadata about video streaming, and allows you to search and filter on important fields like the player version, CDN, and video title.

For more information, see the Metadata Guide.

5Advanced options

Changing the video

There are two cases where the underlying tracking of the video view need to be reset. First, when you load a new source URL into an existing player, and second when the program within a singular stream changes (such as a program within a live stream).

Note: You do not need to change the video info when changing to a different source of the same video content (e.g. different resolution or video format).

New Source

When you change to a new video (in the same player) you need to update the information that Mux knows about the current video. Examples of when this is needed are:

• The player advances to the next video in a playlist
• The user selects a different video to play

This is done by calling muxStatsMediaPlayer.videoChange(CustomerVideoData) which will remove all previous video data and reset all metrics for the video view. See Metadata for the list of video details you can provide. You can include any metadata when changing the video but you should only need to update the values that start with video.

It's best to change the video info immediately after telling the player which new source to play.

New Program (in single stream)

In some cases, you may have the program change within a stream, and you may want to track each program as a view on its own. An example of this is a live stream that streams multiple programs back to back, with no interruptions.

In this case, call muxStatsMediaPlayer.programChange(CustomerVideoData). This will remove all previous video data and reset all metrics for the video view, creating a new video view. See Metadata for the list of video details you can provide. You can include any metadata when changing the video but you should only need to update the values that start with video.

Error tracking

By default, Mux's integration with MediaPlayer automatically tracks fatal errors as thrown by MediaPlayer. In some applications, however, you may want to disable this and track errors on your own, especially if you have retry logic in your application to try to recover from errors that MediaPlayer encounters.

In this case, there are two things that you need to do:

1. Turn off the automatic error tracking. To do this, call muxStatsExoPlayer.setAutomaticErrorTracking(false)
2. When your application encounters a fatal error that you cannot recover from, call muxStatsExoPlayer.error(MuxErrorException e), including a message and a code.

The following is an example of firing a custom error.

// Error code: integer value for the generic type of error that
// occurred.
// Error message: String providing more information on the error
// that occurred.
// For an example, the HTML5 video element uses the
// following: https://developer.mozilla.org/en-US/docs/Web/API/MediaError
// for codes and messages. Feel free to use your own codes and messages
int errorCode = 1;
String errorMessage = "A fatal error was encountered during playback";
MuxErrorException error = new MuxErrorException(errorCode, errorMessage);
muxStatsMediaPlayer.error(error);

It is important that you only trigger an error when the playback has to be abandoned or aborted in an unexpected manner, as Mux tracks fatal playback errors only.