@camstack/system 1.2.256 → 1.2.258

package/dist/builtins/autotrack/autotrack-cameras.d.ts

@@ -1,9 +1,33 @@
 import { FirstLevelMacroClass, PtzAutotrackSettings, PtzAutotrackStatus } from '@camstack/types';
 import { AutotrackLoopConfig } from './autotrack-config.js';
+/**
+ * How much of the frame the subject SHOULD occupy, and nothing else about zoom.
+ *
+ * Hidden on purpose (operator, 2026-09-18: *"rendiamo lo zoom configurabile,
+ * nascosto per ora, ci lavoriamo poi quando ne vedo il bisogno"*). It is not in
+ * `PtzAutotrackSettings` — that schema is the cross-vendor surface the device
+ * page renders, and putting it there would SHOW a control nothing implements.
+ * It lives in this addon's own record instead: settable, persisted, invisible.
+ *
+ * `null` means the loop does not touch zoom at all, which is what every camera
+ * gets until somebody decides otherwise.
+ */
+export interface AutotrackZoomSetting {
+    /**
+     * Target share of the frame for the tracked subject's box, `0..1`.
+     *
+     * The operator's original ask was "keep the target at about 50% of frame",
+     * so 0.5 is the number this exists to hold. It is a FRACTION OF AREA on the
+     * frame the loop measures in, not a zoom level: the loop is declaredly
+     * visual and never learns where the optics are (D520).
+     */
+    readonly targetSubjectFraction: number | null;
+}
 /** One camera's record. */
 export interface AutotrackCameraRecord {
     readonly enabled: boolean;
     readonly settings: PtzAutotrackSettings;
+    readonly zoom: AutotrackZoomSetting;
 }
 /** deviceId → record. */
 export type AutotrackCameraRecords = Readonly<Record<number, AutotrackCameraRecord>>;
@@ -25,18 +49,20 @@ export declare const DEFAULT_CAMERA_RECORD: AutotrackCameraRecord;
  */
 export declare const EMULATED_TARGET_OPTIONS: PtzAutotrackStatus['supportedTargetTypes'];
 /**
- * Read the persisted blob.
+ * Why this camera's zoom request is not being honoured, or `null` when it asked
+ * for nothing.
  *
- * A malformed ENTRY falls back to the defaults and keeps its `enabled` flag —
- * it is never dropped. Dropping it would disarm a function the operator armed,
- * which is the one direction this must not fail in; a camera that is not in
- * the blob at all is simply a camera nobody has switched on.
+ * A setting that is read and ignored in silence is indistinguishable from a
+ * broken one, and this one WILL be read by a loop that cannot act on it yet.
+ * So asking for it produces a sentence naming the number and what is missing.
  */
+export declare function zoomRefusalFor(record: AutotrackCameraRecord): string | null;
 export declare function parseCameraRecords(raw: unknown): AutotrackCameraRecords;
 /** Immutable per-camera patch — a NEW map, the previous one untouched. */
 export declare function withCameraPatch(records: AutotrackCameraRecords, deviceId: number, patch: {
     enabled?: boolean;
     settings?: Partial<PtzAutotrackSettings>;
+    zoom?: Partial<AutotrackZoomSetting>;
 }): AutotrackCameraRecords;
 /**
  * The detection macro class this camera follows.

package/dist/builtins/autotrack/index.js

@@ -52,7 +52,8 @@ var DEFAULT_CAMERA_RECORD = {
 		targetType: "",
 		stopDelaySeconds: 30,
 		disappearDelaySeconds: DEFAULT_AUTOTRACK_LOOP_CONFIG.disappearDelayMs / 1e3
-	}
+	},
+	zoom: { targetSubjectFraction: null }
 };
 /**
 * What this implementation can follow, as the cap's target options.
@@ -88,6 +89,32 @@ function parseSettings(raw) {
 * which is the one direction this must not fail in; a camera that is not in
 * the blob at all is simply a camera nobody has switched on.
 */
+/**
+* Read the hidden zoom setting.
+*
+* Out-of-range is CLAMPED into the unit interval rather than carried: a control
+* loop that eventually reads this must never be handed a 4, and a silently
+* dropped value would look like "the operator never set it".
+*/
+function parseZoom(raw) {
+	if (!isRecordObject(raw)) return { targetSubjectFraction: null };
+	const value = raw["targetSubjectFraction"];
+	if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) return { targetSubjectFraction: null };
+	return { targetSubjectFraction: Math.min(1, value) };
+}
+/**
+* Why this camera's zoom request is not being honoured, or `null` when it asked
+* for nothing.
+*
+* A setting that is read and ignored in silence is indistinguishable from a
+* broken one, and this one WILL be read by a loop that cannot act on it yet.
+* So asking for it produces a sentence naming the number and what is missing.
+*/
+function zoomRefusalFor(record) {
+	const target = record.zoom.targetSubjectFraction;
+	if (target === null) return null;
+	return `autotrack zoom is configured (target subject fraction ${String(target)}) but NOT IMPLEMENTED: the loop drives pan and tilt only. Subject-size control needs a third axis with its own dead band, a rule that it may act only while pan/tilt are settled, and the two D520 measurements first — a stale error costs more the further the optics are zoomed in.`;
+}
 function parseCameraRecords(raw) {
 	if (!isRecordObject(raw)) return {};
 	const out = {};
@@ -97,7 +124,8 @@ function parseCameraRecords(raw) {
 		if (!isRecordObject(value)) continue;
 		out[deviceId] = {
 			enabled: value["enabled"] === true,
-			settings: parseSettings(value["settings"])
+			settings: parseSettings(value["settings"]),
+			zoom: parseZoom(value["zoom"])
 		};
 	}
 	return out;
@@ -112,6 +140,10 @@ function withCameraPatch(records, deviceId, patch) {
 			settings: {
 				...current.settings,
 				...patch.settings
+			},
+			zoom: {
+				...current.zoom,
+				...patch.zoom
 			}
 		}
 	};
