Panduan migrasi AndroidX Media3

Aplikasi yang saat ini menggunakan com.google.android.exoplayer2 mandiri library dan androidx.media akan dimigrasikan ke androidx.media3. Gunakan skrip migrasi untuk memigrasikan file build gradle, Java dan File sumber Kotlin, dan file tata letak XML dari ExoPlayer 2.19.1 ke AndroidX Media3 1.1.1.

Ringkasan

Sebelum melakukan migrasi, tinjau bagian berikut untuk mempelajari lebih lanjut manfaat dari API baru, API yang akan dimigrasikan, dan prasyaratnya yang harus dipenuhi oleh proyek aplikasi Anda.

Alasan bermigrasi ke Jetpack Media3

• Ini adalah tempat baru untuk ExoPlayer, sedangkan com.google.android.exoplayer2 adalah dihentikan.
• Akses Player API di seluruh komponen/proses dengan MediaBrowser/MediaController.
• Gunakan kemampuan tambahan MediaSession dan API MediaController.
• Iklankan kemampuan pemutaran dengan kontrol akses yang mendetail.
• Sederhanakan aplikasi Anda dengan menghapus MediaSessionConnector dan PlayerNotificationManager.
• Kompatibel dengan versi lama dengan API klien media-compat (MediaBrowserCompat/MediaControllerCompat/MediaMetadataCompat)

Media API yang akan dimigrasikan ke AndroidX Media3

• ExoPlayer dan ekstensinya
  Ini mencakup semua modul project ExoPlayer lama kecuali mediasession yang dihentikan. Aplikasi atau modul bergantung pada paket di com.google.android.exoplayer2 dapat dimigrasikan dengan skrip migrasi.
• MediaSessionConnector (bergantung pada androidx.media.* paket dari androidx.media:media:1.4.3+)
  Hapus MediaSessionConnector dan gunakan androidx.media3.session.MediaSession sebagai gantinya.
• MediaBrowserServiceCompat (bergantung pada androidx.media.* paket dari androidx.media:media:1.4.3+)
  Migrasikan subclass androidx.media.MediaBrowserServiceCompat ke androidx.media3.session.MediaLibraryService dan kode menggunakan MediaBrowserCompat.MediaItem hingga androidx.media3.common.MediaItem.
• MediaBrowserCompat (bergantung pada android.support.v4.media.* paket dari androidx.media:media:1.4.3+)
  Memigrasikan kode klien menggunakan MediaBrowserCompat atau MediaControllerCompat untuk menggunakan androidx.media3.session.MediaBrowser dengan androidx.media3.common.MediaItem.

Prasyarat

1. Memastikan project Anda berada di bawah kontrol sumber

   Pastikan Anda dapat dengan mudah mengembalikan perubahan yang diterapkan oleh alat migrasi dengan skrip. Jika Anda belum memiliki project di bawah kontrol sumber, sekarang adalah saat yang tepat untuk memulainya. Jika karena suatu alasan Anda tidak ingin melakukannya, cadangan proyek Anda sebelum memulai migrasi.

2. Mengupdate aplikasi

   • Sebaiknya update project Anda untuk menggunakan versi terbaru library ExoPlayer dan menghapus semua panggilan ke metode yang tidak digunakan lagi. Jika Anda bermaksud untuk menggunakan skrip untuk migrasi, Anda harus mencocokkan ke versi yang Anda perbarui dengan versi yang ditangani oleh skrip.

   • Tingkatkan compileSdkVersion aplikasi Anda menjadi minimal 32.

   • Upgrade Gradle dan plugin Gradle Android Studio ke versi terbaru yang berfungsi dengan dependensi yang diperbarui dari atas. Sebagai :

     • Versi Plugin Android Gradle: 7.1.0
     • Versi Gradle: 7.4

   • Mengganti semua pernyataan impor karakter pengganti yang menggunakan asterix (*) dan gunakan pernyataan impor yang sepenuhnya memenuhi syarat: Hapus karakter pengganti mengimpor pernyataan dan menggunakan Android Studio untuk mengimpor pernyataan yang sepenuhnya pernyataan (F2 - Alt/Enter, F2 - Alt/Enter, ...).

   • Migrasikan dari com.google.android.exoplayer2.PlayerView ke com.google.android.exoplayer2.StyledPlayerView. Ini diperlukan karena tidak ada yang setara dengan com.google.android.exoplayer2.PlayerView di AndroidX Media3.

