Erste Schritte

Der Einstieg in Transformer umfasst die folgenden Schritte:

1. Fügen Sie dem Projekt Media3 Transformer als Abhängigkeit hinzu.
2. Erstellen Sie eine EditedMediaItem für die zu verarbeitenden Medien und die Änderungen, die darauf angewendet werden sollen.
3. Erstellen Sie einen Transformer, der die erforderliche Ausgabe beschreibt, sowie einen Listener für Abschluss- und Fehlerereignisse.
4. Starten Sie den Exportvorgang und übergeben Sie den EditedMediaItem zum Bearbeiten sowie einen Ausgabepfad. Während des Exports können Sie den aktuellen Fortschritt abfragen oder den Vorgang abbrechen.
5. Wenn der Export abgeschlossen ist, bearbeiten Sie die Ausgabe nach Bedarf. Sie können die Ausgabe beispielsweise für eine andere Anwendung freigeben oder auf einen Server hochladen.

Weitere Informationen zu diesen Schritten finden Sie im Folgenden. Ein vollständiges Beispiel finden Sie unter TransformerActivity in der Transformer-Demo-App.

Media3 Transformer als Abhängigkeit hinzufügen

Am einfachsten gelingt der Einstieg in Transformer, wenn Sie der Bibliothek in der Datei build.gradle Ihres App-Moduls Gradle-Abhängigkeiten hinzufügen:

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"

wobei 1.3.1 Ihre bevorzugte Version ist. Die aktuelle Version finden Sie in den Versionshinweisen.

Weitere Informationen zu den verfügbaren Bibliotheksmodulen finden Sie auf der Google Maven-Seite AndroidX Media3.

Java 8-Unterstützung aktivieren

Falls noch nicht geschehen, müssen Sie die Java 8-Unterstützung in allen build.gradle-Dateien aktivieren, die von Transformer abhängig sind. Fügen Sie dazu im Abschnitt android Folgendes hinzu:

compileOptions {
  targetCompatibility JavaVersion.VERSION_1_8
}

Transformation starten

Hier sehen Sie ein Beispiel, wie Sie ein EditedMediaItem erstellen, um Audio aus einer Eingabedatei zu entfernen, und dann eine Transformer-Instanz erstellen und konfigurieren, um H.265/HEVC-Video zu exportieren und das Ergebnis an outputPath auszugeben.

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);

Weitere Informationen zu Medienelementen finden Sie auf der Seite zu ExoPlayer-Medienelementen. Die Eingabe kann ein progressiver oder adaptiver Stream sein, die Ausgabe ist jedoch immer ein progressiver Stream. Bei adaptiven Eingaben werden immer die Tracks mit der höchsten Auflösung für die Transformation ausgewählt. Die Eingabe kann jedes Containerformat haben, das von ExoPlayer unterstützt wird. Die Ausgabe ist jedoch immer eine MP4-Datei.

Sie können mehrere Exportvorgänge hinter derselben Transformer-Instanz ausführen, gleichzeitige Exporte mit derselben Instanz werden jedoch nicht unterstützt.

Hinweis zum Threading

Auf Transformer-Instanzen muss von einem einzelnen Anwendungsthread aus zugegriffen werden und die Listener-Methoden werden im selben Thread aufgerufen. In den meisten Fällen kann der Anwendungsthread einfach der Hauptthread der Anwendung sein. Intern führt Transformer seine Arbeit im Hintergrund aus und sendet seine Aufrufe an Listener-Methoden im Anwendungsthread.

Auf Ereignisse warten

Die Methode start ist asynchron. Sie wird sofort zurückgegeben und die Anwendung wird über den Listener, der an den Transformer-Builder übergeben wurde, über Ereignisse benachrichtigt.

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 enthält Informationen zur Ausgabedatei, einschließlich der Dateigröße und der durchschnittlichen Bitraten für Audio und Video, sofern zutreffend.

Fortschrittsupdates erhalten

Rufen Sie Transformer.getProgress auf, um den aktuellen Fortschritt einer Transformation abzufragen. Der zurückgegebene Wert zeigt den Fortschrittsstatus an. Wenn der Fortschrittsstatus PROGRESS_STATE_AVAILABLE ist, wird die angegebene ProgressHolder mit dem aktuellen Fortschrittsprozentsatz aktualisiert. Das folgende Beispiel zeigt, wie Sie den Fortschritt einer Transformation regelmäßig abfragen. Dabei kann die Methode updateProgressInUi implementiert werden, um einen Fortschrittsbalken zu aktualisieren.

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);
        }
      }
    });

Transformation abbrechen

Wenn der Nutzer einen Exportvorgang zurücknimmt, brechen Sie den Exportvorgang mit Transformer.cancel ab. Ressourcen wie Hardware-Video-Codecs sind begrenzt, insbesondere auf Low-End-Geräten. Daher ist es wichtig, dies zu tun, um Ressourcen freizugeben, wenn die Ausgabe nicht benötigt wird.