การเปลี่ยนแปลงสถานะของเพลเยอร์ (เช่น การเริ่มเล่น การบัฟเฟอร์ หรือข้อผิดพลาด) จะทริกเกอร์เหตุการณ์ที่ส่งไปยังอินสแตนซ์ Player.Listener ที่ลงทะเบียนไว้ เหตุการณ์เหล่านี้จะแสดงด้วยค่าคงที่จำนวนเต็มและกำหนดโดย Player.Event และ Player.Events
ลงทะเบียน Player.Listener
ระบบจะรายงานเหตุการณ์ของเพลเยอร์ไปยังอินสแตนซ์ Player.Listener ที่ลงทะเบียนไว้ วิธีลงทะเบียน Listener เพื่อรับเหตุการณ์ดังกล่าว
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);
หากใช้ Kotlin คุณยังใช้ฟังก์ชันส่วนขยายที่ระงับซึ่งโมดูล media3-common-ktx มีให้เพื่อฟังเหตุการณ์โดยใช้โครูทีนได้ด้วย
ในกรณีนี้ คุณไม่จำเป็นต้องลงทะเบียนหรือยกเลิกการลงทะเบียน Player.Listener อย่างชัดแจ้ง
ฟังเหตุการณ์การเล่นโดยใช้ Player.Listener
Player.Listener มีเมธอดเริ่มต้นที่ว่างเปล่า คุณจึงต้องใช้เฉพาะเมธอดที่คุณสนใจเท่านั้น ดูคำอธิบายแบบเต็มของเมธอดและเวลาที่เรียกใช้ได้ที่ Javadoc เราจะอธิบายวิธีการที่สำคัญที่สุดบางส่วนโดยละเอียดในภายหลัง
ผู้ฟังสามารถเลือกได้ว่าจะใช้ Callback ของแต่ละเหตุการณ์หรือ Callback onEvents ทั่วไปที่เรียกใช้หลังจากเกิดเหตุการณ์อย่างน้อย 1 เหตุการณ์พร้อมกัน ดูคำอธิบายว่าควรใช้ตัวเลือกใดสำหรับกรณีการใช้งานต่างๆ ได้ที่ Individual callbacks vs onEvents
การเปลี่ยนแปลงสถานะการเล่น
คุณรับการเปลี่ยนแปลงสถานะโปรแกรมเล่นได้โดยใช้ onPlaybackStateChanged(@State int state) ใน Player.Listener ที่ลงทะเบียนไว้
เพลเยอร์อาจอยู่ในสถานะการเล่นอย่างใดอย่างหนึ่งต่อไปนี้
Player.STATE_IDLE: สถานะเริ่มต้น สถานะเมื่อเพลเยอร์หยุดทำงาน และเมื่อเล่นไม่สำเร็จ ผู้เล่นจะเก็บทรัพยากรได้ในจำนวนจำกัดเท่านั้นในสถานะนี้Player.STATE_BUFFERING: โปรแกรมเล่นไม่สามารถเล่นจากตำแหน่งปัจจุบันได้ทันที ซึ่งมักเกิดขึ้นเนื่องจากต้องโหลดข้อมูลเพิ่มเติมPlayer.STATE_READY: โปรแกรมเล่นสามารถเล่นจากตำแหน่งปัจจุบันได้ทันทีPlayer.STATE_ENDED: เพลเยอร์เล่นสื่อทั้งหมดเสร็จแล้ว
นอกจากสถานะเหล่านี้แล้ว โปรแกรมเล่นยังมีแฟล็ก playWhenReady เพื่อระบุความตั้งใจของผู้ใช้ที่จะเล่น คุณจะรับการเปลี่ยนแปลงในแฟล็กนี้ได้โดยใช้ onPlayWhenReadyChanged(playWhenReady, @PlayWhenReadyChangeReason int reason)
เพลเยอร์จะเล่น (นั่นคือ ตำแหน่งของเพลเยอร์จะเลื่อนไปข้างหน้าและมีการนำเสนอสื่อต่อผู้ใช้) เมื่อเป็นไปตามเงื่อนไขทั้ง 3 ข้อต่อไปนี้
- เพลเยอร์อยู่ในสถานะ
Player.STATE_READY playWhenReadyคือtrue- ระบบไม่ได้ระงับการเล่นเนื่องจากเหตุผลที่แสดงโดย
Player.getPlaybackSuppressionReason
คุณสามารถเรียกใช้ Player.isPlaying แทนการตรวจสอบพร็อพเพอร์ตี้เหล่านี้ทีละรายการได้ คุณสามารถรับการเปลี่ยนแปลงสถานะนี้ได้โดยใช้ 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. } } });
ข้อผิดพลาดในการเล่น
คุณสามารถรับข้อผิดพลาดที่ทำให้การเล่นไม่สำเร็จได้โดยใช้ onPlayerError(PlaybackException error) ใน Player.Listener ที่ลงทะเบียนไว้ เมื่อเกิดความล้มเหลว ระบบจะเรียกใช้เมธอดนี้ทันทีก่อนที่สถานะการเล่นจะเปลี่ยนเป็น Player.STATE_IDLE คุณสามารถลองเล่นที่ล้มเหลวหรือหยุดไปอีกครั้งได้โดยเรียกใช้ ExoPlayer.prepare
โปรดทราบว่าการใช้งาน Player บางอย่างจะส่งอินสแตนซ์ของคลาสย่อยของ PlaybackException เพื่อให้ข้อมูลเพิ่มเติมเกี่ยวกับความล้มเหลว เช่น ExoPlayer จะส่ง ExoPlaybackException ซึ่งมี type, rendererIndex และช่องอื่นๆ ที่เจาะจงสำหรับ ExoPlayer
ตัวอย่างต่อไปนี้แสดงวิธีตรวจหาเมื่อการเล่นไม่สำเร็จเนื่องจากปัญหาเกี่ยวกับเครือข่าย 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
การเปลี่ยนเพลย์ลิสต์
เมื่อใดก็ตามที่เพลเยอร์เปลี่ยนไปใช้รายการสื่อใหม่ในเพลย์ลิสต์ ระบบจะเรียกใช้ onMediaItemTransition(MediaItem mediaItem, @MediaItemTransitionReason int
reason) ในออบเจ็กต์ Player.Listener ที่ลงทะเบียนไว้ เหตุผลจะระบุว่าเป็นการเปลี่ยนอัตโนมัติ การค้นหา (เช่น หลังจากเรียก player.next()) การเล่นซ้ำรายการเดียวกัน หรือเกิดจากการเปลี่ยนแปลงเพลย์ลิสต์ (เช่น หากมีการนำรายการที่กำลังเล่นอยู่ออก)
ข้อมูลเมตา
ข้อมูลเมตาที่แสดงผลจาก player.getCurrentMediaMetadata() อาจเปลี่ยนแปลงได้เนื่องจากสาเหตุหลายประการ เช่น การเปลี่ยนเพลย์ลิสต์ การอัปเดตข้อมูลเมตาในสตรีม หรือการอัปเดต MediaItem ปัจจุบันระหว่างการเล่น
หากสนใจการเปลี่ยนแปลงข้อมูลเมตา เช่น เพื่ออัปเดต UI ที่แสดงชื่อปัจจุบัน คุณสามารถฟัง onMediaMetadataChanged ได้
กำลังค้นหา
การเรียกใช้เมธอด Player.seekTo จะส่งผลให้เกิดชุด Callback ไปยังอินสแตนซ์ Player.Listener ที่ลงทะเบียนไว้ ดังนี้
onPositionDiscontinuityเมื่อใช้reason=DISCONTINUITY_REASON_SEEKซึ่งเป็นผลโดยตรงจากการเรียกใช้Player.seekToCallback มีช่องPositionInfoสำหรับตำแหน่งก่อนและหลังการกรอonPlaybackStateChangedพร้อมการเปลี่ยนแปลงสถานะทันทีที่เกี่ยวข้องกับการกรอวิดีโอ โปรดทราบว่าอาจไม่มีการเปลี่ยนแปลงดังกล่าว
หากคุณเปิดใช้โหมดสครับด้วย ExoPlayer.setScrubbingModeEnabled สำหรับการลากแถบเลื่อนแบบอินเทอร์แอกทีฟ ExoPlayer จะระงับการเล่นและเรียกใช้ onPlaybackSuppressionReasonChanged ด้วย Player.PLAYBACK_SUPPRESSION_REASON_SCRUBBING การเรียก Player.seekTo แต่ละครั้งจะยังคงทริกเกอร์ onPositionDiscontinuity แม้ว่า ExoPlayer จะยกเลิกการค้นหาที่ถูกแทนที่และรายงานไปยัง AnalyticsListener.onDroppedSeeksWhileScrubbing ก็ตาม
การติดต่อกลับแต่ละครั้งเทียบกับ onEvents
ผู้ฟังสามารถเลือกระหว่างการใช้ Callback แต่ละรายการ เช่น onIsPlayingChanged(boolean isPlaying) และ Callback onEvents(Player
player, Events events) ทั่วไป Callback ทั่วไปจะให้สิทธิ์เข้าถึงออบเจ็กต์ Player และระบุชุด events ที่เกิดขึ้นพร้อมกัน ระบบจะเรียกใช้ Callback นี้หลังจาก Callback ที่สอดคล้องกับแต่ละเหตุการณ์เสมอ
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); } }
คุณควรใช้เหตุการณ์เดี่ยวในกรณีต่อไปนี้
- ผู้ฟังสนใจเหตุผลของการเปลี่ยนแปลง เช่น เหตุผลที่ระบุไว้สำหรับ
onPlayWhenReadyChangedหรือonMediaItemTransition - Listener จะดำเนินการกับค่าใหม่ที่ระบุผ่านพารามิเตอร์ Callback หรือทริกเกอร์สิ่งอื่นที่ไม่ขึ้นอยู่กับพารามิเตอร์ Callback เท่านั้น
- การติดตั้งใช้งาน Listener ต้องการการระบุที่ชัดเจนและอ่านได้ว่าอะไรเป็นตัวทริกเกอร์เหตุการณ์ในชื่อเมธอด
- Listener จะรายงานไปยังระบบวิเคราะห์ที่จำเป็นต้องทราบเกี่ยวกับเหตุการณ์และการเปลี่ยนแปลงสถานะทั้งหมด
ควรใช้ onEvents(Player player, Events events) ทั่วไปในกรณีต่อไปนี้
- Listener ต้องการทริกเกอร์ตรรกะเดียวกันสําหรับหลายเหตุการณ์ ตัวอย่างเช่น การอัปเดต UI สำหรับทั้ง
onPlaybackStateChangedและonPlayWhenReadyChanged - Listener ต้องเข้าถึงออบเจ็กต์
Playerเพื่อทริกเกอร์เหตุการณ์เพิ่มเติม เช่น การกรอหลังจากเปลี่ยนรายการสื่อ - Listener ตั้งใจที่จะใช้ค่าสถานะหลายค่าที่รายงานผ่าน Callback แยกกันร่วมกัน หรือใช้ร่วมกับเมธอด Getter
Playerตัวอย่างเช่น การใช้Player.getCurrentWindowIndex()กับTimelineที่ระบุในonTimelineChangedจะปลอดภัยจากภายใน CallbackonEventsเท่านั้น - ผู้ฟังสนใจว่าเหตุการณ์ต่างๆ เกิดขึ้นร่วมกันอย่างสมเหตุสมผลหรือไม่
เช่น
onPlaybackStateChangedเป็นSTATE_BUFFERINGเนื่องจากการเปลี่ยนรายการสื่อ
ในบางกรณี Listener อาจต้องรวม Callback แต่ละรายการเข้ากับ Callback onEvents ทั่วไป เช่น เพื่อบันทึกเหตุผลการเปลี่ยนแปลงรายการสื่อด้วย onMediaItemTransition แต่จะดำเนินการก็ต่อเมื่อการเปลี่ยนแปลงสถานะทั้งหมดสามารถใช้ร่วมกันใน onEvents ได้เท่านั้น
ฟังเหตุการณ์การเล่นโดยใช้โครูทีน
หรือจะเปิดใช้โครูทีน Kotlin โดยใช้ Player.listenTo และระบุ Player.Event ที่เกี่ยวข้องก็ได้ ดังนี้
โปรดทราบว่าคุณสามารถเรียกใช้ Player.listen และ Player.listenTo ได้จากชุดข้อความใดก็ได้ ขณะที่ระบบจะเรียกใช้ Callback Lambda ในชุดข้อความที่เชื่อมโยงกับ Player.getApplicationLooper เสมอ ดังนั้นจึงเข้าถึงเมธอดและพร็อพเพอร์ตี้สถานะของ Player ภายใน Lambda ของ Callback ได้อย่างปลอดภัย แม้ว่า Coroutine จะเปิดขึ้นในชุดข้อความอื่นก็ตาม
การเปลี่ยนแปลงสถานะการเล่น
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. } } }
ข้อผิดพลาดในการเล่น
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 } } } }
การติดต่อกลับแต่ละครั้งเทียบกับ onEvents
เมื่อฟังเหตุการณ์ของเพลเยอร์ภายในโครูทีน คุณจะต้องระบุการติดตั้งใช้งานสำหรับ Callback onEvents เสมอ แทนที่จะเป็น Callback แต่ละรายการ คุณสามารถเลือกระหว่าง Player.listen กับ Player.listenTo โดยขึ้นอยู่กับว่าเหตุการณ์ใดควรทริกเกอร์การเรียกใช้ Lambda แต่ฟังก์ชันจะเทียบเท่ากันในด้านอื่นๆ ดังนี้
ฟัง
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) } } }
หากสนใจเหตุการณ์หลายประเภท คุณสามารถส่งรายการเหตุการณ์ไปยัง Player.listenTo ได้ ระบบจะเรียกใช้ Lambda เมื่อใดก็ตามที่เกิดเหตุการณ์เหล่านั้น และคุณสามารถตรวจสอบพารามิเตอร์ Events เพื่อดูว่าเหตุการณ์ใดเริ่มทำงานจริง
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) } }
เนื่องจากฟังก์ชันเหล่านี้ทำงานใน onEvents จึงไม่ให้สิทธิ์เข้าถึงอาร์กิวเมนต์ชั่วคราวที่ส่งไปยัง Callback แต่ละรายการ เช่น เหตุผลใน onMediaItemTransition(..., int reason) หรือ oldPosition ใน onPositionDiscontinuity(...) หากตรรกะของคุณอาศัยอาร์กิวเมนต์ที่เฉพาะเจาะจงเหล่านี้ (และไม่พร้อมใช้งานเป็นพร็อพเพอร์ตี้สถานะใน Player) คุณควรใช้อินเทอร์เฟซ Player.Listener มาตรฐานแทน
ใช้ AnalyticsListener
เมื่อใช้ ExoPlayer คุณสามารถลงทะเบียน AnalyticsListener กับเพลเยอร์ได้โดยเรียกใช้ addAnalyticsListener การติดตั้งใช้งาน AnalyticsListener สามารถฟังเหตุการณ์โดยละเอียดซึ่งอาจเป็นประโยชน์สำหรับการวิเคราะห์และการบันทึก ดูรายละเอียดเพิ่มเติมได้ที่หน้าข้อมูลวิเคราะห์
ใช้ EventLogger
EventLogger เป็น AnalyticsListener ที่ไลบรารีจัดเตรียมไว้ให้โดยตรงเพื่อวัตถุประสงค์ในการบันทึก เพิ่ม EventLogger ลงใน ExoPlayer เพื่อเปิดใช้การบันทึกเพิ่มเติมที่เป็นประโยชน์ด้วยบรรทัดเดียว ดังนี้
Kotlin
player.addAnalyticsListener(EventLogger())
Java
player.addAnalyticsListener(new EventLogger());
ดูรายละเอียดเพิ่มเติมได้ที่หน้าการบันทึกแก้ไขข้อบกพร่อง
เริ่มเหตุการณ์ที่ตำแหน่งการเล่นที่ระบุ
กรณีการใช้งานบางกรณีจำเป็นต้องเริ่มเหตุการณ์ที่ตำแหน่งการเล่นที่ระบุ ซึ่งรองรับการใช้ PlayerMessage คุณสร้าง PlayerMessage ได้โดยใช้ ExoPlayer.createMessage คุณตั้งค่าตำแหน่งการเล่นที่ควรดำเนินการได้โดยใช้ PlayerMessage.setPosition ระบบจะดำเนินการกับข้อความในเทรดการเล่นโดยค่าเริ่มต้น แต่คุณสามารถปรับแต่งได้โดยใช้ PlayerMessage.setLooper PlayerMessage.setDeleteAfterDelivery สามารถใช้เพื่อควบคุมว่าจะให้เรียกใช้ข้อความทุกครั้งที่พบตำแหน่งการเล่นที่ระบุหรือไม่ (ซึ่งอาจเกิดขึ้นหลายครั้งเนื่องจากการกรอและโหมดเล่นซ้ำ) หรือเฉพาะครั้งแรกเท่านั้น เมื่อกำหนดค่า PlayerMessage แล้ว คุณจะกำหนดเวลาได้โดยใช้ 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();