現在スタンドアロンの com.google.android.exoplayer2
を使用しているアプリ
ライブラリと androidx.media
を androidx.media3
に移行する必要があります。使用
移行スクリプト: Gradle ビルドファイル、Java、
Kotlin ソースファイル、ExoPlayer の XML レイアウト ファイル
2.19.1
を AndroidX Media3 の 1.1.1
にマッピング。
概要
移行する前に、以下のセクションで詳細を確認し、 新しい API の利点、移行する API、前提条件 満たす必要があります
Jetpack Media3 に移行する理由
- ExoPlayer の新しいホームですが、
com.google.android.exoplayer2
は は終了しました。 - コンポーネント/プロセス間で Player API にアクセスする
MediaBrowser
/MediaController
。 MediaSession
の拡張機能とMediaController
API。- きめ細かいアクセス制御を使用して再生機能をアドバタイズする。
MediaSessionConnector
を削除してアプリを簡素化し、PlayerNotificationManager
。- メディア互換クライアント API との下位互換性
(
MediaBrowserCompat
/MediaControllerCompat
/MediaMetadataCompat
)
AndroidX Media3 に移行するための Media API
- ExoPlayer とその拡張機能
これには、以前の ExoPlayer プロジェクトのすべてのモジュールが含まれますが、 mediasession モジュールを廃止しました。構成に応じて、使用するアプリやモジュールは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 プラグインを最新バージョンにアップグレードする 動作するバージョンを作成します。対象 instance:
- Android Gradle プラグインのバージョン: 7.1.0
- Gradle バージョン: 7.4
アスタリスクを使用しているすべてのワイルドカード インポート ステートメントを置き換える (*)で完全修飾された import ステートメントを使用する場合: ワイルドカードを削除します。 import ステートメントを使用し、Android Studio を使用して完全修飾された ステートメント(F2 - Alt/Enter、F2 - Alt/Enter、...)。
com.google.android.exoplayer2.PlayerView
からcom.google.android.exoplayer2.StyledPlayerView
。必須項目です 同等の Pod が 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
移行スクリプトの使用
ExoPlayer プロジェクトのタグから移行スクリプトをダウンロードします。 アプリをアップデートしたバージョンに対応する GitHub:
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 で [ファイル] >Sync Project with Gradle Files > [Build] > [Clean project] をクリックし、[Build >プロジェクトを再ビルドする( 'ビルド - ビルド出力'タブをご覧ください。
推奨されるフォローアップ手順:
- 不安定な API の使用に関するエラーのオプトインを解決します。
- 非推奨の API 呼び出しの置き換え: 推奨される代替 API を使用します。 Android Studio の警告の上にポインタを置いて、JavaDoc を参照する 非推奨のシンボルを検索して、特定の呼び出しの代わりに何を使用するかを調べます。
- インポート ステートメントを並べ替える: Android Studio でプロジェクトを開き、 プロジェクト ビューアでパッケージ フォルダのノードを右クリックして、 変更されたソースファイルを含むパッケージでインポートを最適化します。
MediaSessionConnector
を androidx.media3.session.MediaSession
に置き換えます。
以前の MediaSessionCompat
では、MediaSessionConnector
は
プレーヤーの状態とセッションの状態の同期を行います。
適切に委任する必要があったコントローラから
使用します。AndroidX Media3 では、これは MediaSession
によって直接行われます。
簡単にアクセスできます
Remove all reference and usage of MediaSessionConnector: ExoPlayer のクラスとパッケージを移行する自動スクリプトで、 スクリプトによって、コードのコンパイル不可能な状態が 解決できない
MediaSessionConnector
。Android Studio は、 アプリをビルドまたは起動しようとしたときに、破損したコードが表示される。依存関係を管理する
build.gradle
ファイルに、 実装の依存関係を AndroidX Media3 セッション モジュールに追加し、 次のように変更します。implementation "androidx.media3:media3-session:1.4.0"
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 メソッド 下位互換性が確保されますこれには、 Media3 コントローラのMediaController.set/addMediaItems()
メソッド。 およびTransportControls.prepareFrom*/playFrom*
メソッドも指定できます。onAddMediaItems
のサンプル実装では、 セッション デモアプリのPlaybackService
にあります。セッションを破棄したコードサイトでメディア セッションを解放します。 次の作業を行います。
mediaSession?.run { player.release() release() mediaSession = null }
Media3 の MediaSessionConnector
機能
次の表に、機能を処理する Media3 API を示します。
以前に実装されていた MediaSessionConnector
です。
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 では、MediaLibraryService
という
MediaBrowserServiceCompat
。MediaLibraryService
の JavaDoc とそのスーパー
クラス MediaSessionService
は、API の概要と
非同期プログラミング モデルを使用します。
MediaLibraryService
には、
MediaBrowserService
。MediaBrowserCompat
または
MediaControllerCompat
は、接続時にコードを変更しなくても引き続き動作する
MediaLibraryService
にマッピングします。クライアントにとっては、アプリが
MediaLibraryService
または以前の MediaBrowserServiceCompat
を使用します。
![サービス、アクティビティ、外部アプリを示したアプリ コンポーネントの図。](https://developer.android.google.cn/static/media/images/overview.png?authuser=7&hl=ja)
下位互換性が機能するためには、両方のサービスを登録する必要があります。 インターフェースを
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.0"
代わりに
MediaLibraryService
を継承するようにサービスを変更するMediaBrowserService
前述のように、MediaLibraryService
は従来の VM と互換性があります。MediaBrowserService
。したがって、このサービスで提供されているより広範な API お客様に提示する内容は変わっていませんそのため おそらくアプリはMediaBrowserService
の実装に必要なロジックのほとんど 新しいMediaLibraryService
に適応させます。従来のバージョンとの主な違いは、
MediaBrowserServiceCompat
は次のとおりです。サービス ライフサイクル メソッドの実装:
onCreate/onDestroy
になります。ここで、 アプリがライブラリ セッション、プレーヤー、その他のリソースを割り当てる/解放する 説明します。アプリは、標準的なサービス ライフサイクル メソッドに加えて、onGetSession(MediaSession.ControllerInfo)
をオーバーライドして返す必要があるonCreate
にビルドされたMediaLibrarySession
。MediaLibraryService.MediaLibrarySessionCallback の実装: ビルド セッションには 実装する
MediaLibraryService.MediaLibrarySessionCallback
示されていますそのため、API のメソッドをオーバーライドする代わりに、 変更する場合は、以前のサービスのすべてのメソッドを 代わりにMediaLibrarySession.Callback
を使用してください。その後、コールバックを使用して
MediaLibrarySession
をビルドします。mediaLibrarySession = MediaLibrarySession.Builder(this, player, MySessionCallback()) .build()
API で MediaLibrarySessionCallback の完全な API を見つけます。 ご覧ください
MediaSession.Callback.onAddMediaItems()
を実装する: コールバックonAddMediaItems(MediaSession, ControllerInfo, List<MediaItem>)
回 プレーヤーにメディア アイテムを追加する、現在および以前のさまざまな API メソッド 下位互換性が確保されます。これには、 Media3 コントローラのMediaController.set/addMediaItems()
メソッド、 およびTransportControls.prepareFrom*/playFrom*
メソッドも指定できます。コールバックのサンプル実装では、 セッション デモアプリのPlaybackService
にあります。AndroidX Media3 が代わりに
androidx.media3.common.MediaItem
を使用している MediaBrowserCompat.MediaItem と MediaMetadataCompat の)パーツ 以前のクラスに関連付けられたコードを適宜変更する必要があります。 代わりに Media3MediaItem
にマッピングします。一般的な非同期プログラミング モデルは
Futures
に変更されましたが、 分離可能なResult
アプローチとは対照的です。MediaBrowserServiceCompat
。サービスの実装では、 結果をデタッチするのではなく、非同期ListenableFuture
を使用して、 即値 Future を返して値を直接返す。
PlayerNotificationManager を削除する
MediaLibraryService
はメディア通知を自動的にサポートしており、
PlayerNotificationManager
は、MediaLibraryService
を使用する場合に削除できます。
MediaSessionService
。
アプリは、カスタム設定を設定することで通知をカスタマイズできます。
onCreate()
の MediaNotification.Provider
に置き換わる
DefaultMediaNotificationProvider
。その後、MediaLibraryService
が
必要に応じてフォアグラウンドでサービスを開始します。
MediaLibraryService.updateNotification()
をオーバーライドすることで、アプリはさらに
完全な所有権で通知の送信、サービスの開始/停止を
必要に応じてフォアグラウンドに移動します。
MediaBrowser を使用してクライアント コードを移行する
AndroidX Media3 では、MediaBrowser
は MediaController/Player
を実装します。
インターフェースを備え、メディアの閲覧のほか、メディア再生の制御にも使用できます。
ライブラリです。MediaBrowserCompat
と 2 つ目の Pod を
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 のユーザーに 2 つの問題を引き起こしました。 および v2 ライブラリ:
- 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 サーフェスの保証が できます。違いは単に lint エラーが発生すると、 サポートします。
不安定な API lint エラーを処理する
詳しい手順については、lint エラーのトラブルシューティングのセクションをご覧ください。
不安定な API の Java と Kotlin の使用に @OptIn
でアノテーションを付ける
サポート終了 API
Android では、非推奨の API の呼び出しに取り消し線が引かれている場合があります。 できます。このような呼び出しは、適切な代替に置き換えることをおすすめします。 この記号にカーソルを合わせると、代わりに使用する API を示す JavaDoc が表示されます。
<ph type="x-smartling-placeholder">![スクリーンショット: 非推奨のメソッドの代わりに JavaDoc を表示する方法](https://developer.android.google.cn/static/media/media3/exoplayer/images/deprecation.png?authuser=7&hl=ja)
コードサンプルとデモアプリ
- AndroidX Media3 セッション デモアプリ(モバイル、WearOS)
<ph type="x-smartling-placeholder">
- </ph>
- カスタム アクション
- システム UI 通知、MediaButton/BT
- Google アシスタントの再生コントロール
- UAMP: Android Media Player(ブランチ media3)(モバイル、AutomotiveOS)
<ph type="x-smartling-placeholder">
- </ph>
- システム UI 通知、MediaButton/BT、再生の再開
- Google アシスタント/Wear OS の再生コントロール
- AutomotiveOS: カスタム コマンドとログイン