Files
jellyfin_vr_web_plugin/pack.py
T
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

413 lines
15 KiB
Python

#!/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
# ---------------------------------------------------------------- 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):
os.makedirs(OUT_DIR, exist_ok=True)
asset = "%s_%s.zip" % (ASSEMBLY, target_abi)
path = os.path.join(OUT_DIR, asset)
with zipfile.ZipFile(path, "w", zipfile.ZIP_DEFLATED) as zf:
zf.write(dll, ASSEMBLY + ".dll")
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?")
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()