# Mux Player for Android
The Mux Player SDK for Android extends media3 to play Mux video in native Android apps. Use this guide to install the SDK, play an asset, and secure playback.
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](https://data.mux.com/)
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](/docs/guides/use-a-custom-domain-for-streaming).
## 1. Install 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`.
```gradle\_groovy
// in a repositories {} block
maven {
url 'https://muxinc.jfrog.io/artifactory/default-maven-release-local'
}
```
```gradle\_kts
// 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.
```gradle\_kts
implementation("com.mux.player:android:1.0.0")
```
```gradle\_groovy
implementation "com.mux.player:android:1.0.0"
```
## 2. Play 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.
```kotlin
val player: 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()
```
```java
MuxPlayer player = new MuxPlayer.Builder(context)
.enableLogcat(true) // Optional. Only applies to Mux. Media3 logging is not touched
.plusExoConfig((config) -> {
// Call ExoPlayer.Builder methods here (but not build()!)
config.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
```kotlin
// 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
```
```java
MediaMetadata metadata = new MediaMetadata.Builder()
.setTitle("Hello from Mux Player on Android")
.build();
// Use the MediaItems class instead of MediaItem.Builder()
MediaItem item = MediaItems.builderFromMuxPlaybackId("YOUR PLAYBACK ID")
// It's just a MediaItem from here, so you can configure it however you like
.setMediaMetadata(metadata)
.build();
// From here, everything is exactly the same as ExoPlayer
player.setMediaItem(item);
player.setPlayWhenReady(true);
player.prepare();
```
### Protecting your content
Mux Video offers options for securing your content from unauthorized playing or recording. For more information, [see below](/docs/guides/mux-player-android#secure-your-playback-experience)
## 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`.
```kotlin
val player: MuxPlayer = MuxPlayer.Builder(context)
// disabled by default
.enableSmartCache(true)
.build()
```
```java
MuxPlayer player = new 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.
```kotlin
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
```
```java
MediaItem mediaItem = MediaItems.builderFromMuxPlaybackId(
"YOUR PLAYBACK ID",
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.
```kotlin
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
```
```java
MediaItem mediaItem = MediaItems.builderFromMuxPlaybackId(
"YOUR PLAYBACK ID",
null, // null for default
/*minResolution =*/ PlaybackResolution.HD_720
)
// .. configure your MediaItem further if required
.build();
```
For more information about controlling your data and platform usage, please see our [guide](/docs/guides/control-playback-resolution) 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.
```kotlin
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()
}
```
```java
private MuxPlayer createPlayer(Context context) {
CustomerData customerData = new CustomerData();
CustomerVideoData videoData = new CustomerVideoData();
videoData.setVideoTitle("Lots of custom data");
videoData.setVideoSeries("my series");
videoData.setVideoId("my app's id for the media");
CustomData customData = new CustomData();
customData.setCustomData1("my custom data field");
customData.setCustomData2("another custom metadata field");
customData.setCustomData10("up to 10 custom fields");
customerData.setCustomerVideoData(videoData);
customerData.setCustomData(customData);
return new MuxPlayer.Builder(context)
.addMonitoringData(customerData)
.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](/docs/guides/secure-video-playback).
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.
```kotlin
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
}
```
```java
MuxPlayer player = createPlayer(context);
MediaItem mediaItem = MediaItems.builderFromMuxPlaybackId(
PlaybackIds.TEARS_OF_STEEL,
PlaybackResolution.QHD_1440,
PlaybackResolution.LD_540,
RenditionOrder.Descending,
/* domain = */ null, // null for default
// put your Signed Playback Token here
/*playbackToken = */ jwt
)
.setMediaMetadata(
new 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](/docs/guides/protect-videos-with-drm). 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](/docs/guides/protect-videos-with-drm). 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.
```kotlin
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
}
```
```java
MuxPlayer player = createPlayer(context);
MediaItem mediaItem = MediaItems.builderFromMuxPlaybackId(
PlaybackIds.TEARS_OF_STEEL,
PlaybackResolution.QHD_1440,
PlaybackResolution.LD_540,
RenditionOrder.Descending,
/* domain = */ null, // null for default
// put your Signed Playback Token here
/*playbackToken = */ jwt,
/*drmToken = */ drmToken,
)
.setMediaMetadata(
new MediaMetadata.Builder()
.setTitle("Private Playback ID Example")
.build()
)
.build();
player.setMediaItem(mediaItem);
// .. Then prepare and play your media as normal
```
## Download Mux Assets for offline playback
## Using `MuxDownloadManager` to download Mux Assets (including offline Widevine DRM)
Mux Player provides a simplified API for downloading Mux Assets for offline playback. The `MuxDownloadManager` class is a singleton that manages the download of Mux Assets and their associated metadata. It provides methods for starting, pausing, resuming, and canceling downloads, as well as querying the status of downloads.
Mux Player's offline downloads are built on top of Android's media3 `DownloadManager` and `DownloadService`, but provide a simplified API for downloading Mux Assets. The `MuxDownloadManager` handles the download of Mux Assets and their associated metadata, including Widevine DRM licenses. It also provides a simple way to query the status of downloads and to listen for download status changes.
If you already have your own download implementation, you can integrate a smaller set of APIs into that implementation in order to download DRM protected Mux Assets. See the section below on [Using your own DownloadManager and database for Mux Assets](#using-your-own-downloadmanager-and-database-for-mux-assets).
### Manifest Setup
In order to use the `MuxDownloadManager`, you need to add the following to your AndroidManifest.xml file:
```xml
```
### Starting new downloads
`MuxDownloadManager` downloads Mux Assets in the background using a `DownloadService`. To start a new download, you can call `MuxDownloadManager.startDownload()` with a MediaItem from Mux Player's `MediaItems` class. As such, you can customize things like clipping and resolution based on Mux's playback parameters.
```kotlin
val item = MediaItems.fromMuxPlaybackId(
"YOUR PLAYBACK ID",
// Optionally, add playback parameters
maxResolution = PlaybackResolution.FHD_1080,
assetStartTime = 30_000L, // start at 30 seconds
assetEndTime = 60_000L, // end at 60 seconds
)
MuxDownloadManager.startDownload(context, item)
```
### Listening for download status changes
`MuxDownloadManager` provides a way to listen for download status changes via the `MuxDownloadManager.DownloadStatusListener` interface. You can register a listener using `MuxDownloadManager.addDownloadStatusListener()` and unregister it using `MuxDownloadManager.removeDownloadStatusListener()`. The listener will be called whenever the status of a download changes, including when a download is completed, failed, or canceled.
```kotlin
MuxDownloadManager.addListener(app,
object : MuxDownloadManager.DownloadStatusListener {
override fun onDownloadChanged(download: MuxDownload, error: Throwable?) {
// Handle Download state changes here, for example, update your UI
}
override fun onDownloadRemoved(download: MuxDownload) {
// handle download removal here
}
override fun onWaitingForRequirementsChanged(waitingForRequirements: Boolean) {
// Downloads are stalled only because the DownloadManager's Requirements aren't met (by
// default, that means no network). A real app might surface this in its UI.
}
}
)
```
### Downloading DRM protected Mux Assets
You can download DRM protected Mux Assets using the same `MuxDownloadManager.startDownload()` method. You just need to provide a playback token and DRM token when creating the MediaItem. The `MuxDownloadManager` will handle the DRM license acquisition and storage for you.
If you are downloading DRM protected Mux Assets, please be aware that the DRM license will expire after a certain period of time, which you can control when you create your DRM token. For more info on offline DRM tokens, see the [DRM Guide](/docs/guides/protect-videos-with-drm#enable-offline-playback). If the DRM license expires, the downloaded asset will no longer be playable. As of v1.7.0 you can renew the license in place by calling `MuxDownloadManager.renewOfflineLicense(context, playbackId, drmToken, domain)` with a freshly minted DRM token, which avoids re-downloading the media. The device must be online to renew, so it is worth renewing opportunistically before the user next goes offline.
Renewal relies on data that Mux Player only began storing alongside the download in v1.7.0. Assets that were downloaded on v1.6.0 or earlier cannot be renewed, even after you upgrade the SDK — they have to be re-downloaded once with a new DRM token, after which they become renewable.
```kotlin
val item = MediaItems.fromMuxPlaybackId(
"YOUR PLAYBACK ID",
// Protected Mux Assets require a playback token and DRM token
playbackToken = "YOUR PLAYBACK TOKEN",
drmToken = "YOUR DRM TOKEN",
// Optionally, add playback parameters
maxResolution = PlaybackResolution.FHD_1080,
assetStartTime = 30_000L, // start at 30 seconds
assetEndTime = 60_000L, // end at 60 seconds
)
MuxDownloadManager.startDownload(context, item)
```
### Querying the download store
`MuxDownloadManager` provides a way to query the download store for the status of downloads. You can call `MuxDownloadManager.allDownloads()` to get a list of all downloads, or `MuxDownloadManager.getDownload()` to get a specific download by its ID.
The Kotlin API is a suspend function, so you can call it from a coroutine. The Java API returns a ListenableFuture, so you can use it with a callback or convert it to a CompletableFuture.
```kotlin
withContext(..) {
val downloads = MuxDownloadManager.getDownloads(context)
// Handle the list of downloads here
}
```
```java
ListenableFuture> future = MuxDownloadManager.allDownloadsFuture(context);
future.addListener(
{
try {
val downloads = future.get()
// Handle the list of downloads here
} catch (e: Exception) {
Log.e(TAG, "Failed to get downloads", e)
}
},
Executors.newSingleThreadExecutor()
)
```
### Playing downloaded Mux Assets
Playing downloaded assets using `Mux Player` is nearly the same as playing a regular Mux Asset. You can use `MediaItems` to create a `MediaItem` from a downloaded asset, and then set it on your `MuxPlayer`. The only difference is that you need to use the `MediaItems.fromDownloadedMuxAsset()` method instead of `MediaItems.fromMuxPlaybackId()`.
If the item is present on-disk then it will be played. If the media hasn't been downloaded yet, you'll get an error.
```kotlin
val mediaItem = MediaItems.forMuxDownload(playbackId = "YOUR PLAYBACK ID", title = "My Downloaded Asset")
muxPlayer.setMediaItem(mediaItem)
```
Downloaded content is not automatically monitored by Mux Data. To monitor playback of downloaded content with Mux Data, you must initialize the player with the same playback ID and playback options used to create the offline download. Monitoring may not be available if the device is offline and cannot reach Mux Data servers.
## Using your own DownloadManager and database for Mux Assets
If you have an offline-download implementation already, you can integrate Mux Player's DRM and offline-HLS support into your existing implementation.
Doing this requires using two custom Mux Player classes with your existing `DownloadManager`: `MuxOfflineCmafHlsMediaSource` and `MuxHlsDownloadCallback`. These classes will set up DRM and track selection for Mux Video assets.
```kotlin
// Here's the whole flow in one place, but you can break it up however you like in your app.
val drmProvider = MuxDrmSessionManagerProvider(DefaultHttpDataSource.Factory(context))
val mediaSource = MuxOfflineCmafHlsMediaSource.create(
dataSourceFactory = DefaultHttpDataSource.Factory(context), /*or any other DataSource.Factory you are using*/,
mediaItem = MediaItems.fromMuxPlaybackId(
"YOUR PLAYBACK ID",
// Add these for downloading protected Mux Assets (signed-playback or DRM)
playbackToken = "YOUR PLAYBACK TOKEN",
drmToken = "YOUR DRM TOKEN",
),
// If you're using DRM, you must provide a MuxDrmSessionManagerProvider, otherwise you can omit this parameter
drmSessionManagerProvider = drmProvider,
)
val downloadHelper = DownloadHelper.Factory()
.setRenderersFactory(renderersFactory)
.setTrackSelectionParameters(DownloadHelper.DEFAULT_TRACK_SELECTOR_PARAMETERS)
.create(mediaSource)
downloadHelper.prepare(MuxHlsDownloadCallback(
mediaSource = mediaSource,
drmProvider = drmProvider,
playbackId = "YOUR PLAYBACK ID",
drmToken = "YOUR DRM TOKEN",
ioExecutor = Executors.newSingleThreadExecutor(),
onReady = { downloadRequest ->
// Send this downloadRequest to your DownloadService to start the download
},
onError = {
// Handle preparation errors here. Errors can come from manifest-fetching, DRM license acquisition, or other issues.
}
))
```
## 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`.
```kotlin
val player: MuxPlayer = MuxPlayer.Builder(context)
.enableSmartCache(true)
.build()
```
## Use a custom Mux Video domain
If you are using a Mux Video [Custom Domain](/docs/guides/use-a-custom-domain-for-streaming), you can specify the domain on a per-`MediaItem` basis. The URL of the stream will have the specified domain and the `stream.` subdomain
```kotlin
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.
```kotlin
private fun createPlayer(context: Context): MuxPlayer {
return MuxPlayer.Builder(context)
.setMuxDataEnv("Another Mux Data Env Key") // replace with your other key
.build()
}
```
```java
MuxPlayer player = new MuxPlayer.Builder(context)
.setMuxDataEnv("Another Mux Data Env Key") // replace with your other key
.build()
```
## Instant Clipping
### Instant Clips
Instant clips are an alternative to our [long-standing asset-based clipping feature](/docs/guides/create-clips-from-your-videos). Requesting instant clips using relative time is now [available for use with all video on-demand (VOD) assets](https://www.mux.com/blog/instant-clipping-update).
Instant clipping allows you to request a stream whose start time is at some later point in the video, relative to the start time of the asset. Likewise you're able to request a stream that ends sooner than when the underlying asset completes. Instant clips do not incur the wait time or expense of a creating a new asset.
Unlike asset-based clipping, instant clipping is done by trimming your VOD assets HLS manifest. This means that instant clipping operates at the segment level of accuracy. You should expect that the content that you clip out may be several seconds longer than you’ve requested. We always make sure to include the timestamps that you request, but your content may start a few seconds earlier, and end a few seconds later.
Assets that originate from a livestream can also be converted into instant clips using program date time epochs. Support for these clips will be available in a future Mux Player Android release.