28 Commits
Author SHA1 Message Date
cat-shark d6734e505c caps: probe hvc1.1.0.L120 so the HEVC gate is not blocked
Chrome's decodingInfo rejects the constraint-byte-less 'hvc1.1.L120' and
answers supported:false even on a machine that decodes HEVC fine. The
override then blocked every spelling of tier 1:120, and 1:120 is exactly
what browserDeviceProfile.js's supportsHevc() probes -- so hevc was
dropped from every DirectPlayProfile and the whole HEVC library was
transcoded. Probe the valid 'hvc1.1.0.L120' instead, and only act on
1:120 when no Main tier is usable at all.
2026-10-19 23:02:39 +08:00
cat-shark d20482d5dd plugin: publish 0.5.2.0 (bundle 16ae94) 2026-10-19 23:02:01 +08:00
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
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
cat-shark 08cbef83a3 plugin: publish 0.5.0.0 (bundle 72681d) 2026-10-18 01:34:32 +08:00
cat-shark c25e40070a caps: treat "decodes it, but not in real time" as unsupported
The previous gate only acted on decodingInfo's supported flag, so a device with
an HEVC decoder that cannot keep up at 8K still claimed level 6.1, Jellyfin
picked DirectPlay, and the picture never appeared. That is the realistic desktop
case and it was deliberately left unhandled; it is now handled.

A tier is blocked when:

    supported === false   cannot decode the format at all
    smooth    === false   can decode it, but not at that resolution and frame
                          rate -- exactly the "decoder exists, 8K does not work"
                          case

powerEfficient:false on its own still does not block. Nothing is asked of the
user: the point is that the client reports accurately and Jellyfin's own
PlaybackInfo decision then picks Transcode by itself. This is the mechanism the
bitrate prompt was compensating for.

Also:
  - each tier is now probed at a realistic bitrate (8K 30Mbps, 4K 20Mbps,
    1080p 8Mbps) instead of a flat 20Mbps
  - the diagnostics show WHY each tier was blocked (unsupported vs not-smooth)
  - new pin list: localStorage['jfvr-cpt-keep'] = '2:183' keeps a tier claimed
    even if the probe says no, so a single misreported device does not require
    switching the whole mechanism off

Verified against the local harness in five modes, all passing:
  pc    supported=false      -> capped at 153 -> TRANSCODE
  slow  supported, !smooth   -> capped at 153 -> TRANSCODE   (the real PC case)
  quest all smooth           -> 8K kept       -> DIRECT PLAY
  pin   2:183 pinned         -> 183 restored  -> DIRECT PLAY
  off   kill switch          -> untouched
2026-10-18 01:34:17 +08:00
cat-shark 0bf0a1f1da docs: the VR button is draggable (0.4.0.0) 2026-10-18 01:21:19 +08:00
cat-shark 1176c2009c plugin: publish 0.4.0.0 (bundle ae28bd) 2026-10-18 01:21:01 +08:00
cat-shark 30f97808ae ui: make the VR button draggable
It was pinned to the bottom-right corner. On a short window that put it straight
on top of the bitrate choices the playback watchdog shows (that panel is
centred), and there was no way to move it out of the way.

The button now uses left/top (set from JS) instead of right/bottom, is draggable
with pointer events, and remembers where it was dropped. Details that matter:

  - touch-action:none, otherwise a drag on a touch screen scrolls the page
  - a drag still fires a click on most browsers, so the click that ends a drag is
    swallowed; dragging never opens the panel by accident
  - clamped to the viewport, and re-clamped on resize
  - double click resets to the default corner (escape hatch for a button dragged
    somewhere awkward)
  - the settings panel follows the button instead of the viewport corner, so the
    two cannot drift apart; it prefers to sit just above the button, falls back
    to below, and clamps on screen when it is taller than the space available

Verified against a local harness, 18 checks, all passing: default placement
matches the old corner, a drag moves it by exactly the pointer delta and
persists it, the click ending a drag does not open the panel, a plain click
still does, the panel tracks the button's right edge, clamping holds at all four
edges, and double click restores the default.
2026-10-18 01:20:22 +08:00
cat-shark 85fea48159 docs: document the decoder-driven canPlayType override (0.3.0.0)
README gains 1.3 and the 2.0 capability row is corrected: the old
"8K HEVC decodingInfo supported:true" was only ever true for 8-bit Main.
HANDOFF 18.7/18.8 record what the override does, the three verified modes, the
kill switch, and what is deliberately left out (AV1, and acting on smooth:false).
2026-10-18 01:09:00 +08:00
cat-shark 986d30dfb4 plugin: publish 0.3.0.0 (bundle 4e9a8f) 2026-10-18 01:08:12 +08:00
cat-shark ab36d2f25c caps: ask the real decoder, and stop the client from over-claiming HEVC
The capability probe only ever asked canPlayType about Main profile (8-bit)
codec strings, which is why the project notes said "8K HEVC: supported" right up
until a Main 10 file showed up and could not be decoded at all. It now also asks
about Main 10, and -- more importantly -- asks the decoder itself.

The override: Jellyfin Web derives its entire HEVC claim from canPlayType
(browserDeviceProfile.js):

    if (canPlayType('video/mp4; codecs="hvc1.2.4.L183"')) {
        maxHevcLevel = 183;              // level 6.1 = 8K
        hevcProfiles = 'main|main 10';
    }

canPlayType answers "does this system have an HEVC decoder", not "can it do
8192x4096 Main 10 at 60fps". A desktop that merely ships an HEVC decoder
therefore claims 8K Main 10, the server picks DirectPlay, and playback dies on a
black screen with no player UI at all. MediaCapabilities.decodingInfo asks the
actual decoder, so its verdict is fed back through canPlayType and Jellyfin's own
logic lands on the right profile -- the desktop drops to what it can really do
and the server transcodes, while a Quest that genuinely decodes 8K Main 10 keeps
DirectPlay. Meta's browser-video docs recommend exactly this API over UA sniffing.

Deliberately conservative: only supported === false downgrades.
supported:true/smooth:false is recorded but changes nothing -- too close to the
edge to act on, and the watchdog already covers "claimed to work, did not".
Kill switch if a device reports nonsense: localStorage['jfvr-cpt'] = 'off'.

Each level is probed at the resolution it exists for (L120 -> 1080p30,
L153 -> 4K60, L183/L186 -> 8K60), because a level string carries no dimensions.

Verified against a local harness in three modes, all passing:
  pc    -> 8K Main10 blocked, Jellyfin caps at level 153, the 8K Main 10 file
           exceeds the claim and the server transcodes
  quest -> nothing blocked, claim stays >= 183, DirectPlay preserved
  off   -> hook not installed, canPlayType untouched, old behaviour restored
Also re-ran the playback watchdog on the new bundle: still fires on media error.

Also widens the harness gitignore to _harness*.html for the new codec harness.
2026-10-18 01:07:44 +08:00
cat-shark bfcd102ed0 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.
2026-10-18 00:29:38 +08:00
cat-shark 131e0349b8 plugin: publish 0.2.0.0 (bundle edca47) 2026-10-18 00:28:26 +08:00
cat-shark d0fe04bf25 watchdog: tell the user when a video never starts, and offer transcode
Some files never produce a picture on some machines. The Quest decodes the
8K HEVC Main 10 files fine; a Windows desktop browser claims HEVC Main 10 up to
level 6.1 via canPlayType() (Jellyfin Web builds its device profile from that,
browserDeviceProfile.js) so the server picks Direct Play, and the desktop GPU
cannot actually decode it. Result: black screen and a spinner.

The user-visible symptom is worse than it sounds: Jellyfin Web creates the whole
player UI only after 'playbackstart', which never fires, so the OSD -- including
the quality menu -- is never built. There is literally nothing to click to lower
the bitrate. Load order, from the source:

  HtmlVideoPlayer.play()            htmlVideoPlayer/plugin.js:502
    createMediaElement()            :1802  spinner + <div.videoPlayerContainer>
                                           + <video>, inserted with no src yet
    setCurrentSrc()                 :593   elem.src = url
      -> loadedmetadata -> canplay -> play -> 'playbackstart'
        -> OSD controller (apps/legacy/controllers/playback/video/index.js:591)

So 40-watchdog.js watches for exactly the pre-OSD state: a .videoPlayerContainer
whose <video> still has videoWidth === 0. It fires immediately on a media error,
or after 15s (45s when the src is already an HLS transcode, where the server has
to produce segments first). It stands down the moment there is a picture, and
never runs during a VR session.

The panel names the format (fetched from the Jellyfin API), explains the cause,
and offers 20/8/3 Mbps plus "keep waiting". A choice writes the same localStorage
keys Jellyfin's own menu writes and reloads: window.playbackManager is not
reachable from injected script (verified: undefined; window.Emby only has Page),
so the settings path is the only option. Note the upstream key really is
'enableautobitratebitrate-...' with "bitrate" twice; reproduced deliberately.
A 120s cooldown in sessionStorage stops it nagging a slow-but-working playback.

Verified against a local harness (3 cases, all passing): healthy playback ->
never arms; media error -> immediate; hung stream -> ~16.4s; dismiss -> hides and
persists the cooldown, and stayed hidden 20s past the threshold; bitrate choice
-> writes maxbitrate-Video-true/false=20000000 and
enableautobitratebitrate-Video-true/false=false, then reloads.
2026-10-18 00:27:53 +08:00
cat-shark 51ab1a4b48 plugin: publish 0.1.0.1 (bundle 917fde) 2026-10-17 23:33:17 +08:00
cat-shark 5279f3929a plugin: fix zip reproducibility and legacy-tag log spam
Two issues found while verifying the live install:

1. pack.py produced a different zip MD5 for identical content, because zip
   records file mtimes. Re-running pack.py would have rewritten the manifest
   checksum while the already-published asset stayed the same, and Jellyfin
   would then refuse the install with "The checksum of the received data
   doesn't match." The zip entry now carries a fixed 1980-01-01 timestamp, and
   --publish downloads the published asset back and compares its MD5 with the
   manifest checksum before reporting success.

2. The legacy deploy.py tag lives in the on-disk index.html, so it was stripped
   from every single response and logged at INFO each time (6 lines and counting
   per boot on the live server). The message is now emitted once, and says what
   it actually means: the tag is still on disk, run deploy.py rollback to clean
   it up.

Verified: 21/21 rewrite checks pass, including a regression case built from the
tag actually present on the server.
2026-10-17 23:33:06 +08:00
cat-shark ac85de2cb8 plugin: publish 0.1.0.0 (bundle 917fde) 2026-10-17 23:25:43 +08:00
cat-shark 7e25861498 plugin: publish 0.1.0.0 (bundle 917fde) 2026-10-17 23:25:01 +08:00
cat-shark f4fe3d61fc plugin: ship JFVR as a real Jellyfin plugin (self-hosted catalog)
Replaces the deploy.py approach (which sed-patched index.html inside the
container, and was therefore lost on every jellyfin/jellyfin upgrade) with a
proper plugin installable from a Jellyfin plugin repository.

