Jellyfin Web VR plugin for Quest 3 (VR180 stereo playback)

Injects a 「VR 播放」 button into Jellyfin Web's video player page and plays
VR180 / VR360 stereo content on Meta Quest 3 directly in the browser, with
DirectPlay 8K HEVC, in-VR subtitles and an in-VR control panel.

Modules (src/, concatenated in filename order into dist/jfvr.js):
  00-core.js       namespace, shared state, GL helpers, layer/frame-hook registry
  10-subtitles.js  libass canvas -> head-locked quad layer, auto-cropped to ink,
                   with depth/size decoupling (angular-size lock)
  20-controls.js   in-VR control panel: progress/seek, transport, subtitle rows,
                   aiming beam, padlock, pure 2D canvas -> XR quad layer
  30-hands.js      system hand model (Three.js + generic-hand GLB) via a manually
                   driven projection layer
  90-main.js       boot, XR session lifecycle, rAF broker (rAF stops during XR),
                   input dispatch, settings panel, localStorage persistence

Key on-device findings are documented in HANDOFF.md §6 and README.md addenda:
requestAnimationFrame stops during an XR session, 3:2 pulldown at 90 Hz needs
updateTargetFrameRate(120), libass must be resized before entering VR, a quad's
local -Z is its plane normal, and hand aiming must use the gaze ray because the
emulated targetRaySpace points sideways. Quest does not expose eye tracking.

Docs: INTERFACES.md (module contract + addenda), README.md (measurements),
HANDOFF.md (handover notes). Credentials are NOT in the repo: deploy.py reads
the SSH password from the JF_PW environment variable.
This commit is contained in:
2026-10-11 19:19:06 +08:00
commit 838675baa6
14 changed files with 13981 additions and 0 deletions
+149
View File
@@ -0,0 +1,149 @@
#!/usr/bin/env python3
"""
Deploy jfvr-mvp.js into the Jellyfin container and inject the script tag
into jellyfin-web/index.html.
Usage:
JF_PW='<ssh-password>' python3 deploy.py # deploy current jfvr-mvp.js
JF_PW='<ssh-password>' python3 deploy.py rollback # restore original index.html
Env:
JF_HOST (default 192.168.123.199)
JF_USER (default admin)
JF_PW (required) SSH password
JF_CONTAINER (default Jellyfin)
"""
import base64
import hashlib
import os
import subprocess
import sys
import paramiko
HOST = os.environ.get("JF_HOST", "192.168.123.199")
USER = os.environ.get("JF_USER", "admin")
PW = os.environ.get("JF_PW")
CONTAINER = os.environ.get("JF_CONTAINER", "Jellyfin")
HERE = os.path.dirname(os.path.abspath(__file__))
BUILT_JS = os.path.join(HERE, "dist", "jfvr.js")
LEGACY_JS = os.path.join(HERE, "legacy", "jfvr-mvp-v6-working.js")
REMOTE_JS = "/tmp/jfvr-mvp.js"
WEB_DIR = "/jellyfin/jellyfin-web"
BACKUP_DIR = "/vol2/jellyfin/config/_vr_backup"
TAG = '<script plugin="JellyfinVR" version="%s" src="jfvr-mvp.js?v=%s" defer></script>'
def build():
"""Concatenate src/*.js into dist/jfvr.js. Aborts on failure."""
r = subprocess.run(
[sys.executable, os.path.join(HERE, "build.py")],
capture_output=True, text=True, cwd=HERE,
)
print(r.stdout.strip() or r.stderr.strip())
if r.returncode != 0:
sys.exit("build failed")
r = subprocess.run(
[sys.executable, os.path.join(HERE, "build.py"), "--check"],
capture_output=True, text=True, cwd=HERE,
)
if r.returncode != 0:
print(r.stdout)
sys.exit("syntax check failed")
def run(client, script, timeout=180):
"""Run a bash script as root on the remote host."""
b64 = base64.b64encode(script.encode()).decode()
wrapped = (
"echo '%s' | sudo -S -p '' bash -c "
"'echo %s | base64 -d > /tmp/_jfvr.sh; bash /tmp/_jfvr.sh'" % (PW, b64)
)
_, out, err = client.exec_command(wrapped, timeout=timeout)
text = out.read().decode("utf-8", "replace")
errs = err.read().decode("utf-8", "replace")
errs = "\n".join(
line for line in errs.splitlines()
if "password for" not in line and not line.startswith("[sudo]")
)
return text, errs
def main():
if not PW:
sys.exit("JF_PW env var is required")
rollback = len(sys.argv) > 1 and sys.argv[1] == "rollback"
legacy = "--legacy" in sys.argv
if not rollback:
if legacy:
BUILT_JS_LOCAL = LEGACY_JS
print("deploying LEGACY bundle")
else:
build()
BUILT_JS_LOCAL = BUILT_JS
else:
BUILT_JS_LOCAL = None
client = paramiko.SSHClient()
client.set_missing_host_key_policy(paramiko.AutoAddPolicy())
client.connect(
HOST, username=USER, password=PW, timeout=15,
look_for_keys=False, allow_agent=False,
)
try:
if rollback:
script = f"""
set -e
if [ ! -f "{BACKUP_DIR}/index.html.orig" ]; then
echo "no backup found at {BACKUP_DIR}/index.html.orig"; exit 1
fi
docker cp "{BACKUP_DIR}/index.html.orig" {CONTAINER}:{WEB_DIR}/index.html
docker exec {CONTAINER} rm -f {WEB_DIR}/jfvr-mvp.js
echo "rolled back. tail:"
docker exec {CONTAINER} tail -c 200 {WEB_DIR}/index.html
"""
out, err = run(client, script)
print(out)
if err.strip():
print("--- STDERR ---\n" + err)
return
data = open(BUILT_JS_LOCAL, "rb").read()
md5 = hashlib.md5(data).hexdigest()
version = "mvp-%s" % md5[:6]
tag = TAG % (version, md5[:6])
sftp = client.open_sftp()
with sftp.open(REMOTE_JS, "wb") as fh:
fh.write(data)
sftp.close()
print("uploaded %d bytes, md5=%s, tag=%s" % (len(data), md5, version))
script = f"""
set -e
mkdir -p "{BACKUP_DIR}"
[ -f "{BACKUP_DIR}/index.html.orig" ] || docker cp {CONTAINER}:{WEB_DIR}/index.html "{BACKUP_DIR}/index.html.orig"
docker cp {REMOTE_JS} {CONTAINER}:{WEB_DIR}/jfvr-mvp.js
docker exec {CONTAINER} sed -i -E 's|<script plugin="JellyfinVR"[^>]*></script>||g' {WEB_DIR}/index.html
docker exec {CONTAINER} sed -i 's|</body>|{tag}</body>|' {WEB_DIR}/index.html
echo "--- tail of index.html ---"
docker exec {CONTAINER} tail -c 300 {WEB_DIR}/index.html
echo
echo "--- md5 inside container ---"
docker exec {CONTAINER} md5sum {WEB_DIR}/jfvr-mvp.js
"""
out, err = run(client, script)
print(out)
if err.strip():
print("--- STDERR ---\n" + err)
finally:
client.close()
if __name__ == "__main__":
main()