# Jellyfin Web VR180 — 项目交接文档 > 给新对话用。读完这份就能接手,不需要重新调查环境。 > 最后更新:已部署版本 `917fde`(`NS.version = hud-11`;ADDENDUM 6 字幕深度/大小解耦 > + 7 唤出门限/前面板精简 + 7b 锁按钮与「锁定」面板模式 + 8/8b 画面搬迁(实时拖动) > + 9 rAF 代理修复(VR 内字幕不再冻结)+ 普通/双目字幕自动识别 > + 10 原生(SRT 等)字幕由插件自绘到 HUD;布局覆盖不再持久化 > + 11 指针跟随正在操作/瞄准的那只手;11b 光标落在引导线上 + 点击归属操作手 > + 12 单一指针主人(主用手默认,按下接管,按住互斥,抬起按源匹配)) > > ⚠️ **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` / ``(密码不写进仓库,见 §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='' python3 deploy.py # 回滚到原始 index.html python3 deploy.py rollback # 部署早期单文件版 python3 deploy.py --legacy # 重连 Quest 的 ADB + CDP ./quest.sh ``` **部署后必须让用户刷新页面**(脚本按页面加载缓存,URL 里的 `?r=` 是破缓存用的)。 ### 诊断信息 页面里「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 subSource / subNativeText ← ADDENDUM 10 activeSrc / pressSrc / pressPtr / handPref ← ADDENDUM 11/12 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. **复位崩溃 = 先建后毁。** 同一 `