@camstack/types 1.2.227 → 1.2.229

package/dist/node.mjs

@@ -50,6 +50,23 @@ function findInPath(name) {
 	}
 }
 /**
+* Refuse an artifact that is not the one we pinned, and leave nothing behind.
+*
+* The failure is deliberately loud and terminal rather than a warning: a
+* mismatch means the bytes are not what was verified, and "not what was
+* verified" is the only state in which running this binary is worse than not
+* having it. The partial file is removed so a retry cannot pick it up.
+*/
+function verifyChecksum(file, expected, name, url) {
+	if (expected === void 0) return;
+	const actual = createHash("sha256").update(readFileSync(file)).digest("hex");
+	if (actual === expected) return;
+	try {
+		unlinkSync(file);
+	} catch {}
+	throw new Error(`${name}: downloaded artifact does not match its pinned checksum — refusing it. url=${url} expected=${expected} actual=${actual}`);
+}
+/**
 * Download a binary to the target directory.
 * Handles archives (zip, tar.gz, tar.xz) and raw binaries.
 */
@@ -74,6 +91,7 @@ async function downloadBinary(opts) {
 		const ext = archiveFormat ?? "tar.gz";
 		const tmpArchive = join(targetDir, `${name}-download.${ext}`);
 		await pipeline(Readable.fromWeb(response.body), createWriteStream(tmpArchive));
+		verifyChecksum(tmpArchive, opts.sha256, name, url);
 		const tmpExtractDir = join(targetDir, `${name}-extract`);
 		mkdirSync(tmpExtractDir, { recursive: true });
 		if (ext === "zip") try {
@@ -120,7 +138,10 @@ async function downloadBinary(opts) {
 			recursive: true,
 			force: true
 		});
-	} else await pipeline(Readable.fromWeb(response.body), createWriteStream(targetPath));
+	} else {
+		await pipeline(Readable.fromWeb(response.body), createWriteStream(targetPath));
+		verifyChecksum(targetPath, opts.sha256, name, url);
+	}
 	chmodSync(targetPath, 493);
 	logger.info("Binary downloaded", { meta: {
 		name,
@@ -271,64 +292,177 @@ async function probeFfmpegBinary(path) {
 	return parseFfmpegCapabilities(path, versionOut, hwaccelOut, encoderOut);
 }
 //#endregion
+//#region src/deps/ffmpeg-artifacts.ts
+/**
+* The ffmpeg build every CamStack node downloads, per platform and arch.
+*
+* ## Why a download, on every node, including the container
+*
+* The version of ffmpeg used to be CODE: baked into the image, changeable only
+* by rebuilding and rolling it. Now it is DATA — this file states the release,
+* and a node that boots with a different one downloads it. Changing ffmpeg is a
+* framework bump, not an image rebuild.
+*
+* It also settles the licence question by removing it. FFmpeg's licence is
+* chosen at compile time: the core is LGPL 2.1+, `--enable-gpl` makes it GPL
+* (for x264/x265), `--enable-version3` makes that v3, and `--enable-nonfree`
+* makes the result undistributable. These are GPL v3 builds, and we do not
+* distribute them: the user's own node fetches the archive from the project
+* that publishes it, so we convey no GPL work and inherit none of the
+* obligations that come with conveying one. That is the whole reason the image
+* no longer installs ffmpeg at all — not a technical preference.
+*
+* ## Why jellyfin-ffmpeg
+*
+* One vendor covering linux-amd64, linux-arm64, darwin-arm64 and darwin-x64
+* from one release, with the widest hardware surface of anything maintained:
+* VAAPI, QSV, NVENC/NVDEC, AMF, Vulkan, OpenCL and DRM on amd64, plus Rockchip
+* MPP on arm64. It reaches the vendor libraries through dlopen trampolines,
+* so the binary is not linked against a driver stack it may not find.
+*
+* **What it still needs from the host, measured 2026-09-19.** On the Unraid
+* HOST, which has no libva, `-vaapi_device` aborts the process outright —
+* `implib-gen: libva-drm.so.2: failed to load library ... Assertion '0 &&
+* "Assertion in generated code"' failed`. Inside our container, which installs
+* libva plus the iHD driver, the same command encodes: verified end to end with
+* `testsrc → format=nv12,hwupload → h264_vaapi`. So the image drops ffmpeg and
+* KEEPS the Intel media stack; the drivers are the part a binary cannot bring.
+*
+* ## Why each artifact carries a checksum and a claim
+*
+* The download is now the only source, so `sha256` is verified before anything
+* is extracted — jellyfin publishes no checksums on its release assets, so
+* these are ours, taken at the version bump. And `expectedHwaccels` is what the
+* build is supposed to be able to do: a binary that probes short of its own
+* claim is a source that changed under us, which is precisely what went
+* unnoticed for months when a static build turned out to carry no VAAPI at all
+* (D536).
+*/
+/** The pinned jellyfin-ffmpeg release. Changing this is the version change. */
+var FFMPEG_RELEASE = "8.1.2-5";
+var BASE = `https://github.com/jellyfin/jellyfin-ffmpeg/releases/download/v${FFMPEG_RELEASE}`;
+function portable(target) {
+	return `${BASE}/jellyfin-ffmpeg_${FFMPEG_RELEASE}_portable_${target}-gpl.tar.xz`;
+}
+/**
+* Every artifact below was fetched and hashed on 2026-09-19, and each one's
+* capability claim was verified by RUNNING it: the linux64 build on the hub
+* itself, the two macOS builds on an M-series Mac (the x86_64 one under
+* Rosetta, which translates x86 to arm — never the reverse, which is why the
+* darwin split matters at all).
+*
+* linux-arm64 is hashed but NOT executed — there is no arm64 Linux node in
+* this cluster yet. Its claim is taken from the project's build script, so the
+* first ARM node to boot will either confirm it or trip the assertion, which is
+* the outcome the assertion exists for.
+*/
+var FFMPEG_ARTIFACTS = {
+	"linux-x64": {
+		url: portable("linux64"),
+		archiveFormat: "tar.xz",
+		sha256: "1fd859927053c44a4f2dbf67ae8b9ba8d29fb3b8930df0dd57d91aa60589363d",
+		sizeBytes: 60255400,
+		expectedHwaccels: [
+			"vaapi",
+			"qsv",
+			"drm",
+			"vulkan",
+			"opencl"
+		]
+	},
+	"linux-arm64": {
+		url: portable("linuxarm64"),
+		archiveFormat: "tar.xz",
+		sha256: "1bd4fafaf4c309cad896d3479152c31d6b7604d4be8b8526882ea16cc6d5f589",
+		sizeBytes: 53958064,
+		expectedHwaccels: ["vaapi", "drm"]
+	},
+	"darwin-arm64": {
+		url: portable("macarm64"),
+		archiveFormat: "tar.xz",
+		sha256: "b2ac80bb184e9a2f3f7c236876b2f56a5639596a95b42f41ced34fab66ad720d",
+		sizeBytes: 32896684,
+		expectedHwaccels: ["videotoolbox"]
+	},
+	"darwin-x64": {
+		url: portable("mac64"),
+		archiveFormat: "tar.xz",
+		sha256: "021cd321ea169722cd2e4aca35884305449666a0d231d3378af7f87d6a5626e5",
+		sizeBytes: 37852180,
+		expectedHwaccels: ["videotoolbox"]
+	}
+};
+/** The artifact for this node, or a refusal naming what was asked for. */
+function getFfmpegArtifact(platform, arch) {
+	const artifact = FFMPEG_ARTIFACTS[`${platform}-${arch}`];
+	if (!artifact) throw new Error(`Unsupported platform/architecture for ffmpeg: ${platform}-${arch}. Point CAMSTACK_FFMPEG_PATH at a binary this node can run.`);
+	return artifact;
+}
+/** The URL alone, for a caller that wants nothing else. */
+function getFfmpegDownloadUrl(platform, arch) {
+	return getFfmpegArtifact(platform, arch).url;
+}
+//#endregion
 //#region src/deps/ffmpeg-binary-source.ts
 /**
-* WHICH ffmpeg a node runs, and why it is never the host's.
+* WHICH ffmpeg a node runs — one rule, on every node.
 *
-* CamStack spawns ffmpeg for the broker's egress and derived transcodes, the
-* WebRTC transcode leg, the recorder, snapshots and the camera grid. What that
-* binary is compiled with decides whether any of them can use the machine's
-* hardware, so it is not a detail to leave to whatever the host happens to have
-* on its PATH:
+* ## The rule
 *
-* - a host binary is an unknown version with unknown vendor libraries, and it
-*   changes under us on any host update;
-* - a self-hosted NVR cannot assume the host has ffmpeg at all.
+* 1. `CAMSTACK_FFMPEG_PATH`, when the operator set it and it exists. Pointing
+*    at your own build is a deliberate act and it wins over everything.
+* 2. The pinned build this node has already downloaded, named by release
+*    (`ffmpeg-<release>`), in `<dataDir>/deps`.
+* 3. Nothing — the caller downloads it. See `ffmpeg-artifacts.ts`.
 *
-* So the binary is always OURS. Two ways it can be ours, and which one applies
-* is a property of where the node runs — not of an environment variable:
+* The system PATH is not on that list and must never be. A host binary is an
+* unknown version with unknown vendor libraries, and it changes under us on any
+* host update; a self-hosted NVR cannot assume the host has ffmpeg at all
+* (D536).
 *
-* | Node | Binary |
-* | --- | --- |
-* | our container image | {@link BUNDLED_FFMPEG_PATH}, installed by the image |
-* | anything else (a native macOS agent) | the static build we download into `<dataDir>/deps` |
+* ## Why the container image is not special any more
 *
-* `BUNDLED_FFMPEG_PATH` is a CamStack-owned path that only our image creates
-* (a link to the ffmpeg the image installs). That is what makes "is this ours?"
-* answerable: `/usr/bin/ffmpeg` is ours INSIDE the image and the host's outside
-* it, and nothing in the process can tell those apart. A path only we ever
-* write can.
+* It was, for one day: the image installed ffmpeg, CamStack preferred it, and
+* that made the answer depend on where a node ran — an image node got VAAPI, a
+* native one got a portable build with none. Now every node downloads the same
+* pinned build, so:
 *
-* The image build is the reason to prefer it over the download: the image
-* installs Ubuntu's ffmpeg next to the Intel media driver, so it carries VAAPI
-* and QSV. The portable static builds carry neither — measured on the hub,
-* 2026-09-18:
+*  - the ffmpeg version is DATA, not code: changing it is a framework bump, not
+*    an image rebuild and a container swap on every machine;
+*  - we ship no ffmpeg binary, so we convey no GPL work — the node fetches it
+*    from the project that publishes it;
+*  - one binary, one set of capabilities, everywhere. A bug that depends on
+*    which ffmpeg answered stops being possible.
 *
-* ```
-* /data/deps/ffmpeg   7.0.2 johnvansickle static   hwaccels: vdpau
-* /usr/bin/ffmpeg     6.1.1 Ubuntu, in the image   hwaccels: vdpau cuda vaapi qsv drm opencl vulkan
-* ```
+* What the image still owes is the DRIVERS, which no binary can bring: libva
+* plus the iHD media driver for Intel. Measured 2026-09-19 — the portable build
+* encodes VAAPI inside our container and ABORTS on the bare Unraid host, where
+* `libva-drm.so.2` does not exist.
 *
-* A child spawned with the first one asks for `-hwaccel vaapi` and gets
-* `Device creation failed: -12` — the name parses, the device cannot exist —
-* then transcodes in software with nothing naming the cause.
+* ## Absent is absent
 *
-* {@link FFMPEG_PATH_ENV} is an operator's VOLUNTARY override, and only that:
-* unset is the normal, correct state on every node, and nothing in the product
-* sets it.
+* The naming carries the release, so two versions coexist during a change and a
+* rollback is a file that is already on disk rather than a download.
 */
-/** Where our container image puts the ffmpeg it installs. Only the image writes this. */
-var BUNDLED_FFMPEG_PATH = "/opt/camstack/bin/ffmpeg";
 /** Operator override. Unset on every node unless a human deliberately set it. */
 var FFMPEG_PATH_ENV = "CAMSTACK_FFMPEG_PATH";
 /**
-* The binary to use, or `null` when there is nothing yet and one must be
-* downloaded.
+* The file name the pinned build is stored under.
+*
+* Versioned on purpose: a download is then idempotent, two releases can sit
+* side by side while a change rolls through a cluster, and going back is a path
+* that already exists instead of a fetch that has to succeed.
+*/
+function ffmpegBinaryName(platform) {
+	return `ffmpeg-${FFMPEG_RELEASE}${platform === "win32" ? ".exe" : ""}`;
+}
+/**
+* The binary to use, or `null` when it has to be downloaded first.
 *
 * An override that does not exist is NOT silently skipped — it is an operator
 * mistake, and falling through to a different binary than the one they named
-* would hide it. The caller reports it and carries on with the default, which
-* is the only safe direction: a typo must not stop a node from serving video.
+* would hide it. The caller reports it and carries on with the pinned build,
+* which is the only safe direction: a typo must not stop a node serving video.
 */
 function chooseFfmpegBinary(input) {
 	const override = input.override?.trim() ?? "";
@@ -336,121 +470,83 @@ function chooseFfmpegBinary(input) {
 		origin: "override",
 		path: override
 	};
-	const bundled = bundledFfmpegPath(input.platform);
-	if (bundled !== null && input.exists(bundled)) return {
-		origin: "bundled",
-		path: bundled
-	};
-	if (input.exists(input.downloadedPath)) return {
+	if (input.exists(input.pinnedPath)) return {
 		origin: "downloaded",
-		path: input.downloadedPath
+		path: input.pinnedPath
 	};
 	return null;
 }
-/** The image-provided path for a platform, or `null` where we ship no image. */
-function bundledFfmpegPath(platform) {
-	return platform === "linux" ? BUNDLED_FFMPEG_PATH : null;
-}
 //#endregion
 //#region src/deps/ffmpeg-downloader.ts
 /**
-* The ffmpeg binary a node runs, and the static build we download when no image
-* provided one.
-*
-* Which binary, and why it is never the host's, is in `ffmpeg-binary-source.ts`.
-* This module is the download half: the URLs, and the resolution that reports
-* what it picked.
+* Provisioning the ffmpeg binary for this node.
 *
-* Sources for the download:
-* - Linux: https://johnvansickle.com/ffmpeg/ (static builds)
-* - macOS: https://www.osxexperts.net/
+* WHICH build, and why every node downloads the same one instead of using
+* anything the machine already has, is in `ffmpeg-binary-source.ts` and
+* `ffmpeg-artifacts.ts`. This module is the act: resolve, download if needed,
+* probe, and say what it got.
 */
 /**
-* johnvansickle for linux (unversioned "release" URLs, so no version appears
-* here), osxexperts for macOS — two different builds, and the Intel one is a
-* different file at a different version from the arm one.
-*/
-var FFMPEG_ARTIFACTS = {
-	"linux-x64": {
-		url: "https://johnvansickle.com/ffmpeg/releases/ffmpeg-release-amd64-static.tar.xz",
-		archiveFormat: "tar.xz",
-		expectedHwaccels: []
-	},
-	"linux-arm64": {
-		url: "https://johnvansickle.com/ffmpeg/releases/ffmpeg-release-arm64-static.tar.xz",
-		archiveFormat: "tar.xz",
-		expectedHwaccels: []
-	},
-	"darwin-arm64": {
-		url: "https://www.osxexperts.net/ffmpeg71arm.zip",
-		archiveFormat: "zip",
-		expectedHwaccels: ["videotoolbox"]
-	},
-	"darwin-x64": {
-		url: "https://www.osxexperts.net/ffmpeg80intel.zip",
-		archiveFormat: "zip",
-		expectedHwaccels: ["videotoolbox"]
-	}
-};
-/** The artifact for this node, or a refusal naming what was asked for. */
-function getFfmpegArtifact(platform, arch) {
-	const artifact = FFMPEG_ARTIFACTS[`${platform}-${arch}`];
-	if (!artifact) throw new Error(`Unsupported platform/architecture for ffmpeg: ${platform}-${arch}`);
-	return artifact;
-}
-/** The URL alone, for a caller that wants nothing else. */
-function getFfmpegDownloadUrl(platform, arch) {
-	return getFfmpegArtifact(platform, arch).url;
-}
-/**
-* Ensure an ffmpeg binary WE provide is available on this node, and report
-* which one and what it can do.
-*
-* Order: the operator's voluntary override → the one our image installed → a
-* copy we already downloaded → download it. The system PATH is not in that
-* list and must never be: see `ffmpeg-binary-source.ts`.
-*
-* The line it logs is the point as much as the path is. "Which ffmpeg am I
-* running, and does it have vaapi" had no answer anywhere in the product, and
-* that is what let a hardware-incapable binary serve every transcode on a hub
-* with a working iGPU for months, silently in software.
+* The ffmpeg this node runs, downloading the pinned build if it is not here
+* yet, and reporting what it got.
+*
+* Order: the operator's `CAMSTACK_FFMPEG_PATH` → the pinned build already on
+* disk → download it. No PATH, no image copy, no per-platform special case —
+* see `ffmpeg-binary-source.ts` for why the image stopped being special after
+* exactly one day.
+*
+* The line it logs is half the point. "Which ffmpeg am I running, and does it
+* have vaapi" had no answer anywhere in the product, and that is what let a
+* hardware-incapable binary serve every transcode on a hub with a working iGPU
+* for months. The other half is the assertion beneath it: a build that probes
+* short of what its artifact claims is a source that changed under us, and it
+* says so with both lists.
 */
 async function ensureFfmpeg(dataDir, logger) {
 	const depsDir = join(dataDir, "deps");
 	const platform = process.platform;
 	const arch = process.arch;
-	const ext = platform === "win32" ? ".exe" : "";
-	const downloadedPath = join(depsDir, `ffmpeg${ext}`);
+	const pinnedPath = join(depsDir, ffmpegBinaryName(platform));
 	const override = process.env[FFMPEG_PATH_ENV];
 	const chosen = chooseFfmpegBinary({
 		platform,
-		downloadedPath,
+		pinnedPath,
 		override,
 		exists: existsSync
 	});
 	if (override !== void 0 && override.trim().length > 0 && chosen?.origin !== "override") logger.error(`${FFMPEG_PATH_ENV} names a binary that does not exist — ignoring it`, { meta: { [FFMPEG_PATH_ENV]: override } });
 	const artifact = chosen === null ? getFfmpegArtifact(platform, arch) : null;
+	if (artifact !== null) logger.info("ffmpeg is not on this node yet — downloading the pinned build", { meta: {
+		release: FFMPEG_RELEASE,
+		url: artifact.url,
+		sizeMb: Math.round(artifact.sizeBytes / 1e6)
+	} });
 	const path = chosen?.path ?? await downloadBinary({
 		name: "ffmpeg",
 		url: artifact?.url ?? getFfmpegDownloadUrl(platform, arch),
 		targetDir: depsDir,
-		targetName: `ffmpeg${ext}`,
+		targetName: ffmpegBinaryName(platform),
 		logger,
 		isArchive: true,
-		archiveFormat: artifact?.archiveFormat ?? "tar.xz"
+		archiveFormat: artifact?.archiveFormat ?? "tar.xz",
+		archiveInnerPath: "ffmpeg",
+		...artifact === null ? {} : { sha256: artifact.sha256 }
 	});
 	const capabilities = await probeFfmpegBinary(path);
 	logger.info("ffmpeg binary resolved", { meta: {
 		path,
 		origin: chosen?.origin ?? "downloaded",
+		release: FFMPEG_RELEASE,
 		version: capabilities.version,
 		hwaccels: [...capabilities.hwaccels].join(",") || "none"
 	} });
-	if (artifact !== null) {
-		const missing = artifact.expectedHwaccels.filter((name) => !capabilities.hwaccels.has(name));
-		if (missing.length > 0) logger.error("the ffmpeg we downloaded cannot do what this artifact is supposed to — the source changed under us", { meta: {
-			url: artifact.url,
-			expected: artifact.expectedHwaccels.join(","),
+	if (chosen?.origin !== "override") {
+		const expected = getFfmpegArtifact(platform, arch).expectedHwaccels;
+		const missing = expected.filter((name) => !capabilities.hwaccels.has(name));
+		if (missing.length > 0) logger.error("this ffmpeg cannot do what its artifact is supposed to — the source changed under us", { meta: {
+			path,
+			release: FFMPEG_RELEASE,
+			expected: expected.join(","),
 			missing: missing.join(","),
 			got: [...capabilities.hwaccels].join(",") || "none"
 		} });
@@ -1937,4 +2033,4 @@ function resolveExportFingerprint(input) {
 	return input.persisted ?? input.fresh;
 }
 //#endregion
-export { ChildCostRegistry, FfmpegProcess, FilesystemStorageProvider, Fmp4FragmentChild, Fmp4FragmentPlane, NO_COST_CLAIM, PYTHON_VERSION, buildBinaryPath, canonicalDeviceFingerprint, canonicalHash, containsOrEquals, diffExportTargets, downloadBinary, ensureBinary, ensureFfmpeg, ensurePython, findInPath, getFfmpegArtifact, getFfmpegDownloadUrl, getPlatformInfo, getPythonDownloadUrl, installPythonPackages, installPythonRequirements, nodeProcStatReader, parseFfmpegCapabilities, parseProcCpuSeconds, parseProcRssBytes, physicalRootOf, probeFfmpegBinary, readProcessCost, resolveExportFingerprint, signExpiringUrl, verifyExpiringUrl };
+export { ChildCostRegistry, FFMPEG_RELEASE, FfmpegProcess, FilesystemStorageProvider, Fmp4FragmentChild, Fmp4FragmentPlane, NO_COST_CLAIM, PYTHON_VERSION, buildBinaryPath, canonicalDeviceFingerprint, canonicalHash, containsOrEquals, diffExportTargets, downloadBinary, ensureBinary, ensureFfmpeg, ensurePython, findInPath, getFfmpegArtifact, getFfmpegDownloadUrl, getPlatformInfo, getPythonDownloadUrl, installPythonPackages, installPythonRequirements, nodeProcStatReader, parseFfmpegCapabilities, parseProcCpuSeconds, parseProcRssBytes, physicalRootOf, probeFfmpegBinary, readProcessCost, resolveExportFingerprint, signExpiringUrl, verifyExpiringUrl };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/types",
-  "version": "1.2.227",
+  "version": "1.2.229",
   "description": "Shared types, interfaces, and model catalogs for the CamStack detection ecosystem",
   "keywords": [
     "camstack",