Memigrasikan ExoPlayer dengan dukungan skrip

Skrip ini memfasilitasi pemindahan dari com.google.android.exoplayer2 ke skrip baru struktur paket dan modul di bagian androidx.media3. Skrip berlaku beberapa pemeriksaan validasi pada project dan mencetak peringatan jika validasi gagal. Jika tidak, alat ini akan menerapkan pemetaan class dan paket yang diganti namanya di resource project gradle Android yang ditulis dalam Java atau Kotlin.

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

Menggunakan skrip migrasi

Peringatan: Skrip dapat menempatkan file build gradle dalam status tidak dapat digunakan jika deklarasi dependensi menggunakan variabel atau teknik lanjutan.

1. Mendownload skrip migrasi dari tag project ExoPlayer di GitHub yang sesuai dengan versi aplikasi yang Anda update:

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

2. Jadikan skrip sebagai dapat dijalankan:

   chmod 744 media3-migration.sh
   

3. Jalankan skrip dengan --help untuk mempelajari opsi.

4. Jalankan skrip dengan -l untuk mencantumkan kumpulan file yang dipilih migrasi (gunakan -f untuk memaksa listingan tanpa peringatan):

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

5. Jalankan skrip dengan -m untuk memetakan paket, class, dan modul ke Media3. Menjalankan skrip dengan opsi -m akan menerapkan perubahan pada opsi yang dipilih .

   • Berhenti pada error validasi tanpa melakukan perubahan

   ./media3-migration.sh -m /path/to/gradle/project/root
   

   • Eksekusi paksa

   Jika skrip menemukan pelanggaran prasyarat, migrasi dapat dilakukan dipaksa dengan flag -f:

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

Catatan: Anda dapat menggunakan parameter -x untuk mengecualikan jalur agar tidak dipilih perubahan.

 # 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

Selesaikan langkah-langkah manual berikut setelah menjalankan skrip dengan opsi -m:

