A Kotlin coroutine wrapper around Media3’s Transformer API

TransformerKt is a Kotlin coroutine wrapper library around media3.transformer:

Transformer is an API for editing media, including converting between formats (transcoding), applying changes like trimming a clip from a longer video, cropping a portion of the video frame, applying custom effects, and other editing operations

You can view the TransformerKt KDocs at docs.transformerkt.dev

• Using media3.transformer version 1.1.0-alpha01

Motivation

The media3.transformer API is Java based and therefore relies on callbacks to notify the caller of the result of an operation. This library wraps the API in a Kotlin coroutine based API to make it easier to use. It exposes the Transformer API as either a suspend function or a Flow.

This library also includes some helpful extension functions to make it easier to use the API. See Usage for more information.

Note: Due to the way Transformer works, the coroutines must be launched on the Dispatchers.Main thread, otherwise the API will throw an IllegalStateException. Since it relies on the current thread to contain a Looper. While it is launched on the main-thread, Transformer delegates all the heavy lifting off of the main thread. See the docs for more information.

Getting Started

First you need to add jitpack to either your root level build.gradle.kts or your settings.gradle.kts file:

In build.gradle.kts:

allprojects {
    repositories {
        maven { url = uri("https://jitpack.io") }
    }
}

Or settings.gradle.kts:

dependencyResolutionManagement {
    repositories {
        maven { url = uri("https://jitpack.io") }
    }
}

Then add the dependency to your app level build.gradle.kts file:

dependencies {
    implementation("dev.transformerkt:transformerkt::1.0.0")
}

Usage

First you should familiarize yourself with the Transformer Docs.

Inputs

Then you need an input video or image file. TransformerKt supports the following inputs:

• MediaItem.
• EditedMediaItem.
  • Note this class is new as of media3 version 1.1.0-alpha01. The library changed the way you apply effects and customizations to the MediaItem.
• A Uri pointing to somewhere on the device.
• A File object pointing to a file in the app’s sand-boxed storage.
  • Warning: Getting a File object to a file outside of the app’s storage will probably cause a permission error.

Now that you have your input sorted, there are two ways to consume this library.

Extension functions

A few extension functions have been added to the Transformer instance.

• suspend fun Transformer.start(): TransformerStatus.Finished
• fun Transformer.start(): Flow<TransformerStatus>

There are overloads for each of the supported inputs. For example:

suspend fun transform(context: Context, input: Uri) {
    val output = File(context.filesDir, "output.mp4")
    val transformer = Transformer.Builder(context).build()
    val result = transformer.start(input, output, TransformerKt.H264Request) { progress ->
        // Update UI progress
    }
    when (result) {
        is TransformerStatus.Failure -> TODO()
        is TransformerStatus.Success -> TODO()
    }
}

Or you can use the Flow version instead:

fun transform(context: Context, input: Uri) {
    val output = File(context.filesDir, "output.mp4")
    val transformer = Transformer.Builder(context).build()
    transformer.start(input, output, TransformerKt.H264Request).collect { status ->
        when (status) {
            is TransformerStatus.Progress -> TODO()
            is TransformerStatus.Success -> TODO()
            is TransformerStatus.Failure -> TODO()
        }
    }
}

Transform Requests

Now that you understand how to use the library, you need to understand what you can do with it.

First take a look at the Transformer Transformation Docs so you can see what is possible.

Note: The documentation is currently not up to date with the latest version of media3. So some things may be different.

By default, the library uses a default instance of TransformationRequest which most likely will not do anything to your input file. Therefore you need to provide your own TransformationRequest to the library, or use one of the predefined ones.

Currently TransformerKt ships with:

• TransformerKt.H264Request
  • Converts the input to an H264 encoded MP4 file.
• TransformerKt.H264AndAacRequest
  • Converts the input to an H264 encoded MP4 file, with AAC audio.

Example Requests

You can modify this request by using the provided buildWith {} extension function for TransformationRequest.Builder.

Convert a video to an H264 encoded MP4 file, with AAC audio:

val request = TransformerKt.H264Request.buildWith {
    setAudioMimeType(MimeTypes.AUDIO_AAC)
}

Convert a HDR video to a SDR video:

val request = TransformerKt.H264Request.buildWith {
    setHdrMode(TransformationRequest.HDR_MODE_TONE_MAP_HDR_TO_SDR_USING_OPEN_GL)
}

Applying Effects

Starting with version 1.1.0-alpha01, the Transformer library changed the way you apply effects. Instead of applying the effects to the Transformer.Builder you now create a EditedMediaItem and apply the affects there.

To make that API a bit easier, an extension function .edited {} has been added to MediaItem.Builder:

val editedMediaItem = MediaItem.Builder()
    .setUri(Uri.parse("https://example.com/video.mp4"))
    .setMediaId("Foo")
    .edited {
        setRemoveAudio(true)
    }

val result = TransformerKt.build(context).start(editedMediaItem, File("output.mp4"))

Or directly from a [MediaItem] instance:

val editedMediaItem = MediaItem
    .fromUri(Uri.parse("https://example.com/video.mp4"))
    .edited {
        setRemoveAudio(true)
    }

val result = TransformerKt.build(context).start(editedMediaItem, File("output.mp4"))

Demo App

A demo app is included in the demo module. It is a simple app that allows you to select a HDR video and convert it do a SDR video.

To run the demo app you can follow these steps:

git clone git@github.com:jordond/transformerkt.git transformerkt
cd transformerkt
./gradlew assembleRelease

Then install the demo/build/outputs/apk/release/demo-release.apk file on your device.

License

See LICENSE

GitHub

View Github