From 0270cd1bc109ccf2114720cd93e8696d1ea81de6 Mon Sep 17 00:00:00 2001 From: catShark <1716967236@qq.com> Date: Sun, 18 Oct 2026 01:35:15 +0800 Subject: [PATCH] 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. --- HANDOFF.md | 42 +++++++++++++++++++++++++++++++----------- README.md | 32 +++++++++++++++++++++++++------- 2 files changed, 56 insertions(+), 18 deletions(-) diff --git a/HANDOFF.md b/HANDOFF.md index b638761..373c4f5 100644 --- a/HANDOFF.md +++ b/HANDOFF.md @@ -890,28 +890,48 @@ enableautobitratebitrate-Video- = false ← 上游拼写,bitra 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.3.0.0 / bundle `4e9a8f`) +### 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`、`L123→1080p60`、`L153→3840x2160@60`、`L183/L186→8192x4096@60` +- 每档在**它对应的分辨率和码率**上探测(level 字符串不带尺寸):`L120→1920x1080@30/8Mbps`、`L123→1080p60/8Mbps`、`L153→3840x2160@60/20Mbps`、`L183/L186→8192x4096@60/30Mbps` - codec string → `':'`(`hvc1.2.4.L183` → `2:183`);`hvc1`/`hev1` 同键,因为差的只是 sample entry -- **只有 `supported === false` 才降级**;`supported:true, smooth:false` 只记录不行动(太贴边,而且看门狗已经兜底) +- **拦掉一档的两个条件**:`supported === false`(完全解不了)或 **`smooth === false`**(能解但跟不上)。只有 `powerEfficient:false`(纯软解)本身不拦 - 钩子在 bundle 执行时**同步**装上(此时还没有 verdict,一律交给原生),探测结果落地后才生效 -- 逃生开关:`localStorage['jfvr-cpt'] = 'off'` → 完全不装钩子 +- 逃生开关:`localStorage['jfvr-cpt'] = 'off'` 完全关掉;`localStorage['jfvr-cpt-keep'] = '2:183'` 只保留某一档(单台设备误报时用) -三种模式本地实测(`_harness-codec.html`,全过): +### 18.7.1 为什么最后把 `smooth` 加上了(重要) -| 模式 | 结果 | -|---|---| -| `pc` | 8K Main10 被拦 → Jellyfin 封顶 level 153 → 8K 文件超出声明 → **转码** | -| `quest` | 无一被拦 → 声明保持 ≥183 → **Direct Play 不变** | -| `off` | 钩子未安装,`canPlayType` 完全未动 → 恢复旧行为 | +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 走同一套机制,但库里没有这类片源,先不做。 -- [ ] `decodingInfo` 的 `smooth` 现在是只记录不行动。如果哪天出现「supported:true 但实际掉帧」的案例,可以考虑把 `smooth === false` 也纳入降级条件(风险:可能误伤 Quest)。 +- [ ] 网络带宽那一维不在设备档案范围内(档案是在播放开始时判一次的)。Jellyfin 自带的 Auto 码率探测管这个。 +- [ ] 看门狗(§1.2)现在退居为纯兜底:如果检测结果准了,它就不应该再触发。它仍然保留,作为「声称能播结果没播出来」的最后一道。 diff --git a/README.md b/README.md index 6e07914..2a4c694 100644 --- a/README.md +++ b/README.md @@ -109,25 +109,43 @@ if (canPlayType('video/mp4; codecs="hvc1.2.4.L183"')) { 插件的做法: -1. 页面加载时用 **`MediaCapabilities.decodingInfo`** 对 HEVC 各档做真机探测(每档在它对应的分辨率上测:L120→1080p30、L153→4K60、L183/L186→8K60,因为 level 字符串本身不带尺寸); -2. 把结果回灌给 `HTMLVideoElement.prototype.canPlayType`:只有 `supported === false` 才返回 `''`,其余全部交给原生实现。 +1. 页面加载时用 **`MediaCapabilities.decodingInfo`** 对 HEVC 各档做真机探测(每档在它对应的分辨率和码率上测:L120→1080p30/8Mbps、L153→4K60/20Mbps、L183/L186→8K60/30Mbps,因为 level 字符串本身不带尺寸); +2. 把结果回灌给 `HTMLVideoElement.prototype.canPlayType`。 + +**拦掉一档的条件有两个,都是「确定的不能」**: + +| 条件 | 含义 | +|---|---| +| `supported === false` | 完全解不了这个格式 | +| `smooth === false` | 能解,但**在那种分辨率和帧率下跟不上** —— 就是「有 HEVC 解码器,但 8K 跑不动」这种桌面场景 | + +只有 `powerEfficient:false`(纯软解)**本身不拦**。 这样 Jellyfin Web 自己那套 `maxHevcLevel` 逻辑就会得出**准确**档案: | 设备 | 结果 | |---|---| -| 桌面(声称支持但实际解不动 8K Main 10) | 降到 level 153 → 8K 文件超出声明 → **服务器转码** | +| 桌面(声称支持但实际解不动 8K Main 10) | 降到 level 153 → 8K 文件超出声明 → **服务器自动转码** | | Quest 3(真能解 8K Main 10) | 保持 ≥183 → **继续 Direct Play** | -**故意保守**:只有 `supported === false` 才降级。`supported:true, smooth:false` 会记录但不影响行为 —— 太贴边了,而且「声称能播结果没播出来」已经有 §1.2 的看门狗兜底。 +注意:这里**不问用户任何东西**。客户端如实上报,Jellyfin 在 `PlaybackInfo` 那一步自己选 Transcode —— 这正是「提示用户切码率」想要达到的目的,只是做在了正确的层。 -出问题的逃生开关(某台设备报得离谱时用): +逃生开关: ```js -localStorage['jfvr-cpt'] = 'off'; // 然后刷新,覆盖完全不安装 +localStorage['jfvr-cpt'] = 'off'; // 完全关掉钩子 +localStorage['jfvr-cpt-keep'] = '2:183'; // 只保留某一档(单台设备误报时用,不用整个关掉) ``` -当前状态可以在诊断面板里看到(`canPlayType hook` 和 `HEVC real (decodingInfo)` 两段)。这也是 Meta 官方文档推荐的做法 —— 他们明确说「用 Media Capabilities API 探测,不要靠 UA 嗅探」。 +当前状态可以在诊断面板里看到,每档会写明**为什么**被拦(`unsupported` / `not-smooth`)或是否被 pin: + +``` +canPlayType hook : on (blocked: Main10 L6.1 (8K) (not-smooth), ...) +HEVC real (decodingInfo): + Main10 L6.1 (8K) supported=true smooth=false powerEfficient=true [8192x4096@60 30Mbps] <-- BLOCKED (not-smooth) +``` + +这也是 Meta 官方文档推荐的做法 —— 他们明确说「用 Media Capabilities API 探测,不要靠 UA 嗅探」。 ### 1.4 「VR 播放」按钮可以拖了