1. Periksa bagaimana skrip mengubah kode Anda: Gunakan alat perbedaan dan perbaiki potensi masalah (pertimbangkan untuk melaporkan bug jika menurut Anda skrip memiliki masalah umum yang muncul tanpa meneruskan opsi -f).
2. Buat project: Gunakan ./gradlew clean build atau di Android Studio, pilih File > Sinkronkan Project dengan File Gradle, lalu Build > Bersihkan project, lalu Build > Build ulang project (pantau build Anda di 'Buat - Output Build' Android Studio.

Catatan: Dalam beberapa kasus, skrip diharapkan membuat project Anda dalam keadaan yang tidak dibangun tanpa memigrasikan kode secara manual. Skrip memperingatkan tentang hal ini dan meminta opsi -f untuk memaksa eksekusi. Misalnya, inilah kasusnya jika aplikasi menggunakan MediaSessionConnector dan MediaSessionCompat. Lihat bagian berikutnya untuk mendapatkan panduan tentang cara bermigrasi dari MediaSessionConnector ke Media3.

Langkah-langkah tindak lanjut yang direkomendasikan:

1. Atasi keikutsertaan atas error terkait penggunaan API yang tidak stabil.
2. Ganti panggilan API yang tidak digunakan lagi: Gunakan API pengganti yang disarankan. Tahan kursor ke peringatan di Android Studio, dan lihat JavaDoc simbol yang tidak digunakan lagi untuk mencari tahu apa yang harus digunakan, alih-alih panggilan tertentu.
3. Urutkan pernyataan impor: Buka project di Android Studio, lalu klik kanan pada node folder paket di penampil project dan pilih Mengoptimalkan impor pada paket yang berisi file sumber yang diubah.

Ganti MediaSessionConnector dengan androidx.media3.session.MediaSession

Di platform MediaSessionCompat lama, MediaSessionConnector telah bertanggung jawab untuk menyinkronkan status pemutar dengan status sesi dan menerima perintah dari {i>controller<i} yang membutuhkan delegasi ke metode pemutar. Dengan AndroidX Media3, hal ini dilakukan oleh MediaSession secara langsung tanpa memerlukan konektor.

1. Hapus semua referensi dan penggunaan MediaSessionConnector: Jika Anda menggunakan skrip otomatis untuk memigrasikan class dan paket ExoPlayer, kemudian kemungkinan besar telah meninggalkan kode Anda dalam keadaan tidak dapat dikompilasi mengenai MediaSessionConnector yang tidak dapat diselesaikan. Android Studio akan menunjukkan kode yang rusak saat Anda mencoba membangun atau memulai aplikasi.

2. Dalam file build.gradle tempat Anda mempertahankan dependensi, tambahkan sebuah dependensi implementasi ke modul sesi AndroidX Media3 dan menghapusnya dependensi lama:

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

3. Ganti MediaSessionCompat dengan androidx.media3.session.MediaSession.

4. Di situs kode tempat Anda membuat MediaSessionCompat lama, gunakan androidx.media3.session.MediaSession.Builder untuk membuat MediaSession. Teruskan pemain untuk membuat pembuat sesi.

   Catatan: Jika aplikasi menggunakan pemutar yang berbeda dengan ExoPlayer, Anda memerlukan implementasi Player kustom yang dapat Anda teruskan ke MediaSession yang menggabungkan pemutar Anda. Kami akan memberikan panduan selengkapnya terkait implementasi Player minimal yang berfungsi bersama dengan media implementasi sesi.

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

   Catatan: Anda dapat menangkap panggilan metode apa pun ke Player dengan menggabungkannya dalam ForwardingPlayer(player).

5. Terapkan MySessionCallback seperti yang diwajibkan oleh aplikasi Anda. Tindakan ini bersifat opsional. Jika izinkan pengontrol untuk menambahkan item media ke pemutar, terapkan MediaSession.Callback.onAddMediaItems() Infrastruktur ini melayani berbagai metode API lama yang menambahkan item media ke pemutar untuk diputar kompatibel dengan sistem lama. Pembaruan ini mencakup Metode MediaController.set/addMediaItems() pada pengontrol Media3, seperti serta TransportControls.prepareFrom*/playFrom* dari API lama. Contoh implementasi onAddMediaItems dapat dapat ditemukan di PlaybackService aplikasi demo sesi.

6. Rilis sesi media di situs kode tempat Anda menghancurkan sesi sebelum migrasi:

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

   Catatan: Anda harus merilis sesi media sebelum membuat yang baru dengan ID yang sama. Media3 menampilkan pengecualian jika aplikasi membocorkan sesi instance Anda.

Fungsi MediaSessionConnector di Media3

Tabel berikut menunjukkan Media3 API yang menangani fungsionalitas sebelumnya diterapkan di MediaSessionConnector.

MediaSessionConnector	AndroidX Media3
CustomActionProvider	MediaSession.Callback.onCustomCommand()/ MediaSession.setCustomLayout()
PlaybackPreparer	MediaSession.Callback.onAddMediaItems() (prepare() dipanggil secara internal)
QueueNavigator	ForwardingPlayer
QueueEditor	MediaSession.Callback.onAddMediaItems()
RatingCallback	MediaSession.Callback.onSetRating()
PlayerNotificationManager	DefaultMediaNotificationProvider/ MediaNotification.Provider

Migrasikan MediaBrowserService ke MediaLibraryService

AndroidX Media3 memperkenalkan MediaLibraryService yang menggantikan MediaBrowserServiceCompat. JavaDoc dari MediaLibraryService dan super-nya class MediaSessionService memberikan pengantar yang baik tentang API dan layanan model pemrograman asinkron.

MediaLibraryService kompatibel dengan versi sebelumnya MediaBrowserService. Aplikasi klien yang menggunakan MediaBrowserCompat atau MediaControllerCompat, terus berfungsi tanpa perubahan kode saat menghubungkan ke MediaLibraryService. Untuk klien, bersifat transparan apakah aplikasi Anda menggunakan MediaLibraryService atau MediaBrowserServiceCompat lama.

Gambar 1: Ringkasan komponen aplikasi media

1. Agar kompatibilitas mundur dapat berfungsi, Anda harus mendaftarkan kedua layanan tersebut antarmuka dengan layanan Anda di AndroidManifest.xml. Dengan cara ini, menemukan layanan Anda melalui antarmuka layanan yang diperlukan:

   <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. Dalam file build.gradle tempat Anda mempertahankan dependensi, tambahkan sebuah dependensi implementasi ke modul sesi AndroidX Media3 dan hapus dependensi lama:

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

3. Ubah layanan Anda agar mewarisi dari MediaLibraryService, bukan MediaBrowserService Seperti yang sudah disebutkan sebelumnya, MediaLibraryService kompatibel dengan versi lama MediaBrowserService. Dengan demikian, API yang lebih luas di mana layanan tersebut yang ditawarkan kepada klien masih sama. Jadi kemungkinannya sebuah aplikasi dapat sebagian besar logika yang diperlukan untuk mengimplementasikan MediaBrowserService dan menyesuaikannya untuk MediaLibraryService baru.

   Perbedaan utamanya dibandingkan dengan MediaBrowserServiceCompat adalah sebagai berikut:

   • Mengimplementasikan metode siklus proses layanan: Metode yang perlu harus diganti pada layanan itu sendiri adalah onCreate/onDestroy, dengan aplikasi mengalokasikan/merilis sesi library, pemutar, dan Google Cloud Platform. Selain metode siklus hidup layanan standar, sebuah aplikasi perlu mengganti onGetSession(MediaSession.ControllerInfo) untuk menampilkan MediaLibrarySession yang dibuat pada onCreate.

   • Mengimplementasikan MediaLibraryService.MediaLibrarySessionCallback: Membuat sebuah sesi memerlukan MediaLibraryService.MediaLibrarySessionCallback yang menerapkan metode API domain aktual. Jadi, alih-alih mengganti metode API layanan lama, Anda akan mengganti metode Sebagai gantinya, MediaLibrarySession.Callback.

     Callback ini kemudian digunakan untuk membuat MediaLibrarySession:

     mediaLibrarySession =
           MediaLibrarySession.Builder(this, player, MySessionCallback())
              .build()
     

     Menemukan API lengkap MediaLibrarySessionCallback di API dokumentasi layanan.

   • Menerapkan MediaSession.Callback.onAddMediaItems(): Callback onAddMediaItems(MediaSession, ControllerInfo, List<MediaItem>) ditayangkan berbagai metode API saat ini dan lama yang menambahkan item media ke pemutar untuk pemutaran dengan cara yang kompatibel dengan versi sebelumnya. Pembaruan ini mencakup Metode MediaController.set/addMediaItems() pada pengontrol Media3, serta TransportControls.prepareFrom*/playFrom* dari API lama. Contoh implementasi callback dapat dapat ditemukan di PlaybackService aplikasi demo sesi.

   • AndroidX Media3 menggunakan androidx.media3.common.MediaItem sebagai gantinya MediaBrowserCompat.MediaItem dan MediaMetadataCompat. Suku Cadang kode Anda yang terkait dengan class lama harus diubah sebagaimana mestinya atau memetakan ke MediaItem Media3.

   • Model pemrograman asinkron umum diubah menjadi Futures di kontras dengan pendekatan Result yang dapat dilepas dari MediaBrowserServiceCompat. Implementasi layanan Anda dapat menampilkan ListenableFuture asinkron, bukan melepaskan hasil atau menampilkan Future langsung untuk menampilkan nilai secara langsung.

Menghapus PlayerNotificationManager

MediaLibraryService mendukung notifikasi media secara otomatis dan PlayerNotificationManager dapat dihapus saat menggunakan MediaLibraryService atau MediaSessionService.

Catatan: Aplikasi yang menargetkan API Level 28+ masih harus meminta izin FOREGROUND_SERVICE Anda.

Aplikasi dapat menyesuaikan notifikasi dengan menyetel parameter kustom MediaNotification.Provider di onCreate() yang menggantikan DefaultMediaNotificationProvider. MediaLibraryService kemudian akan menangani memulai layanan di latar depan sesuai kebutuhan.

Dengan mengganti MediaLibraryService.updateNotification(), aplikasi dapat mengambil kepemilikan penuh atas postingan notifikasi dan memulai/menghentikan layanan dalam latar depan sesuai kebutuhan.

Memigrasikan kode klien menggunakan MediaBrowser

Dengan AndroidX Media3, MediaBrowser mengimplementasikan MediaController/Player dan dapat digunakan untuk mengontrol pemutaran media selain menjelajahi library. Jika Anda harus membuat MediaBrowserCompat dan MediaControllerCompat di versi lama, Anda dapat melakukan hal yang sama hanya dengan menggunakan MediaBrowser di Media3.

Catatan: Pengguna Kotlin dapat bergantung pada kotlin-coroutines-guava atau androidx.concurrent di file build.gradle untuk menambahkan metode ekstensi await ke ListenableFuture. Hal ini membuat MediaBrowser API lebih cocok secara alami ke dalam metode suspend.

MediaBrowser dapat dibuat dan menunggu koneksi ke layanan yang sedang dibuat:

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)
}

