# Composition.Builder

Artifact: [androidx.media3:media3-transformer](https://developer.android.com/jetpack/androidx/releases/media3) [View Source](https://cs.android.com/search?q=file:androidx/media3/transformer/Composition.java+class:androidx.media3.transformer.Composition.Builder)

*** ** * ** ***


```
class Composition.Builder
```

<br />

*** ** * ** ***

A builder for `https://developer.android.com/reference/kotlin/androidx/media3/transformer/Composition` instances.

## Summary

| ### Public constructors |
|---|
| `https://developer.android.com/reference/kotlin/androidx/media3/transformer/Composition.Builder#Builder(java.util.List<androidx.media3.transformer.EditedMediaItemSequence>)(sequences: (https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-mutable-list/index.html)https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/kotlin/androidx/media3/transformer/EditedMediaItemSequence!>!)` Creates an instance. |
| `https://developer.android.com/reference/kotlin/androidx/media3/transformer/Composition.Builder#Builder(androidx.media3.transformer.EditedMediaItemSequence,androidx.media3.transformer.EditedMediaItemSequence...)( sequence: https://developer.android.com/reference/kotlin/androidx/media3/transformer/EditedMediaItemSequence!, sequences: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-array/index.html<https://developer.android.com/reference/kotlin/androidx/media3/transformer/EditedMediaItemSequence!>! )` Creates an instance. |

| ### Public functions |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/media3/transformer/Composition!` | `https://developer.android.com/reference/kotlin/androidx/media3/transformer/Composition.Builder#build()()` Builds a `https://developer.android.com/reference/kotlin/androidx/media3/transformer/Composition` instance. |
| `https://developer.android.com/reference/kotlin/androidx/media3/transformer/Composition.Builder!` | `@https://checkerframework.org/api/com/google/errorprone/annotations/CanIgnoreReturnValue.html [experimentalSetForceAudioTrack](https://developer.android.com/reference/kotlin/androidx/media3/transformer/Composition.Builder#experimentalSetForceAudioTrack(boolean))(forceAudioTrack: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html)` **This function is deprecated.** Use `https://developer.android.com/reference/kotlin/androidx/media3/transformer/EditedMediaItemSequence.Builder#Builder(java.util.Set<java.lang.Integer>)` to set sequence track types instead. <br /> |
| `https://developer.android.com/reference/kotlin/androidx/media3/transformer/Composition.Builder!` | `@https://checkerframework.org/api/com/google/errorprone/annotations/CanIgnoreReturnValue.html @https://developer.android.com/reference/kotlin/androidx/media3/common/util/ExperimentalApi https://developer.android.com/reference/kotlin/androidx/media3/transformer/Composition.Builder#experimentalSetRetainHdrFromUltraHdrImage(boolean)( retainHdrFromUltraHdrImage: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html )` Sets whether to use produce an HDR output video from Ultra HDR image input. |
| `https://developer.android.com/reference/kotlin/androidx/media3/transformer/Composition.Builder!` | `@https://checkerframework.org/api/com/google/errorprone/annotations/CanIgnoreReturnValue.html https://developer.android.com/reference/kotlin/androidx/media3/transformer/Composition.Builder#setEffects(androidx.media3.transformer.Effects)(effects: https://developer.android.com/reference/kotlin/androidx/media3/transformer/Effects!)` Sets the `https://developer.android.com/reference/kotlin/androidx/media3/transformer/Effects` to apply to the `https://developer.android.com/reference/kotlin/androidx/media3/transformer/Composition`. |
| `https://developer.android.com/reference/kotlin/androidx/media3/transformer/Composition.Builder!` | `@https://checkerframework.org/api/com/google/errorprone/annotations/CanIgnoreReturnValue.html https://developer.android.com/reference/kotlin/androidx/media3/transformer/Composition.Builder#setHdrMode(int)(@https://developer.android.com/reference/kotlin/androidx/media3/transformer/Composition.HdrMode hdrMode: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html)` Sets the `https://developer.android.com/reference/kotlin/androidx/media3/transformer/Composition.HdrMode` for HDR video input. |
| `https://developer.android.com/reference/kotlin/androidx/media3/transformer/Composition.Builder!` | `@https://checkerframework.org/api/com/google/errorprone/annotations/CanIgnoreReturnValue.html https://developer.android.com/reference/kotlin/androidx/media3/transformer/Composition.Builder#setTransmuxAudio(boolean)(transmuxAudio: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html)` Sets whether to transmux the `https://developer.android.com/reference/kotlin/androidx/media3/common/MediaItem` audio tracks. |
| `https://developer.android.com/reference/kotlin/androidx/media3/transformer/Composition.Builder!` | `@https://checkerframework.org/api/com/google/errorprone/annotations/CanIgnoreReturnValue.html https://developer.android.com/reference/kotlin/androidx/media3/transformer/Composition.Builder#setTransmuxVideo(boolean)(transmuxVideo: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html)` Sets whether to transmux the `https://developer.android.com/reference/kotlin/androidx/media3/common/MediaItem` video tracks. |
| `https://developer.android.com/reference/kotlin/androidx/media3/transformer/Composition.Builder!` | `@https://checkerframework.org/api/com/google/errorprone/annotations/CanIgnoreReturnValue.html https://developer.android.com/reference/kotlin/androidx/media3/transformer/Composition.Builder#setVideoCompositorSettings(androidx.media3.common.VideoCompositorSettings)( videoCompositorSettings: https://developer.android.com/reference/kotlin/androidx/media3/common/VideoCompositorSettings! )` Sets the `https://developer.android.com/reference/kotlin/androidx/media3/common/VideoCompositorSettings` to apply to the `https://developer.android.com/reference/kotlin/androidx/media3/transformer/Composition`. |
| `https://developer.android.com/reference/kotlin/androidx/media3/transformer/Composition.Builder!` | `@https://checkerframework.org/api/com/google/errorprone/annotations/CanIgnoreReturnValue.html @https://developer.android.com/reference/kotlin/androidx/media3/common/util/ExperimentalApi https://developer.android.com/reference/kotlin/androidx/media3/transformer/Composition.Builder#setVideoFrameAggregationParameters(androidx.media3.transformer.VideoFrameAggregationParameters)( videoFrameAggregationParameters: https://developer.android.com/reference/kotlin/androidx/media3/transformer/VideoFrameAggregationParameters! )` Sets the `https://developer.android.com/reference/kotlin/androidx/media3/transformer/VideoFrameAggregationParameters` to apply to the `https://developer.android.com/reference/kotlin/androidx/media3/transformer/Composition`. |

## Public constructors

### Builder

```
Builder(sequences: (Mutable)List<EditedMediaItemSequence!>!)
```

Creates an instance.

| Parameters |
|---|---|
| `sequences: (https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-mutable-list/index.html)https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/kotlin/androidx/media3/transformer/EditedMediaItemSequence!>!` | The `https://developer.android.com/reference/kotlin/androidx/media3/transformer/EditedMediaItemSequence` instances to compose. The list must be non empty. See `https://developer.android.com/reference/kotlin/androidx/media3/transformer/Composition#sequences()` for more details. |

### Builder

```
Builder(
    sequence: EditedMediaItemSequence!,
    sequences: Array<EditedMediaItemSequence!>!
)
```

Creates an instance.

| See also |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/media3/transformer/Composition.Builder#Builder(java.util.List<androidx.media3.transformer.EditedMediaItemSequence>)` |   |

## Public functions

### build

```
fun build(): Composition!
```

Builds a `https://developer.android.com/reference/kotlin/androidx/media3/transformer/Composition` instance.

### experimentalSetForceAudioTrack

```
@CanIgnoreReturnValue
fun [experimentalSetForceAudioTrack](https://developer.android.com/reference/kotlin/androidx/media3/transformer/Composition.Builder#experimentalSetForceAudioTrack(boolean))(forceAudioTrack: Boolean): Composition.Builder!
```

> [!CAUTION]
> **This function is deprecated.**   
>
> Use `https://developer.android.com/reference/kotlin/androidx/media3/transformer/EditedMediaItemSequence.Builder#Builder(java.util.Set<java.lang.Integer>)` to set sequence track types instead.

### experimentalSetRetainHdrFromUltraHdrImage

```
@CanIgnoreReturnValue
@ExperimentalApi
fun experimentalSetRetainHdrFromUltraHdrImage(
    retainHdrFromUltraHdrImage: Boolean
): Composition.Builder!
```

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

If the `https://developer.android.com/reference/kotlin/androidx/media3/transformer/Composition.HdrMode` is `https://developer.android.com/reference/kotlin/androidx/media3/transformer/Composition#HDR_MODE_KEEP_HDR()`, then setting this to `true` applies the recovery map (i.e. the gainmap) to the base image to produce HDR video frames. This is automatically overridden to true, if the first asset is a HDR video.

The output video will have the same color encoding as the first `https://developer.android.com/reference/kotlin/androidx/media3/transformer/EditedMediaItem` the sequence. If the Ultra HDR image is first in the sequence, output video will default to BT2020 HLG full range colors.

Ignored if `https://developer.android.com/reference/kotlin/androidx/media3/transformer/Composition.HdrMode` is not `https://developer.android.com/reference/kotlin/androidx/media3/transformer/Composition#HDR_MODE_KEEP_HDR()`.

Supported on API 34+, by some device and HDR format combinations. Ignored if unsupported by device or API level.

The default value is `false`.

| Parameters |
|---|---|
| `retainHdrFromUltraHdrImage: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | Whether to use produce an HDR output video from Ultra HDR image input. |

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/media3/transformer/Composition.Builder!` | This builder. |

### setEffects

```
@CanIgnoreReturnValue
fun setEffects(effects: Effects!): Composition.Builder!
```

Sets the `https://developer.android.com/reference/kotlin/androidx/media3/transformer/Effects` to apply to the `https://developer.android.com/reference/kotlin/androidx/media3/transformer/Composition`.

The default value is `https://developer.android.com/reference/kotlin/androidx/media3/transformer/Effects#EMPTY()`.

| Parameters |
|---|---|
| `effects: https://developer.android.com/reference/kotlin/androidx/media3/transformer/Effects!` | The `https://developer.android.com/reference/kotlin/androidx/media3/transformer/Composition``https://developer.android.com/reference/kotlin/androidx/media3/transformer/Effects`. |

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/media3/transformer/Composition.Builder!` | This builder. |

### setHdrMode

```
@CanIgnoreReturnValue
fun setHdrMode(@Composition.HdrMode hdrMode: Int): Composition.Builder!
```

Sets the `https://developer.android.com/reference/kotlin/androidx/media3/transformer/Composition.HdrMode` for HDR video input.

The default value is `https://developer.android.com/reference/kotlin/androidx/media3/transformer/Composition#HDR_MODE_KEEP_HDR()`. Apps that need to tone-map HDR to SDR should generally prefer `https://developer.android.com/reference/kotlin/androidx/media3/transformer/Composition#HDR_MODE_TONE_MAP_HDR_TO_SDR_USING_OPEN_GL()` over `https://developer.android.com/reference/kotlin/androidx/media3/transformer/Composition#HDR_MODE_TONE_MAP_HDR_TO_SDR_USING_MEDIACODEC()`, because its behavior is likely to be more consistent across devices.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/kotlin/androidx/media3/transformer/Composition.HdrMode hdrMode: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | The `https://developer.android.com/reference/kotlin/androidx/media3/transformer/Composition.HdrMode` used. |

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/media3/transformer/Composition.Builder!` | This builder. |

### setTransmuxAudio

```
@CanIgnoreReturnValue
fun setTransmuxAudio(transmuxAudio: Boolean): Composition.Builder!
```

Sets whether to transmux the `https://developer.android.com/reference/kotlin/androidx/media3/common/MediaItem` audio tracks.

The default value is `false`.

If the `https://developer.android.com/reference/kotlin/androidx/media3/transformer/Composition` contains one `https://developer.android.com/reference/kotlin/androidx/media3/common/MediaItem`, the value set is ignored. The audio track will only be transcoded if necessary.

If the input `https://developer.android.com/reference/kotlin/androidx/media3/transformer/Composition` contains multiple `https://developer.android.com/reference/kotlin/androidx/media3/common/MediaItem`, all the audio tracks are transcoded by default. They are all transmuxed if `transmuxAudio` is `true`. Transmuxed tracks must be compatible (typically, all the `https://developer.android.com/reference/kotlin/androidx/media3/common/MediaItem` instances containing the track to transmux are concatenated in a single `https://developer.android.com/reference/kotlin/androidx/media3/transformer/EditedMediaItemSequence` and have the same sample format for that track). Any transcoding effects requested will be ignored.

Requesting audio transmuxing while also requiring silence generation is not allowed, as generating silence requires transcoding. Silence generation is needed when a sequence has `https://developer.android.com/reference/kotlin/androidx/media3/common/C#TRACK_TYPE_AUDIO()` and contains `https://developer.android.com/reference/kotlin/androidx/media3/transformer/EditedMediaItemSequence.Builder#addGap(long)` or an audio-less `https://developer.android.com/reference/kotlin/androidx/media3/transformer/EditedMediaItem`.

| Parameters |
|---|---|
| `transmuxAudio: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | Whether to transmux the audio tracks. |

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/media3/transformer/Composition.Builder!` | This builder. |

### setTransmuxVideo

```
@CanIgnoreReturnValue
fun setTransmuxVideo(transmuxVideo: Boolean): Composition.Builder!
```

Sets whether to transmux the `https://developer.android.com/reference/kotlin/androidx/media3/common/MediaItem` video tracks.

The default value is `false`.

If the `https://developer.android.com/reference/kotlin/androidx/media3/transformer/Composition` contains one `https://developer.android.com/reference/kotlin/androidx/media3/common/MediaItem`, the value set is ignored. The video track will only be transcoded if necessary.

If the input `https://developer.android.com/reference/kotlin/androidx/media3/transformer/Composition` contains multiple `https://developer.android.com/reference/kotlin/androidx/media3/common/MediaItem`, all the video tracks are transcoded by default. They are all transmuxed if `transmuxVideo` is `true`. Transmuxed tracks must be compatible (typically, all the `https://developer.android.com/reference/kotlin/androidx/media3/common/MediaItem` instances containing the track to transmux are concatenated in a single `https://developer.android.com/reference/kotlin/androidx/media3/transformer/EditedMediaItemSequence` and have the same sample format for that track). Any transcoding effects requested will be ignored.

| Parameters |
|---|---|
| `transmuxVideo: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | Whether to transmux the video tracks. |

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/media3/transformer/Composition.Builder!` | This builder. |

### setVideoCompositorSettings

```
@CanIgnoreReturnValue
fun setVideoCompositorSettings(
    videoCompositorSettings: VideoCompositorSettings!
): Composition.Builder!
```

Sets the `https://developer.android.com/reference/kotlin/androidx/media3/common/VideoCompositorSettings` to apply to the `https://developer.android.com/reference/kotlin/androidx/media3/transformer/Composition`.

The default value is `https://developer.android.com/reference/kotlin/androidx/media3/common/VideoCompositorSettings#DEFAULT()`.

| Parameters |
|---|---|
| `videoCompositorSettings: https://developer.android.com/reference/kotlin/androidx/media3/common/VideoCompositorSettings!` | The `https://developer.android.com/reference/kotlin/androidx/media3/common/VideoCompositorSettings`. |

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/media3/transformer/Composition.Builder!` | This builder. |

### setVideoFrameAggregationParameters

```
@CanIgnoreReturnValue
@ExperimentalApi
fun setVideoFrameAggregationParameters(
    videoFrameAggregationParameters: VideoFrameAggregationParameters!
): Composition.Builder!
```

Sets the `https://developer.android.com/reference/kotlin/androidx/media3/transformer/VideoFrameAggregationParameters` to apply to the `https://developer.android.com/reference/kotlin/androidx/media3/transformer/Composition`.

The default value is `https://developer.android.com/reference/kotlin/androidx/media3/transformer/VideoFrameAggregationParameters#DEFAULT()`.

Note: This configuration is only applied when a `https://developer.android.com/reference/kotlin/androidx/media3/common/video/FrameProcessor` is enabled (e.g., by setting a `https://developer.android.com/reference/kotlin/androidx/media3/common/video/FrameProcessor.Factory` via `https://developer.android.com/reference/kotlin/androidx/media3/transformer/Transformer.Builder#setFrameProcessorFactory(androidx.media3.common.video.FrameProcessor.Factory)` or `https://developer.android.com/reference/kotlin/androidx/media3/transformer/CompositionPlayer.Builder#setFrameProcessorFactory(androidx.media3.common.video.FrameProcessor.Factory)`).

| Parameters |
|---|---|
| `videoFrameAggregationParameters: https://developer.android.com/reference/kotlin/androidx/media3/transformer/VideoFrameAggregationParameters!` | The `https://developer.android.com/reference/kotlin/androidx/media3/transformer/VideoFrameAggregationParameters` to apply. |

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/media3/transformer/Composition.Builder!` | This builder. |