This guide walks through integration with Mux's Player SDK for Android, which is built on media3
Beta
This SDK is currently in beta. If you encounter any issues please let us know by filing an issue on Github.
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.
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 {} blockmaven { 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:0.3.1")
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()
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 ExoPlayerplayer.setMediaItem(mediaItem)player.prepare()player.playWhenReady = true
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}
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
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.
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()}
Beta feature
Mux Player's smart caching feature is still in-development. It is expected to work well with short-form content being served from Mux Video, but may not perform optimally in all situations. Smart caching is disabled by default, and can be enabled if you wish to try it out.
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()
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
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()}