Mux Player for Android

The Mux Player SDK is a thin wrapper on top of Google's media3 player SDK with convenient tools for Mux Video users. This SDK is not required to use Mux Video, but it can help you do things like controlling your data and delivery usage, playing Mux assets by ID, automatically leveraging advanced player features like CMCD, and transparently tracking performance and engagement with Mux Data

This guide will help you install the Mux Video SDK in your app, use it to play a Mux Video asset, restrict your usage based on target resolution, and show you how to handle less-common scenarios like using Mux Video's custom domains.

1Install the Mux Player SDK

Add our repository to your Gradle project

Add Mux's maven repository to your gradle files. Newer projects require declaring this in settings.gradle, and older projects require it to be set in the project-level build.gradle.

// in a repositories {} block
maven {
  url = uri("https://muxinc.jfrog.io/artifactory/default-maven-release-local")
}

Add the dependency to your app

Add our library to the dependencies block for your app.

implementation("com.mux.player:android:0.3.1")

2Play a Mux Asset

Create a MuxPlayer

To use the SDK, you must create a MuxPlayer object using its Builder. The basic configuration will enable all of Mux's extra features, and you can make additional config changes using our Builder. Almost all of our defaults config options are the same as ExoPlayer's. We only change things about the default configuration when we need to in order to support a Mux Player feature.

val out: MuxPlayer = MuxPlayer.Builder(context = this)
  .enableLogcat() // Only applies to Mux. Media3 logging is not touched
  .applyExoConfig {
    // Call ExoPlayer.Builder methods here (but not build()!)
    setHandleAudioBecomingNoisy(true)
  }
.build()

Play a Mux Video asset

To play a Mux Video asset using this SDK, you can use our MediaItems API to create new instances of media3's MediaItem or MediaItem.Builder. For the basic example, we'll leave everything default and play an asset you've already uploaded to Mux Video

// Use the MediaItems class instead of MediaItem.Builder()
val mediaItem = MediaItems.builderFromMuxPlaybackId("YOUR PLAYBACK ID")
  // It's just a MediaItem from here, so you can configure it however you like
  .setMediaMetadata(
    MediaMetadata.Builder()
      .setTitle("Hello from Mux Player on Android!")
      .build()
  )
  .build()
// From here, everything is exactly the same as ExoPlayer
player.setMediaItem(mediaItem)
player.prepare()
player.playWhenReady = true

Playback with Access Control

This SDK supports playing Mux Video assets with secure access control. Once you've retrieved your JWT, you can supply it to MediaItems when making a new MediaItem.

private fun playSomething(jwt: String, context: Context) {
  val player = createPlayer(context)
  val mediaItem = MediaItems.builderFromMuxPlaybackId(
    PlaybackIds.TEARS_OF_STEEL,
    playbackToken = jwt,
  )
    .setMediaMetadata(
      MediaMetadata.Builder()
        .setTitle("Private Playback ID Example")
        .build()
    )
    .build()
  player.setMediaItem(mediaItem)
  // .. Then prepare and play your media as normal
}

3Control Your Usage and Quality

Limit data and delivery usage

Depending on your use case and app, you may need to control your either Mux Video usage or your app's data bandwidth usage. Doing this can allow you to save costs and minimize playback interruptions for users on slower devices or data plans. Mux provides some tools to manage costs and resource usage by limiting the maximum resolution your app can stream from Mux Video. To take advantage of this feature, you can supply a PlaybackResolution to our MediaItems class.

val mediaItem = MediaItems.builderFromMuxPlaybackId(
  "YOUR PLAYBACK ID",
  maxResolution = PlaybackResolution.FHD_1080, // limit playback resolution to 1080p
  )
  // .. configure your MediaItem further if required
  .build()
// .. Add the MediaItem to your MuxPlayer like you normally would

Require a minimum resolution

Some use cases require a minimum playback resolution. Applications like screen-sharing for instance, may wish to preserve a certain level of visual quality even if play has to be interrupted to buffer more data. Apps that need their video playback to always be above a certain resolution, regardless of network conditions, can request a minium resolution.

val mediaItem = MediaItems.builderFromMuxPlaybackId(
  "YOUR PLAYBACK ID",
  minResolution = PlaybackResolution.HD_720,
  )
  // .. configure your MediaItem further if required
  .build()
// .. Add the MediaItem to your MuxPlayer like you normally would

For more information about controlling your data and platform usage, please see our guide on controlling playback resolution.

4Add or customize Mux Data metadata

The Mux Player SDK transparently integrates with Mux Data in order to monitor for issues and track engagement with your content. To verify this is working, you can simply play the video in your app, and wait for your session to appear on the Mux Data dashboard. Your session should appear in your Mux Data environment automatically in the same environment as your video asset.

Automatically-Detected Metadata

Mux will automatically collect information about your stream, playback environment, and current playback session ("view") to send to Mux Data. Examples of the kind of information collected are Mux Asset and Playback IDs, player and stream resolution, the start and end times of the view, and some basic information about the end users device like OS and model number.

Customize metadata about your player, viewer, or playback session

The SDK can automatically detect a lot of information about the media you're playing, but you can customize this information if you need to, via the CustomerData class. Anything you specify this way will override metadata values that would ordinarily be detected automatically.

You can initialize your player with whatever custom metadata you like, and you can also update that metadata at any time.

private fun createPlayer(context: Context): MuxPlayer {
  return MuxPlayer.Builder(context)
    .addMonitoringData(
      CustomerData().apply {
        customerViewData = CustomerViewData().apply {
          viewSessionId = UUID.generateUUID()
        }
        customerVideoData = CustomerVideoData().apply {
          videoSeries = "My Series"
          videoId = "abc1234zyxw"
        }
        customData = CustomData().apply { 
          customData1 = "my custom metadata field"
          customData2 = "another custom metadata field"
          customData10 = "up to 10 custom fields"
        }
      }
    )
    .build()
}

Advanced Features

Enable smart caching to improve experience and decrease usage

Mux Player can cache content as it is requested from Mux Video and store it for later requests. This caching is automatic, and we manage the cache content and cache files for you. To enable smart caching, all you need to do is set a parameter when you build your MuxPlayer.

val player: MuxPlayer = MuxPlayer.Builder(context)
  .enableSmartCache(true)
  .build()

Use a custom Mux Video domain

If you are using a Mux Video Custom Domain, you can specify the domain on a per-MediaItem basis. The URL of the stream will have the specified domain and the stream. subdomain

val mediaItem = MediaItems.builderFromMuxPlaybackId(
  "YOUR PLAYBACK ID",
  domain = "customdomain.com", // https://stream.customdomain.com/...
  )
  // .. configure your MediaItem further if required
  .build()
// .. Add the MediaItem to your MuxPlayer like you normally would

Use a specific Mux Data Environment Key

Ordinarily, Mux Data will record views and monitoring data in the same Environment as the Mux Video asset being played. If you are using a different Mux Data environment for some reason, you can specify another Mux Data Env Key for your player to use.

private fun createPlayer(context: Context): MuxPlayer {
  return MuxPlayer.Builder(context)
    .setMuxDataEnv("Another Mux Data Env Key") // replace with your other key  
    .build()
}