@camstack/types 1.2.273 → 1.2.275

package/dist/node.js

@@ -21,7 +21,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 	enumerable: true
 }) : target, mod));
 //#endregion
-const require_composition = require("./composition-BRxAnxtU.js");
+const require_composition = require("./composition-DG4jVTfB.js");
 const require_err_msg = require("./err-msg-Dx2Kor0g.js");
 let node_crypto = require("node:crypto");
 let node_fs = require("node:fs");
@@ -315,191 +315,6 @@ 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 — one rule, on every node.
-*
-* ## The rule
-*
-* 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`.
-*
-* 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).
-*
-* ## Why the container image is not special any more
-*
-* 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 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.
-*
-* 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.
-*
-* ## Absent is absent
-*
-* 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.
-*/
-/** Operator override. Unset on every node unless a human deliberately set it. */
-var FFMPEG_PATH_ENV = "CAMSTACK_FFMPEG_PATH";
-/**
-* 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 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() ?? "";
-	if (override.length > 0 && input.exists(override)) return {
-		origin: "override",
-		path: override
-	};
-	if (input.exists(input.pinnedPath)) return {
-		origin: "downloaded",
-		path: input.pinnedPath
-	};
-	return null;
-}
-//#endregion
 //#region src/deps/ffmpeg-downloader.ts
 /**
 * Provisioning the ffmpeg binary for this node.
@@ -529,26 +344,26 @@ async function ensureFfmpeg(dataDir, logger) {
 	const depsDir = (0, node_path.join)(dataDir, "deps");
 	const platform = process.platform;
 	const arch = process.arch;
-	const pinnedPath = (0, node_path.join)(depsDir, ffmpegBinaryName(platform));
-	const override = process.env[FFMPEG_PATH_ENV];
-	const chosen = chooseFfmpegBinary({
+	const pinnedPath = (0, node_path.join)(depsDir, require_composition.ffmpegBinaryName(platform));
+	const override = process.env[require_composition.FFMPEG_PATH_ENV];
+	const chosen = require_composition.chooseFfmpegBinary({
 		platform,
 		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 (override !== void 0 && override.trim().length > 0 && chosen?.origin !== "override") logger.error(`${require_composition.FFMPEG_PATH_ENV} names a binary that does not exist — ignoring it`, { meta: { [require_composition.FFMPEG_PATH_ENV]: override } });
+	const artifact = chosen === null ? require_composition.getFfmpegArtifact(platform, arch) : null;
 	if (artifact !== null) logger.info("ffmpeg is not on this node yet — downloading the pinned build", { meta: {
-		release: FFMPEG_RELEASE,
+		release: require_composition.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),
+		url: artifact?.url ?? require_composition.getFfmpegDownloadUrl(platform, arch),
 		targetDir: depsDir,
-		targetName: ffmpegBinaryName(platform),
+		targetName: require_composition.ffmpegBinaryName(platform),
 		logger,
 		isArchive: true,
 		archiveFormat: artifact?.archiveFormat ?? "tar.xz",
@@ -559,16 +374,16 @@ async function ensureFfmpeg(dataDir, logger) {
 	logger.info("ffmpeg binary resolved", { meta: {
 		path,
 		origin: chosen?.origin ?? "downloaded",
-		release: FFMPEG_RELEASE,
+		release: require_composition.FFMPEG_RELEASE,
 		version: capabilities.version,
 		hwaccels: [...capabilities.hwaccels].join(",") || "none"
 	} });
 	if (chosen?.origin !== "override") {
-		const expected = getFfmpegArtifact(platform, arch).expectedHwaccels;
+		const expected = require_composition.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,
+			release: require_composition.FFMPEG_RELEASE,
 			expected: expected.join(","),
 			missing: missing.join(","),
 			got: [...capabilities.hwaccels].join(",") || "none"
@@ -1560,6 +1375,48 @@ var FfmpegProcess = class {
 	}
 };
 //#endregion
+//#region src/ffmpeg/pinned-spawn.ts
+/**
+* The spawn a one-shot ffmpeg site uses: the spec's seam when one is injected,
+* else the node's PINNED binary (D540), else `null` — and the site refuses by
+* name. There is no fourth answer: the `?? 'ffmpeg'` this replaces made "no
+* pinned build" mean "run the host's", silently, at every clip site that had it.
+*
+* Node-only (`node:child_process`), so it lives under `@camstack/types/node`.
+*/
+/** The detail a site refusing for want of a binary puts in its refusal. */
+var NO_PINNED_FFMPEG_DETAIL = "no pinned ffmpeg on this node (D540)";
+/**
+* {@link pinnedFfmpegSpawner}, asked at the point of use through the node's
+* resolver (`memoizePinnedFfmpeg`). A site that keeps the RESOLVER rather than
+* a path captured at init recovers when a later resolution succeeds; a path
+* captured as `null` at boot stayed `null` until the runner restarted.
+*/
+async function resolvePinnedFfmpegSpawner(seam, resolveFfmpeg, options) {
+	if (seam !== void 0) return {
+		kind: "ready",
+		spawn: seam
+	};
+	let ffmpegBinaryPath;
+	try {
+		ffmpegBinaryPath = await resolveFfmpeg();
+	} catch (err) {
+		return {
+			kind: "refused",
+			detail: `${NO_PINNED_FFMPEG_DETAIL}: ${err instanceof Error ? err.message : String(err)}`
+		};
+	}
+	return {
+		kind: "ready",
+		spawn: (args) => (0, node_child_process.spawn)(ffmpegBinaryPath, [...args], options)
+	};
+}
+function pinnedFfmpegSpawner(seam, ffmpegBinaryPath, options) {
+	if (seam !== void 0) return seam;
+	if (ffmpegBinaryPath === null) return null;
+	return (args) => (0, node_child_process.spawn)(ffmpegBinaryPath, [...args], options);
+}
+//#endregion
 //#region src/process/child-cost-registry.ts
 /**
 * The registry an addon claims its OWN child processes in — the spawn-site
@@ -2142,12 +1999,13 @@ function resolveExportFingerprint(input) {
 }
 //#endregion
 exports.ChildCostRegistry = ChildCostRegistry;
-exports.FFMPEG_RELEASE = FFMPEG_RELEASE;
+exports.FFMPEG_RELEASE = require_composition.FFMPEG_RELEASE;
 exports.FfmpegProcess = FfmpegProcess;
 exports.FilesystemStorageProvider = FilesystemStorageProvider;
 exports.Fmp4FragmentChild = Fmp4FragmentChild;
 exports.Fmp4FragmentPlane = Fmp4FragmentPlane;
 exports.NO_COST_CLAIM = NO_COST_CLAIM;
+exports.NO_PINNED_FFMPEG_DETAIL = NO_PINNED_FFMPEG_DETAIL;
 exports.PYTHON_VERSION = PYTHON_VERSION;
 exports.buildBinaryPath = buildBinaryPath;
 exports.canonicalDeviceFingerprint = canonicalDeviceFingerprint;
@@ -2160,8 +2018,8 @@ exports.ensureBinary = ensureBinary;
 exports.ensureFfmpeg = ensureFfmpeg;
 exports.ensurePython = ensurePython;
 exports.findInPath = findInPath;
-exports.getFfmpegArtifact = getFfmpegArtifact;
-exports.getFfmpegDownloadUrl = getFfmpegDownloadUrl;
+exports.getFfmpegArtifact = require_composition.getFfmpegArtifact;
+exports.getFfmpegDownloadUrl = require_composition.getFfmpegDownloadUrl;
 exports.getPlatformInfo = getPlatformInfo;
 exports.getPythonDownloadUrl = getPythonDownloadUrl;
 exports.installPythonPackages = installPythonPackages;
@@ -2171,9 +2029,11 @@ exports.parseFfmpegCapabilities = parseFfmpegCapabilities;
 exports.parseProcCpuSeconds = parseProcCpuSeconds;
 exports.parseProcRssBytes = parseProcRssBytes;
 exports.physicalRootOf = physicalRootOf;
+exports.pinnedFfmpegSpawner = pinnedFfmpegSpawner;
 exports.probeFfmpegBinary = probeFfmpegBinary;
 exports.readProcessCost = readProcessCost;
 exports.resolveExportFingerprint = resolveExportFingerprint;
+exports.resolvePinnedFfmpegSpawner = resolvePinnedFfmpegSpawner;
 exports.signExpiringUrl = signExpiringUrl;
 exports.verifyExpiringUrl = verifyExpiringUrl;
 exports.writeFileAtomic = writeFileAtomic;

package/dist/node.mjs

@@ -1,4 +1,4 @@
-import { Ct as Fmp4BoxSplitter, Dt as buildFfmpegArgs, P as compositionSourceKey, St as canonicalHash, a as CUSTOMIZATION_BLOCK_NAME_PREFIX, jt as isSoftwareDecode } from "./composition-BK-GTFYb.mjs";
+import { Ct as chooseFfmpegBinary, Dt as getFfmpegDownloadUrl, Et as getFfmpegArtifact, Lt as isSoftwareDecode, Nt as buildFfmpegArgs, Ot as canonicalHash, P as compositionSourceKey, St as FFMPEG_PATH_ENV, Tt as FFMPEG_RELEASE, a as CUSTOMIZATION_BLOCK_NAME_PREFIX, kt as Fmp4BoxSplitter, wt as ffmpegBinaryName } from "./composition-Dq42XWp0.mjs";
 import { t as errMsg } from "./err-msg-DX6i_MY4.mjs";
 import { createHash, createHmac, randomUUID, timingSafeEqual } from "node:crypto";
 import * as fs from "node:fs";
@@ -292,191 +292,6 @@ 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 — one rule, on every node.
-*
-* ## The rule
-*
-* 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`.
-*
-* 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).
-*
-* ## Why the container image is not special any more
-*
-* 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 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.
-*
-* 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.
-*
-* ## Absent is absent
-*
-* 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.
-*/
-/** Operator override. Unset on every node unless a human deliberately set it. */
-var FFMPEG_PATH_ENV = "CAMSTACK_FFMPEG_PATH";
-/**
-* 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 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() ?? "";
-	if (override.length > 0 && input.exists(override)) return {
-		origin: "override",
-		path: override
-	};
-	if (input.exists(input.pinnedPath)) return {
-		origin: "downloaded",
-		path: input.pinnedPath
-	};
-	return null;
-}
-//#endregion
 //#region src/deps/ffmpeg-downloader.ts
 /**
 * Provisioning the ffmpeg binary for this node.
@@ -1537,6 +1352,48 @@ var FfmpegProcess = class {
 	}
 };
 //#endregion
+//#region src/ffmpeg/pinned-spawn.ts
+/**
+* The spawn a one-shot ffmpeg site uses: the spec's seam when one is injected,
+* else the node's PINNED binary (D540), else `null` — and the site refuses by
+* name. There is no fourth answer: the `?? 'ffmpeg'` this replaces made "no
+* pinned build" mean "run the host's", silently, at every clip site that had it.
+*
+* Node-only (`node:child_process`), so it lives under `@camstack/types/node`.
+*/
+/** The detail a site refusing for want of a binary puts in its refusal. */
+var NO_PINNED_FFMPEG_DETAIL = "no pinned ffmpeg on this node (D540)";
+/**
+* {@link pinnedFfmpegSpawner}, asked at the point of use through the node's
+* resolver (`memoizePinnedFfmpeg`). A site that keeps the RESOLVER rather than
+* a path captured at init recovers when a later resolution succeeds; a path
+* captured as `null` at boot stayed `null` until the runner restarted.
+*/
+async function resolvePinnedFfmpegSpawner(seam, resolveFfmpeg, options) {
+	if (seam !== void 0) return {
+		kind: "ready",
+		spawn: seam
+	};
+	let ffmpegBinaryPath;
+	try {
+		ffmpegBinaryPath = await resolveFfmpeg();
+	} catch (err) {
+		return {
+			kind: "refused",
+			detail: `${NO_PINNED_FFMPEG_DETAIL}: ${err instanceof Error ? err.message : String(err)}`
+		};
+	}
+	return {
+		kind: "ready",
+		spawn: (args) => spawn(ffmpegBinaryPath, [...args], options)
+	};
+}
+function pinnedFfmpegSpawner(seam, ffmpegBinaryPath, options) {
+	if (seam !== void 0) return seam;
+	if (ffmpegBinaryPath === null) return null;
+	return (args) => spawn(ffmpegBinaryPath, [...args], options);
+}
+//#endregion
 //#region src/process/child-cost-registry.ts
 /**
 * The registry an addon claims its OWN child processes in — the spawn-site
@@ -2118,4 +1975,4 @@ function resolveExportFingerprint(input) {
 	return input.persisted ?? input.fresh;
 }
 //#endregion
-export { ChildCostRegistry, FFMPEG_RELEASE, FfmpegProcess, FilesystemStorageProvider, Fmp4FragmentChild, Fmp4FragmentPlane, NO_COST_CLAIM, PYTHON_VERSION, buildBinaryPath, canonicalDeviceFingerprint, canonicalHash, containsOrEquals, customizationBlockName, diffExportTargets, downloadBinary, ensureBinary, ensureFfmpeg, ensurePython, findInPath, getFfmpegArtifact, getFfmpegDownloadUrl, getPlatformInfo, getPythonDownloadUrl, installPythonPackages, installPythonRequirements, nodeProcStatReader, parseFfmpegCapabilities, parseProcCpuSeconds, parseProcRssBytes, physicalRootOf, probeFfmpegBinary, readProcessCost, resolveExportFingerprint, signExpiringUrl, verifyExpiringUrl, writeFileAtomic };
+export { ChildCostRegistry, FFMPEG_RELEASE, FfmpegProcess, FilesystemStorageProvider, Fmp4FragmentChild, Fmp4FragmentPlane, NO_COST_CLAIM, NO_PINNED_FFMPEG_DETAIL, PYTHON_VERSION, buildBinaryPath, canonicalDeviceFingerprint, canonicalHash, containsOrEquals, customizationBlockName, diffExportTargets, downloadBinary, ensureBinary, ensureFfmpeg, ensurePython, findInPath, getFfmpegArtifact, getFfmpegDownloadUrl, getPlatformInfo, getPythonDownloadUrl, installPythonPackages, installPythonRequirements, nodeProcStatReader, parseFfmpegCapabilities, parseProcCpuSeconds, parseProcRssBytes, physicalRootOf, pinnedFfmpegSpawner, probeFfmpegBinary, readProcessCost, resolveExportFingerprint, resolvePinnedFfmpegSpawner, signExpiringUrl, verifyExpiringUrl, writeFileAtomic };

package/package.json

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