hud-8: keep the libass loop alive across XR entry; auto dual/mono subtitles

ADDENDUM 9 — two independent defects found on device.

1. VR subtitles froze on whatever line was on screen when the session started.
   Jellyfin 12.x renders with SubtitlesOctopus, which starts ONE long-lived rAF
   loop when the video loads; entering immersive-vr stops native rAF and destroys
   the callback still pending in the native scheduler, and because the instance's
   rafId stays non-zero it is never restarted (measured live: rafId=1150 native,
   oneshotState.eventStart frozen ~7 min behind the playhead, zero oneshot-render
   requests). The broker now ALWAYS queues rAF (native driver outside XR, rVFC +
   50 ms idle fallback inside), keeps exactly one native callback in flight, and
   no longer clears the queue at session start. A first version re-armed during
   the drain and doubled the driver every frame, freezing the page; that is now
   fixed and locked down by a Node harness (maxConcurrentNative = 1 over 300
   frames, self-rescheduling loop survives a simulated session start).

2. Only dual-eye ASS subtitles worked; a normal subtitle (e.g. the CN SRT track)
   is centred across the whole 2:1 frame and was cut at the eye seam because the
   HUD always sampled the left half. state.subLayout ('auto'|'dual'|'mono',
   default auto, persisted, panel row) plus per-sample detection: seam ink -> mono,
   one half only -> dual/mono, both halves with an empty seam -> column-profile
   copy test. Dual-eye is NOT a pixel mirror (same text at mirrored positions, no
   glyph flip): measured dual copy distance 0.02-0.08 vs mono 1.00, seam ink
   0 vs 50. M.eyeW (half for dual, full for mono) replaces the hard-coded halfW.

Docs: INTERFACES.md ADDENDUM 9, HANDOFF.md §13 (including the Jellyfin service
worker cache trap that made the first deploy look like a no-op).

