Preview Edits with CompositionPlayer

The Jetpack Media3 library provides the CompositionPlayer API, a powerful Player implementation for previewing video edits in real time. If your app lets users edit videos, such as applying effects, trimming, or compositing multiple input media items, CompositionPlayer helps you show an accurate preview of the output. This can be valuable in cases where you don't need to save the applied edits, or to validate the edits are configured as intended before committing them to the final video for export.

What is CompositionPlayer?

CompositionPlayer is a specialized implementation of the Player interface, designed specifically to play Composition objects. A Composition defines how input media assets, like video clips and audio tracks, are arranged and what audio and video effects should be applied to them. To learn more about the Composition API, see Define a Composition of media items.

The primary purpose of CompositionPlayer is to render this Composition, complete with all specified edits, in real-time, allowing users to see exactly how their edits will look before committing to the potentially time- and resource-consuming export process. The same Composition object can then be used with a Transformer instance for export, which you can learn more about in Exporting a Composition.

CompositionPlayer versus ExoPlayer

While both CompositionPlayer and ExoPlayer are Player implementations within Media3, they are optimized for different use-cases:

In essence, CompositionPlayer is most helpful when you need to render a complex Composition of media and effects, typically in an editing context. Use ExoPlayer for general-purpose playback of audio or video content, or to preview single-asset edits with setVideoEffects().

CompositionPlayer for preview

Integrating CompositionPlayer into your app involves a few key steps. First, use the Builder pattern to instantiate a CompositionPlayer, then set the Composition to be played:

val compositionPlayer = CompositionPlayer.Builder(context).build()
compositionPlayer.setComposition(composition)
compositionPlayer.prepare()
compositionPlayer.play()
CompositionPlayer.kt

For guidance on how to create a Composition, see the Create a Composition section.

Note that since CompositionPlayer implements the Player interface, you can then set the target output and control the player through standard Player methods.

Error handling

Attach a Player.Listener instance to your CompositionPlayer to react to playback events and errors. The onPlayerError() callback will also surface any issues coming from editing-specific components like the Composition or VideoGraph.Factory. Read the Player events documentation for more details.

Important Considerations

Some features and limitations to keep in mind as you use CompositionPlayer:

• Although CompositionPlayer is based on the Player interface, some of its behaviors differ from ExoPlayer since it depends on a Composition for playback. For example, CompositionPlayer only supports setting the repeat mode to REPEAT_MODE_OFF or REPEAT_MODE_ALL.
• By default, CompositionPlayer uses a SingleInputVideoGraph.Factory, but if your Composition uses more than one sequence with image or video items, you should use setVideoGraphFactory() when building your CompositionPlayer instance to instead use a MultipleInputVideoGraph.Factory. A SingleInputVideoGraph.Factory is sufficient if only one sequence has image or video items, and the others are audio-only.
• All the media items in your Composition should have a duration explicitly set, either with MediaItem.Builder.setImageDurationMs() for images, or with EditedMediaItem.Builder.setDurationUs() for audio or videos.

The following use cases are supported:

• Single-asset preview.
• Single-sequence (that is, sequential media items) preview.
• Single video sequence + Single audio sequence (for example, background audio) preview.

The following use cases are in active development:

• Multi-asset preview, including layouts such as picture-in-picture, side-by-side, and grid, where multiple video sequences are involved.
• Customizing the editing pipeline with a different graphics engine.

Feature requests

If you have any feature requests or feedback for CompositionPlayer, file an issue on the Media3 GitHub repository.