Définir une composition d'éléments multimédias

La bibliothèque Media3 Transformer fournit une suite d'outils permettant de modifier et de manipuler des contenus multimédias. L'API Composition est un composant essentiel pour l'édition multi-éléments. Cette API vous permet d'organiser plusieurs éléments multimédias d'entrée, tels que des extraits vidéo, des images et des pistes audio, dans une structure unique et cohérente qui peut ensuite être traitée, prévisualisée ou exportée. Une Composition peut être considérée comme une timeline contenant une ou plusieurs séquences de contenus multimédias. Chaque séquence (définie par un EditedMediaItemSequence) contient des éléments multimédias individuels (définis comme des instances EditedMediaItem). Les transformations et les effets peuvent être appliqués à un EditedMediaItem individuel ou à un Composition entier.

Structure d'un objet Composition
Structure d'un objet Composition

Un Composition est votre point d'entrée pour divers cas d'utilisation avec Media3 Transformer, tels que :

  • Combinaison séquentielle de composants audio, d'image et vidéo.
  • Superposer une vidéo sur une autre (picture-in-picture)
  • Mixer une piste audio de fond avec une séquence vidéo.
  • Appliquer des effets visuels ou audio à l'ensemble d'un contenu modifié.
  • Gérer des scénarios complexes comme le traitement des vidéos HDR.

Ce guide explique comment définir et créer des objets Composition, y compris les classes clés impliquées, comment créer des compositions de base et plus complexes avec une ou plusieurs séquences, et comment appliquer des effets à différents niveaux.

Concepts et classes clés

Pour utiliser efficacement l'API Composition, il est important de comprendre les principales classes impliquées dans la création d'une composition média :

Effects :

  • Objectif : un objet Effects est une collection de processeurs audio et d'effets vidéo.
  • Utilisation : dans le contexte d'un Composition, un Effects peut être défini sur des instances EditedMediaItem individuelles pour modifier des clips spécifiques, ou sur le Composition dans son ensemble (généralement pour les effets Presentation qui affectent le résultat final, comme l'ajustement de la résolution d'affichage ou de la fréquence d'images).
  • Pourquoi est-ce important ? Effects est le mécanisme permettant d'appliquer des transformations, des filtres et d'autres traitements à vos contenus multimédias, à la fois au niveau de chaque élément et au niveau de la composition globale. Pour en savoir plus, consultez Transformations.

EditedMediaItem :

  • Objectif : cette classe représente un seul élément multimédia (comme un fichier vidéo, image ou audio) et les modifications à lui appliquer.
  • Utilisation : un EditedMediaItem regroupe un MediaItem (qui pointe vers le contenu multimédia réel) avec un objet Effects.
  • Pourquoi est-ce important ? Il s'agit du composant de base de votre composition. Il vous permet de définir précisément les éléments multimédias à inclure et l'apparence et le son de chacun d'eux avant qu'ils ne soient combinés à d'autres dans une séquence.

EditedMediaItemSequence :

  • Objectif : représente une séquence linéaire d'objets EditedMediaItem destinés à être lus les uns après les autres.
  • Utilisation : un EditedMediaItemSequence est construit avec une liste d'objets EditedMediaItem. Chaque séquence d'un Composition est semblable à une piste ou un calque dans une timeline de montage vidéo multipiste. Par exemple, une séquence peut contenir vos principaux extraits vidéo, tandis qu'une autre séquence, qui se chevauche dans le temps, peut contenir des extraits vidéo à superposer sur la première. Une autre séquence peut ne contenir qu'une piste audio pour la musique de fond.
  • Pourquoi est-ce important ? Un EditedMediaItemSequence regroupe les éléments multimédias associés qui doivent se suivre directement. En utilisant plusieurs séquences, vous pouvez créer des arrangements plus complexes, comme superposer des éléments audio ou créer des incrustations visuelles.

Composition :

  • Objectif : il s'agit de l'objet de premier niveau qui représente l'intégralité de la timeline du contenu multimédia à traiter. Il sert de conteneur pour toutes les séquences multimédias et tous les paramètres ou effets généraux qui s'appliquent à l'ensemble du résultat.
  • Utilisation : un Composition se compose d'un ou de plusieurs objets EditedMediaItemSequence. Vous pouvez également appliquer des effets à l'ensemble de la composition et définir des configurations globales telles que le mode HDR directement sur Composition. Si un Composition contient plusieurs objets EditedMediaItemSequence, ces séquences peuvent être organisées pour être lues de manière séquentielle ou se chevaucher dans le temps, ce qui permet de superposer des mises en page comme le picture-in-picture ou les transitions d'une séquence à une autre.
  • Pourquoi est-ce important ? Un Composition définit la structure globale du média d'entrée à traiter. Il s'agit d'un objet courant que vous pouvez utiliser à la fois pour prévisualiser les modifications avec un CompositionPlayer et pour exporter une vidéo de sortie avec les modifications appliquées à l'aide de Transformer.

Créer et exporter un Composition

Voici un exemple de création d'un élément vidéo composé de deux extraits vidéo modifiés, superposés à une piste audio, et de son exportation :

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

Exemples de cas d'utilisation acceptés

Voici une liste non exhaustive de cas d'utilisation que l'API Transformer prend en charge avec Composition :

  • Combinaison séquentielle de composants audio, d'image et vidéo.
  • Ajouter un son de fond à un élément vidéo
  • Ajouter des effets à une composition
  • Mappage de tonalité de l'entrée HDR vers SDR pour générer une sortie SDR de meilleure qualité visuelle.

Limites actuelles

Les séquences d'une composition doivent respecter les conditions décrites dans Transformer.start(). De plus, les opérations suivantes ne sont pas encore prises en charge lorsque vous travaillez avec des compositions :

  • Fondu enchaîné des pistes vidéo ou audio

Demandes de fonctionnalités

Si vous avez des demandes de fonctionnalités pour les API Transformer, créez un problème dans le dépôt GitHub Media3.