Mux

The Mux Developer Hub

Welcome to the Mux developer hub. You'll find comprehensive guides and documentation to help you start working with Mux as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started

Integration Guide: MediaPlayer

Mux Data is the best way to monitor video streaming performance.

Integration is easy - just initialize the Mux SDK, pass in some metadata, and you're up and running in minutes.

Getting Started

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: https://github.com/muxinc/mux-stats-sdk-mediaplayer.

1. Get the Mux Stats MediaPlayer AAR

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

If you would prefer to build it yourself, first clone the MediaPlayer 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

2. Import the Mux Stats MediaPlayer AAR

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.

3. Add the Mux Stats MediaPlayer monitor

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("EXAMPLE_ENV_KEY");
CustomerVideoData customerVideoData = new CustomerVideoData();
customerVideoData.setVideoTitle("The most epic video ever");

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()

4. Add additional MuxStatsMediaPlayer calls

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:

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();
        }
    }

5. Test it

After you've integrated, start playing a video in the player you've integrated with. Then for your viewing session (called a "video view") to show up in the Mux dashboard, you need to stop watching the video. In a few minutes you'll see the results in your Mux account. We'll also email you when the first video view has been recorded.

6. Add Metadata

Detailed Documentation

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.

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 secondly 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 muxStatsMediaPlayer.setAutomaticErrorTracking(false)

  2. When your application encounters a fatal error that you cannot recover from, call muxStatsMediaPlayer.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.

Release Notes

Current Release

v0.1.0

  • Initial integration with MediaPlayer

Previous Releases

N/A

Updated about a year ago

Integration Guide: MediaPlayer


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.