@camstack/types 1.2.206 → 1.2.208

package/dist/ffmpeg/invocation.d.ts

@@ -234,6 +234,34 @@ export interface FfmpegAudioSidecar {
     readonly rtpUrl: string;
     readonly sdpFile: string;
 }
+/**
+ * An explicit `-filter_complex` graph, for an invocation that combines MORE
+ * THAN ONE input into one output — a composite/grid camera being the case this
+ * exists for: N decodes, one composition, ONE encode, inside ONE child. Frames
+ * never cross a process boundary at frame-rate (D9/D18), so the composition
+ * has to happen where the decodes already are.
+ *
+ * The graph text is the caller's — the builder does not compose, parse or
+ * validate it. What the builder owns is the consequence: a graph names its
+ * OUTPUT PADS, and those pads are what `-map` selects. Declaring the labels
+ * here is what lets the `-map` be DERIVED instead of hardcoded.
+ *
+ * Input pads are addressed by the input's ORDINAL: `[0:v]` is
+ * {@link FfmpegInvocation.input}, `[1:v]` is `extraInputs[0]`, and so on, in
+ * the order the builder emits them.
+ */
+export interface FfmpegFilterGraph {
+    /** The `-filter_complex` value, verbatim. */
+    readonly graph: string;
+    /** The graph's VIDEO output pad label, without brackets (e.g. `grid`). */
+    readonly videoOutLabel: string;
+    /**
+     * The graph's AUDIO output pad label, without brackets. Absent / `null` ⇒
+     * the graph produces no audio and the audio plane is mapped from input 0
+     * (`0:a:0?`) like any single-input invocation.
+     */
+    readonly audioOutLabel?: string | null;
+}
 export interface FfmpegInvocation {
     readonly logLevel: 'error' | 'warning' | 'info';
     /**
@@ -244,6 +272,21 @@ export interface FfmpegInvocation {
      */
     readonly decodeHwAccel: string | null;
     readonly input: FfmpegInputPlan;
+    /**
+     * Inputs 1..N-1, emitted after {@link input} in this order, each with its own
+     * complete input block (`-hwaccel` included — it is per-input, and an option
+     * that lands after ITS `-i` is accepted, ignored, and silently software).
+     *
+     * Absent or empty ⇒ the single-input invocation every existing call site
+     * builds, argv unchanged.
+     */
+    readonly extraInputs?: readonly FfmpegInputPlan[];
+    /**
+     * The composition, when there is one. Present ⇒ `-filter_complex` is emitted
+     * after the last `-i` and the output `-map`s are taken from its declared
+     * pads. See {@link FfmpegFilterGraph}.
+     */
+    readonly filterGraph?: FfmpegFilterGraph | null;
     readonly video: FfmpegVideoPlan;
     readonly audio: FfmpegAudioPlan;
     /** `0` = auto (omit `-threads` and let ffmpeg decide). */
@@ -262,8 +305,35 @@ export declare function isSoftwareDecode(decodeHwAccel: string | null): boolean;
  * appended to this list by a caller — that is the whole point of the function.
  */
 export declare function buildInputArgs(input: FfmpegInputPlan, decodeHwAccel: string | null): string[];
+/**
+ * Which stream each output plane is fed from.
+ *
+ * `null` means **emit no `-map` at all** and let ffmpeg select — which is what
+ * a single-input invocation has always done, and the only shape that keeps the
+ * shipped argv byte-identical. It is never a synonym for "input 0".
+ */
+export interface FfmpegStreamMaps {
+    readonly video: string | null;
+    readonly audio: string | null;
+}
+/** The facts a map derives from: how many inputs there are, and the graph. */
+export type FfmpegStreamSelection = Pick<FfmpegInvocation, 'extraInputs' | 'filterGraph'>;
+/**
+ * Derive the output `-map` selectors. The three cases, in the order they are
+ * decided:
+ *
+ * 1. **A filter graph** — the picture is the graph's declared video pad, and
+ *    the audio is its audio pad when it has one, otherwise input 0's mic. A
+ *    graph's output is not addressable any other way.
+ * 2. **N inputs, no graph** — map input 0 EXPLICITLY. ffmpeg's own selection
+ *    picks the "best" stream across ALL inputs, so the egress would silently
+ *    become whichever camera happens to have the largest frame.
+ * 3. **One input, no graph** — no `-map`. Anything else would change the argv
+ *    of every call site that exists today for no gain.
+ */
+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[]): string[];
+export declare function buildVideoArgs(video: FfmpegVideoPlan, outputArgs: readonly string[], filterGraph?: FfmpegFilterGraph | null): string[];
 /** The whole audio block, after `-i`. */
 export declare function buildAudioArgs(audio: FfmpegAudioPlan): string[];
 /**
@@ -274,10 +344,20 @@ export declare function buildAudioArgs(audio: FfmpegAudioPlan): string[];
  *   [<input.extraArgs>]               │
  *   [-fflags <flag>…]                 │
  *   [-rtsp_transport tcp]             │
- *   -i <url>                         ─┘
- *   <video block>  <threads>  <audio block>   ─┐ OUTPUT options.
+ *   -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[];
 /**

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

@@ -6666,6 +6666,20 @@ export type AppRouter = TrpcCoreRouter<{
             output: z.infer<typeof ptzCapability.methods.goHome.output>;
             meta: object;
         }>;
+        getHomePreset: TRPCQueryProcedure<{
+            input: {
+                [x: string]: unknown;
+            } & z.input<typeof ptzCapability.methods.getHomePreset.input>;
+            output: z.infer<typeof ptzCapability.methods.getHomePreset.output>;
+            meta: object;
+        }>;
+        setHomePreset: TRPCMutationProcedure<{
+            input: {
+                [x: string]: unknown;
+            } & z.input<typeof ptzCapability.methods.setHomePreset.input>;
+            output: z.infer<typeof ptzCapability.methods.setHomePreset.output>;
+            meta: object;
+        }>;
         getPosition: TRPCQueryProcedure<{
             input: {
                 [x: string]: unknown;

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: 1048 method paths across 130 capabilities.
+ * Coverage: 1050 method paths across 130 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: 380 methods carry a device reference, of which
+ * Coverage: 382 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-DqtlfkSS.js");
+const require_sleep = require("./sleep-BAAUFDCk.js");
 const require_event_category = require("./event-category-BVfsrBYA.js");
-const require_canonical_hash = require("./canonical-hash-9lydiEzx.js");
+const require_canonical_hash = require("./canonical-hash-CZ2JqJc3.js");
 const require_enums = require("./enums.js");
 const require_err_msg = require("./err-msg-COpsHMw2.js");
 let zod = require("zod");
@@ -8893,7 +8893,7 @@ var streamBrokerCapability = {
 		*  - the signal is ENABLED for this camera (the operator's per-camera
 		*    choice — a camera may declare a signal the operator does not want
 		*    waking anything), and
-		*  - a consumer is actually attached and waiting on the prestream. Waking
+		*  - a consumer is actually attached and waiting on the sentry. Waking
 		*    a camera nobody is watching is the one thing a battery camera must
 		*    never do, and a signal arriving with no consumer is exactly that.
 		*
@@ -34875,14 +34875,81 @@ function summarisePrivacyAudio(profiles) {
 }
 //#endregion
 //#region src/capabilities/ptz.cap.ts
+/**
+* What a preset id DOES on this camera.
+*
+* On several PTZ firmwares the preset namespace is shared: low ids are stored
+* positions, a reserved band triggers camera FUNCTIONS. The dispensa camera
+* (Hikvision) returns its own reserved band in the preset list, named by the
+* firmware:
+*
+*   34 Back to origin · 39 Day mode · 40 Night mode · 46 Day/Night Auto Mode
+*   92 Set manual limits · 93 Save manual limits · 94 Remote reboot
+*   95 Call OSD menu
+*
+* We used to hand all of these to the UI as ordinary presets. Saving over one
+* is what produced `PUT /ISAPI/PTZCtrl/channels/1/presets/34 -> HTTP 500`: the
+* camera refusing to let "Back to origin" be overwritten, surfaced to the
+* operator as a transport failure.
+*
+* A function preset stays fully usable as a DESTINATION -- `goToPreset('34')`
+* is the single most useful thing that camera can do. Only `savePreset` and
+* `deletePreset` are gated.
+*/
+var PtzPresetFunctionSchema = zod.z.enum([
+	"home",
+	"day-mode",
+	"night-mode",
+	"day-night-auto",
+	"set-limits",
+	"save-limits",
+	"reboot",
+	"osd-menu"
+]);
 var PtzPresetSchema = zod.z.object({
 	id: zod.z.string(),
-	name: zod.z.string()
+	name: zod.z.string(),
+	/**
+	* The firmware function this id performs, when the provider KNOWS the id is
+	* reserved. `null` = an ordinary stored position, OR a reserved id this
+	* provider does not recognise -- the two are told apart by `writable`.
+	*/
+	fn: PtzPresetFunctionSchema.nullable(),
+	/**
+	* Whether `savePreset` / `deletePreset` may target this id. A provider sets
+	* it false only for a band it KNOWS is reserved; where the firmware is not
+	* documented it stays true and a refusal comes from the camera, named.
+	*/
+	writable: zod.z.boolean()
 });
