スタート ガイド

シンプルなユースケースでは、ExoPlayer の使用を開始するには、次の手順を実装します。

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

これらの手順について詳しくは、以下をご覧ください。完全な例については、メイン デモアプリの PlayerActivityをご覧ください。

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

ExoPlayer モジュールを追加する

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

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

Kotlin

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

Groovy

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

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

AndroidX Media3 には、追加機能を提供するために外部ライブラリに依存するライブラリ モジュールがあります。一部は Maven リポジトリから入手できますが、手動でビルドする必要があるものもあります。 詳細については、libraries ディレクトリを参照し、個々の 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()
HelloWorld.kt

Java

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

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

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
HelloWorld.kt

Java

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

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)
HelloWorld.kt

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()
HelloWorld.kt

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();
HelloWorld.java

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

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()
HelloWorld.kt

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();
HelloWorld.java

再生中に再生リストを更新できます。プレーヤーを再度準備する必要はありません。再生リストの設定と操作について詳しくは、 再生リストのページをご覧ください。メディア アイテムの作成時に使用できるさまざまなオプション（クリップや字幕ファイルの添付など）について詳しくは、 アイテムページをご覧ください。

プレーヤーを制御する

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

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

プレーヤーが PlayerView または PlayerControlView にバインドされている場合、これらのコンポーネントに対するユーザー インタラクションによって、プレーヤーの対応するメソッドが呼び出されます。

プレーヤーを解放する

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