@UnstableApi
class Transformer

A transformer to export media inputs.

The same Transformer instance can be used to export multiple inputs (sequentially, not concurrently).

Transformer instances must be accessed from a single application thread. For the vast majority of cases this should be the application's main thread. The thread on which a Transformer instance must be accessed can be explicitly specified by passing a Looper when creating the transformer. If no Looper is specified, then the Looper of the thread that the is created on is used, or if that thread does not have a Looper, the Looper of the application's main thread is used. In all cases the Looper of the thread from which the transformer must be accessed can be queried using getApplicationLooper.

Summary

Nested types

A builder for Transformer instances.

A listener for the export events.
@Documented
@Retention(value = RetentionPolicy.SOURCE)
@Target(value = TYPE_USE)
@IntDef(value = )
annotation Transformer.ProgressState

Progress state.

Constants
const Long

The default value for the maximum delay between output samples.
const Int

Indicates that the progress is available.
const Int

Indicates that the corresponding operation hasn't been started.
const Int

This property is deprecated.

Use PROGRESS_STATE_NOT_STARTED instead.
const Int

Indicates that the progress is permanently unavailable.
const Int

Indicates that the progress is currently unavailable, but might become available.

Public functions
Unit

Adds a Transformer.Listener to listen to the export events.
Transformer.Builder!

Returns a Transformer.Builder initialized with the values of this instance.
Unit

Cancels the export that is currently in progress, if any.
Looper!

Returns the Looper associated with the application thread that's used to access the transformer and on which transformer events are received.
Int

Returns the current ProgressState and updates progressHolder with the current progress if it is available.
Unit

Removes all listeners.
Unit

Removes a Transformer.Listener.
Unit
resume(
    composition: Composition!,
    outputFilePath: String!,
    oldFilePath: String!
)

Resumes a previously cancelled export.
Unit

This function is deprecated.

Use addListener, removeListener or removeAllListeners instead.
Unit
start(composition: Composition!, path: String!)

Starts an asynchronous operation to export the given Composition.
Unit
start(editedMediaItem: EditedMediaItem!, path: String!)

Starts an asynchronous operation to export the given EditedMediaItem.
Unit
start(mediaItem: MediaItem!, path: String!)

Starts an asynchronous operation to export the given MediaItem.
Unit
@InlineMe(replacement = "this.start(mediaItem, path)")
startTransformation(mediaItem: MediaItem!, path: String!)

This function is deprecated.

Use start instead.

Constants

DEFAULT_MAX_DELAY_BETWEEN_MUXER_SAMPLES_MS

const val DEFAULT_MAX_DELAY_BETWEEN_MUXER_SAMPLES_MS: Long

The default value for the maximum delay between output samples.

PROGRESS_STATE_AVAILABLE

const val PROGRESS_STATE_AVAILABLE = 2: Int

Indicates that the progress is available.

PROGRESS_STATE_NOT_STARTED

const val PROGRESS_STATE_NOT_STARTED = 0: Int

Indicates that the corresponding operation hasn't been started.

PROGRESS_STATE_NO_TRANSFORMATION

const val PROGRESS_STATE_NO_TRANSFORMATION = 0: Int

PROGRESS_STATE_UNAVAILABLE

const val PROGRESS_STATE_UNAVAILABLE = 3: Int

Indicates that the progress is permanently unavailable.

PROGRESS_STATE_WAITING_FOR_AVAILABILITY

const val PROGRESS_STATE_WAITING_FOR_AVAILABILITY = 1: Int

Indicates that the progress is currently unavailable, but might become available.

Public functions

addListener

fun addListener(listener: Transformer.Listener!): Unit

Adds a Transformer.Listener to listen to the export events.

Parameters
listener: Transformer.Listener!

A Transformer.Listener.
Throws
java.lang.IllegalStateException

If this method is called from the wrong thread.

buildUpon

fun buildUpon(): Transformer.Builder!

Returns a Transformer.Builder initialized with the values of this instance.

cancel

fun cancel(): Unit

Cancels the export that is currently in progress, if any.

The export output file (if any) is not deleted.

Throws
java.lang.IllegalStateException

If this method is called from the wrong thread.

getApplicationLooper

fun getApplicationLooper(): Looper!

Returns the Looper associated with the application thread that's used to access the transformer and on which transformer events are received.

getProgress

@Transformer.ProgressState
fun getProgress(progressHolder: ProgressHolder!): Int

Returns the current ProgressState and updates progressHolder with the current progress if it is available.

If the export is resumed, this method returns PROGRESS_STATE_UNAVAILABLE.

After an export completes, this method returns PROGRESS_STATE_NOT_STARTED.

Parameters
progressHolder: ProgressHolder!

A ProgressHolder, updated to hold the percentage progress if available.
Returns
Int

