Jetpack Media3 ライブラリは、動画編集をリアルタイムでプレビューするための強力な Player 実装である CompositionPlayer API を提供します。アプリでユーザーが動画を編集できる場合（エフェクトの適用、トリミング、複数の入力メディア アイテムの合成など）、CompositionPlayer を使用すると、出力の正確なプレビューを表示できます。これは、適用した編集を保存する必要がない場合や、編集を最終的な動画にコミットしてエクスポートする前に、意図したとおりに構成されていることを検証する場合に役立ちます。
CompositionPlayer とは
CompositionPlayer は、Composition オブジェクトを再生するために特別に設計された Player インターフェースの特殊な実装です。Composition は、動画クリップや音声トラックなどの入力メディア アセットの配置方法と、適用する音声と動画のエフェクトを定義します。Composition API の詳細については、メディア アイテムの Composition を定義するをご覧ください。
CompositionPlayer の主な目的は、指定されたすべての編集を反映した Composition をリアルタイムでレンダリングすることです。これにより、ユーザーは時間とリソースを消費する可能性のあるエクスポート プロセスを確定する前に、編集結果を正確に確認できます。同じ Composition オブジェクトを Transformer インスタンスでエクスポートに使用できます。詳細については、Composition のエクスポートをご覧ください。
CompositionPlayer 対 ExoPlayer
CompositionPlayer と ExoPlayer はどちらも Media3 内の Player 実装ですが、それぞれ異なるユースケース向けに最適化されています。
機能 |
CompositionPlayer |
ExoPlayer |
メディアを入力する |
1 つの Composition オブジェクトを受け取ります。このオブジェクトは、アイテムごとの効果を持つ複数の EditedMediaItem インスタンスで構成できます。 |
|
タイムライン |
タイムラインと期間は、コンポジション全体に基づいています。 |
タイムラインと再生時間は、アクティブに再生中の MediaItem に対応します。 |
効果 |
エフェクトはコンポジション内で定義され、個々の EditedMediaItem またはコンポジション全体に適用できます。 |
エフェクトは setVideoEffects() を使用して ExoPlayer インスタンス自体に設定され、各エフェクトはプレイリスト内の各アイテムに個別に適用されます。 |
基本的に、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を使用する必要があります。画像または動画アイテムを含むシーケンスが 1 つのみで、他のシーケンスが音声のみの場合は、SingleInputVideoGraph.Factoryで十分です。 - コンポジション内のすべてのメディア アイテムには、明示的に期間を設定する必要があります。画像の場合は
MediaItem.Builder.setImageDurationMs()、音声または動画の場合はEditedMediaItem.Builder.setDurationUs()を使用します。
次のユースケースがサポートされています。
- 単一アセットのプレビュー。
- 単一シーケンス（シーケンシャル メディア アイテム）のプレビュー。
- 単一の動画シーケンス + 単一の音声シーケンス（バックグラウンド オーディオなど）のプレビュー。
現在、次のユースケースが開発中です。
- 複数の動画シーケンスを含むピクチャー イン ピクチャー、並列、グリッドなどのレイアウトを含む、マルチアセットのプレビュー。
- 別のグラフィック エンジンを使用して編集パイプラインをカスタマイズする。
機能リクエスト
CompositionPlayer に関する機能リクエストやフィードバックがある場合は、Media3 GitHub リポジトリで問題を報告してください。