hud-8: keep the libass loop alive across XR entry; auto dual/mono subtitles

ADDENDUM 9 — two independent defects found on device.

1. VR subtitles froze on whatever line was on screen when the session started.
   Jellyfin 12.x renders with SubtitlesOctopus, which starts ONE long-lived rAF
   loop when the video loads; entering immersive-vr stops native rAF and destroys
   the callback still pending in the native scheduler, and because the instance's
   rafId stays non-zero it is never restarted (measured live: rafId=1150 native,
   oneshotState.eventStart frozen ~7 min behind the playhead, zero oneshot-render
   requests). The broker now ALWAYS queues rAF (native driver outside XR, rVFC +
   50 ms idle fallback inside), keeps exactly one native callback in flight, and
   no longer clears the queue at session start. A first version re-armed during
   the drain and doubled the driver every frame, freezing the page; that is now
   fixed and locked down by a Node harness (maxConcurrentNative = 1 over 300
   frames, self-rescheduling loop survives a simulated session start).

2. Only dual-eye ASS subtitles worked; a normal subtitle (e.g. the CN SRT track)
   is centred across the whole 2:1 frame and was cut at the eye seam because the
   HUD always sampled the left half. state.subLayout ('auto'|'dual'|'mono',
   default auto, persisted, panel row) plus per-sample detection: seam ink -> mono,
   one half only -> dual/mono, both halves with an empty seam -> column-profile
   copy test. Dual-eye is NOT a pixel mirror (same text at mirrored positions, no
   glyph flip): measured dual copy distance 0.02-0.08 vs mono 1.00, seam ink
   0 vs 50. M.eyeW (half for dual, full for mono) replaces the hard-coded halfW.

Docs: INTERFACES.md ADDENDUM 9, HANDOFF.md §13 (including the Jellyfin service
worker cache trap that made the first deploy look like a no-op).

