Skip to content

Record your screen, ship a demo. Free and open-source, GPU-accelerated, no watermarks, no subscriptions. Windows, macOS, Linux. Actively maintained.

17.9 KB
Raw Blame
// Provisions the ONNX Runtime shared library into
// electron/native/bin/<platform>-<arch>/, next to the compositor addon and the
// ffmpeg libraries. That directory is gitignored and shipped by electron-builder's
// extraResources, so this runs at build time rather than committing a 15-38 MB binary.
//
// WHY IT SHIPS: the native compositor segments the webcam subject on the CPU
// execution provider (crates/compositor/src/segmentation.rs), and `ort` is linked
// with `load-dynamic` — nothing is needed to BUILD, but at runtime
// `ensureOnnxRuntimeOnPath` (electron/native-bridge/services/compositorViewService.ts)
// walks this exact directory looking for the library and sets ORT_DYLIB_PATH to it.
// Without it `Segmenter::load` fails, the compositor logs one line and draws the
// webcam unsegmented — so the AI background cutout/blur/custom modes are simply off.
// Everything degrades; nothing breaks. That is why this script never fails a build.
//
// VERSION IS NOT FREE TO MOVE. crates/Cargo.toml pins `ort` with feature `api-NN`,
// which is the MINIMUM ONNX Runtime minor version the crate will accept — a lower
// one makes `GetApi` return null and `ort` panics rather than erroring. The pin here
// must satisfy that, and scripts/fetch-onnxruntime.test.mjs cross-checks the two so
// a bump on either side cannot land alone.
//
// SUPPLY CHAIN. This binary is signed and shipped to every user, so nothing floats:
//   - Pinned to an immutable release tag, never `latest`.
//   - SHA-256 verified before the archive is opened. The digests below are the ones
//     GitHub publishes per asset (`digest` in the releases API), independently
//     re-verified by downloading and hashing.
//   - Only the plain CPU assets. The `gpu_cuda*` variants are 200-320 MB and pull
//     NVIDIA runtime dependencies we neither need nor may redistribute; the measured
//     decision to use the CPU EP is in
//     technical-documentation/engineering/webcam-segmentation.md.
//
// LICENSING: ONNX Runtime is MIT, which is compatible with this MIT app — but the
// archive is checked rather than trusted, the same way fetch-ffmpeg.mjs verifies
// ffmpeg's LGPL-ness instead of believing the asset name. Attribution ships in
// THIRD-PARTY-NOTICES.md.

import { spawnSync } from "node:child_process";
import crypto from "node:crypto";
import fs from "node:fs";
import os from "node:os";
import path from "node:path";
import { fileURLToPath, pathToFileURL } from "node:url";

const __dirname = path.dirname(fileURLToPath(import.meta.url));
const ROOT = path.join(__dirname, "..");

/**
 * The pinned release. Asset names are DERIVED from it rather than written out per
 * entry, which is deliberate: fetch-ffmpeg.mjs keeps full asset strings and grew a
 * test because a re-pin moved some and not others. Templating removes that failure
 * mode by construction. The digests still have to move by hand — but a stale one
 * fails loudly on the SHA-256 check before anything is extracted, which is the safe
 * direction to fail in.
 */
const VERSION = "1.27.1";

/**
 * The upstream commit `v${VERSION}` pointed at when it was reviewed.
 *
 * `v1.27.1` is a LIGHTWEIGHT tag — it points straight at a commit and can be moved by
 * anyone with push rights upstream. Nothing here fetches source at install time, so this
 * does not affect `npm run fetch:onnxruntime`; it matters to
 * `.github/workflows/build-onnxruntime-macos.yml`, which builds the library and would
 * otherwise attest an artifact to "whatever that tag meant that morning". The workflow
 * resolves the tag and refuses to build if it no longer resolves here.
 */
const SOURCE_COMMIT = "df2ba1cf8108aa63627cf4cdf8f807880b938616";
const BASE = `https://github.com/microsoft/onnxruntime/releases/download/v${VERSION}`;

