Transformer

Artifact: androidx.media3:media3-transformer

View Source

---

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 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 = 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_NO_TRANSFORMATION = 0 This field is deprecated. Use PROGRESS_STATE_NOT_STARTED instead.
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	setListener(Transformer.Listener listener) This method is deprecated. Use addListener, removeListener or removeAllListeners instead.
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.
void	@InlineMe(replacement = "this.start(mediaItem, path)") startTransformation(MediaItem mediaItem, String path) This method is deprecated. Use start instead.

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_NO_TRANSFORMATION

public static final int PROGRESS_STATE_NO_TRANSFORMATION = 0

This field is deprecated.

Use PROGRESS_STATE_NOT_STARTED instead.

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.

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.

setListener

public void setListener(Transformer.Listener listener)

This method is deprecated.

Use addListener, removeListener or removeAllListeners instead.

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 , 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.
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.

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.
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.

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.
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.

startTransformation

@InlineMe(replacement = "this.start(mediaItem, path)")
public void startTransformation(MediaItem mediaItem, String path)

This method is deprecated.

Use start instead.