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

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

Kotlin

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

Groovy

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

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

PlayerView には、（null を渡して）プレーヤー インスタンスをアタッチおよびデタッチするための setPlayer メソッドがあります。

プレーヤー ビュー

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 をご覧ください。

ビューがレイアウト ファイルで宣言されると、アクティビティの 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 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 }
)

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

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

さらなるカスタマイズ

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