現在スタンドアロンの 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 にアクセスします。MediaSessionAPI とMediaControllerAPI の拡張機能を使用する。- きめ細かいアクセス制御で再生機能をアドバタイズします。
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.common.MediaItemでandroidx.media3.session.MediaBrowserを使用するようにします。
前提条件
プロジェクトがソース管理下にあることを確認する
スクリプトによる移行ツールによって適用された変更を簡単に元に戻せるようにします。プロジェクトをソース管理下にまだ置いていない場合は、今が始めるチャンスです。なんらかの理由で削除しない場合は、移行を開始する前にプロジェクトのバックアップ コピーを作成してください。
アプリを更新する
最新バージョンの ExoPlayer ライブラリを使用するようにプロジェクトを更新し、非推奨のメソッドの呼び出しを削除することをおすすめします。移行にスクリプトを使用する場合は、更新先のバージョンをスクリプトによって処理されるバージョンと一致させる必要があります。
アプリの compileSdkVersion を 32 以上に増やします。
上記の更新された依存関係に対応する最新バージョンに Gradle と Android Studio Gradle プラグインをアップグレードします。次に例を示します。
- Android Gradle プラグインのバージョン: 7.1.0
- Gradle のバージョン: 7.4
アスタリスク（*）を使用しているすべてのワイルドカード import ステートメントを置き換えて、完全修飾 import ステートメントを使用する: ワイルドカード import ステートメントを削除し、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 オプションを指定してスクリプトを実行した後、次の手動での手順を行います。
- スクリプトがコードをどのように変更したかを確認する: diff ツールを使用して、潜在的な問題を修正します（
-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 でプロジェクトを開き、プロジェクト ビューアのパッケージ フォルダ ノードを右クリックして、変更されたソースファイルを含むパッケージで [インポートを最適化] を選択します。
MediaSessionConnector を androidx.media3.session.MediaSession に置き換えます。
以前の MediaSessionCompat の世界では、MediaSessionConnector はプレーヤーの状態をセッションの状態と同期し、適切なプレーヤー メソッドへの委任が必要なコントローラからコマンドを受け取っていました。AndroidX Media3 では、コネクタを必要とせずに MediaSession によって直接行われます。
MediaSessionConnector の参照と使用をすべて削除する: 自動化スクリプトを使用して ExoPlayer クラスとパッケージを移行した場合、そのスクリプトによって、解決できない
MediaSessionConnectorに関するコードがコンパイルできない状態になっている可能性があります。アプリのビルドまたは起動を試みると、Android Studio にエラーのあるコードが表示されます。依存関係を管理する
build.gradleファイルで、AndroidX Media3 セッション モジュールに実装依存関係を追加し、以前の依存関係を削除します。implementation "androidx.media3:media3-session:1.4.1"MediaSessionCompatをandroidx.media3.session.MediaSessionに置き換えます。レガシー
MediaSessionCompatを作成したコードサイトで、androidx.media3.session.MediaSession.Builderを使用してMediaSessionをビルドします。プレーヤーを渡すと、セッション ビルダーが作成されます。val player = ExoPlayer.Builder(context).build() mediaSession = MediaSession.Builder(context, player) .setSessionCallback(MySessionCallback()) .build()アプリの要件に応じて
MySessionCallbackを実装します。これは省略可能です。コントローラがプレーヤーにメディア アイテムを追加できるようにするには、MediaSession.Callback.onAddMediaItems()を実装します。この API は、下位互換性のある方法で再生するためにメディア アイテムをプレーヤーに追加する、現在および従来のさまざまな API メソッドを提供します。これには、Media3 コントローラのMediaController.set/addMediaItems()メソッドと、以前の API のTransportControls.prepareFrom*/playFrom*メソッドが含まれます。onAddMediaItemsの実装例については、セッション デモアプリのPlaybackServiceをご覧ください。移行前にセッションを破棄したコードサイトで、メディア セッションを解放します。
mediaSession?.run { player.release() release() mediaSession = null }
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 とそのスーパークラス MediaSessionService の JavaDoc には、API とサービスの非同期プログラミング モデルの概要が記載されています。
MediaLibraryService は MediaBrowserService と下位互換性があります。MediaBrowserCompat または MediaControllerCompat を使用しているクライアント アプリは、MediaLibraryService に接続するときにコードを変更せずに引き続き動作します。クライアントについては、アプリが MediaLibraryService を使用しているか、以前の MediaBrowserServiceCompat を使用しているかが透過的です。
下位互換性を維持するには、
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.4.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 メソッドと以前の API メソッドを提供します。これには、Media3 コントローラのMediaController.set/addMediaItems()メソッドと、以前の API のTransportControls.prepareFrom*/playFrom*メソッドが含まれます。コールバックの実装例については、セッション デモアプリのPlaybackServiceをご覧ください。AndroidX Media3 では、MediaBrowserCompat.MediaItem と MediaMetadataCompat の代わりに
androidx.media3.common.MediaItemが使用されています。以前のクラスに関連付けられているコードの一部は、それに応じて変更するか、代わりに Media3MediaItemにマッピングする必要があります。MediaBrowserServiceCompatの取り外し可能なResultアプローチとは対照的に、一般的な非同期プログラミング モデルがFuturesに変更されました。サービス実装では、結果を切断する代わりに非同期のListenableFutureを返すか、即時 Future を返して値を直接返すことができます。
PlayerNotificationManager を削除
MediaLibraryService はメディア通知を自動的にサポートし、PlayerNotificationManager は MediaLibraryService または MediaSessionService を使用するときに削除できます。
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 サーフェスの全体と同じレベルの安定性があり、ExoPlayer v2 では安定した Media3 API サーフェスの保証はまったく利用できません。違いは、リンティング エラーで安定性のレベルが異なることを警告するようになった点です。
不安定な API lint エラーを処理する
不安定な API の Java や Kotlin の使用に @OptIn でアノテーションを付ける方法について詳しくは、これらの lint エラーのトラブルシューティングのセクションをご覧ください。
サポート終了 API
Android Studio では、非推奨の API の呼び出しが取り消し線で示されます。このような呼び出しは、適切な代替に置き換えることをおすすめします。記号にカーソルを合わせると、代わりに使用する API を示す JavaDoc が表示されます。
コードサンプルとデモアプリ
- AndroidX Media3 セッション デモアプリ（モバイルと WearOS）
- カスタム アクション
- システム UI 通知、MediaButton/BT
- Google アシスタントの再生コントロール
- UAMP: Android Media Player（ブランチ media3）（モバイル、AutomotiveOS）
- システム UI 通知、MediaButton/BT、再生の再開
- Google アシスタント/Wear OS の再生コントロール
- AutomotiveOS: カスタム コマンドとログイン