Definir uma composição de itens de mídia

A biblioteca Media3 Transformer oferece um conjunto de ferramentas para editar e manipular mídias. Um componente principal para edição de vários recursos é a API Composition. Com ela, é possível organizar vários itens de mídia de entrada, como videoclipes, imagens e faixas de áudio, em uma única estrutura coerente que pode ser processada, visualizada ou exportada. Um Composition pode ser considerado uma linha do tempo que contém uma ou mais sequências de mídia. Cada sequência (definida por um EditedMediaItemSequence) contém itens de mídia individuais (definidos como instâncias EditedMediaItem). Transformações e efeitos podem ser aplicados a um EditedMediaItem individual ou a um Composition inteiro.

A estrutura de um objeto de composição
A estrutura de um objeto Composition

Um Composition é o ponto de entrada para vários casos de uso com o Media3 Transformer, como:

  • Combinar sequencialmente recursos de áudio, imagem e vídeo.
  • Sobrepor um vídeo a outro (picture-in-picture).
  • Misturar uma faixa de áudio em segundo plano com uma sequência de vídeo.
  • Aplicar efeitos visuais ou de áudio em toda a edição.
  • Processamento de cenários complexos, como vídeos em HDR.

Este guia se concentra em como definir e criar objetos Composition, incluindo as principais classes envolvidas, como criar composições básicas e mais complexas com sequências únicas ou múltiplas e como aplicar efeitos em diferentes níveis.

Principais conceitos e classes

Para usar a API Composition de forma eficaz, é importante entender as principais classes envolvidas na criação de uma composição de mídia:

Effects:

  • Finalidade:um objeto Effects é uma coleção de processadores de áudio e efeitos de vídeo.
  • Como é usado:no contexto de um Composition, um Effects pode ser definido em instâncias individuais de EditedMediaItem para modificar clipes específicos ou no Composition como um todo (normalmente para efeitos Presentation que afetam a saída final, como ajustar a resolução da tela ou a taxa de frames).
  • Por que é importante:o Effects é o mecanismo para aplicar transformações, filtros e outros processamentos à sua mídia no nível de item individual e no nível de composição geral. Para mais informações, consulte Transformations.

EditedMediaItem:

  • Finalidade:essa classe representa um único item de mídia (como um vídeo, uma imagem ou um arquivo de áudio) e as edições que serão aplicadas a ele.
  • Como é usado:um EditedMediaItem agrupa um MediaItem (que aponta para o conteúdo de mídia real) com um objeto Effects.
  • Por que isso é importante:esse é o elemento básico fundamental da sua composição. Com ele, você define exatamente qual mídia incluir e como cada parte individual deve aparecer e soar antes de ser combinada com outras em uma sequência.

EditedMediaItemSequence:

  • Finalidade:representa uma sequência linear de objetos EditedMediaItem que devem ser reproduzidos um após o outro.
  • Como é usado:um EditedMediaItemSequence é criado com uma lista de objetos EditedMediaItem. Cada sequência em um Composition é semelhante a uma faixa ou camada em uma linha do tempo de edição de vídeo com várias faixas. Por exemplo, uma sequência pode conter seus clipes de vídeo principais, enquanto outra, com sobreposição de tempo, pode conter clipes de vídeo para serem sobrepostos na primeira. Outra sequência ainda pode conter apenas uma faixa de áudio para música de fundo.
  • Por que isso é importante:um EditedMediaItemSequence agrupa itens de mídia relacionados que devem seguir uns aos outros diretamente. Ao usar várias sequências, você pode criar arranjos mais complexos, como camadas de áudio ou sobreposições visuais.

Composition:

  • Objetivo:é o objeto de nível superior que representa toda a linha do tempo da mídia a ser processada. Ele funciona como um contêiner para todas as sequências de mídia e configurações ou efeitos globais que se aplicam a toda a saída.
  • Como é usado:um Composition consiste em um ou mais objetos EditedMediaItemSequence. Você também pode aplicar efeitos em toda a composição e definir configurações globais, como o modo HDR, diretamente no Composition. Se um Composition contiver vários objetos EditedMediaItemSequence, essas sequências poderão ser organizadas para serem reproduzidas sequencialmente ou se sobrepor no tempo, permitindo layouts sobrepostos, como picture-in-picture ou transições de uma sequência para outra.
  • Por que é importante:um Composition define a estrutura geral da mídia de entrada a ser processada e é um objeto comum que pode ser usado para visualizar edições com um CompositionPlayer e exportar um vídeo de saída com edições aplicadas usando Transformer.

Criar e exportar um Composition

Confira um exemplo de como criar e exportar um recurso de vídeo com dois clipes editados e uma faixa de áudio sobreposta:

Kotlin

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

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

val videoSequence = EditedMediaItemSequence.withAudioAndVideoFrom(listOf(video1, video2))

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

val backgroundAudioSequence =
  EditedMediaItemSequence.withAudioFrom(listOf(backgroundAudio))
    .buildUpon()
    .setIsLooping(true) // Loop audio track through duration of videoSequence
    .build()

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

transformer.start(composition, filePath)

Java

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

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

EditedMediaItemSequence videoSequence =
    EditedMediaItemSequence.withAudioAndVideoFrom(ImmutableList.of(video1, video2));

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

EditedMediaItemSequence backgroundAudioSequence =
    EditedMediaItemSequence.withAudioFrom(ImmutableList.of(backgroundAudio))
        .buildUpon()
        .setIsLooping(true) // Loop audio track through duration of videoSequence
        .build();

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

transformer.start(composition, filePath);

Exemplos de casos de uso compatíveis

Esta é uma lista não exaustiva de casos de uso que a API Transformer aceita com Composition:

  • Combinar sequencialmente recursos de áudio, imagem e vídeo.
  • Adicionar áudio de fundo a um recurso de vídeo.
  • Adicionar efeitos a uma composição.
  • Mapeamento de tons da entrada HDR para SDR para gerar uma saída SDR com melhor qualidade visual.

Limitações atuais

As sequências em uma composição precisam atender às condições descritas em Transformer.start(). Além disso, as seguintes operações ainda não são compatíveis ao trabalhar com composições:

  • Fundir faixas de áudio ou vídeo

Solicitações de recursos

Se você tiver solicitações de recursos para as APIs Transformer, registre um problema no repositório do Media3 no GitHub.