From 34061892efff1270414df18d19bb7a8d99e5e48c Mon Sep 17 00:00:00 2001
From: xiaosi <2652281683@qq.com>
Date: Thu, 3 Sep 2026 10:43:14 +0800
Subject: [PATCH] docs: add live playback stabilize design

Frontend-only plan to reduce dock live stutter/reconnect: normal HLS
config, longer startup 404 window, tighter play-url rebuild policy.
---
 ...26-09-03-live-playback-stabilize-design.md | 111 ++++++++++++++++++
 1 file changed, 111 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-09-03-live-playback-stabilize-design.md

diff --git a/docs/superpowers/specs/2026-09-03-live-playback-stabilize-design.md b/docs/superpowers/specs/2026-09-03-live-playback-stabilize-design.md
new file mode 100644
index 0000000..d05e584
--- /dev/null
+++ b/docs/superpowers/specs/2026-09-03-live-playback-stabilize-design.md
@@ -0,0 +1,111 @@
+# 监控直播播放稳定（卡顿 / 花屏 / 重连）
+
+日期：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 / 部署