@camstack/types 1.2.225 → 1.2.227

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

@@ -1,10 +1,36 @@
 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.
+ *
+ * It is a table rather than two functions computing strings because the three
+ * facts belong together and drifted apart when they did not:
+ *
+ * - 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;
-export declare function getFfmpegArchiveInfo(platform: string): {
-    isArchive: boolean;
-    archiveFormat: 'zip' | 'tar.gz' | 'tar.xz';
-    archiveInnerPath: string;
-};
 /**
  * Ensure an ffmpeg binary WE provide is available on this node, and report
  * which one and what it can do.

package/dist/deps/index.d.ts

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

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;