Como começar

Para começar a usar o Transformer, siga estas etapas:

1. Adicione o Media3 Transformer como uma dependência no seu projeto.
2. Crie um EditedMediaItem que represente a mídia a ser processada e edite para aplicar a ela.
3. Crie um Transformer, descrevendo a saída necessária e um listener para eventos de conclusão e erro.
4. Inicie a operação de exportação, transmitindo o EditedMediaItem para edição e um caminho de saída. Durante a exportação, é possível consultar o progresso atual ou cancelar a operação.
5. Quando a exportação for concluída, processe a saída conforme necessário. Por exemplo, é possível compartilhar a saída com outro app ou fazer upload dela em um servidor.

Continue lendo para saber mais sobre essas etapas e conferir TransformerActivity no app de demonstração do transformador (em inglês) para um exemplo completo.

Adicionar o Media3 Transformer como uma dependência

A maneira mais fácil de começar a usar o Transformer é adicionar dependências do Gradle à biblioteca no arquivo build.gradle do módulo do app:

implementation("androidx.media3:media3-transformer:1.3.1")
implementation("androidx.media3:media3-effect:1.3.1")
implementation("androidx.media3:media3-common:1.3.1")

implementation "androidx.media3:media3-transformer:1.3.1"
implementation "androidx.media3:media3-effect:1.3.1"
implementation "androidx.media3:media3-common:1.3.1"

em que 1.3.1 é sua versão preferida. Para encontrar a versão mais recente, consulte as notas da versão.

Saiba mais sobre os módulos de biblioteca disponíveis na página Google Maven AndroidX Media3.

Ativar a compatibilidade com Java 8

Se ainda não estiver ativado, será necessário ativar a compatibilidade com o Java 8 em todos os arquivos build.gradle que dependem do Transformer adicionando o seguinte à seção android:

compileOptions {
  targetCompatibility JavaVersion.VERSION_1_8
}

Iniciar uma transformação

Veja um exemplo de como criar um EditedMediaItem para remover áudio de um arquivo de entrada e, em seguida, criar e configurar uma instância de Transformer para exportar vídeo H.265/HEVC, gerando o resultado em outputPath.

val inputMediaItem = MediaItem.fromUri("path_to_input_file")
val editedMediaItem =
    EditedMediaItem.Builder(inputMediaItem).setRemoveAudio(true).build()
val transformer = Transformer.Builder(context)
    .setVideoMimeType(MimeTypes.VIDEO_H265)
    .addListener(transformerListener)
    .build()
transformer.start(editedMediaItem, outputPath)

MediaItem inputMediaItem = MediaItem.fromUri("path_to_input_file");
EditedMediaItem editedMediaItem =
    new EditedMediaItem.Builder(inputMediaItem).setRemoveAudio(true).build();
Transformer transformer =
    new Transformer.Builder(context)
        .setVideoMimeType(MimeTypes.VIDEO_H265)
        .addListener(transformerListener)
        .build();
transformer.start(editedMediaItem, outputPath);

Para saber mais sobre itens de mídia, consulte a página de itens de mídia do ExoPlayer (link em inglês). A entrada pode ser um stream progressivo ou adaptativo, mas a saída é sempre um stream progressivo. Para entradas adaptáveis, as faixas de maior resolução são sempre selecionadas para a transformação. A entrada pode ter qualquer formato de contêiner compatível com o ExoPlayer, mas a saída é sempre um arquivo MP4.

É possível executar várias operações de exportação sequencialmente na mesma instância Transformer, mas exportações simultâneas com a mesma instância não são aceitas.

Observação sobre linhas de execução

As instâncias do Transformer precisam ser acessadas em uma única linha de execução do aplicativo, e os métodos de listener são chamados na mesma linha de execução. Na maioria dos casos, a linha de execução do aplicativo pode ser apenas a linha de execução principal. Internamente, o Transformer faz o trabalho em segundo plano e publica as chamadas para métodos de listener na linha de execução do aplicativo.

Ouvir eventos

O método start é assíncrono. Ela retorna imediatamente, e o app é notificado sobre os eventos pelo listener transmitido ao builder Transformer.

val transformerListener: Transformer.Listener =
    object : Transformer.Listener {
  override fun onCompleted(composition: Composition, result: ExportResult) {
    playOutput()
  }

  override fun onError(composition: Composition, result: ExportResult,
                       exception: ExportException) {
    displayError(exception)
  }
}

Transformer.Listener transformerListener =
    new Transformer.Listener() {
      @Override
      public void onCompleted(Composition composition, ExportResult result) {
        playOutput();
      }

      @Override
      public void onError(Composition composition, ExportResult result,
          ExportException exception) {
        displayError(exception);
      }
    };

ExportResult inclui informações sobre o arquivo de saída, como o tamanho do arquivo e as taxas de bits médias para áudio e vídeo, conforme aplicável.

Receber atualizações de progresso

Chame Transformer.getProgress para consultar o progresso atual de uma transformação. O valor retornado indica o estado do progresso. Se o estado de progresso for PROGRESS_STATE_AVAILABLE, o ProgressHolder fornecido será atualizado com a porcentagem de progresso atual. O exemplo a seguir mostra como consultar periodicamente o progresso de uma transformação, em que o método updateProgressInUi pode ser implementado para atualizar uma barra de progresso.

transformer.start(inputMediaItem, outputPath)
val progressHolder = ProgressHolder()
mainHandler.post(
    object : Runnable {
      override fun run() {
        val progressState: @ProgressState Int = transformer.getProgress(progressHolder)
        updateProgressInUi(progressState, progressHolder)
        if (progressState != Transformer.PROGRESS_STATE_NOT_STARTED) {
          mainHandler.postDelayed(/* r= */this,  /* delayMillis= */500)
        }
      }
    }
)

transformer.start(inputMediaItem, outputPath);
ProgressHolder progressHolder = new ProgressHolder();
mainHandler.post(
    new Runnable() {
      @Override
      public void run() {
        @Transformer.ProgressState int progressState = transformer.getProgress(progressHolder);
        updateProgressInUi(progressState, progressHolder);
        if (progressState != PROGRESS_STATE_NOT_STARTED) {
          mainHandler.postDelayed(/* r= */ this, /* delayMillis= */ 500);
        }
      }
    });

Cancelar uma transformação

Se o usuário optar por sair de um fluxo de exportação, cancele a operação de exportação com Transformer.cancel. Recursos como codecs de vídeo de hardware são limitados, especialmente em dispositivos mais simples. Por isso, é importante fazer isso para liberar recursos caso a saída não seja necessária.