Prévisualiser les modifications avec CompositionPlayer

La bibliothèque Jetpack Media3 fournit l'CompositionPlayer API, une implémentation Player puissante pour prévisualiser les modifications vidéo en temps réel. Si votre application permet aux utilisateurs de modifier des vidéos, par exemple en appliquant des effets, en les découpant ou en composant plusieurs éléments multimédias d'entrée, CompositionPlayer vous aide à afficher un aperçu précis de la sortie. Cela peut être utile lorsque vous n'avez pas besoin d'enregistrer les modifications appliquées ou pour vérifier que les modifications sont configurées comme prévu avant de les valider dans la vidéo finale à exporter.

Qu'est-ce que CompositionPlayer ?

CompositionPlayer est une implémentation spécialisée de l' interface Player, conçue spécifiquement pour lire des objets Composition. Une Composition définit la manière dont les éléments multimédias d'entrée, tels que les extraits vidéo et les pistes audio, sont organisés, ainsi que les effets audio et vidéo à leur appliquer. Pour en savoir plus sur l'API Composition, consultez Définir un Composition d'éléments multimédias.

L'objectif principal de CompositionPlayer est de rendre cette Composition, avec toutes les modifications spécifiées, en temps réel, ce qui permet aux utilisateurs de voir exactement à quoi ressembleront leurs modifications avant de s'engager dans le processus d'exportation, qui peut prendre du temps et consommer des ressources. Le même objet Composition peut ensuite être utilisé avec une instance Transformer pour l'exportation. Pour en savoir plus, consultez Exporter une Composition.

CompositionPlayer et ExoPlayer

Bien que CompositionPlayer et ExoPlayer soient des implémentations Player dans Media3, elles sont optimisées pour différents cas d'utilisation :

En substance, CompositionPlayer est plus utile lorsque vous devez afficher une complexe Composition de médias et d'effets, généralement dans un contexte de modification. Utilisez ExoPlayer pour la lecture à usage général de contenus audio ou vidéo, ou pour prévisualiser des modifications d'un seul élément avec setVideoEffects().

CompositionPlayer pour la prévisualisation

L'intégration de CompositionPlayer dans votre application implique quelques étapes clés. Tout d'abord, utilisez le modèle Builder pour instancier un CompositionPlayer, puis définissez le Composition à lire :

val compositionPlayer = CompositionPlayer.Builder(context).build()
compositionPlayer.setComposition(composition)
compositionPlayer.prepare()
compositionPlayer.play()
CompositionPlayer.kt

Pour savoir comment créer un Composition, consultez la Créer un Composition section.

Notez que, comme CompositionPlayer implémente l'interface Player, vous pouvez ensuite définir la sortie cible et contrôler le lecteur à l'aide des méthodes Player standards.

Gestion des exceptions

Associez une Player.Listener instance à votre CompositionPlayer pour réagir aux événements et aux erreurs de lecture. Le rappel onPlayerError() mettra également en évidence les problèmes provenant de composants spécifiques à la modification, tels que Composition ou VideoGraph.Factory. Pour en savoir plus, consultez la documentation sur les événements du lecteur.

Remarques importantes

Voici quelques fonctionnalités et limites à prendre en compte lorsque vous utilisez CompositionPlayer :

• Bien que CompositionPlayer soit basé sur l'interface Player, certains de ses comportements diffèrent d'ExoPlayer, car il dépend d'une Composition pour la lecture. Par exemple, CompositionPlayer n'accepte que la définition du mode de répétition sur REPEAT_MODE_OFF ou REPEAT_MODE_ALL.
• Par défaut, CompositionPlayer utilise une SingleInputVideoGraph.Factory, mais si votre composition utilise plusieurs séquences avec des éléments d'image ou vidéo, vous devez utiliser setVideoGraphFactory() lorsque vous créez votre CompositionPlayer instance pour utiliser à la place une MultipleInputVideoGraph.Factory. Une SingleInputVideoGraph.Factory suffit si une seule séquence comporte des éléments d'image ou vidéo, et que les autres sont uniquement audio.
• La durée de tous les éléments multimédias de votre composition doit être définie explicitement, soit avec MediaItem.Builder.setImageDurationMs() pour les images, soit avec EditedMediaItem.Builder.setDurationUs() pour l'audio ou les vidéos.

Les cas d'utilisation suivants sont compatibles :

• Aperçu d'un seul élément.
• Aperçu d'une seule séquence (c'est-à-dire des éléments multimédias séquentiels).
• Aperçu d'une seule séquence vidéo + une seule séquence audio (par exemple, audio d'arrière-plan).

Les cas d'utilisation suivants sont en cours de développement actif :

• Aperçu de plusieurs éléments, y compris des mises en page telles que l'image dans l'image, côte à côte et la grille, où plusieurs séquences vidéo sont impliquées.
• Personnalisation du pipeline de modification avec un moteur graphique différent.

Demandes de fonctionnalités

Si vous avez des demandes de fonctionnalités ou des commentaires concernant CompositionPlayer, signalez un problème dans le dépôt GitHub Media3.