+/**
+* Where the head is pointing -- per axis, and `null` when the driver cannot
+* read it.
+*
+* It used to be three REQUIRED numbers, which left a provider that cannot read
+* position no way to say so. All four said `0`:
+*
+*   reolink   `return { pan: 0, tilt: 0, zoom: 0 }`  "until a position-query
+*                                                     path lands upstream"
+*   hikvision stub, "firmware-dependent and frequently absent"
+*   amcrest   stub, "no generic absolute-position read for this model family"
+*   onvif     throws
+*
+* So every consumer asking where a camera points was told "perfectly centred"
+* by four cameras that had never looked. That is D393 -- a measurement that
+* FAILED is `null`, never `0`, and the type says so all the way to the
+* decision -- the same shape as the unreadable `statfs` folded into "0 bytes of
+* headroom", which evacuated a healthy disk.
+*
+* D393 also says to check for a narrower structural TWIN of the result type.
+* There is one: `PtzStatusSchema` extends this, so the lie had already
+* propagated into `getStatus`, which is the surface `getPosition`'s own comment
+* tells callers to migrate to.
+*/
 var PtzPositionSchema = zod.z.object({
-	pan: zod.z.number(),
-	tilt: zod.z.number(),
-	zoom: zod.z.number()
+	pan: zod.z.number().nullable(),
+	tilt: zod.z.number().nullable(),
+	zoom: zod.z.number().nullable()
 });
 var PtzMoveCommandSchema = zod.z.object({
 	pan: zod.z.number().optional(),
@@ -34904,7 +34971,72 @@ var PtzOptionsSchema = zod.z.object({
 	maxPresets: zod.z.number().optional(),
 	/** Whether the camera exposes a controllable autofocus toggle
 	*  (boolean `hasX` per the getOptions availability convention). */
-	hasAutofocus: zod.z.boolean()
+	hasAutofocus: zod.z.boolean(),
+	/**
+	* How many distinct speeds this camera's NATIVE scale offers.
+	*
+	* The cap's `speed` is normalized 0..1 and each provider maps it down --
+	* Baichuan 1..63, Dahua 1..8, ISAPI's percentage -100..100. The normalized
+	* value hides how coarse that really is: asking an amcrest for `0.37` is
+	* meaningless, because it has eight steps and three of them round to the
+	* same one. A loop that tunes its own gain has to know the granularity of
+	* the knob it is turning.
+	*
+	* `null` = the driver does not know, or the scale is continuous (ONVIF takes
+	* a float). Never a made-up number.
+	*/
+	speedSteps: zod.z.number().int().positive().nullable(),
+	/**
+	* How long ONE `move` pulse runs on this driver, ms.
+	*
+	* `move` is a self-terminating burst everywhere, but every provider hardcoded
+	* its own duration in private -- 200 reolink, 350 amcrest, 500 hikvision,
+	* 1000 onvif -- so no caller could read it. It is the DENOMINATOR of "how far
+	* did the head travel per pulse": without it a measured displacement has no
+	* gain to be divided into.
+	*
+	* `null` = the driver cannot say.
+	*/
+	moveImpulseMs: zod.z.number().int().positive().nullable()
+});
+/**
+* Which preset `goHome` goes to, and WHO decided.
+*
+* `goHome` used to be three vendor "conventions" written in three comments --
+* Reolink preset 0, Hikvision preset '1', Dahua preset 1 -- and on this fleet
+* not one of the three cameras honours its own:
+*
+*   592  Videocamera camera Daniel (reolink)   preset 0 holds "stanza"
+*   1438 Videocamera dispensa (hikvision)      preset 1 holds "Credenza"
+*   3836 Videocamera studio (amcrest)          preset 1 holds "Preset1"
+*
+* So `goHome` meant "go wherever the operator happened to save in slot 0 or 1",
+* and two of the three swallowed the failure in a bare `catch`. For autotrack
+* this is the HOTTEST path -- it runs every time a subject is released -- so it
+* needs an answer that is true per camera and audible when it is missing.
+*
+* `source` is what makes it honest:
+*   - `operator` -- picked in the UI, stored by the provider.
+*   - `firmware` -- the camera itself named a preset `fn: 'home'` (Hikvision's
+*     "Back to origin"), adopted as the default with nothing to configure.
+*   - `native`   -- the driver homes WITHOUT a preset at all. ONVIF does:
+*     `goHome` is `ptzAbsoluteMove({x:0, y:0, zoom:0})`. `presetId` is null and
+*     that is not a failure -- there is nothing to pick, and the UI must offer
+*     no picker.
+*   - `none`     -- nothing is configured and the camera names nothing.
+*     `goHome` REFUSES rather than moving the head somewhere arbitrary.
+*
+* `source === 'none'` is the refusal condition, NOT `presetId === null`: the
+* native case has no preset and homes perfectly well.
+*/
+var PtzHomePresetSchema = zod.z.object({
+	presetId: zod.z.string().nullable(),
+	source: zod.z.enum([
+		"operator",
+		"firmware",
+		"native",
+		"none"
+	])
 });
 var ptzCapability = {
 	name: "ptz",
@@ -34945,7 +35077,25 @@ var ptzCapability = {
 			auth: "admin"
 		}),
 		getOptions: require_sleep.method(zod.z.object({ deviceId: zod.z.number() }), PtzOptionsSchema),
+		/**
+		* Move to the camera's configured home preset. THROWS when
+		* `getHomePreset()` resolves to `none` -- a head that did not move must
+		* never look like a head that went home.
+		*/
 		goHome: require_sleep.method(zod.z.object({ deviceId: zod.z.number() }), zod.z.void(), { kind: "mutation" }),
+		/** Which preset `goHome` targets, and who decided it. */
+		getHomePreset: require_sleep.method(zod.z.object({ deviceId: zod.z.number() }), PtzHomePresetSchema),
+		/**
+		* Pin the home preset for this camera. `null` clears the operator's choice
+		* and falls back to whatever the firmware names, or to `none`.
+		*/
+		setHomePreset: require_sleep.method(zod.z.object({
+			deviceId: zod.z.number(),
+			presetId: zod.z.string().nullable()
+		}), zod.z.void(), {
+			kind: "mutation",
+			auth: "admin"
+		}),
 		/**
 		* Pull the current PTZ position. Redundant with the auto-injected
 		* `getStatus` method (see `status` below); kept for callers that
@@ -48226,6 +48376,12 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "delete"
 	},
+	"ptz.getHomePreset": {
+		capName: "ptz",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
 	"ptz.getOptions": {
 		capName: "ptz",
 		capScope: "device",
@@ -48274,6 +48430,12 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"ptz.setHomePreset": {
+		capName: "ptz",
+		capScope: "device",
+		addonId: null,
+		access: "create"
+	},
 	"ptz.stop": {
 		capName: "ptz",
 		capScope: "device",
@@ -51718,6 +51880,11 @@ var METHOD_DEVICE_SELECTORS = Object.freeze({
 		form: "single",
 		optional: false
 	}],
+	"ptz.getHomePreset": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
 	"ptz.getOptions": [{
 		name: "deviceId",
 		form: "single",
@@ -51758,6 +51925,11 @@ var METHOD_DEVICE_SELECTORS = Object.freeze({
 		form: "single",
 		optional: false
 	}],
+	"ptz.setHomePreset": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
 	"ptz.stop": [{
 		name: "deviceId",
 		form: "single",
@@ -58384,9 +58556,11 @@ exports.PtzAutotrackRuntimeStateSchema = PtzAutotrackRuntimeStateSchema;
 exports.PtzAutotrackSettingsSchema = PtzAutotrackSettingsSchema;
 exports.PtzAutotrackStatusSchema = PtzAutotrackStatusSchema;
 exports.PtzAutotrackTargetOptionSchema = PtzAutotrackTargetOptionSchema;
+exports.PtzHomePresetSchema = PtzHomePresetSchema;
 exports.PtzMoveCommandSchema = PtzMoveCommandSchema;
 exports.PtzOptionsSchema = PtzOptionsSchema;
 exports.PtzPositionSchema = PtzPositionSchema;
+exports.PtzPresetFunctionSchema = PtzPresetFunctionSchema;
 exports.PtzPresetSchema = PtzPresetSchema;
 exports.PtzStatusSchema = PtzStatusSchema;
 exports.QueryFilterSchema = QueryFilterSchema;
@@ -59107,6 +59281,7 @@ exports.resolveMutate = resolveMutate;
 exports.resolvePoolMemoryPolicy = resolvePoolMemoryPolicy;
 exports.resolveRecordingProfiles = resolveRecordingProfiles;
 exports.resolveRunnerId = resolveRunnerId;
+exports.resolveStreamMaps = require_canonical_hash.resolveStreamMaps;
 exports.resolveVariantModelId = resolveVariantModelId;
 exports.resolveViewableDeviceIds = resolveViewableDeviceIds;
 exports.roleSpec = roleSpec;