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.
572 lines
30 KiB
Markdown
572 lines
30 KiB
Markdown
# Jellyfin Web VR180 — 项目交接文档
|
||
|
||
> 给新对话用。读完这份就能接手,不需要重新调查环境。
|
||
> 最后更新:已部署版本 `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。
|
||
|
||
---
|
||
|
||
## 1. 项目目标
|
||
|
||
给 Jellyfin Web 播放页注入插件,让 **Meta Quest 3 浏览器**能直接播放内网 Jellyfin 里的
|
||
**VR180 立体视频**,不用手动切全屏、选投影。在网页里点「VR 播放」→ 选格式 → 进 VR。
|
||
|
||
---
|
||
|
||
## 2. 环境事实(已核实,不用重查)
|
||
|
||
### 2.1 服务器
|
||
|
||
| 项 | 值 |
|
||
|---|---|
|
||
| 主机 | `192.168.123.199`(fnOS NAS,CW8505fnOS,Intel Pentium Gold 8505 + UHD 核显) |
|
||
| **SSH** | `admin` / `<NAS 密码>`(密码不写进仓库,见 §2.1.1) |
|
||
| Jellyfin | **12.1.0**,Docker 容器名 `Jellyfin`,`jellyfin/jellyfin:latest` |
|
||
| 配置目录 | `/vol2/jellyfin/config` |
|
||
| web 目录(注入点) | 容器内 `/jellyfin/jellyfin-web/` |
|
||
| 备份 | `/vol2/jellyfin/config/_vr_backup/index.html.orig` |
|
||
| 反向代理 | Traefik v3.0(`http://192.168.123.199:8080/api/rawdata` 可读配置) |
|
||
|
||
#### 2.1.1 密码怎么取
|
||
|
||
**仓库里不存密码。** 真实密码在本机一个被 `.gitignore` 忽略的文件里:
|
||
|
||
```
|
||
secrets.local.md # 不入库,只存在于开发机
|
||
```
|
||
|
||
`deploy.py` 也只从环境变量 `JF_PW` 读,代码里没有硬编码。换机器时要么把那份
|
||
`secrets.local.md` 拷过去,要么手动 `export JF_PW=...`。
|
||
|
||
### 2.2 两个访问入口(关键区别)
|
||
|
||
| 入口 | 安全上下文 | WebXR | 速度 |
|
||
|---|---|---|---|
|
||
| **`https://jellyfin.cat-shark.xyz`** | ✅ | **直接可用,零配置** | **IPv6 局域网直连,实测 700 Mbps,TTFB 7–12ms** |
|
||
| `http://192.168.123.199:8096` | ❌ | ❌ 需每台设备在 Quest 浏览器 `chrome://flags` 里启用 `unsafely-treat-insecure-origin-as-secure` 并填该地址 → Relaunch | 内网 |
|
||
|
||
> **推荐一律用 HTTPS 域名。** 该域名的 IPv6 AAAA 记录就是 NAS 自己的局域网地址
|
||
> (`2409:8a14:44a:e360:520:8aa2:7736:4f12`),Quest 与 NAS 在同一个 /64,纯内网直连。
|
||
> IPv4 的 A 记录 `39.105.149.197` 是阿里云中转(NAS 上跑着 `npc` 内网穿透客户端),走 IPv4 才慢。
|
||
|
||
### 2.3 Quest 3
|
||
|
||
| 项 | 值 |
|
||
|---|---|
|
||
| 系统 | Android 14 (SDK 34),build `UP1A.231005.007.A1` |
|
||
| 浏览器 | **`152.1.0.34.52.1079628208`**(Chromium 152.0.7977.83) |
|
||
| 无线 ADB | `192.168.123.229:34485`,由 SideQuest 维持 |
|
||
|
||
**ADB 与 CDP 通路:**
|
||
|
||
```bash
|
||
ADB=/opt/SideQuest/resources/platform-tools/adb # SideQuest 自带的 adb
|
||
$ADB devices -l # 确认设备在线
|
||
$ADB forward tcp:9222 localabstract:chrome_devtools_remote
|
||
curl -s http://127.0.0.1:9222/json/version # 确认 CDP 通
|
||
```
|
||
|
||
项目里有 `quest.sh` 一键做上面这些。拿到 9222 后用 `agent_browser --cdp http://127.0.0.1:9222` 接管 Quest 浏览器。
|
||
|
||
> ⚠️ **CDP 转发会被无线 ADB 重置**,断了就重跑 `quest.sh`。
|
||
|
||
**截图与「看」画面:**
|
||
```bash
|
||
$ADB exec-out screencap -p > shot.png # 4128x2208,双眼并排合成输出
|
||
tesseract shot.png - -l chi_sim --psm 6 # OCR 可读中文
|
||
```
|
||
> ⚠️ 当前模型**看不到图片**,只能靠 OCR + 像素统计 + 差分分析。
|
||
|
||
---
|
||
|
||
## 3. 片源
|
||
|
||
```
|
||
61+ 个 VR180 文件,全部:
|
||
8192 x 4096 | HEVC Main / level 6.1 | ~60 fps | 8–25 Mbps | .mp4 (faststart)
|
||
```
|
||
|
||
即 **VR180 SBS**,每眼 4096×4096 的 180° 等距柱状。
|
||
|
||
**字幕文件是天生的双目设计**(853 部是这样的):
|
||
|
||
```
|
||
Title: VR Dual-Eye Subtitle
|
||
PlayResX: 3840 PlayResY: 1920 ← 2:1,与视频同比例
|
||
Style: LeftEye , Alignment=8, MarginL=50 , MarginR=1920, MarginV=700
|
||
Style: RightEye, Alignment=8, MarginL=1920, MarginR=50 , MarginV=700
|
||
```
|
||
|
||
左半屏=左眼、右半屏=右眼,正好匹配 `stereo-left-right`。
|
||
|
||
> ⚠️ **必须保持 DirectPlay。** Pentium 8505 + UHD 核显编不了 8K(Alder Lake-N 编码上限约 4K),
|
||
> 一旦 Jellyfin 转码,分辨率腰斩且 CPU 打满。
|
||
|
||
---
|
||
|
||
## 4. Quest 3 实测能力(真机数据)
|
||
|
||
| 能力 | 结果 |
|
||
|---|---|
|
||
| `isSecureContext` / `navigator.xr`(HTTPS 下) | true / true |
|
||
| `immersive-vr` | **true** |
|
||
| `XRMediaBinding.createEquirectLayer` | **true** |
|
||
| `XRWebGLBinding.createQuadLayer` | **true** |
|
||
| `XRWebGLBinding.getSubImage` | **需要 2 个参数** `(layer, frame)` |
|
||
| `MAX_TEXTURE_SIZE` / `MAX_RENDERBUFFER_SIZE` | **8192 / 16384** |
|
||
| 8K HEVC `decodingInfo` | `supported:true, powerEfficient:true` |
|
||
| `supportedFrameRates` | **[72, 80, 90, 120]** |
|
||
| `enabledFeatures` | `[local, viewer, bounded-floor, layers, hand-tracking, webxr, local-floor]` |
|
||
| 手部追踪 | ✅ 25 关节齐全,profiles `["oculus-hand","generic-hand","generic-hand-select","generic-trigger"]` |
|
||
| **眼动追踪** | ❌ **Meta 不向 WebXR 暴露** |
|
||
|
||
---
|
||
|
||
## 5. 架构
|
||
|
||
```
|
||
jelllyfin_vr_web_plugin/
|
||
├── INTERFACES.md ← 绑定契约(所有模块必须遵守)+ 5 个 ADDENDUM
|
||
├── README.md ← 技术记录(含全部实测数据)
|
||
├── HANDOFF.md ← 本文档
|
||
├── src/
|
||
│ ├── 00-core.js (353 行) 命名空间、共享状态、GL 助手、层/帧钩子注册表、能力探测
|
||
│ ├── 10-subtitles.js (1022 行) 字幕:libass 画布 → 头锁定 quad 层(HUD)+ 视角尺寸锁定
|
||
│ ├── 20-controls.js (2078 行) 控制面板:拖动条/进度条/按钮/光束/光标/锁,canvas 2D → quad 层
|
||
│ ├── 30-hands.js (569 行) **系统手部模型**:Three.js + 官方 generic-hand GLB → projection 层
|
||
│ └── 90-main.js (1641 行) 引导、会话生命周期、rAF 代理、输入分发、设置面板、持久化、画面搬迁
|
||
├── build.py ← src/*.js 按文件名顺序拼接 → dist/jfvr.js;`--check` 只做语法检查
|
||
├── deploy.py ← 构建 + 上传进容器 + 注入 script 标签;`rollback` 还原
|
||
├── quest.sh ← 一键重连 Quest 的 ADB + CDP 转发
|
||
├── dist/jfvr.js ← 构建产物
|
||
└── legacy/jfvr-mvp-v6-working.js ← 早期验证可用的单文件版(回退用)
|
||
```
|
||
|
||
### 5.1 层栈(**顺序即合成顺序,后的在上**)
|
||
|
||
```
|
||
video equirect XRMediaBinding.createEquirectLayer, 180°, stereo-left-right
|
||
hands projection Three.js 渲染官方手模型(手动渲染循环,不占 baseLayer)
|
||
subtitles quad viewer 空间,头锁定,自动裁剪墨迹包围盒
|
||
controls quad local 空间,固定位置 (0,-0.34,-1.45),身份旋转
|
||
```
|
||
|
||
> ⚠️ **Three.js 不能接管 XR 会话**:`renderer.xr.setSession()` 会设 `baseLayer`,
|
||
> 与 `layers` 数组冲突。所以手模型走**手动渲染循环**(自建 projection layer、
|
||
> 自绑帧缓冲、自遍历 view 设投影矩阵)。
|
||
|
||
### 5.2 关键 API
|
||
|
||
```js
|
||
__JFVR.addLayer(layer) / removeLayer(layer) // 层注册表,自动推 updateRenderState
|
||
__JFVR.addFrameHook(fn) / removeFrameHook(fn) // fn(frame, time, session) 每 XR 帧
|
||
__JFVR.state // 共享状态;window.__JFVR_STATE__ 也是它(供 CDP 读取)
|
||
__JFVR.stats // 诊断信息,全部落在 state.stats
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 关键技术发现(**血泪教训,不要重犯**)
|
||
|
||
### 6.1 `window.requestAnimationFrame` 在 XR 会话中完全停摆
|
||
|
||
```
|
||
实测:6 秒内 0 次回调
|
||
timeupdate : 22 次 ✅
|
||
requestVideoFrameCallback : 288 次 ✅
|
||
```
|
||
|
||
Jellyfin 用 rAF 渲染 libass 字幕 → **进 VR 后字幕画布冻结在最后一帧**。
|
||
**解法**:90-main.js 劫持 `requestAnimationFrame`,XR 中把回调收进私有队列,
|
||
用 `video.requestVideoFrameCallback` 驱动;不在 XR 时透传原生实现。
|
||
|
||
### 6.2 帧率不匹配导致"卡顿"
|
||
|
||
59.94fps 视频 + 90Hz 会话 = **1.5 倍** → 每帧交替显示 1/2 次 = 3:2 pulldown 抖动。
|
||
**解法**:`session.updateTargetFrameRate(120)`(120/60 = 2 整除)。
|
||
实测 87.9 → 114.9 fps,20 秒稳定、丢帧 0.000%。
|
||
|
||
### 6.3 libass 画布必须在**进入 VR 之前**放大
|
||
|
||
libass 按屏幕视频框尺寸渲染(约 1250×708 = **3.5 px/度**,糊)。
|
||
**XR 会话运行期间 libass 不重算画布尺寸**,所以放大动作挂在「打开 VR 面板」这个点击上。
|
||
实测放大到 **4320×2160**(libass 封顶)。
|
||
|
||
**踩过的坑**:退出 VR 时如果还原尺寸,而面板还开着,再进 VR 就不会重新放大 → 字幕糊。
|
||
现在:面板开着就不还原。
|
||
|
||
### 6.4 quad 的局部 `-Z` 是**面法线**,不是轴向
|
||
|
||
想在光束朝向里把 `-Z` 对齐射线是**错的** —— 会让平面垂直于射线、`width` 横在射线上,
|
||
看到的是一条正对眼睛的细横条。正确:**`+X`(长轴)对齐射线**,`-Z` 与射线垂直。
|
||
|
||
### 6.5 单条平面条带沿视线方向时**必然侧对** → 十字双条带
|
||
|
||
光束指向"远离你"的方向时,任何包含光束轴的平面都包含视线方向 → 侧对 → 投影宽度趋零。
|
||
实测有效宽度只剩 `cos(68.7°) = 0.36` 倍 ≈ 2mm ≈ **3 像素,等于隐身**。
|
||
**解法**:**两条正交条带**(第二条绕光束轴转 90°),`max(cosθ, sinθ) ≥ 0.707` 恒成立。
|
||
|
||
### 6.6 手部 `targetRaySpace` 是**模拟射线**
|
||
|
||
Meta 官方文档原文:
|
||
|
||
> the `targetRaySpace` for hands is populated with an **emulated ray** that matches the
|
||
> behaviors of the pointing ray of hands present in **Meta Horizon Home**, which assumes
|
||
> that the UI is in front of the user, so the target rays will **always point in that
|
||
> general direction**
|
||
|
||
- **优点**:系统做了**稳定化**,落点平稳
|
||
- **缺点**:不跟手指
|
||
|
||
> ❌ 我一度改成用食指关节自己算射线 → **指尖逐帧抖动直接传导到落点,明显比系统射线不稳**。
|
||
> **默认必须用系统射线。** 面板里留了「手部指向:系统射线 / 食指」开关供切换。
|
||
|
||
### 6.7 `requestSession()` 必须**同步**写在点击处理里
|
||
|
||
WebXR 规范:需要 *transient activation*。前面不能有 `await`,否则被拒。
|
||
实测用 `element.click()` 从 CDP eval 调用会失败(`The requested session requires user activation`),
|
||
但用 `agent_browser click` 可以(CDP 输入事件算用户手势)。
|
||
|
||
### 6.8 `frame.getPose()` 的结果**只对该帧有效**
|
||
|
||
反复读同一个旧 `XRFrame` 会一直返回缓存值 —— 我因此误判过"射线冻结"。
|
||
**采样必须在帧循环内做。**
|
||
|
||
### 6.9 其余坐标陷阱
|
||
|
||
- 面板带 yaw 旋转后,"平面垂直于局部 z 轴"的假设失效 → `panelHit` 必须
|
||
**把射线变换到层自身空间**再求交(含四元数旋转/共轭/姿态合成)
|
||
- 字幕层在 **viewer 空间**而指针射线在 **local 空间** → 两者不同坐标系,必须转换
|
||
|
||
### 6.10 系统保留手势
|
||
|
||
**掌心肌肤捏合**(palm pinch)是系统保留:左手 = 菜单键,**会直接退出会话**。
|
||
只能用普通点捏。
|
||
|
||
### 6.11 面板“一捏就弹”有两个独立原因(ADDENDUM 7)
|
||
|
||
只修 `pointerDown` 里的 `show()` 不够——`selectstart` 监听里也有一句无条件 `show()`。
|
||
两处删掉后才真的变成“指哪儿弹哪儿”。另外**唤出那一下不算点击**,否则手从远处
|
||
扫到面板的路径上会顺手碰到一个按钮。
|
||
|
||
### 6.12 锁按钮为什么一度做成了独立图层(错误,已改回)
|
||
|
||
第一版把锁做成了控制条右侧的**独立 quad 图层**(x=+0.45),实测选不中。教训:
|
||
|
||
- **能用手的射线扫到的范围 = 光标自己的容差窗口**(`panelHit` 对 0.72m 面板用
|
||
0.25/0.6 → 只能到 x≈0.45,即面板右边缘)。放在更外面就是**任何射线都到不了**。
|
||
- 锁的命中检测当时用的是**面板的图层几何**,所以“面板显示时点不中、隐藏时能点中”——
|
||
行为随面板尺寸变化。
|
||
|
||
正确做法:锁就是**面板上的一个普通按钮**(`lock` 动作),走光标→hitTest→handleSelect
|
||
→onAction 这条已验证能用的路。锁定后切到第三种面板模式 `locked`(0.26×0.10),
|
||
**只画锁、只命中锁**。
|
||
|
||
### 6.13 「头部锁定」的东西永远瞄不到
|
||
|
||
“VR 空间右侧边缘”听起来像视野边缘的头锁定 HUD,但这个项目**只能用手的射线**指向
|
||
(手柄连不上)。头锁定元素的相对角度永远不变,射线**永远追不上它**,所以任何可点的
|
||
元素都必须和控制条在同一个 `refSpace` 里。
|
||
|
||
---
|
||
|
||
## 7. 当前状态(部署 `8ae73b`)
|
||
|
||
### 7.1 可用
|
||
|
||
| 功能 | 状态 |
|
||
|---|---|
|
||
| VR180 立体播放 | ✅ DirectPlay 8K HEVC,120Hz,~112 fps |
|
||
| 字幕 HUD(头锁定 quad) | ✅ 自动裁剪墨迹包围盒、双目半屏提取 |
|
||
| 控制面板(fixed 位置) | ✅ 进度条/播放暂停/±10s/字幕开关/字号±/透明±/复位 |
|
||
| 中文按钮标签 | ✅ |
|
||
| 引导线(十字双光束) | ✅ 任何时候都显示 |
|
||
| 面板唤出门限 | ✅ 只有指示线指向/靠近面板时才唤出;唤出那一下不算点击;500ms 内忽略 |
|
||
| 锁按钮(面板不启动) | ✅ 面板媒体行的第五个按钮:上锁后切到「只显示锁」的最小面板,并同样自动隐藏;每次进 VR 重置为未锁 |
|
||
| 画面搬迁(180°窗口) | ✅ 面板进度条上方的拖动条:按住 0.5s 后拖动 = 搬画面;点一下 = 复位;每次进 VR 回正前方 |
|
||
| 按压反馈 | ✅ 圆环放大 1.9× + 蓝填充 + 变白,300ms |
|
||
| 字幕抓拖 | ✅ 注视选中 + 手移动拖(与视线解耦,避免转头就飘) |
|
||
| 字幕深度/大小解耦 | ✅ 默认「锁定视角尺寸」:拉近/拉远只改深度,视角大小与画面位置不变 |
|
||
| VR 内「近/远」字幕按钮 | ✅ 控制条字幕行现为 9 键:上 下 近 远 小 大 暗 亮 复位 |
|
||
| 字幕行题注显示距离 | ✅ `字幕 距1.45m · 69°`(距离永远是第一个数字,便于和物体对深度) |
|
||
| 字幕 CC 按钮状态 | ✅ 开=蓝底+`字幕开`,关=斜杠 CC+`字幕关` |
|
||
| 设置持久化 | ✅ localStorage `jfvr.settings.v1` |
|
||
| 系统手模型 | ✅ 官方 `generic-hand` GLB,Three.js 渲染,帧率无损失 |
|
||
|
||
### 7.2 已知未完成 / 待验证
|
||
|
||
- **锁定角尺寸的默认值还没定** —— 代码默认 69.2°,但头显上已存的是 **85°**
|
||
(之前用面板滑杆设的,ADDENDUM 7 已移除那个滑杆)。要回默认就在 VR 里按几次「小」
|
||
(每次 −5°),或者直接改 localStorage。
|
||
- **ADDENDUM 7/7b 的 VR 手感未验证** —— 唤出灵不灵、锁按钮好不好矒、500ms 合不合适,
|
||
只能戴上去试。模块级冒烟测试已过(见 README ADDENDUM 7b 的 Verification)。
|
||
- **手柄无法连接** —— **系统层问题,不是插件问题**。
|
||
`adb shell getevent -i` 只列出 5 个设备(无任何控制器),WebXR 的 `inputSources`
|
||
也只有双手。需要在头显里检查手柄电量 / 重新配对 / 确认「自动切换」开关。
|
||
- 手模型实际渲染效果**还没在头显里确认**(subagent 交付后只验证了加载成功 `handsReady: true`)
|
||
- 可疑现象:不捏合时 `inputSources` 仍显示左手 `@0`(按钮 0 卡在按下)
|
||
|
||
---
|
||
|
||
## 8. 字幕距离 / 角尺寸 —— 已解决(ADDENDUM 6)
|
||
|
||
### 用户要解决的问题
|
||
|
||
> 当前 vr 视频中可能出现 vr 空间中物体可能距离我很近,如果字幕还很远,我将无法在
|
||
> 看清物体的同时看清字幕。我希望可以让字幕的空间距离和物体的距离尽量接近。
|
||
|
||
Quest 不给 WebXR 眼动(§4),**没法自动跟视线距离**;而且近处物体足够强行的方案是
|
||
让「距离」变成一个**纯深度**旋钮:不管拉到多近,字幕的角尺寸和画面位置都不变。
|
||
|
||
### 实现(默认开启)
|
||
|
||
`state.subLockAngle = true`,`state.subAngleDeg = 69.2`。锁定时拉近/拉远:
|
||
|
||
```
|
||
width = 2 · |z| · tan(subAngleDeg / 2) 保持角尺寸 θ
|
||
y = (y0 / z0) · z 保持角高度 y/z
|
||
```
|
||
|
||
69.2° 就是旧的 `2.0 m @ 1.45 m`,所以**默认观感零变化**。近端限位从 0.5 m 收到
|
||
**0.35 m**。ADDENDUM 7 之后锁**固定在开**(面板里的「距离与大小」开关已按用户要求移除),
|
||
所以不再有「拉近=变大」的自由模式入口。
|
||
|
||
- VR 内控制条字幕那一行现在是 **9 个按钮**:`上 下 近 远 小 大 暗 亮 复位`。
|
||
- `上/下`:垂直位置 ±0.04 m(以前 VR 里只能抓拖,没有按钮)
|
||
- `近/远`:深度 ±0.15 m(锁定下只改深度,角尺寸不变)
|
||
- `小/大`:锁定下视角宽度 ±5°(解锁后是宽度 ±0.15 m)
|
||
- 题注永远先报**深度**:`字幕 距1.45m · 69°`,右边是不透明度。要用它和眼前物体对深度。
|
||
- 顺手修了两个 bug:① 控制条 CC 按钮以前读的是 controls 模块自己的、main 从不写入的
|
||
`S.subtitlesOn`,所以**永远显示为关**——现在改为回退读共享的 `state.subtitles`,
|
||
并把开/关做成蓝底 `字幕开` / 斜杠 CC `字幕关`;② VR 里没有垂直位置按钮(现已补上)。
|
||
2D 面板的「垂直位置」滑杆实测是好的,所以缺的只是 VR 侧。
|
||
- 抓拖在锁定下会把深度位移按抓取起点的 y/z 比例同步到 y,所以拉到很近时字幕
|
||
不会掉到视野下方。
|
||
- 新增诊断 `stats.subTextDeg`:**实际画出来的字幕墨迹角高度(度)**。用它对照
|
||
文献就能定默认 `subAngleDeg`。
|
||
|
||
### 文献结论(保留供参考)
|
||
|
||
核心指标是 **角尺寸(angular size)**= 距离 × 字体大小的组合,不是单独某一个:
|
||
|
||
- *User Experience of Reading in Virtual Reality — Finding Values for Text Distance, Size and Contrast*
|
||
(arXiv 2004.01545,全文表 I 已复现):以 dmm(1 dmm = 1 m 处 1 mm 字高)为单位,
|
||
**中/长文本偏好 16–18 dmm ≈ 0.9–1.0° 字高**,2 词短文本 27–32 dmm ≈ 1.6–1.8°;
|
||
Google 指南:正文/说明 ~15–20 dmm,标题 32 dmm ≈ 1.8°,大标题 40 dmm ≈ 2.3°。
|
||
参与者明确认为**角尺寸过大**是「最差」读数体验之一 → 存在上限。
|
||
- *VR Reading UIs: Assessing Text Parameters for Reading in VR*(Dingler 等,CHI 2018 EA):
|
||
偏好字高 **41 ± 14 dmm ≈ 2.35° ± 0.8°**。
|
||
- *The influence of text rotation, font and distance on legibility in VR*(IEEE VR 2020)
|
||
与 *An effective method for measuring text legibility in XR*(Frontiers in VR 2023,含 Quest 2)
|
||
都用 dmm/角度测最小可读字号,结论同向:可读性由角尺寸决定。
|
||
|
||
上述都是**字高**角尺寸,而本插件的滑杆/参数是**字幕条整幅角宽**,两者靠 `subTextDeg`
|
||
换算。默认值暂不动(保持已调好的观感),等头显实测后再定。
|
||
|
||
### 待办
|
||
|
||
1. 头显里读 `stats.subTextDeg`,若明显偏离 1–2° 再考虑改默认 `subAngleDeg`
|
||
2. (可选)如果实际用下来「近/远」每次 0.15 m 太粗,再加长按连续调整
|
||
|
||
---
|
||
|
||
## 9. 工作流速查
|
||
|
||
```bash
|
||
cd /home/cat/Desktop/myProject/jelllyfin_vr_web_plugin
|
||
|
||
# 语法检查(全部模块)
|
||
python3 build.py --check
|
||
|
||
# 构建 + 部署(自动构建 → 上传 → 注入 script 标签)
|
||
# 密码从环境变量读;真实值放在本地 secrets.local.md(不入库)
|
||
export JF_PW='<NAS 密码>'
|
||
python3 deploy.py
|
||
|
||
# 回滚到原始 index.html
|
||
python3 deploy.py rollback
|
||
|
||
# 部署早期单文件版
|
||
python3 deploy.py --legacy
|
||
|
||
# 重连 Quest 的 ADB + CDP
|
||
./quest.sh
|
||
```
|
||
|
||
**部署后必须让用户刷新页面**(脚本按页面加载缓存,URL 里的 `?r=<md5前6位>` 是破缓存用的)。
|
||
|
||
### 诊断信息
|
||
|
||
页面里「VR 播放」面板 → 展开「诊断信息」,或经 CDP 读 `window.__JFVR_STATE__.stats`。关键字段:
|
||
|
||
```
|
||
layersBuilt 实际建立的层
|
||
fps / targetFrameRate
|
||
pointer 当前瞄准源与命中坐标
|
||
inputSources 系统报告的输入源
|
||
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 画面搬迁
|
||
videoSpace / videoRebuilds / videoReset / viewDrag / frameErr
|
||
ctlHidden / ctlVisible / ctlBeamOn / ctlDraws / ctlErr
|
||
panelPose / grab / grabValue / saved
|
||
errors[] 最近错误
|
||
```
|
||
|
||
---
|
||
|
||
## 10. 长期隐患
|
||
|
||
1. **注入写在容器内文件**(`/jellyfin/jellyfin-web/index.html`)→
|
||
`jellyfin/jellyfin:latest` 一升级就没了,需重跑 `deploy.py`。
|
||
正式版应改用 **JavaScript Injector**(`n00bcodr/jellyfin-plugins` 的 `12/manifest.json`,
|
||
targetAbi 12.0.0.0)或 **File Transformation**(`IAmParadox27/jellyfin-plugin-file-transformation`,554⭐)。
|
||
2. **Three.js 从 CDN 加载**(1.27MB)→ 依赖外网。可改为本地托管。
|
||
3. **Quest 浏览器版本会随系统更新变化** → 能力探测(诊断信息里的能力段)是唯一的自检手段。
|
||
|
||
---
|
||
|
||
## 11. 参考项目
|
||
|
||
| 项目 | 形态 | 备注 |
|
||
|---|---|---|
|
||
| `JiaruiGe/jellyfinvr`(镜像 `allexxex`) | 单 JS,Three.js | VR180/360/SBS/OU;每帧上传纹理,8K 下是瓶颈 |
|
||
| `Mix1C/Jellyfin-360VR-Player` | 单 JS,A-Frame | 仅 360°,无 180 |
|
||
| `Lqlsoftware/Jellyfin-vr-plugin` | C# DLL | 独立播放页 `/VR/Video/{id}/Play` |
|
||
| `Toastyice/DeoVRDeeplink` | C# DLL + `deovr://` | 可完全自动唤起 Quest 上的 DeoVR(deeplink 走系统,不受 user gesture 限制) |
|
||
| `IAmParadox27/jellyfin-plugin-file-transformation` | C# 插件 | 正式版注入通道 |
|
||
| `n00bcodr/jellyfin-plugins` → JavaScript Injector | 插件 | `12/manifest.json` |
|
||
|
||
---
|
||
|
||
## 12. 自检清单(改完代码后)
|
||
|
||
```
|
||
[ ] python3 build.py --check 全部模块语法通过
|
||
[ ] JF_PW=... python3 deploy.py 部署成功,md5 一致
|
||
[ ] 让用户刷新页面
|
||
[ ] 读 window.__JFVR_STATE__.stats 确认 layersBuilt / errors 为空
|
||
[ ] 确认 fps 仍在 ~110+,targetFrameRate 120
|
||
[ ] 确认面板/字幕/手模型均无异常
|
||
```
|
||
|
||
### 6.14 画面搬迁为什么是"纯旋转"(ADDENDUM 8)
|
||
|
||
等距柱状图层 `radius = 0`,语义是**内容在无穷远**。这决定了三件事:
|
||
|
||
- 平移这个球**看不出任何变化**,所以搬画面只能是 `layer.transform` 的**旋转**
|
||
- 远景没有视差,所以转头/走动时画面**不会游动**
|
||
- 旋转中心就是**球心=眼点**,正好是"以我眼睛为旋转点"
|
||
|
||
而且只转视频层:面板在 `refSpace` 固定姿态、字幕在 viewer 空间头锁定,所以**UI 不会跟着
|
||
画面跑**。代价为零(不解码、不重传纹理、不动 8K HEVC DirectPlay)。
|
||
|
||
拖动用**射线自身的方向差**而不是面板上的坐标:面板坐标挪几度就出界了,射线旋转无行程限制,
|
||
而且"光标下的那个点始终在光标下",才像"抓住画面拖"。
|
||
|
||
### 6.15 拖动为什么一开始"松手才动",以及复位为什么崩(ADDENDUM 8b)
|
||
|
||
两个都是我的 bug,记在下面免得再犯:
|
||
|
||
1. **探测用四元数分量比较 → 假阴性。** `q` 和 `-q` 是同一个旋转,运行时还可能返回归一化后的
|
||
值,所以"写进去再读回来比 y/w"会得出错误的"只读"结论。于是拖动走到重建分支,而那个分支
|
||
被限成"只在松手时执行" → 松手才动。**现在比 `position`**(精确、无符号歧义)。
|
||
2. **复位崩溃 = 先建后毁。** 同一 `<video>` 上同时存在两个 `XRMediaBinding` 等距柱状图层,
|
||
外加微秒级连着重建两次(松手一次 + 复位一次)→ 浏览器直接挂。现在重建一律:
|
||
在 `setTimeout`(**不在 XR 帧回调里**)执行、**先毁后建**、限流 120ms、最多排一个。
|
||
`transform`/`space` 两条路根本不重建,所以正常情况走不到这条。
|
||
3. 顺手补的两个健壮性漏洞:`getOffsetReferenceSpace()` 抛错会逃进帧循环——那里抛异常等于
|
||
**永久冻住会话**(rAF 只在回调末尾续订);现在包了 try/catch 并降级到 rebuild。整个每帧
|
||
函数体也都包了 try/catch。
|
||
|
||
**机制自动二选一**:`stats.videoRotMode` = `transform`(每帧写 transform)/ `space`
|
||
(`layer.space = refSpace.getOffsetReferenceSpace(q)`)/ `rebuild`(手动兼容档)。
|
||
两者**互斥**:创建图层时只有 rebuild 档会把 transform 烘进去,否则会叠加两次旋转。
|
||
|
||
**手势**(按你的要求):`点一下复位 · 按住 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` 是否符合上面的表。
|