Lihat Mengontrol pemutaran dalam sesi media mempelajari cara membuat MediaController untuk mengontrol pemutaran di latar belakang.

Langkah selanjutnya dan pembersihan

Error API tidak stabil

Setelah bermigrasi ke Media3, Anda mungkin melihat error lint tentang penggunaan API yang tidak stabil. Semua API ini aman digunakan dan error lint adalah produk sampingan dari jaminan kompatibilitas biner. Jika Anda tidak memerlukan sistem biner ketat kompatibilitas mundur, error ini dapat disembunyikan dengan aman menggunakan @OptIn anotasi.

Latar belakang

Baik ExoPlayer v1 maupun v2 tidak memberikan jaminan ketat tentang kompatibilitas biner library di antara versi berikutnya. Platform ExoPlayer API sangat didesain agar memungkinkan aplikasi untuk menyesuaikan hampir setiap aspek pemutaran. Versi ExoPlayer berikutnya terkadang akan memperkenalkan simbol penggantian nama atau perubahan yang dapat menyebabkan gangguan lainnya (misalnya, metode baru yang diperlukan pada antarmuka). Di beberapa kebanyakan kasus, kerusakan ini dimitigasi dengan memperkenalkan simbol baru di samping menghentikan penggunaan simbol lama pada beberapa versi, untuk memungkinkan developer waktu untuk memigrasikan penggunaannya, tapi ini tidak selalu memungkinkan.

