Các thay đổi đối với trạng thái của Trình phát (chẳng hạn như bắt đầu phát, lưu vào vùng đệm hoặc lỗi) sẽ kích hoạt các sự kiện được gửi đến các thực thể Player.Listener đã đăng ký. Các sự kiện này được biểu thị bằng hằng số nguyên và được xác định bằng Player.Event và Player.Events.
Đăng ký Player.Listener
Sự kiện của trình phát được báo cáo cho các thực thể Player.Listener đã đăng ký. Cách đăng ký trình nghe để nhận các sự kiện như vậy:
Kotlin
// Add a listener to receive events from the player. player.addListener(listener)
Java
// Add a listener to receive events from the player. player.addListener(listener);
Nếu đang sử dụng Kotlin, bạn cũng có thể dùng các hàm mở rộng tạm ngưng do mô-đun media3-common-ktx cung cấp để theo dõi các sự kiện bằng coroutine.
Trong trường hợp đó, bạn sẽ không cần phải đăng ký hoặc huỷ đăng ký Player.Listener một cách rõ ràng.
Theo dõi các sự kiện phát bằng Player.Listener
Player.Listener có các phương thức mặc định trống, vì vậy, bạn chỉ cần triển khai các phương thức mà bạn quan tâm. Xem Javadoc để biết nội dung mô tả đầy đủ về các phương thức và thời điểm gọi các phương thức đó. Một số phương thức quan trọng nhất sẽ được mô tả chi tiết hơn ở phần sau.
Trình nghe có thể chọn triển khai các lệnh gọi lại sự kiện riêng lẻ hoặc một lệnh gọi lại onEvents chung được gọi sau khi một hoặc nhiều sự kiện xảy ra cùng nhau. Hãy xem Individual callbacks vs onEvents để biết nội dung giải thích về loại nào nên được ưu tiên cho các trường hợp sử dụng khác nhau.
Thay đổi trạng thái phát
Bạn có thể nhận được các thay đổi về trạng thái của trình phát bằng cách triển khai onPlaybackStateChanged(@State int state) trong Player.Listener đã đăng ký.
Trình phát có thể ở một trong bốn trạng thái phát sau:
Player.STATE_IDLE: Đây là trạng thái ban đầu, trạng thái khi trình phát dừng và khi không phát được. Trình phát sẽ chỉ giữ lại một số tài nguyên trong trạng thái này.Player.STATE_BUFFERING: Trình phát không thể phát ngay từ vị trí hiện tại. Điều này chủ yếu xảy ra do cần tải thêm dữ liệu.Player.STATE_READY: Trình phát có thể phát ngay lập tức từ vị trí hiện tại.Player.STATE_ENDED: Trình phát đã phát xong tất cả nội dung nghe nhìn.
Ngoài các trạng thái này, trình phát còn có cờ playWhenReady để cho biết ý định của người dùng phát. Bạn có thể nhận được các thay đổi trong cờ này bằng cách triển khai onPlayWhenReadyChanged(playWhenReady, @PlayWhenReadyChangeReason int reason).
Trình phát đang phát (tức là vị trí của trình phát đang tiến lên và nội dung nghe nhìn đang được trình bày cho người dùng) khi đáp ứng cả ba điều kiện sau:
- Trình phát đang ở trạng thái
Player.STATE_READY playWhenReadylàtrue- Tính năng phát không bị chặn vì lý do do
Player.getPlaybackSuppressionReasontrả về
Thay vì phải kiểm tra từng thuộc tính này, bạn có thể gọi Player.isPlaying. Bạn có thể nhận được các thay đổi đối với trạng thái này bằng cách triển khai onIsPlayingChanged(boolean isPlaying):
Kotlin
player.addListener( object : Player.Listener { override fun onIsPlayingChanged(isPlaying: Boolean) { if (isPlaying) { // Active playback. } else { // Not playing because playback is paused, ended, suppressed, or the player // is buffering, stopped or failed. Check player.playWhenReady, // player.playbackState, player.playbackSuppressionReason and // player.playerError for details. } } } )
Java
player.addListener( new Player.Listener() { @Override public void onIsPlayingChanged(boolean isPlaying) { if (isPlaying) { // Active playback. } else { // Not playing because playback is paused, ended, suppressed, or the player // is buffering, stopped or failed. Check player.getPlayWhenReady, // player.getPlaybackState, player.getPlaybackSuppressionReason and // player.getPlaybackError for details. } } });
Lỗi phát lại
Bạn có thể nhận được lỗi khiến quá trình phát không thành công bằng cách triển khai onPlayerError(PlaybackException error) trong Player.Listener đã đăng ký. Khi
xảy ra lỗi, phương thức này sẽ được gọi ngay trước khi trạng thái phát
chuyển sang Player.STATE_IDLE. Bạn có thể thử phát lại các lượt phát không thành công hoặc bị dừng bằng cách gọi ExoPlayer.prepare.
Xin lưu ý rằng một số cách triển khai Player truyền các thực thể của lớp con PlaybackException để cung cấp thêm thông tin về lỗi. Ví dụ: ExoPlayer truyền ExoPlaybackException, có type, rendererIndex và các trường khác dành riêng cho ExoPlayer.
Ví dụ sau đây cho thấy cách phát hiện trường hợp không phát được do sự cố mạng HTTP:
Kotlin
player.addListener( object : Player.Listener { override fun onPlayerError(error: PlaybackException) { val cause = error.cause if (cause is HttpDataSourceException) { // An HTTP error occurred. val httpError = cause // It's possible to find out more about the error both by casting and by querying // the cause. if (httpError is InvalidResponseCodeException) { // Cast to InvalidResponseCodeException and retrieve the response code, message // and headers. } else { // Try calling httpError.getCause() to retrieve the underlying cause, although // note that it may be null. } } } s.kt
Java
player.addListener( new Player.Listener() { @Override public void onPlayerError(PlaybackException error) { @Nullable Throwable cause = error.getCause(); if (cause instanceof HttpDataSourceException) { // An HTTP error occurred. HttpDataSourceException httpError = (HttpDataSourceException) cause; // It's possible to find out more about the error both by casting and by querying // the cause. if (httpError instanceof HttpDataSource.InvalidResponseCodeException) { // Cast to InvalidResponseCodeException and retrieve the response code, message // and headers. } else { // Try calling httpError.getCause() to retrieve the underlying cause, although // note that it may be null. } } } java
Chuyển đổi danh sách phát
Bất cứ khi nào trình phát chuyển sang một mục nội dung nghe nhìn mới trong danh sách phát, onMediaItemTransition(MediaItem mediaItem, @MediaItemTransitionReason int
reason) sẽ được gọi trên các đối tượng Player.Listener đã đăng ký. Lý do cho biết liệu đây có phải là quá trình chuyển đổi tự động, tua (ví dụ: sau khi gọi player.next()), lặp lại cùng một mục hay do thay đổi danh sách phát (ví dụ: nếu mục đang phát bị xoá).
Siêu dữ liệu
Siêu dữ liệu được trả về từ player.getCurrentMediaMetadata() có thể thay đổi do nhiều lý do: chuyển đổi danh sách phát, cập nhật siêu dữ liệu trong luồng hoặc cập nhật MediaItem hiện tại trong quá trình phát.
Nếu quan tâm đến các thay đổi về siêu dữ liệu, chẳng hạn như để cập nhật giao diện người dùng cho thấy tiêu đề hiện tại, bạn có thể theo dõi onMediaMetadataChanged.
Đang tìm kiếm
Việc gọi các phương thức Player.seekTo sẽ dẫn đến một loạt lệnh gọi lại đến các thực thể Player.Listener đã đăng ký:
onPositionDiscontinuityvớireason=DISCONTINUITY_REASON_SEEK. Đây là kết quả trực tiếp của việc gọiPlayer.seekTo. Lệnh gọi lại có các trườngPositionInfocho vị trí trước và sau khi tua.onPlaybackStateChangedvới mọi thay đổi trạng thái tức thì liên quan đến thao tác tua. Xin lưu ý rằng có thể không có thay đổi nào như vậy.
Nếu bạn bật chế độ kéo để tua bằng ExoPlayer.setScrubbingModeEnabled để kéo thanh tua tương tác, thì ExoPlayer sẽ chặn chế độ phát và gọi onPlaybackSuppressionReasonChanged bằng Player.PLAYBACK_SUPPRESSION_REASON_SCRUBBING. Mỗi lệnh gọi Player.seekTo vẫn kích hoạt onPositionDiscontinuity, ngay cả khi ExoPlayer bỏ qua các lượt tìm kiếm trung gian đã được thay thế và báo cáo các lượt tìm kiếm đó cho AnalyticsListener.onDroppedSeeksWhileScrubbing.
Lệnh gọi lại riêng lẻ so với onEvents
Trình nghe có thể chọn giữa việc triển khai các lệnh gọi lại riêng lẻ như onIsPlayingChanged(boolean isPlaying) và lệnh gọi lại chung onEvents(Player
player, Events events). Lệnh gọi lại chung cung cấp quyền truy cập vào đối tượng Player và chỉ định tập hợp events xảy ra cùng nhau. Lệnh gọi lại này luôn được gọi sau các lệnh gọi lại tương ứng với từng sự kiện.
Kotlin
override fun onEvents(player: Player, events: Player.Events) { if ( events.contains(Player.EVENT_PLAYBACK_STATE_CHANGED) || events.contains(Player.EVENT_PLAY_WHEN_READY_CHANGED) ) { uiModule.updateUi(player) } }
Java
@Override public void onEvents(Player player, Events events) { if (events.contains(Player.EVENT_PLAYBACK_STATE_CHANGED) || events.contains(Player.EVENT_PLAY_WHEN_READY_CHANGED)) { uiModule.updateUi(player); } }
Bạn nên ưu tiên các sự kiện riêng lẻ trong những trường hợp sau:
- Người nghe quan tâm đến lý do thay đổi. Ví dụ: lý do được đưa ra cho
onPlayWhenReadyChangedhoặconMediaItemTransition. - Trình nghe chỉ hoạt động trên các giá trị mới được cung cấp thông qua tham số gọi lại hoặc kích hoạt một số giá trị khác không phụ thuộc vào tham số gọi lại.
- Phương thức triển khai trình nghe ưu tiên chỉ báo rõ ràng, dễ đọc về yếu tố kích hoạt sự kiện trong tên phương thức.
- Trình nghe báo cáo cho một hệ thống phân tích cần biết về tất cả các sự kiện riêng lẻ và thay đổi trạng thái.
Bạn nên ưu tiên sử dụng onEvents(Player player, Events events) chung trong các trường hợp sau:
- Trình nghe muốn kích hoạt cùng một logic cho nhiều sự kiện. Ví dụ: cập nhật giao diện người dùng cho cả
onPlaybackStateChangedvàonPlayWhenReadyChanged. - Trình nghe cần truy cập vào đối tượng
Playerđể kích hoạt các sự kiện khác, ví dụ: tua sau khi chuyển đổi mục nội dung nghe nhìn. - Trình nghe dự định sử dụng nhiều giá trị trạng thái được báo cáo thông qua các lệnh gọi lại riêng biệt cùng nhau hoặc kết hợp với các phương thức getter
Player. Ví dụ: việc sử dụngPlayer.getCurrentWindowIndex()vớiTimelineđược cung cấp trongonTimelineChangedchỉ an toàn trong lệnh gọi lạionEvents. - Trình nghe quan tâm đến việc các sự kiện có xảy ra cùng nhau một cách hợp lý hay không.
Ví dụ:
onPlaybackStateChangedđếnSTATE_BUFFERINGdo chuyển đổi mục nội dung nghe nhìn.
Trong một số trường hợp, trình nghe có thể cần kết hợp các lệnh gọi lại riêng lẻ với lệnh gọi lại onEvents chung, chẳng hạn như để ghi lại lý do thay đổi mục nội dung nghe nhìn bằng onMediaItemTransition, nhưng chỉ hành động khi tất cả thay đổi về trạng thái có thể được sử dụng cùng nhau trong onEvents.
Theo dõi các sự kiện phát bằng coroutine
Ngoài ra, bạn có thể chạy coroutine Kotlin bằng Player.listenTo và chỉ định Player.Event có liên quan:
Xin lưu ý rằng bạn có thể gọi Player.listen và Player.listenTo từ bất kỳ luồng nào, trong khi lệnh gọi lại lambda luôn được gọi trên luồng liên kết với Player.getApplicationLooper. Do đó, bạn có thể truy cập một cách an toàn vào các phương thức và thuộc tính trạng thái của Player bên trong hàm lambda của lệnh gọi lại, ngay cả khi coroutine được chạy trên một luồng khác.
Thay đổi trạng thái phát
coroutineScope.launch { player.listenTo(Player.EVENT_IS_PLAYING_CHANGED) { // `Player` is a receiver scope for this trailing lambda if (isPlaying) { // Active playback. } else { // Not playing. } } }
Lỗi phát lại
coroutineScope.launch { player.listenTo(Player.EVENT_PLAYER_ERROR) { val error = playerError ?: return@listenTo val cause = error.cause if (cause is HttpDataSourceException) { // An HTTP error occurred. if (cause is InvalidResponseCodeException) { // Retrieve the response code, message and headers } else { // Try calling cause.cause to retrieve the underlying cause } } } }
Lệnh gọi lại riêng lẻ so với onEvents
Khi nghe các sự kiện của trình phát bên trong một coroutine, bạn sẽ luôn cung cấp
phần triển khai cho lệnh gọi lại onEvents, thay vì một lệnh gọi lại
riêng lẻ. Bạn có thể chọn giữa Player.listen và Player.listenTo, tuỳ thuộc vào sự kiện nào sẽ kích hoạt lệnh gọi lambda. Nhưng các hàm này
tương đương nhau:
nghe
coroutineScope.launch { player.listen { events -> // `Player` is a receiver scope for this trailing lambda if (events.contains(Player.EVENT_PLAYBACK_STATE_CHANGED)) { // Access the player state directly from the receiver updateUi(playbackState) } if (events.contains(Player.EVENT_PLAYER_ERROR)) { // Access the error directly from the player handleError(playerError) } } }
listenTo
coroutineScope.launch { player.listenTo(Player.EVENT_PLAYBACK_STATE_CHANGED, Player.EVENT_PLAYER_ERROR) { events -> // `Player` is a receiver scope for this trailing lambda if (events.contains(Player.EVENT_PLAYBACK_STATE_CHANGED)) { // Access the player state directly from the receiver updateUi(playbackState) } if (events.contains(Player.EVENT_PLAYER_ERROR)) { // Access the error directly from the player handleError(playerError) } } }
Nếu quan tâm đến nhiều loại sự kiện, bạn có thể truyền danh sách sự kiện đến Player.listenTo. Hàm lambda của bạn sẽ được gọi bất cứ khi nào có sự kiện nào trong số đó
xảy ra và bạn có thể kiểm tra tham số Events để xem sự kiện nào thực sự
đã kích hoạt:
coroutineScope.launch { player.listenTo(Player.EVENT_PLAYBACK_STATE_CHANGED, Player.EVENT_PLAYER_ERROR) { events -> // Unclear which event got triggered without querying `events` parameter // The following function will fire whenever either one is caught updateUiAndHandleError(playbackState, playerError) } }
Vì các hàm này hoạt động trên onEvents, nên chúng không cung cấp quyền truy cập vào các đối số tạm thời được truyền đến từng lệnh gọi lại, chẳng hạn như lý do trong onMediaItemTransition(..., int reason) hoặc oldPosition trong onPositionDiscontinuity(...). Nếu logic của bạn dựa vào các đối số cụ thể này (và các đối số này không có sẵn dưới dạng thuộc tính trạng thái trên Player), thì bạn nên sử dụng giao diện Player.Listener chuẩn.
Sử dụng AnalyticsListener
Khi sử dụng ExoPlayer, bạn có thể đăng ký AnalyticsListener với trình phát bằng cách gọi addAnalyticsListener. Các phương thức triển khai AnalyticsListener có thể theo dõi các sự kiện chi tiết có thể hữu ích cho mục đích phân tích và ghi nhật ký. Hãy xem trang số liệu phân tích để biết thêm thông tin.
Sử dụng EventLogger
EventLogger là một AnalyticsListener do thư viện cung cấp trực tiếp cho mục đích ghi nhật ký. Thêm EventLogger vào ExoPlayer để bật tính năng ghi nhật ký bổ sung hữu ích chỉ bằng một dòng:
Kotlin
player.addAnalyticsListener(EventLogger())
Java
player.addAnalyticsListener(new EventLogger());
Hãy xem trang ghi nhật ký gỡ lỗi để biết thêm chi tiết.
Kích hoạt sự kiện tại các vị trí phát cụ thể
Một số trường hợp sử dụng yêu cầu kích hoạt sự kiện tại các vị trí phát cụ thể. Bạn có thể sử dụng PlayerMessage để thực hiện việc này. Bạn có thể tạo PlayerMessage bằng
ExoPlayer.createMessage. Bạn có thể đặt vị trí phát mà tại đó lệnh sẽ được thực thi bằng cách sử dụng PlayerMessage.setPosition. Theo mặc định, thông báo được thực thi trên luồng phát, nhưng bạn có thể tuỳ chỉnh bằng cách sử dụng PlayerMessage.setLooper. Bạn có thể dùng PlayerMessage.setDeleteAfterDelivery để kiểm soát xem thông báo có được thực thi mỗi khi gặp vị trí phát đã chỉ định hay không (điều này có thể xảy ra nhiều lần do chế độ tua và chế độ lặp lại) hay chỉ thực thi lần đầu tiên. Sau khi định cấu hình PlayerMessage, bạn có thể lên lịch bằng PlayerMessage.send.
Kotlin
player .createMessage { messageType: Int, payload: Any? -> } .setLooper(Looper.getMainLooper()) .setPosition(/* mediaItemIndex= */ 0, /* positionMs= */ 120000) .setPayload(customPayloadData) .setDeleteAfterDelivery(false) .send()
Java
player .createMessage((messageType, payload) -> { // Do something at the specified playback position. }) .setLooper(Looper.getMainLooper()) .setPosition(/* mediaItemIndex= */ 0, /* positionMs= */ 120_000) .setPayload(customPayloadData) .setDeleteAfterDelivery(false) .send();