Jetpack Media3 程式庫提供 CompositionPlayer API，這是功能強大的 Player 實作項目，可即時預覽影片編輯內容。如果應用程式可讓使用者編輯影片，例如套用特效、修剪或合成多個輸入媒體項目，CompositionPlayer 可協助您顯示準確的輸出預覽畫面。如果您不需要儲存套用的編輯內容，或想先驗證編輯內容是否符合預期，再將其匯出為最終影片，這項功能就非常實用。
什麼是 CompositionPlayer？
CompositionPlayer 是 Player 介面的專用實作項目，專門用來播放 Composition 物件。
Composition 定義輸入媒體資產 (例如視訊片段和音軌) 的排列方式，以及要套用哪些音訊和視訊效果。如要進一步瞭解 Composition API，請參閱「定義媒體項目 Composition」。
CompositionPlayer 的主要用途是即時算繪這個 Composition，並顯示所有指定的編輯內容，讓使用者在執行可能耗時且耗用資源的匯出程序前，確切瞭解編輯內容的呈現效果。接著，您可以使用相同的 Composition 物件搭配 Transformer 執行個體匯出，詳情請參閱「匯出 Composition」。
CompositionPlayer對ExoPlayer
CompositionPlayer 和 ExoPlayer 都是 Media3 內部的 Player 實作項目，但兩者最佳化的用途不同：
功能 |
CompositionPlayer |
ExoPlayer |
輸入媒體 |
接受單一 Composition 物件，其中可包含多個 EditedMediaItem 執行個體，並為每個項目套用效果。 |
|
時間軸 |
時間軸和持續時間以整個合成內容為準。 |
時間軸和時間長度會對應到正在播放的 MediaItem。 |
特效 |
效果是在 Composition 中定義，可套用至個別 EditedMediaItem 或整個 Composition。 |
效果是在 ExoPlayer 執行個體本身上使用 setVideoEffects() 設定，且每個效果都會個別套用至播放清單中的每個項目。 |
基本上，當您需要算繪複雜的媒體和效果時，CompositionPlayer最能派上用場，通常是在編輯環境中。Composition使用 ExoPlayer 播放一般用途的音訊或視訊內容，或使用 setVideoEffects() 預覽單一素材的編輯內容。
CompositionPlayer 預覽
將 CompositionPlayer 整合至應用程式需要完成幾個重要步驟。首先，使用建構工具模式例項化 CompositionPlayer，然後設定要播放的 Composition：
val compositionPlayer = CompositionPlayer.Builder(context).build() compositionPlayer.setComposition(composition) compositionPlayer.prepare() compositionPlayer.play()
如需建立 Composition 的指引，請參閱「建立 Composition」一節。
請注意，由於 CompositionPlayer 會實作 Player 介面，因此您可以設定目標輸出，並透過標準 Player 方法控制播放器。
處理錯誤
將 Player.Listener 執行個體附加至 CompositionPlayer，以便對播放事件和錯誤做出反應。onPlayerError() 回呼也會顯示編輯特定元件 (例如 Composition 或 VideoGraph.Factory) 時發生的任何問題。詳情請參閱「播放器事件」說明文件。
重要注意事項
使用 CompositionPlayer 時，請留意以下功能和限制：
- 雖然
CompositionPlayer是以Player介面為基礎，但由於它依附於Composition進行播放，因此部分行為與ExoPlayer不同。舉例來說，CompositionPlayer僅支援將重複模式設為REPEAT_MODE_OFF或REPEAT_MODE_ALL。 - 根據預設，
CompositionPlayer會使用SingleInputVideoGraph.Factory，但如果組合使用多個含有圖片或影片項目的序列，您應在建構CompositionPlayer執行個體時使用setVideoGraphFactory()，改用MultipleInputVideoGraph.Factory。如果只有一個序列含有圖片或影片項目，其他序列則只有音訊，則SingleInputVideoGraph.Factory就足夠。 - 組合中的所有媒體項目都應明確設定時間長度，圖片可使用
MediaItem.Builder.setImageDurationMs()，音訊或影片則可使用EditedMediaItem.Builder.setDurationUs()。
支援的用途如下：
- 單一素材資源預覽。
- 單一序列 (即連續媒體項目) 預覽。
- 預覽單一影片序列 + 單一音訊序列 (例如背景音訊)。
我們正在積極開發下列用途：
- 多素材資源預覽畫面，包括子母畫面、並排和格線等版面配置，其中包含多個影片序列。
- 使用不同的圖形引擎自訂編輯管道。
功能要求
如有任何功能要求或意見回饋，請在 Media3 GitHub 存放區中提出問題。CompositionPlayer