Jetpack Media3 中的 Transformer API 可以提升媒體編輯效能和穩定性。Transformer 支援多種作業，包括：
- 修改剪輯、縮放和旋轉影片
- 添加疊加、濾鏡等特效
- 處理特殊格式，例如 HDR 和慢動作影片
- 套用編輯後匯出媒體項目
本頁面將逐步說明 Transformer 涵蓋的一些重要用途。詳情請參閱 Media3 Transformer 的完整指南。
開始使用
如要開始使用，請在 Jetpack Media3 的 Transformer、Effect 和 Common 模組新增依附元件：
implementation "androidx.media3:media3-transformer:1.3.1" implementation "androidx.media3:media3-effect:1.3.1" implementation "androidx.media3:media3-common:1.3.1"
請務必將 1.3.1 替換為偏好的程式庫版本。如要查看最新版本，請參閱版本資訊。
重要類別
| 類別 | 目的 |
|---|---|
Transformer |
開始和停止轉換，以及檢查執行中轉換的進度更新。 |
EditedMediaItem |
代表要處理的媒體項目，以及要套用的編輯。 |
Effects |
一系列音訊和影片效果。 |
設定輸出內容
透過 Transformer.Builder，您現在無需建立 TransformationRequest 物件，即可透過設定函式來指定 videoMimeType 和 audioMimetype 目錄。
在不同格式之間進行轉碼
以下程式碼顯示如何設定 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_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，表示輸出格式為 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();
如要進一步自訂「效果」的行為，請實作 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，以接收完成或錯誤事件的通知。