laic-frontend/docs/superpowers/specs/2026-09-03-live-playback-stabilize-design.md

监控直播播放稳定（卡顿 / 花屏 / 重连）

日期：2026-09-03
状态：已确认（待写实现计划）
范围：仅前端 laic-frontend

1. 背景与证据

dock-1 现网可开播、可出 HLS 分片，但观感为卡顿 / 花屏 / 经常重连。API + 拉流实测要点：

1. join 后约 8–12s 到 phase=streaming，deviceStreaming=true，cloudOnline=true。
2. GET /play-url 现网返回 http://vpull.jiagutech.com/...m3u8（本地后端源码期望 https://）。
3. https://vpull.jiagutech.com TLS handshake failure（无 peer certificate）；站点本身也是 HTTP。
4. 刚进入 streaming 时 m3u8 常先 404，数秒后才有清单；首份清单常见 #EXT-X-DISCONTINUITY。
5. 分片时长约 5.9s–12s，TARGETDURATION 9–12 —— 普通 HLS，不是低延迟流。
6. 前端 LivePlayer 当前：lowLatencyMode: true，fragLoadingMaxRetry: 1，启动 404 窗口约 15s。
7. join 后立刻 heartbeat 偶发 57006（租约不存在或已过期），前端会 rejoinAfterLeaseInvalid → 整段重开。

用户确认：能出画面，但卡顿 / 花屏 / 经常重连。本轮只改前端。

2. 目标

1. 启动更稳：streaming 后短时 404 不直接失败；允许「等待流就绪」后出画。
2. 播放中少重建：普通分片抖动 / 短暂网络错尽量在播放器内恢复，避免动辄 refreshPlayURL → 整实例重建。
3. 保留明确致命路径：TLS / CORS / 403 仍明确失败，不瞎刷 play-url。

3. 非目标

• 不改后端租约实现、stop grace、阿里云证书 / 播流域名。
• 不把 http:// playUrl 强改 https://（现网 https 不可用，改写会更糟）。
• 不改 Media 页、多路同屏、WebRTC / FLV。
• 不改停止确认框、join busy 重试等已合并行为（仅回归验证）。

4. 方案（稳播优先）

职责不变：LivePlayer 管媒体；useMonitorLive 管会话 / 租约 / play-url 续期。

4.1 LivePlayer.vue

1. new Hls 配置改为普通直播友好：
   • lowLatencyMode: false
   • manifestLoadingMaxRetry: 2
   • levelLoadingMaxRetry: 2
   • fragLoadingMaxRetry: 4
   • 为上述重试设置合理 delay（与 hls.js 默认同量级即可，避免 0 间隔打爆 CDN）
2. 启动 404 / manifest 未就绪窗口加长：
   • 现：STARTUP_RETRY_DELAYS_MS = [500,1000,2000,4000]，STARTUP_WINDOW_MS = 15_000
   • 改：[500,1000,2000,4000,6000,8000]，STARTUP_WINDOW_MS = 30_000
   • 行为不变：窗口内同 URL 退避重建，不请求 /play-url
3. 错误分级：
   • TLS / CORS / certificate / mixed content → SecurityError fatal（已有）
   • HTTP 403 → fatal（已有）
   • 启动窗口内 404 / MANIFEST_LOAD_ERROR → 同 URL 重试；耗尽再 fatal
   • 其它 fatal：若 hls 提供 recoverMediaError 且错误类型适合，先尝试一次自愈；仍失败再 emit('error')
4. AbortError / NotAllowedError / 用户手势恢复路径保持不变。

4.2 useMonitorLive.js

1. onPlayError 收敛：
   • AbortError / NotAllowedError：忽略（已有）
   • recoverable === true：忽略（已有）
   • 57006：仍 rejoinAfterLeaseInvalid()
   • TLS / 403：markPlayFatal，不 refreshPlayURL（已有）
   • 启动耗尽后的 HlsError（含持续 404）：markPlayFatal（已有语义）
   • 其余非致命媒体错：仅在 LivePlayer 明确 fatal 且非 TLS/403 时，有限次 refreshPlayURL（保留 PLAY_RETRY_MAX = 3，fromRetry: true 不重置计数）
2. 不改本轮：
   • 心跳调度公式（仍约 lease/2）
   • phase 轮询间隔 / 超时
   • stop / leave / join busy 重试

4.3 文件

文件	变更
src/components/LivePlayer.vue	HLS 配置、启动窗口、有限自愈
src/composables/useMonitorLive.js	onPlayError 注释与分支收紧（行为按上表）
本 spec	设计文档

5. 错误处理（汇总）

情况	处理
启动期 m3u8 404	LivePlayer 同 URL 退避；不刷 play-url
播放中 frag 短暂失败	hls 重试 / recover；不立刻 rebuild
playUrl 临期	仍按 expiresAt - 30s 续期（已有）
57006	leave 本地态后重新 join
TLS / 403	toast 明确原因；停止刷 URL
启动窗口耗尽仍失败	toast 播放失败；保留会话心跳与否沿用现逻辑（markPlayFatal 清 playUrl，不强制 leave）

6. 验收

对 dock-1（或同等可推流机巢）：

1. 打开直播：可出现短暂「正在等待直播流就绪」，最终出画；不因首包 404 直接失败。
2. 连续播放约 1–2 分钟：无明显「整段黑屏闪断式」频繁重建。
3. 停止弹窗点取消：只关弹窗，不 POST /stop（回归）。
4. 人为 TLS/403 类错误（若可模拟）仍提示致命信息，不循环刷 play-url。
5. npm run build 通过。

7. 风险与后续

• 证书 / http playUrl：站点若日后上 HTTPS，现网 http 拉流会 Mixed Content；需后端改回 https 并修复 vpull 证书。不在本轮。
• 57006 根因：属后端租约时序；前端 rejoin 是兜底，可能仍偶发一次重开。
• 上行抖动：机巢 / SRT 断续导致的 DISCONTINUITY 无法单靠前端消除，只能降低播放器过激反应。

8. 实现顺序

1. 改 LivePlayer HLS 配置 + 启动窗口
2. 收紧 onPlayError 注释 / 分支（若代码已基本符合则只补缺口）
3. build + 现网 dock-1 冒烟
4. commit / 部署