このページは Cloud Translation API によって翻訳されました。

AndroidX Media3 移行ガイド

現在スタンドアロンの com.google.android.exoplayer2 ライブラリと androidx.media を使用しているアプリは、androidx.media3 に移行する必要があります。移行スクリプトを使用して、Gradle ビルドファイル、Java および Kotlin ソースファイル、XML レイアウトファイルを ExoPlayer 2.19.1 から AndroidX Media3 1.1.1 に移行します。

概要

移行する前に、以下のセクションで、新しい API のメリット、移行する API、アプリのプロジェクトが満たすべき前提条件を確認してください。

Jetpack Media3 に移行する理由

これは ExoPlayer の新しいホームですが、com.google.android.exoplayer2 は廃止されました。
MediaBrowser/MediaController を使用して、コンポーネント/プロセス間で Player API にアクセスする。
MediaSession API と MediaController API の拡張機能を使用する。
きめ細かいアクセス制御を使用して再生機能をアドバタイズする。
MediaSessionConnector と PlayerNotificationManager を削除してアプリを簡素化します。
メディア互換クライアント API（MediaBrowserCompat/MediaControllerCompat/MediaMetadataCompat）との下位互換性

AndroidX Media3 に移行するための Media API

ExoPlayer とその拡張機能
これには、廃止された mediasession モジュールを除く、以前の ExoPlayer プロジェクトのすべてのモジュールが含まれます。com.google.android.exoplayer2 のパッケージに依存するアプリやモジュールは、移行スクリプトを使用して移行できます。
MediaSessionConnector（androidx.media:media:1.4.3+ の androidx.media.* パッケージによって異なる）
MediaSessionConnector を削除し、代わりに androidx.media3.session.MediaSession を使用します。
MediaBrowserServiceCompat（androidx.media:media:1.4.3+ の androidx.media.* パッケージによって異なる）
androidx.media.MediaBrowserServiceCompat のサブクラスを androidx.media3.session.MediaLibraryService に移行し、MediaBrowserCompat.MediaItem を使用するコードを androidx.media3.common.MediaItem に移行します。
MediaBrowserCompat（androidx.media:media:1.4.3+ の android.support.v4.media.* パッケージによって異なる）
MediaBrowserCompat または MediaControllerCompat を使用してクライアントコードを移行し、androidx.media3.session.MediaBrowser を androidx.media3.common.MediaItem とともに使用します。

前提条件

プロジェクトがソース管理下にあることを確認する

スクリプトによる移行ツールによって適用された変更を簡単に元に戻せるようにします。プロジェクトをまだソース管理にしていない場合は、ここで開始することをおすすめします。なんらかの理由で移行を希望されない場合は、移行を開始する前にプロジェクトのバックアップコピーを作成してください。
アプリを更新する
- 最新バージョンの ExoPlayer ライブラリを使用するようにプロジェクトを更新し、非推奨のメソッドの呼び出しを削除することをおすすめします。移行にスクリプトを使用する場合は、更新先のバージョンをスクリプトによって処理されるバージョンと一致させる必要があります。
- アプリの compileSdkVersion を 32 以上に増やします。
- 上記の更新された依存関係で動作する最新バージョンに Gradle と Android Studio Gradle プラグインをアップグレードします。次に例を示します。
  - Android Gradle プラグインのバージョン: 7.1.0
  - Gradle バージョン: 7.4
- アスタリスク（*）を使用し、完全修飾されたインポートステートメントを使用するすべてのワイルドカードインポートステートメントを置き換える: ワイルドカードインポートステートメントを削除し、Android Studio を使用して完全修飾ステートメントをインポートします（F2 - Alt/Enter、F2 - Alt/Enter など）。
- com.google.android.exoplayer2.PlayerView から com.google.android.exoplayer2.StyledPlayerView に移行する。AndroidX Media3 には、com.google.android.exoplayer2.PlayerView に相当するものがないため、これが必要となります。

スクリプトのサポートによる ExoPlayer の移行

