@UnstableApi
public final class Composition


A composition of MediaItem instances, with transformations to apply to them.

The MediaItem instances can be concatenated or mixed. Effects can be applied to individual MediaItem instances, as well as to the composition.

Summary

Nested types

public final class Composition.Builder

A builder for Composition instances.

@Documented
@Retention(value = SOURCE)
@Target(value = TYPE_USE)
@IntDef(value = )
public annotation Composition.HdrMode

The strategy to use to transcode or edit High Dynamic Range (HDR) input video.

Constants

static final int

Interpret HDR input as SDR, likely with a washed out look.

static final int

Processes HDR input as HDR, to generate HDR output.

static final int

Tone map HDR input to SDR before processing, to generate SDR output, using the decoder tone-mapper.

static final int

Tone map HDR input to SDR before processing, to generate SDR output, using an OpenGL tone-mapper.

Public fields

final Effects

The Effects to apply to the composition.

final boolean

Whether the output file should always contain an audio track.

final int

The HdrMode specifying how to handle HDR input video.

final boolean

Sets whether to use produce an HDR output video from Ultra HDR image input.

final ImmutableList<EditedMediaItemSequence>

The EditedMediaItemSequence instances to compose.

final boolean

Whether to transmux the media items' audio tracks.

final boolean

Whether to transmux the media items' video tracks.

final VideoCompositorSettings

The VideoCompositorSettings to apply to the composition.

Constants

HDR_MODE_EXPERIMENTAL_FORCE_INTERPRET_HDR_AS_SDR

public static final int HDR_MODE_EXPERIMENTAL_FORCE_INTERPRET_HDR_AS_SDR = 3

Interpret HDR input as SDR, likely with a washed out look.

This is much more widely supported than HDR_MODE_KEEP_HDR, HDR_MODE_TONE_MAP_HDR_TO_SDR_USING_MEDIACODEC, and HDR_MODE_TONE_MAP_HDR_TO_SDR_USING_OPEN_GL. However, as HDR transfer functions and metadata will be ignored, contents will be displayed incorrectly, likely with a washed out look.

Using this API may lead to codec errors before API 29.

Use of this flag may result in ERROR_CODE_DECODING_FORMAT_UNSUPPORTED.

This field is experimental, and will be renamed or removed in a future release.

HDR_MODE_KEEP_HDR

public static final int HDR_MODE_KEEP_HDR = 0

Processes HDR input as HDR, to generate HDR output.

The HDR output format (ex. color transfer) will be the same as the HDR input format.

Supported on API 31+, by some device and HDR format combinations.

If not supported, Transformer will attempt to use HDR_MODE_TONE_MAP_HDR_TO_SDR_USING_OPEN_GL.

HDR_MODE_TONE_MAP_HDR_TO_SDR_USING_MEDIACODEC

public static final int HDR_MODE_TONE_MAP_HDR_TO_SDR_USING_MEDIACODEC = 1

Tone map HDR input to SDR before processing, to generate SDR output, using the decoder tone-mapper.

Supported on API 31+, by some device and HDR format combinations. Tone-mapping is only guaranteed to be supported on API 33+, on devices with HDR capture support.

If not supported, Transformer throws an ExportException.

HDR_MODE_TONE_MAP_HDR_TO_SDR_USING_OPEN_GL

public static final int HDR_MODE_TONE_MAP_HDR_TO_SDR_USING_OPEN_GL = 2

Tone map HDR input to SDR before processing, to generate SDR output, using an OpenGL tone-mapper.

Supported on API 29+.

This may exhibit mild differences from HDR_MODE_TONE_MAP_HDR_TO_SDR_USING_MEDIACODEC, depending on the device's tone-mapping implementation, but should have much wider support and have more consistent results across devices.

If not supported, Transformer throws an ExportException.

Public fields

effects

public final Effects effects

The Effects to apply to the composition.

forceAudioTrack

public final boolean forceAudioTrack

Whether the output file should always contain an audio track.

For more information, see experimentalSetForceAudioTrack.

hdrMode

@Composition.HdrMode
public final int hdrMode

The HdrMode specifying how to handle HDR input video.

For more information, see setHdrMode.

retainHdrFromUltraHdrImage

public final boolean retainHdrFromUltraHdrImage

Sets whether to use produce an HDR output video from Ultra HDR image input.

For more information, see experimentalSetRetainHdrFromUltraHdrImage.

sequences

public final ImmutableList<EditedMediaItemSequencesequences

The EditedMediaItemSequence instances to compose.

MediaItem instances from different sequences that are overlapping in time will be mixed in the output.

transmuxAudio

public final boolean transmuxAudio

Whether to transmux the media items' audio tracks.

For more information, see setTransmuxAudio.

transmuxVideo

public final boolean transmuxVideo

Whether to transmux the media items' video tracks.

For more information, see setTransmuxVideo.

videoCompositorSettings

public final VideoCompositorSettings videoCompositorSettings

The VideoCompositorSettings to apply to the composition.