The final build was not re-checked in the headset: the device left the worn state
mid-verification and the browser could not be relaunched. Verified on device: the
loop survives XR (rafId in the plugin range, eventStart tracking, subUploads 4->7
over 20 s in VR) and the layout metrics above; the final decision wiring is
covered by the offline suites.
This commit is contained in:
2026-10-12 16:32:25 +08:00
parent 7f751b7eee
commit 164d692791
6 changed files with 697 additions and 114 deletions
+82 -4
View File
@@ -1,10 +1,13 @@
# Jellyfin Web VR180 — 项目交接文档
> 给新对话用。读完这份就能接手,不需要重新调查环境。
> 最后更新:已部署版本 `5217a3`(`NS.version = hud-7`;ADDENDUM 6 字幕深度/大小解耦
> + 7 唤出门限/前面板精简 + 7b 锁按钮与「锁定」面板模式 + 8/8b 画面搬迁(实时拖动))
> 已在 Quest 浏览器里实机验证模块加载 + 锁定数学(`subLockAngle/subAngleDeg`,`errors: []`);
> **VR 会话内的观感还没看过**。
> 最后更新:已部署版本 `b9c3a5`(`NS.version = hud-8`;ADDENDUM 6 字幕深度/大小解耦
> + 7 唤出门限/前面板精简 + 7b 锁按钮与「锁定」面板模式 + 8/8b 画面搬迁(实时拖动)
> + 9 rAF 代理修复(VR 内字幕不再冻结)+ 普通/双目字幕自动识别)
>
> ⚠️ **Jellyfin web 注册了 service worker**(`serviceworker.js`,scope `/web/`),会把
> `index.html` 缓存在 SW cache 里。重新部署后如果只是普通刷新,浏览器可能仍用旧的
> `index.html`(于是继续加载旧的 `?v=` 包)。必须清 SW + 清 cache + 硬刷新,见 §13。
---
@@ -410,6 +413,7 @@ pressAt 上次按压命中/未命中
handsReady / handsErr / handsSources / handsFrames
subMode / subCanvasSize / subCrop / subTex / subOpacity / subPlacement
subLockAngle / subAngleDeg / subTextDeg / subYOverZ ← ADDENDUM 6
subLayout / subDual / subEyeW / subCopyND / subCenterInk ← ADDENDUM 9
ctlSubsOn / ctlSubDist / ctlSubAngle / ctlSubLock ← 控制条实际画出的值
ctlLock / ctlMode / ctlHold / pressAt / lastActivate ← ADDENDUM 7/7b 锁、面板保持与唤出判定
videoYaw / videoPitch / videoRotMode / videoTransformWritable ← ADDENDUM 8/8b 画面搬迁
@@ -491,3 +495,77 @@ errors[] 最近错误
**手势**(按你的要求):`点一下复位 · 按住 0.5s 再拖动`。拖动基准取"按住满 0.5s 那一刻"的射线,
不是按下那一刻——否则那半秒会把手抖放大成甩动。1° 死区防抖。
---
## 13. ADDENDUM 9 — 字幕「中断」与普通字幕(已部署 `b9c3a5` / `hud-8`)
### 13.1 定位手法(下次直接复用)
- **连设备**:`./quest.sh`(它的授权检测偶尔误判,失败就手动
`adb forward tcp:9222 localabstract:chrome_devtools_remote`)。
- **读 SubtitlesOctopus 实例**:Jellyfin 12.x 的实例在播放器的闭包里,用 CDP 的
`getEventListeners(video).timeupdate[i].listener` → `[[Scopes]]` → 找带
`oneshotState`/`renderedItems` 的对象。本机脚本见 `/tmp/inst.py`、`/tmp/scan.py`
(一次性工具,未入库)。关键字段:`rafId`(我们的是 1e9 起)、
`oneshotState.eventStart`(当前画的那一行)、`renderRequested`。
- **量 libass 画布**:把 `canvas.libassjs-canvas` 画进小 canvas 取 `getImageData`,
统计左右半屏/中线的墨迹与列轮廓(`/tmp/prof.js`、`/tmp/mirror*.js`)。
- **OCR**:`adb exec-out screencap -p` + `tesseract -l chi_sim`(双脚同屏也能读)。
本次就是靠它确认 HUD 停在 15:45 的台词而视频已在 22:49。
### 13.2 问题一:VR 内字幕冻结(不是「被截断」)
- 现象:进 VR 后字幕永远停在进 VR 前那一帧。实测 `rafId=1150`(**原生** id)、
`oneshotState.eventStart=945.99`(落后播放头约 7 分钟)、整段播放 **0 个**
`oneshot-render` 请求。
- 根因:进入 `immersive-vr` 后原生 rAF 完全停摆。SubtitlesOctopus 在主线程起了**一个
常驻 rAF 循环**(`k`):它负责把 worker 预渲染好的帧画到 canvas、并继续要下一帧。
旧代理只在「已进入 XR」后才接管 rAF,于是**进 XR 那一刻还挂在原生调度器里的那个
`k` 回调被销毁**;而 `i.rafId` 仍非 0,`resetRenderAheadCache` 也不会重启它 → 整个
prerender 链断掉。
- 修复(`src/90-main.js`):rAF 代理**始终**接管(非 XR 用原生 rAF 泵,XR 用 rVFC),
且原生泵**单飞**(`nativeRafStep` 先续期再 drain,队列空则 cancel);`startRafPump`
**不再 clear 队列**(那个回调就是要救的);加 50ms 兜底,暂停/卡住时也能重画。
- ⚠️ **踩过的坑**:第一版原生泵在 drain 期间把 `nativeId` 置空,每个自续期回调都会额外
再排一个原生 rAF → 回调数**指数增长**,直接把页面主线程打爆(CDP 无响应)。现在由
Node 单测固定:自续期循环 300 帧 `maxConcurrentNative = 1`。
### 13.3 问题二:只支持双目 ASS,普通字幕被截断
- 根因:旧代码硬编码只取画布**左半屏**。双目 ASS(`CN_dual_eye`,PlayRes 3840×1920,
LeftEye/RightEye 各占半屏)没问题;普通字幕(`CN` 的 SRT,居中跨整幅)文字中心正好
压在画布中线(两眼接缝)上,于是只剩左半边 → 看起来「断掉」。
- 修复(`src/10-subtitles.js`):新增 `state.subLayout`(`auto`/`dual`/`mono`,默认
`auto`,面板有「字幕布局」一行,持久化)。每次采样统计左右半屏 + 中线 ±40px 的墨迹:
中线有墨 → 普通;只有左半 → 双目;只有右半 → 普通;两半都有且中线空 → **列轮廓平移
匹配**(`columnCopyND` < 0.25 → 双目)。布局切换做 2 帧去抖。
- **血泪教训:双目字幕不是像素镜像**。左右眼是**同一段文字放在对称位置**,字形不翻转,
所以 `left[x] vs right[W-1-x]` 完全对不上(实测均值差 258/1020)。我第一版就是被这个
骗了,把双目误判成普通(HUD 于是把两只眼的字并排显示)。真正成立的是**列轮廓**:
实测双目 `0.02–0.08`、普通 `1.00`、中线墨迹 双目 `0` / 普通 `50`。
- `M.eyeW`(单眼区域宽度:双目=半幅、普通=整幅)替换了原来写死的 `halfW`。
### 13.4 部署缓存陷阱(为什么第一次改了「没生效」)
Jellyfin web 注册了 **service worker**,`index.html` 会被缓存。只普通刷新时浏览器可能
仍用旧 `index.html` → 继续请求旧的 `jfvr-mvp.js?v=5217a3`。清理脚本(一次性的):
```js
for (const r of await navigator.serviceWorker.getRegistrations()) await r.unregister();
for (const k of await caches.keys()) await caches.delete(k);
// + Network.clearBrowserCache + Page.reload{ignoreCache:true}
```
验证新包是否真的加载:`document.querySelector('script[plugin="JellyfinVR"]').getAttribute('src')`
与 `window.__JFVR.version`(应为 `hud-8`)。
### 13.5 待验证 / 本次未完成
- 最终版(`b9c3a5`,`COPY_TOL=0.25`)**还没在头显里跑过**:验证到一半设备进入未佩戴 /
Guardian 状态,Oculus 浏览器无法再拉起(`ps` 无进程、无 devtools socket)。已完成的实机
证据:broker 修复(`rafId` 落在插件区间、`eventStart` 跟随、VR 内 `subUploads` 4→7)、
以及两个布局的**真实量测值**。最终判据是离线单测(真实源码 `columnCopyND`)验证的。
- 下次戴上头显后要确认:`stats.subLayout=auto`、双目轨 `subDual=true/subEyeW=2160/
subCrop` 落在左半屏(≤2160)、普通轨 `subDual=false/subEyeW=4320/subCrop` 跨中线、
`subCopyND` 与 `subCenterInk` 是否符合上面的表。