このスクリプトにより、com.google.android.exoplayer2 から androidx.media3 の下の新しいパッケージとモジュール構造に簡単に移動できます。このスクリプトは、プロジェクトに検証チェックを適用し、検証が失敗した場合は警告を出力します。それ以外の場合は、Java または Kotlin で記述された Android Gradle プロジェクトのリソースに、名前を変更したクラスとパッケージのマッピングが適用されます。

usage: ./media3-migration.sh [-p|-c|-d|-v]|[-m|-l [-x <path>] [-f] PROJECT_ROOT]
 PROJECT_ROOT: path to your project root (location of 'gradlew')
 -p: list package mappings and then exit
 -c: list class mappings (precedence over package mappings) and then exit
 -d: list dependency mappings and then exit
 -l: list files that will be considered for rewrite and then exit
 -x: exclude the path from the list of file to be changed: 'app/src/test'
 -m: migrate packages, classes and dependencies to AndroidX Media3
 -f: force the action even when validation fails
 -v: print the exoplayer2/media3 version strings of this script
 -h, --help: show this help text

移行スクリプトの使用

GitHub で、アプリをアップデートしたバージョンに対応する ExoPlayer プロジェクトのタグから移行スクリプトをダウンロードします。
```
curl -o media3-migration.sh \
  "https://raw.githubusercontent.com/google/ExoPlayer/r2.19.1/media3-migration.sh"
```
スクリプトを実行可能にします。
```
chmod 744 media3-migration.sh
```
--help を指定してスクリプトを実行し、オプションを確認します。
-l を指定してスクリプトを実行し、移行対象として選択されたファイルのセットを一覧表示します（警告なしで強制的に一覧表示するには、-f を使用します）。
```
./media3-migration.sh -l -f /path/to/gradle/project/root
```
-m を使用してスクリプトを実行し、パッケージ、クラス、モジュールを Media3 にマッピングします。-m オプションを指定してスクリプトを実行すると、選択したファイルに変更内容が適用されます。
- 変更を加えずに検証エラーで停止
```
./media3-migration.sh -m /path/to/gradle/project/root
```
- 強制実行
スクリプトが前提条件に違反していることが判明した場合は、-f フラグを使用して移行を強制的に実行できます。
```
./media3-migration.sh -m -f /path/to/gradle/project/root
```

 # list files selected for migration when excluding paths
 ./media3-migration.sh -l -x "app/src/test/" -x "service/" /path/to/project/root
 # migrate the selected files
 ./media3-migration.sh -m -x "app/src/test/" -x "service/" /path/to/project/root

-m オプションを指定してスクリプトを実行した後、次の手動での手順を行います。

スクリプトによるコードの変更を確認する: 差分ツールを使用して、潜在的な問題を修正します（-f オプションを渡さずに引き起こされた一般的な問題がスクリプトにあると思われる場合は、バグの報告を検討してください）。
プロジェクトをビルドします: ./gradlew clean build を使用するか、Android Studio で [File] > [Sync Project with Gradle Files]、[Build] > [Clean project]、[Build] > [Rebuild project] の順に選択します（ビルドは、Android Studio の [Build - Build Output] タブでモニタリングします）。

推奨されるフォローアップ手順:

不安定な API の使用に関するエラーのオプトインを解決します。
非推奨の API 呼び出しの置き換え: 推奨される代替 API を使用します。Android Studio の警告の上にポインタを置き、非推奨のシンボルの JavaDoc を参照して、特定の呼び出しの代わりに何を使用するかを確認します。
インポートステートメントを並べ替える: Android Studio でプロジェクトを開き、プロジェクトビューアでパッケージフォルダノードを右クリックし、変更されたソースファイルを含むパッケージで [Optimize imports（インポートを最適化する）] を選択します。

`MediaSessionConnector` を `androidx.media3.session.MediaSession` に置き換えます。

以前の MediaSessionCompat 環境では、MediaSessionConnector がプレーヤーの状態をセッションの状態と同期し、適切なプレーヤーメソッドへの委任が必要なコントローラからコマンドを受信していました。AndroidX Media3 では、コネクタを必要とせずに、MediaSession が直接行います。

