Replaces the deploy.py approach (which sed-patched index.html inside the
container, and was therefore lost on every jellyfin/jellyfin upgrade) with a
proper plugin installable from a Jellyfin plugin repository.
The web bundle is unchanged: the same src/*.js -> dist/jfvr.js is now embedded
in Jellyfin.Plugin.JFVR.dll and served from /JFVR/jfvr.js with a content-hash
cache key. index.html is rewritten at request time by an IStartupFilter
middleware, so nothing on disk is touched.
Verified before this commit:
- dotnet build: 0 warnings, 0 errors (net10.0, Jellyfin.Controller 12.1.0)
- the DLL embeds dist/jfvr.js byte for byte
- 19/19 checks on the rewrite logic (injection, idempotency, legacy-tag
takeover, no </body> safety, other scripts preserved, URL override)
- manifest.json passes Jellyfin's PackageInfo/VersionInfo expectations
- the packaged zip's MD5 matches the checksum the manifest advertises
Details that were checked against the Jellyfin source rather than assumed:
- a catalog version survives when targetAbi <= serverVersion, so a single
targetAbi 12.0.0.0 package covers all of 12.x (server is 12.1.0)
- Jellyfin writes meta.json itself at install time, so the zip needs only
the DLL
- Jellyfin verifies the MD5 at install time
Also adds pack.py (build -> package -> manifest -> Gitea release) and documents
the plugin route in README/HANDOFF, keeping deploy.py as a fallback.
792 lines
43 KiB
Markdown
792 lines
43 KiB
Markdown
# 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` / `<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
|
||
|
||
# ---- 插件路线(推荐)----
|
||
python3 pack.py # 构建 + 打包 + 更新 manifest.json
|
||
python3 pack.py --bump --publish # 版本号 +1,建 Gitea Release,上传 zip,推 manifest
|
||
python3 pack.py --print-urls # 只打印 Jellyfin 要填的仓库地址
|
||
# 需要 GITEA_TOKEN(write:repository),从环境变量或 secrets.local.md 读
|
||
|
||
# ---- 老路线:直接注入容器内文件(兜底)----
|
||
# 密码从环境变量读;真实值放在本地 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
|
||
```
|
||
|
||
**插件路线**:Jellyfin 里点更新/重装 → 重启 → 刷新浏览器。
|
||
**老路线**:部署后必须让用户刷新页面(脚本按页面加载缓存,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
|
||
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`
|
||
一升级就没了~~ —— **已解决**:现在是插件 `Jellyfin.Plugin.JFVR`,在请求时改写
|
||
`index.html`,磁盘上的 web 目录一个字节都不动。见 `plugin/` 和 `pack.py`,
|
||
安装地址 `https://git.cat-shark.xyz/cat-shark/jellyfin_vr_web_plugin/raw/branch/main/manifest.json`。
|
||
`deploy.py` 保留作为兜底(两者不要同时用)。
|
||
剩下的维护成本:Jellyfin 升大版本时可能要重新编译(插件对 `Jellyfin.Controller 12.1.0` / net10.0)。
|
||
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` 是否符合上面的表。
|
||
|
||
---
|
||
|
||
## 14. ADDENDUM 10 — 普通字幕(SRT 等)为什么读不到(已部署 `e394bcb` / `hud-9`)
|
||
|
||
### 14.1 根因:Jellyfin 只把 ssa/ass 交给 libass
|
||
|
||
`htmlVideoPlayer-plugin` 的 `renderTracksEvents` 决策:
|
||
|
||
```js
|
||
a = (n.Codec || '').toLowerCase();
|
||
if (!X.includes(a)) { // X = ['ssa','ass']
|
||
if (a === 'pgssub') -> renderPgs
|
||
if (Y.includes(a)) -> renderVobSub // Y = ['dvdsub','vobsub']
|
||
if (!u(h.fe)) -> renderSubtitlesWithCustomElement // DOM 覆盖层
|
||
/* 否则落到原生 TextTrack 分支 */
|
||
}
|
||
return renderSsaAss(...); // 只有 ssa/ass
|
||
```
|
||
|
||
所以 `subrip`/`vtt` **根本不会创建 libass canvas**。设备实测(选中 `CN` SRT 时):
|
||
`canvas.libassjs-canvas` 数量 **0**、`.libassjs-canvas-parent` 0、`.videoSubtitles` 0,
|
||
只有 `video.textTracks[0] = { kind:'subtitles', label:'manualTrack', mode:'showing',
|
||
cues:315 }` —— 浏览器用 `::cue` 自己画。插件**无论改什么布局都读不到任何东西**。
|
||
|
||
### 14.2 修复(`src/10-subtitles.js`)
|
||
|
||
`updateSource()` 每帧挑来源:
|
||
|
||
- 有非空 `canvas.libassjs-canvas` → `srcKind='libass'`(原路径不变);
|
||
- 否则若有 showing 的 TextTrack 或 `.videoSubtitlesInner` → `srcKind='native'`:
|
||
从 `textTracks[i].activeCues` 读当前 cue(兜底读 DOM 覆盖层 `innerText`),
|
||
清洗 ASS/HTML 标签与双向控制符、按字符折行,用白字黑描边画进私有 1920×1080
|
||
canvas,再走**完全相同的裁剪/上传/HUD 管线**;
|
||
- 都没有 → `srcKind='none'`,清一次字幕条。
|
||
|
||
`prepare()` 在没有 libass canvas 时跳过(放大播放器框只是为了让 libass 重渲染,原生
|
||
canvas 是我们自己的)。新增诊断 `stats.subSource` / `stats.subNativeText` 和
|
||
`Subtitles.getSourceKind()`。
|
||
|
||
### 14.3 血的教训:布局覆盖**不要持久化**
|
||
|
||
ADDENDUM 9 把 `state.subLayout` 存进了 `jfvr.settings.v1`。结果一个残留的 `'mono'`
|
||
静默地把默认的**双目**内容强制成普通:`dual:false`、`eyeW:4320`、裁剪跨越两眼接缝 →
|
||
HUD 把两只眼的字幕并排显示。找这个 bug 花的时间比写检测还多。现在 `subLayout`
|
||
**不持久化**(和 `subtitles`、`subMode:'off'` 同理),开机恒为 `auto`,面板可临时改。
|
||
|
||
### 14.4 设备实测(`hud-9`)
|
||
|
||
| 选中轨 | `subSource` | 结果 |
|
||
|---|---|---|
|
||
| `CN_dual_eye`(ass,idx 0) | `libass` | `dual:true`、`eyeW:2160`、`crop:[1040,768,1176,924]`(左半)、`copyND:0.055`、uploads 递增 |
|
||
| `CN`(subrip,idx 1) | `native` | `dual:false`、`eyeW:1920`、canvas 1920×1080、`text:"进去了呢"`、`crop` 256×88、uploads 递增 |
|
||
|
||
私有 cue canvas 还读回做了 OCR(cue `怎么样?好好地` → OCR `怎么样? 好好地`);
|
||
注入/移除一个假的 `canvas.libassjs-canvas` 能让 `subSource` 在 `libass`/`native`
|
||
间切换且 `subErr` 为空。
|
||
|
||
---
|
||
|
||
## 15. ADDENDUM 11 — 指针跟随「正在操作/正在瞄准」的那只手(已部署 `6bf1021` / `hud-10`)
|
||
|
||
**根因**:双手都会报 `tracked-pointer` 射线,而运行时的顺序不是「用户正在用的那只手」。
|
||
`updatePointer()` 取**第一个**有有效射线的输入源就 `break`;而 `pointerDown()` 调用的是
|
||
`updatePointer(frame)`——**没有把 `select` 事件里的 `inputSource` 传进去**。于是设备上:
|
||
|
||
- 引导线/光标永远钉在一只手上(用户用另一只手指也不跟)→「引导线并没有指向光标」;
|
||
- 另一只手的捏合**落在被钉住那只手所指的位置**:左手控制点击位置,右手完成点击。
|
||
|
||
**修复**(`src/90-main.js`):`updatePointer(frame, preferSrc)` 为每个 tracked-pointer
|
||
源各算一次命中,再用纯函数 `pickPointerCand(cands, preferKey, activeKey)` 选:
|
||
|
||
```
|
||
1. preferSrc —— 当前正在操作的那个源(select / gamepad 按下)
|
||
2. 上次操作的源 —— 前提是它正瞄准面板(hit.inBounds)
|
||
3. 任一个正在瞄准面板的源(运行时顺序)
|
||
4. 上次操作的源(粘滞)
|
||
5. 第一个源
|
||
```
|
||
|
||
`pointerDown()` 传入事件的 `inputSource`,所以每次操作都用**操作那只手**的射线判定;
|
||
选中的手之后保持粘滞。诊断新增 `stats.activeSrc`,会话结束时清空。
|
||
|
||
**验证**:`pickPointerCand` 是纯函数,直接从构建产物提取做了单测——包含你描述的场景
|
||
(引导线在左手 → 右手捏合)现在得到 `hand:right` 并保持;另有「左手接管」「操作手不在
|
||
面板上、另一只手在瞄 → 跟随瞄准手」「都没瞄 → 保持上次操作手」等 9 个用例全过。
|
||
|
||
**验证手法(重要,可复用)**:官方文档里只有 **Meta XR Simulator** 能模拟 aim/poke/pinch/grab,
|
||
但它是**开发机上的桌面工具**,面向 Unity/Unreal 原生应用;`adb` 没有 XR 输入注入,CDP 也没有
|
||
WebXR 域(`WebXR.enable` 不存在)。所以改成**从页面注入合成输入源**:
|
||
|
||
```js
|
||
// 每个 targetRaySpace 都是本会话真实的 XRRigidTransform 偏移参考空间
|
||
var off = (await session.requestReferenceSpace('local'))
|
||
.getOffsetReferenceSpace(new XRRigidTransform({x:±0.2, y:-0.34, z:-1.0}));
|
||
window.__FAKE = [ {handedness:'left', targetRayMode:'tracked-pointer', hand:{}, targetRaySpace:off,
|
||
gamepad:{buttons:[{pressed:false,value:0}]}} , /* right */ ];
|
||
Object.defineProperty(XRSession.prototype,'inputSources',{configurable:true,get:function(){return window.__FAKE;}});
|
||
// 触发:window.__FAKE[1].gamepad.buttons[0].pressed = true → pollGamepads 上升沿 → pointerDown(src,frame,'gamepad')
|
||
```
|
||
|
||
走的是**真实**的 `pointerDown(src, frame, …)`(和 `select` 同一条路径),测完把
|
||
`inputSources` 描述符还原。实测(`immersive-vr` 活动会话):
|
||
|
||
```
|
||
初始 pointer hand:left HIT 0.22,0.50 activeSrc hand:left
|
||
右手按下 pointer hand:right HIT 0.78,0.50 activeSrc hand:right
|
||
右手松开 pointer hand:right HIT 0.78,0.50 (粘滞保持)
|
||
左手按下 pointer hand:left HIT 0.22,0.50 activeSrc hand:left
|
||
右手没瞄面板时按下 pressAt "MISS (not aiming at the panel)" ← 没有偷用左手位置
|
||
```
|
||
|
||
> `XRInputSourceEvent('select', …)` 构造器要求真实 `XRInputSource`,所以无法伪造 select 事件;
|
||
> 但 select 与 gamepad 共用 `pointerDown`,已被上面覆盖。
|
||
|
||
---
|
||
|
||
## 16. ADDENDUM 11b — 光标落在引导线上;点击归属操作那只手(已部署 `3d3b5f`)
|
||
|
||
针对 ADDENDUM 11 实测后反馈的两点。
|
||
|
||
### 16.1 光标偏离引导线(越靠边缘越明显)
|
||
|
||
`panelHit()` 会把**打在面板外**的交点**夹取到边框**,并用 `inBounds` 标出来;但
|
||
`updatePointer()` 把夹取后的 `nx,ny` 当 `pointer.hit` 发布了。于是光标环画在**面板边框**上,
|
||
而光束末端在**真实交点**(面板之外)——射线越偏离面板,两者差得越远,与反馈完全一致。
|
||
|
||
现在 **只有 `hit.inBounds` 才发布 `pointer.hit`**:光标只在射线真正打在面板上时出现,必然落在
|
||
光束上。只要射线与面板平面相交就仍然发布 `distance`,且 `beamLength()` 不再要求 `p.hit`,
|
||
所以瞄边缘时引导线仍指到面板平面。擦边仍能**唤出**控制条(宽判 `panelHit(...,0.5,0.9)` 未动),
|
||
但擦边不再能**按下**。
|
||
|
||
### 16.2 右手点击仍会落在左手位置
|
||
|
||
三个独立原因,全部修掉:
|
||
|
||
- **冷却是全局的**:`ACTIVATE_COOLDOWN_MS`(250ms) 会压掉 250ms 内的任意一次按下,所以一只手的
|
||
gamepad 抖动会**吃掉另一只手的 `select`**,动作随即用了第一只手的位置。现改为**按输入源分别
|
||
计时**(`lastActivateByKey`):同一次捏合产生的 gamepad+select 仍会去重,但绝不会吃掉另一只手。
|
||
- **取不到射线时静默回退到另一只手**:现在只要给了 `preferKey`(正在操作的那个源),它就
|
||
**独占这次射击**;若它不在候选里,`pick` 返回 `null`,这次按下算 **MISS**。
|
||
- **`frame` 为空时根本没重新归属**:`pointerDown()` 原来写 `if (frame) updatePointer(...)`,
|
||
frame 为空时就沿用上一帧的指针(可能是另一只手)。现在回退到 `S.lastFrame`,且若仍算不出指针,
|
||
直接记 `MISS (acting source has no ray)`。
|
||
|
||
新增诊断:`stats.pressSrc`(本次按下归属的源)、`stats.pressPtr`(`hand:right HIT` /
|
||
`hand:right nohit` / `(no ray)`)。
|
||
|
||
### 16.3 实测(注入合成输入源,活动会话)
|
||
|
||
```
|
||
都在面板上,右手按下 pressSrc hand:right pressPtr "hand:right HIT" pressAt 0.78,0.50 seek 79.5%
|
||
左手按下后 100ms 右手按下 pressSrc hand:right pressAt 0.78,0.50 (右手没被吃掉)
|
||
两只手都在面板外 state.pointer.hit = null (不再夹取光标)
|
||
面板外右手按下 pressSrc hand:right pressPtr "hand:right nohit"
|
||
pressAt "MISS (no hit on the panel)" (没有用左手位置)
|
||
```
|
||
|
||
---
|
||
|
||
## 17. ADDENDUM 12 — 单一指针“主人”:主用手默认,按下接管(已部署 `917fde` / `hud-11`)
|
||
|
||
之前的指针是**对称**的:谁最后操作谁拥有;谁都没操作时用「运行时第一个源」——本设备上就是**左手**,
|
||
所以右撇子一抬手引导线就在非惯用手上。而且两只手会互相打扰彼此的按住操作。
|
||
|
||
### 17.1 单一主人(像鼠标只有一个光标)
|
||
|
||
`pickPointerCand(cands, preferKey, ownerKey, prefHand)`:
|
||
|
||
```
|
||
preferKey(正在操作的那个源) → 就是它;取不到 → null ⇒ 这次按下 MISS
|
||
主人且正瞄面板 → 主人
|
||
主用手且正瞄面板 → 主用手
|
||
任一只正瞄面板的手 → 它
|
||
主人(没瞄面板) → 主人
|
||
主用手(没瞄面板) → 主用手
|
||
→ 第一个源
|
||
```
|
||
|
||
- **`state.handPref`**(`'right' | 'left'`,默认 `'right'`)= 指针的默认主人(惯用手)。
|
||
在**进 VR 前的面板**「操作 → 主用手」里设置,持久化在 `jfvr.settings.v1`。会话开始生效;
|
||
会话中主人只会粘滞。
|
||
- **按下即接管**(`preferKey`),之后主人粘在那只手上(只要它在瞄面板)。
|
||
|
||
### 17.2 两只手不再互相打扰
|
||
|
||
- **按住期间互斥**:某只手发起的长按/拖动(`grab` / `viewDrag`)进行中时,**另一只手的按下被忽略**
|
||
(`stats.pressAt = 'IGNORED (other hand is holding)'`)。
|
||
- **抬起按源匹配**:`pointerUp(src)` 只结束 `src` 自己发起的那次抓取/拖动。之前它是无参的,
|
||
所以**任一只手松手都会取消另一只手的字幕抓拖/画面搬迁**。现在 `onSelectEnd(ev)` 和
|
||
`pollGamepads` 都会传源,`grab` / `viewDrag` 各自带 `key`。
|
||
- **失效收尾**:`dropStaleHolds()` 每帧检查,若发起抓取的那只手从 `session.inputSources` 消失
|
||
(手部追踪丢失)就主动结束,避免永远没有 release 事件而卡住。
|
||
|
||
新增诊断:`stats.handPref`、`stats.owner`(= `stats.activeSrc`),以及已有的 `pressSrc` / `pressPtr`。
|
||
|
||
### 17.3 实测(注入合成输入源,活动会话)
|
||
|
||
```
|
||
默认(handPref=right),两手都在面板上 pointer hand:right HIT 0.78,0.50 (原来是 hand:left)
|
||
handPref=left(持久化后重开会话) pointer hand:left HIT 0.22,0.50
|
||
左手按下后松开 主人 hand:left,之后仍是 left
|
||
右手按住画面拖动条,左手按下 pressAt "IGNORED (other hand is holding)"
|
||
右手按住画面拖动条,左手松开 viewDrag 仍 "armed"(拖动存活)
|
||
右手按住画面拖动条,右手松开 viewDrag "reset (tap)"(拖动结束)
|
||
```
|