Files
jellyfin_vr_web_plugin/HANDOFF.md
T
cat-shark 263e270747 hud-6: pan the 180° video window about the eye; padlock as a panel button
ADDENDUM 8 — panning the video window (yaw/pitch about the eye)
The 180° window was hard-wired dead ahead, so scenes staged below the horizon
could only be watched by physically lowering the head. The video layer is an
XREquirectLayer with radius 0, i.e. the content sits at infinity: only its
ORIENTATION is visible and translating it does nothing. So panning is purely
layer.transform's rotation, which rotates the content about the eye point — no
parallax, no swim when the head moves, and no decode/upload cost (8K HEVC
DirectPlay untouched). Only the video rotates; the panel (refSpace, fixed pose)
and the subtitles (viewer space, head-locked) stay in front of the user.

    state.videoYaw   (+ = picture moved RIGHT)
    state.videoPitch (+ = picture moved UP)
    q = qy(-yaw) * qx(pitch)   -> aim = (cos p·sin yaw, sin p, -cos p·cos yaw)

Interaction is one affordance in the panel, above the progress bar (the owner's
requested placement): a drag strip. Pinch and drag -> the picture follows the
hand 1:1; three taps within 1.6 s reset it (taps counted on RELEASE, so a drag
cannot be mistaken for one); the live angles are printed on the strip. The drag
is driven by the RAY's own direction delta rather than a cursor position on the
panel: a panel-space cursor leaves the panel after a few degrees, while ray
rotation has no range limit and keeps the content point under the cursor.
Controls.hold() freezes the panel auto-hide for the drag's duration.

Pitch is limited only by a gimbal guard (±(π/2 - 0.02)) per "不限"; yaw wraps to
[-π, π]. Both reset to 0 on every VR session — not persisted.

Runtime risk: XREquirectLayer.transform is settable per spec but a runtime may
ignore the write, so it is probed once per session (write a known rotation, read
it back) -> stats.videoRotMode = 'live' (transform write per frame) or
'rebuild' (recreate the media layer, but only on creation/release/reset, never
per frame). THIS PROBE NEEDS A REAL XR SESSION — it is the one thing not
verifiable offline.

ADDENDUM 7b (previous pass, in this commit's tree) — the padlock
The padlock had been given its own quad layer parked 0.45 m to the right of the
panel. On device it could not be selected while the panel was shown but could
when it was hidden. Aiming is the binding constraint: with hands the only
pointing device is a ray, and the cursor's acceptance window reaches the panel's
own right edge, so the badge was outside every reachable ray; its hit test also
used the panel's layer geometry, which is why the behaviour flipped with panel
visibility. It is now an ordinary panel button (media row, fifth slot) using the
same hitTest/handleSelect path as every other button, and "locked" is a third
panel mode (0.26 × 0.10 m) that draws and hit-tests ONLY the padlock. Locking
swaps the panel in place and lets it auto-hide; the next summon shows the padlock
alone; unlocking restores the full panel and ignores presses for 500 ms.
handleSelect() no longer falls back to pressing the panel centre when no ray hit
exists.

Panel: expanded grew 0.72 × 0.21 m -> 0.72 × 0.26 m (canvas 1440 × 520) for the
drag strip; every row re-proportioned.

Verified offline against the real bundle: quaternion/drag maths (aim direction
for ±yaw/±pitch, unit norm, azimuth/elevation recovery, yaw wrap, pitch clamp,
"aimed point ends up under the cursor"), panel hit bands on the new canvas
(strip 0..0.20, inert readout 0.20..0.30, seek 0.30..0.52, media 0.52..0.74,
subtitle 0.84..1.0, no dead column), the strip's drawn readout, and hold().
build.py --check passes; deployed as mvp-2e32e6 and confirmed live on the Quest
(hud-6, videoYaw/videoPitch 0, errors empty).
2026-10-11 19:59:25 +08:00

23 KiB
Raw Blame History

Jellyfin Web VR180 — 项目交接文档

给新对话用。读完这份就能接手,不需要重新调查环境。 最后更新:已部署版本 2e32e6(NS.version = hud-6;ADDENDUM 6 字幕深度/大小解耦

  • 7 唤出门限/前面板精简 + 7b 锁按钮与「锁定」面板模式 + 8 画面拖动搬迁) 已在 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 通路:

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。

截图与「看」画面:

$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

__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°窗口) ✅ 面板进度条上方的拖动条:按住拖动,画面绕眼点左右上下转;连点 3 次复位;每次进 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. 工作流速查

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 / ctlHold / pressAt / lastActivate         ← ADDENDUM 7/7b 锁、面板保持与唤出判定
videoYaw / videoPitch / videoAngleLive / videoRotMode        ← ADDENDUM 8 画面搬迁
videoRebuilds / videoReset / viewDrag / viewTaps
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)。

拖动用射线自身的方向差而不是面板上的坐标:面板坐标挪几度就出界了,射线旋转无行程限制, 而且"光标下的那个点始终在光标下",才像"抓住画面拖"。

唯一的未知:XREquirectLayer.transform 规范上可写,但运行时可能忽略。所以每会话探测一次 (写一个已知旋转再读回):live = 每帧写 transform(零成本);rebuild = 只能重建媒体层, 那就只在创建/松手/复位时重建,拖动过程中画面在松手后追上。见 stats.videoRotMode / videoRebuilds。这条必须真机验证,离线测不出来。