MediaSessionConnector の参照と使用をすべて削除: 自動スクリプトを使用して ExoPlayer のクラスとパッケージを移行した場合は、解決できない MediaSessionConnector に関してコードがコンパイル不能な状態になっている可能性があります。アプリをビルドまたは起動しようとすると、破損したコードが表示されます。
依存関係を管理する build.gradle ファイルで、AndroidX Media3 セッションモジュールに実装依存関係を追加し、以前の依存関係を削除します。
```
implementation "androidx.media3:media3-session:1.3.1"
```
MediaSessionCompat を androidx.media3.session.MediaSession に置き換えます。
以前の MediaSessionCompat を作成したコードサイトで、androidx.media3.session.MediaSession.Builder を使用して MediaSession をビルドします。プレーヤーを渡してセッションビルダーを作成します。

注: アプリで ExoPlayer とは異なるプレーヤーを使用している場合は、プレーヤーをラップする MediaSession に渡すことができるカスタムの Player 実装が必要です。メディアセッションの実装と連携する最小限の Player 実装に関する詳細なガイダンスを提供します。
```
val player = ExoPlayer.Builder(context).build()
mediaSession = MediaSession.Builder(context, player)
    .setSessionCallback(MySessionCallback())
    .build()
```
注: Player のメソッド呼び出しは、ForwardingPlayer(player) でラップすることでインターセプトできます。
アプリの要件に沿って MySessionCallback を実装します。これは省略可能です。コントローラがプレーヤーにメディアアイテムを追加できるようにするには、MediaSession.Callback.onAddMediaItems() を実装します。この API は、下位互換性のある方法で再生するためにメディアアイテムをプレーヤーに追加する、現在および従来のさまざまな API メソッドを提供します。これには、Media3 コントローラの MediaController.set/addMediaItems() メソッドや、レガシー API の TransportControls.prepareFrom*/playFrom* メソッドが含まれます。onAddMediaItems の実装例については、セッションデモアプリの PlaybackService をご覧ください。
移行前にセッションを破棄したコードサイトで、メディアセッションを解放します。
```
mediaSession?.run {
  player.release()
  release()
  mediaSession = null
}
```
注: 同じ ID で新しいメディアセッションを作成する前に、メディアセッションを解放することが重要です。アプリがセッションインスタンスをリークしている場合、Media3 は例外をスローします。

Media3 の `MediaSessionConnector` 機能

次の表に、MediaSessionConnector に以前実装された機能を処理する Media3 API を示します。

MediaSessionConnector	AndroidX Media3
`CustomActionProvider`	`MediaSession.Callback.onCustomCommand()/ MediaSession.setCustomLayout()`
`PlaybackPreparer`	`MediaSession.Callback.onAddMediaItems()`（`prepare()` は内部で呼び出されます）
`QueueNavigator`	`ForwardingPlayer`
`QueueEditor`	`MediaSession.Callback.onAddMediaItems()`
`RatingCallback`	`MediaSession.Callback.onSetRating()`
`PlayerNotificationManager`	`DefaultMediaNotificationProvider/ MediaNotification.Provider`

`MediaBrowserService` を `MediaLibraryService` に移行する

AndroidX Media3 には、MediaBrowserServiceCompat に代わる MediaLibraryService が導入されています。MediaLibraryService の JavaDoc とそのスーパークラス MediaSessionService は、サービスの API と非同期プログラミングモデルの概要を示しています。

MediaLibraryService には MediaBrowserService と下位互換性があります。MediaBrowserCompat または MediaControllerCompat を使用するクライアントアプリは、MediaLibraryService に接続するときに、コードを変更しなくても引き続き動作します。クライアントについては、アプリが MediaLibraryService を使用しているか、以前の MediaBrowserServiceCompat を使用しているかが透過的です。

サービス、アクティビティ、外部アプリを示したアプリコンポーネントの図。 — **図 1**: メディアアプリコンポーネントの概要

