@camstack/types 1.2.224 → 1.2.226

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

@@ -378,6 +378,28 @@ export interface FfmpegFilterGraph {
      */
     readonly audioOutLabel?: string | null;
 }
+/**
+ * The hardware device an ENCODER runs on — a different question from
+ * {@link FfmpegInvocation.decodeHwAccel}, and the reason both exist.
+ *
+ * A software decode can feed a hardware encoder: ffmpeg pushes the frames to
+ * the GPU with `hwupload`, and the encode — which is where the CPU actually
+ * goes — never touches a core. Tying the two together is what kept this hub on
+ * `libx264` while its iGPU sat idle: the node's DECODE preference is `copy`
+ * for a good reason (hardware decode hard-fails on a fragile HEVC source) and
+ * that preference was deciding the ENCODER too.
+ *
+ * Declaring it is all-or-nothing by construction: the device option, the
+ * upload filter and the encoder are emitted together or not at all, because
+ * any two of the three without the third is a child that dies at start-up
+ * ("No device available for encoder", "Impossible to convert between the
+ * formats").
+ */
+export interface FfmpegHwEncodeDevice {
+    readonly kind: 'vaapi';
+    /** DRM render node, e.g. `/dev/dri/renderD128`. */
+    readonly renderNode: string;
+}
 export interface FfmpegInvocation {
     readonly logLevel: 'error' | 'warning' | 'info';
     /**
@@ -387,6 +409,12 @@ export interface FfmpegInvocation {
      * DECODER ADDON's ranking, never the raw kernel resolver's.
      */
     readonly decodeHwAccel: string | null;
+    /**
+     * The device the hardware ENCODER runs on. Absent ⇒ nothing changes: no
+     * device option, no upload filter, argv unchanged for every software
+     * encode and for every call site that predates this field.
+     */
+    readonly hwEncodeDevice?: FfmpegHwEncodeDevice;
     readonly input: FfmpegInputPlan;
     /**
      * Inputs 1..N-1, emitted after {@link input} in this order, each with its own
@@ -464,32 +492,14 @@ export type FfmpegStreamSelection = Pick<FfmpegInvocation, 'extraInputs' | 'filt
  */
 export declare function resolveStreamMaps(selection: FfmpegStreamSelection): FfmpegStreamMaps;
 /** The whole video block (`-vf` … `-c:v` … knobs), after `-i`. */
-export declare function buildVideoArgs(video: FfmpegVideoPlan, outputArgs: readonly string[], filterGraph?: FfmpegFilterGraph | null): string[];
+export declare function buildVideoArgs(video: FfmpegVideoPlan, outputArgs: readonly string[], filterGraph?: FfmpegFilterGraph | null, 
+/** Set when the encoder runs on a GPU — see {@link FfmpegHwEncodeDevice}. */
+hwEncode?: {
+    readonly device: FfmpegHwEncodeDevice;
+    readonly decodeHwAccel: string | null;
+}): string[];
 /** The whole audio block, after `-i`. */
 export declare function buildAudioArgs(audio: FfmpegAudioPlan): string[];
-/**
- * Assemble the full ffmpeg argument list. Layout:
- *
- *   -hide_banner -loglevel <level>
- *   [-hwaccel <backend|auto>]        ─┐ INPUT options — strictly before -i.
- *   [<input.extraArgs>]               │
- *   [-fflags <flag>…]                 │
- *   [-rtsp_transport tcp]             │
- *   -i <url>                         ─┘ …repeated per extraInput
- *   [-filter_complex <graph>]         ─ global, after the LAST -i
- *   [-map <video>]  <video block>  <threads>  ─┐ OUTPUT options.
- *   [-map <audio>]  <audio block>              │
- *   <consumer outputArgs verbatim>             │
- *   <sink>                                    ─┘ terminal
- *
- * The `-map`s are DERIVED (see {@link resolveStreamMaps}), never constants:
- * one input with no graph emits none at all, which is why the argv of every
- * call site that predates the N-input extension is unchanged to the byte.
- *
- * {@link FfmpegInvocation.audioSidecar} is the one map that stays literal
- * (`0:a:0?`): the sidecar is defined as the SOURCE's microphone on its own RTP
- * output, not as whatever the main output happens to carry.
- */
 export declare function buildFfmpegArgs(inv: FfmpegInvocation): string[];
 /**
  * The hardware encoder for a target codec on `backend`, or the software one.

package/dist/generated/addon-api.d.ts

@@ -9206,6 +9206,13 @@ export type AppRouter = TrpcCoreRouter<{
             output: z.infer<typeof webrtcSessionCapability.methods.getSessionState.output>;
             meta: object;
         }>;
+        getSessionDebug: TRPCQueryProcedure<{
+            input: {
+                [x: string]: unknown;
+            } & z.input<typeof webrtcSessionCapability.methods.getSessionDebug.input>;
+            output: z.infer<typeof webrtcSessionCapability.methods.getSessionDebug.output>;
+            meta: object;
+        }>;
     }>>;
     zoneAnalytics: TRPCBuiltRouter<{
         ctx: TrpcContext;

package/dist/generated/method-access-map.d.ts

@@ -6,7 +6,7 @@
  * scope+access check inside `protectedProcedure` (see
  * `server/backend/src/api/trpc/trpc.middleware.ts`).
  *
- * Coverage: 1055 method paths across 131 capabilities.
+ * Coverage: 1056 method paths across 131 capabilities.
  */
 import type { CapabilityMethodAccess } from '../capabilities/capability-definition.js';
 export interface MethodAccessRecord {

package/dist/generated/method-device-selectors.d.ts

@@ -6,7 +6,7 @@
  * system-scope cap that takes a deviceId was previously never device-filtered
  * — see the generator header).
  *
- * Coverage: 387 methods carry a device reference, of which
+ * Coverage: 388 methods carry a device reference, of which
  * 141 are on SYSTEM-scope caps.
  *
  * Top-level fields, number arrays, and one-level arrays of objects carrying

package/dist/index.js

@@ -1,7 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_sleep = require("./sleep-VlZxDyXq.js");
+const require_sleep = require("./sleep-D7DPSeiv.js");
 const require_event_category = require("./event-category-BVfsrBYA.js");
-const require_canonical_hash = require("./canonical-hash-DYsYm8is.js");
+const require_canonical_hash = require("./canonical-hash-CSE4ioRi.js");
 const require_enums = require("./enums.js");
 const require_err_msg = require("./err-msg-COpsHMw2.js");
 let zod = require("zod");
@@ -20819,6 +20819,7 @@ var MediaFileKindEnum = zod.z.enum([
 	"keyFrameSmall",
 	"thumbnailSmall",
 	"confirmationCrop",
+	"debugCrop",
 	"sceneFrame"
 ]);
 /**
@@ -23196,6 +23197,18 @@ var RunnerCameraConfigSchema = zod.z.object({
 	motionStreamId: zod.z.string(),
 	detectionStreamId: zod.z.string(),
 	/**
+	* Which rung this camera's audio analysis listens on — `auto` (the lowest
+	* AVAILABLE native rung) or an explicit one.
+	*
+	* Not consumed by the runner: carried here so it travels with the camera's
+	* config the way `audioMotionWindowMs` does, and so the orchestrator's
+	* watchdog resolves the same stream the audio subscription did. OPTIONAL
+	* with no default — absent means `auto`, which is what every camera written
+	* before this field had, and an absent optional adds nothing to the
+	* generated cap-input defaults (D537).
+	*/
+	audioStreamPick: require_sleep.AudioStreamPickSchema.optional(),
+	/**
 	* Motion sources that can activate the pipeline. At least one must
 	* be present. Multiple sources OR-ed: any one firing arms the
 	* cooldown timer and transitions watching → active. The same
@@ -27132,6 +27145,104 @@ var WebrtcStreamChoiceSchema = zod.z.object({
 	bitrateKbps: zod.z.number().nullable()
 });
 /**
+* The last move the adaptive ladder made on this session, and the numbers it
+* rested on. Mirrors `LadderDecision` in the stream-broker's
+* `adaptive-controller.ts` — the log line's evidence, made readable.
+*
+* Nullability is load-bearing: `lossRatio: null` means the loss tracker had
+* no window to report, which is NOT a link with zero loss.
+*/
+var WebrtcLadderDecisionSchema = zod.z.object({
+	/** `loss` — RTCP / client-reported packet loss; `stall` — the picture
+	*  stopped moving; `healthy` — a promotion. */
+	cause: zod.z.enum([
+		"loss",
+		"stall",
+		"healthy"
+	]),
+	/** The rung the ladder moved TO. Null for a move that changed no rung
+	*  (an MTU reduction, a forced transcode-down at the bottom). */
+	tier: require_sleep.CamProfileSchema.nullable(),
+	/** Whether that move forced the egress transcode-down rung. */
+	forcedTranscodeDown: zod.z.boolean(),
+	/** Loss ratio over the tracker's window at the moment of the decision. */
+	lossRatio: zod.z.number().nullable(),
+	/** The client's reported downlink at that moment, in kbps. */
+	clientKbps: zod.z.number().nullable(),
+	/** How long the stall detector had been seeing nothing arrive. */
+	stalledForMs: zod.z.number().nullable(),
+	/** Whether the broker WAS sending while that was measured — the half that
+	*  separates "the camera stopped" from "the link stopped". */
+	serverSending: zod.z.boolean().nullable(),
+	/** Epoch ms. The overlay prints its age; a decision from 40 minutes ago
+	*  must not read like one from this second. */
+	at: zod.z.number()
+});
+/** Per-tier count of MEASURED downgrades this viewer session has suffered. */
+var WebrtcTierFailureSchema = zod.z.object({
+	tier: require_sleep.CamProfileSchema,
+	failures: zod.z.number().int().nonnegative()
+});
+/**
+* What the SERVER decided for one WebRTC session — the half the client cannot
+* measure. See `getSessionDebug`.
+*/
+var WebrtcSessionDebugSchema = zod.z.object({
+	sessionId: zod.z.string(),
+	/** Whether the session still exists here. Everything below is null when
+	*  it does not — a dead session has no measurements, not zero ones. */
+	alive: zod.z.boolean(),
+	/** Epoch ms this snapshot was taken, so the overlay can show its age. */
+	observedAt: zod.z.number(),
+	/** The broker actually feeding this session (`<deviceId>/<camStreamId>`). */
+	brokerId: zod.z.string().nullable(),
+	camStreamId: zod.z.string().nullable(),
+	/** `derived` = this hub BUILT the rung being served (a transcode/scale of
+	*  another stream); `native` = the camera's own encode. */
+	sourceKind: zod.z.enum([
+		"native",
+		"derived",
+		"unknown"
+	]),
+	/** Whether the ladder is running at all (an `adaptive` target). */
+	adaptive: zod.z.boolean(),
+	/** The rung `auto` ACTUALLY resolved to right now. Null when the broker
+	*  is bound to no profile slot (a manually-activated stream). */
+	servedTier: require_sleep.CamProfileSchema.nullable(),
+	/** Which node ingests the source. Null when unresolved. */
+	ingestNodeId: zod.z.string().nullable(),
+	/** Whether that node is a remote one (the media crosses a node boundary
+	*  before it reaches this session). Null when unresolved. */
+	ingestIsRemote: zod.z.boolean().nullable(),
+	/** Codec off the source, and the one negotiated with this client. */
+	sourceCodec: zod.z.string().nullable(),
+	negotiatedCodec: zod.z.string().nullable(),
+	/** Whether the EGRESS leg re-encodes for this client or forwards the
+	*  source bytes untouched. */
+	egressLeg: zod.z.enum([
+		"copy",
+		"transcode",
+		"unknown"
+	]),
+	/** What the broker itself reports about the rung it is serving. */
+	brokerStatus: zod.z.string().nullable(),
+	brokerCodec: zod.z.string().nullable(),
+	brokerBitrateKbps: zod.z.number().nullable(),
+	brokerInputFps: zod.z.number().nullable(),
+	brokerUptimeMs: zod.z.number().nullable(),
+	/** RTP packets this session has sent — the server's own "am I sending?". */
+	rtpPacketsSent: zod.z.number().nullable(),
+	/** D42: the track may be carrying the recorded feeder, not live. The ladder
+	*  is suspended there, so a frozen picture in `recorded` mode means
+	*  something entirely different. */
+	trackMode: zod.z.enum(["live", "recorded"]).nullable(),
+	lastDecision: WebrtcLadderDecisionSchema.nullable(),
+	tierFailures: zod.z.array(WebrtcTierFailureSchema),
+	/** Successful promotions in this viewer session (drives the progressive
+	*  healthy timer). Null when no ladder is running. */
+	upgradeCount: zod.z.number().nullable()
+});
+/**
 * WebRTC session — device-scoped facade over the system `webrtc` cap.
 *
 * Exposes per-device signaling (`createSession`, `handleAnswer`,
@@ -27371,7 +27482,27 @@ var webrtcSessionCapability = {
 			* the same answer as "it ended": either way nothing is holding it up.
 			*/
 			alive: zod.z.boolean()
-		}))
+		})),
+		/**
+		* The SERVER's half of the stream-debug overlay, for one live session.
+		*
+		* The client can measure its own transport (`getStats()`); it cannot see
+		* which rung `auto` actually resolved to, why the ladder last moved, or
+		* whether the rung it is being served is the camera's own encode or
+		* something this hub built. That asymmetry is why "quality is stuck on
+		* low" reports have historically been unanswerable from the viewer alone.
+		*
+		* EVERY measurement here is nullable and `null` means UNKNOWN, never zero
+		* (D393): a session whose ladder has never moved reports
+		* `lastDecision: null`, which is a different fact from a ladder that moved
+		* for `healthy` with a 0 loss ratio.
+		*
+		* Read-only, ~1 Hz, polled by the overlay only while it is visible.
+		*/
+		getSessionDebug: require_sleep.method(zod.z.object({
+			deviceId: zod.z.number().int().nonnegative(),
+			sessionId: zod.z.string()
+		}), WebrtcSessionDebugSchema, { kind: "query" })
 	},
 	/** BIG PLAN 2: declarative mount hint — read by `@camstack/system` `buildCapRouters`. */
 	mount: { kind: "server-provided" }
