@camstack/types 1.2.227 → 1.2.228

package/dist/deps/binary-downloader.d.ts

@@ -24,6 +24,18 @@ export interface DownloadOptions {
     readonly archiveFormat?: 'zip' | 'tar.gz' | 'tar.xz';
     /** Relative path within archive to the binary (e.g., 'ffmpeg-6.1/bin/ffmpeg') */
     readonly archiveInnerPath?: string;
+    /**
+     * SHA-256 the downloaded ARCHIVE must have, verified before a byte of it is
+     * extracted.
+     *
+     * Optional only because the python downloader predates it. For ffmpeg it is
+     * not optional in practice: the download is the ONLY source of the binary
+     * every transcode runs through, it arrives over a redirect to a third-party
+     * host, and the publisher ships no checksums of its own — so ours is the only
+     * thing standing between a changed artifact and a silent swap of the most
+     * privileged subprocess this system spawns.
+     */
+    readonly sha256?: string;
 }
 /**
  * Download a binary to the target directory.

package/dist/deps/ffmpeg-artifacts.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 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. */
+export declare const FFMPEG_RELEASE: "8.1.2-5";
+/** ffmpeg 8.1.2 is what this release builds — for the log line, not resolution. */
+export declare const FFMPEG_VERSION: "8.1.2";
+export interface FfmpegArtifact {
+    readonly url: string;
+    readonly archiveFormat: 'zip' | 'tar.gz' | 'tar.xz';
+    /** SHA-256 of the ARCHIVE, verified before extraction. */
+    readonly sha256: string;
+    /** Bytes, as published — for the "downloading 60 MB" line. */
+    readonly sizeBytes: number;
+    /**
+     * `-hwaccels` names this build must report. Asserted after download: short of
+     * this is a changed source, not a quiet degradation.
+     */
+    readonly expectedHwaccels: readonly string[];
+}
+/** The artifact for this node, or a refusal naming what was asked for. */
+export declare function getFfmpegArtifact(platform: string, arch: string): FfmpegArtifact;
+/** The URL alone, for a caller that wants nothing else. */
+export declare function getFfmpegDownloadUrl(platform: string, arch: string): string;

package/dist/deps/ffmpeg-binary-source.d.ts

@@ -1,74 +1,72 @@
 /**
- * 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. */
-export declare const BUNDLED_FFMPEG_PATH = "/opt/camstack/bin/ffmpeg";
 /** Operator override. Unset on every node unless a human deliberately set it. */
 export declare const FFMPEG_PATH_ENV = "CAMSTACK_FFMPEG_PATH";
-export type FfmpegBinaryOrigin = 'override' | 'bundled' | 'downloaded';
+export type FfmpegBinaryOrigin = 'override' | 'downloaded';
 export interface FfmpegBinaryChoice {
     readonly origin: FfmpegBinaryOrigin;
     readonly path: string;
 }
 export interface FfmpegBinarySourceInput {
     readonly platform: string;
-    /** `<dataDir>/deps/ffmpeg`, where a downloaded copy lands. */
-    readonly downloadedPath: string;
+    /** `<dataDir>/deps/ffmpeg-<release>` — where the pinned build lands. */
+    readonly pinnedPath: string;
     /** The raw value of {@link FFMPEG_PATH_ENV}, or null/empty when unset. */
     readonly override: string | null | undefined;
     readonly exists: (path: string) => boolean;
 }
 /**
- * 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.
+ */
+export declare function ffmpegBinaryName(platform: string): string;
+/**
+ * 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.
  */
 export declare function chooseFfmpegBinary(input: FfmpegBinarySourceInput): FfmpegBinaryChoice | null;
-/** The image-provided path for a platform, or `null` where we ship no image. */
-export declare function bundledFfmpegPath(platform: string): string | null;

package/dist/deps/ffmpeg-downloader.d.ts

@@ -1,47 +1,18 @@
 import type { IScopedLogger } from '../interfaces/logging.js';
 /**
- * One artifact per platform+arch: the URL, how it is packed, and what the
- * binary inside is SUPPOSED to be able to do.
+ * The ffmpeg this node runs, downloading the pinned build if it is not here
+ * yet, and reporting what it got.
  *
- * It is a table rather than two functions computing strings because the three
- * facts belong together and drifted apart when they did not:
+ * 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 darwin branch computed an arch and then discarded it, handing an
- *   Intel Mac an arm64 Mach-O it cannot execute under any translation;
- * - a single `FFMPEG_VERSION = '7.1'` named the version of nothing — the linux
- *   URL is unversioned and serves 7.0.2 — so the inner path built from it never
- *   matched and only the extractor's recursive fallback saved it;
- * - and nothing recorded what a download was expected to be capable of, which
- *   is how a build with no VAAPI at all served every transcode on this fleet
- *   for months (D536).
- *
- * `expectedHwaccels` is that missing claim. It is deliberately EMPTY for the
- * linux static builds: they carry no hardware support and pretending otherwise
- * would make the assertion a lie. That emptiness is the honest description of
- * a portable build, and the reason a node that has an image prefers the image's
- * ffmpeg over this one.
- */
-export interface FfmpegArtifact {
-    readonly url: string;
-    readonly archiveFormat: 'zip' | 'tar.gz' | 'tar.xz';
-    /** `-hwaccels` names this artifact is built with. Empty = none, honestly. */
-    readonly expectedHwaccels: readonly string[];
-}
-/** The artifact for this node, or a refusal naming what was asked for. */
-export declare function getFfmpegArtifact(platform: string, arch: string): FfmpegArtifact;
-/** The URL alone, for a caller that wants nothing else. */
-export declare function getFfmpegDownloadUrl(platform: string, arch: string): string;
-/**
- * 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 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.
  */
 export declare function ensureFfmpeg(dataDir: string, logger: IScopedLogger): Promise<string>;