/**
 * Where a target's archive is fetched from. Upstream unless the entry overrides it.
 *
 * The override exists for one reason, and it is not preference: **no published ONNX
 * Runtime has ever satisfied this app's macOS floor.** Every release from 1.24 on is
 * built for macOS 14, and every release before it for at least 13.3, while
 * `electron-builder.json5` declares 13.0 and `before-pack.cjs` refuses anything above
 * the floor — correctly, since the deployment target decides which symbols the linker
 * resolves against the OS instead of emitting locally (#515). So `npm run build:mac`
 * cannot package a macOS bundle at all with the upstream artifact.
 *
 * `.github/workflows/build-onnxruntime-macos.yml` builds one with the floor pinned and
 * prints the `PINNED` entry to paste here. Everything else about this file is
 * unchanged: an immutable URL, and a SHA-256 verified before the archive is opened.
 * What moves is who built the bytes, not how much they are trusted.
 */
const baseUrlFor = (spec) => spec.baseUrl ?? BASE;

/**
 * Per-target: the upstream artifact slug, its digest, and the library to lift out.
 *
 * `out` is not cosmetic — it is the exact name `ortLibName()` looks for in
 * compositorViewService.ts. `member` is the file inside the archive, which on macOS
 * and Linux is the VERSIONED real file rather than the unversioned symlink beside
 * it: tar restores that symlink as a symlink, and a dangling one in the packaged app
 * would resolve to nothing.
 *
 * darwin-x64 is absent and cannot be added: Microsoft publishes no `osx-x86_64`
 * (or universal) asset for any release from 1.27 on — arm64 is the only macOS
 * target. Building it from source is the only way to change that, and it is not
 * worth an ffmpeg-macos-sized build script for a shrinking platform when the
 * fallback is "the effect is off". See the darwin-x64 branch in main().
 */
const PINNED = {
	"win32-x64": {
		slug: "win-x64",
		ext: "zip",
		sha256: "2e00414a63fdef0914cd5a5ede6c707844878e0c08e1b6693842f0451b2df2a1",
		member: "onnxruntime.dll",
		out: "onnxruntime.dll",
	},
	"win32-arm64": {
		slug: "win-arm64",
		ext: "zip",
		sha256: "6e22c2061ba6400b42a59663d700c8694e4e8fe654cf452c4700c24237407ae1",
		member: "onnxruntime.dll",
		out: "onnxruntime.dll",
	},
	// The one target that does NOT come from upstream, and it is not a preference.
	// Microsoft's `onnxruntime-osx-arm64-1.27.1.tgz` is built for macOS 14, this app
	// declares a 13.0 floor, and `before-pack.cjs` refuses a payload demanding more —
	// correctly, since the deployment target decides which symbols the linker resolves
	// against the OS rather than emitting locally (#515). So `npm run build:mac` could
	// not package at all. No published release fixes that: every one from 1.24 on is
	// `minos 14.0`, and every one before it is at least 13.3.
	//
	// This one is built by `.github/workflows/build-onnxruntime-macos.yml` from the
	// commit above, with the deployment target pinned, and published under a
	// `v0.0.0-*` tag — the marker this repo already uses for a binary that needs a
	// permanent URL but is not a product version. Its provenance is attested:
	//
	//     gh attestation verify onnxruntime-osx-arm64-1.27.1.tgz --repo getopenscreen/openscreen
	//
	// Everything else about it is unchanged: immutable URL, SHA-256 verified before
	// the archive is opened. What moved is who built the bytes, not how far they are
	// trusted.
	"darwin-arm64": {
		slug: "osx-arm64",
		ext: "tgz",
		sha256: "b8b7e62786eea42fc867bdbc2d3f573655a4b0e602c6938c4cea151a9ef71623",
		member: `libonnxruntime.${VERSION}.dylib`,
		out: "libonnxruntime.dylib",
		baseUrl:
			"https://github.com/getopenscreen/openscreen/releases/download/v0.0.0-onnxruntime-1.27.1",
	},
	// Linux is wired into `build:linux` since its back-end gained the capture half
	// (`capture_webcam_rgb` + `set_webcam_mask` in `compositor_linux.rs`). Until
	// then this entry existed but was deliberately unused: the back-end carried the
	// segmentation SHADER only, so `fx.z` never left 0 and the library would have
	// been 23 MB of installer for a code path that could not run.
	// See technical-documentation/engineering/webcam-segmentation-backend-port.md.
	"linux-x64": {
		slug: "linux-x64",
		ext: "tgz",
		sha256: "25b1ef1fea1acd210d63f8f24dc870ad6e077795ce1f54876252c6d3803c15af",
		member: `libonnxruntime.so.${VERSION}`,
		out: "libonnxruntime.so",
	},
	"linux-arm64": {
		slug: "linux-aarch64",
		ext: "tgz",
		sha256: "33c67e33d1e25b816878366ea276589a024f71f000e7ff955c4b33224d639edd",
		member: `libonnxruntime.so.${VERSION}`,
		out: "libonnxruntime.so",
	},
};

