播放器是应用中用于播放媒体项的组件。Media3 Player
接口为播放器通常处理的功能设置了一个大纲。这包括:
- 影响播放控制,例如播放、暂停和跳转
- 查询当前正在播放的媒体的属性,例如播放位置
- 管理媒体项的播放列表/队列
- 配置播放属性,例如随机播放、重复播放、速度和音量
- 向屏幕呈现视频
Media3 还提供了一个 Player
接口的实现,称为 ExoPlayer
。
组件之间的通用接口
Media3 中的多个组件实现了 Player 接口,例如:
组件 | 说明和行为备注 |
---|---|
ExoPlayer |
媒体播放器 API,以及 Player 接口的默认实现。 |
MediaController |
与 MediaSession 互动以发送播放命令。如果您的 Player 和 MediaSession 位于与播放器 Activity 或播放器界面 Fragment 不同的 Service 中,您可以将 MediaController 指定为 PlayerView 界面的播放器。播放和播放列表方法调用通过 MediaSession 发送到 Player 。
|
MediaBrowser |
除了 MediaController 提供的功能之外,还可与 MediaLibrarySession 互动以浏览可用的媒体内容。
|
SimpleBasePlayer |
一种 Player 实现,可将要实现的方法数量减少到最低限度。当您使用想要连接到 MediaSession 的自定义播放器时,此属性非常有用。
|
ForwardingSimpleBasePlayer |
一种 SimpleBasePlayer 子类,旨在将播放操作转发到另一个 Player ,同时允许与 SimpleBasePlayer 相同的行为自定义。使用此类可抑制或修改特定播放操作。
|
CastPlayer |
一种与 Cast 接收器应用通信的 Player 实现。行为取决于底层 Cast 会话。
|
虽然 MediaSession
不实现 Player
接口,但在创建 MediaSession
时需要 Player
。其目的是允许其他进程或线程访问 Player
。
Media3 播放架构
如果您有权访问 Player
,则应直接调用其方法来发出播放命令。您可以通过实现 MediaSession
来通告播放并授予外部来源播放控制权。这些外部来源实现了一个 MediaController
,可用于连接到媒体会话并发出播放命令请求。
在后台播放媒体时,您需要将媒体会话和播放器置于作为前台服务运行的 MediaSessionService
或 MediaLibraryService
中。如果您这样做,就可以将播放器与应用中包含播放控制界面的 Activity 分开。这可能需要您使用媒体控制器。

Player
接口在 Media3 的架构中发挥着关键作用。播放器状态
实现 Player
接口的媒体播放器的状态主要包含 4 类信息:
- 播放状态
- 使用
getPlaybackState()
进行检索。 - 接口定义的状态值包括
STATE_IDLE
、STATE_BUFFERING
、STATE_READY
和STATE_ENDED
。
- 使用
- 媒体内容播放列表
- 用于播放的
MediaItem
实例序列。 - 使用
getCurrentTimeline()
进行检索 Player
实例可以提供播放列表操作方法,例如添加或移除MediaItem
,以及简便方法,例如getCurrentMediaItem()
。
- 用于播放的
- 播放/暂停属性,例如:
playWhenReady
:指示用户是否希望媒体在可能的情况下播放,或者保持暂停状态- 播放抑制原因:指示播放被抑制的原因(如果适用),即使
playWhenReady
为true
isPlaying
:表示播放器当前是否正在播放,只有在播放状态为STATE_READY
、playWhenReady
为true
且播放未被抑制时,此值为true
- 播放位置,包括:
- 当前媒体内容项的索引:播放列表中当前
MediaItem
的索引。 isPlayingAd
:表示是否正在播放插播广告。- 当前播放位置:当前
MediaItem
或插播广告中的当前播放位置。
- 当前媒体内容项的索引:播放列表中当前
此外,通过 Player
接口,可以访问可用轨道、媒体元数据、播放速度、音量以及播放的其他辅助属性。
监听更改
使用 Player.Listener
监听 Player
中的更改。如需详细了解如何创建和使用监听器,请参阅有关播放器事件的 ExoPlayer 文档。
请注意,监听器接口不包含任何用于跟踪正常播放进度的回调。如需持续监控播放进度(例如设置进度条界面),您应以适当的时间间隔查询当前位置。
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
接口提供了多种方式来操纵状态和控制播放:
- 基本播放控件,例如
play()
、pause()
、prepare()
和stop()
。 - 播放列表操作,例如
addMediaItem()
或removeMediaItem()
。 - 搜索以更改当前内容或位置。
- 设置重复播放模式和随机播放模式。
- 更新轨道选择偏好设置。
- 设置播放速度。
自定义 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_ITEM
和 COMMAND_SEEK_TO_NEXT_MEDIA_ITEM
等操作。
修改 Player
实现
您可以利用 ForwardingSimpleBasePlayer
修改现有 Player
的状态和行为,而无需创建完全自定义的 Player
。如需了解详情,请参阅“自定义”页面上的指南。