単純なユースケースの場合、ExoPlayer
の使用を開始するには次の手順を実装します。
- ExoPlayer を依存関係としてプロジェクトに追加します。
ExoPlayer
インスタンスを作成します。- プレーヤーをビューにアタッチします(動画出力用とユーザー入力用)。
- プレイするプレーヤーに
MediaItem
を用意します。 - 完了したらプレーヤーを離します。
以下では、これらの手順について詳しく説明します。完全な例については、メインのデモアプリの 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
を呼び出します。