@camstack/types 1.2.207 → 1.2.208

package/dist/addon.js

@@ -1,5 +1,5 @@
 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_err_msg = require("./err-msg-COpsHMw2.js");
 //#region src/generated/cap-input-defaults.ts

package/dist/addon.mjs

@@ -1,4 +1,4 @@
-import { A as DeviceType, Et as normalizeAddonInitResult, G as ReadinessRegistry, H as nodePin, I as expandCapMethods, K as ReadinessTimeoutError, S as DEVICE_CHILDREN_BATCH_MAX, St as DATAPLANE_SECRET_HEADER, T as describeCustomActions, Tt as BaseAddon, U as readNodePin, Y as scopeKey, a as asJsonObject, b as deviceOpsCapability, d as BOOT_RECOVERY_BACKOFF_MS, f as DEVICE_SCOPED_CAPS, h as createEventBusSliceSource, j as adminUiCapability, kt as emitReadiness, m as createDeviceProxy, p as isDeviceScopedCap, s as asString, t as sleep, u as parseJsonUnknown, wt as DisposerChain, x as viewerUiCapability } from "./sleep-BDR76Ykr.mjs";
+import { A as DeviceType, Et as normalizeAddonInitResult, G as ReadinessRegistry, H as nodePin, I as expandCapMethods, K as ReadinessTimeoutError, S as DEVICE_CHILDREN_BATCH_MAX, St as DATAPLANE_SECRET_HEADER, T as describeCustomActions, Tt as BaseAddon, U as readNodePin, Y as scopeKey, a as asJsonObject, b as deviceOpsCapability, d as BOOT_RECOVERY_BACKOFF_MS, f as DEVICE_SCOPED_CAPS, h as createEventBusSliceSource, j as adminUiCapability, kt as emitReadiness, m as createDeviceProxy, p as isDeviceScopedCap, s as asString, t as sleep, u as parseJsonUnknown, wt as DisposerChain, x as viewerUiCapability } from "./sleep-B1y0Fo1U.mjs";
 import { t as EventCategory } from "./event-category-BVDXG4tB.mjs";
 import { t as errMsg } from "./err-msg-IQTHeDzc.mjs";
 //#region src/generated/cap-input-defaults.ts

package/dist/{canonical-hash-9lydiEzx.js → canonical-hash-CZ2JqJc3.js}

@@ -64,8 +64,41 @@ function buildInputArgs(input, decodeHwAccel) {
 	args.push("-i", input.url);
 	return args;
 }
+/**
+* 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.
+*/
+function resolveStreamMaps(selection) {
+	const graph = selection.filterGraph;
+	if (graph) return {
+		video: `[${graph.videoOutLabel}]`,
+		audio: graph.audioOutLabel ? `[${graph.audioOutLabel}]` : "0:a:0?"
+	};
+	if (selection.extraInputs?.length) return {
+		video: "0:v:0",
+		audio: "0:a:0?"
+	};
+	return {
+		video: null,
+		audio: null
+	};
+}
 /** The `-vf` filter args, or `[]` when a consumer `-vf` already claims the slot. */
