定義媒體項目的組合

Media3 轉換器程式庫提供一系列工具，可用於編輯及操控媒體。多項資產編輯的核心元件是 Composition API。這個 API 可讓您將多個輸入媒體項目 (例如影片片段、圖片和音軌) 排列成單一連貫的結構，然後處理、預覽或匯出。Composition 可視為時間軸，內含一或多個媒體序列。每個序列 (由 EditedMediaItemSequence 定義) 都包含個別的媒體項目 (定義為 EditedMediaItem 執行個體)。轉換和效果可以套用至個別 EditedMediaItem，或整個 Composition。

Composition 是 Media3 Transformer 各種用途的進入點，例如：

• 依序結合音訊、圖片和影片素材資源。
• 在另一部影片上疊加影片 (子母畫面)。
• 將背景音軌與影片序列混合。
• 在整個編輯片段中套用視覺或音效。
• 處理 HDR 影片處理等複雜情境。

本指南著重於如何定義及建構 Composition 物件，包括相關的主要類別、如何使用單一或多個序列建立基本和更複雜的組合，以及如何在不同層級套用效果。

重要概念和類別

如要有效使用 Composition API，請務必瞭解建構媒體組合時涉及的主要類別：

Effects：

• 用途：Effects 物件是音訊處理器和視訊效果的集合。
• 用途：在 Composition 的脈絡中，Effects 可設定在個別 EditedMediaItem 執行個體上，修改特定片段，或設定在整個 Composition 上 (通常用於影響最終輸出的 Presentation 特效，例如調整顯示解析度或影格率)。
• 重要性： Effects 是在個別項目層級和整體組合層級，對媒體套用轉換、篩選器和其他處理作業的機制。詳情請參閱「Transformations」一文。

EditedMediaItem：

• 用途：這個類別代表單一媒體 (例如影片、圖片或音訊檔案)，以及要套用的編輯內容。
• 使用方式：EditedMediaItem 會將 MediaItem (指向實際媒體內容) 與 Effects 物件分組。
• 重要性：這是構圖的基本構成元素。您可以精確定義要加入的媒體，以及每個片段在與序列中的其他片段合併前，應呈現的外觀和聲音。

EditedMediaItemSequence：

• 用途：代表 EditedMediaItem 物件的線性序列，這些物件會依序播放。
• 使用方式：EditedMediaItemSequence 是以 EditedMediaItem 物件清單建構而成。每個序列都類似於多軌影片編輯時間軸中的軌跡或圖層。Composition舉例來說，一個序列可能包含主要影片片段，而另一個序列 (時間重疊) 可能包含要疊加在第一個序列上的影片片段，還有一個序列可能只包含背景音樂的音軌。
• 重要性：EditedMediaItemSequence 會將應直接接續播放的相關媒體項目分組。使用多個序列可建構更複雜的編排方式，例如疊加音訊或建立視覺疊加效果。

Composition：

• 用途：這是頂層物件，代表要處理的整個媒體時間軸。是所有媒體序列的容器，以及適用於整個輸出的任何全域設定或效果。
• 用途：Composition 包含一或多個 EditedMediaItemSequence 物件。您也可以直接在 Composition 中套用整個合成的特效，並設定 HDR 模式等全域設定。如果 Composition 包含多個 EditedMediaItemSequence 物件，這些序列可以安排依序播放，也可以在時間上重疊，以便製作重疊的版面配置，例如子母畫面，或是從一個序列轉換到另一個序列。
• 重要性：Composition 會定義要處理的輸入媒體整體結構，是您可同時用於預覽編輯內容 (使用 CompositionPlayer) 和匯出輸出影片 (使用 Transformer) 的常見物件。

建立並匯出 Composition

以下範例說明如何建立影片素材資源，其中包含兩個經過編輯的影片片段，並疊加音軌，然後匯出：

val video1 = EditedMediaItem.Builder(MediaItem.fromUri(video1Uri)).build()

val video2 = EditedMediaItem.Builder(MediaItem.fromUri(video2Uri)).build()

val videoSequence = EditedMediaItemSequence.withAudioAndVideoFrom(listOf(video1, video2))

val backgroundAudio = EditedMediaItem.Builder(MediaItem.fromUri(audioUri)).build()

val backgroundAudioSequence =
  EditedMediaItemSequence.withAudioFrom(listOf(backgroundAudio))
    .buildUpon()
    .setIsLooping(true) // Loop audio track through duration of videoSequence
    .build()

val composition = Composition.Builder(videoSequence, backgroundAudioSequence).build()

transformer.start(composition, filePath)
Composition.kt

EditedMediaItem video1 = new EditedMediaItem.Builder(MediaItem.fromUri(video1Uri)).build();

EditedMediaItem video2 = new EditedMediaItem.Builder(MediaItem.fromUri(video2Uri)).build();

EditedMediaItemSequence videoSequence =
    EditedMediaItemSequence.withAudioAndVideoFrom(ImmutableList.of(video1, video2));

EditedMediaItem backgroundAudio =
    new EditedMediaItem.Builder(MediaItem.fromUri(audioUri)).build();

EditedMediaItemSequence backgroundAudioSequence =
    EditedMediaItemSequence.withAudioFrom(ImmutableList.of(backgroundAudio))
        .buildUpon()
        .setIsLooping(true) // Loop audio track through duration of videoSequence
        .build();

Composition composition =
    new Composition.Builder(videoSequence, backgroundAudioSequence).build();

transformer.start(composition, filePath);
CompositionJava.java

支援的用途範例

以下列舉 Transformer API 支援的 Composition 用途：

• 依序結合音訊、圖片和影片素材資源。
• 在影片素材資源中加入背景音訊。
• 在 Composition 中新增效果。
• 將 HDR 輸入內容色調映射至 SDR，產生視覺品質更佳的 SDR 輸出內容。

目前限制

組合中的序列必須符合Transformer.start()中列出的條件。此外，使用 Compositions 時，系統尚不支援下列作業：

• 視訊或音訊軌的交叉淡化

功能要求

如要對 Transformer API 提出任何功能要求，請在 Media3 GitHub 存放區中回報問題。