播放器接口

播放器是应用中促进媒体项播放的组件。Media3 Player 接口为播放器通常处理的功能设定了框架。这包括

  • 影响播放控制,例如播放、暂停和查找
  • 查询当前播放媒体的属性,例如播放位置
  • 管理媒体项的播放列表/队列
  • 配置播放属性,例如随机播放、重复、速度和音量
  • 将视频渲染到屏幕

Media3 还提供了 Player 接口的实现,称为 ExoPlayer

组件之间的通用接口

Media3 中的几个组件实现了 `Player` 接口,例如

组件 描述和行为说明
ExoPlayer 一个媒体播放器 API,也是 Player 接口的默认实现。
MediaController MediaSession 交互以发送播放命令。如果您的 PlayerMediaSession 位于与播放器 UI 所在的 ActivityFragment 分离的 Service 中,则可以将 MediaController 分配为 PlayerView UI 的播放器。播放和播放列表方法调用会通过 MediaSession 发送到您的 Player
MediaBrowser 除了 MediaController 提供的功能外,还与 MediaLibrarySession 交互以浏览可用的媒体内容。
SimpleBasePlayer 一个 Player 实现,它将要实现的方法数量减少到最少。在使用要连接到 MediaSession 的自定义播放器时很有用。
ForwardingSimpleBasePlayer SimpleBasePlayer 的一个子类,旨在将播放操作转发到另一个 Player,同时允许与 SimpleBasePlayer 相同的行为自定义。使用此类别可以抑制或修改特定的播放操作。
CastPlayer 与 Cast 接收器应用通信的 Player 实现。行为取决于底层 Cast 会话。

尽管 MediaSession 未实现 Player 接口,但在创建时需要一个 Player。其目的是提供从其他进程或线程访问 Player 的权限。

Media3 播放架构

如果您可以访问 Player,则应直接调用其方法以发出播放命令。您可以通过实现 MediaSession 来宣传您的播放并授予外部源播放控制权限。这些外部源实现 MediaController,它有助于连接到媒体会话并发出播放命令请求。

在后台播放媒体时,您需要将媒体会话和播放器置于作为前台服务运行的 MediaSessionServiceMediaLibraryService 中。如果这样做,您可以将播放器与应用中包含播放控制 UI 的 Activity 分离。这可能需要您使用媒体控制器。

A diagram showing how Media3 playback components fit into a media app architecture.
图 1Player 接口在 Media3 架构中扮演着关键角色。

播放器状态

实现 Player 接口的媒体播放器状态主要由以下 4 类信息组成

  1. 播放状态
  2. 媒体项播放列表
  3. 播放/暂停属性,例如
    • playWhenReady:指示用户是否希望媒体在可能时播放或保持暂停状态
    • 播放抑制原因:指示播放被抑制的原因(如果适用),即使 playWhenReadytrue 也是如此
    • isPlaying:指示播放器当前是否正在播放,只有当播放状态为 STATE_READYplayWhenReadytrue 且播放未被抑制时,此值才为 true
  4. 播放位置,包括

此外,Player 接口允许访问可用轨道媒体元数据播放速度音量和播放的其他辅助属性。

监听更改

使用 Player.Listener 监听 Player 中的更改。有关如何创建和使用监听器的详细信息,请参阅 ExoPlayer 文档中的“播放器事件”

请注意,监听器接口不包含任何用于跟踪正常播放进度的回调。要持续监控播放进度,例如设置进度条 UI,您应该以适当的间隔查询当前位置。

Kotlin

val handler = Handler(Looper.getMainLooper())
fun checkPlaybackPosition(delayMs: Long): Boolean =
  handler.postDelayed(
    {
      val currentPosition = player.currentPosition
      // Update UI based on currentPosition
      checkPlaybackPosition(delayMs)
    },
    delayMs)

Java

Handler handler = new Handler(Looper.getMainLooper());
boolean checkPlaybackPosition(long delayMs) {
    return handler.postDelayed(() -> {
        long currentPosition = player.getCurrentPosition();
        // Update UI based on currentPosition
        checkPlaybackPosition(delayMs);
    }, delayMs);
}

控制播放

Player 接口提供了多种操作状态和控制播放的方法

自定义 Player 实现

要创建自定义播放器,您可以扩展 Media3 中包含的 SimpleBasePlayer。此类提供了 Player 接口的基本实现,以最大程度地减少您需要实现的方法数量。

首先,覆盖 getState() 方法。此方法在被调用时应填充当前播放器状态,包括

  • 可用命令集
  • 播放属性,例如当播放状态为 STATE_READY 时播放器是否应开始播放、当前播放媒体项的索引以及当前项中的播放位置

Kotlin

class CustomPlayer : SimpleBasePlayer(looper) {
  override fun getState(): State {
    return State.Builder()
      .setAvailableCommands(...) // Set which playback commands the player can handle
      // Configure additional playback properties
      .setPlayWhenReady(true, PLAY_WHEN_READY_CHANGE_REASON_USER_REQUEST)
      .setCurrentMediaItemIndex(0)
      .setContentPositionMs(0)
      .build()
  }
}

Java

public class CustomPlayer extends SimpleBasePlayer {
  public CustomPlayer(Looper looper) {
    super(looper);
  }

  @Override
  protected State getState() {
    return new State.Builder()
      .setAvailableCommands(...) // Set which playback commands the player can handle
      // Configure additional playback properties
      .setPlayWhenReady(true, PLAY_WHEN_READY_CHANGE_REASON_USER_REQUEST)
      .setCurrentMediaItemIndex(0)
      .setContentPositionMs(0)
      .build();
  }
}

SimpleBasePlayer 将强制 State 以有效状态值组合创建。它还将处理监听器并通知监听器状态更改。如果需要手动触发状态更新,请调用 invalidateState()

除了 getState() 方法,您只需要实现用于播放器声明可用的命令的方法。找到与您要实现的功能对应的可重写处理程序方法。例如,覆盖 handleSeek() 方法以支持 COMMAND_SEEK_IN_CURRENT_MEDIA_ITEMCOMMAND_SEEK_TO_NEXT_MEDIA_ITEM 等操作。

修改 Player 实现

您可以使用 ForwardingSimpleBasePlayer 修改现有 Player 的状态和行为,而不是创建完全自定义的 Player。有关更多详细信息,请参阅“自定义”页面上的指南。