播放器事件

监听播放事件

系统会将状态变化和播放错误等事件报告给已注册的 Player.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);

Player.Listener 具有空的默认方法，因此您只需实现自己感兴趣的方法。如需查看方法的完整说明以及调用时间，请参阅 Javadoc。下面将更详细地介绍一些最重要的方法。

监听器可以选择实现单个事件回调，也可以实现通用的 onEvents 回调，后者会在一个或多个事件一起发生后被调用。如需了解在不同使用场景下应首选哪种方法，请参阅 Individual callbacks vs onEvents。

播放状态变更

通过在已注册的 Player.Listener 中实现 onPlaybackStateChanged(@State int state)，可以接收播放器状态的变化。播放器可能会处于以下 4 种播放状态之一：

Player.STATE_IDLE：这是初始状态，也是播放器停止和播放失败时的状态。播放器在此状态下只会保留有限的资源。
Player.STATE_BUFFERING：播放器无法立即从当前位置开始播放。这主要是因为需要加载更多数据。
Player.STATE_READY：播放器可以立即从当前位置开始播放。
Player.STATE_ENDED：播放器已完成所有媒体的播放。

除了这些状态之外，播放器还有一个 playWhenReady 标志来指示用户的播放意图。通过实现 onPlayWhenReadyChanged(playWhenReady, @PlayWhenReadyChangeReason int reason) 可以接收此标志的更改。

当满足以下全部三个条件时，播放器正在播放（即，其位置在前进，并且正在向用户呈现媒体）：

播放器处于 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.
        }
      }
    });

播放错误

通过在已注册的 Player.Listener 中实现 onPlayerError(PlaybackException error)，可以接收导致播放失败的错误。发生故障时，系统会在播放状态转换为 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.
        }
      }
    }
  }
)

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.
          }
        }
      }
    });

播放列表过渡

每当播放器在播放列表中切换到新的媒体项时，系统都会对已注册的 Player.Listener 对象调用 onMediaItemTransition(MediaItem mediaItem, @MediaItemTransitionReason int reason)。该原因表示这是自动过渡、搜索（例如在调用 player.next() 后）、同一项的重复播放，还是由播放列表更改（例如，如果移除了当前播放的项）引起的。

元数据

由于多种原因，从 player.getCurrentMediaMetadata() 返回的元数据可能会发生变化：播放列表过渡、插播广告元数据更新或在播放过程中更新当前 MediaItem。

如果您对元数据更改感兴趣（例如，为了更新显示当前标题的界面），可以监听 onMediaMetadataChanged。

正在指定播放时间点

调用 Player.seekTo 方法会导致对已注册的 Player.Listener 实例进行一系列回调：

onPositionDiscontinuity 是 reason=DISCONTINUITY_REASON_SEEK。这是调用 Player.seekTo 的直接结果。该回调具有 PositionInfo 字段，分别表示搜索前后的位置。
onPlaybackStateChanged，其中包含与搜索相关的任何即时状态变化。请注意，可能没有此类更改。

单个回调与 `onEvents`

监听器可以选择实现 onIsPlayingChanged(boolean isPlaying) 等单个回调，也可以选择实现通用的 onEvents(Player player, Events events) 回调。通用回调提供对 Player 对象的访问权限，并指定同时发生的一组 events。此回调始终在与各个事件对应的回调之后调用。

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 提供的理由。
监听器仅对通过回调参数提供的新值执行操作，或触发不依赖于回调参数的其他操作。
监听器实现最好在方法名称中清晰明了地指明触发事件的原因。
监听器会向需要了解所有单个事件和状态更改的分析系统报告。

在以下情况下，应首选泛型 onEvents(Player player, Events events)：

监听器希望针对多个事件触发相同的逻辑。例如，同时为 onPlaybackStateChanged 和 onPlayWhenReadyChanged 更新界面。
监听器需要访问 Player 对象才能触发更多事件，例如在媒体项过渡后进行搜索。
监听器打算一起使用通过单独的回调报告的多个状态值，或者将这些状态值与 Player getter 方法结合使用。例如，使用 Player.getCurrentWindowIndex() 和 onTimelineChanged 中提供的 Timeline 仅在 onEvents 回调中是安全的。
监听器关注的是事件是否在逻辑上同时发生。例如，由于媒体项过渡，从 onPlaybackStateChanged 变为 STATE_BUFFERING。

在某些情况下，监听器可能需要将各个回调与通用 onEvents 回调相结合，例如使用 onMediaItemTransition 记录媒体项更改原因，但只有在 onEvents 中可以一起使用所有状态更改时才采取行动。

使用 `AnalyticsListener`

使用 ExoPlayer 时，可以通过调用 addAnalyticsListener 向播放器注册 AnalyticsListener。AnalyticsListener 实现能够监听可能对分析和日志记录有用的详细事件。如需了解详情，请参阅分析页面。

使用 `EventLogger`

EventLogger 是库直接提供的 AnalyticsListener，用于日志记录。向 ExoPlayer 添加 EventLogger，只需一行代码即可启用有用的额外日志记录：

Kotlin

player.addAnalyticsListener(EventLogger())

Java

player.addAnalyticsListener(new EventLogger());

如需了解详情，请参阅调试日志记录页面。

在指定播放位置触发事件

在某些用例中，需要在指定的播放位置触发事件。此功能通过 PlayerMessage 提供支持。可以使用 ExoPlayer.createMessage 创建 PlayerMessage。可以使用 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();

播放器事件 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

监听播放事件

Kotlin

Java

播放状态变更

Kotlin

Java

播放错误

Kotlin

Java

播放列表过渡

元数据

正在指定播放时间点

单个回调与 onEvents

Kotlin

Java

使用 AnalyticsListener

使用 EventLogger

Kotlin

Java

在指定播放位置触发事件

Kotlin

Java

播放器事件

单个回调与 `onEvents`

使用 `AnalyticsListener`

使用 `EventLogger`