Les API Transformer de Jetpack Media3 sont conçues pour rendre l'édition multimédia performante et fiable. Transformer est compatible avec un certain nombre d'opérations, y compris les suivantes:
- Modifier une vidéo (couper, mettre à l'échelle et pivoter)
- Ajouter des effets tels que des superpositions et des filtres
- Traitement de formats spéciaux tels que la technologie HDR et les vidéos au ralenti
- Exporter un élément multimédia après avoir appliqué des modifications
Cette page présente certains des principaux cas d'utilisation couverts par l'outil Transformer. Pour en savoir plus, consultez nos guides complets sur Media3 Transformer.
Premiers pas
Pour commencer, ajoutez une dépendance aux modules Transformer, Effect et Common de Jetpack Media3:
implementation "androidx.media3:media3-transformer:1.3.1" implementation "androidx.media3:media3-effect:1.3.1" implementation "androidx.media3:media3-common:1.3.1"
Veillez à remplacer 1.3.1
par votre version préférée de la bibliothèque. Vous pouvez consulter les notes de version pour accéder à la dernière version.
Classes importantes
Classe | Finalité |
---|---|
Transformer |
Démarrer et arrêter des transformations, et vérifier les mises à jour de la progression d'une transformation en cours d'exécution |
EditedMediaItem |
Représente un élément multimédia à traiter et les modifications à lui appliquer. |
Effects |
Collection d'effets audio et vidéo. |
Configurer la sortie
Avec Transformer.Builder
, vous pouvez désormais spécifier les répertoires videoMimeType
et audioMimetype
en définissant la fonction sans avoir à créer un objet TransformationRequest
.
Transcodage entre formats
Le code suivant montre comment configurer un objet Transformer
pour générer une vidéo H.265/AVC et des fichiers audio AAC:
Kotlin
val transformer = Transformer.Builder(context) .setVideoMimeType(MimeTypes.VIDEO_H265) .setAudioMimeType(MimeTypes.AUDIO_AAC) .build()
Java
Transformer transformer = new Transformer.Builder(context) .setVideoMimeType(MimeTypes.VIDEO_H265) .setAudioMimeType(MimeTypes.AUDIO_AAC) .build();
Si le format du support d'entrée correspond déjà à la requête de transformation pour l'audio ou la vidéo, Transformer passe automatiquement à la transmuxing, c'est-à-dire en copiant les échantillons compressés du conteneur d'entrée vers le conteneur de sortie sans y apporter de modifications. Cela évite les coûts de calcul et la perte potentielle de qualité du décodage et du réencodage du même format.
Définir le mode HDR
Si le fichier multimédia d'entrée est au format HDR, vous avez le choix entre plusieurs modes de traitement des informations HDR par Transformer. Vous souhaiterez probablement utiliser HDR_MODE_KEEP_HDR
ou HDR_MODE_TONE_MAP_HDR_TO_SDR_USING_OPEN_GL
.
HDR_MODE_KEEP_HDR |
HDR_MODE_TONE_MAP_HDR_TO_SDR_USING_OPEN_GL |
|
---|---|---|
Description | Conserver les données HDR, c'est-à-dire que le format de sortie HDR est identique au format d'entrée HDR. | Une entrée HDR de type "tonemap" en SDR à l'aide d'un outil de mappage de tons OpenGL, ce qui signifie que le format de sortie est en SDR. |
Assistance | Compatible à partir d'un niveau d'API 31 pour les appareils qui intègrent un encodeur doté de la capacité FEATURE_HdrEditing . |
Compatible avec les niveaux d'API 29 et supérieurs. |
Erreurs | Si ce n'est pas le cas, essayez d'utiliser HDR_MODE_TONE_MAP_HDR_TO_SDR_USING_OPEN_GL à la place. |
S'il n'est pas pris en charge, génère une exception ExportException . |
Sur les appareils compatibles avec les fonctionnalités d'encodage requises et exécutant Android 13 (niveau d'API 33) ou version ultérieure, les objets Transformer
vous permettent de modifier des vidéos HDR.
HDR_MODE_KEEP_HDR
est le mode par défaut lors de la création de l'objet Composition
, comme indiqué dans le code suivant:
Kotlin
val composition = Composition.Builder( ImmutableList.of(videoSequence)) .setHdrMode(HDR_MODE_KEEP_HDR) .build()
Java
Composition composition = new Composition.Builder( ImmutableList.of(videoSequence)) .setHdrMode(Composition.HDR_MODE_KEEP_HDR) .build();
Préparer un élément multimédia
Un MediaItem
représente un élément audio ou vidéo dans votre application. Un EditedMediaItem
collecte un MediaItem
ainsi que les transformations à lui appliquer.
Couper une vidéo
Pour supprimer les parties indésirables d'une vidéo, vous pouvez définir des positions de début et de fin personnalisées en ajoutant un ClippingConfiguration
au MediaItem
.
Kotlin
val clippingConfiguration = MediaItem.ClippingConfiguration.Builder() .setStartPositionMs(10_000) // start at 10 seconds .setEndPositionMs(20_000) // end at 20 seconds .build() val mediaItem = MediaItem.Builder() .setUri(videoUri) .setClippingConfiguration(clippingConfiguration) .build()
Java
ClippingConfiguration clippingConfiguration = new MediaItem.ClippingConfiguration.Builder() .setStartPositionMs(10_000) // start at 10 seconds .setEndPositionMs(20_000) // end at 20 seconds .build(); MediaItem mediaItem = new MediaItem.Builder() .setUri(videoUri) .setClippingConfiguration(clippingConfiguration) .build();
Utiliser des effets intégrés
Media3 inclut un certain nombre d'effets vidéo intégrés pour les transformations courantes, par exemple:
Classe | Effet |
---|---|
Presentation |
Mettre à l'échelle l'élément multimédia en fonction de la résolution ou du format |
ScaleAndRotateTransformation |
Mettre à l'échelle l'élément multimédia selon un multiplicateur et/ou faire pivoter l'élément multimédia |
Crop |
Recadrer l'élément multimédia pour utiliser un cadre plus petit ou plus grand |
OverlayEffect |
Ajouter une superposition de texte ou d'image par-dessus l'élément multimédia |
Pour les effets audio, vous pouvez ajouter une séquence d'instances AudioProcessor
qui transformeront les données audio brutes (PCM). Par exemple, vous pouvez utiliser un ChannelMixingAudioProcessor
pour mixer et ajuster des canaux audio.
Pour utiliser ces effets, créez une instance de l'effet ou du processeur audio, créez une instance de Effects
avec les effets audio et vidéo que vous souhaitez appliquer à l'élément multimédia, puis ajoutez l'objet Effects
à un EditedMediaItem
.
Kotlin
val channelMixingProcessor = ChannelMixingAudioProcessor() val rotateEffect = ScaleAndRotateTransformation.Builder().setRotationDegrees(60f).build() val cropEffect = Crop(-0.5f, 0.5f, -0.5f, 0.5f) val effects = Effects(listOf(channelMixingProcessor), listOf(rotateEffect, cropEffect)) val editedMediaItem = EditedMediaItem.Builder(mediaItem) .setEffects(effects) .build()
Java
ChannelMixingAudioProcessor channelMixingProcessor = new ChannelMixingAudioProcessor(); ScaleAndRotateTransformation rotateEffect = new ScaleAndRotateTransformation.Builder() .setRotationDegrees(60f) .build(); Crop cropEffect = new Crop(-0.5f, 0.5f, -0.5f, 0.5f); Effects effects = new Effects( ImmutableList.of(channelMixingProcessor), ImmutableList.of(rotateEffect, cropEffect) ); EditedMediaItem editedMediaItem = new EditedMediaItem.Builder(mediaItem) .setEffects(effects) .build();
Créer des effets personnalisés
En étendant les effets inclus dans Media3, vous pouvez créer des effets personnalisés spécifiques à vos cas d'utilisation. Dans l'exemple suivant, utilisez la sous-classe MatrixTransformation
pour effectuer un zoom sur la vidéo afin qu'elle remplisse l'image au cours de la première seconde de lecture:
Kotlin
val zoomEffect = MatrixTransformation { presentationTimeUs -> val transformationMatrix = Matrix() // Set the scaling factor based on the playback position val scale = min(1f, presentationTimeUs / 1_000f) transformationMatrix.postScale(/* x */ scale, /* y */ scale) transformationMatrix } val editedMediaItem = EditedMediaItem.Builder(inputMediaItem) .setEffects(Effects(listOf(), listOf(zoomEffect)) .build()
Java
MatrixTransformation zoomEffect = presentationTimeUs -> { Matrix transformationMatrix = new Matrix(); // Set the scaling factor based on the playback position float scale = min(1f, presentationTimeUs / 1_000f); transformationMatrix.postScale(/* x */ scale, /* y */ scale); return transformationMatrix; }; EditedMediaItem editedMediaItem = new EditedMediaItem.Builder(inputMediaItem) .setEffects(new Effects(ImmutableList.of(), ImmutableList.of(zoomEffect))) .build();
Pour personnaliser davantage le comportement d'un effet, implémentez un GlShaderProgram
. La méthode queueInputFrame()
permet de traiter les trames d'entrée. Par exemple, pour exploiter les fonctionnalités de machine learning de MediaPipe, vous pouvez utiliser un FrameProcessor
MediaPipe pour envoyer chaque image via un graphe MediaPipe. Vous trouverez un exemple dans l'application de démonstration Transformer.
Prévisualiser les effets
Avec ExoPlayer, vous pouvez prévisualiser les effets ajoutés à un élément multimédia avant de lancer le processus d'exportation. À l'aide du même objet Effects
que pour EditedMediaItem
, appelez setVideoEffects()
sur votre instance ExoPlayer.
Kotlin
val player = ExoPlayer.builder(context) .build() .also { exoPlayer -> exoPlayer.setMediaItem(inputMediaItem) exoPlayer.setVideoEffects(effects) exoPlayer.prepare() }
Java
ExoPlayer player = new ExoPlayer.builder(context).build(); player.setMediaItem(inputMediaItem); player.setVideoEffects(effects); exoPlayer.prepare();
Vous pouvez également prévisualiser des effets audio avec ExoPlayer. Lorsque vous créez votre instance ExoPlayer
, transmettez un RenderersFactory
personnalisé qui configure les moteurs de rendu audio du lecteur pour générer du contenu audio vers un AudioSink
qui utilise votre séquence AudioProcessor
. Dans l'exemple ci-dessous, nous effectuons cette opération en remplaçant la méthode buildAudioSink()
d'un DefaultRenderersFactory
.
Kotlin
val player = ExoPlayer.Builder(context, object : DefaultRenderersFactory(context) { override fun buildAudioSink( context: Context, enableFloatOutput: Boolean, enableAudioTrackPlaybackParams: Boolean, enableOffload: Boolean ): AudioSink? { return DefaultAudioSink.Builder(context) .setEnableFloatOutput(enableFloatOutput) .setEnableAudioTrackPlaybackParams(enableAudioTrackPlaybackParams) .setOffloadMode(if (enableOffload) { DefaultAudioSink.OFFLOAD_MODE_ENABLED_GAPLESS_REQUIRED } else { DefaultAudioSink.OFFLOAD_MODE_DISABLED }) .setAudioProcessors(arrayOf(channelMixingProcessor)) .build() } }).build()
Java
ExoPlayer player = new ExoPlayer.Builder(context, new DefaultRenderersFactory(context) { @Nullable @Override protected AudioSink buildAudioSink( Context context, boolean enableFloatOutput, boolean enableAudioTrackPlaybackParams, boolean enableOffload ) { return new DefaultAudioSink.Builder(context) .setEnableFloatOutput(enableFloatOutput) .setEnableAudioTrackPlaybackParams(enableAudioTrackPlaybackParams) .setOffloadMode( enableOffload ? DefaultAudioSink.OFFLOAD_MODE_ENABLED_GAPLESS_REQUIRED : DefaultAudioSink.OFFLOAD_MODE_DISABLED) .setAudioProcessors(new AudioProcessor[]{channelMixingProcessor}) .build(); } }).build();
Démarrer une transformation
Enfin, créez un Transformer
pour appliquer vos modifications et commencer à exporter l'élément multimédia obtenu.
Kotlin
val transformer = Transformer.Builder(context) .addListener(listener) .build() transformer.start(editedMediaItem, outputPath)
Java
Transformer transformer = new Transformer.Builder(context) .addListener(listener) .build(); transformer.start(editedMediaItem, outputPath);
Vous pouvez également annuler le processus d'exportation si nécessaire avec Transformer.cancel()
.
Vérifier les mises à jour de la progression
Transformer.start
est renvoyé immédiatement et s'exécute de manière asynchrone. Pour interroger la progression actuelle d'une transformation, appelez Transformer.getProgress()
.
Cette méthode utilise un ProgressHolder
. Si l'état de progression est disponible, c'est-à-dire si la méthode renvoie PROGRESS_STATE_AVAILABLE
, le ProgressHolder
fourni est mis à jour avec le pourcentage de progression actuel.
Vous pouvez également associer un écouteur à votre Transformer
pour être informé des événements d'achèvement ou d'erreur.