@@ -50470,6 +50601,12 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"webrtcSession.getSessionDebug": {
+		capName: "webrtc-session",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
 	"webrtcSession.getSessionState": {
 		capName: "webrtc-session",
 		capScope: "device",
@@ -52726,6 +52863,11 @@ var METHOD_DEVICE_SELECTORS = Object.freeze({
 		form: "single",
 		optional: false
 	}],
+	"webrtcSession.getSessionDebug": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
 	"webrtcSession.getSessionState": [{
 		name: "deviceId",
 		form: "single",
@@ -58233,6 +58375,7 @@ exports.AudioMetricsHistoryPointSchema = AudioMetricsHistoryPointSchema;
 exports.AudioMetricsHistorySchema = AudioMetricsHistorySchema;
 exports.AudioMetricsSnapshotSchema = AudioMetricsSnapshotSchema;
 exports.AudioPcmChunkSchema = AudioPcmChunkSchema;
+exports.AudioStreamPickSchema = require_sleep.AudioStreamPickSchema;
 exports.AuthResultSchema = AuthResultSchema;
 exports.AutoUpdateSettingsSchema = AutoUpdateSettingsSchema;
 exports.AutomationActionSchema = AutomationActionSchema;
@@ -59266,8 +59409,11 @@ exports.WELL_KNOWN_TABS = require_sleep.WELL_KNOWN_TABS;
 exports.WELL_KNOWN_TAB_MAP = require_sleep.WELL_KNOWN_TAB_MAP;
 exports.WaterHeaterStatusSchema = WaterHeaterStatusSchema;
 exports.WeatherStatusSchema = WeatherStatusSchema;
+exports.WebrtcLadderDecisionSchema = WebrtcLadderDecisionSchema;
+exports.WebrtcSessionDebugSchema = WebrtcSessionDebugSchema;
 exports.WebrtcStreamChoiceSchema = WebrtcStreamChoiceSchema;
 exports.WebrtcStreamTargetSchema = WebrtcStreamTargetSchema;
+exports.WebrtcTierFailureSchema = WebrtcTierFailureSchema;
 exports.WhiteBalanceModeSchema = WhiteBalanceModeSchema;
 exports.WidgetHostEnum = WidgetHostEnum;
 exports.WidgetLoginMethodSchema = WidgetLoginMethodSchema;