Protocol: Events

所有从 player 上抛到 host(或 inline 场景直接触发)的事件。

核心事件

Event	Payload	触发时机
ready	{ duration, quality[], subtitles?[] }	播放器 metadata 就绪(subtitles 可选,1.2.0+,ADR-027)
play	{}	开始播放
pause	{}	暂停
ended	{}	播放结束
timeupdate	{ time, duration }	播放进度更新(~250ms;直播 duration 为 0)
volumechange	{ volume, muted }	音量或静音变化
seeking	{ time }	开始 seek
seeked	{ time }	seek 完成
waiting	{}	缓冲开始(卡顿)
playing	{}	缓冲结束,继续播放
progress	{ buffered: TimeRange[] }	缓冲区间更新
qualitychange	{ level, auto }	清晰度变化(auto=ABR 自动切)
subtitlechange	{ id: number | null }	字幕轨切换(null=已关闭;无 auto,字幕无 ABR)。1.2.0+(ADR-027)
error	PlayerError	错误发生
autoplayblocked	{}	自动播放被拒
reconnectstart	{ attempt, maxAttempts, reason?, nextDelayMs? }	开始重连
reconnectsuccess	{ attempts }	重连成功
reconnectfailed	{ attempts, reason? }	重连失败(用满 maxRetries)
compatwarning	{ code, message, ua }	兼容性警告
stalled	{ phase, position, durationMs? }	测量过的卡顿(HealthMonitor;phase=start/end,end 带 durationMs)。1.1.0+

事件名全小写连写(对齐 HTML5 媒体事件),是 wire 上的名字;消费面各自映射 ——Vue emit time-update,React prop onTimeUpdate。

stalled vs waiting/playing:后两者是 HTML5 裸事件透传(只有开始/结束瞬间、 不带测量、测不到冻帧型隐性卡顿);stalled 是 HealthMonitor 测量后的结果,phase='end' 带 durationMs 供埋点算卡顿率。冻结后 1.1.0 minor 新增(ADR-026),受 consent.analytics 门控。

subtitlechange + setSubtitle + ready.subtitles 是字幕控制侧闭环(冻结后 1.2.0 minor, ADR-027),镜像 quality 的 qualitychange/setQuality/ready.quality。字幕菜单 UI 归团队层 (同 QualityMenu),SDK 只暴露轨道 + 切换命令 + 渲染引擎(xgplayer TextTrack,isShowIcon:false)。

详细说明

权威来源:packages/protocol/src/events.ts(Zod schema)+ ARCHITECTURE.md § 8.4。