@@ -921,6 +953,11 @@ var AutotrackAddon = class extends require_dist.BaseAddon {
 			}
 		});
 		this.ctx.logger.warn("autotrack ON: this camera must not be driven by anyone else", { tags: { deviceId } });
+		const zoomRefusal = zoomRefusalFor(record);
+		if (zoomRefusal !== null) this.ctx.logger.warn(zoomRefusal, {
+			tags: { deviceId },
+			meta: { targetSubjectFraction: record.zoom.targetSubjectFraction }
+		});
 	}
 	stopSession(deviceId, reason) {
 		const session = this.sessions.get(deviceId);

package/dist/builtins/autotrack/index.mjs

@@ -47,7 +47,8 @@ var DEFAULT_CAMERA_RECORD = {
 		targetType: "",
 		stopDelaySeconds: 30,
 		disappearDelaySeconds: DEFAULT_AUTOTRACK_LOOP_CONFIG.disappearDelayMs / 1e3
-	}
+	},
+	zoom: { targetSubjectFraction: null }
 };
 /**
 * What this implementation can follow, as the cap's target options.
@@ -83,6 +84,32 @@ function parseSettings(raw) {
 * which is the one direction this must not fail in; a camera that is not in
 * the blob at all is simply a camera nobody has switched on.
 */
+/**
+* Read the hidden zoom setting.
+*
+* Out-of-range is CLAMPED into the unit interval rather than carried: a control
+* loop that eventually reads this must never be handed a 4, and a silently
+* dropped value would look like "the operator never set it".
+*/
+function parseZoom(raw) {
+	if (!isRecordObject(raw)) return { targetSubjectFraction: null };
+	const value = raw["targetSubjectFraction"];
+	if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) return { targetSubjectFraction: null };
+	return { targetSubjectFraction: Math.min(1, value) };
+}
+/**
+* Why this camera's zoom request is not being honoured, or `null` when it asked
+* for nothing.
+*
+* A setting that is read and ignored in silence is indistinguishable from a
+* broken one, and this one WILL be read by a loop that cannot act on it yet.
+* So asking for it produces a sentence naming the number and what is missing.
+*/
+function zoomRefusalFor(record) {
+	const target = record.zoom.targetSubjectFraction;
+	if (target === null) return null;
+	return `autotrack zoom is configured (target subject fraction ${String(target)}) but NOT IMPLEMENTED: the loop drives pan and tilt only. Subject-size control needs a third axis with its own dead band, a rule that it may act only while pan/tilt are settled, and the two D520 measurements first — a stale error costs more the further the optics are zoomed in.`;
+}
 function parseCameraRecords(raw) {
 	if (!isRecordObject(raw)) return {};
 	const out = {};
@@ -92,7 +119,8 @@ function parseCameraRecords(raw) {
 		if (!isRecordObject(value)) continue;
 		out[deviceId] = {
 			enabled: value["enabled"] === true,
-			settings: parseSettings(value["settings"])
+			settings: parseSettings(value["settings"]),
+			zoom: parseZoom(value["zoom"])
 		};
 	}
 	return out;
@@ -107,6 +135,10 @@ function withCameraPatch(records, deviceId, patch) {
 			settings: {
 				...current.settings,
 				...patch.settings
+			},
+			zoom: {
+				...current.zoom,
+				...patch.zoom
 			}
 		}
 	};
@@ -916,6 +948,11 @@ var AutotrackAddon = class extends BaseAddon {
 			}
 		});
 		this.ctx.logger.warn("autotrack ON: this camera must not be driven by anyone else", { tags: { deviceId } });
+		const zoomRefusal = zoomRefusalFor(record);
+		if (zoomRefusal !== null) this.ctx.logger.warn(zoomRefusal, {
+			tags: { deviceId },
+			meta: { targetSubjectFraction: record.zoom.targetSubjectFraction }
+		});
 	}
 	stopSession(deviceId, reason) {
 		const session = this.sessions.get(deviceId);

package/dist/builtins/camera-grid/index.js

@@ -1588,7 +1588,7 @@ function inputPlanFor(source) {
 	return {
 		url: source.url,
 		rtspTransport: "tcp",
-		fflags: ["+discardcorrupt+nobuffer"],
+		fflags: ["+discardcorrupt"],
 		lowDelay: true,
 		analyzeDurationUs: ANALYZE_DURATION_US,
 		probeSizeBytes: PROBE_SIZE_BYTES

package/dist/builtins/camera-grid/index.mjs

@@ -1583,7 +1583,7 @@ function inputPlanFor(source) {
 	return {
 		url: source.url,
 		rtspTransport: "tcp",
-		fflags: ["+discardcorrupt+nobuffer"],
+		fflags: ["+discardcorrupt"],
 		lowDelay: true,
 		analyzeDurationUs: ANALYZE_DURATION_US,
 		probeSizeBytes: PROBE_SIZE_BYTES

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/system",
-  "version": "1.2.256",
+  "version": "1.2.258",
   "description": "Core addon for CamStack — builtins, pipeline, process management, auth, logging, events",
   "keywords": [
     "camstack",