Files
jellyfin_vr_web_plugin/HANDOFF.md
T
cat-shark 0270cd1bc1 docs: record the smooth/throughput dimension (0.5.0.0)
README 1.3 now documents both blocking conditions (supported=false and
smooth=false), the pin list, and the fact that nothing is asked of the user.
HANDOFF 18.7.1 explains why smooth was deliberately left out in 0.3.0.0 and why
that was wrong: it is precisely the realistic desktop case (decoder present, 8K
too slow), and it is what this machine actually hit.
2026-10-18 01:35:15 +08:00

938 lines
51 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 — 项目交接文档
> 给新对话用。读完这份就能接手,不需要重新调查环境。
> 最后更新:已部署版本 `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`(仅 8-bit Main,见 ADDENDUM 12) |
| `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)"(拖动结束)
```
---
## 18. ADDENDUM 12 — 「这台机器放不出来」:8K Main 10 与客户端自报能力(插件 0.2.0.0 / bundle `edca47`)
### 18.1 现象
同一个文件 `masex.tv@kiwvr00896_1_8k.mp4`:
- **Quest 3 上正常播放**
- **PC 浏览器上黑屏 / 一直转圈,进度条不走**,而且**播放器界面(含码率菜单)根本不出现**
### 18.2 根因
**文件是 10-bit,而库里其它文件都是 8-bit。** 实测:
```
FAILS : kiwvr00896_1_8k profile=Main 10 pix_fmt=yuv420p10le 8192x4096 level 183 (6.1) 30 Mbps
kiwvr00896_2_8k profile=Main 10 pix_fmt=yuv420p10le
WORKS : 13dsvr01786_1_8k profile=Main pix_fmt=yuv420p 8192x4096 level 183
13dsvr01794_1_8k profile=Main pix_fmt=yuv420p
13dsvr01797_1_8k profile=Main pix_fmt=yuv420p
```
**关键:Jellyfin 的直连/转码决策 100% 看客户端上报的 DeviceProfile。** Jellyfin Web 是这么生成它的(`src/scripts/browserDeviceProfile.js`):
```js
let maxHevcLevel = 120;
let hevcProfiles = 'main';
// hevc main10 level 6.1
if (videoTestElement.canPlayType('video/mp4; codecs="hvc1.2.4.L183"')...) {
maxHevcLevel = 183; // 8K
hevcProfiles = 'main|main 10'; // 10-bit
}
```
PC 浏览器对 `hvc1.2.4.L183` 返回 **"probably"**(系统里有*某个* HEVC 解码器,`canPlayType` 判断很粗),于是声明「支持 Main 10 到 level 6.1(8K)」→ 服务器选了 **Direct Play** → 实际硬件解不动 → 黑屏。Quest 声明同样的话但它真做得到。
**服务器侧没有「强制转码」开关。** `UserPolicy` 只有:`EnableVideoPlaybackTranscoding`(已开)、`EnablePlaybackRemuxing`(已开)、`RemoteClientBitrateLimit`(只对远程连接)、`ForceRemoteSourceTranscoding`(只对远程片源)。没有任何按条目/按设备的强制转码。
**顺带发现:本项目的能力探测有盲区。** `src/00-core.js:326` 只测了
```js
['video/mp4; codecs="hev1.1.6.L183.B0"', // profile_idc 1 = Main(8-bit)
'video/mp4; codecs="hvc1.1.6.L183.B0"',
'video/mp4; codecs="hev1"', 'video/mp4; codecs="hvc1"']
```
`hev1.**1.6**.L183.B0` 里的 `1.6` 是 **Main**;**Main 10 是 `hev1.2.4.L183.B0`,从来没测过**。所以 README §2.0 那句「8K HEVC decodingInfo supported:true」**只对 8-bit 成立** —— 之前碰巧全是 8-bit 文件才没暴露。
### 18.3 为什么卡住之后连码率都调不了(重要)
Jellyfin Web 的播放器 UI **只在 `playbackstart` 之后才被创建**:
```
HtmlVideoPlayer.play() htmlVideoPlayer/plugin.js:502
createMediaElement() :1802 loading.show() 转圈
<div.videoPlayerContainer><video>
document.body.insertBefore(...) ← 还没有 src
updateVideoUrl() / setCurrentSrc() :593 elem.src = url
→ loadedmetadata → canplay → play
→ 'playbackstart'
→ OSD 控制器(apps/legacy/controllers/playback/video/index.js:591)
```
媒体起不来 → 事件不触发 → **OSD(含码率菜单)从未被创建**。所以「卡住后调不了码率」不是菜单藏起来了,是**它还不存在**。
推论:看门狗不能用 `90-main.js` 的 `findVideo()`(它要求 `videoWidth`,卡死时返回 null),必须直接看 `.videoPlayerContainer video`。
### 18.4 对策:`src/40-watchdog.js`
检测「OSD 之前就卡住」这个状态并给出唯一的解 —— 让服务器转码。见 README §1.2。
阈值:媒体报错立即弹;直连 15 秒;转码(src 已是 hls)45 秒;有画面立即退出;VR 会话中不跑。
选码率后写入 Jellyfin 自己那套键再重载:
```
maxbitrate-Video-<true|false> = 20000000
enableautobitratebitrate-Video-<true|false> = false ← 上游拼写,bitrate 出现两次
```
> 不能用 `playbackManager.setMaxStreamingBitrate()`:那个模块**没有暴露到 window**
> (实测 `window.playbackManager === undefined`,`window.Emby` 只剩 `Page`)。
### 18.5 转码在这台 NAS 上的实测能力
2026-10-05 那次播放走的就是转码:
```
-codec:v h264_vaapi -b:v 2744000 -vf "scale_vaapi=w=1280:h=640"
→ 1280x640 @ 2.7 Mbps,ffmpeg 每次 exit 0,无失败
```
8K 10-bit 硬解 + h264 硬编在 UHD 上跑得动,但**输出只有 1280×640**(当时目标码率 2.7 Mbps;UHD 编码上限约 4K)。
### 18.6 附带查清的两件事
1. **续播点 33:22.759 的来历**:就是 2026-10-05 那次转码会话留下的(`stopped ... at 2002759ms`)。所以 10-17 两次播放都从 33:22 续播,画面出不来进度自然不动,于是「停在 33:22」重复了两次。
2. **文件本身没问题**:完全分配无空洞(`du` 实际用量 == 表观大小)、`moov` 在文件头(faststart 正常)、33:22 处 ffmpeg 解码无报错、Jellyfin 数据库里时长正确(50:58)。同目录还有 3 个垃圾广告文件(`.url` × 3 + 一个 20 MB 的 `三 上 悠 亚…mp4`),是盗版站打包进来的。
### 18.7 已做(插件 0.5.0.0 / bundle `72681d`)
- [x] `src/00-core.js` 的能力探测补上 Main 10 和 8K/4K 分档;新增 `NS.caps.codec`(`decodingInfo` 逐档结果)与 `NS.capsDiag()` 里的 `HEVC real` 段
- [x] **彻底自动化**:用 `MediaCapabilities.decodingInfo` 真机探测后覆盖 `HTMLVideoElement.prototype.canPlayType`,让 Jellyfin Web 自己那套 `maxHevcLevel` 逻辑算出准确 profile
- [x] **补上「实时吞吐」这一维**(`smooth`)—— 见下
覆盖逻辑的关键点:
- 每档在**它对应的分辨率和码率**上探测(level 字符串不带尺寸):`L120→1920x1080@30/8Mbps`、`L123→1080p60/8Mbps`、`L153→3840x2160@60/20Mbps`、`L183/L186→8192x4096@60/30Mbps`
- codec string → `'<profile_idc>:<level>'`(`hvc1.2.4.L183` → `2:183`);`hvc1`/`hev1` 同键,因为差的只是 sample entry
- **拦掉一档的两个条件**:`supported === false`(完全解不了)或 **`smooth === false`**(能解但跟不上)。只有 `powerEfficient:false`(纯软解)本身不拦
- 钩子在 bundle 执行时**同步**装上(此时还没有 verdict,一律交给原生),探测结果落地后才生效
- 逃生开关:`localStorage['jfvr-cpt'] = 'off'` 完全关掉;`localStorage['jfvr-cpt-keep'] = '2:183'` 只保留某一档(单台设备误报时用)
### 18.7.1 为什么最后把 `smooth` 加上了(重要)
0.3.0.0 只看了 `supported`,当时故意不动 `smooth`,理由是怕误伤 Quest。但那样会漏掉**最现实的那种桌面场景**:
> 显卡**有** HEVC 解码器(所以 `canPlayType` 报 "probably"、`supported:true`),但**在 8K60 下跑不动**(`smooth:false`)
结果就是:声称支持 level 6.1 → 服务器 DirectPlay → 黑屏。而这恰好就是本机上那个文件的真实情况。所以 0.5.0.0 把它纳入判定。
**定位真机问题时看这个**:在出问题的浏览器控制台跑
```js
window.__JFVR.capsDiag()
```
会列出每一档的 `supported / smooth / powerEfficient`、探测用的负载、以及**为什么被拦**(`unsupported` 还是 `not-smooth`)。一次就能看出是哪一维的问题。
五种模式本地实测(`_harness-codec.html`,全过):
| 模式 | 模拟 | 结果 |
|---|---|---|
| `pc` | `supported=false` | 封顶 level 153 → **转码** |
| `slow` | `supported=true, smooth=false`(**真实桌面场景**) | 封顶 level 153 → **转码** |
| `quest` | 全部 `smooth` | 保持 ≥183 → **Direct Play** |
| `pin` | `slow` + `jfvr-cpt-keep=2:183` | 恢复 183 → **Direct Play** |
| `off` | 开关关闭 | `canPlayType` 完全未动 |
### 18.8 待办
- [ ] 探测目前只覆盖 HEVC。AV1 / VP9 走同一套机制,但库里没有这类片源,先不做。
- [ ] 网络带宽那一维不在设备档案范围内(档案是在播放开始时判一次的)。Jellyfin 自带的 Auto 码率探测管这个。
- [ ] 看门狗(§1.2)现在退居为纯兜底:如果检测结果准了,它就不应该再触发。它仍然保留,作为「声称能播结果没播出来」的最后一道。