Files
jellyfin_vr_web_plugin/HANDOFF.md
T
cat-shark 838675baa6 Jellyfin Web VR plugin for Quest 3 (VR180 stereo playback)
Injects a 「VR 播放」 button into Jellyfin Web's video player page and plays
VR180 / VR360 stereo content on Meta Quest 3 directly in the browser, with
DirectPlay 8K HEVC, in-VR subtitles and an in-VR control panel.

Modules (src/, concatenated in filename order into dist/jfvr.js):
  00-core.js       namespace, shared state, GL helpers, layer/frame-hook registry
  10-subtitles.js  libass canvas -> head-locked quad layer, auto-cropped to ink,
                   with depth/size decoupling (angular-size lock)
  20-controls.js   in-VR control panel: progress/seek, transport, subtitle rows,
                   aiming beam, padlock, pure 2D canvas -> XR quad layer
  30-hands.js      system hand model (Three.js + generic-hand GLB) via a manually
                   driven projection layer
  90-main.js       boot, XR session lifecycle, rAF broker (rAF stops during XR),
                   input dispatch, settings panel, localStorage persistence

Key on-device findings are documented in HANDOFF.md §6 and README.md addenda:
requestAnimationFrame stops during an XR session, 3:2 pulldown at 90 Hz needs
updateTargetFrameRate(120), libass must be resized before entering VR, a quad's
local -Z is its plane normal, and hand aiming must use the gaze ray because the
emulated targetRaySpace points sideways. Quest does not expose eye tracking.

Docs: INTERFACES.md (module contract + addenda), README.md (measurements),
HANDOFF.md (handover notes). Credentials are NOT in the repo: deploy.py reads
the SSH password from the JF_PW environment variable.
2026-10-11 19:19:06 +08:00

455 lines
22 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Jellyfin Web VR180 — 项目交接文档
> 给新对话用。读完这份就能接手,不需要重新调查环境。
> 最后更新:已部署版本 `7616c9`(`NS.version = hud-5`;ADDENDUM 6 字幕深度/大小解耦
> + ADDENDUM 7 唤出门限/进 VR 前面板精简 + ADDENDUM 7b 锁按钮与「锁定」面板模式)
> 已在 Quest 浏览器里实机验证模块加载 + 锁定数学(`subLockAngle/subAngleDeg`,`errors: []`);
> **VR 会话内的观感还没看过**。
---
## 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 (343 行) 命名空间、共享状态、GL 助手、层/帧钩子注册表、能力探测
│ ├── 10-subtitles.js (1022 行) 字幕:libass 画布 → 头锁定 quad 层(HUD)+ 视角尺寸锁定
│ ├── 20-controls.js (1930 行) 控制面板:进度条/按钮/光束/光标/锁按钮,canvas 2D → quad 层
│ ├── 30-hands.js (569 行) **系统手部模型**:Three.js + 官方 generic-hand GLB → projection 层
│ └── 90-main.js (1420 行) 引导、会话生命周期、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 重置为未锁 |
| 按压反馈 | ✅ 圆环放大 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
ctlSubsOn / ctlSubDist / ctlSubAngle / ctlSubLock ← 控制条实际画出的值
ctlLock / ctlMode / pressAt / lastActivate ← ADDENDUM 7/7b 锁与唤出判定
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
[ ] 确认面板/字幕/手模型均无异常
```