const assetName = (spec) => `onnxruntime-${spec.slug}-${VERSION}.${spec.ext}`;

/** Magic bytes the vendored library must start with, per target platform. */
const MAGIC = {
	win32: { bytes: [0x4d, 0x5a], name: "PE (MZ)" }, //             .dll
	darwin: { bytes: [0xcf, 0xfa, 0xed, 0xfe], name: "Mach-O 64" }, // .dylib
	linux: { bytes: [0x7f, 0x45, 0x4c, 0x46], name: "ELF" }, //        .so
};

function run(cmd, args, opts = {}) {
	return spawnSync(cmd, args, { stdio: "inherit", ...opts });
}

function tarBin() {
	if (process.platform !== "win32") return "tar";
	const sys32 = path.join(process.env.SystemRoot ?? "C:\\Windows", "System32", "tar.exe");
	return fs.existsSync(sys32) ? sys32 : "tar";
}

function extract(archive, destDir) {
	fs.mkdirSync(destDir, { recursive: true });
	// Run from destDir with a bare filename: given an absolute Windows path, tar
	// reads "C:\..." as host:path and tries to resolve a host called C.
	const r = run(tarBin(), [archive.endsWith(".zip") ? "-xf" : "-xzf", path.basename(archive)], {
		cwd: destDir,
	});
	if (r.status !== 0) throw new Error(`tar failed to extract ${path.basename(archive)}`);
}

/** Depth-first search for a file by exact basename. */
function find(dir, name) {
	for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
		const p = path.join(dir, entry.name);
		if (entry.isDirectory()) {
			const hit = find(p, name);
			if (hit) return hit;
		} else if (entry.name === name) {
			return p;
		}
	}
	return null;
}

/**
 * Refuses anything that is not the MIT ONNX Runtime we pinned.
 *
 * Three independent checks, because the digest alone only proves we got the archive
 * we asked for — it says nothing about having lifted the RIGHT FILE out of it, which
 * is where a re-pin actually goes wrong (a renamed member silently vendors a 20 KB
 * provider stub, and the failure surfaces as "the effect does nothing" months later).
 *
 *   1. the archive's LICENSE really is MIT — asset names are not evidence;
 *   2. the library is a binary of the expected format for the target platform;
 *   3. it carries the pinned version string, which is what `GetVersionString()`
 *      returns and what `ort` compares against its `api-NN` floor.
 */
