現在スタンドアロンの 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
をビルドします。プレーヤーを渡してセッション ビルダーを作成します。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
の JavaDoc とそのスーパークラス MediaSessionService
は、サービスの 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.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
を使用しています。以前のクラスに関連付けられているコード部分は、それに応じて変更するか、代わりに Media3MediaItem
にマッピングする必要があります。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 が表示されます。
コードサンプルとデモアプリ
- AndroidX Media3 セッション デモアプリ(モバイルと WearOS)
- カスタム アクション
- システム UI 通知、MediaButton/BT
- Google アシスタントの再生コントロール
- UAMP: Android Media Player(ブランチ media3)(モバイル、AutomotiveOS)
- システム UI 通知、MediaButton/BT、再生の再開
- Google アシスタント/Wear OS の再生コントロール
- AutomotiveOS: カスタム コマンドとログイン