再生コントロールをアプリに追加する

メディアを再生するアプリには、メディアを表示して再生を制御するためのユーザー インターフェース コンポーネントが必要です。Media3 ライブラリには、多数の UI コンポーネントを含む UI モジュールが含まれています。UI モジュールに依存するには、次の依存関係を追加します。

Kotlin

implementation("androidx.media3:media3-ui:1.5.0")

Groovy

implementation "androidx.media3:media3-ui:1.5.0"

最も重要なコンポーネントは、メディアの再生用のビューである PlayerView です。PlayerView は、再生中の動画、画像、字幕、アルバムアート、再生コントロールを表示します。

PlayerView には、プレーヤー インスタンスを接続および切断（null を渡す）ための setPlayer メソッドがあります。

PlayerView

PlayerView は、動画、画像、音声の再生の両方に使用できます。動画再生の場合は動画と字幕をレンダリングし、画像再生の場合はビットマップをレンダリングします。また、音声ファイルのメタデータとして含まれるアートワークを表示できます。他の UI コンポーネントと同様に、レイアウト ファイルに含めることができます。たとえば、PlayerView は次の XML に含めることができます。

<androidx.media3.ui.PlayerView
    android:id="@+id/player_view"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    app:show_buffering="when_playing"
    app:show_shuffle_button="true"/>

上記のスニペットは、PlayerView が複数の属性を提供していることを示しています。これらの属性を使用すると、ビューの動作や外観をカスタマイズできます。これらの属性のほとんどには、実行時にビューをカスタマイズするために使用できる対応するセッター メソッドがあります。PlayerView Javadoc には、これらの属性と setter メソッドの詳細が記載されています。

レイアウト ファイルでビューを宣言したら、アクティビティの onCreate メソッドでビューを検索できます。

Kotlin

override fun onCreate(savedInstanceState: Bundle?) {
  super.onCreate(savedInstanceState)
  // ...
  playerView = findViewById(R.id.player_view)
}

Java

@Override
protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  // ...
  playerView = findViewById(R.id.player_view);
}

プレーヤーが初期化されたら、setPlayer を呼び出してビューに接続できます。

Kotlin

// Instantiate the player.
val player = ExoPlayer.Builder(context).build()
// Attach player to the view.
playerView.player = player
// Set the media item to be played.
player.setMediaItem(mediaItem)
// Prepare the player.
player.prepare()

Java

// Instantiate the player.
player = new ExoPlayer.Builder(context).build();
// Attach player to the view.
playerView.setPlayer(player);
// Set the media item to be played.
player.setMediaItem(mediaItem);
// Prepare the player.
player.prepare();

サーフェス タイプを選択する

PlayerView の surface_type 属性を使用すると、動画の再生に使用するサーフェスのタイプを設定できます。値 spherical_gl_surface_view（球面動画の再生用の特別な値）と video_decoder_gl_surface_view（拡張機能レンダラを使用した動画レンダリング用）のほか、surface_view、texture_view、none の値を使用できます。ビューが音声再生専用の場合は、サーフェスの作成がコストがかかる可能性があるため、none を使用してサーフェスの作成を回避する必要があります。

ビューが通常の動画再生用の場合は、surface_view または texture_view を使用する必要があります。SurfaceView には、動画再生に関して TextureView にはない次のようなメリットがあります。

• 多くのデバイスで消費電力を大幅に削減。
• フレーム タイミングの精度が向上し、動画の再生がスムーズになります。
• 対応デバイスで高画質の HDR 動画出力をサポート。
• DRM で保護されたコンテンツの再生時の安全な出力のサポート。
• UI レイヤをアップスケーリングする Android TV デバイスで、ディスプレイのフル解像度で動画コンテンツをレンダリングする機能。

したがって、可能な場合は TextureView ではなく SurfaceView を使用することをおすすめします。TextureView は、SurfaceView でニーズが満たされない場合にのみ使用してください。たとえば、次の注記で説明するように、Android 7.0（API レベル 24）より前に、動画サーフェスのスムーズなアニメーションやスクロールが必要な場合です。この場合、SDK_INT が 24 未満（Android 7.0）の場合にのみ TextureView を使用し、それ以外の場合は SurfaceView を使用することをおすすめします。