function verify(libPath, licensePath, targetPlatform) {
	const license = fs.readFileSync(licensePath, "utf8");
	if (!/^MIT License/m.test(license)) {
		throw new Error(
			`${path.basename(licensePath)} does not begin with "MIT License".\n` +
				"Refusing to vendor: ONNX Runtime is MIT and this app is MIT — a relicensed\n" +
				"upstream is a decision for a human, not a build script.",
		);
	}

	const buf = fs.readFileSync(libPath);
	const magic = MAGIC[targetPlatform];
	if (!magic.bytes.every((b, i) => buf[i] === b)) {
		const got = [...buf.subarray(0, 4)].map((b) => b.toString(16).padStart(2, "0")).join(" ");
		throw new Error(
			`${path.basename(libPath)} is not a ${magic.name} binary (starts with ${got}).\n` +
				"The archive layout probably changed under the pin — check `member`.",
		);
	}

	// The version lives in the binary as a plain NUL-terminated string.
	if (!buf.includes(Buffer.from(`\0${VERSION}\0`, "latin1"))) {
		throw new Error(
			`${path.basename(libPath)} does not carry the version string ${VERSION}.\n` +
				"Either the pin and the digest disagree, or the wrong member was extracted.",
		);
	}

	return `MIT ONNX Runtime ${VERSION}, ${magic.name}, ${(buf.length / 1048576).toFixed(1)} MB`;
}

async function download(spec) {
	const asset = assetName(spec);
	const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "openscreen-ort-"));
	console.log(`Downloading ${asset}\n  from v${VERSION}`);
	const res = await fetch(`${baseUrlFor(spec)}/${asset}`);
	if (!res.ok) throw new Error(`Download failed: ${res.status} ${res.statusText}`);
	const bytes = Buffer.from(await res.arrayBuffer());

	// Before opening it: is this the exact artifact we pinned?
	const got = crypto.createHash("sha256").update(bytes).digest("hex");
	if (got !== spec.sha256) {
		fs.rmSync(tmp, { recursive: true, force: true });
		throw new Error(
			`SHA-256 mismatch for ${asset}\n  expected ${spec.sha256}\n  got      ${got}\n` +
				"Refusing to extract. Either the pin is stale or the artifact changed under it.",
		);
	}
	console.log(`  sha256 ok (${(bytes.length / 1048576).toFixed(0)} MB)`);

	const archive = path.join(tmp, asset);
	fs.writeFileSync(archive, bytes);
	extract(archive, tmp);
	return tmp;
}

/**
 * Where the fast path learns WHICH archive a staged library came from.
 *
 * The version string cannot tell two builds of one release apart, and on darwin-arm64
 * that is the whole difference: Microsoft's osx-arm64 1.27.1 and the floor-pinned one
 * built here both carry `\01.27.1\0`, but only the second passes before-pack.cjs's
 * macOS floor. A checkout that staged the upstream library kept hearing "Already
 * present" and then failed to package. `spec.sha256` is the ARCHIVE's digest, so the
 * staged file cannot be compared to it directly — this record ties the two together.
 *
 * Beside the per-target directories rather than inside them: every `extraResources`
 * filter in electron-builder.json5 ships the contents of `<platform>-<arch>/` only.
 */
export const stampPathFor = (tag) =>
	path.join(ROOT, "electron", "native", "bin", `.onnxruntime-${tag}.json`);

const sha256Of = (file) => crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex");

/** Records that `dest` was vendored from the archive `spec` pins. */
export function writeStamp(dest, stamp, spec) {
	const record = { archive: spec.sha256, library: sha256Of(dest) };
	fs.writeFileSync(stamp, `${JSON.stringify(record, null, "\t")}\n`);
}

/** Why the library at `dest` is not the one `spec` pins, or null when it is. */
export function stagedMismatch(dest, stamp, spec) {
	let record;
	try {
		record = JSON.parse(fs.readFileSync(stamp, "utf8"));
	} catch {
		return "no record of the archive it came from";
	}
	if (record?.archive !== spec.sha256) return "vendored from a different archive";
	if (record.library !== sha256Of(dest)) return "replaced since it was vendored";
	return null;
}

