This guide walks through integration with Mux's Player SDK for Android, which is built on media3
Install the Mux Player SDK
Play a Mux Asset
Control Your Usage and Quality
Add or customize Mux Data metadata
Secure your playback experience
Advanced Features
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.
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 our library to the dependencies block for your app.
implementation("com.mux.player:android:1.0.0")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()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 = trueMux Video offers options for securing your content from unauthorized playing or recording. For more information, see below
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()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 wouldSome 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 wouldFor more information about controlling your data and platform usage, please see our guide on controlling playback resolution.
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.
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.
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()
}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.
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
}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.
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.
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
}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()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 wouldOrdinarily, 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()
}Instant clips are an alternative to our long-standing asset-based clipping feature. Requesting instant clips using relative time is now available for use with all video on-demand (VOD) assets.
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.