@camstack/types 1.2.223 → 1.2.225

package/dist/{canonical-hash-C5pB-QV1.mjs → canonical-hash-CvL03d3i.mjs}

@@ -57,6 +57,7 @@ function buildInputArgs(input, decodeHwAccel) {
 	const args = [];
 	if (!isSoftwareDecode(decodeHwAccel)) args.push("-hwaccel", String(decodeHwAccel));
 	if (input.extraArgs?.length) args.push(...input.extraArgs);
+	if (input.decodeThreadCount !== void 0 && input.decodeThreadCount > 0) args.push("-threads", String(input.decodeThreadCount));
 	if (input.analyzeDurationUs !== void 0) args.push("-analyzeduration", String(input.analyzeDurationUs));
 	if (input.probeSizeBytes !== void 0) args.push("-probesize", String(input.probeSizeBytes));
 	if (input.lowDelay === true) args.push("-flags", "low_delay");
@@ -327,7 +328,7 @@ function buildFfmpegArgs(inv) {
 		...(inv.extraInputs ?? []).flatMap((extra) => buildInputArgs(extra, inv.decodeHwAccel)),
 		...graph ? ["-filter_complex", graph.graph] : []
 	];
-	const threadArgs = inv.threadCount > 0 ? ["-threads", String(inv.threadCount)] : [];
+	const threadArgs = [...inv.threadCount > 0 ? ["-threads", String(inv.threadCount)] : [], ...inv.filterThreadCount !== void 0 && inv.filterThreadCount > 0 ? ["-filter_threads", String(inv.filterThreadCount)] : []];
 	const maps = resolveStreamMaps(inv);
 	const videoMapArgs = maps.video ? ["-map", maps.video] : [];
 	const audioMapArgs = maps.audio ? ["-map", maps.audio] : [];

package/dist/{canonical-hash-BS9dQmcQ.js → canonical-hash-DYsYm8is.js}

@@ -57,6 +57,7 @@ function buildInputArgs(input, decodeHwAccel) {
 	const args = [];
 	if (!isSoftwareDecode(decodeHwAccel)) args.push("-hwaccel", String(decodeHwAccel));
 	if (input.extraArgs?.length) args.push(...input.extraArgs);
+	if (input.decodeThreadCount !== void 0 && input.decodeThreadCount > 0) args.push("-threads", String(input.decodeThreadCount));
 	if (input.analyzeDurationUs !== void 0) args.push("-analyzeduration", String(input.analyzeDurationUs));
 	if (input.probeSizeBytes !== void 0) args.push("-probesize", String(input.probeSizeBytes));
 	if (input.lowDelay === true) args.push("-flags", "low_delay");
@@ -327,7 +328,7 @@ function buildFfmpegArgs(inv) {
 		...(inv.extraInputs ?? []).flatMap((extra) => buildInputArgs(extra, inv.decodeHwAccel)),
 		...graph ? ["-filter_complex", graph.graph] : []
 	];
-	const threadArgs = inv.threadCount > 0 ? ["-threads", String(inv.threadCount)] : [];
+	const threadArgs = [...inv.threadCount > 0 ? ["-threads", String(inv.threadCount)] : [], ...inv.filterThreadCount !== void 0 && inv.filterThreadCount > 0 ? ["-filter_threads", String(inv.filterThreadCount)] : []];
 	const maps = resolveStreamMaps(inv);
 	const videoMapArgs = maps.video ? ["-map", maps.video] : [];
 	const audioMapArgs = maps.audio ? ["-map", maps.audio] : [];

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

@@ -0,0 +1,74 @@
+/**
+ * WHICH ffmpeg a node runs, and why it is never the host's.
+ *
+ * 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:
+ *
+ * - 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.
+ *
+ * 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:
+ *
+ * | 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` |
+ *
+ * `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.
+ *
+ * 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:
+ *
+ * ```
+ * /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
+ * ```
+ *
+ * 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.
+ *
+ * {@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.
+ */
+/** 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 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;
+    /** 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.
+ *
+ * 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.
+ */
+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

@@ -6,7 +6,16 @@ export declare function getFfmpegArchiveInfo(platform: string): {
     archiveInnerPath: string;
 };
 /**
- * Ensure ffmpeg binary is available.
- * Checks: deps dir → system PATH → download.
+ * 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.
  */
 export declare function ensureFfmpeg(dataDir: string, logger: IScopedLogger): Promise<string>;

package/dist/ffmpeg/binary-capabilities.d.ts

@@ -0,0 +1,31 @@
+/** What one ffmpeg binary reports about itself. */
+export interface FfmpegBinaryCapabilities {
+    readonly path: string;
+    /** First line of `-version`, for the log that names the choice. */
+    readonly version: string;
+    /** Names from `-hwaccels`, e.g. `vaapi`, `qsv`, `videotoolbox`. */
+    readonly hwaccels: ReadonlySet<string>;
+    /** Encoder names from `-encoders`, e.g. `h264_vaapi`, `h264_videotoolbox`. */
+    readonly encoders: ReadonlySet<string>;
+}
+/**
+ * Turn three raw outputs into capabilities. Separated from the spawning so the
+ * parsers can be held against what ffmpeg REALLY prints — which is how the
+ * legend rows were caught being read as encoder names.
+ */
+export declare function parseFfmpegCapabilities(path: string, versionOut: string, hwaccelOut: string, encoderOut: string): FfmpegBinaryCapabilities;
+/** Ask one binary what it can do. Never throws — an unusable binary answers empty. */
+export declare function probeFfmpegBinary(path: string): Promise<FfmpegBinaryCapabilities>;
+/**
+ * Pick the binary that can serve this node's hardware.
+ *
+ * `wanted` is what the NODE has, from the hardware resolver — the order it is
+ * given in is the order of preference. A candidate that offers any of them
+ * wins, earliest-wanted first; among equals the earliest CANDIDATE wins, so a
+ * caller states its own precedence by the order it passes them in.
+ *
+ * With nothing wanted, or nothing offering anything, the first candidate wins:
+ * a node with no hardware has no reason to prefer one binary over another, and
+ * "the first one" is the caller's existing precedence, unchanged.
+ */
+export declare function pickCapableBinary(candidates: readonly FfmpegBinaryCapabilities[], wanted: readonly string[]): FfmpegBinaryCapabilities | null;

package/dist/ffmpeg/invocation.d.ts

@@ -60,6 +60,24 @@ export interface FfmpegInputPlan {
      */
     readonly analyzeDurationUs?: number;
     readonly probeSizeBytes?: number;
+    /**
+     * `-threads` for the DECODER, emitted before `-i`.
+     *
+     * Distinct from {@link FfmpegInvocation.threadCount}, which lands after the
+     * video args and therefore bounds the ENCODER only. Nothing bounded the
+     * decoder at all until 2026-09-18, and that is where the threads were: left
+     * at auto, libavcodec creates `min(cores, 16)` frame threads per input, on a
+     * 20-core hub, per child.
+     *
+     * Measured the same day: a grid tile reading a 1080p sub-stream held 72
+     * threads; with this set to 1 and `filterThreadCount` to 1 it holds 26. The
+     * container's pid cgroup counts every one against a 2048 ceiling it was
+     * actively refusing at.
+     *
+     * A parallel decode is still a real thing — a 4K software decode at 25 fps
+     * cannot keep up single-threaded — so this is a number, not a flag.
+     */
+    readonly decodeThreadCount?: number;
     /**
      * A headerless stream of raw frames — `-f rawvideo` and the three facts that
      * demuxer cannot discover for itself.
@@ -389,6 +407,21 @@ export interface FfmpegInvocation {
     readonly audio: FfmpegAudioPlan;
     /** `0` = auto (omit `-threads` and let ffmpeg decide). */
     readonly threadCount: number;
+    /**
+     * `-filter_threads` — the size of libavfilter's OWN slice pool, which
+     * `-threads` does not touch.
+     *
+     * A separate number because it is a separate pool: ffmpeg sizes the filter
+     * pool to the core count independently of the codec threads, per graph. On
+     * this 20-core hub that is ~15 threads per graph doing nothing measurable on
+     * a 320x180-class output, and the container's pid cgroup counts every one of
+     * them. Measured on the hub 2026-09-18: a recorder passthrough went 20 → 5
+     * threads, a snapshot grab 35 → 4, an egress transcode 62 → 18, with
+     * `-threads` and this set together.
+     *
+     * Omitted when absent, so no shipped argv changes by adding the field.
+     */
+    readonly filterThreadCount?: number;
     /** Consumer output options, emitted verbatim after the encode block. */
     readonly outputArgs: readonly string[];
     readonly sink: FfmpegSink;

package/dist/index.js

@@ -1,7 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_sleep = require("./sleep-VlZxDyXq.js");
 const require_event_category = require("./event-category-BVfsrBYA.js");
-const require_canonical_hash = require("./canonical-hash-BS9dQmcQ.js");
+const require_canonical_hash = require("./canonical-hash-DYsYm8is.js");
 const require_enums = require("./enums.js");
 const require_err_msg = require("./err-msg-COpsHMw2.js");
 let zod = require("zod");

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import { $ as CAM_PROFILE_ORDER, A as DeviceType, At as isEvent, B as systemMethod, Bt as isAudioChunkFormat, C as customAction, Ct as SHARE_VIEW_KINDS, D as ChargingStatus, Dt as createDurableState, E as deviceCustomAction, Et as normalizeAddonInitResult, F as event, Ft as hydrateSchema, G as ReadinessRegistry, H as nodePin, I as expandCapMethods, It as resolveHydratedFieldValue, J as readinessKey, K as ReadinessTimeoutError, L as isDeviceConfigCap, Lt as AUDIO_CHUNK_FORMATS, M as DEFAULT_RUNTIME_STATE_DURABILITY, Mt as WELL_KNOWN_TAB_MAP, N as DEVICE_SETTINGS_CONTRIBUTION_METHODS, Nt as collectHydratedFieldEntries, O as DeviceFeature, Ot as createEvent, P as DEVICE_STATUS_METHOD, Pt as collectHydratedFieldValues, Q as BrokerStatusSchema, R as method, Rt as audioChunkBytesPerSample, S as DEVICE_CHILDREN_BATCH_MAX, St as DATAPLANE_SECRET_HEADER, T as describeCustomActions, Tt as BaseAddon, U as readNodePin, V as CAP_NODE_PIN_CONTEXT_KEY, W as toNodeId, X as AudioChunkFormatSchema, Y as scopeKey, Z as BrokerStatsSchema, _ as createMirrorSource, _t as SubscribeFramesResultSchema, a as asJsonObject, at as DecodedFrameSchema, b as deviceOpsCapability, bt as parseProfileBrokerId, c as parseJsonArray, ct as FrameHandleSchema, d as BOOT_RECOVERY_BACKOFF_MS, dt as ProfileSlotStatusSchema, et as CamProfileSchema, f as DEVICE_SCOPED_CAPS, ft as StreamSourceEntrySchema, g as createLazyTrpcSource, gt as SubscribeFramesInputSchema, h as createEventBusSliceSource, ht as SubscribeAudioChunksResultSchema, i as asJsonArray, it as DecodedAudioChunkSchema, j as adminUiCapability, jt as WELL_KNOWN_TABS, k as DeviceRole, kt as emitReadiness, l as parseJsonObject, lt as ProfileRtspEntrySchema, m as createDeviceProxy, mt as SubscribeAudioChunksInputSchema, n as sleepCancellable, nt as CamStreamResolutionSchema, o as asNumber, ot as EncodedPacketSchema, p as isDeviceScopedCap, pt as StreamSourceSchema, q as emitDownForOwnedCaps, r as asBoolean, rt as CameraStreamSchema, s as asString, st as FrameHandleFormatSchema, t as sleep, tt as CamStreamKindSchema, u as parseJsonUnknown, ut as ProfileSlotSchema, v as createSliceHandle, vt as makeProfileBrokerId, w as defineCustomActions, wt as DisposerChain, x as viewerUiCapability, xt as selectAssignedProfileSlots, y as RawStateResultSchema, yt as makeSourceBrokerId, z as resolveCapMount, zt as expandAudioChunkToF32le } from "./sleep-GU_us3DG.mjs";
 import { t as EventCategory } from "./event-category-BVDXG4tB.mjs";
-import { a as buildAudioArgs, c as buildVideoArgs, d as logBannerArgs, f as pickVideoEncoder, i as audioPlanFromEncodeProfile, l as invocationFromEncodeProfile, n as Fmp4BoxSplitter, o as buildFfmpegArgs, p as resolveStreamMaps, r as AUDIO_PRESETS, s as buildInputArgs, t as canonicalHash, u as isSoftwareDecode } from "./canonical-hash-C5pB-QV1.mjs";
+import { a as buildAudioArgs, c as buildVideoArgs, d as logBannerArgs, f as pickVideoEncoder, i as audioPlanFromEncodeProfile, l as invocationFromEncodeProfile, n as Fmp4BoxSplitter, o as buildFfmpegArgs, p as resolveStreamMaps, r as AUDIO_PRESETS, s as buildInputArgs, t as canonicalHash, u as isSoftwareDecode } from "./canonical-hash-CvL03d3i.mjs";
 import { EventSourceType } from "./enums.mjs";
 import { t as errMsg } from "./err-msg-IQTHeDzc.mjs";
 import { z } from "zod";

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_canonical_hash = require("./canonical-hash-BS9dQmcQ.js");
+const require_canonical_hash = require("./canonical-hash-DYsYm8is.js");
 const require_err_msg = require("./err-msg-COpsHMw2.js");
 let node_crypto = require("node:crypto");
 let node_fs = require("node:fs");
@@ -185,16 +185,208 @@ async function ensureBinary(opts) {
 	});
 }
 //#endregion
+//#region src/ffmpeg/binary-capabilities.ts
+/**
+* What an ffmpeg binary can actually DO, asked of the binary itself.
+*
+* ## The failure this exists to end
+*
+* `ensureFfmpeg` prefers a downloaded STATIC build over the system one, and a
+* static build is compiled for portability: no vendor libraries, no VAAPI, no
+* QSV. On a machine with a working Intel iGPU that is precisely backwards, and
+* the symptom does not say so. Measured on the hub, 2026-09-18:
+*
+* ```
+* /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
+* ```
+*
+* Every consumer that went through `ensureFfmpeg` — the broker's egress and
+* derived transcodes, the WebRTC transcode leg, the camera grid — asked for
+* `-hwaccel vaapi`, got `Device creation failed: -12`, and fell back to
+* software. `-12` is what fftools prints when `av_hwdevice_ctx_alloc` returns
+* NULL because the type is not in the build: the NAME parses, so the request
+* looks valid and the device simply cannot exist. It reads as a resource
+* problem and is a build property.
+*
+* ## Why asking the kernel was not enough
+*
+* The existing hardware resolver answers from `/dev/dri` presence. That is a
+* correct description of the NODE, and it is what `node-av` needs — the
+* detection workers were on VAAPI the whole time. It says nothing about the
+* separate binary a child will be spawned with, and it was being read as
+* though it did.
+*
+* So: two questions, two answers. What does this node HAVE (the resolver), and
+* what can this BINARY use (here). A backend needs both.
+*/
+/** How long a probe may take before the binary counts as unusable. */
+var PROBE_TIMEOUT_MS = 5e3;
+function run(path, args) {
+	return new Promise((resolve) => {
+		(0, node_child_process.execFile)(path, [...args], { timeout: PROBE_TIMEOUT_MS }, (error, stdout) => {
+			resolve(error ? "" : stdout);
+		});
+	});
+}
+/**
+* `-hwaccels` prints a header line and then one name per line. Anything with a
+* space in it is prose, not a name.
+*/
+function parseNames(output) {
+	const names = /* @__PURE__ */ new Set();
+	for (const raw of output.split("\n")) {
+		const line = raw.trim();
+		if (line.length === 0 || line.includes(" ")) continue;
+		names.add(line);
+	}
+	return names;
+}
+/**
+* `-encoders` prints a LEGEND and then a table, separated by a dashed line:
+*
+* ```
+* Encoders:
+*  V..... = Video
+*  .F.... = Frame-level multithreading
+*  ------
+*  V....D h264_vaapi           H.264/AVC (VAAPI) (codec h264)
+* ```
+*
+* The legend rows have the SAME leading flag shape as the table rows, so a
+* pattern alone matches ` V..... = Video` and yields `=` as an encoder name.
+* Verified against the hub's own output on 2026-09-18, which is how that was
+* caught. So the separator is the parser's state: nothing counts before it.
+*/
+function parseEncoders(output) {
+	const names = /* @__PURE__ */ new Set();
+	let inTable = false;
+	for (const raw of output.split("\n")) {
+		if (!inTable) {
+			if (raw.trim().startsWith("---")) inTable = true;
+			continue;
+		}
+		const match = /^\s[VAS][.F][.S][.X][.B][.D]\s+(\S+)/.exec(raw);
+		if (match?.[1] !== void 0) names.add(match[1]);
+	}
+	return names;
+}
+/**
+* Turn three raw outputs into capabilities. Separated from the spawning so the
+* parsers can be held against what ffmpeg REALLY prints — which is how the
+* legend rows were caught being read as encoder names.
+*/
+function parseFfmpegCapabilities(path, versionOut, hwaccelOut, encoderOut) {
+	return {
+		path,
+		version: versionOut.split("\n")[0]?.trim() ?? "",
+		hwaccels: parseNames(hwaccelOut),
+		encoders: parseEncoders(encoderOut)
+	};
+}
+/** Ask one binary what it can do. Never throws — an unusable binary answers empty. */
+async function probeFfmpegBinary(path) {
+	const [versionOut, hwaccelOut, encoderOut] = await Promise.all([
+		run(path, ["-hide_banner", "-version"]),
+		run(path, ["-hide_banner", "-hwaccels"]),
+		run(path, ["-hide_banner", "-encoders"])
+	]);
+	return parseFfmpegCapabilities(path, versionOut, hwaccelOut, encoderOut);
+}
+//#endregion
+//#region src/deps/ffmpeg-binary-source.ts
+/**
+* WHICH ffmpeg a node runs, and why it is never the host's.
+*
+* 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:
+*
+* - 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.
+*
+* 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:
+*
+* | 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` |
+*
+* `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.
+*
+* 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:
+*
+* ```
+* /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
+* ```
+*
+* 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.
+*
+* {@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.
+*/
+/** 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.
+*
+* 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.
+*/
+function chooseFfmpegBinary(input) {
+	const override = input.override?.trim() ?? "";
+	if (override.length > 0 && input.exists(override)) return {
+		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 {
+		origin: "downloaded",
+		path: input.downloadedPath
+	};
+	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
 /**
-* Download ffmpeg static build for the current platform.
+* The ffmpeg binary a node runs, and the static build we download when no image
+* provided one.
 *
-* Sources:
-* - Linux: https://johnvansickle.com/ffmpeg/ (static builds)
-* - macOS: https://evermeet.cx/ffmpeg/ or homebrew
+* 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.
 *
-* Using BtbN's GitHub releases as they cover both platforms:
-* https://github.com/BtbN/FFmpeg-Builds/releases
+* Sources for the download:
+* - Linux: https://johnvansickle.com/ffmpeg/ (static builds)
+* - macOS: https://www.osxexperts.net/
 */
 var FFMPEG_VERSION = "7.1";
 function getFfmpegDownloadUrl(platform, arch) {
@@ -232,21 +424,48 @@ function getFfmpegArchiveInfo(platform) {
 	}
 }
 /**
-* Ensure ffmpeg binary is available.
-* Checks: deps dir → system PATH → download.
+* 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.
 */
 async function ensureFfmpeg(dataDir, logger) {
 	const depsDir = (0, node_path.join)(dataDir, "deps");
 	const platform = process.platform;
 	const arch = process.arch;
-	const archiveInfo = getFfmpegArchiveInfo(platform);
-	return ensureBinary({
+	const ext = platform === "win32" ? ".exe" : "";
+	const downloadedPath = (0, node_path.join)(depsDir, `ffmpeg${ext}`);
+	const override = process.env[FFMPEG_PATH_ENV];
+	const chosen = chooseFfmpegBinary({
+		platform,
+		downloadedPath,
+		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 path = chosen?.path ?? await downloadBinary({
 		name: "ffmpeg",
+		url: getFfmpegDownloadUrl(platform, arch),
 		targetDir: depsDir,
-		downloadUrl: getFfmpegDownloadUrl(platform, arch),
+		targetName: `ffmpeg${ext}`,
 		logger,
-		...archiveInfo
+		...getFfmpegArchiveInfo(platform)
 	});
+	const capabilities = await probeFfmpegBinary(path);
+	logger.info("ffmpeg binary resolved", { meta: {
+		path,
+		origin: chosen?.origin ?? "downloaded",
+		version: capabilities.version,
+		hwaccels: [...capabilities.hwaccels].join(",") || "none"
+	} });
+	return path;
 }
 //#endregion
 //#region src/deps/python-downloader.ts

package/dist/node.mjs

@@ -1,4 +1,4 @@
-import { n as Fmp4BoxSplitter, o as buildFfmpegArgs, t as canonicalHash, u as isSoftwareDecode } from "./canonical-hash-C5pB-QV1.mjs";
+import { n as Fmp4BoxSplitter, o as buildFfmpegArgs, t as canonicalHash, u as isSoftwareDecode } from "./canonical-hash-CvL03d3i.mjs";
 import { t as errMsg } from "./err-msg-IQTHeDzc.mjs";
 import { createHash, createHmac, randomUUID, timingSafeEqual } from "node:crypto";
 import * as fs from "node:fs";
@@ -7,7 +7,7 @@ import * as path$1 from "node:path";
 import path, { basename, join } from "node:path";
 import { pipeline } from "node:stream/promises";
 import { Readable } from "node:stream";
-import { execFileSync, spawn } from "node:child_process";
+import { execFile, execFileSync, spawn } from "node:child_process";
 import { readFile } from "node:fs/promises";
 //#region src/deps/binary-downloader.ts
 /**
@@ -162,16 +162,208 @@ async function ensureBinary(opts) {
 	});
 }
 //#endregion
+//#region src/ffmpeg/binary-capabilities.ts
+/**
+* What an ffmpeg binary can actually DO, asked of the binary itself.
+*
+* ## The failure this exists to end
+*
+* `ensureFfmpeg` prefers a downloaded STATIC build over the system one, and a
+* static build is compiled for portability: no vendor libraries, no VAAPI, no
+* QSV. On a machine with a working Intel iGPU that is precisely backwards, and
+* the symptom does not say so. Measured on the hub, 2026-09-18:
+*
+* ```
+* /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
+* ```
+*
+* Every consumer that went through `ensureFfmpeg` — the broker's egress and
+* derived transcodes, the WebRTC transcode leg, the camera grid — asked for
+* `-hwaccel vaapi`, got `Device creation failed: -12`, and fell back to
+* software. `-12` is what fftools prints when `av_hwdevice_ctx_alloc` returns
+* NULL because the type is not in the build: the NAME parses, so the request
+* looks valid and the device simply cannot exist. It reads as a resource
+* problem and is a build property.
+*
+* ## Why asking the kernel was not enough
+*
+* The existing hardware resolver answers from `/dev/dri` presence. That is a
+* correct description of the NODE, and it is what `node-av` needs — the
+* detection workers were on VAAPI the whole time. It says nothing about the
+* separate binary a child will be spawned with, and it was being read as
+* though it did.
+*
+* So: two questions, two answers. What does this node HAVE (the resolver), and
+* what can this BINARY use (here). A backend needs both.
+*/
+/** How long a probe may take before the binary counts as unusable. */
+var PROBE_TIMEOUT_MS = 5e3;
+function run(path, args) {
+	return new Promise((resolve) => {
+		execFile(path, [...args], { timeout: PROBE_TIMEOUT_MS }, (error, stdout) => {
+			resolve(error ? "" : stdout);
+		});
+	});
+}
+/**
+* `-hwaccels` prints a header line and then one name per line. Anything with a
+* space in it is prose, not a name.
+*/
+function parseNames(output) {
+	const names = /* @__PURE__ */ new Set();
+	for (const raw of output.split("\n")) {
+		const line = raw.trim();
+		if (line.length === 0 || line.includes(" ")) continue;
+		names.add(line);
+	}
+	return names;
+}
+/**
+* `-encoders` prints a LEGEND and then a table, separated by a dashed line:
+*
+* ```
+* Encoders:
+*  V..... = Video
+*  .F.... = Frame-level multithreading
+*  ------
+*  V....D h264_vaapi           H.264/AVC (VAAPI) (codec h264)
+* ```
+*
+* The legend rows have the SAME leading flag shape as the table rows, so a
+* pattern alone matches ` V..... = Video` and yields `=` as an encoder name.
+* Verified against the hub's own output on 2026-09-18, which is how that was
+* caught. So the separator is the parser's state: nothing counts before it.
+*/
+function parseEncoders(output) {
+	const names = /* @__PURE__ */ new Set();
+	let inTable = false;
+	for (const raw of output.split("\n")) {
+		if (!inTable) {
+			if (raw.trim().startsWith("---")) inTable = true;
+			continue;
+		}
+		const match = /^\s[VAS][.F][.S][.X][.B][.D]\s+(\S+)/.exec(raw);
+		if (match?.[1] !== void 0) names.add(match[1]);
+	}
+	return names;
+}
+/**
+* Turn three raw outputs into capabilities. Separated from the spawning so the
+* parsers can be held against what ffmpeg REALLY prints — which is how the
+* legend rows were caught being read as encoder names.
+*/
+function parseFfmpegCapabilities(path, versionOut, hwaccelOut, encoderOut) {
+	return {
+		path,
+		version: versionOut.split("\n")[0]?.trim() ?? "",
+		hwaccels: parseNames(hwaccelOut),
+		encoders: parseEncoders(encoderOut)
+	};
+}
+/** Ask one binary what it can do. Never throws — an unusable binary answers empty. */
+async function probeFfmpegBinary(path) {
+	const [versionOut, hwaccelOut, encoderOut] = await Promise.all([
+		run(path, ["-hide_banner", "-version"]),
+		run(path, ["-hide_banner", "-hwaccels"]),
+		run(path, ["-hide_banner", "-encoders"])
+	]);
+	return parseFfmpegCapabilities(path, versionOut, hwaccelOut, encoderOut);
+}
+//#endregion
+//#region src/deps/ffmpeg-binary-source.ts
+/**
+* WHICH ffmpeg a node runs, and why it is never the host's.
+*
+* 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:
+*
+* - 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.
+*
+* 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:
+*
+* | 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` |
+*
+* `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.
+*
+* 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:
+*
+* ```
+* /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
+* ```
+*
+* 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.
+*
+* {@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.
+*/
+/** 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.
+*
+* 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.
+*/
+function chooseFfmpegBinary(input) {
+	const override = input.override?.trim() ?? "";
+	if (override.length > 0 && input.exists(override)) return {
+		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 {
+		origin: "downloaded",
+		path: input.downloadedPath
+	};
+	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
 /**
-* Download ffmpeg static build for the current platform.
+* The ffmpeg binary a node runs, and the static build we download when no image
+* provided one.
 *
-* Sources:
-* - Linux: https://johnvansickle.com/ffmpeg/ (static builds)
-* - macOS: https://evermeet.cx/ffmpeg/ or homebrew
+* 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.
 *
-* Using BtbN's GitHub releases as they cover both platforms:
-* https://github.com/BtbN/FFmpeg-Builds/releases
+* Sources for the download:
+* - Linux: https://johnvansickle.com/ffmpeg/ (static builds)
+* - macOS: https://www.osxexperts.net/
 */
 var FFMPEG_VERSION = "7.1";
 function getFfmpegDownloadUrl(platform, arch) {
@@ -209,21 +401,48 @@ function getFfmpegArchiveInfo(platform) {
 	}
 }
 /**
-* Ensure ffmpeg binary is available.
-* Checks: deps dir → system PATH → download.
+* 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.
 */
 async function ensureFfmpeg(dataDir, logger) {
 	const depsDir = join(dataDir, "deps");
 	const platform = process.platform;
 	const arch = process.arch;
-	const archiveInfo = getFfmpegArchiveInfo(platform);
-	return ensureBinary({
+	const ext = platform === "win32" ? ".exe" : "";
+	const downloadedPath = join(depsDir, `ffmpeg${ext}`);
+	const override = process.env[FFMPEG_PATH_ENV];
+	const chosen = chooseFfmpegBinary({
+		platform,
+		downloadedPath,
+		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 path = chosen?.path ?? await downloadBinary({
 		name: "ffmpeg",
+		url: getFfmpegDownloadUrl(platform, arch),
 		targetDir: depsDir,
-		downloadUrl: getFfmpegDownloadUrl(platform, arch),
+		targetName: `ffmpeg${ext}`,
 		logger,
-		...archiveInfo
+		...getFfmpegArchiveInfo(platform)
 	});
+	const capabilities = await probeFfmpegBinary(path);
+	logger.info("ffmpeg binary resolved", { meta: {
+		path,
+		origin: chosen?.origin ?? "downloaded",
+		version: capabilities.version,
+		hwaccels: [...capabilities.hwaccels].join(",") || "none"
+	} });
+	return path;
 }
 //#endregion
 //#region src/deps/python-downloader.ts

package/package.json

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