使用 Media3 Transformer 创建一个基本的视频编辑应用程序

Jetpack Media3 中的 Transformer API 旨在使媒体编辑高效且可靠。Transformer 支持多种操作，包括

使用修剪、缩放和旋转修改视频
添加叠加和滤镜等效果
处理 HDR 和慢动作视频等特殊格式
在应用编辑后导出媒体项目

本页介绍了 Transformer 涵盖的一些关键用例。有关更多详细信息，您可以查看我们关于 Media3 Transformer 的完整指南。

入门

要开始，请添加对 Jetpack Media3 的 Transformer、Effect 和 Common 模块的依赖项

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

请确保将 1.4.1 替换为您偏好的库版本。您可以参考发布说明查看最新版本。

重要类

类	用途
`Transformer`	启动和停止转换，并在运行转换时检查进度更新。
`EditedMediaItem`	表示要处理的媒体项以及要应用于它的编辑。
`Effects`	音频和视频效果的集合。

配置输出

使用 Transformer.Builder，您现在可以指定 videoMimeType 和 audioMimetype 目录，方法是设置函数，而无需创建 TransformationRequest 对象。

在格式之间进行转码

以下代码展示了如何配置一个 Transformer 对象以输出 H.265/AVC 视频和 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();

如果输入媒体格式与音频或视频的转换请求匹配，Transformer 会自动切换到 *转封装*，即，在不修改的情况下将压缩样本从输入容器复制到输出容器。这避免了相同格式的解码和重新编码带来的计算成本和潜在的质量损失。

设置 HDR 模式

如果输入媒体文件采用 HDR 格式，您可以选择几种不同的模式来处理 Transformer 处理 HDR 信息的方式。您可能希望使用 HDR_MODE_KEEP_HDR 或 HDR_MODE_TONE_MAP_HDR_TO_SDR_USING_OPEN_GL。

	`HDR_MODE_KEEP_HDR`	`HDR_MODE_TONE_MAP_HDR_TO_SDR_USING_OPEN_GL`
描述	保留 HDR 数据，这意味着 HDR 输出格式与 HDR 输入格式相同。	使用 OpenGL 色调映射器将 HDR 输入色调映射到 SDR，这意味着输出格式将采用 SDR。
支持	在 API 级别 31 及以上版本上受支持，适用于包含具有 `FEATURE_HdrEditing` 功能的编码器的设备。	在 API 级别 29 及以上版本上受支持。
错误	如果不受支持，则尝试使用 `HDR_MODE_TONE_MAP_HDR_TO_SDR_USING_OPEN_GL`。	如果不受支持，则会引发 `ExportException`。

在支持所需编码功能并运行 Android 13（API 级别 33）或更高版本的设备上，Transformer 对象允许您编辑 HDR 视频。 HDR_MODE_KEEP_HDR 是构建 Composition 对象时的默认模式，如以下代码所示

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

准备媒体项

一个 MediaItem 代表您的应用中的音频或视频项。一个 EditedMediaItem 收集一个 MediaItem 以及要应用于它的转换。

修剪视频

要删除视频中不需要的部分，可以通过将 ClippingConfiguration 添加到 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();

使用内置效果

Media3 包含许多用于常见转换的内置视频效果，例如

类	效果
`演示`	按分辨率或纵横比缩放媒体项
`ScaleAndRotateTransformation`	按倍数缩放媒体项和/或旋转媒体项
`Crop`	将媒体项裁剪为更小或更大的帧
`OverlayEffect`	在媒体项顶部添加文本或图像叠加层

对于音频效果，您可以添加一系列 AudioProcessor 实例，这些实例将转换原始 (PCM) 音频数据。例如，您可以使用 ChannelMixingAudioProcessor 来混合和缩放音频通道。

要使用这些效果，请创建效果或音频处理器的实例，使用您要应用于媒体项的音频和视频效果构建 Effects 的实例，然后将 Effects 对象添加到 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();

创建自定义效果

通过扩展 Media3 中包含的效果，您可以创建特定于您的用例的自定义效果。在以下示例中，使用子类 MatrixTransformation 将视频放大以在播放的前一秒钟内填充框架

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

要进一步自定义效果的行为，请实现 GlShaderProgram。 queueInputFrame() 方法用于处理输入帧。例如，要利用 MediaPipe 的机器学习功能，您可以使用 MediaPipe FrameProcessor 将每个帧发送到 MediaPipe 图表中。在 Transformer 演示应用程序中查看此示例。

预览效果

使用 ExoPlayer，您可以在开始导出过程之前预览添加到媒体项的效果。使用与 EditedMediaItem 相同的 Effects 对象，在您的 ExoPlayer 实例上调用 setVideoEffects()。

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

您还可以使用 ExoPlayer 预览音频效果。在构建您的 ExoPlayer 实例时，传入一个自定义的 RenderersFactory，该工厂会配置播放器的音频渲染器，以将音频输出到使用 AudioProcessor 序列的 AudioSink。在下面的示例中，我们通过覆盖 DefaultRenderersFactory 的 buildAudioSink() 方法来实现此目的。

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

启动转换

最后，创建一个 Transformer 来应用您的编辑并开始导出生成的媒体项。

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

同样，如果需要，您可以使用 Transformer.cancel() 取消导出过程。

检查进度更新

Transformer.start 会立即返回并异步运行。要查询转换的当前进度，请调用 Transformer.getProgress()。此方法接受一个 ProgressHolder，如果进度状态可用，即如果该方法返回 PROGRESS_STATE_AVAILABLE，则提供的 ProgressHolder 将使用当前进度百分比进行更新。

您还可以将侦听器附加到您的 Transformer，以便在完成或错误事件时收到通知。