Upload video directly from an Android app

Direct Uploads allow you to provide an authenticated upload URL to your client applications so content can be uploaded directly to Mux without needing any intermediate steps. You still get to control who gets an authenticated URL, how long it's viable, and, of course, the Asset settings used when the upload is complete.

The Android Upload SDK allows a client application to upload video files from an Android device to Mux Video. The upload can be paused before completion and resume where it left off, even after process death.

Let's start by uploading a video directly into Mux from an Android application. The code from these examples can be found in our upload example app

Gradle setup

To integrate the Mux Upload SDK into your Android app, you first have to add it to your project, then create a MuxUpload object using an upload URL your app can fetch from a trusted server. Once you create the MuxUpload, you can start it with start().

A working example can be found alongside our source code here.

Add Mux's maven repository to your project

Add our maven repository to your project's repositories block. Depending on your setup, you may need to do this either the settings.gradle under dependencyResolutionManagement or your project's build.gradle.

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

Add the Upload SDK to your app's dependencies

Add the upload SDK to your app's dependencies block in its build.gradle file.

// in your app's dependencies
implementation("com.mux.video:upload:0.4.1")

Upload a video

In order to securely upload a video, you will need to create a PUT URL for your video. Once you have created the upload URL, return it to the Android client then use the MuxUpload class to upload the file to Mux.

Getting an Upload URL to Mux Video

In order to upload a new video to Mux, you must first create a new Direct Upload to receive the file. The Direct Upload will contain a resumable PUT url for your Android client to use while uploading the video file.

You should not create your Direct Uploads directly from your app. Instead, refer to the Direct Upload Guide to create them securely on your server backend.

Creating and starting your MuxUpload

To perform the upload from your Android app, you can use the MuxUpload class. At the simplest, you need to build your MuxUpload via its Builder, then add your listeners and start() the upload.

/**
 * @param myUploadUri PUT URL fetched from a trusted environment
 * @param myVideoFile File where the local video is stored. The app must have permission to read this file
*/
fun beginUpload(myUploadUrl: Uri, myVideoFile: File) {
  val upl = MuxUpload.Builder(myUploadUrl, myVideoFile).build()
  upl.addProgressListener { innerUploads.postValue(uploadList) }
  upl.addResultListener {
    if (it.isSuccess) {
      notifyUploadSuccess()
    } else {
      notifyUploadFail()
    }
  }
  upl.start()
}

Resume uploads after network loss or process death

The upload SDK will keep track of uploads that are in progress. When your app starts, you can restart them using MuxUploadManager. For more information on managing, pausing, and resuming uploads, see the next section of this guide.

// You can do this anywhere, but it's really effective to do early in app startup
MuxUploadManager.resumeAllCachedJobs()

Upload from a coroutine

If you're using Kotlin coroutines, you don't have to rely on the listener API to receive notifications when an upload succeeds or fails. If you prefer, you can use awaitSuccess in your coroutine.

suspend fun uploadFromCoroutine(videoFile: File): Result<UploadStatus> {
  val uploadUrl = withContext(Dispatchers.IO) { 
    getUploadUrl()  // via call to your backend server, see the guide above
  } 
  val upload = MuxUpload.Builder(uploadUrl, videoFile).build()
  return upload.awaitSuccess()
}

Resuming and managing Uploads

MuxUploads are managed globally while they are in-progress. Your upload can safely continue while your user does other things in your app. Optionally, you can listen for progress updates for these uploads in, eg, a foreground Service with a system notification, or a progress view in another Fragment.

Find Uploads already in progress

MuxUploads are managed internally by the SDK, and you don't have to hold onto a reference to your MuxUpload in order for the upload to complete. You can get a MuxUpload object for any file currently uploading using MuxUploadManager

This example listens for progress updates. You can also pause() or cancel() your uploads this way if desired.

fun listenToUploadInProgress(videoFile: File) {
  val upload = MuxUploadManager.findUploadByFile(videoFile)
  upload?.setProgressListener { handleProgress(it) }
}

Advanced

The Upload SDK is capable of processing input videos in order to optimize them for use with Mux Video. This behavior can be disabled if it isn't desired, although this may still result in pre-processing on Mux's servers. We don't recommend you change any of these settings unless you are experiencing issues.

fun beginUpload(myUploadUrl: Uri, myVideoFile: File) {
  val upl = MuxUpload.Builder(myUploadUrl, myVideoFile)
    .standarizationEnabled(false) // disable input processing
    .build()
  // add listeners etc
  upl.start()
}

Release notes

Current release

0.5.0

New:

• Audio transcoding

Improvements:

• Improved performance reporting

Previous releases

0.4.2

New

• feat: Add UploadResult class for java users to interpret Result

Fixes

• Fix: Some methods on MuxUpload.Builder don't return Builder
• Fix: the application context shouldn't be visible
• Fix: Transcoding errors handled incorrectly

0.4.1

New

• feat: Add API for listening to and retrieving the status of an upload
• feat: Add Input Standardization, to process videos device-side

Fixes

• fix: Metrics events not properly redirected

Known Issues

• There's no notification/callback for the result of input standardization

0.4.0

Improvements

• doc: Finish out the public KDoc
• doc: Improve KDocs and add logo
• nfc: Hide some internal classes from java. This should not affect anyone using the SDK

Fixes

• fix: pausing uploads shouldn't create errors

0.3.1

Improvements

• fix: Restarts broken due to invalid progress data

0.3.0

Breaking

• breaking: Remove extraneous MIME type and Retry Time Builder fields. Configuring these did nothing

Updates

• update: Add the ability to resume all failed or paused uploads

Improvements

• Greatly improved the example app

0.2.0

Improvements

• fix: Hide some constructors to prevent unintended use by java callers
• feat: Add Performance Metrics Tracking

0.1.0

🥳 First beta release of the Mux Android SDK

Features

• Upload multiple files at once
• Pause and resume uploads, even after process death
• Observe upload progress from anywhere in your app without extra code