Jetpack Media3 中的 Transformer API 旨在提升媒體編輯的效率和穩定性。轉換器支援多種作業,包括:
- 運用剪輯、縮放和旋轉等功能來修改影片
- 新增重疊和濾鏡等效果
- 正在處理特殊格式,例如 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
指定 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();
如果輸入媒體格式與音訊或影片的轉換要求相符,轉換器會自動切換為「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 格式。 |
輔助 | 如果裝置搭載的編碼器支援 FEATURE_HdrEditing 功能,就會支援 API 級別 31 以上的版本。 |
適用於 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
以及要套用至其的轉換。
剪輯影片
如要移除影片不需要的部分,可以在 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 圖表傳送每個畫面。請在轉換器示範應用程式中查看此範例。
預覽效果
使用 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
,以便接收完成或錯誤事件的通知。