Using Transformer, you can combine multiple media assets, such as videos, images, and audio files to create a`Composition`.

## Exporting a Composition

To apply[transformations](https://developer.android.com/media/media3/transformer/transformations)(such as effects or trimming edits) to a`MediaItem`, you should create an[`EditedMediaItem`](https://developer.android.com/reference/androidx/media3/transformer/EditedMediaItem)to represent the asset that has the transformations applied to it.

`EditedMediaItem`objects can then be concatenated together to create an[`EditedMediaItemSequence`](https://developer.android.com/reference/androidx/media3/transformer/EditedMediaItemSequence). For example, you can create an`EditedMediaItemSequence`with two edited videos. Items inside an`EditedMediaItemSequence`are ordered sequentially and don't overlap in time.

A`Composition`is the combination of one or more`EditedMediaItemSequence`objects. All`EditedMediaItemSequence`objects in the`Composition`are mixed together, allowing you to combine video and audio assets.

`Composition`objects can be exported using Transformer.

Here is an example of creating and exporting a video asset that consists of two edited video clips, overlaid with an audio track:  

### Kotlin

```kotlin
val transformer = ... // Set up Transformer instance

val video1 = EditedMediaItem.Builder(
  MediaItem.fromUri(video1Uri))
  .build()

val video2 = EditedMediaItem.Builder(
  MediaItem.fromUri(video2Uri))
  .build()

val videoSequence = EditedMediaItemSequence(
  video1, video2)

val backgroundAudio = EditedMediaItem.Builder(
  MediaItem.fromUri(audioUri))
  .build()

val backgroundAudioSequence = EditedMediaItemSequence(
  ImmutableList.of(backgroundAudio),
  /* isLooping= */ true) // Loop audio track through duration of videoSequence

val composition = Composition.Builder(
  videoSequence,
  backgroundAudioSequence)
  .build()

val filePath = ... // Provide file path to save Composition

transformer.start(composition, filePath)
```

### Java

```java
Transformer transformer = ... // Set up Transformer instance

EditedMediaItem video1 = new EditedMediaItem.Builder(
  MediaItem.fromUri(video1Uri))
  .build();

EditedMediaItem video2 = new EditedMediaItem.Builder(
  MediaItem.fromUri(video2Uri))
  .build();

EditedMediaItemSequence videoSequence = new EditedMediaItemSequence(
  video1, video2);

EditedMediaItem backgroundAudio = new EditedMediaItem.Builder(
  MediaItem.fromUri(audioUri))
  .build();

EditedMediaItemSequence backgroundAudioSequence = new EditedMediaItemSequence(
  ImmutableList.of(backgroundAudio),
  /* isLooping= */ true); // Loop audio track through duration of videoSequence

String filePath = ... // Provide file path to save Composition

Composition composition = new Composition.Builder(
  videoSequence,
  backgroundAudioSequence)
  .build();

transformer.start(composition, filePath);
```

<br />

## Examples of supported use cases

This is a non-exhaustive list of use cases that the Transformer API supports with Compositions:

- Sequentially combining audio, image, and video assets. However, all items in a sequence must have the same tracks. For example, you cannot have a sequence that contains an audio only file, followed by a video file.
- Adding background audio to a video asset.
- Adding effects to a Composition.
- Tone mapping HDR input to SDR to generate better visual quality SDR output.

## Current limitations

Sequences within a Composition must meet the conditions outlined in[`Transformer.start()`](https://developer.android.com/reference/androidx/media3/transformer/Transformer#start(androidx.media3.transformer.Composition,java.lang.String)). Furthermore, the following operations are not yet supported when working with Compositions:

- Starting playback of an`EditedMediaItemSequence`with an offset.
- Crossfading video or audio tracks

## Feature requests

If you have any feature requests for the Transformer API, file an issue on the[Media3 GitHub repository](https://github.com/androidx/media/issues).