現在、スタンドアロンの 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.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
はメディア通知を自動的にサポートし、MediaLibraryService
または MediaSessionService
を使用する場合は PlayerNotificationManager
を削除できます。
アプリは、onCreate()
に DefaultMediaNotificationProvider
に代わるカスタム MediaNotification.Provider
を設定して、通知をカスタマイズできます。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(branch media3)(モバイル、AutomotiveOS)
- システム UI 通知、MediaButton/BT、再生の再開
- Google アシスタント/Wear OS の再生コントロール
- AutomotiveOS: カスタム コマンドとログイン