注: Android 7.0（API レベル 24）までは、SurfaceView レンダリングはビュー アニメーションと適切に同期されていませんでした。以前のリリースでは、SurfaceView がスクロール コンテナに配置されたときや、アニメーションが適用されたときに、望ましくない効果が生じる可能性がありました。このような効果には、ビューのコンテンツが表示される場所から少し遅れて表示される、アニメーションを適用するとビューが黒くなるなどがあります。そのため、Android 7.0 より前の動画でスムーズなアニメーションやスクロールを実現するには、SurfaceView ではなく TextureView を使用する必要があります。

注: SurfaceView のサーフェスのライフサイクルはビューの可視性に関連付けられていますが、TextureView のサーフェスのライフサイクルはウィンドウのアタッチとデタッチに関連付けられています。そのため、SurfaceView を使用するスクロール UI では、出力サーフェスが少し遅れて使用可能になるため、再生の開始に時間がかかることがあります。Android 14 以降では、PlayerView は SurfaceView.setSurfaceLifecycle(SURFACE_LIFECYCLE_FOLLOWS_ATTACHMENT) を使用してこの動作を回避します。アプリが SurfaceView を直接使用している（PlayerView を使用しない）場合は、このモードを有効にすることをおすすめします。Android 14 より前は、ビューをリサイクルするときにビューを画面外に移動することで、サーフェスが破棄されるのを回避できました。

注: 一部の Android TV デバイスでは、ディスプレイのフル解像度よりも低い解像度で UI レイヤを実行し、ユーザーに表示するためにアップスケーリングしています。たとえば、4K ディスプレイを搭載した Android TV で UI レイヤが 1080p で実行される場合があります。このようなデバイスでは、SurfaceView を使用して、ディスプレイのフル解像度でコンテンツをレンダリングする必要があります。ディスプレイのフル解像度（現在のディスプレイ モード）は、Util.getCurrentDisplayModeSize を使用してクエリできます。UI レイヤの解像度は、Android の Display.getSize API を使用してクエリできます。

Android TV での D-pad ナビゲーション

Android TV のリモコンには、Activity の dispatchKeyEvent(KeyEvent) にキーイベントとして届くコマンドを送信する D-pad コントロールがあります。これらはプレーヤー ビューに委任する必要があります。

Kotlin

override fun dispatchKeyEvent(event: KeyEvent?): Boolean{
  return playerView.dispatchKeyEvent(event!!) || super.dispatchKeyEvent(event)
}

Java

@Override
public boolean dispatchKeyEvent(KeyEvent event) {
  return playerView.dispatchKeyEvent(event) || super.dispatchKeyEvent(event);
}

再生コントロールの操作や広告のスキップを行うには、プレーヤー ビューのフォーカスをリクエストすることが重要です。Activity の onCreate でフォーカスをリクエストすることを検討してください。

Kotlin

override fun onCreate(savedInstanceState: Bundle?) {
  super.onCreate(savedInstanceState)
  // ...
  playerView.requestFocus()
  // ...
}

Java

@Override
public void onCreate(@Nullable Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    // ...
    playerView.requestFocus();
    // ...
}

Android TV で Compose を使用している場合は、AndroidView をフォーカス可能にして、必要に応じて修飾子パラメータを AndroidView に渡してイベントを委任する必要があります。

AndroidView(
  modifier = modifier
    .focusable()
    .onKeyEvent { playerView.dispatchKeyEvent(it.nativeKeyEvent) },
  factory = { playerView }
)

ドローアブルをオーバーライドする

注意: 次のセクションで説明するカスタマイズが、ライブラリの今後のバージョンで引き続き機能することを保証するものではありません。リソース ID の名前が変更される場合や、一部が完全に削除される場合があります。これは、リソース ID が「private」とマークされていることで示されます。

PlayerView は PlayerControlView を使用して、再生コントロールと進行状況バーを表示します。PlayerControlView で使用されるドローアブルは、アプリで定義されている同じ名前のドローアブルでオーバーライドできます。オーバーライド可能なコントロール ドローアブルの一覧については、PlayerControlView Javadoc をご覧ください。

その他のカスタマイズ

上記以外のカスタマイズが必要な場合は、アプリ デベロッパーが Media3 の UI モジュールで提供されている UI コンポーネントを使用するのではなく、独自の UI コンポーネントを実装することが想定されます。