From bfcd102ed0670611e1874949d611b383cfc22cde Mon Sep 17 00:00:00 2001
From: catShark <1716967236@qq.com>
Date: Sun, 18 Oct 2026 00:29:38 +0800
Subject: [PATCH] docs: record the 8K Main 10 root cause, the OSD load order,
and the watchdog
README gets a section on the watchdog; HANDOFF gets ADDENDUM 12 with the full
investigation: the failing file is HEVC Main 10 while every other 8K file is
Main, Jellyfin Web builds its device profile from canPlayType('hvc1.2.4.L183')
which over-claims, the server has no force-transcode switch, and the player UI
(including the quality menu) is only created after 'playbackstart' -- which is
why a stuck video has no quality menu to click.
Also records that src/00-core.js only ever probed Main-profile codec strings, so
the documented "8K HEVC supported" result was never true for 10-bit.
---
HANDOFF.md | 105 +++++++++++++++++++++++++++++++++++++++++++++++++++++
README.md | 39 ++++++++++++++++++++
2 files changed, 144 insertions(+)
diff --git a/HANDOFF.md b/HANDOFF.md
index f035cba..a638d93 100644
--- a/HANDOFF.md
+++ b/HANDOFF.md
@@ -789,3 +789,108 @@ handPref=left(持久化后重开会话) pointer hand:left HIT 0.22,0
右手按住画面拖动条,左手松开 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() 转圈
+