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

日期：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 / 部署