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

AndroidX Media3 移行ガイド

現在スタンドアロンの 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.1"
```
MediaSessionCompat を次の内容に置き換えます。 androidx.media3.session.MediaSession。
以前の MediaSessionCompat を作成したコードサイトでは、次のコマンドを使用します。 androidx.media3.session.MediaSession.Builder を使用して、 MediaSession。プレーヤーを渡してセッションビルダーを作成します。

注: アプリで ExoPlayer とは異なるプレーヤーを使用している場合は、渡すことができるカスタム Player 実装が必要です。プレーヤーをラップする MediaSession。詳細なガイダンスについてはメディアと連携する最小限の Player 実装を中心に
```
val player = ExoPlayer.Builder(context).build()
mediaSession = MediaSession.Builder(context, player)
    .setSessionCallback(MySessionCallback())
    .build()
```
注: Player のメソッド呼び出しをインターセプトするには、 ForwardingPlayer(player)。
アプリの要件に沿って MySessionCallback を実装します。これは省略可能です。条件コントローラがプレーヤーにメディアアイテムを追加できるようにし、 MediaSession.Callback.onAddMediaItems()。さまざまな既存 / 組織のでの再生用にメディアアイテムをプレーヤーに追加する以前の API メソッド下位互換性が確保されますこれには、 Media3 コントローラの MediaController.set/addMediaItems() メソッド。および TransportControls.prepareFrom*/playFrom* メソッドも指定できます。onAddMediaItems のサンプル実装では、セッションデモアプリの PlaybackService にあります。
セッションを破棄したコードサイトでメディアセッションを解放します。次の作業を行います。
```
mediaSession?.run {
  player.release()
  release()
  mediaSession = null
}
```
注: 新しいメディアセッションを作成する前に、メディアセッションを解放することが重要です。作成します。アプリがセッションをリークしている場合、Media3 が例外をスローする

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 を使用します。

サービス、アクティビティ、外部アプリを示したアプリコンポーネントの図。 — **図 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.4.1"
```
代わりに 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 の）パーツ以前のクラスに関連付けられたコードを適宜変更する必要があります。代わりに Media3 MediaItem にマッピングします。
- 一般的な非同期プログラミングモデルは 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 が表示されます。

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

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

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