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 APIMediaController
. - Iklankan kemampuan pemutaran dengan kontrol akses yang mendetail.
- Sederhanakan aplikasi Anda dengan menghapus
MediaSessionConnector
danPlayerNotificationManager
. - 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 dicom.google.android.exoplayer2
dapat dimigrasikan dengan skrip migrasi. - MediaSessionConnector (bergantung pada
androidx.media.*
paket dariandroidx.media:media:1.4.3+
)
HapusMediaSessionConnector
dan gunakanandroidx.media3.session.MediaSession
sebagai gantinya. - MediaBrowserServiceCompat (bergantung pada
androidx.media.*
paket dariandroidx.media:media:1.4.3+
)
Migrasikan subclassandroidx.media.MediaBrowserServiceCompat
keandroidx.media3.session.MediaLibraryService
dan kode menggunakanMediaBrowserCompat.MediaItem
hinggaandroidx.media3.common.MediaItem
. - MediaBrowserCompat (bergantung pada
android.support.v4.media.*
paket dariandroidx.media:media:1.4.3+
)
Memigrasikan kode klien menggunakanMediaBrowserCompat
atauMediaControllerCompat
untuk menggunakanandroidx.media3.session.MediaBrowser
denganandroidx.media3.common.MediaItem
.
Prasyarat
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.
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
kecom.google.android.exoplayer2.StyledPlayerView
. Ini diperlukan karena tidak ada yang setara dengancom.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
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"
Jadikan skrip sebagai dapat dijalankan:
chmod 744 media3-migration.sh
Jalankan skrip dengan
--help
untuk mempelajari opsi.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
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
# 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
:
- 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
). - 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.
Langkah-langkah tindak lanjut yang direkomendasikan:
- Atasi keikutsertaan atas error terkait penggunaan API yang tidak stabil.
- 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.
- 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.
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.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"
Ganti
MediaSessionCompat
denganandroidx.media3.session.MediaSession
.Di situs kode tempat Anda membuat
MediaSessionCompat
lama, gunakanandroidx.media3.session.MediaSession.Builder
untuk membuatMediaSession
. Teruskan pemain untuk membuat pembuat sesi.val player = ExoPlayer.Builder(context).build() mediaSession = MediaSession.Builder(context, player) .setSessionCallback(MySessionCallback()) .build()
Terapkan
MySessionCallback
seperti yang diwajibkan oleh aplikasi Anda. Tindakan ini bersifat opsional. Jika izinkan pengontrol untuk menambahkan item media ke pemutar, terapkanMediaSession.Callback.onAddMediaItems()
Infrastruktur ini melayani berbagai metode API lama yang menambahkan item media ke pemutar untuk diputar kompatibel dengan sistem lama. Pembaruan ini mencakup MetodeMediaController.set/addMediaItems()
pada pengontrol Media3, seperti sertaTransportControls.prepareFrom*/playFrom*
dari API lama. Contoh implementasionAddMediaItems
dapat dapat ditemukan diPlaybackService
aplikasi demo sesi.Rilis sesi media di situs kode tempat Anda menghancurkan sesi sebelum migrasi:
mediaSession?.run { player.release() release() mediaSession = null }
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.
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>
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"
Ubah layanan Anda agar mewarisi dari
MediaLibraryService
, bukanMediaBrowserService
Seperti yang sudah disebutkan sebelumnya,MediaLibraryService
kompatibel dengan versi lamaMediaBrowserService
. 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 mengimplementasikanMediaBrowserService
dan menyesuaikannya untukMediaLibraryService
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 menggantionGetSession(MediaSession.ControllerInfo)
untuk menampilkanMediaLibrarySession
yang dibuat padaonCreate
.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()
: CallbackonAddMediaItems(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 MetodeMediaController.set/addMediaItems()
pada pengontrol Media3, sertaTransportControls.prepareFrom*/playFrom*
dari API lama. Contoh implementasi callback dapat dapat ditemukan diPlaybackService
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 keMediaItem
Media3.Model pemrograman asinkron umum diubah menjadi
Futures
di kontras dengan pendekatanResult
yang dapat dilepas dariMediaBrowserServiceCompat
. Implementasi layanan Anda dapat menampilkanListenableFuture
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
.
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.
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:
- Upgrade dari versi ExoPlayer dapat menyebabkan kode berhenti dikompilasi.
- 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.
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