スタート ガイド

単純なユースケースの場合、ExoPlayer の使用を開始するには次の手順を実装します。

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

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

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

ExoPlayer モジュールを追加する

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

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

Kotlin

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

Groovy

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

ここで、1.3.1 が優先バージョンです（最新バージョンについては、リリースノートをご覧ください）。すべてのモジュールは同じバージョンである必要があります。

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

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

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

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

compileOptions {
  targetCompatibility JavaVersion.VERSION_1_8
}

Multidex を有効にする

Gradle の minSdkVersion が 20 以下の場合は、ビルドエラーを防ぐために Multidex を有効にする必要があります。

プレーヤーを作成する

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

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 の「スレッドモデル」をご覧ください。

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

ExoPlayer ライブラリには、メディア再生用にさまざまなビルド済み 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);

PlayerControlView をスタンドアロン コンポーネントとして使用することもできます。これは音声のみのユースケースに役立ちます。

ExoPlayer のビルド済み UI コンポーネントの使用は任意です。独自の UI を実装する動画アプリでは、ExoPlayer の setVideoSurfaceView、setVideoTextureView、setVideoSurfaceHolder、setVideoSurface メソッドを使用して、それぞれターゲットの SurfaceView、TextureView、SurfaceHolder、または Surface を設定できます。ExoPlayer の addTextOutput メソッドを使用して、再生中にレンダリングされる字幕を受け取ることができます。

プレイリストへのデータ入力とプレーヤーの準備

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 はプレイリストを直接サポートしているため、複数のメディア アイテムを連続して再生するプレーヤーを準備できます。

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 を呼び出します。