Transformer

Artifact: androidx.media3:media3-transformer

Kotlin |Java

@UnstableApi
public final 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 Transformer.Builder 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
`public final class Transformer.Builder` A builder for `Transformer` instances.
`public interface Transformer.Listener` A listener for the export events.
`@Documented @Retention(value = RetentionPolicy.SOURCE) @Target(value = ElementType.TYPE_USE) @IntDef(value = ) public annotation Transformer.ProgressState` Progress state.

Constants
`static final long`	`DEFAULT_MAX_DELAY_BETWEEN_MUXER_SAMPLES_MS` The default value for the `maximum delay between output samples`.
`static final int`	`PROGRESS_STATE_AVAILABLE = 2` Indicates that the progress is available.
`static final int`	`PROGRESS_STATE_NOT_STARTED = 0` Indicates that the corresponding operation hasn't been started.
`static final int`	`PROGRESS_STATE_UNAVAILABLE = 3` Indicates that the progress is permanently unavailable.
`static final int`	`PROGRESS_STATE_WAITING_FOR_AVAILABILITY = 1` Indicates that the progress is currently unavailable, but might become available.

Public methods
`void`	`addListener(Transformer.Listener listener)` Adds a `Transformer.Listener` to listen to the export events.
`Transformer.Builder`	`buildUpon()` Returns a `Transformer.Builder` initialized with the values of this instance.
`void`	`cancel()` Cancels the export that is currently in progress, if any.
`Looper`	`getApplicationLooper()` Returns the `Looper` associated with the application thread that's used to access the transformer and on which transformer events are received.
`int`	`@Transformer.ProgressState getProgress(ProgressHolder progressHolder)` Returns the current `ProgressState` and updates `progressHolder` with the current progress if it is `available`.
`void`	`removeAllListeners()` Removes all `listeners`.
`void`	`removeListener(Transformer.Listener listener)` Removes a `Transformer.Listener`.
`void`	`resume( Composition composition, String outputFilePath, String oldFilePath )` Resumes a previously `cancelled` export.
`void`	`start(Composition composition, String path)` Starts an asynchronous operation to export the given `Composition`.
`void`	`start(EditedMediaItem editedMediaItem, String path)` Starts an asynchronous operation to export the given `EditedMediaItem`.
`void`	`start(MediaItem mediaItem, String path)` Starts an asynchronous operation to export the given `MediaItem`.

Constants

DEFAULT_MAX_DELAY_BETWEEN_MUXER_SAMPLES_MS

public static final long DEFAULT_MAX_DELAY_BETWEEN_MUXER_SAMPLES_MS

The default value for the maximum delay between output samples.

PROGRESS_STATE_AVAILABLE

public static final int PROGRESS_STATE_AVAILABLE = 2

Indicates that the progress is available.

PROGRESS_STATE_NOT_STARTED

public static final int PROGRESS_STATE_NOT_STARTED = 0

Indicates that the corresponding operation hasn't been started.

PROGRESS_STATE_UNAVAILABLE

public static final int PROGRESS_STATE_UNAVAILABLE = 3

Indicates that the progress is permanently unavailable.

PROGRESS_STATE_WAITING_FOR_AVAILABILITY

public static final int PROGRESS_STATE_WAITING_FOR_AVAILABILITY = 1

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

Public methods

addListener

public void addListener(Transformer.Listener listener)

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

Parameters
`Transformer.Listener listener`	A `Transformer.Listener`.

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

buildUpon

public Transformer.Builder buildUpon()

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

cancel

public void cancel()

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

public Looper getApplicationLooper()

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
public int getProgress(ProgressHolder progressHolder)

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

public void removeAllListeners()

Removes all listeners.

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

removeListener

public void removeListener(Transformer.Listener listener)

Removes a Transformer.Listener.

Parameters
`Transformer.Listener listener`	A `Transformer.Listener`.

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

resume

public void resume(
    Composition composition,
    String outputFilePath,
    String oldFilePath
)

Resumes a previously cancelled export.

An export can be resumed only when:

The Composition contains a single EditedMediaItemSequence having continuous audio and video tracks.
The output is an MP4 file.
The Composition and EditedMediaItem instances do not contain speed changing effects.

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

Parameters
`Composition composition`	The `Composition` to resume export.
`String outputFilePath`	The path to the output file. This must be different from the output path of the cancelled export.
`String oldFilePath`	The output path of the the cancelled export.

start

public void start(Composition composition, String path)

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 EditedMediaItemSequence, 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:

The tracks present in the output of a sequence are determined by the trackTypes parameter of the EditedMediaItemSequence.Builder. Tracks of types not present in trackTypes will be dropped. If an EditedMediaItem within a sequence does not contain a track of a declared type, silent audio or blank video will be generated.
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 ToInt16PcmAudioProcessor 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.
`String path`	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

public void start(EditedMediaItem editedMediaItem, String path)

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.

Parameters
`EditedMediaItem editedMediaItem`	The `EditedMediaItem` to export.
`String path`	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

public void start(MediaItem mediaItem, String path)

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.

Parameters
`MediaItem mediaItem`	The `MediaItem` to export.
`String path`	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.

Transformer

Summary

Nested types

Constants

Public methods

Constants

DEFAULT_MAX_DELAY_BETWEEN_MUXER_SAMPLES_MS

PROGRESS_STATE_AVAILABLE

PROGRESS_STATE_NOT_STARTED

PROGRESS_STATE_UNAVAILABLE

PROGRESS_STATE_WAITING_FOR_AVAILABILITY

Public methods

addListener

buildUpon

cancel

getApplicationLooper

getProgress

removeAllListeners

removeListener

resume

start

start

start