スタート ガイド

ExoPlayer を使用するには、次の手順を実装します。

  1. 依存関係として ExoPlayer をプロジェクトに追加します。
  2. ExoPlayer インスタンスを作成します。
  3. プレーヤーをビューにアタッチする（動画出力とユーザー入力用）。
  4. 再生する MediaItem をプレーヤーに用意します。
  5. 完了したらプレーヤーを解放します。

これらの手順については、後ほど詳しく説明します。完全な例については、メインのデモアプリの PlayerActivity をご覧ください。

ExoPlayer を依存関係として追加する

アプリで ExoPlayer を使用するには、必要なモジュールを追加し、Java 8 のサポートを有効にします。

ExoPlayer モジュールを追加する

AndroidX Media3 の使用を開始する最も簡単な方法は、アプリ モジュールの build.gradle ファイルに必要なライブラリの Gradle 依存関係を追加することです。

たとえば、DASH 再生サポートと UI コンポーネントを備えた ExoPlayer に依存するには、次のようにモジュールに依存関係を追加します。

Kotlin

implementation("androidx.media3:media3-exoplayer:1.11.1")
implementation("androidx.media3:media3-exoplayer-dash:1.11.1")
implementation("androidx.media3:media3-ui:1.11.1")
implementation("androidx.media3:media3-ui-compose-material3:1.11.1")

Groovy

implementation "androidx.media3:media3-exoplayer:1.11.1"
implementation "androidx.media3:media3-exoplayer-dash:1.11.1"
implementation "androidx.media3:media3-ui:1.11.1"
implementation("androidx.media3:media3-ui-compose-material3:1.11.1")

ここで、1.11.1 は任意のバージョンです（最新バージョンはリリースノートで確認できます）。すべてのモジュールは同じバージョンである必要があります。

AndroidX Media3 には、外部ライブラリに依存して追加機能を提供するライブラリ モジュールがあります。Maven リポジトリから入手できるものもあれば、手動でビルドする必要があるものもあります。ライブラリ ディレクトリを参照し、個々の README で詳細を確認してください。

利用可能なライブラリ モジュールの詳細については、Google Maven AndroidX Media ページをご覧ください。

Java 8 のサポートを有効にする

まだ有効にしていない場合は、ExoPlayer に依存するすべての build.gradle ファイルで、少なくとも Java 8 のサポートを有効にする必要があります。そのためには、android セクションに以下を追加します。

compileOptions {
  targetCompatibility JavaVersion.VERSION_1_8
}

プレーヤーを作成する

ExoPlayer.Builder を使用して ExoPlayer インスタンスを作成できます。これにより、さまざまなカスタマイズ オプションが提供されます。次のコードは、インスタンスを作成する最も簡単な例です。

Kotlin

val player = ExoPlayer.Builder(context).build()

Java

ExoPlayer player = new ExoPlayer.Builder(context).build();

スレッド化に関する注意事項

ExoPlayer インスタンスには、単一のアプリケーション スレッドからアクセスする必要があります。ほとんどの場合、これはアプリケーションのメインスレッドです。ExoPlayer の UI コンポーネントまたは IMA 拡張機能を使用する場合は、アプリケーションのメインスレッドを使用する必要があります。

ExoPlayer インスタンスにアクセスする必要があるスレッドは、プレーヤーの作成時に Looper を渡すことで明示的に指定できます。Looper が指定されていない場合は、プレーヤーが作成されたスレッドの Looper が使用されます。そのスレッドに Looper がない場合は、アプリのメインスレッドの Looper が使用されます。いずれの場合も、プレーヤーにアクセスする必要があるスレッドの Looper は、Player.getApplicationLooper を使用してクエリできます。

ExoPlayer のスレッドモデルについて詳しくは、ExoPlayer Javadoc の「スレッドモデル」セクションをご覧ください。

プレーヤーをビューにアタッチする

media3-ui ライブラリには、メディア再生用の事前構築済み UI コンポーネントが用意されています。これには、PlayerControlView、SubtitleView、動画がレンダリングされる Surface をカプセル化する PlayerView が含まれます。PlayerView は、アプリケーションのレイアウト XML に含めることができます。たとえば、プレーヤーをビューにバインドするには、次のようにします。

Kotlin

// Bind the player to the view.
playerView.player = player

Java

