Visualizar edições com CompositionPlayer

A biblioteca Jetpack Media3 fornece a API CompositionPlayer, uma implementação Player eficiente para visualizar edições de vídeo em tempo real. Se o app permitir que os usuários editem vídeos, como aplicar efeitos, cortar ou compor vários itens de mídia de entrada, o CompositionPlayer ajuda a mostrar uma prévia precisa da saída. Isso pode ser útil quando você não precisa salvar as edições aplicadas ou para validar se elas estão configuradas conforme o esperado antes de serem incluídas no vídeo final para exportação.

O que é o CompositionPlayer?

CompositionPlayer é uma implementação especializada da interface Player, projetada especificamente para reproduzir objetos Composition. Um Composition define como os recursos de mídia de entrada, como clipes de vídeo e faixas de áudio, são organizados e quais efeitos de áudio e vídeo devem ser aplicados a eles. Para saber mais sobre a API Composition, consulte Definir um Composition de itens de mídia.

O objetivo principal do CompositionPlayer é renderizar esse Composition, com todas as edições especificadas, em tempo real, permitindo que os usuários vejam exatamente como as edições vão ficar antes de se comprometer com o processo de exportação, que pode consumir tempo e recursos. O mesmo objeto Composition pode ser usado com uma instância Transformer para exportação. Saiba mais em Exportar um Composition.

CompositionPlayer x ExoPlayer

Embora CompositionPlayer e ExoPlayer sejam implementações de Player na Media3, elas são otimizadas para diferentes casos de uso:

Em essência, o CompositionPlayer é mais útil quando você precisa renderizar um Composition complexo de mídia e efeitos, geralmente em um contexto de edição. Use ExoPlayer para reprodução de uso geral de conteúdo de áudio ou vídeo ou para visualizar edições de um único recurso com setVideoEffects().

CompositionPlayer para visualização

A integração do CompositionPlayer ao seu app envolve algumas etapas principais. Primeiro, use o padrão Builder para instanciar um CompositionPlayer e defina o Composition a ser reproduzido:

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

Para orientações sobre como criar um Composition, consulte a seção Criar um Composition.

Como CompositionPlayer implementa a interface Player, é possível definir a saída de destino e controlar o player usando métodos Player padrão.

Tratamento de erros

Anexe uma instância Player.Listener ao seu CompositionPlayer para reagir a eventos e erros de reprodução. O callback onPlayerError() também vai mostrar problemas de componentes específicos de edição, como o Composition ou o VideoGraph.Factory. Leia a documentação Eventos do player para saber mais.

Considerações importantes

Alguns recursos e limitações a serem considerados ao usar o CompositionPlayer:

• Embora CompositionPlayer seja baseado na interface Player, alguns dos comportamentos dele são diferentes de ExoPlayer, já que ele depende de um Composition para a reprodução. Por exemplo, CompositionPlayer só permite definir o modo de repetição como REPEAT_MODE_OFF ou REPEAT_MODE_ALL.
• Por padrão, o CompositionPlayer usa um SingleInputVideoGraph.Factory, mas se a composição usar mais de uma sequência com itens de imagem ou vídeo, use setVideoGraphFactory() ao criar a instância CompositionPlayer para usar um MultipleInputVideoGraph.Factory. Um SingleInputVideoGraph.Factory é suficiente se apenas uma sequência tiver itens de imagem ou vídeo e as outras forem apenas de áudio.
• Todos os itens de mídia na sua composição precisam ter uma duração definida explicitamente, seja com MediaItem.Builder.setImageDurationMs() para imagens ou com EditedMediaItem.Builder.setDurationUs() para áudio ou vídeos.

Os seguintes casos de uso são compatíveis:

• Prévia de um único recurso.
• Visualização de sequência única (ou seja, itens de mídia sequenciais).
• Prévia de uma sequência de vídeo + uma sequência de áudio (por exemplo, áudio de fundo).

Os seguintes casos de uso estão em desenvolvimento ativo:

• Prévia de vários recursos, incluindo layouts como picture-in-picture, lado a lado e grade, em que várias sequências de vídeo estão envolvidas.
• Personalizar o pipeline de edição com um mecanismo gráfico diferente.

Solicitações de recursos

Se você tiver solicitações de recursos ou feedback para CompositionPlayer, registre um problema no repositório do Media3 no GitHub.