Guida introduttiva

Per iniziare a utilizzare Transformer:

  1. Aggiungi Media3 Transformer come dipendenza al tuo progetto.
  2. Crea un EditedMediaItem che rappresenti i contenuti multimediali da elaborare e le modifiche da applicare.
  3. Crea un Transformer che descriva l'output richiesto e un listener per gli eventi di completamento ed errore.
  4. Avvia l'operazione di esportazione, passando l'EditedMediaItem da modificare e un percorso di output. Durante l'esportazione, puoi eseguire una query sullo stato di avanzamento attuale o annullare l'operazione.
  5. Al termine dell'esportazione, gestisci l'output in base alle esigenze. Ad esempio, puoi condividere l'output con un'altra app o caricarlo su un server.

Continua a leggere per maggiori dettagli su questi passaggi e consulta TransformerActivity nell' app demo di Transformer per un esempio completo.

Aggiungere Media3 Transformer come dipendenza

Il modo più semplice per iniziare a utilizzare Transformer è aggiungere le dipendenze Gradle alla libreria nel file build.gradle del modulo dell'app:

Kotlin

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

Alla moda

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

dove 1.10.0 è la versione che preferisci. L'ultima versione è disponibile nelle note di rilascio.

Per ulteriori informazioni sui moduli della libreria disponibili, consulta la pagina Google Maven AndroidX Media3.

Attivare il supporto di Java 8

Se non è già attivo, devi attivare il supporto di Java 8 in tutti i file build.gradle che dipendono da Transformer aggiungendo quanto segue alla sezione android:

compileOptions {
  targetCompatibility JavaVersion.VERSION_1_8
}

Avviare una trasformazione

Ecco un esempio di creazione di un EditedMediaItem per rimuovere l'audio di un file di input, quindi di creazione e configurazione di un'istanza Transformer per esportare video H.265/HEVC, generando l'output in outputPath.

Kotlin

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)
GettingStarted.kt

Java

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);
GettingStarted.java

Per ulteriori informazioni sugli elementi multimediali, consulta la pagina Elementi multimediali di ExoPlayer. L'input può essere uno stream progressivo o adattivo, ma l'output è sempre uno stream progressivo. Per gli input adattivi, per la trasformazione vengono sempre selezionate le tracce con la risoluzione più alta. L'input può essere di qualsiasi formato container supportato da ExoPlayer, ma l'output è sempre un file MP4.

Puoi eseguire più operazioni di esportazione in sequenza sulla stessa istanza Transformer, ma le esportazioni simultanee con la stessa istanza non sono supportate.

Una nota sui thread

È necessario accedere alle istanze di Transformer da un singolo thread dell'applicazione e i metodi del listener vengono chiamati sullo stesso thread. Nella maggior parte dei casi, il thread dell'applicazione può essere semplicemente il thread principale dell'applicazione. Internamente, Transformer esegue il lavoro in background e pubblica le chiamate ai metodi del listener sul thread dell'applicazione.

Ascoltare gli eventi

Il metodo start è asincrono. Viene restituito immediatamente e l'app riceve una notifica degli eventi tramite il listener passato al builder Transformer.

Kotlin

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)
    }
  }
GettingStarted.kt

Java

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);
      }
    };
GettingStarted.java

ExportResult include informazioni sul file di output, tra cui le dimensioni del file e le velocità in bit medie per audio e video, a seconda dei casi.

Ricevere aggiornamenti sullo stato di avanzamento

Chiama Transformer.getProgress per eseguire una query sullo stato di avanzamento attuale di una trasformazione. Il valore restituito indica lo stato di avanzamento. Se lo stato di avanzamento è PROGRESS_STATE_AVAILABLE, il ProgressHolder fornito viene aggiornato con la percentuale di avanzamento attuale. L'esempio seguente mostra come eseguire periodicamente una query sullo stato di avanzamento di una trasformazione, in cui il metodo updateProgressInUi può essere implementato per aggiornare una barra di avanzamento.

Kotlin

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)
      }
    }
  }
)
GettingStarted.kt

Java

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);
        }
      }
    });
GettingStarted.java

Annullare una trasformazione

Se l'utente sceglie di uscire da un flusso di esportazione, annulla l'operazione di esportazione con Transformer.cancel. Le risorse come i codec video hardware sono limitate, soprattutto sui dispositivi di fascia bassa, quindi è importante farlo per liberare risorse se l'output non è necessario.