下位互換性を機能させるには、AndroidManifest.xml でサービスに両方のサービスインターフェースを登録する必要があります。このようにして、クライアントは必要なサービスインターフェースによってサービスを見つけます。
```
<service android:name=".MusicService" android:exported="true">
    <intent-filter>
        <action android:name="androidx.media3.session.MediaLibraryService"/>
        <action android:name="android.media.browse.MediaBrowserService" />
    </intent-filter>
</service>
```
依存関係を管理する build.gradle ファイルで、AndroidX Media3 セッションモジュールに実装依存関係を追加し、以前の依存関係を削除します。
```
implementation "androidx.media3:media3-session:1.3.1"
```
MediaBrowserService ではなく MediaLibraryService から継承するようにサービスを変更します。前述のように、MediaLibraryService は以前の MediaBrowserService と互換性があります。したがって、サービスがクライアントに提供する広範な API は変わりません。そのため、MediaBrowserService を実装して新しい MediaLibraryService に適応させるために必要なロジックのほとんどはアプリで保持できます。

以前の MediaBrowserServiceCompat との主な違いは次のとおりです。
- サービスライフサイクルメソッドを実装する: サービス自体でオーバーライドする必要があるメソッドは onCreate/onDestroy です。ここで、アプリはライブラリセッション、プレーヤー、その他のリソースの割り当てとリリースを行います。標準のサービスライフサイクルメソッドに加えて、アプリは onGetSession(MediaSession.ControllerInfo) をオーバーライドして、onCreate にビルドされた MediaLibrarySession を返す必要があります。
- MediaLibraryService.MediaLibrarySessionCallback の実装: セッションを作成するには、実際のドメイン API メソッドを実装する MediaLibraryService.MediaLibrarySessionCallback が必要です。そのため、レガシーサービスの API メソッドをオーバーライドするのではなく、MediaLibrarySession.Callback のメソッドをオーバーライドします。
  
  その後、コールバックを使用して MediaLibrarySession をビルドします。
```
mediaLibrarySession =
      MediaLibrarySession.Builder(this, player, MySessionCallback())
         .build()
```
  MediaLibrarySessionCallback の完全な API については、API ドキュメントをご覧ください。
- MediaSession.Callback.onAddMediaItems() を実装する: コールバック onAddMediaItems(MediaSession, ControllerInfo, List<MediaItem>) は、下位互換性のある方法で再生するためにメディアアイテムをプレーヤーに追加する、現在および以前のさまざまな API メソッドを提供します。これには、Media3 コントローラの MediaController.set/addMediaItems() メソッドや、レガシー API の TransportControls.prepareFrom*/playFrom* メソッドが含まれます。コールバックのサンプル実装は、セッションデモアプリの PlaybackService にあります。
- AndroidX Media3 は、MediaBrowserCompat.MediaItem と MediaMetadataCompat の代わりに androidx.media3.common.MediaItem を使用しています。以前のクラスに関連付けられているコード部分は、それに応じて変更するか、代わりに Media3 MediaItem にマッピングする必要があります。
- MediaBrowserServiceCompat の取り外し可能な Result アプローチとは対照的に、一般的な非同期プログラミングモデルは Futures に変更されました。サービスの実装では、結果をデタッチする代わりに非同期の ListenableFuture を返すか、すぐに値を返す Future を返すことができます。

PlayerNotificationManager を削除する

MediaLibraryService はメディア通知を自動的にサポートします。MediaLibraryService または MediaSessionService を使用する場合は、PlayerNotificationManager を削除できます。

DefaultMediaNotificationProvider を置き換えるカスタム MediaNotification.Provider を onCreate() で設定することで、アプリで通知をカスタマイズできます。その後、MediaLibraryService が必要に応じてフォアグラウンドでサービスを開始します。

MediaLibraryService.updateNotification() をオーバーライドすることにより、アプリはさらに、通知の送信と、必要に応じてフォアグラウンドでサービスを開始/停止するための完全な所有権を取得できます。

MediaBrowser を使用してクライアントコードを移行する

AndroidX Media3 では、MediaBrowser は MediaController/Player インターフェースを実装し、メディアライブラリのブラウジングに加えてメディア再生の制御に使用できます。以前の環境で MediaBrowserCompat と MediaControllerCompat を作成する必要がある場合は、Media3 の MediaBrowser を使用するだけで作成できます。

MediaBrowser を作成し、サービスへの接続が確立されるのを待ちます。

