เหตุการณ์ของผู้เล่น

การเปลี่ยนแปลงสถานะของเพลเยอร์ (เช่น การเริ่มเล่น การบัฟเฟอร์ หรือข้อผิดพลาด) จะทริกเกอร์เหตุการณ์ที่ส่งไปยังอินสแตนซ์ 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 ที่ลงทะเบียนไว้ ดังนี้

  1. onPositionDiscontinuity เมื่อใช้ reason=DISCONTINUITY_REASON_SEEK ซึ่งเป็นผลโดยตรงจากการเรียกใช้ Player.seekTo Callback มีช่อง PositionInfo สำหรับตำแหน่งก่อนและหลังการกรอ
  2. 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 จะปลอดภัยจากภายใน Callback onEvents เท่านั้น
  • ผู้ฟังสนใจว่าเหตุการณ์ต่างๆ เกิดขึ้นร่วมกันอย่างสมเหตุสมผลหรือไม่ เช่น 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();