async function main() {
	// `--target` exists for CI, which provisions for the runner it is on; without it
	// the host is the target, which is what every local build wants.
	const targetArg = process.argv.find((a) => a.startsWith("--target="));
	const tag = targetArg
		? targetArg.slice("--target=".length)
		: `${process.platform}-${process.arch}`;
	const [targetPlatform] = tag.split("-");

	// Not an error, and deliberately exit 0: `build:mac` runs on an Intel runner for
	// the x64 DMG, and there is no upstream library to give it. Failing here would
	// break a release build over a feature that is designed to be absent gracefully.
	if (tag === "darwin-x64") {
		console.log(
			"ONNX Runtime is not provisioned for darwin-x64: Microsoft publishes no\n" +
				"osx-x86_64 (or universal) asset for 1.27 or later — arm64 is the only macOS\n" +
				"target. The webcam background effects are therefore OFF on Intel Macs; the\n" +
				"compositor logs one line and draws the camera unsegmented. Nothing else changes.",
		);
		return;
	}

	const spec = PINNED[tag];
	if (!spec) {
		console.log(
			`No pinned ONNX Runtime for ${tag} — skipping. Have: ${Object.keys(PINNED).join(", ")}`,
		);
		return;
	}
	if (!MAGIC[targetPlatform]) {
		throw new Error(`Unknown target platform in --target=${tag}`);
	}

	const binDir = path.join(ROOT, "electron", "native", "bin", tag);
	const dest = path.join(binDir, spec.out);

	const stamp = stampPathFor(tag);

	if (fs.existsSync(dest) && !process.argv.includes("--force")) {
		// Re-verify rather than trusting the filename: this directory is gitignored
		// scratch space that a half-finished run, a hand copy or an older pin can leave
		// anything in — including the right version from the wrong archive.
		const why = stagedMismatch(dest, stamp, spec);
		if (!why) {
			console.log(`Already present: ${dest}`);
			console.log(
				`  ONNX Runtime ${VERSION} from ${assetName(spec)}, ${(fs.statSync(dest).size / 1048576).toFixed(1)} MB`,
			);
			console.log("Use --force to re-download.");
			return;
		}
		console.log(
			`Present but not the pinned ONNX Runtime ${VERSION} (${why}) — re-fetching: ${dest}`,
		);
	}

	const tmp = await download(spec);
	try {
		const lib = find(tmp, spec.member);
		if (!lib) throw new Error(`${spec.member} not found inside ${assetName(spec)}`);
		const license = find(tmp, "LICENSE");
		if (!license) throw new Error(`LICENSE not found inside ${assetName(spec)}`);

		// Verify BEFORE vendoring: nothing unchecked reaches electron/native/bin,
		// where the packager would happily ship it.
		console.log("Verifying...");
		const banner = verify(lib, license, targetPlatform);

		fs.mkdirSync(binDir, { recursive: true });
		fs.copyFileSync(lib, dest);
		if (targetPlatform !== "win32") fs.chmodSync(dest, 0o755);
		writeStamp(dest, stamp, spec);

		console.log(`  ${banner}`);
		// Où que viennent les octets, dire de quelle source ils sortent. Pour un artefact
		// amont c'est le tag ; pour un que nous avons construit (`baseUrl`), c'est le commit
		// que le workflow a compilé, et c'est la seule chose qui rend le binaire traçable
		// une fois qu'il ne porte plus le nom de Microsoft.
		if (spec.baseUrl) {
			console.log(`  built here from microsoft/onnxruntime@${SOURCE_COMMIT}`);
		}
		console.log(`\nVendored -> ${dest}`);
	} finally {
		fs.rmSync(tmp, { recursive: true, force: true });
	}
}

// Only when run as a CLI — importing this from a test must not start downloading.
// realpath because Node resolves the entry point through symlinks before naming it.
if (process.argv[1] && import.meta.url === pathToFileURL(fs.realpathSync(process.argv[1])).href) {
	main().catch((err) => {
		console.error(`\n${err.message}`);
		process.exit(1);
	});
}