scope.launch {
    val sessionToken =
        SessionToken(context, ComponentName(context, MusicService::class.java)
    browser =
        MediaBrowser.Builder(context, sessionToken))
            .setListener(BrowserListener())
            .buildAsync()
            .await()
    // Get the library root to start browsing the library.
    root = browser.getLibraryRoot(/* params= */ null).await();
    // Add a MediaController.Listener to listen to player state events.
    browser.addListener(playerListener)
    playerView.setPlayer(browser)
}

バックグラウンドでの再生を制御する MediaController を作成する方法については、メディアセッションでの再生を制御するをご覧ください。

次のステップとクリーンアップ

不安定な API エラー

Media3 への移行後、不安定な API の使用に関する lint エラーが表示されることがあります。これらの API は安全に使用できます。lint エラーは、新しいバイナリ互換性保証の副産物です。厳密なバイナリ互換性が必要ない場合は、@OptIn アノテーションを使用してこれらのエラーを安全に抑制できます。

背景情報

ExoPlayer v1 と v2 のいずれも、後続のバージョン間でのライブラリのバイナリ互換性について厳密な保証を提供していません。ExoPlayer API のサーフェスは、アプリが再生のほぼすべての側面をカスタマイズできるように、設計上非常に大きくなっています。ExoPlayer の後続のバージョンでは、シンボル名の変更やその他の破壊的変更（インターフェースで新しい必須メソッドなど）が導入されることがあります。ほとんどの場合、これらの互換性の問題は、デベロッパーが使用環境を移行する時間を確保するために、新しいシンボルを導入し、いくつかのバージョンの古いシンボルを非推奨にすることで軽減されましたが、必ずしも可能とは限りませんでした。

この互換性を破る変更により、ExoPlayer v1 および v2 ライブラリのユーザーに次の 2 つの問題を引き起こしました。

ExoPlayer バージョンにアップグレードすると、コードのコンパイルが停止することがあります。
ExoPlayer に直接依存するアプリと中間ライブラリを介して依存するアプリでは、両方の依存関係が同じバージョンであることを確認する必要があります。そうしないと、バイナリの非互換性によりランタイムクラッシュが発生する可能性があります。

Media3 の改善

Media3 は API サーフェスのサブセットのバイナリ互換性を保証します。バイナリの互換性を保証しない部分には、@UnstableApi のマークが付きます。この区別を明確にするために、不安定な API シンボルを使用すると、@OptIn アノテーションが付いていない限り、lint エラーが生成されます。

ExoPlayer v2 から Media3 に移行すると、不安定な API lint エラーが多数発生することがあります。これにより、Media3 は ExoPlayer v2 よりも「安定性が低い」ように見える場合があります。これは違います。Media3 API の「不安定」な部分の安定性は、ExoPlayer v2 API サーフェス全体と同レベルです。安定した Media3 API サーフェスの保証は、ExoPlayer v2 では一切利用できません。違いは、lint エラーがさまざまなレベルの安定性を警告するようになったことです。

不安定な API lint エラーを処理する

不安定な API の Java や Kotlin の使用に @OptIn でアノテーションを付ける方法について詳しくは、これらの lint エラーのトラブルシューティングのセクションをご覧ください。

サポート終了 API

Android Studio では、非推奨の API の呼び出しに取り消し線が引かれている場合があります。このような呼び出しは、適切な代替に置き換えることをおすすめします。この記号にカーソルを合わせると、代わりに使用する API を示す JavaDoc が表示されます。

スクリーンショット: 非推奨のメソッドの代わりに JavaDoc を表示する方法 — **図 3**: Android Studio の JavaDoc ツールチップには、非推奨のシンボルの代替手段が提案されます。

コードサンプルとデモアプリ

AndroidX Media3 セッションデモアプリ（モバイルと WearOS）
- カスタムアクション
- システム UI 通知、MediaButton/BT
- Google アシスタントの再生コントロール
UAMP: Android Media Player（ブランチ media3）（モバイル、AutomotiveOS）
- システム UI 通知、MediaButton/BT、再生の再開
- Google アシスタント/Wear OS の再生コントロール
- AutomotiveOS: カスタムコマンドとログイン