Các ứng dụng hiện đang sử dụng thư viện com.google.android.exoplayer2
độc lập và androidx.media
nên chuyển sang androidx.media3
. Sử dụng tập lệnh di chuyển để di chuyển các tệp bản dựng gradle, tệp nguồn Java và Kotlin cũng như tệp bố cục XML từ ExoPlayer 2.19.1
sang AndroidX Media3 1.1.1
.
Tổng quan
Trước khi di chuyển, hãy xem lại các phần sau để tìm hiểu thêm về lợi ích của các API mới, API cần di chuyển và các điều kiện tiên quyết mà dự án của ứng dụng phải đáp ứng.
Lý do nên di chuyển sang Jetpack Media3
- Đây là nơi lưu trữ mới của ExoPlayer, trong khi
com.google.android.exoplayer2
đã ngừng hoạt động. - Truy cập Player API trên các thành phần/quy trình bằng
MediaBrowser
/MediaController
. - Sử dụng các chức năng mở rộng của API
MediaSession
vàMediaController
. - Quảng cáo các tính năng phát bằng chế độ kiểm soát quyền truy cập chi tiết.
- Đơn giản hoá ứng dụng bằng cách xoá
MediaSessionConnector
vàPlayerNotificationManager
. - Tương thích ngược với các API ứng dụng tương thích với nội dung đa phương tiện (
MediaBrowserCompat
/MediaControllerCompat
/MediaMetadataCompat
)
API đa phương tiện để di chuyển sang AndroidX Media3
- ExoPlayer và các tiện ích của nó
Bộ này bao gồm tất cả các mô-đun của dự án ExoPlayer cũ, ngoại trừ mô-đun mediasession đã ngừng hoạt động. Bạn có thể di chuyển các ứng dụng hoặc mô-đun phụ thuộc vào các gói trongcom.google.android.exoplayer2
bằng tập lệnh di chuyển. - MediaSessionConnector (tuỳ thuộc vào gói
androidx.media.*
củaandroidx.media:media:1.4.3+
)
XoáMediaSessionConnector
và sử dụngandroidx.media3.session.MediaSession
. - MediaBrowserServiceCompat (tuỳ thuộc vào gói
androidx.media.*
củaandroidx.media:media:1.4.3+
)
Di chuyển các lớp con củaandroidx.media.MediaBrowserServiceCompat
sangandroidx.media3.session.MediaLibraryService
và mã sử dụngMediaBrowserCompat.MediaItem
sangandroidx.media3.common.MediaItem
. - MediaBrowserCompat (tuỳ thuộc vào gói
android.support.v4.media.*
củaandroidx.media:media:1.4.3+
)
Di chuyển mã ứng dụng bằng cách sử dụngMediaBrowserCompat
hoặcMediaControllerCompat
để sử dụngandroidx.media3.session.MediaBrowser
vớiandroidx.media3.common.MediaItem
.
Điều kiện tiên quyết
Đảm bảo dự án của bạn nằm trong quyền kiểm soát nguồn
Đảm bảo bạn có thể dễ dàng huỷ bỏ các thay đổi do các công cụ di chuyển theo tập lệnh áp dụng. Nếu bạn chưa đưa dự án của mình vào hệ thống quản lý nguồn, thì đây là thời điểm thích hợp để bắt đầu. Nếu vì lý do nào đó mà bạn không muốn làm như vậy, hãy tạo bản sao dự phòng của dự án trước khi bắt đầu di chuyển.
Cập nhật ứng dụng
Bạn nên cập nhật dự án của mình để sử dụng phiên bản mới nhất của thư viện ExoPlayer và xoá mọi lệnh gọi đến các phương thức không dùng nữa. Nếu dự định sử dụng tập lệnh để di chuyển, bạn cần so khớp phiên bản mà bạn đang cập nhật với phiên bản do tập lệnh xử lý.
Tăng compileSdkVersion của ứng dụng lên ít nhất là 32.
Nâng cấp Gradle và trình bổ trợ Gradle cho Android Studio lên một phiên bản mới đây hoạt động với các phần phụ thuộc đã cập nhật ở trên. Ví dụ:
- Phiên bản trình bổ trợ Android cho Gradle: 7.1.0
- Phiên bản Gradle: 7.4
Thay thế tất cả câu lệnh nhập ký tự đại diện đang sử dụng dấu hoa thị (*) và sử dụng câu lệnh nhập đủ điều kiện: Xoá câu lệnh nhập ký tự đại diện và sử dụng Android Studio để nhập câu lệnh đủ điều kiện (F2 – Alt/Enter, F2 – Alt/Enter, …).
Di chuyển từ
com.google.android.exoplayer2.PlayerView
sangcom.google.android.exoplayer2.StyledPlayerView
. Điều này là cần thiết vì không có giá trị tương đương vớicom.google.android.exoplayer2.PlayerView
trong AndroidX Media3.
Di chuyển ExoPlayer có hỗ trợ tập lệnh
Tập lệnh này hỗ trợ việc di chuyển từ com.google.android.exoplayer2
sang cấu trúc gói và mô-đun mới trong androidx.media3
. Tập lệnh này áp dụng một số quy trình kiểm tra xác thực trên dự án của bạn và in cảnh báo nếu không xác thực được.
Nếu không, công cụ này sẽ áp dụng tính năng liên kết các lớp và gói đã đổi tên trong tài nguyên của dự án Android cho Gradle được viết bằng Java hoặc 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
Sử dụng tập lệnh di chuyển
Tải tập lệnh di chuyển xuống từ thẻ của dự án ExoPlayer trên GitHub tương ứng với phiên bản mà bạn đã cập nhật ứng dụng:
curl -o media3-migration.sh \ "https://raw.githubusercontent.com/google/ExoPlayer/r2.19.1/media3-migration.sh"
Đặt tập lệnh ở chế độ có thể thực thi:
chmod 744 media3-migration.sh
Chạy tập lệnh bằng
--help
để tìm hiểu về các tuỳ chọn.Chạy tập lệnh bằng
-l
để liệt kê tập hợp các tệp được chọn để di chuyển (sử dụng-f
để buộc liệt kê mà không có cảnh báo):./media3-migration.sh -l -f /path/to/gradle/project/root
Chạy tập lệnh bằng
-m
để liên kết các gói, lớp và mô-đun với Media3. Việc chạy tập lệnh bằng tuỳ chọn-m
sẽ áp dụng các thay đổi cho các tệp đã chọn.- Dừng lại khi gặp lỗi xác thực mà không thực hiện thay đổi
./media3-migration.sh -m /path/to/gradle/project/root
- Thực thi bắt buộc
Nếu tập lệnh phát hiện thấy lỗi vi phạm các điều kiện tiên quyết, bạn có thể buộc di chuyển bằng cờ
-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
Hoàn tất các bước thủ công sau đây sau khi chạy tập lệnh bằng tuỳ chọn -m
:
- Kiểm tra cách tập lệnh thay đổi mã của bạn: Sử dụng công cụ so sánh và khắc phục các vấn đề tiềm ẩn (hãy cân nhắc việc gửi lỗi nếu bạn cho rằng tập lệnh có một vấn đề chung đã được đưa ra mà không truyền tuỳ chọn
-f
). - Tạo dự án: Sử dụng
./gradlew clean build
hoặc trong Android Studio, chọn File > Sync Project with Gradle Files (Tệp > Đồng bộ hoá dự án với tệp Gradle), sau đó chọn Build > Clean project (Tạo > Dọn dự án), rồi chọn Build > Rebuild project (Tạo > Tạo lại dự án) (theo dõi bản dựng trong thẻ "Build – Build Output" (Tạo – Đầu ra bản dựng) của Android Studio.
Các bước tiếp theo nên thực hiện:
- Giải quyết lỗi chọn sử dụng đối với lỗi liên quan đến việc sử dụng các API không ổn định.
- Thay thế các lệnh gọi API không dùng nữa: Sử dụng API thay thế được đề xuất. Giữ con trỏ trên cảnh báo trong Android Studio và tham khảo JavaDoc của biểu tượng không dùng nữa để tìm hiểu xem bạn nên sử dụng gì thay vì một lệnh gọi nhất định.
- Sắp xếp các câu lệnh nhập: Mở dự án trong Android Studio, sau đó nhấp chuột phải vào nút thư mục gói trong trình xem dự án rồi chọn Optimize imports (Tối ưu hoá nội dung nhập) trên các gói chứa tệp nguồn đã thay đổi.
Thay thế MediaSessionConnector
bằng androidx.media3.session.MediaSession
.
Trong thế giới MediaSessionCompat
cũ, MediaSessionConnector
chịu trách nhiệm đồng bộ hoá trạng thái của trình phát với trạng thái của phiên và nhận lệnh từ các tay điều khiển cần uỷ quyền cho các phương thức trình phát thích hợp. Với AndroidX Media3, việc này được thực hiện trực tiếp bởi MediaSession
mà không cần trình kết nối.
Xoá tất cả tệp tham chiếu và cách sử dụng MediaSessionConnector: Nếu bạn đã sử dụng tập lệnh tự động để di chuyển các lớp và gói ExoPlayer, thì tập lệnh đó có thể đã khiến mã của bạn ở trạng thái không biên dịch được liên quan đến
MediaSessionConnector
không thể phân giải. Android Studio sẽ cho bạn thấy mã bị lỗi khi bạn cố gắng tạo hoặc khởi động ứng dụng.Trong tệp
build.gradle
nơi bạn duy trì các phần phụ thuộc, hãy thêm phần phụ thuộc triển khai vào mô-đun phiên AndroidX Media3 và xoá phần phụ thuộc cũ:implementation "androidx.media3:media3-session:1.5.0"
Thay thế
MediaSessionCompat
bằngandroidx.media3.session.MediaSession
.Tại vị trí mã mà bạn đã tạo
MediaSessionCompat
cũ, hãy sử dụngandroidx.media3.session.MediaSession.Builder
để tạoMediaSession
. Truyền trình phát để tạo trình tạo phiên.val player = ExoPlayer.Builder(context).build() mediaSession = MediaSession.Builder(context, player) .setSessionCallback(MySessionCallback()) .build()
Triển khai
MySessionCallback
theo yêu cầu của ứng dụng. Việc này là không bắt buộc. Nếu bạn muốn cho phép tay điều khiển thêm các mục nội dung nghe nhìn vào trình phát, hãy triển khaiMediaSession.Callback.onAddMediaItems()
. Lớp này phân phát nhiều phương thức API hiện tại và cũ để thêm các mục nội dung nghe nhìn vào trình phát nhằm phát theo cách tương thích ngược. Bao gồm các phương thứcMediaController.set/addMediaItems()
của bộ điều khiển Media3, cũng như các phương thứcTransportControls.prepareFrom*/playFrom*
của API cũ. Bạn có thể tìm thấy một ví dụ về cách triển khaionAddMediaItems
trongPlaybackService
của ứng dụng minh hoạ phiên.Giải phóng phiên phát nội dung nghe nhìn tại vị trí mã mà bạn đã huỷ phiên trước khi di chuyển:
mediaSession?.run { player.release() release() mediaSession = null }
Chức năng MediaSessionConnector
trong Media3
Bảng sau đây cho thấy các API Media3 xử lý chức năng từng được triển khai trong MediaSessionConnector
.
MediaSessionConnector | AndroidX Media3 |
---|---|
CustomActionProvider |
MediaSession.Callback.onCustomCommand()/
MediaSession.setCustomLayout() |
PlaybackPreparer |
MediaSession.Callback.onAddMediaItems()
(prepare() được gọi nội bộ)
|
QueueNavigator |
ForwardingSimpleBasePlayer |
QueueEditor |
MediaSession.Callback.onAddMediaItems() |
RatingCallback |
MediaSession.Callback.onSetRating() |
PlayerNotificationManager |
DefaultMediaNotificationProvider/
MediaNotification.Provider |
Di chuyển MediaBrowserService
sang MediaLibraryService
AndroidX Media3 giới thiệu MediaLibraryService
thay thế cho MediaBrowserServiceCompat
. JavaDoc của MediaLibraryService
và lớp cấp trên MediaSessionService
cung cấp thông tin giới thiệu hữu ích về API và mô hình lập trình không đồng bộ của dịch vụ.
MediaLibraryService
có khả năng tương thích ngược với MediaBrowserService
. Ứng dụng khách đang sử dụng MediaBrowserCompat
hoặc MediaControllerCompat
sẽ tiếp tục hoạt động mà không cần thay đổi mã khi kết nối với MediaLibraryService
. Đối với ứng dụng khách, ứng dụng của bạn đang sử dụng MediaLibraryService
hay MediaBrowserServiceCompat
cũ đều được thể hiện rõ ràng.
Để khả năng tương thích ngược hoạt động, bạn cần đăng ký cả hai giao diện dịch vụ với dịch vụ của mình trong
AndroidManifest.xml
. Bằng cách này, ứng dụng sẽ tìm thấy dịch vụ của bạn theo giao diện dịch vụ bắt buộc:<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>
Trong tệp
build.gradle
nơi bạn duy trì các phần phụ thuộc, hãy thêm phần phụ thuộc triển khai vào mô-đun phiên AndroidX Media3 và xoá phần phụ thuộc cũ:implementation "androidx.media3:media3-session:1.5.0"
Thay đổi dịch vụ của bạn để kế thừa từ
MediaLibraryService
thay vìMediaBrowserService
. Như đã nói trước đó,MediaLibraryService
tương thích vớiMediaBrowserService
cũ. Do đó, API rộng hơn mà dịch vụ đang cung cấp cho ứng dụng vẫn giữ nguyên. Vì vậy, có thể một ứng dụng có thể giữ lại hầu hết logic cần thiết để triển khaiMediaBrowserService
và điều chỉnh logic đó choMediaLibraryService
mới.Sau đây là những điểm khác biệt chính so với
MediaBrowserServiceCompat
cũ:Triển khai các phương thức vòng đời của dịch vụ: Các phương thức cần được ghi đè trên chính dịch vụ là
onCreate/onDestroy
, trong đó ứng dụng phân bổ/giải phóng phiên thư viện, trình phát và các tài nguyên khác. Ngoài các phương thức vòng đời dịch vụ tiêu chuẩn, ứng dụng cần ghi đèonGetSession(MediaSession.ControllerInfo)
để trả vềMediaLibrarySession
được tạo trongonCreate
.Triển khai MediaLibraryService.MediaLibrarySessionCallback: Việc tạo một phiên yêu cầu một
MediaLibraryService.MediaLibrarySessionCallback
triển khai các phương thức API miền thực tế. Vì vậy, thay vì ghi đè các phương thức API của dịch vụ cũ, bạn sẽ ghi đè các phương thức củaMediaLibrarySession.Callback
.Sau đó, lệnh gọi lại được dùng để tạo
MediaLibrarySession
:mediaLibrarySession = MediaLibrarySession.Builder(this, player, MySessionCallback()) .build()
Tìm API đầy đủ của MediaLibrarySessionCallback trong tài liệu API.
Triển khai
MediaSession.Callback.onAddMediaItems()
: Lệnh gọi lạionAddMediaItems(MediaSession, ControllerInfo, List<MediaItem>)
phân phát nhiều phương thức API hiện tại và cũ để thêm các mục nội dung đa phương tiện vào trình phát nhằm phát theo cách tương thích ngược. API này bao gồm các phương thứcMediaController.set/addMediaItems()
của bộ điều khiển Media3, cũng như các phương thứcTransportControls.prepareFrom*/playFrom*
của API cũ. Bạn có thể tìm thấy cách triển khai mẫu của lệnh gọi lại trongPlaybackService
của ứng dụng minh hoạ phiên.AndroidX Media3 đang sử dụng
androidx.media3.common.MediaItem
thay vì MediaBrowserCompat.MediaItem và MediaMetadataCompat. Bạn cần thay đổi các phần mã liên kết với các lớp cũ cho phù hợp hoặc ánh xạ đếnMediaItem
Media3.Mô hình lập trình không đồng bộ chung đã thay đổi thành
Futures
, trái ngược với phương phápResult
có thể tháo rời củaMediaBrowserServiceCompat
. Quá trình triển khai dịch vụ của bạn có thể trả về mộtListenableFuture
không đồng bộ thay vì tách một kết quả hoặc trả về một Future ngay lập tức để trực tiếp trả về một giá trị.
Xoá PlayerNotificationManager
MediaLibraryService
tự động hỗ trợ thông báo nội dung nghe nhìn và bạn có thể xoá PlayerNotificationManager
khi sử dụng MediaLibraryService
hoặc MediaSessionService
.
Ứng dụng có thể tuỳ chỉnh thông báo bằng cách đặt một MediaNotification.Provider
tuỳ chỉnh trong onCreate()
thay thế cho DefaultMediaNotificationProvider
. Sau đó, MediaLibraryService
sẽ xử lý việc bắt đầu dịch vụ trên nền trước nếu cần.
Bằng cách ghi đè MediaLibraryService.updateNotification()
, ứng dụng có thể toàn quyền đăng thông báo và bắt đầu/dừng dịch vụ ở nền trước khi cần.
Di chuyển mã ứng dụng bằng MediaBrowser
Với AndroidX Media3, MediaBrowser
triển khai các giao diện MediaController/Player
và có thể dùng để điều khiển việc phát nội dung nghe nhìn ngoài việc duyệt qua thư viện nội dung nghe nhìn. Nếu phải tạo MediaBrowserCompat
và MediaControllerCompat
trong thế giới cũ, bạn có thể thực hiện tương tự bằng cách chỉ sử dụng MediaBrowser
trong Media3.
Bạn có thể tạo MediaBrowser
và chờ kết nối với dịch vụ đang được thiết lập:
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)
}
Hãy xem phần Kiểm soát chế độ phát trong phiên phát nội dung nghe nhìn để tìm hiểu cách tạo MediaController
nhằm kiểm soát chế độ phát ở chế độ nền.
Các bước tiếp theo và dọn dẹp
Lỗi API không ổn định
Sau khi di chuyển sang Media3, bạn có thể thấy lỗi tìm lỗi mã nguồn về việc sử dụng API không ổn định.
Bạn có thể sử dụng các API này một cách an toàn và lỗi tìm lỗi mã nguồn là sản phẩm phụ của việc đảm bảo khả năng tương thích nhị phân mới của chúng tôi. Nếu bạn không yêu cầu khả năng tương thích nhị phân nghiêm ngặt, bạn có thể chặn các lỗi này một cách an toàn bằng chú thích @OptIn
.
Thông tin khái quát
Cả ExoPlayer phiên bản 1 và 2 đều không đưa ra cam kết nghiêm ngặt về khả năng tương thích nhị phân của thư viện giữa các phiên bản tiếp theo. Theo thiết kế, giao diện API ExoPlayer rất lớn để cho phép các ứng dụng tuỳ chỉnh gần như mọi khía cạnh của quá trình phát. Các phiên bản tiếp theo của ExoPlayer đôi khi sẽ giới thiệu việc đổi tên biểu tượng hoặc các thay đổi có thể gây lỗi khác (ví dụ: các phương thức bắt buộc mới trên giao diện). Trong hầu hết các trường hợp, các lỗi này đã được giảm thiểu bằng cách giới thiệu biểu tượng mới cùng với việc ngừng sử dụng biểu tượng cũ trong một vài phiên bản để cho phép nhà phát triển có thời gian di chuyển cách sử dụng, nhưng không phải lúc nào cũng có thể làm được điều này.
Những thay đổi có thể gây lỗi này đã gây ra hai vấn đề cho người dùng thư viện ExoPlayer v1 và v2:
- Việc nâng cấp từ phiên bản này lên phiên bản ExoPlayer có thể khiến mã ngừng biên dịch.
- Một ứng dụng phụ thuộc vào ExoPlayer cả trực tiếp và thông qua thư viện trung gian phải đảm bảo cả hai phần phụ thuộc đều có cùng phiên bản, nếu không, sự không tương thích nhị phân có thể dẫn đến sự cố trong thời gian chạy.
Các điểm cải tiến trong Media3
Media3 đảm bảo khả năng tương thích nhị phân cho một tập hợp con của nền tảng API. Các phần không đảm bảo khả năng tương thích của tệp nhị phân được đánh dấu bằng @UnstableApi
. Để làm rõ sự khác biệt này, việc sử dụng các biểu tượng API không ổn định sẽ tạo ra lỗi tìm lỗi mã nguồn, trừ phi các biểu tượng đó được chú thích bằng @OptIn
.
Sau khi di chuyển từ ExoPlayer v2 sang Media3, bạn có thể thấy nhiều lỗi tìm lỗi mã nguồn API không ổn định. Điều này có thể khiến Media3 có vẻ "kém ổn định" hơn ExoPlayer v2. Không phải vậy. Các phần "không ổn định" của API Media3 có cùng mức độ ổn định với toàn bộ giao diện API ExoPlayer v2 và không có gì đảm bảo về giao diện API Media3 ổn định trong ExoPlayer v2. Điểm khác biệt đơn giản là lỗi tìm lỗi mã nguồn hiện sẽ cảnh báo cho bạn về các mức độ ổn định khác nhau.
Xử lý lỗi tìm lỗi mã nguồn API không ổn định
Hãy xem phần khắc phục sự cố về các lỗi tìm lỗi mã nguồn này để biết thông tin chi tiết về cách chú thích cách sử dụng Java và Kotlin của các API không ổn định bằng @OptIn
.
API không dùng nữa
Bạn có thể nhận thấy các lệnh gọi đến API không dùng nữa bị gạch ngang trong Android Studio. Bạn nên thay thế các lệnh gọi đó bằng phương án thay thế thích hợp. Di chuột qua biểu tượng để xem JavaDoc cho biết bạn nên sử dụng API nào.
Mã mẫu và ứng dụng minh hoạ
- Ứng dụng minh hoạ phiên AndroidX Media3 (thiết bị di động và WearOS)
- Thao tác tuỳ chỉnh
- Thông báo trên giao diện người dùng hệ thống, MediaButton/BT
- Điều khiển chế độ phát bằng Trợ lý Google
- UAMP: Trình phát nội dung đa phương tiện Android (nhánh media3) (thiết bị di động, AutomotiveOS)
- Thông báo giao diện người dùng hệ thống, MediaButton/BT, Tiếp tục phát
- Điều khiển chế độ phát bằng Trợ lý Google/WearOS
- AutomotiveOS: lệnh tuỳ chỉnh và đăng nhập