AndroidX Media3 移行ガイド

現在スタンドアロンの com.google.android.exoplayer2 を使用しているアプリ ライブラリと androidx.mediaandroidx.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 のパッケージは、 移行スクリプトを実行します
  • MediaSessionConnectorandroidx.media:media:1.4.3+ 個の androidx.media.* パッケージ)
    MediaSessionConnector を削除して、 androidx.media3.session.MediaSession を使用してください。
  • MediaBrowserServiceCompatandroidx.media:media:1.4.3+ 個の androidx.media.* パッケージ)
    androidx.media.MediaBrowserServiceCompat のサブクラスを以下に移行: androidx.media3.session.MediaLibraryService を使用し、 MediaBrowserCompat.MediaItemandroidx.media3.common.MediaItem
  • MediaBrowserCompatandroidx.media:media:1.4.3+ 個の android.support.v4.media.* パッケージ)
    MediaBrowserCompat または MediaControllerCompatandroidx.media3.session.MediaBrowser を使用する androidx.media3.common.MediaItem に置き換えます。

前提条件

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

    スクリプトによる移行ツールで適用された変更を簡単に元に戻すことができる。 まだプロジェクトをソース管理にしていない場合は、ここで確認する 確認しましょう。なんらかの理由で変更したくない場合は、 プロジェクトのバックアップ コピーを作成します。

  2. アプリを更新する

    • プロジェクトを更新して、 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

移行スクリプトの使用

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

    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. スクリプトによるコードの変更を確認する: 差分ツールを使用して修正します。 発生する可能性のある問題(スクリプトにバグがあると思われる場合は、バグの報告を検討してください) これは、-f オプションを渡さずに生じた一般的な問題です)。
  2. プロジェクトをビルドする: ./gradlew clean build または Android を使用します。 Studio で [ファイル] >Sync Project with Gradle Files > [Build] > [Clean project] をクリックし、[Build >プロジェクトを再ビルドする'ビルド - ビルド出力'タブをご覧ください。
で確認できます。

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

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

MediaSessionConnectorandroidx.media3.session.MediaSession に置き換えます。

以前の MediaSessionCompat では、MediaSessionConnector は プレーヤーの状態とセッションの状態の同期を行います。 適切に委任する必要があったコントローラから 使用します。AndroidX Media3 では、これは MediaSession によって直接行われます。 簡単にアクセスできます

  1. Remove all reference and usage of 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 メソッド 下位互換性が確保されますこれには、 Media3 コントローラの MediaController.set/addMediaItems() メソッド。 および TransportControls.prepareFrom*/playFrom* メソッドも指定できます。onAddMediaItems のサンプル実装では、 セッション デモアプリの PlaybackService にあります。

  6. セッションを破棄したコードサイトでメディア セッションを解放します。 次の作業を行います。

    mediaSession?.run {
      player.release()
      release()
      mediaSession = null
    }
    

Media3 の MediaSessionConnector 機能

次の表に、機能を処理する Media3 API を示します。 以前に実装されていた MediaSessionConnector です。

MediaSessionConnectorAndroidX 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

MediaBrowserServiceMediaLibraryService に移行する

AndroidX Media3 では、MediaLibraryService という MediaBrowserServiceCompatMediaLibraryService の JavaDoc とそのスーパー クラス MediaSessionService は、API の概要と 非同期プログラミング モデルを使用します。

MediaLibraryService には、 MediaBrowserServiceMediaBrowserCompat または MediaControllerCompat は、接続時にコードを変更しなくても引き続き動作する MediaLibraryService にマッピングします。クライアントにとっては、アプリが MediaLibraryService または以前の MediaBrowserServiceCompat を使用します。

<ph type="x-smartling-placeholder">
</ph> サービス、アクティビティ、外部アプリを示したアプリ コンポーネントの図。
図 1: メディアアプリ コンポーネントの概要
  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. 代わりに 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.MediaItemMediaMetadataCompat の)パーツ 以前のクラスに関連付けられたコードを適宜変更する必要があります。 代わりに Media3 MediaItem にマッピングします。

    • 一般的な非同期プログラミング モデルは Futures に変更されましたが、 分離可能な Result アプローチとは対照的です。 MediaBrowserServiceCompat。サービスの実装では、 結果をデタッチするのではなく、非同期 ListenableFuture を使用して、 即値 Future を返して値を直接返す

PlayerNotificationManager を削除する

MediaLibraryService はメディア通知を自動的にサポートしており、 PlayerNotificationManager は、MediaLibraryService を使用する場合に削除できます。 MediaSessionService

アプリは、カスタム設定を設定することで通知をカスタマイズできます。 onCreate()MediaNotification.Provider に置き換わる DefaultMediaNotificationProvider。その後、MediaLibraryService が 必要に応じてフォアグラウンドでサービスを開始します。

MediaLibraryService.updateNotification() をオーバーライドすることで、アプリはさらに 完全な所有権で通知の送信、サービスの開始/停止を 必要に応じてフォアグラウンドに移動します。

MediaBrowser を使用してクライアント コードを移行する

AndroidX Media3 では、MediaBrowserMediaController/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 ライブラリ:

  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 サーフェスの保証が できます。違いは単に lint エラーが発生すると、 サポートします。

不安定な API lint エラーを処理する

詳しい手順については、lint エラーのトラブルシューティングのセクションをご覧ください。 不安定な API の Java と Kotlin の使用に @OptIn でアノテーションを付ける

サポート終了 API

Android では、非推奨の API の呼び出しに取り消し線が引かれている場合があります。 できます。このような呼び出しは、適切な代替機能に置き換えることをおすすめします。 この記号にカーソルを合わせると、代わりに使用する API を示す JavaDoc が表示されます。

<ph type="x-smartling-placeholder">
</ph> スクリーンショット: 非推奨のメソッドの代わりに JavaDoc を表示する方法
図 3: Android Studio の JavaDoc ツールチップ。非推奨のシンボルの代替手段が提案されます。

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

  • 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: カスタム コマンドとログイン