package/dist/deps/index.d.ts

@@ -1,3 +1,4 @@
 export { ensureBinary, downloadBinary, findInPath, getPlatformInfo, buildBinaryPath, } from './binary-downloader.js';
-export { ensureFfmpeg, getFfmpegArtifact, getFfmpegDownloadUrl } from './ffmpeg-downloader.js';
+export { ensureFfmpeg } from './ffmpeg-downloader.js';
+export { FFMPEG_RELEASE, getFfmpegArtifact, getFfmpegDownloadUrl } from './ffmpeg-artifacts.js';
 export { ensurePython, installPythonPackages, installPythonRequirements, getPythonDownloadUrl, PYTHON_VERSION, } from './python-downloader.js';

package/dist/node.d.ts

@@ -1,6 +1,7 @@
 export type { PlatformInfo } from './deps/binary-downloader.js';
 export { buildBinaryPath, downloadBinary, ensureBinary, findInPath, getPlatformInfo, } from './deps/binary-downloader.js';
-export { ensureFfmpeg, getFfmpegArtifact, getFfmpegDownloadUrl } from './deps/ffmpeg-downloader.js';
+export { ensureFfmpeg } from './deps/ffmpeg-downloader.js';
+export { FFMPEG_RELEASE, getFfmpegArtifact, getFfmpegDownloadUrl } from './deps/ffmpeg-artifacts.js';
 export { probeFfmpegBinary, parseFfmpegCapabilities, type FfmpegBinaryCapabilities, } from './ffmpeg/binary-capabilities.js';
 export { ensurePython, getPythonDownloadUrl, installPythonPackages, installPythonRequirements, PYTHON_VERSION, } from './deps/python-downloader.js';
 export type { Fmp4FragmentChildArgs, Fmp4FragmentChildDeps, } from './ffmpeg/fmp4-fragment-child.js';

package/dist/node.js

@@ -73,6 +73,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 = (0, node_crypto.createHash)("sha256").update((0, node_fs.readFileSync)(file)).digest("hex");
+	if (actual === expected) return;
+	try {
+		(0, node_fs.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.
 */
@@ -97,6 +114,7 @@ async function downloadBinary(opts) {
 		const ext = archiveFormat ?? "tar.gz";
 		const tmpArchive = (0, node_path.join)(targetDir, `${name}-download.${ext}`);
 		await (0, node_stream_promises.pipeline)(node_stream.Readable.fromWeb(response.body), (0, node_fs.createWriteStream)(tmpArchive));
+		verifyChecksum(tmpArchive, opts.sha256, name, url);
 		const tmpExtractDir = (0, node_path.join)(targetDir, `${name}-extract`);
 		(0, node_fs.mkdirSync)(tmpExtractDir, { recursive: true });
 		if (ext === "zip") try {
@@ -143,7 +161,10 @@ async function downloadBinary(opts) {
 			recursive: true,
 			force: true
 		});
-	} else await (0, node_stream_promises.pipeline)(node_stream.Readable.fromWeb(response.body), (0, node_fs.createWriteStream)(targetPath));
+	} else {
+		await (0, node_stream_promises.pipeline)(node_stream.Readable.fromWeb(response.body), (0, node_fs.createWriteStream)(targetPath));
+		verifyChecksum(targetPath, opts.sha256, name, url);
+	}
 	(0, node_fs.chmodSync)(targetPath, 493);
 	logger.info("Binary downloaded", { meta: {
 		name,
@@ -294,64 +315,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() ?? "";
@@ -359,121 +493,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 = (0, node_path.join)(dataDir, "deps");
 	const platform = process.platform;
 	const arch = process.arch;
-	const ext = platform === "win32" ? ".exe" : "";
-	const downloadedPath = (0, node_path.join)(depsDir, `ffmpeg${ext}`);
+	const pinnedPath = (0, node_path.join)(depsDir, ffmpegBinaryName(platform));
 	const override = process.env[FFMPEG_PATH_ENV];
 	const chosen = chooseFfmpegBinary({
 		platform,
-		downloadedPath,
+		pinnedPath,
 		override,
 		exists: node_fs.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"
 		} });
@@ -1961,6 +2057,7 @@ function resolveExportFingerprint(input) {
 }
 //#endregion
 exports.ChildCostRegistry = ChildCostRegistry;
+exports.FFMPEG_RELEASE = FFMPEG_RELEASE;
 exports.FfmpegProcess = FfmpegProcess;
 exports.FilesystemStorageProvider = FilesystemStorageProvider;
 exports.Fmp4FragmentChild = Fmp4FragmentChild;

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.228",
   "description": "Shared types, interfaces, and model catalogs for the CamStack detection ecosystem",
   "keywords": [
     "camstack",