The final build was not re-checked in the headset: the device left the worn state
mid-verification and the browser could not be relaunched. Verified on device: the
loop survives XR (rafId in the plugin range, eventStart tracking, subUploads 4->7
over 20 s in VR) and the layout metrics above; the final decision wiring is
covered by the offline suites.
This commit is contained in:
2026-10-12 16:32:25 +08:00
parent 7f751b7eee
commit 164d692791
6 changed files with 697 additions and 114 deletions
+85 -28
View File
@@ -20,11 +20,26 @@
* rAF broker
* ------------------------------------------------------------------
* While an immersive XR session runs, window.requestAnimationFrame is
* COMPLETELY stopped (measured: 0 callbacks in 6s) and Jellyfin renders
* libass subtitles from an rAF loop, so subtitles freeze. Hold callbacks
* in our own queue while in XR and drive them from
* video.requestVideoFrameCallback (which still fires, in step with the
* video). Outside XR delegate to the native implementation.
* COMPLETELY stopped (measured: 0 callbacks in 6s). Jellyfin renders libass
* subtitles from an rAF loop, so that froze the subtitle canvas.
*
* The FIRST fix was to queue callbacks in XR and pump the queue from
* video.requestVideoFrameCallback. That is not enough on Jellyfin 12.x: a
* callback that is ALREADY PENDING in the NATIVE scheduler when the session
* starts is destroyed with the native scheduler and never runs again, and
* SubtitlesOctopus starts ONE long-lived rAF loop when the video loads whose
* id is never reset. Verified on device: instance.rafId stuck on a native id
* (1150), oneshotState.eventStart frozen ~7 min behind the playhead, zero
* oneshot-render requests for the whole session -> the whole prerender chain
* stalls and the HUD shows the last line drawn before VR started.
*
* So the queue is used ALWAYS, even outside XR, and drained by a native rAF
* pump. Nothing is ever left pending natively, so nothing can be lost when the
* session starts; startRafPump just swaps the driver. In XR the native pump
* stops and video.requestVideoFrameCallback drives the queue (it still fires,
* in step with the video); a slow timer also drives it when the video is not
* presenting frames (paused / stalled / ended), so a paused seek or a track
* switch still redraws instead of leaving a stale line on screen.
* ================================================================== */
var RAFQ = {
inXR: false,
@@ -33,24 +48,13 @@
queue: new Map(),
nextId: 1000000000,
pumped: 0,
nativeId: null,
lastPump: 0,
err: null
};
try {
window.requestAnimationFrame = function (cb) {
if (!RAFQ.inXR) return RAFQ.native(cb);
var id = RAFQ.nextId++;
RAFQ.queue.set(id, cb);
return id;
};
window.cancelAnimationFrame = function (id) {
if (RAFQ.queue.has(id)) { RAFQ.queue.delete(id); return; }
return RAFQ.nativeCancel(id);
};
} catch (e) { log('rAF broker install failed', e); }
function pumpRaf(t) {
if (!RAFQ.inXR || !RAFQ.queue.size) return;
function drainRaf(t) {
if (!RAFQ.queue.size) return;
var cbs = [];
RAFQ.queue.forEach(function (cb) { cbs.push(cb); });
RAFQ.queue.clear();
@@ -60,24 +64,66 @@
}
}
// Native driver (outside XR). Exactly ONE native callback is kept in flight so
// that a rAF which re-schedules itself cannot multiply the driver (an earlier
// version nulled nativeId before draining, re-armed on every self-rescheduling
// callback AND again at the end -> exponential native callbacks -> frozen page).
function nativeRafStep(t) {
if (RAFQ.inXR) { RAFQ.nativeId = null; return; } // the XR driver owns the queue
RAFQ.nativeId = RAFQ.native(nativeRafStep); // re-arm BEFORE draining
drainRaf(t);
if (!RAFQ.queue.size && !RAFQ.inXR) { // nothing left -> stop
try { RAFQ.nativeCancel(RAFQ.nativeId); } catch (e) {}
RAFQ.nativeId = null;
}
}
function ensureNativeRaf() {
if (RAFQ.inXR || RAFQ.nativeId != null) return;
RAFQ.nativeId = RAFQ.native(nativeRafStep);
}
try {
window.requestAnimationFrame = function (cb) {
if (typeof cb !== 'function') return 0;
var id = RAFQ.nextId++;
RAFQ.queue.set(id, cb);
if (!RAFQ.inXR) ensureNativeRaf();
return id;
};
window.cancelAnimationFrame = function (id) {
if (RAFQ.queue.has(id)) { RAFQ.queue.delete(id); return; }
return RAFQ.nativeCancel(id);
};
} catch (e) { log('rAF broker install failed', e); }
function startRafPump(video) {
// NOTE: do NOT clear the queue. The callback that a naive broker loses at
// session start is sitting in it, and it is the one that keeps Jellyfin's
// subtitle loop alive. The pending NATIVE driver id is dropped: that callback
// is lost with the native scheduler anyway, and clearing the id lets the
// driver restart cleanly after the session ends.
RAFQ.nativeId = null;
RAFQ.inXR = true;
RAFQ.queue.clear();
RAFQ.pumped = 0;
RAFQ.lastPump = 0;
RAFQ.err = null;
var stopped = false;
S.stats.rafPump = video && video.requestVideoFrameCallback ? 'videoFrameCallback' : 'interval';
if (video && video.requestVideoFrameCallback) {
var step = function (now) {
if (stopped) return;
pumpRaf(now);
RAFQ.lastPump = performance.now();
drainRaf(now);
video.requestVideoFrameCallback(step);
};
video.requestVideoFrameCallback(step);
RAFQ.stop = function () { stopped = true; };
return;
}
var id = setInterval(function () { pumpRaf(performance.now()); }, 16);
// Idle fallback: rVFC stops while the video is paused / stalled / ended.
var id = setInterval(function () {
if (stopped || !RAFQ.inXR) return;
if (performance.now() - RAFQ.lastPump > 60) drainRaf(performance.now());
}, 50);
RAFQ.stop = function () { stopped = true; clearInterval(id); };
}
@@ -85,9 +131,9 @@
try { if (RAFQ.stop) RAFQ.stop(); } catch (e) {}
RAFQ.stop = null;
RAFQ.inXR = false;
// hand leftovers back to the real scheduler so nothing is stranded
RAFQ.queue.forEach(function (cb) { try { RAFQ.native(cb); } catch (e) {} });
RAFQ.queue.clear();
RAFQ.lastPump = 0;
// hand the queue back to the native driver so nothing is stranded
ensureNativeRaf();
}
/* ================================================================== *
@@ -124,6 +170,7 @@
S.subOpacity = num(o.subOpacity, 0.1, 1.0, S.subOpacity);
S.ctlAutoHideMs = num(o.ctlAutoHideMs, 1000, 10000, S.ctlAutoHideMs);
if (o.subMode === 'hud' || o.subMode === 'sphere') S.subMode = o.subMode;
if (o.subLayout === 'auto' || o.subLayout === 'dual' || o.subLayout === 'mono') S.subLayout = o.subLayout;
// ADDENDUM 8: how the picture aim is applied. 'space' is the live path; the
// 'rebuild' escape hatch exists because mutating a media layer's transform is
// ignored by this runtime, so if an offset reference space turns out not to be
@@ -158,6 +205,7 @@
subAngleDeg: S.subAngleDeg,
subOpacity: S.subOpacity,
subMode: S.subMode,
subLayout: S.subLayout,
subAlpha: S.subAlpha,
projection: S.projection,
stereo: S.stereo,
@@ -411,6 +459,15 @@
body.appendChild(segRow('显示', function () { return S.subtitles ? 'on' : 'off'; },
function (v) { S.subtitles = v === 'on'; saveSettings(); },
[{ label: '开', value: 'on' }, { label: '关', value: 'off' }]));
// ADDENDUM 9: dual-eye ASS vs a normal (mono) subtitle. 'auto' detects from
// the libass canvas; force it only if the detection gets it wrong.
body.appendChild(segRow('字幕布局', function () { return S.subLayout || 'auto'; },
function (v) {
S.subLayout = v;
if (NS.Subtitles && NS.Subtitles.setLayout) { try { NS.Subtitles.setLayout(v); } catch (e) {} }
saveSettings();
},
[{ label: '自动', value: 'auto' }, { label: '双目', value: 'dual' }, { label: '普通', value: 'mono' }]));
body.appendChild(NS.makeEl('div', 'jfvr-hint',
'字幕的位置 / 距离 / 大小 / 不透明度都在 VR 里用控制条调(控制条最下面一行),' +
'调好会自动记住。VR 空间右侧有个锁图标:锁上后面板不会再被唤出。'));