简介
AtomicPlayer 管理低延迟直播和 CDN 流的视频播放。 渲染视图在运行时通过 setView 绑定;视频帧将渲染到给定的 AtomicLiveView 容器中。此绑定与视图的窗口挂载时序解耦:在视图挂载到窗口前调用 setView 是安全的(例如在 UICollectionViewCell 或 RecyclerView 中),绑定将在视图就绪后自动完成。 主要能力:拉流播放(
startPlay / stopPlay)。渲染视图绑定与旋转模式控制(
setView / setRenderRotation)。频道加入与离开(
joinChannel / leaveChannel)。播放控制(
switchStream)。SEI 消息接收(
enableReceiveSeiMessage)。播放状态与统计(
state 实时状态、PlayerStatistics 统计信息)。事件回调(Swift 通过
playerEvent、Kotlin 通过 addListener 接收 SEI 数据、错误、直播结束、被踢出等事件)。功能特性
PlayerState:播放状态,包含播放生命周期状态和统计信息。
PlayerEvent:播放器事件回调,包含 SEI 接收、播放错误、直播结束、被踢出等事件类型。
可订阅数据
PlayerState 的字段描述如下:
属性名 | 类型 | 描述 |
playbackStatus | 播放状态,反映当前播放生命周期。 | |
statistics | 播放运行时统计,由 SDK 周期性上报。 | |
totalViewerCount | StateFlow<Int> | 总观众数。 |
API 列表
函数名 | 描述 |
添加播放器事件回调监听器。 | |
移除播放器事件回调监听器。 | |
设置渲染视图。 | |
设置渲染旋转角度。 | |
截取当前视频帧。 | |
开始播放指定 URL 的远端流。 | |
停止播放。 | |
无缝切换到新的流地址。 | |
设置播放音量。 | |
加入频道。 | |
离开频道。 | |
启用或禁用 SEI 消息接收。 | |
通过键值对启用高级特性。 |
观察状态和事件
addListener
添加播放器事件回调监听器。
fun addListener(listener: PlayerListener?) = impl.addListener(listener)
版本信息
从3.5版本开始支持。
参数说明
参数名 | 类型 | 描述 |
listener | 监听器。 |
removeListener
移除播放器事件回调监听器。
fun removeListener(listener: PlayerListener?) = impl.removeListener(listener)
版本信息
从3.5版本开始支持。
参数说明
参数名 | 类型 | 描述 |
listener | 监听器。 |
视图管理
setView
设置渲染视图。视频帧将渲染到给定的
AtomicLiveView 容器中。此绑定与视图挂载窗口的时机解耦:可在视图挂载窗口前调用(如 UICollectionView cell 或 RecyclerView 中),视图就绪后自动完成绑定。fun setView(view: AtomicLiveView) = impl.setView(view)
版本信息
从3.5版本开始支持。
参数说明
参数名 | 类型 | 描述 |
view | 渲染视图容器。 |
setRenderRotation
设置渲染旋转角度。
fun setRenderRotation(rotation: PlayerRenderRotation) = impl.setRenderRotation(rotation)
版本信息
从3.5版本开始支持。
参数说明
参数名 | 类型 | 描述 |
rotation | 渲染旋转角度。 |
snapshot
截取当前视频帧。
fun snapshot(callback: SnapshotCallback? = null) = impl.snapshot(callback)
版本信息
从3.5版本开始支持。
参数说明
参数名 | 类型 | 描述 |
callback | SnapshotCallback? | 截图结果回调。截图失败时图片为 null。 |
播放控制
startPlay
开始播放指定 URL 的远端流。在已播放的实例上调用此方法会停止前一个流并播放新的流。
fun startPlay(url: String) = impl.startPlay(url)
版本信息
从3.5版本开始支持。
参数说明
参数名 | 类型 | 描述 |
url | String | 流地址。 |
stopPlay
停止播放。
fun stopPlay() = impl.stopPlay()
版本信息
从3.5版本开始支持。
switchStream
无缝切换到新的流地址,不拆除当前渲染视图。适用于清晰度切换(如 720p → 1080p)和 CDN 线路故障转移。
fun switchStream(url: String, completion: CompletionHandler? = null) = impl.switchStream(url, completion)
版本信息
从3.5版本开始支持。
参数说明
参数名 | 类型 | 描述 |
url | String | 新流地址。 |
completion | 切换结果回调(成功/失败状态)。 |
setVolume
设置播放音量。
fun setVolume(volume: Int) = impl.setVolume(volume)
版本信息
从3.5版本开始支持。
参数说明
参数名 | 类型 | 描述 |
volume | Int | 音量等级,取值范围 0 ~ 100;超出范围的值会被截断。 |
频道管理
joinChannel
加入频道。
fun joinChannel(liveID: String, completion: CompletionHandler? = null) = impl.joinChannel(liveID, completion)
版本信息
从3.5版本开始支持。
参数说明
参数名 | 类型 | 描述 |
liveID | String | 直播 ID。 |
completion | 完成回调。 |
leaveChannel
离开频道。
fun leaveChannel() = impl.leaveChannel()
版本信息
从3.5版本开始支持。
SEI 消息
enableReceiveSeiMessage
启用或禁用 SEI 消息接收。启用后,嵌入视频流中的 SEI 数据将通过
PlayerEvent.seiReceived 事件投递。fun enableReceiveSeiMessage(enable: Boolean, payloadType: Int) = impl.enableReceiveSeiMessage(enable, payloadType)
版本信息
从3.5版本开始支持。
参数说明
参数名 | 类型 | 描述 |
enable | Boolean | 是否启用 SEI 消息接收。 |
payloadType | Int | 要过滤的 SEI payload 类型。常见值:243(自定义布局)、100(音量布局)、245(ASR 消息)。 |
高级功能
enableAdvancedFeature
通过键值对启用高级特性。支持的键取决于底层原生播放器能力,可能随版本演进。
fun enableAdvancedFeature(key: String, value: Any) = impl.enableAdvancedFeature(key, value)
版本信息
从3.5版本开始支持。
参数说明
参数名 | 类型 | 描述 |
key | String | 特性键。 |
value | Any | 特性值,类型取决于具体键。 |
数据结构
PlayerCode
播放器错误码,用于上报播放器操作结果和运行时错误。
枚举值 | 值 | 说明 |
OK | 0 | 无错误,操作成功。 |
ERROR_INVALID_PARAMETER | -1001 | 参数非法。 |
PlayerPlaybackStatus
播放器状态,反映当前播放生命周期。 状态机(典型迁移):
startPlayIDLE ──────────────────▶ LOADING▲ ││ play succeededstopPlay │connection lost ││ ▼│◀─────────────────────PLAYING ◀────────────────┐│ │ ││ │ ││ buffering recover succeeded│ │ ││ ▼ │└──────────────────────LOADING ─────────────────┘
说明:
IDLE 为初始状态;调用 stopPlay 后也会回到该状态。 缓冲 / 自动恢复过程复用 LOADING,不区分“首次加载”与“重新缓冲”。枚举值 | 值 | 说明 |
IDLE | 0 | 空闲。初始状态,或播放停止 / 连接断开。 |
LOADING | 1 | 加载中。正在建立连接或缓冲数据;视频尚未开始或暂时停顿。 |
PLAYING | 2 | 播放中。链路正常,视频流畅播放。 |
PlayerRenderRotation
视频渲染旋转角度。
枚举值 | 值 | 说明 |
ROTATION_0 | 0 | 不旋转。 |
ROTATION_90 | 1 | 顺时针旋转 90 度。 |
ROTATION_180 | 2 | 顺时针旋转 180 度。 |
ROTATION_270 | 3 | 顺时针旋转 270 度。 |
PlayerListener
播放器事件监听器,用于接收 SEI 数据、播放错误、直播结束、被踢出等一次性事件。通过
addListener / removeListener 注册/移除监听器。PlayerStatistics
播放器运行时统计信息,包含活跃播放器的实时运行指标。
属性 | 类型 | 说明 |
videoWidth | Int | 视频宽度(像素)。 |
videoHeight | Int | 视频高度(像素)。 |
videoFps | Int | 视频帧率(fps)。 |
videoBitrate | Int | 视频码率(bps)。 |
audioBitrate | Int | 音频码率(bps)。 |
PlayerState
播放器响应式状态,携带 AtomicPlayer 的状态。可通过
state 读取当前值或观察变化。属性 | 类型 | 说明 |
playbackStatus | 播放状态,反映当前播放生命周期。 | |
statistics | 播放运行时统计,由 SDK 周期性上报。 | |
totalViewerCount | StateFlow<Int> | 总观众数。 |