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 supporting player features like caching, 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, configure Mux Player for your specific app and media, 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:1.0.0")

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 Video's features, and you can make additional config changes using our Builder. Almost all of our default 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(true) // Optional. 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

Protecting your content

Mux Video offers options for securing your content from unauthorized playing or recording. For more information, see below

Control Your Usage and Quality

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. Caching can reduce overall data usage and costs by storing some streamed video locally in a private directory on the device. This way content doesn't need to be downloaded again if the user watches the content over, when playback loops, or during seeking. Mux Player's caching is automatic when enabled, and we manage the cache files for you.

If you are interested in Mux Player's caching features, you can enable them when you build your MuxPlayer.

val player: MuxPlayer = MuxPlayer.Builder(context)
  // disabled by default
  .enableSmartCache(true)
  .build()

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

Guarantee 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.

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

Secure your playback experience

Depending on the needs of your business and your users, you may need to secure your videos against unauthorized copying or viewing. Mux Video offers options for securing your playback experience. The right option for your app depends on your own use case. Your best option, if any, is a trade-off between security, complexity, and loading time for the end user.

Signed Playback URLs

Mux Player supports playing Mux Video assets with signed playback. Signed playback uses a JSON web token (JWT) signed on your application server, created using a key identifier created using our APIs. For more information about how to set up signed playback, check out our secure video playback guide.

For this guide, we'll focus on what to do on the client, once you have the JWT from your app's backend server. To play the asset securely you can supply your JWT to MediaItems.fromMuxPlaybackId or MediaItems.builderFromMuxPlaybackId. The resulting MediaItem will be configured to play the asset securely using your token.

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
}

Digital Rights Management (DRM)

Mux Player for Android can be configured to protect videos from unauthorized use via Widevine DRM. Support for DRM is automatically enabled in the player. As long as you have both a signed playback token (see above) and a DRM token, your DRM-protected asset can be played using Mux Player. The process of setting up DRM is somewhat complex, and is detailed here in our DRM Guide. This guide will focus on what to do once you have obtained a Playback Token and DRM Token from your application server.

1. Setting up DRM for an asset

To use DRM playback for your asset, you'll need to set up a DRM configuration and DRM-enabled playback ID. The process for doing this is the same regardless of your player, and you can read more about it in our DRM Guide. Once you have an environment and asset set up with DRM, you can use your that asset's DRM Token, Playback Token, and Playback ID with Mux Player to do DRM playback transparently.

2. Playing a DRM-protected asset

To play your DRM-protected asset, simply provide the Playback Token and DRM Token you generated in the last step. You can provide them as parameters to MediaItems.fromMuxPlaybackId(). No other configuration is required in order to use DRM with Mux Player.

private fun playSomething(myPlaybackId: String, myPlaybackToken: String, myDrmToken: String, context: Context) {
  val player = createPlayer(context)
  val mediaItem = MediaItems.builderFromMuxPlaybackId(
    playbackId,
    playbackToken = myPlaybackToken,
    drmToken = myDrmToken,
  )
    .setMediaMetadata(
      MediaMetadata.Builder()
        .setTitle("DRM playback Example")
        .build()
    )
    .build()
  player.setMediaItem(mediaItem)
  // .. Then prepare and play your media as normal
}

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