@UnstableApi
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

A builder for Composition instances.
@Documented
@Retention(value = SOURCE)
@Target(value = TYPE_USE)
@IntDef(value = )
annotation Composition.HdrMode

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

Constants
const Int

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

Processes HDR input as HDR, to generate HDR output.
const Int

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

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

Public properties
Effects!

The Effects to apply to the composition.
Boolean

Whether the output file should always contain an audio track.
Int

The HdrMode specifying how to handle HDR input video.
Boolean

Sets whether to use produce an HDR output video from Ultra HDR image input.
ImmutableList<EditedMediaItemSequence!>!

The EditedMediaItemSequence instances to compose.
Boolean

Whether to transmux the media items' audio tracks.
Boolean

Whether to transmux the media items' video tracks.
VideoCompositorSettings!

The VideoCompositorSettings to apply to the composition.

Constants

HDR_MODE_EXPERIMENTAL_FORCE_INTERPRET_HDR_AS_SDR

const val HDR_MODE_EXPERIMENTAL_FORCE_INTERPRET_HDR_AS_SDR = 3: Int

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

const val HDR_MODE_KEEP_HDR = 0: Int

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

const val HDR_MODE_TONE_MAP_HDR_TO_SDR_USING_MEDIACODEC = 1: Int

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

const val HDR_MODE_TONE_MAP_HDR_TO_SDR_USING_OPEN_GL = 2: Int

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 properties

effects

val effects: Effects!

The Effects to apply to the composition.

forceAudioTrack

val forceAudioTrack: Boolean

Whether the output file should always contain an audio track.

For more information, see experimentalSetForceAudioTrack.

hdrMode

@Composition.HdrMode
val hdrMode: Int

The HdrMode specifying how to handle HDR input video.

For more information, see setHdrMode.

retainHdrFromUltraHdrImage

val retainHdrFromUltraHdrImage: Boolean

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

For more information, see experimentalSetRetainHdrFromUltraHdrImage.

sequences

val sequences: ImmutableList<EditedMediaItemSequence!>!

The EditedMediaItemSequence instances to compose.

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

transmuxAudio

val transmuxAudio: Boolean

Whether to transmux the media items' audio tracks.

For more information, see setTransmuxAudio.

transmuxVideo

val transmuxVideo: Boolean

Whether to transmux the media items' video tracks.

For more information, see setTransmuxVideo.

videoCompositorSettings

val videoCompositorSettings: VideoCompositorSettings!

The VideoCompositorSettings to apply to the composition.