-function buildVideoFilterArgs(scale, outputArgs) {
+function buildVideoFilterArgs(scale, outputArgs, filterGraph) {
+	if (filterGraph) {
+		if (scale) throw new Error("FfmpegInvocation: video.scale cannot be combined with a filter graph — scale inside the graph instead (the -vf would feed an output the graph already feeds)");
+		if (outputArgs.some((a) => a === "-vf")) throw new Error("FfmpegInvocation: outputArgs carries a -vf while a filter graph feeds the same output — fold the filter into the graph");
+		return [];
+	}
 	if (!scale) return [];
 	if (outputArgs.some((a) => a === "-vf")) return [];
 	if (scale.mode === "exact") return ["-vf", `scale=${scale.width}:${scale.height}`];
@@ -89,14 +122,17 @@ function buildRateControlArgs(video) {
 	];
 }
 /** The whole video block (`-vf` … `-c:v` … knobs), after `-i`. */
-function buildVideoArgs(video, outputArgs) {
-	if (video.kind === "copy") return [
-		"-c:v",
-		"copy",
-		...video.bitstreamFilter ? ["-bsf:v", video.bitstreamFilter] : []
-	];
+function buildVideoArgs(video, outputArgs, filterGraph) {
+	if (video.kind === "copy") {
+		if (filterGraph) throw new Error("FfmpegInvocation: a filter graph produces a NEW picture, so video.kind must be `encode`");
+		return [
+			"-c:v",
+			"copy",
+			...video.bitstreamFilter ? ["-bsf:v", video.bitstreamFilter] : []
+		];
+	}
 	const args = [
-		...buildVideoFilterArgs(video.scale, outputArgs),
+		...buildVideoFilterArgs(video.scale, outputArgs, filterGraph),
 		"-c:v",
 		video.encoder
 	];
@@ -251,20 +287,39 @@ function buildAudioSidecarArgs(sidecar) {
 *   [<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.
 */
 function buildFfmpegArgs(inv) {
-	const head = [...logBannerArgs(inv.logLevel), ...buildInputArgs(inv.input, inv.decodeHwAccel)];
+	const graph = inv.filterGraph ?? null;
+	const head = [
+		...logBannerArgs(inv.logLevel),
+		...buildInputArgs(inv.input, inv.decodeHwAccel),
+		...(inv.extraInputs ?? []).flatMap((extra) => buildInputArgs(extra, inv.decodeHwAccel)),
+		...graph ? ["-filter_complex", graph.graph] : []
+	];
 	const threadArgs = inv.threadCount > 0 ? ["-threads", String(inv.threadCount)] : [];
+	const maps = resolveStreamMaps(inv);
+	const videoMapArgs = maps.video ? ["-map", maps.video] : [];
+	const audioMapArgs = maps.audio ? ["-map", maps.audio] : [];
 	if (inv.sink.kind === "rtp-outputs") {
 		const videoLeg = inv.sink.video ? [
 			"-an",
 			"-map",
-			"0:v:0",
-			...buildVideoArgs(inv.video, inv.outputArgs),
+			maps.video ?? "0:v:0",
+			...buildVideoArgs(inv.video, inv.outputArgs, graph),
 			...threadArgs,
 			...inv.outputArgs,
 			...buildRtpOutputArgs(inv.sink.video)
@@ -272,7 +327,7 @@ function buildFfmpegArgs(inv) {
 		const audioLeg = inv.sink.audio ? [
 			"-vn",
 			"-map",
-			"0:a:0?",
+			maps.audio ?? "0:a:0?",
 			...buildAudioArgs(inv.audio),
 			...buildRtpOutputArgs(inv.sink.audio)
 		] : [];
@@ -282,15 +337,17 @@ function buildFfmpegArgs(inv) {
 			...audioLeg
 		];
 	}
+	const mutedAudio = isElementaryVideoSink(inv.sink) || inv.audio.kind === "none";
 	const audioArgs = isElementaryVideoSink(inv.sink) ? ["-an"] : buildAudioArgs(inv.audio);
-	const sinkArgs = buildStdoutOrRtspSinkArgs(inv.sink);
 	return [
 		...head,
-		...buildVideoArgs(inv.video, inv.outputArgs),
+		...videoMapArgs,
+		...buildVideoArgs(inv.video, inv.outputArgs, graph),
 		...threadArgs,
+		...mutedAudio ? [] : audioMapArgs,
 		...audioArgs,
 		...inv.outputArgs,
-		...sinkArgs,
+		...buildStdoutOrRtspSinkArgs(inv.sink),
 		...inv.audioSidecar ? buildAudioSidecarArgs(inv.audioSidecar) : []
 	];
 }
@@ -686,3 +743,9 @@ Object.defineProperty(exports, "pickVideoEncoder", {
 		return pickVideoEncoder;
 	}
 });
+Object.defineProperty(exports, "resolveStreamMaps", {
+	enumerable: true,
+	get: function() {
+		return resolveStreamMaps;
+	}
+});

package/dist/{canonical-hash-Ch5bSjFG.mjs → canonical-hash-DBkl8q6V.mjs}

@@ -64,8 +64,41 @@ function buildInputArgs(input, decodeHwAccel) {
 	args.push("-i", input.url);
 	return args;
 }
+/**
+* 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.
+*/
+function resolveStreamMaps(selection) {
+	const graph = selection.filterGraph;
+	if (graph) return {
+		video: `[${graph.videoOutLabel}]`,
+		audio: graph.audioOutLabel ? `[${graph.audioOutLabel}]` : "0:a:0?"
+	};
+	if (selection.extraInputs?.length) return {
+		video: "0:v:0",
+		audio: "0:a:0?"
+	};
+	return {
+		video: null,
+		audio: null
+	};
+}
 /** The `-vf` filter args, or `[]` when a consumer `-vf` already claims the slot. */
-function buildVideoFilterArgs(scale, outputArgs) {
+function buildVideoFilterArgs(scale, outputArgs, filterGraph) {
+	if (filterGraph) {
+		if (scale) throw new Error("FfmpegInvocation: video.scale cannot be combined with a filter graph — scale inside the graph instead (the -vf would feed an output the graph already feeds)");
+		if (outputArgs.some((a) => a === "-vf")) throw new Error("FfmpegInvocation: outputArgs carries a -vf while a filter graph feeds the same output — fold the filter into the graph");
+		return [];
+	}
 	if (!scale) return [];
 	if (outputArgs.some((a) => a === "-vf")) return [];
 	if (scale.mode === "exact") return ["-vf", `scale=${scale.width}:${scale.height}`];
@@ -89,14 +122,17 @@ function buildRateControlArgs(video) {
 	];
 }
 /** The whole video block (`-vf` … `-c:v` … knobs), after `-i`. */
-function buildVideoArgs(video, outputArgs) {
-	if (video.kind === "copy") return [
-		"-c:v",
-		"copy",
-		...video.bitstreamFilter ? ["-bsf:v", video.bitstreamFilter] : []
-	];
+function buildVideoArgs(video, outputArgs, filterGraph) {
+	if (video.kind === "copy") {
+		if (filterGraph) throw new Error("FfmpegInvocation: a filter graph produces a NEW picture, so video.kind must be `encode`");
+		return [
+			"-c:v",
+			"copy",
+			...video.bitstreamFilter ? ["-bsf:v", video.bitstreamFilter] : []
+		];
+	}
 	const args = [
-		...buildVideoFilterArgs(video.scale, outputArgs),
+		...buildVideoFilterArgs(video.scale, outputArgs, filterGraph),
 		"-c:v",
 		video.encoder
 	];
@@ -251,20 +287,39 @@ function buildAudioSidecarArgs(sidecar) {
 *   [<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.
 */
 function buildFfmpegArgs(inv) {
-	const head = [...logBannerArgs(inv.logLevel), ...buildInputArgs(inv.input, inv.decodeHwAccel)];
+	const graph = inv.filterGraph ?? null;
+	const head = [
+		...logBannerArgs(inv.logLevel),
+		...buildInputArgs(inv.input, inv.decodeHwAccel),
+		...(inv.extraInputs ?? []).flatMap((extra) => buildInputArgs(extra, inv.decodeHwAccel)),
+		...graph ? ["-filter_complex", graph.graph] : []
+	];
 	const threadArgs = inv.threadCount > 0 ? ["-threads", String(inv.threadCount)] : [];
+	const maps = resolveStreamMaps(inv);
+	const videoMapArgs = maps.video ? ["-map", maps.video] : [];
+	const audioMapArgs = maps.audio ? ["-map", maps.audio] : [];
 	if (inv.sink.kind === "rtp-outputs") {
 		const videoLeg = inv.sink.video ? [
 			"-an",
 			"-map",
-			"0:v:0",
-			...buildVideoArgs(inv.video, inv.outputArgs),
+			maps.video ?? "0:v:0",
+			...buildVideoArgs(inv.video, inv.outputArgs, graph),
 			...threadArgs,
 			...inv.outputArgs,
 			...buildRtpOutputArgs(inv.sink.video)
@@ -272,7 +327,7 @@ function buildFfmpegArgs(inv) {
 		const audioLeg = inv.sink.audio ? [
 			"-vn",
 			"-map",
-			"0:a:0?",
+			maps.audio ?? "0:a:0?",
 			...buildAudioArgs(inv.audio),
 			...buildRtpOutputArgs(inv.sink.audio)
 		] : [];
@@ -282,15 +337,17 @@ function buildFfmpegArgs(inv) {
 			...audioLeg
 		];
 	}
+	const mutedAudio = isElementaryVideoSink(inv.sink) || inv.audio.kind === "none";
 	const audioArgs = isElementaryVideoSink(inv.sink) ? ["-an"] : buildAudioArgs(inv.audio);
-	const sinkArgs = buildStdoutOrRtspSinkArgs(inv.sink);
 	return [
 		...head,
-		...buildVideoArgs(inv.video, inv.outputArgs),
+		...videoMapArgs,
+		...buildVideoArgs(inv.video, inv.outputArgs, graph),
 		...threadArgs,
+		...mutedAudio ? [] : audioMapArgs,
 		...audioArgs,
 		...inv.outputArgs,
-		...sinkArgs,
+		...buildStdoutOrRtspSinkArgs(inv.sink),
 		...inv.audioSidecar ? buildAudioSidecarArgs(inv.audioSidecar) : []
 	];
 }
@@ -614,4 +671,4 @@ function replaceWithSortedKeys(_key, value) {
 	return value;
 }
 //#endregion
-export { buildAudioArgs as a, buildVideoArgs as c, logBannerArgs as d, pickVideoEncoder as f, audioPlanFromEncodeProfile as i, invocationFromEncodeProfile as l, Fmp4BoxSplitter as n, buildFfmpegArgs as o, AUDIO_PRESETS as r, buildInputArgs as s, canonicalHash as t, isSoftwareDecode as u };
+export { buildAudioArgs as a, buildVideoArgs as c, logBannerArgs as d, pickVideoEncoder as f, audioPlanFromEncodeProfile as i, invocationFromEncodeProfile as l, Fmp4BoxSplitter as n, buildFfmpegArgs as o, resolveStreamMaps as p, AUDIO_PRESETS as r, buildInputArgs as s, canonicalHash as t, isSoftwareDecode as u };

package/dist/capabilities/index.d.ts

@@ -186,7 +186,7 @@ export { type IPowerMeterProvider, type PowerMeterStatus, PowerMeterStatusSchema
 export { type GpsLocation, type IPresenceProvider, type PresenceStatus, PresenceStatusSchema, presenceCapability, } from './presence.cap.js';
 export { type IPressureSensorProvider, type PressureSensorStatus, PressureSensorStatusSchema, pressureSensorCapability, } from './pressure-sensor.cap.js';
 export { type IPrivacyMaskProvider, type PrivacyMaskOptions, PrivacyMaskOptionsSchema, type PrivacyMaskPatch, PrivacyMaskPatchSchema, type PrivacyMaskRegion, PrivacyMaskRegionSchema, type PrivacyMaskShape, PrivacyMaskShapeSchema, type PrivacyMaskStatus, PrivacyMaskStatusSchema, privacyMaskCapability, summarisePrivacyAudio, } from './privacy-mask.cap.js';
-export { type IPtzProvider, PtzMoveCommandSchema, type PtzOptions, PtzOptionsSchema, PtzPositionSchema, PtzPresetSchema, type PtzStatus, PtzStatusSchema, ptzCapability, } from './ptz.cap.js';
+export { type IPtzProvider, type PtzHomePreset, PtzHomePresetSchema, PtzMoveCommandSchema, type PtzOptions, PtzOptionsSchema, PtzPositionSchema, type PtzPreset, type PtzPresetFunction, PtzPresetFunctionSchema, PtzPresetSchema, type PtzStatus, PtzStatusSchema, ptzCapability, } from './ptz.cap.js';
 export { type IPtzAutotrackProvider, type PtzAutotrackRuntimeState, PtzAutotrackRuntimeStateSchema, type PtzAutotrackSettings, PtzAutotrackSettingsSchema, type PtzAutotrackStatus, PtzAutotrackStatusSchema, type PtzAutotrackTargetOption, PtzAutotrackTargetOptionSchema, ptzAutotrackCapability, } from './ptz-autotrack.cap.js';
 export { type IRebootProvider, rebootCapability } from './reboot.cap.js';
 export { type IRecordingProvider, type LocateSegmentResult, LocateSegmentResultSchema, RECORDING_TIMELINE_BATCH_MAX, type ReadGopBytesResult, ReadGopBytesResultSchema, type ReadSegmentBytesResult, ReadSegmentBytesResultSchema, type ReadWindowBytesResult, ReadWindowBytesResultSchema, type RecordingAvailability, type RecordingAvailabilityForDevice, RecordingAvailabilityForDeviceSchema, RecordingAvailabilitySchema, type RecordingDays, type RecordingDaysForDevice, RecordingDaysForDeviceSchema, RecordingDaysSchema, type RecordingDeviceUsage, RecordingDeviceUsageSchema, type RecordingLocationUsage, RecordingLocationUsageSchema, type RecordingManifest, RecordingManifestSchema, RecordingRangeSchema, type RecordingRebalanceInput, RecordingRebalanceInputSchema, type RecordingRebalanceMove, RecordingRebalanceMoveSchema, type RecordingRebalancePlan, RecordingRebalancePlanSchema, type RecordingRebalanceSkip, type RecordingRebalanceSkipReason, RecordingRebalanceSkipReasonSchema, RecordingRebalanceSkipSchema, type RecordingStatus, RecordingStatusSchema, type RecordingStorageUsage, RecordingStorageUsageSchema, recordingCapability, } from './recording.cap.js';

package/dist/capabilities/ptz.cap.d.ts

@@ -1,14 +1,81 @@
 import { z } from 'zod';
 import { type InferProvider } from './capability-definition.js';
 import { DeviceType } from '../device/device-type.js';
+/**
+ * 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.
+ */
+export declare const PtzPresetFunctionSchema: z.ZodEnum<{
+    home: "home";
+    reboot: "reboot";
+    "day-mode": "day-mode";
+    "night-mode": "night-mode";
+    "day-night-auto": "day-night-auto";
+    "set-limits": "set-limits";
+    "save-limits": "save-limits";
+    "osd-menu": "osd-menu";
+}>;
+export type PtzPresetFunction = z.infer<typeof PtzPresetFunctionSchema>;
 declare const PtzPresetSchema: z.ZodObject<{
     id: z.ZodString;
     name: z.ZodString;
+    fn: z.ZodNullable<z.ZodEnum<{
+        home: "home";
+        reboot: "reboot";
+        "day-mode": "day-mode";
+        "night-mode": "night-mode";
+        "day-night-auto": "day-night-auto";
+        "set-limits": "set-limits";
+        "save-limits": "save-limits";
+        "osd-menu": "osd-menu";
+    }>>;
+    writable: z.ZodBoolean;
 }, z.core.$strip>;
+/**
+ * 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.
+ */
 declare const PtzPositionSchema: z.ZodObject<{
-    pan: z.ZodNumber;
-    tilt: z.ZodNumber;
-    zoom: z.ZodNumber;
+    pan: z.ZodNullable<z.ZodNumber>;
+    tilt: z.ZodNullable<z.ZodNumber>;
+    zoom: z.ZodNullable<z.ZodNumber>;
 }, z.core.$strip>;
 declare const PtzMoveCommandSchema: z.ZodObject<{
     pan: z.ZodOptional<z.ZodNumber>;
@@ -20,9 +87,9 @@ declare const PtzMoveCommandSchema: z.ZodObject<{
  *  `getPosition` / `move` still operate on the bare position; the
  *  auto-injected `getStatus` returns this richer block. */
 declare const PtzStatusSchema: z.ZodObject<{
-    pan: z.ZodNumber;
-    tilt: z.ZodNumber;
-    zoom: z.ZodNumber;
+    pan: z.ZodNullable<z.ZodNumber>;
+    tilt: z.ZodNullable<z.ZodNumber>;
+    zoom: z.ZodNullable<z.ZodNumber>;
     autofocus: z.ZodBoolean;
 }, z.core.$strip>;
 /** Per-camera PTZ availability descriptor — drives the UI. */
@@ -33,7 +100,49 @@ declare const PtzOptionsSchema: z.ZodObject<{
     supportsPresets: z.ZodBoolean;
     maxPresets: z.ZodOptional<z.ZodNumber>;
     hasAutofocus: z.ZodBoolean;
+    speedSteps: z.ZodNullable<z.ZodNumber>;
+    moveImpulseMs: z.ZodNullable<z.ZodNumber>;
 }, z.core.$strip>;
+/**
+ * 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.
+ */
+export declare const PtzHomePresetSchema: z.ZodObject<{
+    presetId: z.ZodNullable<z.ZodString>;
+    source: z.ZodEnum<{
+        operator: "operator";
+        none: "none";
+        native: "native";
+        firmware: "firmware";
+    }>;
+}, z.core.$strip>;
+export type PtzHomePreset = z.infer<typeof PtzHomePresetSchema>;
 export declare const ptzCapability: {
     readonly name: "ptz";
     readonly scope: "device";
@@ -73,6 +182,17 @@ export declare const ptzCapability: {
         }, z.core.$strip>, z.ZodArray<z.ZodObject<{
             id: z.ZodString;
             name: z.ZodString;
+            fn: z.ZodNullable<z.ZodEnum<{
+                home: "home";
+                reboot: "reboot";
+                "day-mode": "day-mode";
+                "night-mode": "night-mode";
+                "day-night-auto": "day-night-auto";
+                "set-limits": "set-limits";
+                "save-limits": "save-limits";
+                "osd-menu": "osd-menu";
+            }>>;
+            writable: z.ZodBoolean;
         }, z.core.$strip>>, import("./capability-definition.js").CapabilityMethodKind>;
         readonly goToPreset: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
             deviceId: z.ZodNumber;
@@ -96,10 +216,37 @@ export declare const ptzCapability: {
             supportsPresets: z.ZodBoolean;
             maxPresets: z.ZodOptional<z.ZodNumber>;
             hasAutofocus: z.ZodBoolean;
+            speedSteps: z.ZodNullable<z.ZodNumber>;
+            moveImpulseMs: z.ZodNullable<z.ZodNumber>;
         }, z.core.$strip>, import("./capability-definition.js").CapabilityMethodKind>;
+        /**
+         * 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.
+         */
         readonly goHome: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
             deviceId: z.ZodNumber;
         }, z.core.$strip>, z.ZodVoid, "mutation">;
+        /** Which preset `goHome` targets, and who decided it. */
+        readonly getHomePreset: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            deviceId: z.ZodNumber;
+        }, z.core.$strip>, z.ZodObject<{
+            presetId: z.ZodNullable<z.ZodString>;
+            source: z.ZodEnum<{
+                operator: "operator";
+                none: "none";
+                native: "native";
+                firmware: "firmware";
+            }>;
+        }, z.core.$strip>, import("./capability-definition.js").CapabilityMethodKind>;
+        /**
+         * Pin the home preset for this camera. `null` clears the operator's choice
+         * and falls back to whatever the firmware names, or to `none`.
+         */
+        readonly setHomePreset: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            deviceId: z.ZodNumber;
+            presetId: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>, z.ZodVoid, "mutation">;
         /**
          * Pull the current PTZ position. Redundant with the auto-injected
          * `getStatus` method (see `status` below); kept for callers that
@@ -109,9 +256,9 @@ export declare const ptzCapability: {
         readonly getPosition: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
             deviceId: z.ZodNumber;
         }, z.core.$strip>, z.ZodObject<{
-            pan: z.ZodNumber;
-            tilt: z.ZodNumber;
-            zoom: z.ZodNumber;
+            pan: z.ZodNullable<z.ZodNumber>;
+            tilt: z.ZodNullable<z.ZodNumber>;
+            zoom: z.ZodNullable<z.ZodNumber>;
         }, z.core.$strip>, import("./capability-definition.js").CapabilityMethodKind>;
         /** Toggle the camera's autofocus. Only meaningful when
          *  `getOptions().hasAutofocus` is true. */
@@ -122,15 +269,16 @@ export declare const ptzCapability: {
     };
     readonly status: {
         readonly schema: z.ZodObject<{
-            pan: z.ZodNumber;
-            tilt: z.ZodNumber;
-            zoom: z.ZodNumber;
+            pan: z.ZodNullable<z.ZodNumber>;
+            tilt: z.ZodNullable<z.ZodNumber>;
+            zoom: z.ZodNullable<z.ZodNumber>;
             autofocus: z.ZodBoolean;
         }, z.core.$strip>;
         readonly kind: "command-driven";
     };
 };
 export type IPtzProvider = InferProvider<typeof ptzCapability>;
+export type PtzPreset = z.infer<typeof PtzPresetSchema>;
 export type PtzOptions = z.infer<typeof PtzOptionsSchema>;
 export type PtzStatus = z.infer<typeof PtzStatusSchema>;
 export { PtzPresetSchema, PtzPositionSchema, PtzStatusSchema, PtzMoveCommandSchema, PtzOptionsSchema, };