AndroidX Media3 移行ガイド

現在、スタンドアロンの 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 を使用するようにします。

前提条件

1. プロジェクトがソース管理下にあることを確認する

   スクリプトによる移行ツールによって適用された変更を簡単に元に戻せるようにします。プロジェクトをソース管理下にまだ置いていない場合は、今が始めるチャンスです。なんらかの理由で削除しない場合は、移行を開始する前にプロジェクトのバックアップ コピーを作成してください。

2. アプリを更新する

   • プロジェクトを更新して 最新バージョンの 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

移行スクリプトを使用する

1. アプリを更新したバージョンに対応する GitHub の ExoPlayer プロジェクトのタグから移行スクリプトをダウンロードします。

   curl -o media3-migration.sh \
     "https://raw.githubusercontent.com/google/ExoPlayer/r2.19.1/media3-migration.sh"
   

2. スクリプトを実行可能にします。

   chmod 744 media3-migration.sh
   

3. --help を使用してスクリプトを実行すると、オプションを確認できます。

4. -l を使用してスクリプトを実行し、移行に選択されたファイルのセットを表示します（-f を使用して、警告なしで強制的にリストします）。

   ./media3-migration.sh -l -f /path/to/gradle/project/root
   

5. -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 オプションを使用してスクリプトを実行した後、次の手順を手動で完了します。

1. スクリプトがコードをどのように変更したかを確認する: diff ツールを使用して、潜在的な問題を修正します（-f オプションを渡さずにスクリプトに一般的な問題が発生していると思われる場合は、バグを報告することを検討してください）。
2. プロジェクトをビルドする: ./gradlew clean build を使用するか、Android Studio で [File] > [Sync Project with Gradle Files]、[Build] > [Clean project]、[Build] > [Rebuild project] の順に選択します（Android Studio の [Build - Build Output] タブでビルドをモニタリングします）。

推奨されるフォローアップ手順:

1. 不安定な API の使用に関するエラーのオプトインを解決しました。
2. 非推奨の API 呼び出しを置き換える: 推奨される置き換え API を使用します。Android Studio で警告にポインタを合わせ、非推奨のシンボルの JavaDoc を参照して、特定の呼び出しの代わりに何を使用するかを確認します。
3. インポート ステートメントを並べ替える: Android Studio でプロジェクトを開き、プロジェクト ビューアのパッケージ フォルダ ノードを右クリックして、変更されたソースファイルを含むパッケージで [インポートを最適化] を選択します。

MediaSessionConnector を androidx.media3.session.MediaSession に置き換えます。

以前の MediaSessionCompat の世界では、MediaSessionConnector はプレーヤーの状態をセッションの状態と同期し、適切なプレーヤー メソッドへの委任が必要なコントローラからコマンドを受け取っていました。AndroidX Media3 では、コネクタを必要とせずに MediaSession によって直接行われます。

1. MediaSessionConnector の参照と使用をすべて削除する: 自動化スクリプトを使用して ExoPlayer クラスとパッケージを移行した場合、そのスクリプトによって、解決できない MediaSessionConnector に関するコードがコンパイルできない状態になっている可能性があります。アプリのビルドまたは起動を試みると、Android Studio にエラーのあるコードが表示されます。

2. 依存関係を管理する build.gradle ファイルで、AndroidX Media3 セッション モジュールに実装依存関係を追加し、以前の依存関係を削除します。

   implementation "androidx.media3:media3-session:1.4.1"
   

3. MediaSessionCompat を androidx.media3.session.MediaSession に置き換えます。

4. レガシー MediaSessionCompat を作成したコードサイトで、androidx.media3.session.MediaSession.Builder を使用して MediaSession をビルドします。プレーヤーを渡すと、セッション ビルダーが作成されます。

   val player = ExoPlayer.Builder(context).build()
   mediaSession = MediaSession.Builder(context, player)
       .setSessionCallback(MySessionCallback())
       .build()
   

5. アプリの要件に応じて MySessionCallback を実装します。これは省略可能です。コントローラがプレーヤーにメディア アイテムを追加できるようにするには、MediaSession.Callback.onAddMediaItems() を実装します。下位互換性のある方法で再生するために、メディア アイテムをプレーヤーに追加するさまざまな現在の API メソッドと以前の API メソッドを提供します。これには、Media3 コントローラの MediaController.set/addMediaItems() メソッドと、以前の API の TransportControls.prepareFrom*/playFrom* メソッドが含まれます。onAddMediaItems の実装例は、セッション デモアプリの PlaybackService にあります。

6. 移行前にセッションを破棄したコードサイトでメディア セッションを解放します。

   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 を使用しているかは透明です。

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>
   

2. 依存関係を管理する build.gradle ファイルで、AndroidX Media3 セッション モジュールに実装依存関係を追加し、以前の依存関係を削除します。

   implementation "androidx.media3:media3-session:1.4.1"
   

3. 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 が使用されています。以前のクラスに関連付けられているコードの一部は、それに応じて変更するか、代わりに Media3 MediaItem にマッピングする必要があります。

   • 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 つの問題が発生しました。

1. から ExoPlayer バージョンにアップグレードすると、コードのコンパイルが停止する可能性があります。
2. 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: カスタム コマンドとログイン