使用 Media3 Transformer 建立基本的影片編輯應用程式

Jetpack Media3 中的 Transformer API 可以提升媒體編輯效能和穩定性。Transformer 支援多種作業,包括:

  • 修改剪輯、縮放和旋轉影片
  • 添加疊加、濾鏡等特效
  • 處理特殊格式,例如 HDR 和慢動作影片
  • 套用編輯後匯出媒體項目

本頁面將逐步說明 Transformer 涵蓋的一些重要用途。詳情請參閱 Media3 Transformer 的完整指南。

開始使用

如要開始使用,請在 Jetpack Media3 的 Transformer、Effect 和 Common 模組新增依附元件:

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

請務必將 1.2.1 替換為偏好的程式庫版本。如要查看最新版本,請參閱版本資訊

重要類別

類別 目的
Transformer 開始和停止轉換,以及檢查執行中轉換的進度更新。
EditedMediaItem 代表要處理的媒體項目,以及要套用的編輯。
Effects 一系列音訊和影片效果。

設定輸出內容

透過 Transformer.Builder,您現在無需建立 TransformationRequest 物件,即可透過設定函式來指定 videoMimeTypeaudioMimetype 目錄。

在不同格式之間進行轉碼

以下程式碼顯示如何設定 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 會自動切換為「Transmuxing」,也就是在不修改的情況下,將壓縮過的樣本從輸入容器複製到輸出容器。這樣可以避免以相同格式解碼及重新編碼時,產生的運算成本和潛在品質損失。

設定高動態範圍模式

如果輸入媒體檔案是 HDR 格式,則可以選用幾種不同的模式,決定 Transformer 處理 HDR 資訊的方式。建議您使用 HDR_MODE_KEEP_HDRHDR_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,表示輸出格式為 SDR。
支援 支援 API 級別 31 以上級別的裝置,如果裝置搭載具有 FEATURE_HdrEditing 功能的編碼器,即可支援這項設定。 支援 API 級別 29 以上。
錯誤 如未支援,請嘗試改用 HDR_MODE_TONE_MAP_HDR_TO_SDR_USING_OPEN_GL 如果不支援,會擲回 ExportException

在支援必要編碼功能且搭載 Android 13 (API 級別 33) 以上版本的裝置上,Transformer 物件可讓您編輯 HDR 影片。建構 Composition 物件時,預設模式為 HDR_MODE_KEEP_HDR,如以下程式碼所示:

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 以及要套用的轉換。

剪輯影片

如要移除影片中不需要的部分,您可以在 MediaItem 中加入 ClippingConfiguration,藉此設定自訂的開始和結束位置。

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 提供多種內建影片特效,適用於常見轉換,例如:

類別 效果
Presentation 依解析度或顯示比例縮放媒體項目
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();

如要進一步自訂「效果」的行為,請實作 GlShaderProgramqueueInputFrame() 方法用於處理輸入影格。舉例來說,如要利用 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。在以下範例中,我們會覆寫 DefaultRenderersFactorybuildAudioSink() 方法,

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,以接收完成或錯誤事件的通知。