The ProgressState.
Throws
java.lang.IllegalStateException

If this method is called from the wrong thread.

removeAllListeners

fun removeAllListeners(): Unit

Removes all listeners.

Throws
java.lang.IllegalStateException

If this method is called from the wrong thread.

removeListener

fun removeListener(listener: Transformer.Listener!): Unit

Removes a Transformer.Listener.

Parameters
listener: Transformer.Listener!

A Transformer.Listener.
Throws
java.lang.IllegalStateException

If this method is called from the wrong thread.

resume

fun resume(
    composition: Composition!,
    outputFilePath: String!,
    oldFilePath: String!
): Unit

Resumes a previously cancelled export.

An export can be resumed only when:

Note that export optimizations (such as trim optimization) will not be applied upon resumption.

Parameters
composition: Composition!

The Composition to resume export.
outputFilePath: String!

The path to the output file. This must be different from the output path of the cancelled export.
oldFilePath: String!

The output path of the the cancelled export.

setListener

fun setListener(listener: Transformer.Listener!): Unit

start

fun start(composition: Composition!, path: String!): Unit

Starts an asynchronous operation to export the given Composition.

The first EditedMediaItem in the first EditedMediaItemSequence that has a given track will determine the output format for that track, unless the format is set when building the Transformer. For example, consider the following composition 

  Composition {
    EditedMediaItemSequence {
      [ImageMediaItem, VideoMediaItem]
    },
    EditedMediaItemSequence {
      [AudioMediaItem]
    },
  }
 The video format will be determined by the ImageMediaItem in the first , while the audio format will be determined by the AudioMediaItem in the second EditedMediaItemSequence.

Some compositions are not supported yet. More specifically, Sequences within the Composition must meet the following conditions:

  • If an EditedMediaItem in a sequence contains data of a given track, so must all items in that sequence.
    • For audio, this condition can be removed by setting an experimental flag.
  • If a sequence starts with an HDR EditedMediaItem, all the following items in the sequence must be HDR.
  • All items containing audio data must output 16 bit PCM audio with the same number of channels. This can be done by adding a and/or a ChannelMixingAudioProcessor to the item specific effects.

The export state is notified through the listener.

Concurrent exports on the same Transformer object are not allowed.

If no custom Muxer.Factory is specified, the output is an MP4 file.

The output can contain at most one video track and one audio track. Other track types are ignored. For adaptive bitrate inputs, if no custom AssetLoader.Factory is specified, the highest bitrate video and audio streams are selected.

If exporting the video track entails transcoding, the output frames' dimensions will be swapped if the output video's height is larger than the width. This is to improve compatibility among different device encoders.

Parameters
composition: Composition!

The Composition to export.
path: String!

The path to the output file.
Throws
java.lang.IllegalStateException

If this method is called from the wrong thread.
java.lang.IllegalStateException

If an export is already in progress.

start

fun start(editedMediaItem: EditedMediaItem!, path: String!): Unit

Starts an asynchronous operation to export the given EditedMediaItem.

The export state is notified through the listener.

Concurrent exports on the same Transformer object are not allowed.

If no custom Muxer.Factory is specified, the output is an MP4 file.

The output can contain at most one video track and one audio track. Other track types are ignored. For adaptive bitrate inputs, if no custom AssetLoader.Factory is specified, the highest bitrate video and audio streams are selected.

If exporting the video track entails transcoding, the output frames' dimensions will be swapped if the output video's height is larger than the width. This is to improve compatibility among different device encoders.

Parameters
editedMediaItem: EditedMediaItem!

The EditedMediaItem to export.
path: String!

The path to the output file.
Throws
java.lang.IllegalStateException

If this method is called from the wrong thread.
java.lang.IllegalStateException

If an export is already in progress.

start

fun start(mediaItem: MediaItem!, path: String!): Unit

Starts an asynchronous operation to export the given MediaItem.

The export state is notified through the listener.

Concurrent exports on the same Transformer object are not allowed.

If no custom Muxer.Factory is specified, the output is an MP4 file.

The output can contain at most one video track and one audio track. Other track types are ignored. For adaptive bitrate inputs, if no custom AssetLoader.Factory is specified, the highest bitrate video and audio streams are selected.

If exporting the video track entails transcoding, the output frames' dimensions will be swapped if the output video's height is larger than the width. This is to improve compatibility among different device encoders.

Parameters
mediaItem: MediaItem!

The MediaItem to export.
path: String!

The path to the output file.
Throws
java.lang.IllegalArgumentException

If the MediaItem is not supported.
java.lang.IllegalStateException

If this method is called from the wrong thread.
java.lang.IllegalStateException

If an export is already in progress.

startTransformation

@InlineMe(replacement = "this.start(mediaItem, path)")
fun startTransformation(mediaItem: MediaItem!, path: String!): Unit