Perubahan yang dapat menyebabkan gangguan ini mengakibatkan dua masalah bagi pengguna ExoPlayer v1 dan library v2:

1. Upgrade dari versi ExoPlayer dapat menyebabkan kode berhenti dikompilasi.
2. Aplikasi yang bergantung pada ExoPlayer baik secara langsung maupun melalui perantara {i>library<i} harus memastikan bahwa kedua dependensi adalah versi yang sama, jika tidak, inkompatibilitas biner dapat mengakibatkan error runtime.

Peningkatan di Media3

Media3 menjamin kompatibilitas biner untuk subset platform API. Tujuan bagian yang tidak menjamin kompatibilitas biner ditandai dengan @UnstableApi Untuk memperjelas perbedaan ini, penggunaan data dari ketidakstabilan Simbol API menghasilkan error lint kecuali jika dianotasi dengan @OptIn.

Setelah bermigrasi dari ExoPlayer v2 ke Media3, Anda mungkin melihat banyak API yang tidak stabil error lint. Ini mungkin membuat Media3 tampak 'kurang stabil' daripada ExoPlayer v2. Bukan itu masalahnya. 'tidak stabil' sebagian besar dari Media3 API memiliki tingkat stabilitas sebagaimana seluruh platform API ExoPlayer v2, dan jaminan platform Media3 API yang stabil tidak tersedia di ExoPlayer v2 di semua. Perbedaannya hanyalah bahwa error lint kini memperingatkan Anda tentang tingkat stabilitas.

Menangani error lint API yang tidak stabil

Lihat bagian pemecahan masalah tentang error lint ini untuk detail tentang cara anotasikan penggunaan Java dan Kotlin API yang tidak stabil dengan @OptIn.

API yang tidak digunakan lagi

Anda mungkin melihat bahwa panggilan ke API yang tidak digunakan lagi dicoret di Android di Studio. Sebaiknya ganti panggilan tersebut dengan alternatif yang sesuai. Arahkan kursor ke simbol untuk melihat JavaDoc yang memberi tahu API mana yang akan digunakan.

Gambar 3: Tooltip JavaDoc di Android Studio menyarankan alternatif untuk simbol yang tidak digunakan lagi.

Contoh kode dan aplikasi demo

• Aplikasi demo sesi AndroidX Media3 (seluler dan WearOS)
  • Tindakan kustom
  • Notifikasi UI sistem, MediaButton/BT
  • Kontrol pemutaran Asisten Google
• UAMP: Android Media Player (media cabang3) (seluler, AutomotiveOS)
  • Notifikasi UI sistem, MediaButton/BT, Melanjutkan pemutaran
  • Kontrol pemutaran Asisten Google/WearOS
  • AutomotiveOS: login dan perintah kustom