The web bundle is unchanged: the same src/*.js -> dist/jfvr.js is now embedded
in Jellyfin.Plugin.JFVR.dll and served from /JFVR/jfvr.js with a content-hash
cache key. index.html is rewritten at request time by an IStartupFilter
middleware, so nothing on disk is touched.

Verified before this commit:
  - dotnet build: 0 warnings, 0 errors (net10.0, Jellyfin.Controller 12.1.0)
  - the DLL embeds dist/jfvr.js byte for byte
  - 19/19 checks on the rewrite logic (injection, idempotency, legacy-tag
    takeover, no </body> safety, other scripts preserved, URL override)
  - manifest.json passes Jellyfin's PackageInfo/VersionInfo expectations
  - the packaged zip's MD5 matches the checksum the manifest advertises

Details that were checked against the Jellyfin source rather than assumed:
  - a catalog version survives when targetAbi <= serverVersion, so a single
    targetAbi 12.0.0.0 package covers all of 12.x (server is 12.1.0)
  - Jellyfin writes meta.json itself at install time, so the zip needs only
    the DLL
  - Jellyfin verifies the MD5 at install time

Also adds pack.py (build -> package -> manifest -> Gitea release) and documents
the plugin route in README/HANDOFF, keeping deploy.py as a fallback.
2026-10-17 23:17:00 +08:00
cat-shark 0713f35513 hud-11: one pointer owner (dominant hand, press takes over) + hand isolation
ADDENDUM 12. The pointer was symmetric: whoever acted last owned it, and when
neither had acted the first source in runtime order won - the LEFT hand on this
runtime, so a right-handed user's guide line sat on the non-dominant hand.

- state.handPref ('right'|'left', default 'right') is the default owner. Set from the
  pre-VR panel (操作 -> 主用手), persisted. pickPointerCand(cands, preferKey,
  ownerKey, prefHand): acting source owns the shot (or MISSes), else owner aiming ->
  preferred hand aiming -> any hand aiming -> owner -> preferred hand -> first.
- A press takes the pointer over and the owner sticks while it is aiming.
- Hold exclusion: while a grab/viewDrag started by one source is active, a press from
  the other source is ignored (pressAt "IGNORED (other hand is holding)").
- Source-matched release: pointerUp(src) only ends the hold src started. It used to be
  argument-less, so either hand's release cancelled the other hand's subtitle grab or
  picture pan. grab/viewDrag now carry a key; onSelectEnd(ev) and pollGamepads pass
  their source.
- dropStaleHolds() runs each frame and ends a hold whose source left
  session.inputSources (tracking lost), so nothing sticks.

New diagnostics: stats.handPref, stats.owner.

Verified with injected synthetic input sources:
  default (right), both on panel     pointer hand:right HIT 0.78,0.50  (was hand:left)
  handPref=left, fresh session       pointer hand:left  HIT 0.22,0.50
  left press, release                owner hand:left, stays left
  right holds picture-pan, left press    "IGNORED (other hand is holding)"
  right holds picture-pan, LEFT release  viewDrag stays armed (drag survives)
  right holds picture-pan, RIGHT release viewDrag reset (tap) (drag ends)
2026-10-12 21:36:03 +08:00
cat-shark e18c3d51bd hud-10 (rev3): cursor on the guide line; a press is attributed to the acting hand
ADDENDUM 11b, both reported against ADDENDUM 11.

1. The cursor drifted off the guide line, worse near the panel edge. panelHit()
   clamps an off-panel intersection to the border and flags it via inBounds, but
   updatePointer() published that clamped nx,ny as pointer.hit, so the ring was
   drawn on the border while the beam ended at the true (off-panel) intersection.
   pointer.hit is now published only when inBounds; distance is still published so
   an edge-aimed beam reaches the plane (beamLength no longer requires p.hit).
   Near-misses still summon the bar, but no longer press.

2. A right-hand press could still act at the left hand's position, for three
   separate reasons: the activate cooldown was global (a gamepad edge from one hand
   swallowed the other hand's select - now per input source); a missing ray fell
   back to another hand (with a preferKey the acting source now owns the shot and
   a missing candidate MISSes); and a null frame skipped re-attribution entirely
   (now falls back to S.lastFrame and MISSes if the acting source yields no
   pointer).

New diagnostics: stats.pressSrc, stats.pressPtr.

Verified with injected synthetic input sources:
  both on panel, right press      pressSrc hand:right  pressAt 0.78,0.50  seek 79.5%
  left press then right 100ms     pressSrc hand:right  pressAt 0.78,0.50  (not swallowed)
  both off panel                  state.pointer.hit = null (no clamped cursor)
  off panel, right press          pressPtr "hand:right nohit"  MISS (no hit on the panel)
2026-10-12 21:07:05 +08:00
cat-shark 5eb679f6ca hud-10 (rev2): verify the hand switch with injected synthetic XR input sources
Adds the on-device verification for ADDENDUM 11 and a diagnostics nit
(stats.activeSrc reports '(none)' while no candidate is picked).

There is no official way to fake hand input on a Quest for a WebXR page: Meta's
simulator is a desktop tool for Unity/Unreal native apps, adb has no XR input
injection and CDP has no WebXR domain (WebXR.enable does not exist). So the test
injects synthetic input sources whose targetRaySpace is a real XRRigidTransform
offset reference space of the live session, and drives a press through the real
gamepad path (rising edge on gamepad.buttons[0]) - the same pointerDown(src, frame,
...) the select event reaches. XRSession.prototype.inputSources is overridden for
the test and restored after.

Measured in a live immersive-vr session:
  initial            pointer hand:left  HIT 0.22,0.50
  right press        pointer hand:right HIT 0.78,0.50  activeSrc hand:right
  right release      pointer hand:right HIT 0.78,0.50  (sticky)
  left press         pointer hand:left  HIT 0.22,0.50
  right press, right hand off panel -> pressAt "MISS (not aiming at the panel)"
                                       (did NOT fall back to the left hand's position)
2026-10-12 20:29:51 +08:00
cat-shark 2459b999c6 hud-10: the VR pointer follows the hand that is acting or aiming
ADDENDUM 11. With two hands both report a tracked-pointer ray and the runtime's order
is not "the hand the user is using". updatePointer() took the first valid source and
broke, and pointerDown() called updatePointer(frame) without the select event's
inputSource. On device that pinned the guide line/cursor to one hand while the user
aimed with the other, and made the other hand's pinch land wherever the pinned hand
pointed (left hand controlling the click position, right hand clicking).

updatePointer(frame, preferSrc) now builds a candidate per tracked-pointer source and
pickPointerCand() chooses: the acting source, else the last-active source while it is
on the panel, else any source on the panel, else the last-active source, else the
first. pointerDown() passes the event's inputSource, so an action is always evaluated
with the acting hand's ray, and the choice sticks afterwards. stats.activeSrc reports
it; session end resets it.

pickPointerCand is pure and unit-tested against the built bundle (9 cases, including
the reported one: guide on the left + right pinch -> hand:right, and it stays).

Verified in the headset only up to "no hands tracked at the time"; the live hand
switch still needs a worn headset.
2026-10-12 20:22:29 +08:00
cat-shark 22dd482d69 hud-9: render native (SRT) subtitles in the HUD; stop persisting the layout override
ADDENDUM 10. Two more independent subtitle problems found on device.

1. Normal (non-ASS) subtitles never reached the HUD. Jellyfin's
   htmlVideoPlayer-plugin only routes ssa/ass through SubtitlesOctopus
   (`if (!['ssa','ass'].includes(codec))` -> pgssub/vobsub/custom-element/native);
   subrip falls through to the browser's own TextTrack rendering, so there is no
   libass canvas at all (measured with the CN SRT selected: 0 libass canvases,
   0 .videoSubtitles overlays, textTracks[0] = manualTrack/mode=showing/315 cues).
   No layout setting could have made that work.

   updateSource() now picks the source every XR frame: the libass canvas when it
   exists, otherwise the active TextTrack cue (fallback: the .videoSubtitlesInner
   overlay). The native text is cleaned, wrapped and painted white-on-black into a
   private 1920x1080 canvas that flows through the unchanged crop/upload/HUD path.
   prepare() is skipped when there is no libass canvas. New diagnostics:
   stats.subSource / stats.subNativeText, Subtitles.getSourceKind().

2. ADDENDUM 9 persisted state.subLayout, and a stale 'mono' in jfvr.settings.v1
   silently forced the mono branch on the default dual-eye content (dual:false,
   eyeW:4320, crop across the seam -> both eyes side by side). The override is now
   per-session: not saved, not restored, 'auto' at boot.

Verified on device with hud-9:
  CN_dual_eye (ass)   -> subSource=libass, dual=true, eyeW=2160,
                         crop=[1040,768,1176,924], copyND=0.055
  CN (subrip)         -> subSource=native, dual=false, eyeW=1920, text="进去了呢",
                         crop 256x88, uploads climbing
The private cue canvas was read back and OCR'd (cue "怎么样?好好地" -> "怎么样? 好好地"),
and injecting/removing a fake libass canvas flips subSource with no errors.
2026-10-12 19:53:10 +08:00
cat-shark 164d692791 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.
2026-10-12 16:32:25 +08:00
23 changed files with 5188 additions and 196 deletions
+7 -1
View File
@@ -9,7 +9,7 @@ secrets*.md
# deploy.py --legacy actually uses), so only the legacy one is tracked.
/jfvr-mvp.js
# Temporary offline test page (fake <video> + libass canvas + XR stubs).
_harness.html
_harness*.html
# --- build / tooling noise --------------------------------------------
__pycache__/
@@ -18,3 +18,9 @@ __pycache__/
Thumbs.db
*.swp
*~
# --- .NET plugin build -------------------------------------------------
plugin/**/bin/
plugin/**/obj/
# pack.py output: the packaged plugin zip (distributed via Gitea Releases)
dist/plugin/
+553 -11
View File
@@ -1,10 +1,16 @@
# Jellyfin Web VR180 — 项目交接文档
> 给新对话用。读完这份就能接手,不需要重新调查环境。
> 最后更新:已部署版本 `5217a3`(`NS.version = hud-7`;ADDENDUM 6 字幕深度/大小解耦
> + 7 唤出门限/前面板精简 + 7b 锁按钮与「锁定」面板模式 + 8/8b 画面搬迁(实时拖动))
> 已在 Quest 浏览器里实机验证模块加载 + 锁定数学(`subLockAngle/subAngleDeg`,`errors: []`);
> **VR 会话内的观感还没看过**。
> 最后更新:已部署版本 `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。
---
@@ -116,7 +122,7 @@ Style: RightEye, Alignment=8, MarginL=1920, MarginR=50 , MarginV=700
| `XRWebGLBinding.createQuadLayer` | **true** |
| `XRWebGLBinding.getSubImage` | **需要 2 个参数** `(layer, frame)` |
| `MAX_TEXTURE_SIZE` / `MAX_RENDERBUFFER_SIZE` | **8192 / 16384** |
| 8K HEVC `decodingInfo` | `supported:true, powerEfficient:true` |
| 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"]` |
@@ -380,7 +386,13 @@ cd /home/cat/Desktop/myProject/jelllyfin_vr_web_plugin
# 语法检查(全部模块)
python3 build.py --check
# 构建 + 部署(自动构建 → 上传 → 注入 script 标签)
# ---- 插件路线(推荐)----
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
@@ -395,7 +407,8 @@ python3 deploy.py --legacy
./quest.sh
```
**部署后必须让用户刷新页面**(脚本按页面加载缓存,URL 里的 `?r=<md5前6位>` 是破缓存用的)。
**插件路线**:Jellyfin 里点更新/重装 → 重启 → 刷新浏览器。
**老路线**:部署后必须让用户刷新页面(脚本按页面加载缓存,URL 里的 `?r=<md5前6位>` 是破缓存用的)。
### 诊断信息
@@ -410,6 +423,9 @@ 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 画面搬迁
@@ -423,10 +439,12 @@ errors[] 最近错误
## 10. 长期隐患
1. **注入写在容器内文件**(`/jellyfin/jellyfin-web/index.html`)→
`jellyfin/jellyfin:latest` 一升级就没了,需重跑 `deploy.py`。
正式版应改用 **JavaScript Injector**(`n00bcodr/jellyfin-plugins` 的 `12/manifest.json`,
targetAbi 12.0.0.0)或 **File Transformation**(`IAmParadox27/jellyfin-plugin-file-transformation`,554⭐)。
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 浏览器版本会随系统更新变化** → 能力探测(诊断信息里的能力段)是唯一的自检手段。
@@ -491,3 +509,527 @@ errors[] 最近错误
**手势**(按你的要求):`点一下复位 · 按住 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)现在退居为纯兜底:如果检测结果准了,它就不应该再触发。它仍然保留,作为「声称能播结果没播出来」的最后一道。
---
## 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` 存在的意义。
+315
View File
@@ -976,3 +976,318 @@ double rotation) and schedules no rebuild; unchanged angles reuse the cached spa
rebuild strategy queues at most one, and its observed order is
`removeLayer -> createVideoLayer -> addLayer`; a throwing/absent
`getOffsetReferenceSpace()` is reported and permanently falls back to `rebuild`.
# ADDENDUM 9 — subtitle pipeline survival + normal (mono) subtitles
Two independent defects, found on device with the VR session left in its broken state.
## 1. The rAF broker lost Jellyfin's subtitle loop at session start
`90-main.js` no longer just *forwards* to native `requestAnimationFrame` outside XR. It
**always** holds callbacks in its own queue and drives them with one of two drivers:
- outside XR: a native rAF driver that keeps **exactly one** native callback in flight
(`nativeRafStep` re-arms *before* draining and cancels itself when the queue empty);
- inside XR: `video.requestVideoFrameCallback`, plus a 50 ms idle fallback so a paused /
stalled / ended video still redraws (paused seek, subtitle track switch).
Why: `requestSession('immersive-vr')` stops native rAF completely. Jellyfin 12.x renders
subtitles with SubtitlesOctopus, whose main thread starts **one long-lived rAF loop**
(`rafId`) when the video loads, draws the canvas from it and requests the next prerender
from the worker (`oneshot-render`). A callback still pending in the *native* scheduler when
the session starts is destroyed with it, and because `rafId` stays non-zero the loop is
never restarted.
Evidence (live instance, via CDP closure inspection):
```
rafId : 1150 <- native id, not the plugin's 1e9 range
oneshotState.eventStart: 945.99 <- canvas frozen ~7 min behind the playhead
renderRequested : false
oneshot-render requests during 15 s of playback: 0
```
After the fix, in a live VR session: `rafId = 1000028035`, `eventStart` follows
`video.currentTime`, and `stats.subUploads` climbs while subtitles change.
`startRafPump()` must **not** clear the queue (that callback is the one being rescued) and
must drop the stale `nativeId`. `stopRafPump()` re-arms the native driver.
## 2. Auto dual-eye / mono subtitle layout
`10-subtitles.js` used to assume the libass canvas is a stereo left/right pair and always
sampled the **left half**. A normal subtitle (e.g. the `CN` SRT track) is centred across the
whole 2:1 frame, so half of it was cut off.
`state.subLayout` (`'auto' | 'dual' | 'mono'`, default `'auto'`, persisted) selects the
region; `stats.subLayout / subDual / subEyeW / subCopyND / subCenterInk` report it.
Per sample (on the 320×160 downsample) the module builds the ink box and column count of
each half plus the ink in a ±40 source-px band around the seam, then:
```
only the left half has ink -> dual (sample the left half)
only the right half has ink -> mono (sample the whole width)
ink crosses the seam -> mono
both halves, seam empty -> columnCopyND < COPY_TOL ? dual : mono
```
**Dual-eye is NOT a pixel mirror.** Both eyes carry the *same* text at mirrored *positions*;
the glyphs are not flipped, so `left[x]` vs `right[W-1-x]` fails badly (measured mean delta
258/1020 → "not a mirror"). What is true is that the two halves' ink **column profiles**
match under a small horizontal shift, because they are the same line. Measured on device:
| layout | centre-band ink | column-copy distance |
|---|---|---|
| dual-eye (`CN_dual_eye`) | 0 | 0.02 – 0.08 |
| mono (`CN` SRT) | 50 / frame | 1.00 |
`COPY_TOL = 0.25`. A layout change is debounced (two consecutive samples) because it
rebuilds the layer.
`M.eyeW` is one eye's region width (half for dual, full for mono); `computeTexDims()`,
`drawHud()`'s crop/clamp and the texture scale all use it instead of the old hard-coded
`halfW`.
### API additions
```js
__JFVR.Subtitles.setLayout('auto' | 'dual' | 'mono') // also state.subLayout
__JFVR.Subtitles.getLayout(): string
```
## 3. Verification
- Broker logic replicated exactly in a Node harness against the built bundle:
`maxConcurrentNative = 1` over 300 frames with a self-rescheduling loop (the first
version re-armed during the drain and doubled the driver every frame — that froze the
page); simulating session start (native callbacks dropped) leaves the loop in the queue
and it keeps firing from the XR driver.
- `columnCopyND` extracted from the built bundle and exercised with the on-device
measurements: dual 0.00–0.08 → `dual`, mono centre-ink → `mono`, no-copy word-gap
profile 0.41 → `mono`.
- On device (before the UI became unreachable): the broker change was observed to carry
SubtitlesOctopus's loop through `immersive-vr` (`rafId` in the plugin's id range,
`eventStart` tracking, `subUploads` 4 → 7 over 20 s in VR).
# ADDENDUM 10 — normal (non-ASS) subtitles: Jellyfin does not use libass for them
## 1. Why normal subtitles were invisible
The HUD samples `canvas.libassjs-canvas`. That canvas only exists when Jellyfin
routes the subtitle through **SubtitlesOctopus (libass)**. From
`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 overlay
/* else falls through to the native TextTrack path */
}
return renderSsaAss(...); // ssa/ass ONLY
```
So `subrip`/`vtt`/… never reach libass. Observed on device with the `CN` SRT track
selected: `canvas.libassjs-canvas` count **0**, `.libassjs-canvas-parent` 0,
`.videoSubtitles` 0 — and `video.textTracks[0] = { kind:'subtitles', label:'manualTrack',
mode:'showing', cues:315 }`, i.e. the **browser** is rendering the cues through
`::cue`. There was nothing for the plugin to read, at any layout setting.
## 2. What the module does now
`updateSource()` runs every XR frame and picks the source:
- a `canvas.libassjs-canvas` with a non-zero size → `srcKind = 'libass'` (unchanged path);
- otherwise, if the player has a showing TextTrack or a `.videoSubtitlesInner`
overlay → `srcKind = 'native'`. The active text comes from
`textTracks[i].activeCues` (fallback: the DOM overlay's `innerText`), is cleaned
of ASS/HTML tags and bidi marks, wrapped, and painted — white with a black outline,
centred — into a private 1920×1080 canvas. That canvas is fed through the exact
same crop/bbox/upload code as the libass one.
- neither → `srcKind = 'none'` and the strip is cleared once.
`prepare()` is a no-op without a libass canvas (blowing up the player box is only
needed so libass re-renders bigger; the native canvas is ours).
New diagnostics: `stats.subSource` (`'libass' | 'native' | 'none'`),
`stats.subNativeText`; `__JFVR.Subtitles.getSourceKind()`.
## 3. The persisted layout override was a trap
ADDENDUM 9 persisted `state.subLayout`. A stale `'mono'` in `jfvr.settings.v1`
silently forced the mono branch on the default **dual-eye** content: `dual:false`,
`eyeW:4320`, and a crop spanning the seam, so the HUD showed both eyes' text side by
side. Debugging that cost more time than the detection itself.
`subLayout` is therefore **not persisted** (same reasoning as `subtitles` and
`subMode:'off'` — a stored value that leaves the layer looking broken). It is
`'auto'` at boot, toggleable per session from the panel.
## 4. Verification (on device, build `hud-9`)
| selected track | `subSource` | result |
|---|---|---|
| `CN_dual_eye` (ass, idx 0) | `libass` | `dual:true`, `eyeW:2160`, `crop:[1040,768,1176,924]` (left half), `copyND:0.055`, uploads climbing |
| `CN` (subrip, idx 1) | `native` | `dual:false`, `eyeW:1920`, canvas 1920×1080, `text:"进去了呢"`, `crop` 256×88, uploads climbing |
The private cue canvas was read back and OCR'd ("怎么样? 好好地" for cue
"怎么样?好好地"), and injecting/removing a fake `canvas.libassjs-canvas` flips
`subSource` between `libass` and `native` with no errors.
# ADDENDUM 11 — the pointer follows the hand that is acting / aiming
With two hands, BOTH report a `tracked-pointer` ray, and the runtime's order is not
"the hand the user is using". `updatePointer()` took the **first** input source with
a valid ray and `break`ed, and `pointerDown()` called `updatePointer(frame)` without
passing the source from the `select` event. Consequences on device:
- the guide line / cursor stayed pinned to one hand even while the user aimed with
the other (so the guide did not point where they were pointing);
- the other hand's pinch landed **wherever the pinned hand pointed** — the left hand
controlled the click position while the right hand performed the click.
`updatePointer(frame, preferSrc)` now builds a candidate per tracked-pointer source
(with its `panelHit`), and `pickPointerCand()` chooses:
```
1. preferSrc the source acting right now (select / gamepad press)
2. last-active source while it is aiming at the panel (hit.inBounds)
3. any source aiming at the panel (first in runtime order)
4. last-active source (sticky)
5. the first source
```
`pointerDown()` passes the event's `inputSource`, so an action is always evaluated
with the acting hand's ray, and the choice sticks afterwards (`state.stats.activeSrc`).
`pointerUp`/session end reset it.
### Verification
There is no official way to fake hand input on a Quest for a WebXR page: Meta's
simulator (the only "simulate aim/poke/pinch/grab" tool in the docs) is a desktop
tool for Unity/Unreal native apps, `adb` has no input-injection for XR, and CDP has
no WebXR domain. So the live check injected **synthetic input sources** from the page:
each `targetRaySpace` is a real `XRRigidTransform` offset reference space of the live
session, and a press is driven through the real gamepad path (a rising edge on
`gamepad.buttons[0]`), which reaches the same `pointerDown(src, frame, …)` the
`select` event uses. `XRSession.prototype.inputSources` is overridden for the test and
restored afterwards.
Measured in a live `immersive-vr` session:
```
initial pointer hand:left HIT 0.22,0.50 activeSrc hand:left
right hand press pointer hand:right HIT 0.78,0.50 activeSrc hand:right lastActivate gamepad:right
right hand release pointer hand:right HIT 0.78,0.50 (sticky)
left hand press pointer hand:left HIT 0.22,0.50 activeSrc hand:left
right press, right hand NOT on panel
pressAt "MISS (not aiming at the panel)" <- did NOT use the left hand's position
```
`pickPointerCand` is also extracted from the built bundle and unit-tested (9 cases).
# ADDENDUM 11b — the cursor sits ON the guide line; a press is attributed to the acting hand
Two follow-ups reported against ADDENDUM 11.
## 1. The cursor drifted off the guide line, worse near the panel edge
`panelHit()` clamps an intersection that misses the panel to the border and returns
`inBounds` to say so, but `updatePointer()` published that clamped `nx,ny` as
`pointer.hit`. The cursor ring was therefore drawn **on the panel border** while the
beam ended at the true intersection, which is off the panel: the further off the panel
the ray pointed, the larger the gap — exactly as reported.
`pointer.hit` is now published **only when `hit.inBounds`** the cursor exists only where
the ray really meets the panel, so it always lies on the beam. `distance` is still
published whenever the ray meets the panel plane, and `beamLength()` no longer requires
`p.hit`, so an edge-aimed beam still reaches the plane. Near-misses keep summoning the
bar (the wide `panelHit(...,0.5,0.9)` check is unchanged), but they no longer press.
## 2. A right-hand press could still act at the left hand's position
Three separate causes, all fixed:
- **The cooldown was global.** `ACTIVATE_COOLDOWN_MS` (250 ms) suppressed *any* press
within 250 ms of the previous one, so a stray gamepad edge from one hand swallowed the
other hand's `select` — and the action then used the first hand's pointer. The cooldown
is now **per input source** (`lastActivateByKey`), so it still de-duplicates the
gamepad/`select` pair of one pinch but never eats the other hand's press.
- **A missing ray silently fell back to the other hand.** If the acting source's ray
could not be resolved, `pickPointerCand` skipped to the next candidate. Now, when a
`preferKey` (the acting source) is supplied, it **owns the shot**: if it is not among
the candidates the pick is `null` and the press MISSES.
- **A null frame meant no re-attribution at all.** `pointerDown()` did
`if (frame) updatePointer(...)`, so with no frame the per-frame pointer (possibly the
other hand) was used silently. It now falls back to `S.lastFrame`, and when the acting
source still yields no pointer it reports `MISS (acting source has no ray)`.
New diagnostics: `stats.pressSrc` (the source key the press was attributed to) and
`stats.pressPtr` (`hand:right HIT` / `hand:right nohit` / `(no ray)`).
## Verification (injected synthetic input sources, live session)
```
both hands on panel, right press pressSrc hand:right pressPtr "hand:right HIT" pressAt 0.78,0.50 seek 79.5%
left press then right 100 ms later pressSrc hand:right pressAt 0.78,0.50 (right not swallowed)
both hands off panel state.pointer.hit = null (no clamped cursor)
both off panel, right press pressSrc hand:right pressPtr "hand:right nohit"
pressAt "MISS (no hit on the panel)" (did NOT use the left hand)
```
# ADDENDUM 12 — one pointer owner: the dominant hand, taken over by a press
The pointer was symmetric: whichever hand acted last owned it, and when neither had
acted the first source in runtime order won — which is the LEFT hand on this runtime, so
a right-handed user's guide line sat on the non-dominant hand. Two hands could also
disturb each other's holds.
## 1. One owner (a mouse-like single cursor)
`pickPointerCand(cands, preferKey, ownerKey, prefHand)`:
```
preferKey (the acting source) -> that source, or null => the press MISSES
owner aiming at the panel -> owner
the preferred hand aiming at the panel -> preferred hand
any hand aiming at the panel -> that hand
owner (not aiming) -> owner
the preferred hand (not aiming) -> preferred hand
-> the first source
```
- **`state.handPref`** (`'right' | 'left'`, default `'right'`) is the pointer's default
owner — the dominant hand. Set from the pre-VR panel ("操作 → 主用手"), persisted in
`jfvr.settings.v1`. It applies at the start of a session; during a session the owner
simply sticks.
- **A press takes the pointer over** (`preferKey`), and the owner then sticks to that
hand while it is aiming.
## 2. The hands can no longer disturb each other
- **Hold exclusion:** while a hold/drag started by one source is in progress
(`grab` / `viewDrag`), a press from the OTHER source is ignored
(`stats.pressAt = 'IGNORED (other hand is holding)'`).
- **Source-matched release:** `pointerUp(src)` only ends a hold that `src` started.
It used to be argument-less, so *either* hand's release cancelled the other hand's
subtitle grab / picture pan. `onSelectEnd(ev)` and `pollGamepads` now pass their
source. `grab` / `viewDrag` carry a `key`.
- **Stale holds:** `dropStaleHolds()` runs each frame and ends a hold whose source has
left `session.inputSources` (hand tracking lost) — otherwise no release would ever
arrive and the drag would stick.
New diagnostics: `stats.handPref`, `stats.owner` (= `stats.activeSrc`), plus the
existing `pressSrc` / `pressPtr`.
## Verification (injected synthetic input sources, live session)
```
default (handPref=right), both hands on panel pointer hand:right HIT 0.78,0.50 (was hand:left)
handPref=left (persisted, fresh session) pointer hand:left HIT 0.22,0.50
left press, release owner hand:left, still left afterwards
right holds picture-pan, left press pressAt "IGNORED (other hand is holding)"
right holds picture-pan, LEFT releases viewDrag stays "armed" (drag survives)
right holds picture-pan, RIGHT releases viewDrag "reset (tap)" (drag ends)
```
+159 -4
View File
@@ -16,9 +16,149 @@ VR180 / VR360 沉浸播放,不用再手动切全屏 + 选投影。
| 备份 | `/vol2/jellyfin/config/_vr_backup/index.html.orig` |
| 两个入口都生效 | `http://192.168.123.199:8096/web/` 与 `https://jellyfin.cat-shark.xyz/web/` |
> ⚠️ 注入写在**容器内文件**里,`jellyfin/jellyfin:latest` 一升级就没了,重跑 `deploy.py` 即可。
> 正式版应改用 **JavaScript Injector 插件**(`n00bcodr/jellyfin-plugins` 的 `12/manifest.json`,targetAbi 12.0.0.0)
> 或 **File Transformation**,这样升级不丢、可开关。
> ⚠️ 老路子(`deploy.py`):注入写在**容器内文件**里,`jellyfin/jellyfin:latest` 一升级就没了,
> 得重跑 `deploy.py`。**现在已经有插件版了,见下面 §1.1,优先用插件。**
### 1.1 插件化(推荐,已实现)
JFVR 同时也是一个标准的 **Jellyfin 插件**,通过自建 Gitea 仓库分发,走 Dashboard 的
「添加存储库 → Catalog 安装」,**不再改容器内任何文件**。
| 项 | 值 |
|---|---|
| 插件仓库地址 | `https://git.cat-shark.xyz/cat-shark/jellyfin_vr_web_plugin/raw/branch/main/manifest.json` |
| 插件名 / GUID | `Jellyfin Web VR` / `7d33ef59-f9b0-412b-93bd-5cd5353018de` |
| 目标 ABI | `12.0.0.0`(Jellyfin 只保留 `targetAbi <= 服务器版本` 的条目,所以一份包覆盖整个 12.x) |
| 插件代码 | `plugin/Jellyfin.Plugin.JFVR/`(C#,net10.0,对 `Jellyfin.Controller 12.1.0`) |
| 打包 / 发布 | `python3 pack.py` / `python3 pack.py --bump --publish` |
| 脚本端点 | `/JFVR/jfvr.js`(bundle 内嵌在 DLL 里,URL 带内容哈希做缓存键) |
| 状态查询 | `/JFVR/status` |
| 设置页 | Dashboard → 插件 → Jellyfin Web VR(开关注入 / 覆盖脚本 URL) |
| 页面按钮 | 「VR 播放」按钮**可拖动**(位置记住;双击回到默认右下角) |
**安装**:Dashboard → 插件 → 目录 → ⚙️ → ➕ → 粘贴上面的仓库地址 → 保存 →
在 Catalog 里找到 **Jellyfin Web VR** → 安装 → **重启 Jellyfin**。
**工作方式**:`ScriptInjectionStartupFilter` 在**请求时**把
`<script plugin="JFVR" src="../JFVR/jfvr.js?v=<hash>" defer></script>`
插到 `index.html` 的 `</body>` 之前。磁盘上的 `/jellyfin/jellyfin-web/` 一个字节都不动,
所以升级 Jellyfin 不会丢。如果检测到老 `deploy.py` 留下的 `<script plugin="JellyfinVR" ...>`,
会**自动清掉**,不会重复加载 bundle。
**改完 web 代码后的流程**:
```bash
python3 pack.py --bump --publish # 构建 → 打包 → 建 Release → 推 manifest
# 然后在 Jellyfin 里:插件页点更新(或重装),重启,刷新浏览器
```
> 老路子仍然可用,作为插件的兜底:`JF_PW=... python3 deploy.py`。
> 但**两者不要同时开** —— 装了插件就别再跑 `deploy.py`(跑完插件也会把那个标签清掉)。
### 1.2 播放看门狗(卡住检测)
`src/40-watchdog.js`。针对一种很坑的失败:**某些设备/浏览器放不出来时,Jellyfin 的播放器界面根本不会被创建**。
原因(已从 Jellyfin Web 源码确认):播放器 UI 只在 `playbackstart` 事件之后构建,而 `playbackstart` 要等媒体真的起来了才会触发。加载顺序是:
```
HtmlVideoPlayer.play() htmlVideoPlayer/plugin.js:502
createMediaElement() :1802 转圈 + <div.videoPlayerContainer> + <video>
(此时还没 src)
setCurrentSrc() :593 elem.src = url
→ loadedmetadata → canplay → play → 'playbackstart'
→ OSD 控制器(apps/legacy/controllers/playback/video/index.js:591)
```
媒体起不来 → `playbackstart` 不触发 → **码率菜单根本不存在**,页面上只剩一个转圈和一个 `videoWidth === 0` 的 `<video>`。所以「卡住之后调不了码率」不是菜单藏起来了,是菜单还没被创建。
看门狗就盯这个状态(`.videoPlayerContainer` 里的 `<video>` 仍然是 `videoWidth === 0`):
| | 阈值 |
|---|---|
| 媒体报错(`video.error`) | 立即弹 |
| 直连没画面 | 15 秒 |
| 转码(src 已经是 hls) | 45 秒(服务器要先出片) |
| 已经有画面 | 立即退出,不打扰 |
| VR 会话中 | 完全不跑 |
弹窗会写明**具体格式**(走 Jellyfin API 查 MediaStreams),并给 20/8/3 Mbps 三档 + 「继续等待」。选一档后写入 Jellyfin 自己那套 localStorage 键然后重载:
```
maxbitrate-Video-<true|false> = 20000000
enableautobitratebitrate-Video-<true|false> = false
```
> 注意 `enableautobitratebitrate` 里 `bitrate` 确实出现了两次 —— 这是 Jellyfin 上游的拼写,照抄的。
> 之所以不用 `playbackManager.setMaxStreamingBitrate()`:那个模块没暴露到 window(已实测 `window.playbackManager === undefined`,`window.Emby` 只剩 `Page`),所以只能写设置 + 重载。
选过之后 120 秒内不再打扰(记在 sessionStorage)。
### 1.3 让客户端如实上报解码能力(`canPlayType` 覆盖)
`src/00-core.js`。解决的问题:**Jellyfin 的直连/转码决策 100% 看客户端上报的设备档案**,而 Jellyfin Web 是从 `canPlayType` 推出整个 HEVC 声明的(`browserDeviceProfile.js`):
```js
if (canPlayType('video/mp4; codecs="hvc1.2.4.L183"')) {
maxHevcLevel = 183; // level 6.1 = 8K
hevcProfiles = 'main|main 10';
}
```
`canPlayType` 回答的是「这台机器*有没有* HEVC 解码器」,不是「能不能解 8192×4096 的 Main 10 @60fps」。所以一个只是「系统里有 HEVC 解码器」的桌面浏览器会声称支持 8K Main 10 → 服务器选 DirectPlay → 黑屏(而 OSD 压根不会创建,见 §1.2)。
插件的做法:
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 文件超出声明 → **服务器自动转码** |
| Quest 3(真能解 8K Main 10) | 保持 ≥183 → **继续 Direct Play** |
注意:这里**不问用户任何东西**。客户端如实上报,Jellyfin 在 `PlaybackInfo` 那一步自己选 Transcode —— 这正是「提示用户切码率」想要达到的目的,只是做在了正确的层。
逃生开关:
```js
localStorage['jfvr-cpt'] = 'off'; // 完全关掉钩子
localStorage['jfvr-cpt-keep'] = '2:183'; // 只保留某一档(单台设备误报时用,不用整个关掉)
```
当前状态可以在诊断面板里看到,每档会写明**为什么**被拦(`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 播放」按钮可以拖了
原来钉死在右下角(`right:16px; bottom:120px`),窗口矮的时候正好压在播放看门狗弹窗的码率按钮上,没地方躲。
现在:
- 用 `left/top` 定位(不再用 `right/bottom`),用 pointer 事件拖动,位置记在 `localStorage['jfvr-btn-pos']`
- `touch-action:none` —— 不加这个,触屏上拖动会变成滚动页面
- **拖动结束仍然会触发一次 click**,代码会把那一次吃掉,所以拖完不会意外弹出面板
- 限制在视窗内,窗口缩放时会重新夹紧
- **双击回到默认右下角**(拖到尴尬位置时的逃生口)
- 设置面板跟着按钮走(不再是钉在视窗角落),优先放在按钮上方,上方放不下就放下方,再放不下就夹在屏幕内
---
@@ -41,10 +181,14 @@ UA Mozilla/5.0 (X11; Linux x86_64; Quest 3) ... Chrome/152 ... VR Safari/537.36
| `XRWebGLBinding` | — | true ← 回退路径可用 |
| `MAX_TEXTURE_SIZE` | 8192 | 8192 |
| `MAX_RENDERBUFFER_SIZE` | 16384 | 16384 |
| 8K HEVC `decodingInfo` | supported / powerEfficient | **supported:true, powerEfficient:true** |
| 8K HEVC `decodingInfo` | supported / powerEfficient | **supported:true, powerEfficient:true**(仅 8-bit Main) |
结论:**HTTPS 下 Quest 浏览器提供全部所需 WebXR 能力,8K HEVC 走硬件解码。**
> ⚠️ 上面那行 `decodingInfo` 当年只测了 **8-bit Main** 的 codec string(`hev1.1.6.L183.B0`),
> **10-bit Main 10(`hev1.2.4.L183.B0`)从来没测过**。插件现在会分档探测(见 §1.3),
> 诊断面板里会列出 Main/Main10 × 4K/8K 的真实结果。
### 2.1 网络实测:HTTPS 域名在 Quest 上就是内网直连
```
@@ -255,6 +399,16 @@ WebXR 规范原文:
## 8. 修改 / 部署 / 回滚
### 8.1 插件(推荐)
```bash
python3 pack.py --bump --publish # 构建 + 打包 + 建 Release + 推 manifest.json
```
然后在 Jellyfin 里更新插件并重启,刷新浏览器。
### 8.2 老路子:直接注入容器内文件(兜底)
```bash
# 改 jfvr-mvp.js 后重新部署
JF_PW='<ssh密码>' python3 deploy.py
@@ -264,6 +418,7 @@ JF_PW='<ssh密码>' python3 deploy.py rollback
```
`deploy.py` 用文件 md5 前 6 位作为版本号写进 script 标签的 query,自动破缓存。
插件走的是同一套破缓存思路,只是 hash 由 DLL 内嵌 bundle 的 md5 算出来。
---
+1 -1
View File
@@ -21,7 +21,7 @@ SRC = os.path.join(HERE, "src")
DIST = os.path.join(HERE, "dist")
OUT = os.path.join(DIST, "jfvr.js")
ORDER = ["00-core.js", "10-subtitles.js", "20-controls.js", "30-hands.js", "90-main.js"]
ORDER = ["00-core.js", "10-subtitles.js", "20-controls.js", "30-hands.js", "40-watchdog.js", "90-main.js"]
def sources():
+1435 -90
View File
File diff suppressed because it is too large Load Diff
+76
View File
@@ -0,0 +1,76 @@
[
{
"name": "Jellyfin Web VR",
"guid": "7d33ef59-f9b0-412b-93bd-5cd5353018de",
"overview": "VR180/VR360 playback inside Jellyfin Web for Meta Quest 3.",
"description": "Injects a \"VR 播放\" button into the Jellyfin Web video player page and drives an immersive WebXR session on Meta Quest 3, preferring XRMediaBinding.createEquirectLayer and falling back to XRWebGLBinding. Ships equirectangular 180/360 plus SBS/OU layouts, in-headset subtitles, a wrist controller, and hand tracking.\n",
"owner": "cat-shark",
"category": "General",
"versions": [
{
"version": "0.5.2.0",
"targetAbi": "12.0.0.0",
"changelog": "Bundle version: `16ae94`\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.2.0/Jellyfin.Plugin.JFVR_12.0.0.0.zip",
"checksum": "C5BD8E8C384642D4502BE1A0F80B8E68",
"timestamp": "2026-10-19T15:01:57"
},
{
"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",
"changelog": "Bundle version: `72681d`\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.0.0/Jellyfin.Plugin.JFVR_12.0.0.0.zip",
"checksum": "F9773C70C9CC4858AF042E40D5CFBAA9",
"timestamp": "2026-10-17T17:34:28"
},
{
"version": "0.4.0.0",
"targetAbi": "12.0.0.0",
"changelog": "Bundle version: `ae28bd`\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.4.0.0/Jellyfin.Plugin.JFVR_12.0.0.0.zip",
"checksum": "30A0E388FFD6A3D88C73DAB5928C6388",
"timestamp": "2026-10-17T17:20:34"
},
{
"version": "0.3.0.0",
"targetAbi": "12.0.0.0",
"changelog": "Bundle version: `4e9a8f`\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.3.0.0/Jellyfin.Plugin.JFVR_12.0.0.0.zip",
"checksum": "1BFAF246451C090E351F9DDD516BD4DC",
"timestamp": "2026-10-17T17:08:08"
},
{
"version": "0.2.0.0",
"targetAbi": "12.0.0.0",
"changelog": "Bundle version: `edca47`\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.2.0.0/Jellyfin.Plugin.JFVR_12.0.0.0.zip",
"checksum": "355DD18DC228A6586334431518C4B60D",
"timestamp": "2026-10-17T16:28:23"
},
{
"version": "0.1.0.1",
"targetAbi": "12.0.0.0",
"changelog": "Bundle version: `917fde`\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.1.0.1/Jellyfin.Plugin.JFVR_12.0.0.0.zip",
"checksum": "5BB9DA51A50C5449E7C1D0D6602E8813",
"timestamp": "2026-10-17T15:33:14"
},
{
"version": "0.1.0.0",
"targetAbi": "12.0.0.0",
"changelog": "Bundle version: `917fde`\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.1.0.0/Jellyfin.Plugin.JFVR_12.0.0.0.zip",
"checksum": "F9CC1843F0B9386A9E990669112FF533",
"timestamp": "2026-10-17T15:25:41"
}
]
}
]
+451
View File
@@ -0,0 +1,451 @@
#!/usr/bin/env python3
"""
Build the JFVR Jellyfin plugin, package it the way Jellyfin expects, and
(optionally) publish it to the Gitea repo that doubles as the plugin catalog.
What it does, in order:
1. build.py src/*.js -> dist/jfvr.js
2. dotnet build plugin/Jellyfin.Plugin.JFVR -> Jellyfin.Plugin.JFVR.dll
(the bundle is embedded straight from dist/jfvr.js)
3. verify the DLL really contains the bytes we just built
4. zip one DLL, named <assembly>_<targetAbi>.zip
5. manifest.json add/replace this version's entry (MD5 = the zip's MD5,
which Jellyfin re-checks at install time)
6. --publish create the Gitea release, upload the zip, push the
manifest so Jellyfin can see it
Usage:
python3 pack.py # build + package + update manifest.json
python3 pack.py --bump # same, after bumping the last version field
python3 pack.py --version 0.2.0.0 # same, with an explicit version
python3 pack.py --publish # ... and publish to Gitea
python3 pack.py --print-urls # just show the catalog URL
Env:
GITEA_TOKEN required by --publish. Scope: write:repository.
Falls back to a GITEA_TOKEN line in secrets.local.md.
GITEA_URL default https://git.cat-shark.xyz
GITEA_REPO default cat-shark/jellyfin_vr_web_plugin
GITEA_BRANCH default main
DOTNET path to the dotnet binary (default: $PATH, then ~/.dotnet/dotnet)
"""
import argparse
import hashlib
import json
import os
import re
import shutil
import subprocess
import sys
import urllib.error
import urllib.request
import uuid
import zipfile
from datetime import datetime, timezone
import yaml
HERE = os.path.dirname(os.path.abspath(__file__))
PLUGIN_DIR = os.path.join(HERE, "plugin")
BUILD_YAML = os.path.join(PLUGIN_DIR, "build.yaml")
PROJECT = os.path.join(PLUGIN_DIR, "Jellyfin.Plugin.JFVR", "Jellyfin.Plugin.JFVR.csproj")
BUNDLE = os.path.join(HERE, "dist", "jfvr.js")
OUT_DIR = os.path.join(HERE, "dist", "plugin")
MANIFEST = os.path.join(HERE, "manifest.json")
SECRETS = os.path.join(HERE, "secrets.local.md")
ASSEMBLY = "Jellyfin.Plugin.JFVR"
MAX_VERSIONS = 20
GITEA_URL = os.environ.get("GITEA_URL", "https://git.cat-shark.xyz").rstrip("/")
GITEA_REPO = os.environ.get("GITEA_REPO", "cat-shark/jellyfin_vr_web_plugin")
GITEA_BRANCH = os.environ.get("GITEA_BRANCH", "main")
# ---------------------------------------------------------------- helpers
def run(cmd, **kw):
"""Run a command, echo it, and abort on failure."""
print("$ " + " ".join(cmd))
r = subprocess.run(cmd, capture_output=True, text=True, **kw)
if r.stdout.strip():
print(r.stdout.rstrip())
if r.returncode != 0:
print(r.stderr.rstrip(), file=sys.stderr)
sys.exit("command failed: %s" % cmd[0])
if r.stderr.strip():
print(r.stderr.rstrip(), file=sys.stderr)
return r
def dotnet_bin():
explicit = os.environ.get("DOTNET")
if explicit:
return explicit
found = shutil.which("dotnet")
if found:
return found
local = os.path.expanduser("~/.dotnet/dotnet")
if os.path.exists(local):
return local
sys.exit("dotnet not found. Install the .NET 10 SDK, or set DOTNET=/path/to/dotnet")
def md5_of(path):
h = hashlib.md5()
with open(path, "rb") as fh:
for chunk in iter(lambda: fh.read(1 << 20), b""):
h.update(chunk)
return h.hexdigest().upper()
def bundle_version():
"""The 6-char version the in-page HUD reports (build.py uses the same rule)."""
with open(BUNDLE, "rb") as fh:
return hashlib.md5(fh.read()).hexdigest()[:6]
def read_build_yaml():
with open(BUILD_YAML, encoding="utf-8") as fh:
return yaml.safe_load(fh)
def bump(version):
parts = version.split(".")
while len(parts) < 4:
parts.append("0")
parts[-1] = str(int(parts[-1]) + 1)
return ".".join(parts)
def write_build_yaml_version(version):
with open(BUILD_YAML, encoding="utf-8") as fh:
text = fh.read()
text = re.sub(r'^version:\s*".*?"', 'version: "%s"' % version, text, count=1, flags=re.M)
with open(BUILD_YAML, "w", encoding="utf-8") as fh:
fh.write(text)
def catalog_url():
return "%s/%s/raw/branch/%s/manifest.json" % (GITEA_URL, GITEA_REPO, GITEA_BRANCH)
def source_url(tag, asset):
return "%s/%s/releases/download/%s/%s" % (GITEA_URL, GITEA_REPO, tag, asset)
# ---------------------------------------------------------------- gitea
def gitea_token():
token = os.environ.get("GITEA_TOKEN")
if token:
return token.strip()
if os.path.exists(SECRETS):
with open(SECRETS, encoding="utf-8") as fh:
for line in fh:
m = re.match(r"^\s*GITEA_TOKEN\s*[:=]\s*(\S+)", line)
if m:
return m.group(1)
sys.exit(
"--publish needs a Gitea token.\n"
"Create one at %s/user/settings/applications (scope: write:repository)\n"
"then export GITEA_TOKEN=... or add a 'GITEA_TOKEN: ...' line to secrets.local.md"
% GITEA_URL
)
def gitea_request(method, path, token, body=None, ctype="application/json"):
url = "%s/api/v1%s" % (GITEA_URL, path)
data = json.dumps(body).encode() if body is not None else None
req = urllib.request.Request(url, data=data, method=method)
req.add_header("Authorization", "token " + token)
req.add_header("Content-Type", ctype)
try:
with urllib.request.urlopen(req, timeout=60) as resp:
raw = resp.read()
return resp.status, (json.loads(raw) if raw else None)
except urllib.error.HTTPError as e:
raw = e.read()
try:
return e.code, json.loads(raw)
except Exception:
return e.code, raw.decode("utf-8", "replace")
def multipart(fields, files):
boundary = "----JFVR" + uuid.uuid4().hex
out = bytearray()
for key, value in fields.items():
out += ('--%s\r\nContent-Disposition: form-data; name="%s"\r\n\r\n%s\r\n'
% (boundary, key, value)).encode()
for key, (filename, data, ctype) in files.items():
out += ('--%s\r\nContent-Disposition: form-data; name="%s"; filename="%s"\r\n'
'Content-Type: %s\r\n\r\n' % (boundary, key, filename, ctype)).encode()
out += data + b"\r\n"
out += ("--%s--\r\n" % boundary).encode()
return bytes(out), "multipart/form-data; boundary=%s" % boundary
def publish(tag, meta, zip_path, asset_name, changelog, token):
path = "/repos/%s/releases/tags/%s" % (GITEA_REPO, tag)
status, release = gitea_request("GET", path, token)
if status == 200:
print("release %s already exists (id %s)" % (tag, release["id"]))
else:
status, release = gitea_request("POST", "/repos/%s/releases" % GITEA_REPO, token, {
"tag_name": tag,
"name": "%s %s" % (meta["name"], tag),
"body": changelog,
"draft": False,
"prerelease": False,
})
if status not in (200, 201):
sys.exit("creating release %s failed (%s): %s" % (tag, status, release))
print("created release %s (id %s)" % (tag, release["id"]))
release_id = release["id"]
for asset in release.get("assets") or []:
if asset["name"] == asset_name:
gitea_request("DELETE",
"/repos/%s/releases/%s/assets/%s" % (GITEA_REPO, release_id, asset["id"]),
token)
print("replaced existing asset %s" % asset_name)
with open(zip_path, "rb") as fh:
payload, ctype = multipart({}, {"attachment": (asset_name, fh.read(), "application/zip")})
url = "%s/api/v1/repos/%s/releases/%s/assets?name=%s" % (GITEA_URL, GITEA_REPO, release_id, asset_name)
req = urllib.request.Request(url, data=payload, method="POST")
req.add_header("Authorization", "token " + token)
req.add_header("Content-Type", ctype)
try:
with urllib.request.urlopen(req, timeout=300) as resp:
json.loads(resp.read())
except urllib.error.HTTPError as e:
sys.exit("uploading %s failed (%s): %s" % (asset_name, e.code, e.read().decode("utf-8", "replace")))
print("uploaded %s" % asset_name)
def head_ok(url):
"""A draft release 404s on its download URL; verify the asset is really live."""
req = urllib.request.Request(url, method="HEAD")
try:
with urllib.request.urlopen(req, timeout=60) as resp:
return resp.status, resp.headers.get("Content-Length")
except urllib.error.HTTPError as e:
return e.code, None
def fetch_md5(url):
"""Download the published asset and hash it -- exactly what Jellyfin does.
This is the check that catches a manifest whose checksum no longer matches the
uploaded zip (a real failure mode: the install then dies with
"The checksum of the received data doesn't match.").
"""
h = hashlib.md5()
req = urllib.request.Request(url, method="GET")
with urllib.request.urlopen(req, timeout=300) as resp:
while True:
chunk = resp.read(1 << 20)
if not chunk:
break
h.update(chunk)
return h.hexdigest().upper()
# ---------------------------------------------------------------- steps
def build_bundle():
run([sys.executable, os.path.join(HERE, "build.py")], cwd=HERE)
def build_plugin(version):
env = dict(os.environ)
dotnet = dotnet_bin()
env["DOTNET_ROOT"] = os.path.dirname(dotnet)
env["DOTNET_CLI_TELEMETRY_OPTOUT"] = "1"
env["DOTNET_NOLOGO"] = "1"
run([dotnet, "build", PROJECT, "-c", "Release", "-p:Version=" + version], cwd=HERE, env=env)
dll = os.path.join(os.path.dirname(PROJECT), "bin", "Release", "net10.0", ASSEMBLY + ".dll")
if not os.path.exists(dll):
sys.exit("expected build output missing: %s" % dll)
return dll
def verify_embedded(dll):
"""Guard against shipping a DLL whose embedded bundle is not what we built."""
with open(dll, "rb") as fh:
blob = fh.read()
with open(BUNDLE, "rb") as fh:
bundle = fh.read()
at = blob.find(bundle)
if at < 0:
sys.exit("the built DLL does not contain dist/jfvr.js -- refusing to package")
if int.from_bytes(blob[at - 4:at], "little") != len(bundle):
sys.exit("embedded bundle length prefix mismatch -- refusing to package")
print("verified: DLL embeds %d bytes of dist/jfvr.js (md5 %s)" % (len(bundle), bundle_version()))
def make_zip(dll, target_abi):
"""Package the DLL the way Jellyfin expects: one file, named after the assembly.
The entry gets a fixed timestamp on purpose. zip stores mtimes, so packaging
the same DLL twice would otherwise produce different bytes, a different MD5,
and a manifest checksum that no longer matches the already-uploaded asset.
"""
os.makedirs(OUT_DIR, exist_ok=True)
asset = "%s_%s.zip" % (ASSEMBLY, target_abi)
path = os.path.join(OUT_DIR, asset)
info = zipfile.ZipInfo(ASSEMBLY + ".dll", date_time=(1980, 1, 1, 0, 0, 0))
info.compress_type = zipfile.ZIP_DEFLATED
info.external_attr = 0o644 << 16
with open(dll, "rb") as fh:
payload = fh.read()
with zipfile.ZipFile(path, "w") as zf:
zf.writestr(info, payload)
print("packaged %s (%d bytes)" % (path, os.path.getsize(path)))
return path, asset
def update_manifest(meta, version, asset, checksum, changelog):
if os.path.exists(MANIFEST):
with open(MANIFEST, encoding="utf-8") as fh:
manifest = json.load(fh)
else:
manifest = []
package = next((p for p in manifest if p.get("guid") == meta["guid"]), None)
if package is None:
package = {
"name": meta["name"],
"guid": meta["guid"],
"overview": meta["overview"],
"description": meta["description"],
"owner": meta["owner"],
"category": meta["category"],
"versions": [],
}
if meta.get("imageUrl"):
package["imageUrl"] = meta["imageUrl"]
manifest.append(package)
for key in ("name", "overview", "description", "owner", "category"):
package[key] = meta[key]
entry = {
"version": version,
"targetAbi": meta["targetAbi"],
"changelog": changelog,
"sourceUrl": source_url("v" + version, asset),
"checksum": checksum,
"timestamp": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S"),
}
package["versions"] = [v for v in package["versions"] if v.get("version") != version]
package["versions"].insert(0, entry)
package["versions"] = package["versions"][:MAX_VERSIONS]
with open(MANIFEST, "w", encoding="utf-8") as fh:
json.dump(manifest, fh, indent=2, ensure_ascii=False)
fh.write("\n")
return entry
def main():
ap = argparse.ArgumentParser(description=__doc__,
formatter_class=argparse.RawDescriptionHelpFormatter)
ap.add_argument("--version", help="plugin version, e.g. 0.2.0.0")
ap.add_argument("--bump", action="store_true", help="bump the last version component")
ap.add_argument("--publish", action="store_true", help="create the Gitea release and upload the zip")
ap.add_argument("--no-push", action="store_true", help="with --publish: skip git commit/push")
ap.add_argument("--print-urls", action="store_true", help="print the catalog URL and exit")
args = ap.parse_args()
if args.print_urls:
print("Jellyfin plugin repository URL:")
print(" " + catalog_url())
return
meta = read_build_yaml()
if args.version:
version = args.version
write_build_yaml_version(version)
elif args.bump:
version = bump(meta["version"])
write_build_yaml_version(version)
meta = read_build_yaml()
else:
version = meta["version"]
print("=" * 72)
print("JFVR plugin %s (targetAbi %s)" % (version, meta["targetAbi"]))
print("=" * 72)
build_bundle()
js_ver = bundle_version()
dll = build_plugin(version)
verify_embedded(dll)
zip_path, asset = make_zip(dll, meta["targetAbi"])
checksum = md5_of(zip_path)
print("zip md5: %s" % checksum)
changelog = (meta.get("changelog") or "").strip()
changelog = "Bundle version: `%s`\n\n%s" % (js_ver, changelog)
entry = update_manifest(meta, version, asset, checksum, changelog)
print("manifest.json updated: %s" % entry["sourceUrl"])
if args.publish:
token = gitea_token()
publish("v" + version, meta, zip_path, asset, changelog, token)
status, length = head_ok(entry["sourceUrl"])
print("asset check: HTTP %s, %s bytes" % (status, length))
if status != 200:
sys.exit("the asset is not downloadable -- is the release a draft?")
# What Jellyfin will do at install time: download it and compare MD5.
live = fetch_md5(entry["sourceUrl"])
if live != checksum:
sys.exit("published asset md5 %s != manifest checksum %s -- install would fail"
% (live, checksum))
print("asset md5 matches the manifest checksum (%s)" % live)
if not args.no_push:
run(["git", "add", "manifest.json", "plugin/build.yaml"], cwd=HERE)
dirty = subprocess.run(
["git", "diff", "--cached", "--quiet", "--", "manifest.json", "plugin/build.yaml"],
cwd=HERE,
).returncode != 0
if dirty:
run(["git", "commit", "-m", "plugin: publish %s (bundle %s)" % (version, js_ver)], cwd=HERE)
else:
print("manifest.json unchanged -- nothing to commit")
run(["git", "push", "origin", GITEA_BRANCH], cwd=HERE)
else:
print("--no-push: push manifest.json yourself, Jellyfin reads it from the branch")
print()
print("=" * 72)
print("Jellyfin plugin repository URL:")
print(" " + catalog_url())
print()
print("Bundle (in-page HUD version): %s" % js_ver)
print("Install: Dashboard > Plugins > Catalog > gear > + > paste the URL above.")
if not args.publish:
print("Then: python3 pack.py --publish (creates the release and pushes the manifest)")
if __name__ == "__main__":
main()
@@ -0,0 +1,129 @@
<!DOCTYPE html>
<html>
<head>
<title>Jellyfin Web VR</title>
</head>
<body>
<div id="JfvrConfigPage" data-role="page" class="page type-interior pluginConfigurationPage">
<div data-role="content">
<div class="content-primary">
<form id="JfvrConfigForm">
<div class="verticalSection">
<div class="sectionTitleContainer flex align-items-center">
<h2 class="sectionTitle">Jellyfin Web VR</h2>
<a is="emby-linkbutton" class="raised raised-mini emby-button" style="margin-left:2em"
target="_blank" rel="noopener"
href="https://git.cat-shark.xyz/cat-shark/jellyfin_vr_web_plugin">
<i class="md-icon button-icon button-icon-left secondaryText"></i>
<span>Help</span>
</a>
</div>
<p class="fieldDescription">
在 jellyfin-web 的 <code>index.html</code> 里注入 VR 播放脚本,让 Quest 3
浏览器直接进入 VR180 / VR360 沉浸播放。改写发生在请求时,磁盘上的文件不会被改动,
所以 Jellyfin 升级不会丢掉注入。
</p>
<p class="fieldDescription">
<strong>改完设置后需要刷新浏览器</strong>(<code>index.html</code> 本身没有强缓存,
普通刷新即可)。
</p>
</div>
<div class="checkboxContainer checkboxContainer-withDescription">
<label>
<input is="emby-checkbox" type="checkbox" id="chkEnabled" />
<span>启用注入</span>
</label>
<div class="fieldDescription checkboxFieldDescription">
关闭后 <code>index.html</code> 原样返回,不再注入;脚本端点仍然可以访问。
</div>
</div>
<div class="inputContainer">
<input is="emby-input" type="text" id="txtScriptUrl" label="脚本 URL 覆盖(可选)" />
<div class="fieldDescription">
留空则使用插件内置的 bundle:<code id="builtinUrl">/JFVR/jfvr.js</code>。
填了就注入这个 URL(例如自建 CDN 上的副本),内置 bundle 不再使用。
</div>
</div>
<div>
<button is="emby-button" type="submit" class="raised button-submit block">
<span>保存</span>
</button>
</div>
<div class="verticalSection" style="margin-top:1.5em">
<h3 class="sectionTitle" style="font-size:1.1em">状态</h3>
<div id="statusBox" class="fieldDescription">读取中…</div>
</div>
</form>
</div>
</div>
</div>
<script>
(function () {
'use strict';
var PLUGIN_ID = '7d33ef59-f9b0-412b-93bd-5cd5353018de';
function statusLine(label, value) {
return '<div><strong>' + label + ':</strong> ' + value + '</div>';
}
function renderStatus() {
var box = document.querySelector('#statusBox');
var url;
try {
url = ApiClient.getUrl('JFVR/status');
} catch (err) {
url = '/JFVR/status';
}
ApiClient.ajax({ type: 'GET', url: url, dataType: 'json' }).then(function (s) {
box.innerHTML =
statusLine('插件版本', s.version) +
statusLine('bundle 版本', s.bundleHash + '(' + s.bundleBytes + ' bytes)') +
statusLine('注入', s.enabled ? '已启用' : '已关闭') +
statusLine('注入的 URL', '<code>' + s.injectedTag + '</code>');
}).catch(function () {
box.textContent = '无法读取 /JFVR/status(插件可能尚未加载完成)。';
});
}
function loadConfiguration() {
Dashboard.showLoadingMsg();
ApiClient.getPluginConfiguration(PLUGIN_ID).then(function (config) {
document.querySelector('#chkEnabled').checked = config.Enabled !== false;
document.querySelector('#txtScriptUrl').value = config.ScriptUrlOverride || '';
Dashboard.hideLoadingMsg();
renderStatus();
});
}
function saveConfiguration(e) {
e.preventDefault();
Dashboard.showLoadingMsg();
ApiClient.getPluginConfiguration(PLUGIN_ID).then(function (config) {
config.Enabled = document.querySelector('#chkEnabled').checked;
config.ScriptUrlOverride = document.querySelector('#txtScriptUrl').value || '';
ApiClient.updatePluginConfiguration(PLUGIN_ID, config).then(function (result) {
Dashboard.processPluginConfigurationUpdateResult(result);
renderStatus();
});
});
return false;
}
document.querySelector('#JfvrConfigForm').addEventListener('submit', saveConfiguration);
document.addEventListener('pageshow', function (e) {
if (e.target.id === 'JfvrConfigPage') {
loadConfiguration();
}
});
})();
</script>
</body>
</html>
@@ -0,0 +1,82 @@
using System;
using System.Threading.Tasks;
using Jellyfin.Plugin.JFVR.Services;
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Net.Http.Headers;
namespace Jellyfin.Plugin.JFVR.Controllers;
/// <summary>
/// Serves the JFVR web bundle and a small status endpoint.
///
/// The bundle is anonymous on purpose: the injected tag lives in
/// <c>index.html</c>, which the browser fetches before the user has
/// authenticated, and the payload is the same JavaScript that is already public
/// in the project repository.
/// </summary>
[ApiController]
[Route("JFVR")]
public class JfvrController : ControllerBase
{
private readonly BundleProvider _bundle;
/// <summary>
/// Initializes a new instance of the <see cref="JfvrController"/> class.
/// </summary>
/// <param name="bundle">Embedded web bundle.</param>
public JfvrController(BundleProvider bundle)
{
_bundle = bundle;
}
/// <summary>
/// Returns the JFVR web bundle.
/// </summary>
/// <returns>The bundle as JavaScript.</returns>
[HttpGet("jfvr.js")]
[AllowAnonymous]
[Produces("application/javascript")]
public ActionResult GetBundle()
{
var etag = "\"" + _bundle.Hash + "\"";
// The URL is versioned with ?v=<hash>, so the body for a given URL never
// changes: it is safe to cache forever, and an update always produces a
// new URL.
Response.Headers[HeaderNames.CacheControl] = "public, max-age=31536000, immutable";
Response.Headers[HeaderNames.ETag] = etag;
if (Request.Headers[HeaderNames.IfNoneMatch].ToString().Contains(_bundle.Hash, StringComparison.Ordinal))
{
return StatusCode(304);
}
return File(_bundle.Bytes, "application/javascript; charset=utf-8");
}
/// <summary>
/// Reports which bundle the server is serving and whether injection is on.
/// Handy for verifying a deployment without opening DevTools on the Quest.
/// </summary>
/// <returns>A small JSON status object.</returns>
[HttpGet("status")]
[AllowAnonymous]
public ActionResult<object> GetStatus()
{
var config = Plugin.Instance?.Configuration;
return new
{
plugin = "Jellyfin.Plugin.JFVR",
version = typeof(Plugin).Assembly.GetName().Version?.ToString() ?? "unknown",
bundleHash = _bundle.Hash,
bundleBytes = _bundle.Bytes.Length,
enabled = config?.Enabled ?? false,
scriptUrlOverride = config?.ScriptUrlOverride ?? string.Empty,
injectedTag = string.IsNullOrWhiteSpace(config?.ScriptUrlOverride)
? "../JFVR/jfvr.js?v=" + _bundle.Hash
: config!.ScriptUrlOverride.Trim()
};
}
}
@@ -0,0 +1,48 @@
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFramework>net10.0</TargetFramework>
<RootNamespace>Jellyfin.Plugin.JFVR</RootNamespace>
<AssemblyName>Jellyfin.Plugin.JFVR</AssemblyName>
<Nullable>enable</Nullable>
<ImplicitUsings>disable</ImplicitUsings>
<LangVersion>latest</LangVersion>
<GenerateDocumentationFile>false</GenerateDocumentationFile>
<EnableDefaultEmbeddedResourceItems>false</EnableDefaultEmbeddedResourceItems>
<!-- Overridden by pack.py from plugin/build.yaml (dotnet build -p:Version=...). -->
<Version>0.1.0.0</Version>
<!--
Single source of truth for the injected bundle. dist/jfvr.js is produced by
build.py from src/*.js; embedding it straight from there (instead of copying
it into the project) means the DLL can never ship a stale bundle.
-->
<JfvrBundlePath>$(MSBuildThisFileDirectory)..\..\dist\jfvr.js</JfvrBundlePath>
</PropertyGroup>
<Target Name="JfvrCheckBundle" BeforeTargets="PrepareForBuild">
<Error
Condition="!Exists('$(JfvrBundlePath)')"
Text="dist/jfvr.js is missing. Run 'python3 build.py' first (pack.py does this for you)." />
</Target>
<ItemGroup>
<!--
ExcludeAssets=runtime is required: Jellyfin provides these at runtime, and
copying them into the plugin folder prevents the plugin from registering.
-->
<PackageReference Include="Jellyfin.Controller" Version="12.1.0">
<ExcludeAssets>runtime</ExcludeAssets>
</PackageReference>
<PackageReference Include="Jellyfin.Model" Version="12.1.0">
<ExcludeAssets>runtime</ExcludeAssets>
</PackageReference>
</ItemGroup>
<ItemGroup>
<EmbeddedResource Include="$(JfvrBundlePath)" LogicalName="Jellyfin.Plugin.JFVR.Web.jfvr.js" />
<EmbeddedResource Include="Configuration\configPage.html" LogicalName="Jellyfin.Plugin.JFVR.Configuration.configPage.html" />
</ItemGroup>
</Project>
+66
View File
@@ -0,0 +1,66 @@
using System;
using System.Collections.Generic;
using Jellyfin.Plugin.JFVR.Services;
using MediaBrowser.Common.Configuration;
using MediaBrowser.Common.Plugins;
using MediaBrowser.Model.Plugins;
using MediaBrowser.Model.Serialization;
namespace Jellyfin.Plugin.JFVR;
/// <summary>
/// The JFVR plugin. Owns the identity (GUID + version) that the Jellyfin plugin
/// catalog matches on, and serves the embedded web bundle.
/// </summary>
public class Plugin : BasePlugin<PluginConfiguration>, IHasWebPages
{
/// <summary>
/// Initializes a new instance of the <see cref="Plugin"/> class.
/// </summary>
/// <param name="applicationPaths">Jellyfin application paths.</param>
/// <param name="xmlSerializer">XML serializer for the configuration.</param>
/// <param name="bundle">Embedded web bundle.</param>
public Plugin(IApplicationPaths applicationPaths, IXmlSerializer xmlSerializer, BundleProvider bundle)
: base(applicationPaths, xmlSerializer)
{
Instance = this;
Bundle = bundle;
}
/// <summary>
/// Gets the current plugin instance. Set by the DI container at startup;
/// the injection middleware reads the configuration through it.
/// </summary>
public static Plugin? Instance { get; private set; }
/// <summary>
/// Gets the embedded web bundle.
/// </summary>
public BundleProvider Bundle { get; }
/// <inheritdoc />
public override string Name => "Jellyfin Web VR";
/// <inheritdoc />
public override Guid Id => Guid.Parse("7d33ef59-f9b0-412b-93bd-5cd5353018de");
/// <inheritdoc />
public override string Description =>
"Injects a VR play button into Jellyfin Web so Meta Quest 3 can play VR180/VR360 in WebXR.";
/// <inheritdoc />
public IEnumerable<PluginPageInfo> GetPages()
{
return new[]
{
new PluginPageInfo
{
Name = "JFVR",
DisplayName = "Jellyfin Web VR",
EmbeddedResourcePath = GetType().Namespace + ".Configuration.configPage.html",
EnableInMainMenu = true,
MenuIcon = "view_in_ar"
}
};
}
}
@@ -0,0 +1,25 @@
using MediaBrowser.Model.Plugins;
namespace Jellyfin.Plugin.JFVR;
/// <summary>
/// JFVR plugin configuration. Persisted by Jellyfin as XML under
/// <c>&lt;config&gt;/plugins/configurations/Jellyfin.Plugin.JFVR.xml</c>, so it
/// survives container recreation and Jellyfin upgrades.
/// </summary>
public class PluginConfiguration : BasePluginConfiguration
{
/// <summary>
/// Gets or sets a value indicating whether the plugin rewrites the served
/// <c>index.html</c>. When disabled the response is passed through untouched
/// (the legacy injection, if any, is left alone too) but the bundle endpoint
/// stays reachable.
/// </summary>
public bool Enabled { get; set; } = true;
/// <summary>
/// Gets or sets an optional URL used instead of the embedded bundle. Leave
/// empty to serve <c>../JFVR/jfvr.js?v=&lt;hash&gt;</c> from this plugin.
/// </summary>
public string ScriptUrlOverride { get; set; } = string.Empty;
}
@@ -0,0 +1,23 @@
using Jellyfin.Plugin.JFVR.Services;
using MediaBrowser.Controller;
using MediaBrowser.Controller.Plugins;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.DependencyInjection;
namespace Jellyfin.Plugin.JFVR;
/// <summary>
/// Registers the plugin's services with the Jellyfin host container.
/// </summary>
public class PluginServiceRegistrator : IPluginServiceRegistrator
{
/// <inheritdoc />
public void RegisterServices(IServiceCollection serviceCollection, IServerApplicationHost applicationHost)
{
serviceCollection.AddSingleton<BundleProvider>();
// The request-time injection path: rewrites jellyfin-web's index.html on
// the way out. Nothing is written to disk.
serviceCollection.AddSingleton<IStartupFilter, ScriptInjectionStartupFilter>();
}
}
@@ -0,0 +1,55 @@
using System;
using System.IO;
using System.Security.Cryptography;
namespace Jellyfin.Plugin.JFVR.Services;
/// <summary>
/// Loads the JFVR web bundle that is embedded in this assembly and exposes it
/// together with a short content hash.
///
/// The hash is the cache-busting token in the injected
/// <c>&lt;script src="../JFVR/jfvr.js?v=HASH"&gt;</c> tag, so a new plugin build
/// always forces browsers to refetch the bundle. It is also the same
/// <c>md5[:6]</c> version string the in-page HUD reports, which makes "which JS
/// is the Quest actually running?" answerable from both sides.
/// </summary>
public sealed class BundleProvider
{
/// <summary>
/// Logical name of the embedded resource, set explicitly in the .csproj so it
/// does not depend on the project's folder layout.
/// </summary>
internal const string ResourceName = "Jellyfin.Plugin.JFVR.Web.jfvr.js";
/// <summary>
/// Initializes a new instance of the <see cref="BundleProvider"/> class.
/// </summary>
/// <exception cref="InvalidOperationException">
/// Thrown when the bundle was not embedded, which means the build is broken.
/// </exception>
public BundleProvider()
{
using var stream = typeof(BundleProvider).Assembly.GetManifestResourceStream(ResourceName);
if (stream is null)
{
throw new InvalidOperationException(
$"Embedded resource '{ResourceName}' is missing from {typeof(BundleProvider).Assembly.FullName}.");
}
using var buffer = new MemoryStream();
stream.CopyTo(buffer);
Bytes = buffer.ToArray();
Hash = Convert.ToHexString(MD5.HashData(Bytes)).ToLowerInvariant()[..8];
}
/// <summary>
/// Gets the raw bundle bytes.
/// </summary>
public byte[] Bytes { get; }
/// <summary>
/// Gets the short (8 hex chars) MD5 of <see cref="Bytes"/>.
/// </summary>
public string Hash { get; }
}
@@ -0,0 +1,97 @@
using System;
using System.Text.RegularExpressions;
namespace Jellyfin.Plugin.JFVR.Services;
/// <summary>
/// The pure text transformation behind <see cref="ScriptInjectionStartupFilter"/>:
/// given jellyfin-web's <c>index.html</c>, return the version with the JFVR
/// script tag in it.
///
/// Deliberately free of ASP.NET and Jellyfin types so it can be exercised
/// directly against captured HTML.
/// </summary>
public static class IndexHtmlRewriter
{
/// <summary>
/// Marker that identifies an index.html this plugin already rewrote.
/// </summary>
public const string StartComment = "<!-- BEGIN JFVR (Jellyfin Web VR) -->";
/// <summary>
/// Closing half of the injected block.
/// </summary>
public const string EndComment = "<!-- END JFVR (Jellyfin Web VR) -->";
/// <summary>
/// Matches the tag written by the old <c>deploy.py</c>
/// (<c>&lt;script plugin="JellyfinVR" ... src="jfvr-mvp.js?v=..."&gt;&lt;/script&gt;</c>).
///
/// The plugin's own tag deliberately uses <c>plugin="JFVR"</c>, so the two can
/// never be confused: installing the plugin takes over from the legacy
/// injection automatically instead of loading the bundle twice.
/// </summary>
private static readonly Regex LegacyTag = new(
"<script[^>]*plugin=\"JellyfinVR\"[^>]*>\\s*</script>\\s*",
RegexOptions.IgnoreCase | RegexOptions.Compiled);
/// <summary>
/// Gets a value indicating whether <paramref name="html"/> already carries our block.
/// </summary>
/// <param name="html">The served HTML.</param>
/// <returns>True when the block is already present.</returns>
public static bool IsInjected(string html)
{
return html.Contains(StartComment, StringComparison.Ordinal);
}
/// <summary>
/// Builds the block that gets inserted immediately before <c>&lt;/body&gt;</c>.
/// </summary>
/// <param name="scriptUrl">URL of the bundle to load.</param>
/// <returns>The HTML block, newline terminated.</returns>
public static string BuildBlock(string scriptUrl)
{
return StartComment
+ "\n<script plugin=\"JFVR\" data-jfvr=\"1\" src=\"" + scriptUrl + "\" defer></script>\n"
+ EndComment
+ "\n";
}
/// <summary>
/// Injects the JFVR block into <paramref name="html"/>.
///
/// Idempotent: an already-injected document is returned unchanged. A legacy
/// <c>deploy.py</c> tag is removed on the way so the bundle is never loaded twice.
/// If there is no <c>&lt;/body&gt;</c> to anchor to, the (possibly
/// legacy-cleaned) input is returned unchanged.
/// </summary>
/// <param name="html">The served HTML.</param>
/// <param name="scriptUrl">URL of the bundle to load.</param>
/// <param name="removedLegacy">True when a legacy tag was stripped.</param>
/// <returns>The HTML to serve.</returns>
public static string Rewrite(string html, string scriptUrl, out bool removedLegacy)
{
removedLegacy = false;
if (IsInjected(html))
{
return html;
}
var cleaned = html;
if (LegacyTag.IsMatch(html))
{
cleaned = LegacyTag.Replace(html, string.Empty);
removedLegacy = true;
}
var bodyClose = cleaned.LastIndexOf("</body>", StringComparison.OrdinalIgnoreCase);
if (bodyClose < 0)
{
return cleaned;
}
return cleaned[..bodyClose] + BuildBlock(scriptUrl) + "\n" + cleaned[bodyClose..];
}
}
@@ -0,0 +1,210 @@
using System;
using System.IO;
using System.Text;
using System.Threading;
using System.Threading.Tasks;
using Jellyfin.Plugin.JFVR.Services;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Primitives;
using Microsoft.Net.Http.Headers;
namespace Jellyfin.Plugin.JFVR.Services;
/// <summary>
/// Injects the JFVR <c>&lt;script&gt;</c> tag into jellyfin-web's index.html at
/// request time, through ASP.NET Core middleware registered via
/// <see cref="IStartupFilter"/>.
///
/// Why request-time rewriting instead of the old deploy.py approach (which
/// <c>sed</c>-patched <c>/jellyfin/jellyfin-web/index.html</c> inside the
/// container):
/// - nothing on disk is modified, so a <c>jellyfin/jellyfin:latest</c> upgrade
/// cannot silently drop the injection;
/// - it is idempotent and additive;
/// - on any error the original response is served unchanged -- the middleware
/// never throws into the pipeline;
/// - it can be switched off from the dashboard.
///
/// The technique (strip Accept-Encoding so the static handler returns plain
/// text, buffer the body, rewrite, fix up the validators) is the same one the
/// community JavaScript Injector plugin uses; that plugin's own history is why
/// the details below look paranoid.
/// </summary>
public sealed class ScriptInjectionStartupFilter : IStartupFilter
{
private readonly BundleProvider _bundle;
private readonly ILogger<ScriptInjectionStartupFilter> _logger;
private int _loggedOnce;
private int _legacyLoggedOnce;
/// <summary>
/// Initializes a new instance of the <see cref="ScriptInjectionStartupFilter"/> class.
/// </summary>
/// <param name="bundle">Embedded web bundle.</param>
/// <param name="logger">Logger.</param>
public ScriptInjectionStartupFilter(BundleProvider bundle, ILogger<ScriptInjectionStartupFilter> logger)
{
_bundle = bundle;
_logger = logger;
}
/// <inheritdoc />
public Action<IApplicationBuilder> Configure(Action<IApplicationBuilder> next)
{
return app =>
{
// Registered before next(app) so this runs outermost. That ordering
// matters: stripping Accept-Encoding here means the response
// compression middleware downstream never compresses the body, so
// what we buffer is always complete, plain-text HTML.
app.Use(InvokeAsync);
next(app);
};
}
private async Task InvokeAsync(HttpContext context, Func<Task> nextMw)
{
var config = Plugin.Instance?.Configuration;
if (config is null || !config.Enabled || !IsIndexRequest(context.Request))
{
await nextMw().ConfigureAwait(false);
return;
}
// Normalize the request so the static handler returns a complete 200:
// - no Accept-Encoding -> no compression, plain text body;
// - no Range/If-Range -> no 206 partial response, which would otherwise
// pass through un-injected with a total length that no longer matches.
var hadAcceptEncoding = context.Request.Headers.TryGetValue(HeaderNames.AcceptEncoding, out StringValues acceptEncoding);
context.Request.Headers.Remove(HeaderNames.AcceptEncoding);
context.Request.Headers.Remove(HeaderNames.Range);
context.Request.Headers.Remove(HeaderNames.IfRange);
var originalBody = context.Response.Body;
using var buffer = new MemoryStream();
context.Response.Body = buffer;
try
{
await nextMw().ConfigureAwait(false);
}
catch
{
// Not ours to swallow. Discard the partially buffered body (it never
// reached the real stream, so the response has not started) and let
// the host render a clean error page.
context.Response.Body = originalBody;
throw;
}
finally
{
if (hadAcceptEncoding)
{
context.Request.Headers[HeaderNames.AcceptEncoding] = acceptEncoding;
}
}
context.Response.Body = originalBody;
buffer.Seek(0, SeekOrigin.Begin);
var isHtml = context.Response.StatusCode == 200
&& context.Response.ContentType is not null
&& context.Response.ContentType.Contains("text/html", StringComparison.OrdinalIgnoreCase);
if (!isHtml)
{
// 304, redirects, non-HTML: pass straight through, byte for byte.
await buffer.CopyToAsync(originalBody).ConfigureAwait(false);
return;
}
string html;
using (var reader = new StreamReader(buffer, Encoding.UTF8, detectEncodingFromByteOrderMarks: true, leaveOpen: true))
{
html = await reader.ReadToEndAsync().ConfigureAwait(false);
}
try
{
html = Rewrite(html, config);
}
catch (Exception ex)
{
// Never break index.html: serve whatever we have.
_logger.LogWarning(ex, "JFVR: index.html rewrite failed, serving the original response.");
}
var bytes = Encoding.UTF8.GetBytes(html);
context.Response.ContentType = "text/html; charset=utf-8";
context.Response.ContentLength = bytes.Length;
// The body changed, so validators computed for the original bytes are
// invalid, and range requests on the rewritten document are not supported
// (they are already stripped on the way in).
context.Response.Headers.Remove(HeaderNames.ETag);
context.Response.Headers.Remove(HeaderNames.LastModified);
context.Response.Headers.Remove(HeaderNames.AcceptRanges);
context.Response.Headers.Remove(HeaderNames.ContentEncoding);
await originalBody.WriteAsync(bytes).ConfigureAwait(false);
}
private string Rewrite(string html, PluginConfiguration config)
{
var scriptUrl = string.IsNullOrWhiteSpace(config.ScriptUrlOverride)
? "../JFVR/jfvr.js?v=" + _bundle.Hash
: config.ScriptUrlOverride.Trim();
var rewritten = IndexHtmlRewriter.Rewrite(html, scriptUrl, out var removedLegacy);
if (removedLegacy && Interlocked.Exchange(ref _legacyLoggedOnce, 1) == 0)
{
// Logged once, not per request: the legacy tag lives in the on-disk
// index.html, so it is stripped from every single response until the
// file itself is cleaned up (deploy.py rollback) or deploy.py is run
// again. Per-request logging would just fill the log with the same line.
_logger.LogInformation(
"JFVR: stripping the legacy deploy.py <script> tag from index.html. "
+ "It is still present on disk; run 'python3 deploy.py rollback' to clean it up.");
}
if (IndexHtmlRewriter.IsInjected(html) || rewritten == html)
{
// Already ours (the common case on every reload), or nothing to anchor to.
return rewritten;
}
if (Interlocked.Exchange(ref _loggedOnce, 1) == 0)
{
_logger.LogInformation("JFVR: injecting {Block}", IndexHtmlRewriter.BuildBlock(scriptUrl).Trim());
}
return rewritten;
}
/// <summary>
/// Matches the web app shell however it is requested: bare <c>/web</c>,
/// <c>/web/</c> (SPA serve) and an explicit <c>/web/index.html</c>. The
/// EndsWith form stays correct when Jellyfin is hosted under a base-url
/// prefix (e.g. <c>/jellyfin/web/</c>).
/// </summary>
private static bool IsIndexRequest(HttpRequest request)
{
if (!HttpMethods.IsGet(request.Method))
{
return false;
}
var path = request.Path.Value;
if (string.IsNullOrEmpty(path) || path == "/")
{
return true;
}
return path.EndsWith("/web/index.html", StringComparison.OrdinalIgnoreCase)
|| path.EndsWith("/web/", StringComparison.OrdinalIgnoreCase)
|| path.Equals("/web", StringComparison.OrdinalIgnoreCase);
}
}
+27
View File
@@ -0,0 +1,27 @@
---
# Metadata for the Jellyfin plugin catalog entry. pack.py reads this file to
# build manifest.json, and passes `version` to dotnet as -p:Version.
#
# targetAbi is deliberately 12.0.0.0 rather than the exact server version:
# Jellyfin keeps a catalog version only when `targetAbi <= serverVersion`
# (InstallationManager.GetAvailablePackages), so one package covers all of 12.x.
name: "Jellyfin Web VR"
guid: "7d33ef59-f9b0-412b-93bd-5cd5353018de"
version: "0.5.2.0"
targetAbi: "12.0.0.0"
framework: "net10.0"
overview: "VR180/VR360 playback inside Jellyfin Web for Meta Quest 3."
description: >
Injects a "VR 播放" button into the Jellyfin Web video player page and drives
an immersive WebXR session on Meta Quest 3, preferring
XRMediaBinding.createEquirectLayer and falling back to XRWebGLBinding.
Ships equirectangular 180/360 plus SBS/OU layouts, in-headset subtitles,
a wrist controller, and hand tracking.
category: "General"
owner: "cat-shark"
artifacts:
- "Jellyfin.Plugin.JFVR.dll"
changelog: >
First 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.
+293 -5
View File
@@ -11,7 +11,7 @@
var NS = window.__JFVR = window.__JFVR || {};
NS.version = 'hud-7'; // hud-7 = ADDENDUM 8b (live picture pan: transform/space, hold-to-drag, tap-to-reset)
NS.version = 'hud-11'; // hud-11 = ADDENDUM 12 (single pointer owner: dominant hand by default, press takes over, hold exclusion) + 11/10/9
NS.__core = true;
/* ------------------------------------------------------------------ *
@@ -51,6 +51,7 @@
subtitles: true,
ctlLock: false, // ADDENDUM 7: control-bar lock badge (per VR session)
subMode: 'hud', // 'hud' | 'sphere' | 'off'
subLayout: 'auto', // ADDENDUM 9: 'auto' | 'dual' | 'mono' subtitle layout
subAlpha: 'premultiplied', // 'premultiplied' | 'straight'
subOpacity: 0.85, // 0..1, applied to the subtitle layer live
// y is the quad CENTRE; negative = below eye level. -0.42 keeps the strip
@@ -66,6 +67,7 @@
subAngleDeg: 69.2,
controls: true,
handPref: 'right', // ADDENDUM 12: dominant hand = the pointer's default owner
ctlAutoHideMs: 4000, // in-VR control bar auto-hide
// written every XR frame by 90-main.js, read by modules
@@ -305,9 +307,132 @@
hasGetJointPose: typeof window.XRFrame !== 'undefined' && typeof XRFrame.prototype.getJointPose === 'function',
maxTextureSize: null,
hevc: {},
decoding8k: null
decoding8k: null,
/* MediaCapabilities verdicts, keyed '<profile_idc>:<level>'. See below. */
codec: {},
codecBlocked: [],
codecKept: [],
cptPatched: false,
cptMode: null
};
/* ------------------------------------------------------------------ *
* codec capability: what this browser will ACTUALLY decode
* ------------------------------------------------------------------
* Two layers.
*
* 1. NS.caps.hevc -- raw canPlayType() answers, for the diagnostics panel.
* This used to only ask about Main profile (8-bit), which is why the
* project's notes said "8K HEVC: supported" right up until a Main 10
* (10-bit) file showed up and could not be decoded at all. The Main 10
* strings are the ones that actually matter for 8K VR here.
*
* 2. NS.caps.codec + the canPlayType override -- makes Jellyfin Web build
* an ACCURATE device profile.
*
* Why the override: Jellyfin Web derives its entire HEVC claim from
* canPlayType (src/scripts/browserDeviceProfile.js):
*
* let maxHevcLevel = 120, hevcProfiles = 'main';
* ...
* if (canPlayType('video/mp4; codecs="hvc1.2.4.L183"')) {
* maxHevcLevel = 183; // level 6.1 = 8K
* hevcProfiles = 'main|main 10';
* }
*
* canPlayType answers "does this system have an HEVC decoder", not "can it
* do 8192x4096 Main 10 at 60 fps". So a desktop browser that merely ships an
* HEVC decoder claims 8K Main 10, the server picks DirectPlay, and playback
* dies on a black screen with no player UI (the OSD is only built after
* 'playbackstart'). decodingInfo asks the actual decoder, so feeding its
* verdict back through canPlayType lets Jellyfin's own logic land on the
* right profile: the desktop drops to whatever it can really do and the
* server transcodes, while a Quest that genuinely decodes 8K Main 10 keeps
* DirectPlay. Meta's browser-video docs recommend exactly this API over UA
* sniffing.
*
* 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 "decoder exists, 8K does not work"
* case
*
* 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
* localStorage['jfvr-cpt-keep'] = '2:183' never downgrade these tiers
*/
// decodingInfo needs real dimensions; a level string does not carry them, so
// 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.
//
// NOTE on the codec strings: they MUST carry a constraint byte. Chrome's
// MediaCapabilities.decodingInfo does not recognise the bare 'hvc1.1.L120'
// spelling and answers supported:false for it even on a machine that decodes
// HEVC perfectly, while 'hvc1.1.0.L120' is answered correctly. That one
// character used to matter far more than it looks: browserDeviceProfile.js
// gates the WHOLE hevc entry on supportsHevc(), which is exactly
//
// canPlayType('...codecs="hvc1.1.L120"') ||
// canPlayType('...codecs="hev1.1.L120"') ||
// canPlayType('...codecs="hvc1.1.0.L120"') || ...
//
// so a spurious block of tier 1:120 (all spellings map to it) removes hevc
// from every DirectPlayProfile and transcode every HEVC file in the library.
// 1:120 is NOT part of Jellyfin's level chain; it is only that gate.
var CODEC_PROBES = [
{ key: '1:120', name: 'Main L4.0', w: 1920, h: 1080, fps: 30, mbps: 8, codec: 'hvc1.1.0.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' },
{ key: '2:186', name: 'Main10 L6.2 (8K60)', w: 8192, h: 4096, fps: 60, mbps: 30, codec: 'hvc1.2.4.L186' }
];
/**
* 'video/mp4; codecs="hvc1.2.4.L183.B0"' -> '2:183' (profile_idc : level).
* Both the hvc1 and hev1 spellings map to the same key: they differ in the
* sample entry, not in what has to be decoded.
*/
function hevcKey(type) {
var m = /(?:hvc1|hev1)\.([0-9]+)(?:\.[0-9]+)?\.l([0-9]+)/i.exec(String(type || ''));
return m ? m[1] + ':' + m[2] : null;
}
NS.caps.hevcKey = hevcKey;
(function probe() {
try {
var mb = window.XRMediaBinding;
@@ -321,12 +446,17 @@
if (gl) NS.caps.maxTextureSize = gl.getParameter(gl.MAX_TEXTURE_SIZE);
} catch (e) {}
try {
['video/mp4; codecs="hev1.1.6.L183.B0"',
var ve = document.createElement('video');
['video/mp4; codecs="hev1.1.6.L183.B0"', // Main 8-bit 8K (the files that work)
'video/mp4; codecs="hvc1.1.6.L183.B0"',
'video/mp4; codecs="hev1.2.4.L183.B0"', // Main 10 8K (the files that do not)
'video/mp4; codecs="hvc1.2.4.L183.B0"',
'video/mp4; codecs="hev1.2.4.L153.B0"', // Main 10 4K
'video/mp4; codecs="hvc1.2.4.L153.B0"',
'video/mp4; codecs="hev1"',
'video/mp4; codecs="hvc1"'].forEach(function (cs) {
NS.caps.hevc[cs] = (typeof MediaSource !== 'undefined' && MediaSource.isTypeSupported(cs)) ||
document.createElement('video').canPlayType(cs) || 'no';
ve.canPlayType(cs) || 'no';
});
} catch (e) {}
if (navigator.xr && navigator.xr.isSessionSupported) {
@@ -336,8 +466,162 @@
}
})();
/* ------------------------------------------------------------------ *
* MediaCapabilities probe + canPlayType override
* ------------------------------------------------------------------ */
/** Tiers the user has pinned as "keep claiming this", '<key>,<key>' in localStorage. */
function readKeepList() {
try {
var raw = localStorage.getItem('jfvr-cpt-keep') || '';
return raw.split(',').map(function (s) { return s.trim(); }).filter(Boolean);
} catch (e) { return []; }
}
/** Why a verdict means "do not claim this tier", or null if it is fine. */
function blockReason(v, keep) {
if (!v || v.error) return null; // unknown -> leave it to the browser
if (keep.indexOf(v.key) >= 0) return null; // user pinned it
if (v.supported === false) return 'unsupported';
if (v.smooth === false) return 'not-smooth';
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(':');
// Base tier. 1:120 is not in Jellyfin's level chain -- it is only the
// coarse "does this client have HEVC at all" gate (supportsHevc() in
// browserDeviceProfile.js, which probes exactly this level). Blocking it
// drops hevc from every DirectPlayProfile, i.e. transcodes the entire
// HEVC library. Never act on it unless the device is unusable at EVERY
// Main tier, so one flaky/early probe cannot do that.
if (key === '1:120') {
var anyMainUsable = CODEC_PROBES.some(function (p) {
if (p.key === '1:120' || p.key.charAt(0) !== '1') return false;
var m = NS.caps.codec[p.key];
return !!m && !m.error && m.supported !== false && m.smooth !== false;
});
if (anyMainUsable) return null;
}
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 = 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 = 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);
});
}
function installCanPlayTypeOverride() {
if (NS.caps.cptMode === 'off') return;
var proto = window.HTMLVideoElement && window.HTMLVideoElement.prototype;
if (!proto || typeof proto.canPlayType !== 'function') return;
var orig = proto.canPlayType;
proto.canPlayType = function (type) {
try {
var key = hevcKey(type);
// Only a definite "no" is acted on. Anything else is the browser's call.
if (key && shouldBlock(key, NS.caps.__keep || [])) return '';
} catch (e) { /* never break the native answer */ }
return orig.apply(this, arguments);
};
NS.caps.cptPatched = true;
NS.caps.cptMode = 'on';
}
(function probeCodecs() {
// Kill switch, and the escape hatch if this ever misbehaves on a device.
try {
if (localStorage.getItem('jfvr-cpt') === 'off') { NS.caps.cptMode = 'off'; return; }
} catch (e) {}
var mc = navigator.mediaCapabilities;
if (!mc || typeof mc.decodingInfo !== 'function') { NS.caps.cptMode = 'no-api'; return; }
// Read the pin list once, up front: canPlayType is synchronous and must not
// touch localStorage on every call.
NS.caps.__keep = readKeepList();
// Install FIRST, synchronously, so the hook is in place before anything can
// read canPlayType. Until a verdict lands the hook just defers to native,
// which is the safe default.
installCanPlayTypeOverride();
var pending = CODEC_PROBES.length;
CODEC_PROBES.forEach(function (p) {
var cfg = {
type: 'file',
video: {
contentType: 'video/mp4; codecs="' + p.codec + '"',
width: p.w, height: p.h, bitrate: p.mbps * 1000000, framerate: p.fps
}
};
mc.decodingInfo(cfg).then(function (info) {
NS.caps.codec[p.key] = {
key: p.key, name: p.name, workload: p.w + 'x' + p.h + '@' + p.fps + ' ' + p.mbps + 'Mbps',
supported: info.supported, smooth: info.smooth, powerEfficient: info.powerEfficient
};
}).catch(function (e) {
NS.caps.codec[p.key] = { key: p.key, name: p.name, error: String(e && e.message || e) };
}).then(function () {
if (--pending === 0) {
applyVerdicts();
NS.log('codec probe done; blocked = ' + (NS.caps.codecBlocked.join(', ') || 'none') +
(NS.caps.codecKept.length ? '; pinned = ' + NS.caps.codecKept.join(', ') : ''));
}
});
});
})();
NS.capsDiag = function () {
var c = NS.caps;
var keep = readKeepList();
var real = CODEC_PROBES.map(function (p) {
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 = 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 + ']' + note;
}).join('\n');
return [
'origin : ' + location.origin,
'secureContext : ' + c.secureContext,
@@ -347,7 +631,11 @@
'createQuadLayer : ' + c.hasQuadLayer,
'hand tracking API : ' + c.hasHandTracking + ' / jointSpace=' + c.hasXRJointSpace + ' / getJointPose=' + c.hasGetJointPose,
'MAX_TEXTURE_SIZE : ' + c.maxTextureSize,
'HEVC : ' + JSON.stringify(c.hevc)
'HEVC canPlayType : ' + JSON.stringify(c.hevc),
'canPlayType hook : ' + (c.cptMode || 'pending') +
(c.cptMode === 'on' ? ' (blocked: ' + (c.codecBlocked.join(', ') || 'nothing yet') + ')' : ''),
'HEVC real (decodingInfo):',
real
].join('\n');
};
})();
+379 -34
View File
@@ -57,6 +57,30 @@
var DIFF_SUM = 24; // per-sample channel delta that counts as a changed sample
var HUD_TEX_W = 2048; // target texture width (≈30 px/deg for a 2 m strip @ 1.45 m)
var HUD_TEX_ASPECT = 0.28; // texH = texW * this (room for multi-line subtitles)
// ADDENDUM 9 — dual-eye vs normal (mono) subtitle layout, auto-detected.
// The libass canvas holds EITHER a stereo left/right pair (two copies, one per
// eye; the left half is the left eye) OR a single normal subtitle positioned
// across the whole frame.
//
// IMPORTANT: dual-eye is NOT a pixel mirror. Both eyes carry the SAME text at
// mirrored POSITIONS; the glyphs are not flipped, so comparing left[x] with
// right[W-1-x] fails badly (measured mean delta ~258/1020, i.e. "not a mirror").
// What IS true is that the two halves' ink COLUMN profiles match under a small
// horizontal shift, because they are the same line of text. Measured on device:
// dual -> normalised copy distance 0.02, mono -> 1.00, seam ink present only for
// mono. So the copy test is the discriminator.
var CENTER_BAND_PX = 40; // source px around the eye seam that count as "centre ink"
var COPY_TOL = 0.25; // column-profile copy distance for "two copies of one line"
// (measured: dual 0.02-0.08, mono 1.00)
// ADDENDUM 10 — Jellyfin only routes ssa/ass through SubtitlesOctopus (the
// libass canvas). Every other text codec (subrip, vtt, ...) is drawn by the
// BROWSER from a TextTrack (`video.addTextTrack` + mode 'showing'), so there is
// no canvas at all to sample. The HUD then paints the active cue itself into a
// private canvas and feeds it through the same crop/upload pipeline.
var NATIVE_W = 1920, NATIVE_H = 1080;
var NATIVE_FONT_H = 0.052; // cue font size as a fraction of the canvas height
var NATIVE_LINE_H = 1.32; // line advance
var NATIVE_MAX_W = 0.9; // max text width as a fraction of the canvas width
var SPHERE_TEX_W = 4096; // legacy equirect layer size
var SPHERE_TEX_H = 2048;
var OPACITY_DEFAULT = 0.85; // dim the strip below full opacity by default
@@ -123,8 +147,19 @@
cropCanvas: null,
cropCtx: null,
srcW: 0, srcH: 0, halfW: 1,
srcW: 0, srcH: 0, halfW: 1, fullW: 1, eyeW: 1,
texW: 0, texH: 0,
// ADDENDUM 9: layout is the user setting ('auto' | 'dual' | 'mono'); dualEye
// is the resolved result (auto-detected when layout === 'auto').
layout: (S.subLayout === 'dual' || S.subLayout === 'mono') ? S.subLayout : 'auto',
dualEye: true,
mismatch: 0, // consecutive samples disagreeing with dualEye (debounce)
copyND: null, // diagnostics: normalised column-profile copy distance
centerInk: null, // diagnostics: ink pixels in the seam band
colL: null, colR: null, // reused column-profile scratch (half width each)
// ADDENDUM 10: where the HUD's source pixels come from.
srcKind: 'none', // 'libass' | 'native' | 'none'
nativeCanvas: null, nativeCtx: null, nativeText: null,
bbox: null,
lastSample: null,
hasInk: false,
@@ -145,6 +180,174 @@
catch (e) { return null; }
}
/* ================================================================
* ADDENDUM 10 — native (non-libass) subtitle source
* Jellyfin asks the browser to render subrip/vtt cues from a TextTrack, so the
* HUD has no canvas to read. Read the active cue, paint it into a private
* canvas, and let the normal crop/upload path take over from there.
* ============================================================== */
function ensureNativeCanvas() {
if (!M.nativeCanvas) {
try {
M.nativeCanvas = document.createElement('canvas');
M.nativeCanvas.width = NATIVE_W;
M.nativeCanvas.height = NATIVE_H;
M.nativeCtx = M.nativeCanvas.getContext('2d');
// Kept in the DOM but hidden: Canvas2D works detached too, and this makes
// the exact pixels the HUD uploads inspectable from DevTools.
M.nativeCanvas.className = 'jfvr-native-subs';
M.nativeCanvas.style.display = 'none';
(document.body || document.documentElement).appendChild(M.nativeCanvas);
} catch (e) { M.nativeCtx = null; }
}
return !!M.nativeCtx;
}
// Jellyfin renders non-ASS text subtitles one of two ways depending on the
// build: into a TextTrack (video.addTextTrack + mode 'showing', the browser
// shows it through ::cue) or into a DOM overlay (div.videoSubtitlesInner).
// Both leave no canvas behind.
function hasNativeTracks() {
try {
var v = S.video;
if (v && v.textTracks) {
for (var i = 0; i < v.textTracks.length; i++) {
var tr = v.textTracks[i];
if (tr && tr.mode === 'showing' && tr.cues && tr.cues.length) return true;
}
}
if (document.querySelector('.videoSubtitlesInner')) return true;
} catch (e) {}
return false;
}
function activeNativeText() {
var out = [];
try {
var v = S.video;
if (v && v.textTracks) {
for (var i = 0; i < v.textTracks.length; i++) {
var tr = v.textTracks[i];
if (!tr || tr.mode !== 'showing') continue;
var cues = tr.activeCues; // maintained by the browser
if (!cues) continue;
for (var j = 0; j < cues.length; j++) {
var s = cues[j] && cues[j].text;
if (s) out.push(s);
}
}
}
if (!out.length) {
var d = document.querySelector('.videoSubtitlesInner, .videoSubtitles');
if (d) { var t = d.innerText || ''; if (t) out.push(t); }
}
} catch (e) { return ''; }
return out.join('\n');
}
function cleanCueText(s) {
return String(s == null ? '' : s)
.replace(/\{[^}]*\}/g, '') // ASS override tags
.replace(/<[^>]*>/g, '') // html-ish tags
.replace(/&nbsp;/g, ' ').replace(/&amp;/g, '&')
.replace(/&lt;/g, '<').replace(/&gt;/g, '>')
.replace(/[\u200e\u200f\u202a-\u202e]/g, '') // bidi control marks
.replace(/\r/g, '')
.replace(/[ \t]+\n/g, '\n')
.replace(/\n{3,}/g, '\n\n')
.trim();
}
function wrapCueLines(ctx, text, maxW) {
var out = [];
var paras = text.split('\n');
for (var p = 0; p < paras.length; p++) {
var para = paras[p];
if (!para) { out.push(''); continue; }
var line = '';
for (var i = 0; i < para.length; i++) {
var ch = para[i];
if (line && ctx.measureText(line + ch).width > maxW) {
var sp = line.lastIndexOf(' ');
if (sp > 0 && /[A-Za-z0-9]/.test(line.charAt(line.length - 1))) {
out.push(line.slice(0, sp));
line = line.slice(sp + 1);
} else {
out.push(line);
line = '';
}
}
line += ch;
}
out.push(line);
}
return out.length ? out : [''];
}
function drawNativeCue(text) {
var c = M.nativeCanvas, ctx = M.nativeCtx;
if (!c || !ctx) return;
var W = c.width, H = c.height;
ctx.clearRect(0, 0, W, H);
if (!text) return;
var fs = Math.max(12, Math.round(H * NATIVE_FONT_H));
ctx.font = '600 ' + fs + 'px "Noto Sans SC","Noto Sans CJK SC","PingFang SC",' +
'"Microsoft YaHei",system-ui,Arial,sans-serif';
ctx.textAlign = 'center';
ctx.textBaseline = 'middle';
ctx.lineJoin = 'round';
ctx.miterLimit = 2;
var lines = wrapCueLines(ctx, text, W * NATIVE_MAX_W);
var lh = fs * NATIVE_LINE_H;
var y0 = H / 2 - (lines.length - 1) * lh / 2;
ctx.lineWidth = Math.max(2, Math.round(fs * 0.1));
ctx.strokeStyle = 'rgba(0,0,0,0.95)';
ctx.fillStyle = '#ffffff';
for (var i = 0; i < lines.length; i++) {
ctx.strokeText(lines[i], W / 2, y0 + i * lh);
ctx.fillText(lines[i], W / 2, y0 + i * lh);
}
}
// Decide, per frame, which canvas the HUD samples. libass wins when Jellyfin
// created one; otherwise the native cue canvas. Returns false when there is no
// subtitle source at all.
function updateSource() {
var lib = getCanvas();
if (lib && lib.width > 0 && lib.height > 0) {
if (M.srcKind !== 'libass') {
M.srcKind = 'libass';
M.canvas = lib;
M.nativeText = null;
M.lastSample = null; M.hasInk = false; M.bbox = null;
computeTexDims();
M.needRebuild = true;
}
return true;
}
if (!hasNativeTracks()) {
if (M.srcKind !== 'none') { M.srcKind = 'none'; M.hasInk = false; M.bbox = null; M.dirty = true; }
return false;
}
if (!ensureNativeCanvas()) return false;
var text = cleanCueText(activeNativeText());
if (text !== M.nativeText) {
M.nativeText = text;
drawNativeCue(text);
M.dirty = true;
}
if (M.srcKind !== 'native') {
M.srcKind = 'native';
M.canvas = M.nativeCanvas;
M.dualEye = false; // our own canvas is always one centred line
M.mismatch = 0;
M.lastSample = null; M.hasInk = false; M.bbox = null;
computeTexDims();
M.needRebuild = true;
}
return true;
}
function getHolder(video) {
var holder = null;
try { holder = document.querySelector('.videoPlayerContainer'); } catch (e) {}
@@ -159,6 +362,13 @@
st.subLayer = !!M.layer;
st.subPrepared = !!M.prepared;
st.subCanvasSize = M.canvas ? (M.canvas.width + 'x' + M.canvas.height) : null;
st.subSource = M.srcKind;
st.subNativeText = M.nativeText ? M.nativeText.slice(0, 60) : null;
st.subLayout = M.layout;
st.subDual = M.dualEye;
st.subEyeW = M.eyeW;
st.subCopyND = (M.copyND == null) ? null : +M.copyND.toFixed(3);
st.subCenterInk = M.centerInk;
st.subTex = (M.texW && M.texH) ? (M.texW + 'x' + M.texH) : null;
st.subInk = M.hasInk;
st.subCrop = M.bbox ? [
@@ -183,6 +393,10 @@
* ============================================================== */
function prepare() {
if (M.prepared) return; // idempotent via a live flag, not a backup check
// Only libass needs the box blown up so it re-renders bigger. The native cue
// canvas is ours, so resizing the player would be pointless (and would move
// the browser's own cue overlay around).
if (!getCanvas()) { log('prepare skipped: native subtitle source'); return; }
var video = S.video || null;
var holder = getHolder(video);
try {
@@ -253,13 +467,17 @@
var maxTex = maxTexSize();
M.srcW = cw;
M.srcH = ch;
M.halfW = Math.max(1, Math.floor(cw / 2)); // mono HUD uses the LEFT half only
M.fullW = Math.max(1, cw);
M.halfW = Math.max(1, Math.floor(cw / 2));
// ADDENDUM 9: the HUD samples ONE eye's subtitle region. Dual-eye packs both
// eyes into the canvas; a normal subtitle uses the whole frame.
M.eyeW = M.dualEye ? M.halfW : M.fullW;
if (M.mode === 'sphere') {
M.texW = Math.max(2, Math.min(SPHERE_TEX_W, maxTex, cw || 2));
M.texH = Math.max(2, Math.min(SPHERE_TEX_H, maxTex, ch || 2));
} else {
M.texW = Math.max(2, Math.min(HUD_TEX_W, maxTex, M.halfW));
M.texW = Math.max(2, Math.min(HUD_TEX_W, maxTex, M.eyeW));
M.texH = Math.max(2, Math.min(maxTex, Math.round(M.texW * HUD_TEX_ASPECT)));
}
}
@@ -415,6 +633,7 @@
if (S.subMode === 'hud' || S.subMode === 'sphere' || S.subMode === 'off') M.mode = S.subMode;
if (S.subAlpha === 'premultiplied' || S.subAlpha === 'straight') M.alpha = S.subAlpha;
readLayoutSetting();
if (isNum(S.subOpacity)) M.opacity = clamp01(S.subOpacity);
else S.subOpacity = M.opacity;
if (typeof S.subLockAngle === 'boolean') M.lockAngle = S.subLockAngle;
@@ -424,10 +643,6 @@
if (M.mode === 'off') { log('create: subtitle mode off'); return null; }
var canvas = getCanvas();
if (!canvas || !canvas.width || !canvas.height) {
setErr('no libass canvas'); log('create: no <canvas.libassjs-canvas>'); return null;
}
if (typeof window.XRWebGLBinding !== 'function') {
setErr('no XRWebGLBinding'); log('create: no XRWebGLBinding'); return null;
}
@@ -439,11 +654,17 @@
var gl = NS.xrGl(true);
if (!gl) { setErr('no webgl2'); log('create: no webgl2 context'); return null; }
M.canvas = canvas;
M.gl = gl;
M.glCanvas = gl.canvas;
M.uploads = 0;
M.samples = 0;
// ADDENDUM 10: the source may be the libass canvas OR our own cue canvas.
// Start on the native canvas so create() works even before Jellyfin has
// created its renderer, then updateSource() upgrades to libass if it shows up.
ensureNativeCanvas();
M.canvas = M.nativeCanvas;
M.srcKind = 'none';
updateSource();
computeTexDims();
if (!M.texW || !M.texH) { setErr('bad canvas size'); log('create: bad canvas size'); destroy(); return null; }
@@ -490,13 +711,15 @@
var layer = attachLayer(session);
if (!layer) throw new Error('layer creation returned null');
M.needRebuild = false; // the source was already resolved above
sample(); // seed bbox / hasInk before the first XR frame
M.dirty = true;
setErr(null);
updateStats();
log('subtitles layer created:', M.mode, M.texW + 'x' + M.texH,
'alpha=' + M.alpha, 'canvas=' + canvas.width + 'x' + canvas.height);
'alpha=' + M.alpha, 'source=' + M.srcKind,
'canvas=' + (M.canvas ? M.canvas.width + 'x' + M.canvas.height : 'none'));
return layer;
} catch (e) {
setErr((e && e.message) || e);
@@ -522,9 +745,11 @@
} catch (e) {}
M.gl = null; M.glCanvas = null; M.prog = null; M.tex = null; M.fbo = null;
M.binding = null; M.session = null; M.canvas = null;
M.srcKind = 'none'; M.nativeText = null;
M.sampleCanvas = null; M.sampleCtx = null;
M.cropCanvas = null; M.cropCtx = null;
M.srcW = 0; M.srcH = 0; M.halfW = 1; M.texW = 0; M.texH = 0;
M.srcW = 0; M.srcH = 0; M.halfW = 1; M.fullW = 1; M.eyeW = 1; M.texW = 0; M.texH = 0;
M.copyND = null; M.centerInk = null; M.colL = null; M.colR = null; M.mismatch = 0;
M.bbox = null; M.lastSample = null;
M.hasInk = false; M.lastDrawnInk = false;
M.dirty = false; M.needRebuild = false;
@@ -571,6 +796,24 @@
return true;
}
// ADDENDUM 9: normalised distance between the two halves' ink column profiles at
// their best horizontal alignment. ~0 for dual-eye (same line, two copies), ~1
// for a normal subtitle (the halves are different parts of one line).
function columnCopyND(colL, colR, half) {
var D = Math.round(half * 0.4), best = 1e9;
for (var lag = -D; lag <= D; lag++) {
var diff = 0, tot = 0;
for (var i = 0; i < half; i++) {
var j = i + lag;
var r = (j >= 0 && j < half) ? colR[j] : 0;
diff += Math.abs(colL[i] - r);
tot += colL[i] + r;
}
if (tot > 0) { var nd = diff / tot; if (nd < best) best = nd; }
}
return (best === 1e9) ? 1 : best;
}
function sample() {
var canvas = M.canvas;
var ctx = M.sampleCtx;
@@ -595,11 +838,20 @@
var d = img.data;
var prev = M.lastSample;
var hud = (M.mode === 'hud');
var half = hud ? (SAMPLE_W >> 1) : SAMPLE_W; // HUD bbox: LEFT half only
var minX = half + 1, minY = SAMPLE_H + 1, maxX = -1, maxY = -1;
var half = SAMPLE_W >> 1;
var diff = 0;
var sx = cw / SAMPLE_W, sy = ch / SAMPLE_H;
var padX = PAD_PX / sx, padY = PAD_PX / sy;
var band = Math.max(1, Math.round(CENTER_BAND_PX / sx));
// Track the ink box of each REGION separately so the layout can be resolved
// before cropping: l* = left half, r* = right half, centerInk = the seam.
var lMinX = SAMPLE_W + 1, lMaxX = -1, lMinY = SAMPLE_H + 1, lMaxY = -1;
var rMinX = SAMPLE_W + 1, rMaxX = -1, rMinY = SAMPLE_H + 1, rMaxY = -1;
var centerInk = 0;
if (!M.colL) { M.colL = new Int32Array(half); M.colR = new Int32Array(half); }
var colL = M.colL, colR = M.colR;
colL.fill(0); colR.fill(0);
for (var y = 0; y < SAMPLE_H; y++) {
var row = y * SAMPLE_W * 4;
@@ -610,11 +862,21 @@
Math.abs(d[i + 2] - prev[i + 2]) + Math.abs(d[i + 3] - prev[i + 3]);
if (dd > DIFF_SUM) diff++;
}
if (hud && x < half && d[i + 3] > INK_ALPHA) {
if (x < minX) minX = x;
if (x > maxX) maxX = x;
if (y < minY) minY = y;
if (y > maxY) maxY = y;
if (!hud || d[i + 3] <= INK_ALPHA) continue;
if (x < half) {
if (x < lMinX) lMinX = x;
if (x > lMaxX) lMaxX = x;
if (y < lMinY) lMinY = y;
if (y > lMaxY) lMaxY = y;
if (x > half - band) centerInk++;
colL[x]++;
} else {
if (x < rMinX) rMinX = x;
if (x > rMaxX) rMaxX = x;
if (y < rMinY) rMinY = y;
if (y > rMaxY) rMaxY = y;
if (x < half + band) centerInk++;
colR[x - half]++;
}
}
}
@@ -622,20 +884,63 @@
M.lastSample = d;
if (!prev || diff > DIFF_SAMPLES) M.dirty = true; // content changed -> re-upload
if (!hud) { updateStats(); return; }
if (hud) {
if (maxX < 0) {
if (M.hasInk) { M.hasInk = false; M.dirty = true; } // clear the strip once
} else {
var raw = quantise({
x0: Math.max(0, (minX - padX) * sx),
y0: Math.max(0, (minY - padY) * sy),
x1: Math.min(cw / 2, (maxX + 1 + padX) * sx),
y1: Math.min(ch, (maxY + 1 + padY) * sy)
});
if (!M.hasInk) { M.hasInk = true; M.bbox = raw; M.dirty = true; }
else if (updateBBox(raw)) M.dirty = true;
// ---- ADDENDUM 9: resolve dual-eye vs mono ----------------------------
// dual-eye: two copies of the same line -> no ink at the seam AND the two
// halves' column profiles match under a horizontal shift. mono: one line
// across the whole frame -> ink crosses the seam and the halves do not match.
var hasLeft = lMaxX >= 0, hasRight = rMaxX >= 0;
var hasInk = hasLeft || hasRight || centerInk > 0;
if (hasInk) {
M.centerInk = centerInk;
var dual = M.dualEye;
if (M.srcKind === 'native') { M.copyND = null; dual = false; } // our own canvas is always mono
else if (M.layout === 'dual') dual = true;
else if (M.layout === 'mono') dual = false;
else if (hasLeft && hasRight) {
if (centerInk > 0) { M.copyND = null; dual = false; }
else { M.copyND = columnCopyND(colL, colR, half); dual = (M.copyND < COPY_TOL); }
}
else dual = !!hasLeft; // ink in ONE half -> dual (left) else mono (right)
if (dual !== M.dualEye) {
// Debounce: a layout switch rebuilds the layer, so require two
// consecutive samples before believing it (never observed to flicker on
// real content, but cheap insurance against a rebuild every sample).
M.mismatch = (M.mismatch || 0) + 1;
if (M.mismatch >= 2) {
M.mismatch = 0;
M.dualEye = dual;
computeTexDims();
M.needRebuild = true; // the texture width changed with the region
}
} else M.mismatch = 0;
}
// ---- crop to the ink box of the RESOLVED region ----------------------
var x0s, y0s, x1s, y1s;
if (hasInk) {
if (M.dualEye && hasLeft) {
x0s = lMinX; y0s = lMinY; x1s = lMaxX; y1s = lMaxY;
} else {
x0s = hasLeft ? lMinX : rMinX;
x1s = hasRight ? rMaxX : lMaxX;
y0s = Math.min(hasLeft ? lMinY : Infinity, hasRight ? rMinY : Infinity);
y1s = Math.max(hasLeft ? lMaxY : -1, hasRight ? rMaxY : -1);
}
}
if (!hasInk) {
if (M.hasInk) { M.hasInk = false; M.dirty = true; } // clear the strip once
} else {
var raw = quantise({
x0: Math.max(0, (x0s - padX) * sx),
y0: Math.max(0, (y0s - padY) * sy),
x1: Math.min(M.eyeW, (x1s + 1 + padX) * sx),
y1: Math.min(ch, (y1s + 1 + padY) * sy)
});
if (!M.hasInk) { M.hasInk = true; M.bbox = raw; M.dirty = true; }
else if (updateBBox(raw)) M.dirty = true;
}
updateStats();
}
@@ -648,9 +953,9 @@
var b = M.bbox;
if (!gl || !b) return;
var cw = Math.max(1, Math.min(M.halfW, Math.round(b.x1 - b.x0)));
var cw = Math.max(1, Math.min(M.eyeW, Math.round(b.x1 - b.x0)));
var ch = Math.max(1, Math.round(b.y1 - b.y0));
var sx = Math.max(0, Math.min(Math.max(0, M.halfW - cw), Math.round(b.x0)));
var sx = Math.max(0, Math.min(Math.max(0, M.eyeW - cw), Math.round(b.x0)));
var sy = Math.max(0, Math.min(Math.max(0, M.srcH - ch), Math.round(b.y0)));
var crop = M.cropCanvas, cctx = M.cropCtx;
@@ -658,7 +963,7 @@
cctx.clearRect(0, 0, cw, ch);
cctx.drawImage(M.canvas, sx, sy, cw, ch, 0, 0, cw, ch);
var scale = M.texW / M.halfW; // texture px per source px
var scale = M.texW / M.eyeW; // texture px per source px
var dw = cw * scale, dh = ch * scale;
var fit = Math.min(1, tw / dw, th / dh); // never overflow the colorTexture
dw *= fit; dh *= fit;
@@ -747,7 +1052,11 @@
: (frame.predictedDisplayTime != null ? frame.predictedDisplayTime
: (window.performance ? performance.now() : Date.now()));
if (t - M.lastSampleT >= SAMPLE_MS || M.lastSampleT < 0) {
// Keep the source current every frame (native cue text changes on its own).
var hasSrc = updateSource();
if (!hasSrc) {
if (M.hasInk) { M.hasInk = false; M.bbox = null; M.dirty = true; }
} else if (t - M.lastSampleT >= SAMPLE_MS || M.lastSampleT < 0) {
M.lastSampleT = t;
sample();
}
@@ -767,6 +1076,38 @@
/* ================================================================
* settings (safe before or during a session)
* ============================================================== */
// ADDENDUM 9 — read state.subLayout into the module. A forced layout resolves
// immediately; 'auto' keeps the current guess until sample() sees ink.
function readLayoutSetting() {
if (S.subLayout === 'dual' || S.subLayout === 'mono') M.layout = S.subLayout;
else { M.layout = 'auto'; if (S.subLayout !== 'auto') S.subLayout = 'auto'; }
if (M.layout !== 'auto') { M.dualEye = (M.layout === 'dual'); M.mismatch = 0; }
}
// Force home the dual-eye / mono decision, or go back to auto-detection.
function setLayout(mode) {
if (mode !== 'auto' && mode !== 'dual' && mode !== 'mono') return;
M.layout = mode;
S.subLayout = mode;
if (!M.canvas) { updateStats(); return; }
if (mode === 'auto') {
M.bbox = null; M.hasInk = false; M.mismatch = 0; M.dirty = true; // re-detect from the next sample
} else {
var forced = (mode === 'dual');
if (forced !== M.dualEye) {
M.dualEye = forced;
M.bbox = null; M.hasInk = false;
M.mismatch = 0;
computeTexDims();
M.needRebuild = true;
M.dirty = true;
}
}
updateStats();
}
function getLayout() { return M.layout; }
function setMode(mode) {
if (mode !== 'hud' && mode !== 'sphere' && mode !== 'off') return;
var changed = (M.mode !== mode);
@@ -981,6 +1322,7 @@
else if (S.subMode) S.subMode = M.mode;
if (S.subAlpha === 'premultiplied' || S.subAlpha === 'straight') M.alpha = S.subAlpha;
else if (S.subAlpha) S.subAlpha = M.alpha;
readLayoutSetting();
if (isNum(S.subOpacity)) M.opacity = clamp01(S.subOpacity);
else S.subOpacity = M.opacity;
if (typeof S.subLockAngle === 'boolean') M.lockAngle = S.subLockAngle;
@@ -1006,6 +1348,8 @@
create: create,
destroy: destroy,
setMode: setMode,
setLayout: setLayout,
getLayout: getLayout,
setAlphaMode: setAlphaMode,
setPlacement: setPlacement,
getPlacement: getPlacement,
@@ -1017,6 +1361,7 @@
setOpacity: setOpacity,
getOpacity: getOpacity,
getLayer: getLayer,
getMode: getMode
getMode: getMode,
getSourceKind: function () { return M.srcKind; }
};
})();
+4 -1
View File
@@ -1532,8 +1532,11 @@
return d > 0 ? d : null;
}
// ADDENDUM 11b: the beam reaches the panel plane whenever the ray meets it,
// even when the intersection is off the panel (there is simply no cursor then).
// Previously it fell back to a fixed length without a hit, so an edge-aimed
// beam stopped short of the plane while the cursor was clamped to the border.
function beamLength(p) {
if (!p.hit) return BEAM_L_DEFAULT;
var d = num(p.distance);
if (d == null) d = panelDistance(p);
if (d == null || !(d > BEAM_L_MIN)) return BEAM_L_DEFAULT;
+357
View File
@@ -0,0 +1,357 @@
/*!
* JFVR watchdog — "this video never started" detection.
*
* WHY THIS EXISTS
* ---------------
* Jellyfin Web builds the whole player UI (including the quality menu) only
* after the 'playbackstart' event, which the media element fires once it has
* actually started. The load order is:
*
* HtmlVideoPlayer.play() htmlVideoPlayer/plugin.js:502
* createMediaElement() :1802 -> loading.show() spinner
* -> <div.videoPlayerContainer><video>
* -> inserted into document.body
* (no src yet!)
* setCurrentSrc() :593 -> elem.src = url, only now
* -> loadedmetadata -> canplay -> play
* -> 'playbackstart'
* -> OSD controller (apps/legacy/controllers/playback/video/index.js:591)
*
* So when the browser cannot use the stream, the OSD never appears at all: the
* page is a spinner over an empty container with a <video> whose videoWidth is
* still 0. There is no quality menu to click, because it was never created.
*
* That is the case this module covers. It watches for exactly that state and
* offers the only thing that can help: tell Jellyfin to transcode.
*
* WHY localStorage AND NOT THE PLAYBACK MANAGER
* --------------------------------------------
* The bitrate is normally set through playbackManager.setMaxStreamingBitrate(),
* which does a live changeStream(). That manager is an ES module export and is
* NOT on window (verified: window.playbackManager is undefined; window.Emby only
* has Page). So the watchdog writes the same keys appSettings would have written
* (src/scripts/settings/appSettings.js) and reloads, which makes Jellyfin request
* PlaybackInfo again with the new cap and pick Transcode.
*
* NOTE the key name really does say "bitrate" twice — that is upstream's typo,
* reproduced here deliberately.
*/
(function () {
'use strict';
var NS = window.__JFVR;
if (!NS) { console.error('[JFVR] core missing'); return; }
if (NS.__watchdog) return;
NS.__watchdog = true;
var S = NS.state;
var log = NS.log;
/* ------------------------------------------------------------------ *
* tunables
* ------------------------------------------------------------------ */
var POLL_MS = 500;
// Direct play on a LAN should have metadata almost immediately; the file is
// 11 GB but its moov atom is at the front, so there is nothing to wait for.
// A transcode is different: the server has to decode the first GOP and produce
// segments before the browser sees any metadata, and this NAS is doing 8K.
var DEAD_MS = 15000;
var DEAD_TRANSCODE_MS = 45000;
// After the user answers (either way) stay quiet, so a slow-but-working
// playback does not get nagged at.
var QUIET_MS = 120000;
var QUIET_KEY = 'jfvr-watchdog-quiet-until';
// Values from Jellyfin's own menu (src/components/qualityOptions.js).
var CHOICES = [
{ label: '20 Mbps', bitrate: 20000000, note: '≈4K,最接近原始画质' },
{ label: '8 Mbps', bitrate: 8000000, note: '1080p 档,稳' },
{ label: '3 Mbps', bitrate: 3000000, note: '720p 档,最省算力' }
];
var W = {
seenAt: 0, // when the current stalled <video> first showed up
shown: false,
quietUntil: 0,
lastReason: '',
applied: null,
codec: null, // filled in best-effort from the Jellyfin API
panel: null
};
NS.Watchdog = W;
/* ------------------------------------------------------------------ *
* helpers
* ------------------------------------------------------------------ */
function now() { return Date.now(); }
/**
* The element Jellyfin creates in createMediaElement(). It exists from the
* very start of playback — including the failure case, which is the whole
* point: findVideo() in 90-main.js requires videoWidth and would return null.
*/
function playerVideo() {
var c = document.querySelector('.videoPlayerContainer');
if (!c) return null;
return c.querySelector('video') || null;
}
function isTranscode(v) {
var src = v.currentSrc || v.src || '';
return src.indexOf('/hls') >= 0 || src.indexOf('.m3u8') >= 0;
}
/** Metadata parsed AND a frame available. False means "no picture". */
function hasPicture(v) {
return v.videoWidth > 0 && v.readyState >= 2;
}
function readQuiet() {
try {
var raw = window.sessionStorage && sessionStorage.getItem(QUIET_KEY);
return raw ? parseInt(raw, 10) || 0 : 0;
} catch (e) { return 0; }
}
function setQuiet(ms) {
W.quietUntil = now() + ms;
try { sessionStorage.setItem(QUIET_KEY, String(W.quietUntil)); } catch (e) {}
}
/**
* Write the same keys Jellyfin's own quality menu writes, for BOTH in-network
* and out-of-network, because the client is the only side that knows which one
* applies and we cannot ask it (appSettings is not on window).
*/
function applyBitrate(bitrate) {
var media = 'Video';
['true', 'false'].forEach(function (inNet) {
try {
localStorage.setItem('enableautobitratebitrate-' + media + '-' + inNet, 'false');
localStorage.setItem('maxbitrate-' + media + '-' + inNet, String(bitrate));
} catch (e) {
log('watchdog: could not persist bitrate', e && e.message);
}
});
W.applied = bitrate;
log('watchdog: capped bitrate at', bitrate, 'and reloading');
setQuiet(QUIET_MS);
window.location.reload();
}
/* ------------------------------------------------------------------ *
* best-effort: name the actual format so the message is actionable
* ------------------------------------------------------------------ */
function itemIdFrom(v) {
var s = (v && (v.currentSrc || v.src)) || '';
var m = s.match(/\/Videos\/([0-9a-f]{32})\//i);
if (m) return m[1];
m = (window.location.hash || '').match(/[?&]id=([0-9a-f]{32})/i);
return m ? m[1] : null;
}
function describeCodec(v) {
if (W.codec) return;
var id = itemIdFrom(v);
if (!id || !window.ApiClient) return;
var url;
try { url = window.ApiClient.getUrl('Items/' + id); } catch (e) { return; }
window.ApiClient.ajax({ type: 'GET', url: url, dataType: 'json' }).then(function (item) {
var ms = (item && item.MediaSources && item.MediaSources[0] && item.MediaSources[0].MediaStreams) || [];
for (var i = 0; i < ms.length; i++) {
var st = ms[i];
if (st.Type !== 'Video') continue;
W.codec = [
st.Width + '×' + st.Height,
(st.Codec || '').toUpperCase(),
st.Profile || '',
st.BitDepth ? st.BitDepth + '-bit' : ''
].filter(Boolean).join(' ');
break;
}
if (W.shown) render(); // update the message in place
}).catch(function () { /* the prompt works fine without this */ });
}
/* ------------------------------------------------------------------ *
* the prompt
* ------------------------------------------------------------------ */
var WD_CSS = [
'.jfvr-wd{position:fixed;left:50%;top:50%;transform:translate(-50%,-50%);z-index:2147483002;width:420px;max-width:calc(100vw - 32px);',
'background:rgba(18,18,22,.97);color:#eaeaea;border:1px solid rgba(255,255,255,.16);border-radius:14px;',
'box-shadow:0 18px 60px rgba(0,0,0,.7);font-family:inherit;font-size:14px;padding:18px 18px 14px;backdrop-filter:blur(10px)}',
'.jfvr-wd h3{margin:0 0 6px;font-size:16px;font-weight:600}',
'.jfvr-wd p{margin:0 0 10px;font-size:13px;line-height:1.6;color:#c3c9d4}',
'.jfvr-wd .jfvr-wd-fmt{color:#ffd479;font-weight:600}',
'.jfvr-wd .jfvr-wd-sub{font-size:12px;color:#8b93a1;line-height:1.55;margin-bottom:12px}',
'.jfvr-wd-btns{display:flex;flex-direction:column;gap:8px;margin-bottom:10px}',
'.jfvr-wd-btns button{display:flex;justify-content:space-between;align-items:baseline;gap:10px;width:100%;padding:10px 12px;',
'border:1px solid rgba(255,255,255,.16);border-radius:9px;background:rgba(255,255,255,.05);color:#eaeaea;',
'font-size:14px;font-weight:600;cursor:pointer;font-family:inherit;text-align:left}',
'.jfvr-wd-btns button:hover{background:rgba(78,161,255,.18);border-color:#4ea1ff}',
'.jfvr-wd-btns button span.note{font-size:11px;font-weight:400;color:#8b93a1}',
'.jfvr-wd-quiet{width:100%;padding:9px;border:0;border-radius:9px;background:transparent;color:#8b93a1;',
'font-size:13px;cursor:pointer;font-family:inherit}',
'.jfvr-wd-quiet:hover{color:#eaeaea}',
'.jfvr-wd-diag{margin-top:10px;font-size:11px;color:#8b93a1}',
'.jfvr-wd-diag summary{cursor:pointer;user-select:none}',
'.jfvr-wd-diag pre{white-space:pre-wrap;word-break:break-all;margin:8px 0 0;font-size:10px;line-height:1.5;',
'max-height:150px;overflow:auto;color:#9fb0c4;background:rgba(0,0,0,.35);padding:8px;border-radius:7px}'
].join('');
function injectWdCss() {
if (document.getElementById('jfvr-wd-css')) return;
var s = NS.makeEl('style');
s.id = 'jfvr-wd-css';
s.textContent = WD_CSS;
document.head.appendChild(s);
}
function diagText(v) {
var e = v.error;
return [
'readyState : ' + v.readyState + ' (0=HAVE_NOTHING, 1=HAVE_METADATA, 2=HAVE_CURRENT_DATA)',
'networkState: ' + v.networkState,
'videoWidth : ' + v.videoWidth + '×' + v.videoHeight,
'paused : ' + v.paused,
'currentTime : ' + v.currentTime,
'error : ' + (e ? e.code + ' ' + (e.message || '') : 'none'),
'src : ' + String(v.currentSrc || v.src || '').slice(0, 160),
'格式 : ' + (W.codec || '(未知)')
].join('\n');
}
function render() {
if (!W.panel) return;
var body = W.panel.querySelector('.jfvr-wd-body');
var v = playerVideo();
if (body && v) {
var fmt = body.querySelector('.jfvr-wd-fmt');
if (fmt) fmt.textContent = W.codec || '这个格式';
var pre = body.querySelector('pre');
if (pre) pre.textContent = diagText(v);
}
}
function show(v, reason) {
if (W.shown) { render(); return; }
W.shown = true;
W.lastReason = reason;
injectWdCss();
var p = NS.makeEl('div', 'jfvr-wd');
p.id = 'jfvr-wd';
p.appendChild(NS.makeEl('h3', null, '视频没能开始播放'));
var body = NS.makeEl('div', 'jfvr-wd-body');
var msg = NS.makeEl('p');
var waited = Math.round(timeoutMs(v) / 1000);
msg.innerHTML =
(reason === 'error'
? '播放器报错了,一个画面都没解出来。'
: '等了 ' + waited + ' 秒都没拿到任何画面(<code>videoWidth = 0</code>),' +
'所以播放器界面也没有被创建出来。') +
'最常见的原因是<strong>这台设备解不动这个格式</strong>:' +
'<span class="jfvr-wd-fmt">' + (W.codec || '该格式') + '</span>。<br>' +
'让服务器转码成 H.264 再播就能看到画面,代价是画质下降(这台 NAS 的转码上限约 4K)。';
body.appendChild(msg);
body.appendChild(NS.makeEl('div', 'jfvr-wd-sub',
'选一档码率后会写入播放设置并重新加载页面。'));
var btns = NS.makeEl('div', 'jfvr-wd-btns');
CHOICES.forEach(function (c) {
var b = NS.makeEl('button');
b.type = 'button';
b.appendChild(NS.makeEl('span', null, c.label));
b.appendChild(NS.makeEl('span', 'note', c.note));
b.addEventListener('click', function (ev) {
ev.stopPropagation();
applyBitrate(c.bitrate);
});
btns.appendChild(b);
});
body.appendChild(btns);
var quiet = NS.makeEl('button', 'jfvr-wd-quiet', '继续等待,先别管我');
quiet.type = 'button';
quiet.addEventListener('click', function (ev) {
ev.stopPropagation();
setQuiet(QUIET_MS);
hide();
});
body.appendChild(quiet);
var diag = NS.makeEl('details', 'jfvr-wd-diag');
diag.appendChild(NS.makeEl('summary', null, '诊断信息'));
diag.appendChild(NS.makeEl('pre', null, diagText(v)));
body.appendChild(diag);
p.appendChild(body);
document.body.appendChild(p);
W.panel = p;
NS.recordError('watchdog', new Error('playback never started: ' + reason));
log('watchdog: playback never started, reason =', reason, 'codec =', W.codec);
}
function hide() {
W.shown = false;
if (W.panel) { W.panel.remove(); W.panel = null; }
}
function reset() {
W.seenAt = 0;
W.codec = null;
if (W.shown) hide();
}
function timeoutMs(v) {
return isTranscode(v) ? DEAD_TRANSCODE_MS : DEAD_MS;
}
/* ------------------------------------------------------------------ *
* poll
* ------------------------------------------------------------------ */
function poll() {
// Never interfere with an active VR session: the session owns the flow and
// a modal in the middle of it would be a disaster.
if (S.session) { if (W.shown) hide(); return; }
var v = playerVideo();
if (!v) { reset(); return; }
// Playback is fine (or at least has a picture): stand down.
if (hasPicture(v)) { reset(); return; }
// A media error is unambiguous — no need to wait out the timer.
if (v.error) {
describeCodec(v);
if (W.quietUntil && now() < W.quietUntil) return;
show(v, 'error');
return;
}
if (!W.seenAt) W.seenAt = now();
if (now() - W.seenAt < timeoutMs(v)) return;
if (W.quietUntil && now() < W.quietUntil) return;
describeCodec(v);
show(v, 'timeout');
}
NS.Watchdog.init = function () {
W.quietUntil = readQuiet();
setInterval(poll, POLL_MS);
log('watchdog armed (dead=' + DEAD_MS + 'ms, transcode=' + DEAD_TRANSCODE_MS + 'ms)');
};
})();
+396 -49
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,9 @@
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;
// subLayout is deliberately NOT restored: a persisted manual override
// silently ruined the default dual-eye content once already (forced 'mono'
// made the HUD show both eyes side by side). Layout always starts on 'auto'.
// 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
@@ -138,6 +187,7 @@
if (o.subAlpha === 'premultiplied' || o.subAlpha === 'straight') S.subAlpha = o.subAlpha;
if (o.projection === '180' || o.projection === '360') S.projection = o.projection;
if (o.stereo === 'mono' || o.stereo === 'sbs' || o.stereo === 'ou') S.stereo = o.stereo;
if (o.handPref === 'right' || o.handPref === 'left') S.handPref = o.handPref;
if (typeof o.controls === 'boolean') S.controls = o.controls;
// NOTE: `subtitles` is deliberately NOT restored. Persisting it meant a
// session where the user toggled subtitles off came back with them off,
@@ -161,6 +211,7 @@
subAlpha: S.subAlpha,
projection: S.projection,
stereo: S.stereo,
handPref: S.handPref,
videoRotMode: S.videoRotMode,
controls: S.controls,
ctlAutoHideMs: S.ctlAutoHideMs
@@ -248,16 +299,23 @@
// Sits ABOVE Jellyfin's own OSD bar: at the viewport's bottom-right it
// covered the player's fullscreen button (owner report). 120 px clears the
// OSD bottom bar; the settings panel stacks above it.
'.jfvr-btn{position:fixed;right:16px;bottom:120px;z-index:2147483000;display:flex;align-items:center;gap:8px;',
// left/top are set from JS (see placeButton) so the button can be dragged
// anywhere. touch-action:none is what makes a drag work on a touch screen
// instead of scrolling the page underneath.
'.jfvr-btn{position:fixed;z-index:2147483000;display:flex;align-items:center;gap:8px;',
'padding:10px 16px;border:0;border-radius:24px;background:linear-gradient(135deg,#4ea1ff,#7b5cff);color:#fff;',
'font-size:15px;font-weight:600;cursor:pointer;box-shadow:0 6px 22px rgba(0,0,0,.45);font-family:inherit}',
'font-size:15px;font-weight:600;cursor:grab;box-shadow:0 6px 22px rgba(0,0,0,.45);font-family:inherit;',
'touch-action:none;user-select:none;-webkit-user-select:none;-webkit-tap-highlight-color:transparent}',
'.jfvr-btn:active{transform:scale(.96)}',
'.jfvr-btn.jfvr-drag{cursor:grabbing;transform:none;box-shadow:0 10px 32px rgba(0,0,0,.65)}',
// the panel must always fit the viewport AND keep the CTA reachable, so the
// body scrolls and the button lives in a sticky footer
'.jfvr-panel{position:fixed;right:16px;bottom:180px;z-index:2147483001;width:290px;background:rgba(20,20,24,.96);',
// Positioned from JS (positionPanel) so it follows the button once the
// button has been dragged; it no longer lives in the viewport corner.
'.jfvr-panel{position:fixed;z-index:2147483001;width:290px;background:rgba(20,20,24,.96);',
'color:#eaeaea;border:1px solid rgba(255,255,255,.14);border-radius:14px;box-shadow:0 12px 40px rgba(0,0,0,.6);',
'font-family:inherit;font-size:14px;backdrop-filter:blur(10px);display:flex;flex-direction:column;',
'max-height:calc(100vh - 200px);overflow:hidden}',
'max-height:calc(100vh - 32px);overflow:hidden}',
'.jfvr-head{display:flex;justify-content:space-between;align-items:center;padding:10px 12px;background:rgba(255,255,255,.06);font-weight:600;flex:0 0 auto}',
'.jfvr-x{background:none;border:0;color:#aaa;font-size:20px;line-height:1;cursor:pointer;padding:0 4px}',
'.jfvr-body{padding:12px;overflow-y:auto;flex:1 1 auto;min-height:0}',
@@ -305,9 +363,151 @@
var b = NS.makeEl('button', 'jfvr-btn');
b.type = 'button';
b.innerHTML = '<span>&#127909;</span><span>VR 播放</span>';
b.addEventListener('click', function (ev) { ev.stopPropagation(); togglePanel(); });
b.title = '点击打开设置;按住拖动可以换位置;双击回到默认位置';
b.addEventListener('click', function (ev) {
ev.stopPropagation();
// A drag still produces a click on most browsers. Swallow that one so
// dragging the button never opens the panel by accident.
if (dragMoved) { dragMoved = false; return; }
togglePanel();
});
// Escape hatch: a button dragged half off a small window is annoying to
// recover by hand.
b.addEventListener('dblclick', function (ev) {
ev.stopPropagation();
resetButtonPos();
});
installDrag(b);
document.body.appendChild(b);
btn = b;
btnPos = readBtnPos();
placeButton(b, btnPos);
}
/* ------------------------------------------------------------------ *
* button placement / dragging
* ------------------------------------------------------------------
* The button used to be pinned to the bottom-right corner. On a short window
* that put it right on top of the bitrate choices the playback watchdog
* shows (that panel is centred), and there was no way to move it. It is
* draggable now and the spot is remembered per browser.
*
* The settings panel follows the button rather than the viewport corner, so
* the two cannot drift apart.
* ------------------------------------------------------------------ */
var BTN_POS_KEY = 'jfvr-btn-pos';
var BTN_MARGIN = 8;
var DRAG_SLOP = 4; // px of travel before it counts as a drag, not a tap
var btnPos = null; // {left, top} once placed; persisted on drop
var dragging = false;
var dragMoved = false;
var dragStart = null;
function readBtnPos() {
try {
var o = JSON.parse(localStorage.getItem(BTN_POS_KEY) || 'null');
if (o && typeof o.left === 'number' && typeof o.top === 'number') return o;
} catch (e) {}
return null;
}
function writeBtnPos(pos) {
try { localStorage.setItem(BTN_POS_KEY, JSON.stringify(pos)); } catch (e) {}
}
function clampPos(left, top, w, h) {
var maxLeft = Math.max(BTN_MARGIN, window.innerWidth - w - BTN_MARGIN);
var maxTop = Math.max(BTN_MARGIN, window.innerHeight - h - BTN_MARGIN);
return {
left: Math.round(Math.min(Math.max(left, BTN_MARGIN), maxLeft)),
top: Math.round(Math.min(Math.max(top, BTN_MARGIN), maxTop))
};
}
/** The default spot: the old fixed corner, expressed in left/top. */
function defaultPos(b) {
return { left: window.innerWidth - b.offsetWidth - 16,
top: window.innerHeight - b.offsetHeight - 120 };
}
function placeButton(b, pos) {
var p = pos || defaultPos(b);
var c = clampPos(p.left, p.top, b.offsetWidth, b.offsetHeight);
b.style.left = c.left + 'px';
b.style.top = c.top + 'px';
b.style.right = 'auto';
b.style.bottom = 'auto';
return c;
}
function resetButtonPos() {
if (!btn) return;
try { localStorage.removeItem(BTN_POS_KEY); } catch (e) {}
btnPos = placeButton(btn, null);
positionPanel();
}
function installDrag(b) {
b.addEventListener('pointerdown', function (ev) {
if (ev.button != null && ev.button !== 0) return; // primary button / touch only
var r = b.getBoundingClientRect();
dragging = true;
dragMoved = false;
dragStart = { x: ev.clientX, y: ev.clientY, left: r.left, top: r.top };
b.classList.add('jfvr-drag');
try { b.setPointerCapture(ev.pointerId); } catch (e) {}
});
b.addEventListener('pointermove', function (ev) {
if (!dragging || !dragStart) return;
var dx = ev.clientX - dragStart.x;
var dy = ev.clientY - dragStart.y;
if (!dragMoved) {
if (Math.abs(dx) < DRAG_SLOP && Math.abs(dy) < DRAG_SLOP) return;
dragMoved = true;
if (panel) hidePanel(); // do not drag the panel around with it
}
btnPos = clampPos(dragStart.left + dx, dragStart.top + dy, b.offsetWidth, b.offsetHeight);
b.style.left = btnPos.left + 'px';
b.style.top = btnPos.top + 'px';
});
function endDrag(ev) {
if (!dragging) return;
dragging = false;
dragStart = null;
b.classList.remove('jfvr-drag');
try { b.releasePointerCapture(ev.pointerId); } catch (e) {}
if (dragMoved) writeBtnPos(btnPos);
}
b.addEventListener('pointerup', endDrag);
b.addEventListener('pointercancel', endDrag);
}
/** Put the panel next to the button: above it, or below when there is no room. */
function positionPanel() {
if (!panel || !btn) return;
var b = btn.getBoundingClientRect();
var w = panel.offsetWidth;
var h = panel.offsetHeight;
var gap = 8;
var left = b.right - w; // right edges aligned
var top = b.top - h - gap;
if (top < BTN_MARGIN) top = b.bottom + gap; // no room above -> below
var maxLeft = Math.max(BTN_MARGIN, window.innerWidth - w - BTN_MARGIN);
var maxTop = Math.max(BTN_MARGIN, window.innerHeight - h - BTN_MARGIN);
panel.style.left = Math.round(Math.min(Math.max(left, BTN_MARGIN), maxLeft)) + 'px';
panel.style.top = Math.round(Math.min(Math.max(top, BTN_MARGIN), maxTop)) + 'px';
panel.style.right = 'auto';
panel.style.bottom = 'auto';
}
function onViewportResize() {
if (btn && document.body.contains(btn)) btnPos = placeButton(btn, btnPos);
positionPanel();
}
function removeButton() {
@@ -411,10 +611,26 @@
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 空间右侧有个锁图标:锁上后面板不会再被唤出。'));
body.appendChild(NS.makeEl('div', 'jfvr-sec', '操作'));
body.appendChild(segRow('主用手', function () { return S.handPref || 'right'; },
function (v) { S.handPref = v; saveSettings(); },
[{ label: '右手', value: 'right' }, { label: '左手', value: 'left' }]));
body.appendChild(NS.makeEl('div', 'jfvr-hint',
'引导线/光标默认在主用手上;另一只手按下会立刻接管那一次操作。'));
// ADDENDUM 8: the picture-pan mechanism. Only touch this if panning does not
// move the picture live (see stats.videoRotMode).
body.appendChild(segRow('画面旋转', function () { return S.videoRotMode || 'auto'; },
@@ -475,6 +691,7 @@
panel.appendChild(foot);
document.body.appendChild(panel);
positionPanel();
panelSync = function () {
for (var i = 0; i < panelSyncs.length; i++) {
@@ -705,6 +922,7 @@
try {
updatePointer(frame);
pollGamepads(frame);
dropStaleHolds();
updatePanelPose(frame, dt);
updateGrabFrame(frame);
updateViewDrag(frame);
@@ -792,6 +1010,8 @@
S.ctlLock = false;
panelPose = null;
pointer = { visible: false, beam: false, source: 'none', origin: { x: 0, y: 0, z: 0 }, dir: { x: 0, y: 0, z: -1 }, hit: null };
activeSrcKey = null; // ADDENDUM 11: fresh hand choice every session
lastActivateByKey = {};
S.pointer = null;
S.session = null;
S.refSpace = null;
@@ -978,7 +1198,63 @@
// the only mode (an index-finger ray carries fingertip jitter straight into
// the cursor, and nobody wants to point with one finger).
function updatePointer(frame) {
// Identity for an input source that survives the runtime re-listing it.
function srcKey(src) {
if (!src) return null;
return (src.hand ? 'hand' : 'ctrl') + ':' + (src.handedness || '?');
}
function candByKey(cands, key) {
for (var i = 0; i < cands.length; i++) if (cands[i].key === key) return cands[i];
return null;
}
function candByHand(cands, hand) {
for (var i = 0; i < cands.length; i++) if (cands[i].hand === hand) return cands[i];
return null;
}
// ADDENDUM 12 — pure: choose which input source owns the pointer.
// cands [{ key, hand, onPanel, ... }] in runtime order
// preferKey the source that is acting right now (select / gamepad press)
// ownerKey the source that owns the pointer (last accepted press)
// prefHand the dominant hand ('right' | 'left') — the default owner
//
// The acting source OWNS the shot: if it cannot be resolved the pick is null and
// the press MISSES (never another hand's position). Otherwise:
// owner aiming -> preferred hand aiming -> any hand aiming -> owner ->
// preferred hand -> first.
// A mouse-style single cursor: exactly ONE hand ever drives the guide line.
function pickPointerCand(cands, preferKey, ownerKey, prefHand) {
if (preferKey) return candByKey(cands, preferKey);
if (!cands || !cands.length) return null;
var owner = ownerKey ? candByKey(cands, ownerKey) : null;
var pref = prefHand ? candByHand(cands, prefHand) : null;
if (owner && owner.onPanel) return owner;
if (pref && pref.onPanel) return pref;
for (var i = 0; i < cands.length; i++) if (cands[i].onPanel) return cands[i];
if (owner) return owner;
if (pref) return pref;
return cands[0];
}
// When the source that started a hold disappears (hand tracking lost), the hold
// would otherwise stick forever because no release event ever arrives.
function dropStaleHolds() {
var srcs = (S.session && S.session.inputSources) ? S.session.inputSources : [];
var i;
function present(src) {
for (i = 0; i < srcs.length; i++) if (srcs[i] === src) return true;
return false;
}
if (grab && !present(grab.src)) endGrab();
if (viewDrag && !present(viewDrag.src)) endViewDrag();
}
// ADDENDUM 11: which hand owns the pointer.
var activeSrcKey = null;
function updatePointer(frame, preferSrc) {
if (!S.session) return;
var next = {
visible: false, beam: false, source: 'none',
@@ -996,24 +1272,49 @@
// platform; an index-finger ray computed from joint poses carries the
// per-frame fingertip jitter straight into the cursor, so its landing point
// is visibly less steady. Meta's own samples use targetRaySpace too.
//
// ADDENDUM 11: with two hands BOTH report a tracked-pointer ray, and the
// runtime's order is not "the hand the user is using". Taking the first one
// pinned the guide line to one hand AND made the OTHER hand's select land
// wherever the pinned hand pointed. The pointer now follows, in order:
// 1. the source acting right now (select / gamepad press),
// 2. the last acting source, while it is aiming at the panel,
// 3. any source aiming at the panel,
// 4. the last acting source, then the first one.
var cands = [];
for (var i = 0; i < srcs.length; i++) {
var src = srcs[i];
if (src.targetRayMode !== 'tracked-pointer') continue;
var isHand = !!src.hand;
var ray = rayOf(frame, src);
if (!ray) continue;
var hit = panelHit(frame, ray, layer, 0.25, 0.6);
var hit = null;
try { hit = panelHit(frame, ray, layer, 0.25, 0.6); } catch (e) { hit = null; }
cands.push({
src: src, ray: ray, hit: hit, key: srcKey(src), hand: src.handedness,
onPanel: !!(hit && hit.inBounds)
});
}
var pick = pickPointerCand(cands, preferSrc ? srcKey(preferSrc) : null, activeSrcKey, S.handPref);
if (pick) {
activeSrcKey = pick.key;
next = {
visible: true,
beam: true,
source: (isHand ? 'hand' : 'controller') + ':' + src.handedness,
origin: ray.origin,
dir: ray.dir,
hit: hit ? { nx: hit.nx, ny: hit.ny } : null,
distance: hit ? hit.distance : null,
source: (pick.src.hand ? 'hand' : 'controller') + ':' + pick.src.handedness,
origin: pick.ray.origin,
dir: pick.ray.dir,
// ADDENDUM 11b: only a hit that is really ON the panel becomes the
// cursor. panelHit() clamps an off-panel intersection to the border, and
// drawing the cursor at that clamped point while the beam ended at the
// true intersection made the two drift apart - the further off the panel
// the ray pointed, the worse the gap. `distance` is still published so the
// beam still reaches the panel plane.
hit: (pick.hit && pick.hit.inBounds) ? { nx: pick.hit.nx, ny: pick.hit.ny } : null,
distance: pick.hit ? pick.hit.distance : null,
pressed: performance.now() < pressUntil
};
break;
}
pointer = next;
@@ -1022,6 +1323,8 @@
if (NS.Controls && NS.Controls.setPointer) {
try { NS.Controls.setPointer(next); } catch (e) {}
}
S.stats.activeSrc = next.visible ? (activeSrcKey || '(none)') : '(none)';
S.stats.handPref = S.handPref || 'right';
S.stats.pointer = next.source +
(next.hit ? ' HIT ' + next.hit.nx.toFixed(2) + ',' + next.hit.ny.toFixed(2) : ' (no hit)');
S.stats.inputSources = srcs.map(function (s) {
@@ -1273,7 +1576,7 @@
var a = rayAngles(ray);
if (!a) { S.stats.viewDrag = 'no ray'; return; }
viewDrag = {
src: src, t0: performance.now(), armed: false,
src: src, key: srcKey(src), t0: performance.now(), armed: false,
a0: null, yaw0: S.videoYaw, pitch0: S.videoPitch, moved: false
};
S.stats.viewDrag = 'pressed (hold ' + VIEW_HOLD_MS + 'ms to pan)';
@@ -1369,6 +1672,10 @@
* ------------------------------------------------------------------ */
var ACTIVATE_COOLDOWN_MS = 250;
var lastActivate = 0;
// ADDENDUM 11b: the cooldown is per INPUT SOURCE, not global. With hands, a
// stray gamepad edge from one hand used to swallow the other hand's `select`
// within 250 ms, so the click silently used the first hand's position.
var lastActivateByKey = {};
var padPrev = new WeakMap();
/* ---------------- grab & drag the subtitle strip ---------------- *
@@ -1410,6 +1717,7 @@
if (!p0) { S.stats.grab = 'no source point'; return; }
grab = {
src: src,
key: srcKey(src),
p0: p0,
place0: { y: S.subPlacement.y, z: S.subPlacement.z, width: S.subPlacement.width },
moved: false
@@ -1513,15 +1821,40 @@
function pointerDown(src, frame, via) {
if (!S.session) return;
var now = performance.now();
if (now - lastActivate < ACTIVATE_COOLDOWN_MS) return; // dedupe select+gamepad
var actKey = srcKey(src) || (via || '?');
if (now - (lastActivateByKey[actKey] || 0) < ACTIVATE_COOLDOWN_MS) return;
lastActivateByKey[actKey] = now;
lastActivate = now;
S.stats.lastActivate = (via || '?') + (src && src.handedness ? ':' + src.handedness : '');
S.stats.pressSrc = actKey;
// Captured BEFORE show(): when the control bar is already up, a pinch belongs
// to the bar, so it must not also yank the subtitles.
var barWasShown = NS.Controls && NS.Controls.isVisible ? !!NS.Controls.isVisible() : false;
if (frame) { try { updatePointer(frame); } catch (e) {} }
// ADDENDUM 11b: attribute the shot to the acting source. If its ray cannot be
// resolved, MISS - never fall back to whatever hand the per-frame pointer was
// on, which is exactly how a right-hand pinch ended up landing on the left
// hand's position.
frame = frame || S.lastFrame;
if (src) {
var excludeKey = srcKey(src);
if (excludeKey &&
((grab && grab.key && grab.key !== excludeKey) ||
(viewDrag && viewDrag.key && viewDrag.key !== excludeKey))) {
S.stats.pressAt = 'IGNORED (other hand is holding)';
return;
}
if (frame) { try { updatePointer(frame, src); } catch (e) {} }
if (!pointer || !pointer.visible) {
S.stats.pressAt = 'MISS (acting source has no ray)';
S.stats.pressPtr = '(no ray)';
return;
}
S.stats.pressPtr = pointer.source + (pointer.hit ? ' HIT' : ' nohit');
} else if (frame) {
try { updatePointer(frame); } catch (e) {}
}
// 1) grabbing the subtitle strip wins, but only while the bar is down
if (frame && !barWasShown) {
@@ -1579,7 +1912,14 @@
var pressUntil = 0;
function pointerUp() {
// ADDENDUM 12: only the source that STARTED a hold ends it. A release from the
// other hand used to cancel the first hand's drag (subtitle grab / picture pan).
function pointerUp(src) {
var key = srcKey(src);
if (key) {
if (grab && grab.key && grab.key !== key) return;
if (viewDrag && viewDrag.key && viewDrag.key !== key) return;
}
endGrab();
endViewDrag();
}
@@ -1599,7 +1939,7 @@
var prev = padPrev.get(src) || false;
padPrev.set(src, pressed);
if (pressed && !prev) pointerDown(src, frame, 'gamepad');
else if (!pressed && prev) pointerUp();
else if (!pressed && prev) pointerUp(src);
}
}
@@ -1607,8 +1947,8 @@
pointerDown(ev && ev.inputSource, S.lastFrame, 'select');
}
function onSelectEnd() {
pointerUp();
function onSelectEnd(ev) {
pointerUp(ev && ev.inputSource);
}
/* ---------------- live subtitle setters (single source of truth) ---------------- */
// state.subPlacement / subAngleDeg are re-read from the module after every
@@ -1749,9 +2089,13 @@
// `subtitles` and `subMode` could otherwise leave the layer uncreated.
S.subtitles = true;
if (S.subMode === 'off') S.subMode = 'hud';
S.subLayout = 'auto'; // ADDENDUM 10: the override is per-session only
try { if (NS.Subtitles && NS.Subtitles.init) NS.Subtitles.init(); } catch (e) { NS.recordError('Subtitles.init', e); }
try { if (NS.Controls && NS.Controls.init) NS.Controls.init(); } catch (e) { NS.recordError('Controls.init', e); }
try { if (NS.Hands && NS.Hands.init) NS.Hands.init(); } catch (e) { NS.recordError('Hands.init', e); }
// Watches for "the player never produced a picture" and offers the only fix
// that helps (let the server transcode). See 40-watchdog.js.
try { if (NS.Watchdog && NS.Watchdog.init) NS.Watchdog.init(); } catch (e) { NS.recordError('Watchdog.init', e); }
scan();
new MutationObserver(scan).observe(document.documentElement, { childList: true, subtree: true });
@@ -1759,6 +2103,9 @@
window.addEventListener('beforeunload', function () {
if (S.session) { try { S.session.end(); } catch (e) {} }
});
// Keep the draggable button (and the panel that follows it) on screen when
// the window changes size.
window.addEventListener('resize', onViewportResize);
installFrameTracker();
window.__JFVR_STATE__ = S;