Premiers pas

Pour commencer à utiliser Transformer, procédez comme suit :

1. Ajoutez Media3 Transformer en tant que dépendance dans votre projet.
2. Créez un EditedMediaItem représentant le contenu multimédia à traiter et les modifications à lui appliquer.
3. Créez un Transformer décrivant la sortie requise et un écouteur pour les événements de fin et d'erreur.
4. Lancez l'opération d'exportation en transmettant le EditedMediaItem à modifier et un chemin d'accès de sortie. Pendant l'exportation, vous pouvez interroger la progression actuelle ou annuler l'opération.
5. Une fois l'exportation terminée, traitez le résultat selon vos besoins. Par exemple, vous pouvez partager le résultat avec une autre application ou l'importer sur un serveur.

Lisez la suite pour en savoir plus sur ces étapes, et consultez TransformerActivity dans l'application de démonstration Transformer pour obtenir un exemple complet.

Ajouter Media3 Transformer en tant que dépendance

Le moyen le plus simple de commencer à utiliser Transformer consiste à ajouter des dépendances Gradle à la bibliothèque dans le fichier build.gradle de votre module d'application :

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

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

où 1.11.1 est votre version préférée. Pour connaître la dernière version, consultez les notes de version.

Pour en savoir plus sur les modules de bibliothèque disponibles, consultez la page Google Maven AndroidX Media3.

Activer la compatibilité avec Java 8

Si ce n'est pas déjà fait, vous devez activer la compatibilité avec Java 8 dans tous les fichiers build.gradle qui dépendent de Transformer en ajoutant les éléments suivants à la section android :

compileOptions {
  targetCompatibility JavaVersion.VERSION_1_8
}

Lancer une transformation

Voici un exemple de création d'un EditedMediaItem pour supprimer l'audio d'un fichier d'entrée, puis de création et de configuration d'une instance Transformer pour exporter une vidéo H.265/HEVC, en envoyant le résultat vers 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)
GettingStarted.kt

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

Pour en savoir plus sur les éléments multimédias, consultez la page sur les éléments multimédias ExoPlayer. L'entrée peut être un flux progressif ou adaptatif, mais la sortie est toujours un flux progressif. Pour les entrées adaptatives, les pistes de résolution la plus élevée sont toujours sélectionnées pour la transformation. L'entrée peut être de n'importe quel format de conteneur compatible avec ExoPlayer, mais la sortie est toujours un fichier MP4.

Vous pouvez exécuter plusieurs opérations d'exportation de manière séquentielle sur la même instance Transformer, mais les exportations simultanées avec la même instance ne sont pas acceptées.

Pour savoir comment générer des contenus multimédias en combinant plusieurs entrées, consultez Édition multi-asset.

Remarque sur les threads

Les instances Transformer doivent être accessibles à partir d'un seul thread d'application, et les méthodes d'écoute sont appelées sur le même thread. Dans la plupart des cas, le thread d'application peut simplement être le thread principal de l'application. En interne, Transformer effectue son travail en arrière-plan et publie ses appels aux méthodes d'écoute sur le thread de l'application.

Écouter des événements

La méthode start est asynchrone. Elle est renvoyée immédiatement, et l'application est informée des événements via l'écouteur transmis au compilateur 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)
    }
  }
GettingStarted.kt

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 inclut des informations sur le fichier de sortie, y compris la taille du fichier et les débits binaires moyens pour l'audio et la vidéo, le cas échéant.

Recevoir des notifications sur la progression

Appelez Transformer.getProgress pour interroger la progression actuelle d'une transformation. La valeur renvoyée indique l'état de progression. Si l'état de progression est PROGRESS_STATE_AVAILABLE, l'élément ProgressHolder fourni est mis à jour avec le pourcentage de progression actuel. L'exemple suivant montre comment interroger régulièrement la progression d'une transformation, où la méthode updateProgressInUi peut être implémentée pour mettre à jour une barre de progression.

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

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

Annuler une transformation

Si l'utilisateur choisit de quitter un flux d'exportation, annulez l'opération d'exportation avec Transformer.cancel. Les ressources telles que les codecs vidéo matériels sont limitées, en particulier sur les appareils d'entrée de gamme. Il est donc important de libérer des ressources si la sortie n'est pas nécessaire.