3 Commits
Author SHA1 Message Date
cat-shark cf731c16c2 docs: ADDENDUM 13 — the real root cause is nvidia-vaapi-driver 0.0.14
Records the full evidence chain (VAAPI fails at 8K Main 10 while CUDA/NVDEC and
8-bit 8K both work; chrome://gpu shows the driver advertising Main 10 up to
8192x8192), the upstream bug (self-referential CUVIDDECODECREATEINFO
initializer, fixed in 0.0.18), the correct Chrome/VAAPI setup on Kubuntu, and
what it means for the plugin (nothing once the driver is updated; and why
0.5.0.0's gate was wrong and 0.5.1.0 fixed it).
2026-10-18 11:58:23 +08:00
cat-shark 03919dab98 plugin: publish 0.5.1.0 (bundle 3e611e) 2026-10-18 11:57:52 +08:00
cat-shark beba1e66f0 caps: never lower the level ceiling when 8-bit at that level works
The 0.5.0.0 gate blocked a Main 10 tier whenever decodingInfo called it
unusable. That is wrong on a machine that decodes 8-bit 8K but not 10-bit 8K,
which is exactly the machine this was written on (measured: nvidia-vaapi-driver
decodes 8192x4096 Main 8-bit and fails to create a decoder for 8192x4096
Main 10).

browserDeviceProfile.js derives the level ceiling and the profile list from ONE
chain of Main 10 probes -- the only Main (8-bit) probes are L4.0 and L4.1. So
the reachable states are only (120,main) (123,main) (123,main|main 10)
(153,main|main 10) (183,main|main 10) (186,main|main 10). "Main up to 8K,
Main 10 only up to 4K" is not expressible. Blocking 2:183 on that machine
therefore does not spare the 10-bit file -- it drags every 8-bit 8K file down to
level 153 and transcodes the whole library. On a server that cannot transcode 8K
in real time that trades one broken file for sixty.

So a Main 10 tier is now only blocked when the SAME LEVEL is also unusable in
Main (8-bit): 8-bit probes were added at L5.1, L6.1 and L6.2 as the control. The
cost is that a device which decodes 8-bit at a level but not 10-bit still claims
10-bit there and can black-screen on such a file -- which is precisely what
40-watchdog.js exists for.

Also notes the real root cause for that machine, which is not in this plugin:
nvidia-vaapi-driver 0.0.14 has a self-referential CUVIDDECODECREATEINFO
initializer (".ulWidth = vdci.ulMaxWidth = ..."), undefined behaviour that feeds
invalid dimensions to cuvidCreateDecoder. It advertises HEVC Main 10 up to
8192x8192 but cannot create the decoder. Fixed upstream in 0.0.18 by moving the
assignments out of the initializer.

Verified against the local harness, five modes, all passing:
  pc    8K unusable in both bit depths -> cap 153 -> TRANSCODE
  slow  8-bit 8K ok, 10-bit 8K not     -> nothing blocked -> 8-bit 8K DIRECT PLAY
  quest everything ok                  -> DIRECT PLAY
  pin   2:183 pinned                   -> pin wins, rest still blocked
  off   kill switch                    -> canPlayType untouched
2026-10-18 11:57:11 +08:00
5 changed files with 253 additions and 33 deletions
+98
View File
@@ -935,3 +935,101 @@ window.__JFVR.capsDiag()
- [ ] 探测目前只覆盖 HEVC。AV1 / VP9 走同一套机制,但库里没有这类片源,先不做。
- [ ] 网络带宽那一维不在设备档案范围内(档案是在播放开始时判一次的)。Jellyfin 自带的 Auto 码率探测管这个。
- [ ] 看门狗(§1.2)现在退居为纯兜底:如果检测结果准了,它就不应该再触发。它仍然保留,作为「声称能播结果没播出来」的最后一道。
---
## 19. ADDENDUM 13 — 真机根因:`nvidia-vaapi-driver` 0.0.14 的自引用初始化器
### 19.1 结论(先看这个)
本机(Kubuntu / NVIDIA TU116M GTX 1660 Ti Mobile / Chrome 152)播不了 8K Main 10,
**根因不在 Jellyfin、不在插件、也不在显卡硬件**,而在 `nvidia-vaapi-driver` 的版本:
```
已安装: nvidia-vaapi-driver 0.0.14-1 (2025-06-08,Ubuntu 26.04 仓库里只有这个)
已修复: 0.0.18 (2026-08-31)
```
**升级到 0.0.18 即可,不需要转码、不需要插件做任何补偿。**
### 19.2 证据链
**1) 硬件能做,中间层不行** —— 同一文件、同一台机器:
| 路径 | 结果 |
|---|---|
| `ffmpeg -hwaccel vaapi`(走 nvidia-vaapi-driver) | ❌ `Failed to create decode context: 2 (resource allocation failed)` |
| `ffmpeg -hwaccel cuda`(直连 NVDEC) | ✅ 正常 |
| VAAPI 解 8K **Main(8-bit)** | ✅ 正常 |
| VAAPI 解 1080p **Main 10** | ✅ 正常 |
→ 只有 **8K + 10-bit** 这个组合失败;硬件本身没问题。
**2) Chrome 侧的配置是对的** —— `chrome://gpu` 实测:
```
Graphics Feature Status
* Video Decode: Hardware accelerated ← VAAPI 生效中
Video Acceleration Information
Decode hevc main : 144x144 to 8192x8192 pixels
Decode hevc main 10 : 144x144 to 8192x8192 pixels ← 驱动"声称"支持
```
**驱动声称支持 8K Main 10,实际建不出解码器。** 于是:
```
canPlayType('hvc1.2.4.L183') → truthy
→ Jellyfin Web 声明 maxHevcLevel=183 / main|main 10
→ 服务器选 DirectPlay(日志里没有任何 ffmpeg)
→ Chrome 真正解码时 cuvidCreateDecoder 失败
→ 黑屏 / 一直转圈(而 OSD 只在 playbackstart 之后创建,所以连码率菜单都没有)
```
**3) 上游 bug** —— 0.0.14 的 `src/vabackend.c`:
```c
CUVIDDECODECREATEINFO vdci = {
.ulWidth = vdci.ulMaxWidth = vdci.ulTargetWidth = picture_width, // ← 在自身初始化器里引用自己
.ulHeight = vdci.ulMaxHeight = vdci.ulTargetHeight = picture_height, // C 里这是未定义行为
```
修复提交 `a565237`(2026-07-09)标题即 **"fix: drop self-referential CUVIDDECODECREATEINFO initializer"**,
把赋值移出初始化器;`#449`(2026-07-17 合入)把同样的修复镜像到另一个函数。**0.0.17 仍有问题,0.0.18 已修复。**
### 19.3 Kubuntu 上正确让 Chrome 用显卡
用户现有的启动参数**是对的**(`chrome://gpu` 已确认 `Video Decode: Hardware accelerated`):
```
--enable-features=VaapiOnNvidiaGPUs,VaapiVideoDecodeLinuxGL,VaapiVideoDecoder
--disable-features=UseChromeOSDirectVideoDecoder
```
配套条件:
- `nvidia-vaapi-driver` **≥ 0.0.18**(当前 0.0.14 → 这是要补的一环)
- 驱动 README 要求内核参数 `nvidia-drm.modeset=1`(**本机当前未设置**,`/proc/cmdline` 里没有)
- `LIBVA_DRIVER_NAME=nvidia`
- 注意:驱动 README 明说 *"specifically designed to be used by Firefox … may not operate correctly in other applications"*、*"Chrome is currently unsupported"*。Chrome 能用但不受官方支持。
升级(Ubuntu 仓库只有 0.0.14,需从源码构建):
```bash
sudo apt install meson ninja-build libva-dev libegl-dev gstreamer1.0-plugins-bad libffmpeg-nvenc-dev
git clone --branch v0.0.18 https://github.com/elFarto/nvidia-vaapi-driver
cd nvidia-vaapi-driver && meson setup build && sudo meson install -C build
```
### 19.4 这对插件意味着什么
升级驱动后:Chrome 能真正解 8K Main 10 → `decodingInfo` 报 `smooth:true` → 插件不拦任何档
→ 直连 8K → 看门狗也不会触发。**插件侧不需要做任何补偿。**
但 **0.5.0.0 的判定逻辑本身有个缺陷,已在 0.5.1.0 修掉**:它在 `smooth === false` 时就压低
level 上限,而 Jellyfin 的档案**无法表达「Main 支持到 8K,Main 10 只到 4K」**(level 上限和
profile 列表来自同一条 Main 10 判断链)。所以在那台「8-bit 8K 正常、10-bit 8K 失败」的机器上,
拦掉 `2:183` 会把**整库 61 个 8-bit 8K 文件**一起拖进转码 —— 而 NAS 转 8K 只能出 1280×640。
0.5.1.0 改成:**只有当同位深的 Main(8-bit)档也不可用时,才压低 level 上限**(为此补测了
Main L5.1 / L6.1 / L6.2 作为对照)。代价是「8-bit 能解、10-bit 不能」的设备仍会声称 10-bit 并在
那种文件上黑屏 —— 那正是 `40-watchdog.js` 存在的意义。
+73 -16
View File
@@ -360,16 +360,39 @@
* DirectPlay. Meta's browser-video docs recommend exactly this API over UA
* sniffing.
*
* Only a definite "no" downgrades, but "no" has two shapes and both matter:
* A tier is blocked when:
*
* supported === false the decoder cannot handle the format at all
* smooth === false it can, but not in real time at that resolution and
* frame rate -- the case a desktop with a small HEVC
* decoder hits on 8K, where the picture never appears
* even though the codec is "supported"
* supported === false the decoder cannot handle the format at all
* smooth === false it can, but not in real time at that resolution and
* frame rate -- the "decoder exists, 8K does not work"
* case
*
* Either one means the server should transcode. A tier that is only
* `powerEfficient:false` (software decode) is NOT acted on by itself.
* AND, for a Main 10 tier, only when the SAME LEVEL IS ALSO UNUSABLE IN MAIN
* (8-bit). That second condition is not cosmetic; it is forced by a real
* limitation in Jellyfin's device profile.
*
* browserDeviceProfile.js derives the level ceiling and the profile list from
* ONE chain of Main 10 probes -- the only Main (8-bit) probes are L4.0 and
* L4.1. So the reachable states are only:
*
* (120, main) (123, main) (123, main|main 10) (153, main|main 10)
* (183, main|main 10) (186, main|main 10)
*
* "Main up to 8K, Main 10 only up to 4K" is NOT expressible. So blocking
* 2:183 on a device that decodes 8-bit 8K but not 10-bit 8K does not just
* spare the 10-bit file -- it drags every 8-bit 8K file down to level 153 and
* transcodes them too. On a server that cannot transcode 8K in real time
* (measured: 8192x4096 -> 1280x640), that trades one broken file for sixty.
*
* Verified on the machine this was written for: NVIDIA VAAPI decodes
* 8192x4096 Main 8-bit fine and fails to create a decoder for 8192x4096
* Main 10 (nvidia-vaapi-driver passes the surface bit depth straight to
* cuvidCreateDecoder). Its whole library is 8-bit 8K, so lowering the ceiling
* would have broken all of it.
*
* The cost of this rule: a device that decodes 8-bit at a level but not
* 10-bit will still claim 10-bit at that level and can black-screen on such a
* file. 40-watchdog.js covers exactly that, which is why it stays.
*
* Escape hatches, if a device reports nonsense:
* localStorage['jfvr-cpt'] = 'off' disable the hook entirely
@@ -377,11 +400,15 @@
*/
// decodingInfo needs real dimensions; a level string does not carry them, so
// each level is probed at the resolution and bitrate it exists for.
// each level is probed at the resolution and bitrate it exists for. Main
// (8-bit) is probed at the same levels as Main 10 because it is the control
// that decides whether a level is really out of reach.
var CODEC_PROBES = [
{ key: '1:120', name: 'Main L4.0', w: 1920, h: 1080, fps: 30, mbps: 8, codec: 'hvc1.1.L120' },
{ key: '1:123', name: 'Main L4.1', w: 1920, h: 1080, fps: 60, mbps: 8, codec: 'hvc1.1.4.L123' },
{ key: '1:153', name: 'Main L5.1 (4K)', w: 3840, h: 2160, fps: 60, mbps: 20, codec: 'hvc1.1.5.L153.B0' },
{ key: '1:183', name: 'Main L6.1 (8K)', w: 8192, h: 4096, fps: 60, mbps: 30, codec: 'hvc1.1.6.L183.B0' },
{ key: '1:186', name: 'Main L6.2 (8K60)', w: 8192, h: 4096, fps: 60, mbps: 30, codec: 'hvc1.1.6.L186.B0' },
{ key: '2:123', name: 'Main10 L4.1', w: 1920, h: 1080, fps: 60, mbps: 8, codec: 'hvc1.2.4.L123' },
{ key: '2:153', name: 'Main10 L5.1 (4K)', w: 3840, h: 2160, fps: 60, mbps: 20, codec: 'hvc1.2.4.L153' },
{ key: '2:183', name: 'Main10 L6.1 (8K)', w: 8192, h: 4096, fps: 60, mbps: 30, codec: 'hvc1.2.4.L183' },
@@ -453,14 +480,42 @@
return null;
}
/** True when this tier is not usable on its own terms. */
function tierUnusable(key) {
var v = NS.caps.codec[key];
return !!v && !v.error && (v.supported === false || v.smooth === false);
}
/**
* The decision the canPlayType hook uses.
*
* A Main 10 tier is only blocked when the SAME LEVEL is also unusable in Main
* (8-bit). See the long comment above CODEC_PROBES: Jellyfin's profile cannot
* express "Main up to 8K, Main 10 up to 4K", so blocking 2:183 on a device
* that handles 8-bit 8K would drag all of its 8-bit 8K files into transcoding.
*/
function shouldBlock(key, keep) {
var v = NS.caps.codec[key];
if (!v || v.error) return null;
if (keep.indexOf(key) >= 0) return null;
var own = blockReason(v, keep);
if (!own) return null;
var parts = key.split(':');
if (parts[0] === '2') {
// Control: the same level in Main (8-bit).
if (!tierUnusable('1:' + parts[1])) return null;
}
return own;
}
function applyVerdicts() {
var keep = readKeepList();
var keep = NS.caps.__keep || [];
NS.caps.codecKept = [];
NS.caps.codecBlocked = [];
CODEC_PROBES.forEach(function (p) {
var v = NS.caps.codec[p.key];
if (!v) return;
var why = blockReason(v, keep);
var why = shouldBlock(p.key, keep);
if (why) NS.caps.codecBlocked.push(p.name + ' (' + why + ')');
else if (keep.indexOf(p.key) >= 0) NS.caps.codecKept.push(p.name);
});
@@ -475,9 +530,8 @@
proto.canPlayType = function (type) {
try {
var key = hevcKey(type);
var v = key && NS.caps.codec[key];
// Only a definite "no" is acted on. Anything else is the browser's call.
if (v && blockReason(v, NS.caps.__keep || [])) return '';
if (key && shouldBlock(key, NS.caps.__keep || [])) return '';
} catch (e) { /* never break the native answer */ }
return orig.apply(this, arguments);
};
@@ -535,11 +589,14 @@
var v = c.codec[p.key];
if (!v) return ' ' + p.name.padEnd(20) + ' (pending)';
if (v.error) return ' ' + p.name.padEnd(20) + ' error: ' + v.error;
var why = blockReason(v, keep);
var why = shouldBlock(p.key, keep);
var own = blockReason(v, keep);
var note = why ? ' <-- BLOCKED (' + why + ')' :
(own ? ' (unusable, but kept: 8-bit at this level works)' :
(keep.indexOf(p.key) >= 0 ? ' <-- pinned' : ''));
return ' ' + p.name.padEnd(20) + ' supported=' + v.supported +
' smooth=' + v.smooth + ' powerEfficient=' + v.powerEfficient +
' [' + v.workload + ']' +
(why ? ' <-- BLOCKED (' + why + ')' : (keep.indexOf(p.key) >= 0 ? ' <-- pinned' : ''));
' [' + v.workload + ']' + note;
}).join('\n');
return [
+8
View File
@@ -7,6 +7,14 @@
"owner": "cat-shark",
"category": "General",
"versions": [
{
"version": "0.5.1.0",
"targetAbi": "12.0.0.0",
"changelog": "Bundle version: `3e611e`\n\nFirst plugin build. The web bundle is embedded in the DLL and served from /JFVR/jfvr.js; index.html is rewritten at request time, so nothing is written to the jellyfin-web folder on disk.",
"sourceUrl": "https://git.cat-shark.xyz/cat-shark/jellyfin_vr_web_plugin/releases/download/v0.5.1.0/Jellyfin.Plugin.JFVR_12.0.0.0.zip",
"checksum": "54AB6541A1BFD7A62636A435350821E0",
"timestamp": "2026-10-18T03:57:47"
},
{
"version": "0.5.0.0",
"targetAbi": "12.0.0.0",
+1 -1
View File
@@ -7,7 +7,7 @@
# (InstallationManager.GetAvailablePackages), so one package covers all of 12.x.
name: "Jellyfin Web VR"
guid: "7d33ef59-f9b0-412b-93bd-5cd5353018de"
version: "0.5.0.0"
version: "0.5.1.0"
targetAbi: "12.0.0.0"
framework: "net10.0"
overview: "VR180/VR360 playback inside Jellyfin Web for Meta Quest 3."
+73 -16
View File
@@ -352,16 +352,39 @@
* DirectPlay. Meta's browser-video docs recommend exactly this API over UA
* sniffing.
*
* Only a definite "no" downgrades, but "no" has two shapes and both matter:
* A tier is blocked when:
*
* supported === false the decoder cannot handle the format at all
* smooth === false it can, but not in real time at that resolution and
* frame rate -- the case a desktop with a small HEVC
* decoder hits on 8K, where the picture never appears
* even though the codec is "supported"
* supported === false the decoder cannot handle the format at all
* smooth === false it can, but not in real time at that resolution and
* frame rate -- the "decoder exists, 8K does not work"
* case
*
* Either one means the server should transcode. A tier that is only
* `powerEfficient:false` (software decode) is NOT acted on by itself.
* AND, for a Main 10 tier, only when the SAME LEVEL IS ALSO UNUSABLE IN MAIN
* (8-bit). That second condition is not cosmetic; it is forced by a real
* limitation in Jellyfin's device profile.
*
* browserDeviceProfile.js derives the level ceiling and the profile list from
* ONE chain of Main 10 probes -- the only Main (8-bit) probes are L4.0 and
* L4.1. So the reachable states are only:
*
* (120, main) (123, main) (123, main|main 10) (153, main|main 10)
* (183, main|main 10) (186, main|main 10)
*
* "Main up to 8K, Main 10 only up to 4K" is NOT expressible. So blocking
* 2:183 on a device that decodes 8-bit 8K but not 10-bit 8K does not just
* spare the 10-bit file -- it drags every 8-bit 8K file down to level 153 and
* transcodes them too. On a server that cannot transcode 8K in real time
* (measured: 8192x4096 -> 1280x640), that trades one broken file for sixty.
*
* Verified on the machine this was written for: NVIDIA VAAPI decodes
* 8192x4096 Main 8-bit fine and fails to create a decoder for 8192x4096
* Main 10 (nvidia-vaapi-driver passes the surface bit depth straight to
* cuvidCreateDecoder). Its whole library is 8-bit 8K, so lowering the ceiling
* would have broken all of it.
*
* The cost of this rule: a device that decodes 8-bit at a level but not
* 10-bit will still claim 10-bit at that level and can black-screen on such a
* file. 40-watchdog.js covers exactly that, which is why it stays.
*
* Escape hatches, if a device reports nonsense:
* localStorage['jfvr-cpt'] = 'off' disable the hook entirely
@@ -369,11 +392,15 @@
*/
// decodingInfo needs real dimensions; a level string does not carry them, so
// each level is probed at the resolution and bitrate it exists for.
// each level is probed at the resolution and bitrate it exists for. Main
// (8-bit) is probed at the same levels as Main 10 because it is the control
// that decides whether a level is really out of reach.
var CODEC_PROBES = [
{ key: '1:120', name: 'Main L4.0', w: 1920, h: 1080, fps: 30, mbps: 8, codec: 'hvc1.1.L120' },
{ key: '1:123', name: 'Main L4.1', w: 1920, h: 1080, fps: 60, mbps: 8, codec: 'hvc1.1.4.L123' },
{ key: '1:153', name: 'Main L5.1 (4K)', w: 3840, h: 2160, fps: 60, mbps: 20, codec: 'hvc1.1.5.L153.B0' },
{ key: '1:183', name: 'Main L6.1 (8K)', w: 8192, h: 4096, fps: 60, mbps: 30, codec: 'hvc1.1.6.L183.B0' },
{ key: '1:186', name: 'Main L6.2 (8K60)', w: 8192, h: 4096, fps: 60, mbps: 30, codec: 'hvc1.1.6.L186.B0' },
{ key: '2:123', name: 'Main10 L4.1', w: 1920, h: 1080, fps: 60, mbps: 8, codec: 'hvc1.2.4.L123' },
{ key: '2:153', name: 'Main10 L5.1 (4K)', w: 3840, h: 2160, fps: 60, mbps: 20, codec: 'hvc1.2.4.L153' },
{ key: '2:183', name: 'Main10 L6.1 (8K)', w: 8192, h: 4096, fps: 60, mbps: 30, codec: 'hvc1.2.4.L183' },
@@ -445,14 +472,42 @@
return null;
}
/** True when this tier is not usable on its own terms. */
function tierUnusable(key) {
var v = NS.caps.codec[key];
return !!v && !v.error && (v.supported === false || v.smooth === false);
}
/**
* The decision the canPlayType hook uses.
*
* A Main 10 tier is only blocked when the SAME LEVEL is also unusable in Main
* (8-bit). See the long comment above CODEC_PROBES: Jellyfin's profile cannot
* express "Main up to 8K, Main 10 up to 4K", so blocking 2:183 on a device
* that handles 8-bit 8K would drag all of its 8-bit 8K files into transcoding.
*/
function shouldBlock(key, keep) {
var v = NS.caps.codec[key];
if (!v || v.error) return null;
if (keep.indexOf(key) >= 0) return null;
var own = blockReason(v, keep);
if (!own) return null;
var parts = key.split(':');
if (parts[0] === '2') {
// Control: the same level in Main (8-bit).
if (!tierUnusable('1:' + parts[1])) return null;
}
return own;
}
function applyVerdicts() {
var keep = readKeepList();
var keep = NS.caps.__keep || [];
NS.caps.codecKept = [];
NS.caps.codecBlocked = [];
CODEC_PROBES.forEach(function (p) {
var v = NS.caps.codec[p.key];
if (!v) return;
var why = blockReason(v, keep);
var why = shouldBlock(p.key, keep);
if (why) NS.caps.codecBlocked.push(p.name + ' (' + why + ')');
else if (keep.indexOf(p.key) >= 0) NS.caps.codecKept.push(p.name);
});
@@ -467,9 +522,8 @@
proto.canPlayType = function (type) {
try {
var key = hevcKey(type);
var v = key && NS.caps.codec[key];
// Only a definite "no" is acted on. Anything else is the browser's call.
if (v && blockReason(v, NS.caps.__keep || [])) return '';
if (key && shouldBlock(key, NS.caps.__keep || [])) return '';
} catch (e) { /* never break the native answer */ }
return orig.apply(this, arguments);
};
@@ -527,11 +581,14 @@
var v = c.codec[p.key];
if (!v) return ' ' + p.name.padEnd(20) + ' (pending)';
if (v.error) return ' ' + p.name.padEnd(20) + ' error: ' + v.error;
var why = blockReason(v, keep);
var why = shouldBlock(p.key, keep);
var own = blockReason(v, keep);
var note = why ? ' <-- BLOCKED (' + why + ')' :
(own ? ' (unusable, but kept: 8-bit at this level works)' :
(keep.indexOf(p.key) >= 0 ? ' <-- pinned' : ''));
return ' ' + p.name.padEnd(20) + ' supported=' + v.supported +
' smooth=' + v.smooth + ' powerEfficient=' + v.powerEfficient +
' [' + v.workload + ']' +
(why ? ' <-- BLOCKED (' + why + ')' : (keep.indexOf(p.key) >= 0 ? ' <-- pinned' : ''));
' [' + v.workload + ']' + note;
}).join('\n');
return [