// Bind the player to the view.
playerView.setPlayer(player);

Media3 のビルド済み UI コンポーネントの使用は任意です。独自の UI を実装する動画アプリの場合、ターゲットの SurfaceView、TextureView、SurfaceHolder、Surface は、それぞれプレーヤーの setVideoSurfaceView、setVideoTextureView、setVideoSurfaceHolder、setVideoSurface メソッドを使用して設定できます。Listener.onCues コールバックを使用すると、再生中にレンダリングする必要がある字幕を受信できます。setImageOutput を使用すると、デコードされた画像を受信できます。

ユーザー エクスペリエンスを向上させるため、keepScreenOn 属性を追加することを検討してください。デバイスをスリープ状態にしない他のアクションについては、バックグラウンド処理のページをご覧ください。

android:keepScreenOn="true"

アプリが UI に Jetpack Compose を使用している場合は、media3-ui-compose-material3 ライブラリの Player コンポーザブルを使用できます。Player は動画を表示し、再生コントロール スロットの事前入力された値を含みます。androidx.media3.common.Player オブジェクトを androidx.media3.ui.compose.material3.Player コンポーザブルにアタッチするには、引数として渡します。

// Bind the player to the composable.
Player(player = player)

Media3 UI コンポーネントの使用とそのカスタマイズについて詳しくは、UI ページをご覧ください。

再生リストにデータを入力してプレーヤーを準備する

ExoPlayer では、すべてのメディアが MediaItem で表されます。メディアを再生するには、対応する MediaItem を作成してプレーヤーに追加し、プレーヤーを準備して、play を呼び出して再生を開始する必要があります。

Kotlin

// Build the media item.
val mediaItem = MediaItem.fromUri(videoUri)
// Set the media item to be played.
player.setMediaItem(mediaItem)
// Prepare the player.
player.prepare()
// Start the playback.
player.play()

Java

// Build the media item.
MediaItem mediaItem = MediaItem.fromUri(videoUri);
// Set the media item to be played.
player.setMediaItem(mediaItem);
// Prepare the player.
player.prepare();
// Start the playback.
player.play();

ExoPlayer は再生リストを直接サポートしているため、複数のメディア アイテムをプレーヤーに準備して、1 つずつ再生できます。

Kotlin

// Build the media items.
val firstItem = MediaItem.fromUri(firstVideoUri)
val secondItem = MediaItem.fromUri(secondVideoUri)
// Add the media items to be played.
player.addMediaItem(firstItem)
player.addMediaItem(secondItem)
// Prepare the player.
player.prepare()
// Start the playback.
player.play()

Java

// Build the media items.
MediaItem firstItem = MediaItem.fromUri(firstVideoUri);
MediaItem secondItem = MediaItem.fromUri(secondVideoUri);
// Add the media items to be played.
player.addMediaItem(firstItem);
player.addMediaItem(secondItem);
// Prepare the player.
player.prepare();
// Start the playback.
player.play();

再生リストは、プレーヤーを再度準備することなく、再生中に更新できます。プレイリストへの入力と操作について詳しくは、プレイリストのページをご覧ください。メディア アイテムの作成時に利用可能なさまざまなオプション（クリッピングや字幕ファイルの添付など）について詳しくは、メディア アイテムのページをご覧ください。

プレーヤーを操作する

プレーヤーの準備が完了したら、プレーヤーのメソッドを呼び出すことで再生を制御できます。よく使用されるメソッドをいくつか紹介します。

  • play と pause は、再生を開始、一時停止します。
  • seekTo を使用すると、メディア内でシークできます。
  • hasPrevious、hasNext、previous、next を使用すると、プレイリストを移動できます。
  • setRepeatMode は、メディアをループするかどうかとその方法を制御します。
  • setShuffleModeEnabled はプレイリストのシャッフルを制御します。
  • setPlaybackParameters は、再生速度と音声のピッチを調整します。

プレーヤーが PlayerView または PlayerControlView にバインドされている場合、ユーザーがこれらのコンポーネントを操作すると、プレーヤーの対応するメソッドが呼び出されます。

プレーヤーを解放する

プレーヤーが不要になったら、プレーヤーを解放することが重要です。そうすることで、動画デコーダなどの限られたリソースを解放して、他のアプリで使用できるようにします。これを行うには、ExoPlayer.release を呼び出します。