@camstack/addon-provider-hikvision 1.2.12 → 1.2.13

package/dist/addon.mjs

@@ -6469,7 +6469,20 @@ var BrokerStatsSchema = object({
 		sampleRate: number(),
 		channels: number(),
 		supported: boolean()
-	}).nullable().optional()
+	}).nullable().optional(),
+	/**
+	* BROKER-SIDE AUDIO MUTE (D83). `true` = this broker is deliberately
+	* distributing none of the device's audio, on live or recording.
+	*
+	* Present so a silent camera can be told apart from a broken one on the
+	* stream panel itself, without cross-referencing the switch group: a
+	* broker holding an `audio` track descriptor while `audioMuted` is true is
+	* working exactly as asked. `audioMutedDropped` counts the audio units
+	* thrown away since the current dial — it is how you confirm from stats
+	* alone that the mute is on the packet path and not merely persisted.
+	*/
+	audioMuted: boolean().optional(),
+	audioMutedDropped: number().optional()
 });
 /**
 * Exporter-facing "profile restream" entry. Returned by
@@ -7102,6 +7115,19 @@ object({
 * | `notifications` | `notificationRules.setDeviceMuted` | `NotificationCenter.evaluateAndEnqueue` returns before any rule is evaluated |
 * | `privacy-mask` | `privacyMask.setMask({ enabled })` → the CAMERA | the camera blanks the masked regions itself; every stream and recording carries the black boxes |
 * | `device-audio` | `privacyMask.setAudioEnabled` → the CAMERA | the camera stops encoding an audio track at all; every consumer sees silent video |
+* | `broker-audio` | `streamBroker.setDeviceAudioMute` → `DeviceOverride.audioMuted` | `StreamBroker.setAudioMuted` drops the audio plane at the source: no `type:'audio'` packet leaves `fanOutEncoded`, no RTP reaches the restreamer, and the restreamer serves the video-only SDP |
+*
+* ## `device-audio` and `broker-audio` are two functions, not two knobs
+*
+* They look adjacent and they are not the same control ([D83](../../../../docs/decisions/adr-0083.md)):
+* `device-audio` writes the CAMERA, so it is hardware privacy — the microphone
+* genuinely stops, it survives CamStack entirely, and it costs a multi-second
+* encoder restart on every flip. `broker-audio` writes THIS server, so it is
+* instant, vendor-independent and reversible without touching the camera, and
+* a camera that ignores or lacks the ISAPI/Reolink control is still silenced.
+* D62 forbids a second switch that *disagrees* with the first; these two
+* cannot disagree, because neither reads the other's store — the camera holds
+* one, the broker holds the other, and each reports its own fact.
 *
 * ## The two switches whose authority is not on this server
 *
@@ -7163,6 +7189,7 @@ var CameraSwitchIdSchema = _enum([
 	"object-detection",
 	"privacy-mask",
 	"device-audio",
+	"broker-audio",
 	"audio-analysis",
 	"recording",
 	"notifications"
@@ -7188,7 +7215,8 @@ var CameraSwitchAuthoritySchema = discriminatedUnion("kind", [
 	object({
 		kind: literal("camera-mask"),
 		capName: string()
-	})
+	}),
+	object({ kind: literal("broker-audio-mute") })
 ]);
 /**
 * Why a switch is not offered for this camera. Rendered instead of the
@@ -9560,7 +9588,25 @@ method(object({
 }), _void(), {
 	kind: "mutation",
 	auth: "admin"
-}), method(object({ brokerId: string() }), boolean()), object({
+}), method(object({ brokerId: string() }), boolean()), method(object({ deviceId: number().int() }), object({
+	muted: boolean(),
+	/**
+	* How many live non-derived brokers currently hold the mute. Purely
+	* diagnostic: `muted` is the policy and is authoritative on its own
+	* (it applies to brokers that do not exist yet), while this says
+	* whether anything is presently being silenced.
+	*/
+	appliedBrokers: number().int().nonnegative()
+})), method(object({
+	deviceId: number().int(),
+	muted: boolean()
+}), object({
+	muted: boolean(),
+	appliedBrokers: number().int().nonnegative()
+}), {
+	kind: "mutation",
+	auth: "admin"
+}), object({
 	deviceId: number().int().nonnegative(),
 	camStreamId: string(),
 	profile: CamProfileSchema
@@ -15092,6 +15138,30 @@ var TrackSourceSchema = _enum([
 	"audio"
 ]);
 /**
+* Where a track sits in the RETRAIN lifecycle (D81).
+*
+*  - `none` — never marked, or un-marked. Evictable.
+*  - `staging` — the operator wants this track as training material and has not
+*    finished with it. **This is the only state retention holds**: the track and
+*    everything it owns (object events, crops, keyframes, CLIP vector) survive
+*    the device's age window.
+*  - `trained` — the retrain page has taken what it needed. The frames it chose
+*    were COPIED into the retrain dataset at selection time, so the dataset no
+*    longer depends on the track's media and the track becomes EVICTABLE again.
+*    Terminal for the plain `markForTrain` toggle: returning it to `staging` is
+*    a deliberate action of the retrain page, not a side effect of a checkbox.
+*
+* There is no `null`. The state is stored `TEXT NOT NULL DEFAULT 'none'` because
+* the store's filter language has only positive equality and `whereIn` — no
+* negation, no IS NULL — so a NULL would be unselectable by ANY predicate and
+* would make the entire pre-column history immortal in one deploy.
+*/
+var RetrainStatusSchema = _enum([
+	"none",
+	"staging",
+	"trained"
+]);
+/**
 * Per-track OPERATOR flags — set by hand from the admin UI or the viewer, never
 * by the pipeline. Spread into `TrackSchema` and `KeyEventSchema` from one place
 * so the two surfaces cannot drift.
@@ -15101,18 +15171,31 @@ var TrackSourceSchema = _enum([
 * columns existed read as absent, and a consumer that needs a boolean should say
 * `flag === true`, not `flag !== false`.
 *
-* What the flags DO is deliberately UNDEFINED at the time of writing: they are
-* operator curation, and the behaviour they drive will be specified separately.
-* In particular a `markForTrain` track is NOT pinned against retention — see
-* `docs/decisions/adr-0059.md` for why that is a store-level change, not a flag.
+* `markForTrain` is the WIRE FACE of {@link RetrainStatusSchema}, not a column:
+* it is exactly `retrainStatus === 'staging'`, in both directions. Writing
+* `true` moves `none → staging`, writing `false` moves `staging → none`, and a
+* `trained` track reports `false` while refusing both writes. The boolean is
+* kept because three surfaces drive a toggle off it; anything that needs to tell
+* "never marked" from "already trained" must read `retrainStatus`.
+*
+* `debug` does NOT pin; it is attention, not durability.
 */
 var TrackFlagFields = {
-	/** Operator marked this track as training material. */
+	/** Operator marked this track as training material — i.e. `retrainStatus` is
+	*  `'staging'`. */
 	markForTrain: boolean().optional(),
 	/** Operator marked this track for diagnostic attention. */
 	debug: boolean().optional()
 };
 /**
+* The lifecycle field itself, on the READ surfaces only (`Track`, `KeyEvent`).
+* Deliberately NOT part of {@link TrackFlagFields}: that group also builds the
+* write patch, and the status is not something the toggle sets — it is what the
+* toggle's boolean is derived from. Absent on an in-RAM track never touched;
+* always present on a persisted row (the column default materialises `'none'`).
+*/
+var TrackRetrainFields = { retrainStatus: RetrainStatusSchema.optional() };
+/**
 * The write half: a PARTIAL patch. An omitted key is left untouched, so setting
 * one flag can never clear the other — the toggles are independent and are
 * driven from three surfaces that do not know about each other.
@@ -15126,7 +15209,32 @@ var TrackFlagsPatchSchema = object(TrackFlagFields);
 var TrackFlagsSchema = object({
 	trackId: string(),
 	markForTrain: boolean(),
-	debug: boolean()
+	debug: boolean(),
+	/** The lifecycle state the boolean was derived from. Required here (unlike on
+	*  a track row) because this shape is only ever produced by the write body,
+	*  which always knows it — and a surface that has just written needs to render
+	*  `trained` without a re-fetch. */
+	retrainStatus: RetrainStatusSchema
+});
+/** Per-camera slice of a training-export estimate. */
+var TrainingExportDeviceTotalsSchema = object({
+	deviceId: number(),
+	tracks: number().int(),
+	files: number().int(),
+	bytes: number().int()
+});
+/**
+* What a training export WOULD contain. Computed from media index rows only —
+* no blob is read to produce this.
+*/
+var TrainingExportSummarySchema = object({
+	generatedAt: number(),
+	trackCount: number().int(),
+	fileCount: number().int(),
+	byteCount: number().int(),
+	/** More marked tracks exist than a single pass carries. */
+	truncated: boolean(),
+	devices: array(TrainingExportDeviceTotalsSchema).readonly()
 });
 var TrackSchema = object({
 	trackId: string(),
@@ -15171,7 +15279,8 @@ var TrackSchema = object({
 	*  Populated from the persisted envelope columns on historical reads;
 	*  absent on legacy rows, dims-less tracks and active (in-RAM) tracks. */
 	envelope: TrackEnvelopeSchema.optional(),
-	...TrackFlagFields
+	...TrackFlagFields,
+	...TrackRetrainFields
 });
 var BaseEventFields = {
 	id: string(),
@@ -15385,7 +15494,8 @@ var KeyEventSchema = object({
 	bestEventId: string(),
 	/** Track lifetime in ms (lastSeen - firstSeen). */
 	windowMs: number().optional(),
-	...TrackFlagFields
+	...TrackFlagFields,
+	...TrackRetrainFields
 });
 object({
 	trackId: string(),
@@ -15646,6 +15756,12 @@ DeviceType.Camera, method(object({ deviceId: number() }), array(TrackSchema).rea
 }), method(OpsLogQueryInputSchema, array(OpsLogEntrySchema).readonly(), {
 	kind: "query",
 	auth: "admin"
+}), method(object({ deviceIds: array(number()).optional() }), TrainingExportSummarySchema, {
+	kind: "query",
+	auth: "admin"
+}), method(object({ deviceIds: array(number()).optional() }), object({ url: string() }), {
+	kind: "query",
+	auth: "admin"
 }), method(object({
 	eventId: string(),
 	kind: MediaFileKindEnum.optional()
@@ -22508,6 +22624,173 @@ setOverlay: method(object({
 	}] }
 };
 /**
+* `osd-manager` — the ORCHESTRATOR over the device-scope `osd` cap.
+*
+* The `osd` cap is the firmware contract: it probes a camera's overlay
+* SLOTS and writes literal text into one. It has no idea WHERE that text
+* comes from, and it must not — a driver that grew a "show the temperature
+* here" feature would grow it once per vendor.
+*
+* This cap owns the other half: a per-(camera, slot) BINDING that says
+* which value feeds the slot, how it is formatted, and under which
+* conditions it is shown at all. One addon renders every binding on every
+* camera, so a new source costs zero driver code.
+*
+* Three deliberate choices, each with a rejected alternative:
+*
+*  1. A source is `(capName, valuePath)` over the kernel's device
+*     runtime-state mirror — NOT a closed enum of source kinds. Every
+*     cap-keyed slice a device publishes is bindable the day the cap
+*     ships. The rejected alternative (one enum member per source, with
+*     a resolver branch each) is what makes "add the humidity too" a
+*     code change.
+*  2. The display gate reuses `NcConditionsSchema` verbatim — the
+*     notification centre's condition vocabulary — rather than a parallel
+*     model. An operator who has learned one condition editor has learned
+*     both.
+*  3. Because the renderer's facts are device STATE and not a detection
+*     record, only a SUBSET of that vocabulary can be answered here.
+*     `setSlotBinding` REJECTS the rest at write time (see
+*     `getConditionSupport`). It does not accept-then-fail-closed: a
+*     condition that can never be true renders a permanently blank
+*     overlay, and a blank overlay looks exactly like a broken camera.
+*/
+/** Where a slot's value comes from. */
+var OsdSourceSchema = discriminatedUnion("kind", [
+	object({
+		kind: literal("static"),
+		text: string().max(64)
+	}),
+	object({
+		kind: literal("clock"),
+		/** Token pattern: `YYYY MM DD HH mm ss`. Everything else is literal. */
+		pattern: string().min(1).max(32).default("HH:mm"),
+		/** IANA zone. Omitted = the server's zone. */
+		timezone: string().min(1).max(64).optional()
+	}),
+	object({
+		kind: literal("device-state"),
+		deviceId: number().int().optional(),
+		capName: string().min(1).max(64),
+		/** Dot path inside the slice, e.g. `detected`, `value`, `mode`. */
+		valuePath: string().min(1).max(64)
+	})
+]);
+var OsdSlotBindingSchema = object({
+	/** Off = the manager stops driving this slot. It does NOT clear it. */
+	enabled: boolean().default(true),
+	source: OsdSourceSchema,
+	/** `${value}` and `${unit}` are substituted; every occurrence. */
+	template: string().max(96).default("${value}"),
+	/** Truncate with an ellipsis past this length. Absent = no limit. */
+	maxCharacters: number().int().min(4).max(64).optional(),
+	/**
+	* Decimal places for a numeric value. `0` yields an integer — the
+	* documented workaround for firmwares that reject `.` in overlay text.
+	*/
+	maxDecimals: number().int().min(0).max(4).default(1),
+	/** Appended via `${unit}`. The state mirror does not carry units. */
+	unitLabel: string().max(8).optional(),
+	/** Raw value → display text, e.g. `{"true":"MOTION","false":""}`. */
+	valueMap: record(string(), string()).optional(),
+	/** Time windows in which the slot is shown. Absent = always. */
+	schedule: NcScheduleSchema.optional(),
+	/**
+	* Display gate, in the notification centre's condition vocabulary.
+	* Only the keys reported by `getConditionSupport` are accepted.
+	*/
+	conditions: NcConditionsSchema.optional(),
+	/** Rendered when the gate is closed or the value unreadable. Empty = hide. */
+	fallbackText: string().max(64).default("")
+});
+/** One camera slot, as the operator sees it: firmware truth + our binding. */
+var OsdSlotViewSchema = object({
+	slotId: string(),
+	kind: OsdOverlayKindEnum,
+	/** Firmware refuses text edits (a timestamp, the channel name). */
+	readOnly: boolean(),
+	cameraEnabled: boolean(),
+	cameraText: string().optional(),
+	binding: OsdSlotBindingSchema.nullable()
+});
+/**
+* What happened to one slot on one render pass. `unchanged` exists so the
+* operator can tell "we are driving this and the value is steady" from
+* "we never got there" — and so the loop can prove it is not rewriting
+* identical text to the camera every tick.
+*/
+var OsdRenderOutcomeEnum = _enum([
+	"written",
+	"unchanged",
+	"gated",
+	"unreadable",
+	"disabled",
+	"unbound",
+	"failed"
+]);
+var OsdRenderResultSchema = object({
+	slotId: string(),
+	outcome: OsdRenderOutcomeEnum,
+	/** The text the slot should carry. Empty = the slot is switched off. */
+	text: string(),
+	/** Why, whenever the outcome is not a plain write. Never silent. */
+	reason: string().optional()
+});
+var OsdSourceValueTypeEnum = _enum([
+	"number",
+	"boolean",
+	"string",
+	"enum"
+]);
+/**
+* One bindable value, derived from a cap's `runtimeState` schema — never
+* hand-listed. The editor renders from this, so a cap that ships a new
+* state field becomes bindable with no UI change.
+*/
+var OsdSourceOptionSchema = object({
+	deviceId: number().int(),
+	deviceName: string(),
+	capName: string(),
+	valuePath: string(),
+	label: string(),
+	valueType: OsdSourceValueTypeEnum,
+	/** Present for `enum`; the editor offers these as `valueMap` keys. */
+	enumValues: array(string()).readonly().optional()
+});
+method(object({ deviceId: number().int() }), object({
+	supported: boolean(),
+	slots: array(OsdSlotViewSchema)
+}), { auth: "admin" }), method(object({ deviceId: number().int() }), object({ sources: array(OsdSourceOptionSchema) }), { auth: "admin" }), method(object({}), object({
+	supported: array(string()),
+	catalog: array(NcConditionDescriptorSchema)
+}), { auth: "admin" }), method(object({
+	deviceId: number().int(),
+	slotId: string().min(1),
+	binding: OsdSlotBindingSchema
+}), object({
+	slot: OsdSlotViewSchema,
+	render: OsdRenderResultSchema
+}), {
+	kind: "mutation",
+	auth: "admin"
+}), method(object({
+	deviceId: number().int(),
+	slotId: string().min(1)
+}), object({ success: literal(true) }), {
+	kind: "mutation",
+	auth: "admin"
+}), method(object({
+	deviceId: number().int(),
+	slotId: string().min(1),
+	binding: OsdSlotBindingSchema.optional()
+}), OsdRenderResultSchema, {
+	kind: "mutation",
+	auth: "admin"
+}), method(object({ deviceId: number().int() }), object({ results: array(OsdRenderResultSchema) }), {
+	kind: "mutation",
+	auth: "admin"
+});
+/**
 * Feeder connectivity / power status — mirrors the HA petkit device-status
 * enum: `normal` (online, mains), `offline` (not reaching PetKit cloud),
 * `on_batteries` (running on battery backup). `null` until first reported.
@@ -29562,6 +29845,48 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"osdManager.clearSlotBinding": {
+		capName: "osd-manager",
+		capScope: "system",
+		addonId: null,
+		access: "delete"
+	},
+	"osdManager.getConditionSupport": {
+		capName: "osd-manager",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
+	"osdManager.getDeviceOsd": {
+		capName: "osd-manager",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
+	"osdManager.getSourceCatalog": {
+		capName: "osd-manager",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
+	"osdManager.previewSlot": {
+		capName: "osd-manager",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
+	"osdManager.renderDevice": {
+		capName: "osd-manager",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
+	"osdManager.setSlotBinding": {
+		capName: "osd-manager",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
 	"petFeeder.callPet": {
 		capName: "pet-feeder",
 		capScope: "device",
@@ -29724,6 +30049,18 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"pipelineAnalytics.getTrainingExportSummary": {
+		capName: "pipeline-analytics",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
+	"pipelineAnalytics.getTrainingExportUrl": {
+		capName: "pipeline-analytics",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
 	"pipelineAnalytics.listEventKinds": {
 		capName: "pipeline-analytics",
 		capScope: "device",
@@ -31200,6 +31537,12 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"streamBroker.getDeviceAudioMute": {
+		capName: "stream-broker",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"streamBroker.getPreBufferInfo": {
 		capName: "stream-broker",
 		capScope: "system",
@@ -31320,6 +31663,12 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"streamBroker.setDeviceAudioMute": {
+		capName: "stream-broker",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
 	"streamBroker.setPreBufferDuration": {
 		capName: "stream-broker",
 		capScope: "system",
@@ -32763,6 +33112,215 @@ function buildAuthHeader(input) {
 	return `Digest ${parts.join(", ")}`;
 }
 //#endregion
+//#region src/hikvision-snapshot-channel.ts
+/**
+* Hikvision encodes a channel id as `{cameraNumber}{streamSlot}`; slot `1` is
+* the main stream. The provider has always taken its snapshot from the main
+* stream of the device's camera number, and that stays the default.
+*/
+function defaultSnapshotChannelId(cameraNumber) {
+	return `${cameraNumber}01`;
+}
+/** Human name for a stream slot, for the select label. */
+function streamSlotLabel(channelId) {
+	const slot = channelId.slice(-1);
+	if (slot === "1") return "Main stream";
+	if (slot === "2") return "Sub stream";
+	if (slot === "3") return "Third stream";
+	return `Stream ${slot}`;
+}
+/**
+* Tag scanner. `<?xml …?>`, `<!-- … -->` and `<![CDATA[…]]>` never match —
+* `?`, `!` are outside the name class — so they are skipped as text.
+*/
+function* scanTags(xml) {
+	const re = /<(\/?)\s*([A-Za-z_][A-Za-z0-9_.:-]*)([^>]*)>/g;
+	let m;
+	while ((m = re.exec(xml)) !== null) {
+		const rawName = m[2] ?? "";
+		const colon = rawName.lastIndexOf(":");
+		yield {
+			name: (colon >= 0 ? rawName.slice(colon + 1) : rawName).toLowerCase(),
+			closing: m[1] === "/",
+			selfClosing: (m[3] ?? "").trimEnd().endsWith("/"),
+			start: m.index,
+			end: re.lastIndex
+		};
+	}
+}
+function decodeXmlEntities$1(s) {
+	return s.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, "\"").replace(/&apos;/g, "'").replace(/&amp;/g, "&");
+}
+/**
+* Text of the first `<tag>` that is a DIRECT child of `elementInner`.
+*
+* `null` when the element has no such direct child — a nested occurrence
+* (`<Video><enabled>`) is deliberately invisible here. Empty string when the
+* direct child exists but is empty or self-closing, which is NOT the same
+* answer and callers must keep the two apart.
+*/
+function readDirectChildText(elementInner, tag) {
+	const want = tag.toLowerCase();
+	let depth = 0;
+	let openedAt = -1;
+	for (const token of scanTags(elementInner)) {
+		if (token.selfClosing) {
+			if (depth === 0 && !token.closing && token.name === want) return "";
+			continue;
+		}
+		if (token.closing) {
+			if (depth === 1 && openedAt >= 0 && token.name === want) return decodeXmlEntities$1(elementInner.slice(openedAt, token.start).trim());
+			depth = Math.max(0, depth - 1);
+			continue;
+		}
+		if (depth === 0 && token.name === want && openedAt < 0) openedAt = token.end;
+		depth += 1;
+	}
+	return null;
+}
+/**
+* Inner content of the first `<tag>…</tag>` element in `xml`, or `null`.
+* Used to reach INTO a `<StreamingChannel>` before asking for a direct child.
+*/
+function extractElementInner(xml, tag) {
+	const want = tag.toLowerCase();
+	let depth = 0;
+	let openedAt = -1;
+	for (const token of scanTags(xml)) {
+		if (token.selfClosing) {
+			if (depth === 0 && !token.closing && token.name === want) return "";
+			continue;
+		}
+		if (token.closing) {
+			if (depth === 1 && openedAt >= 0 && token.name === want) return xml.slice(openedAt, token.start);
+			depth = Math.max(0, depth - 1);
+			continue;
+		}
+		if (depth === 0 && token.name === want && openedAt < 0) openedAt = token.end;
+		depth += 1;
+	}
+	return null;
+}
+/**
+* Every `<StreamingChannel>` element's inner content, in document order.
+* Depth-aware, so a `<StreamingChannelList>` wrapper is transparent and a
+* (hypothetical) nested repeat is not double-counted.
+*/
+function streamingChannelBlocks(xml) {
+	const out = [];
+	let depth = 0;
+	let openedAt = -1;
+	let openDepth = -1;
+	for (const token of scanTags(xml)) {
+		if (token.selfClosing) continue;
+		if (token.closing) {
+			depth = Math.max(0, depth - 1);
+			if (openedAt >= 0 && depth === openDepth && token.name === "streamingchannel") {
+				out.push(xml.slice(openedAt, token.start));
+				openedAt = -1;
+				openDepth = -1;
+			}
+			continue;
+		}
+		if (openedAt < 0 && token.name === "streamingchannel") {
+			openedAt = token.end;
+			openDepth = depth;
+		}
+		depth += 1;
+	}
+	return out;
+}
+/**
+* The CHANNEL's own `<enabled>` in a `/ISAPI/Streaming/channels/{id}` document
+* (or in one `<StreamingChannel>` block). `null` when the firmware emits no
+* channel-level flag — distinct from `false`, which means the operator (or the
+* camera) switched the channel off and no picture will come out of it.
+*
+* Never returns `<Video><enabled>` or `<Audio><enabled>`.
+*/
+function readStreamingChannelEnabled(xml) {
+	const raw = readDirectChildText(extractElementInner(xml, "StreamingChannel") ?? xml, "enabled");
+	if (raw === null || raw === "") return null;
+	return raw.trim().toLowerCase() === "true";
+}
+/**
+* Parse `/ISAPI/Streaming/channels` into one summary per channel. Element-scoped
+* throughout: `enabled` is the channel's own flag even on a firmware that emits
+* `<Video>` before it.
+*/
+function parseStreamingChannelSummaries(xml) {
+	const out = [];
+	for (const block of streamingChannelBlocks(xml)) {
+		const channelId = readDirectChildText(block, "id");
+		if (channelId === null || channelId === "") continue;
+		const name = readDirectChildText(block, "channelName");
+		const enabledRaw = readDirectChildText(block, "enabled");
+		out.push({
+			channelId,
+			channelName: name === null || name === "" ? null : name,
+			enabled: enabledRaw === null || enabledRaw === "" ? true : enabledRaw.toLowerCase() === "true"
+		});
+	}
+	return out;
+}
+/**
+* Build the operator-facing select options from PROBED channels — never a
+* hardcoded main/sub pair. A channel the camera reports as disabled is still
+* listed (choosing it is a legitimate way to say "use this once I re-enable
+* it") but says so, so an operator does not pick a source that cannot produce
+* a picture without being told.
+*
+* Ordered by channel id so main/sub/third read in the natural order.
+*/
+function buildSnapshotChannelOptions(channels) {
+	return channels.toSorted((a, b) => a.channelId.localeCompare(b.channelId, "en")).map((c) => {
+		const parts = [`${streamSlotLabel(c.channelId)} — ${c.channelId}`];
+		const detail = [];
+		if (c.channelName !== null && c.channelName !== void 0 && c.channelName !== "") detail.push(c.channelName);
+		if (c.width !== null && c.width !== void 0 && c.height !== null && c.height !== void 0) detail.push(`${c.width}×${c.height}`);
+		if (c.codec !== null && c.codec !== void 0 && c.codec !== "") detail.push(c.codec);
+		if (c.enabled === false) detail.push("disabled on camera");
+		if (detail.length > 0) parts.push(`(${detail.join(", ")})`);
+		return {
+			value: c.channelId,
+			label: parts.join(" ")
+		};
+	});
+}
+/**
+* Resolve the channel a snapshot is taken from.
+*
+* - Nothing stored → the historical default. This is the whole
+*   no-behaviour-change-on-upgrade guarantee: the setting starts at the channel
+*   the provider already used and only an explicit operator save moves it.
+* - Stored choice present in `available` → the operator's channel.
+* - `available` EMPTY → honour the stored choice. An empty list means the probe
+*   never ran (fresh boot, unreachable camera), not that the camera refused the
+*   channel; discarding an operator's setting because we have not looked yet
+*   would be destroying their work on a fallible read.
+* - Stored choice absent from a non-empty `available` → default, flagged
+*   `fallback-unknown` so the caller can log it.
+*/
+function resolveSnapshotChannelId(configured, available, fallbackChannelId) {
+	const choice = (configured ?? "").trim();
+	if (choice === "") return {
+		channelId: fallbackChannelId,
+		source: "default"
+	};
+	if (available.length === 0) return {
+		channelId: choice,
+		source: "operator"
+	};
+	if (available.includes(choice)) return {
+		channelId: choice,
+		source: "operator"
+	};
+	return {
+		channelId: fallbackChannelId,
+		source: "fallback-unknown"
+	};
+}
+//#endregion
 //#region src/hikvision-stream-audio.ts
 /**
 * Compare a post-write read-back against what was asked for.
@@ -34230,7 +34788,7 @@ function parseStreamingChannelCaps(xml) {
 function parseStreamingChannelConfig(xml) {
 	const id = extractTag(xml, "id") ?? "";
 	const channelName = extractTag(xml, "channelName");
-	const enabled = (extractTag(xml, "enabled") ?? "false").toLowerCase() === "true";
+	const enabled = readStreamingChannelEnabled(xml) ?? true;
 	const videoCodecType = extractTag(xml, "videoCodecType");
 	const width = parseIntSafe(extractTag(xml, "videoResolutionWidth"));
 	const height = parseIntSafe(extractTag(xml, "videoResolutionHeight"));
@@ -34465,11 +35023,12 @@ function decodeXmlEntities(s) {
 }
 function parseChannelsList(xml) {
 	const blocks = extractAllBlocks(xml, "StreamingChannel");
+	const summaries = new Map(parseStreamingChannelSummaries(xml).map((s) => [s.channelId, s]));
 	const out = [];
 	for (const b of blocks) {
 		const id = extractTag(b, "id");
 		if (!id) continue;
-		const enabled = (extractTag(b, "enabled") ?? "true").toLowerCase() === "true";
+		const enabled = summaries.get(id)?.enabled ?? true;
 		const codec = extractTag(b, "videoCodecType");
 		const width = parseIntSafe(extractTag(b, "videoResolutionWidth"));
 		const height = parseIntSafe(extractTag(b, "videoResolutionHeight"));
@@ -35830,6 +36389,13 @@ var HikvisionDeviceCacheSchema = object({
 	ntpSnapshot: HikvisionNtpSnapshotSchema.optional(),
 	streamSnapshots: record(string(), object({
 		channelName: string().nullable().optional(),
+		/**
+		* The CHANNEL's own `<enabled>` — read element-scoped via
+		* `readStreamingChannelEnabled`, never the `<Video>` / `<Audio>`
+		* sub-element flag that shares the tag name. Drives the
+		* "disabled on camera" hint on the snapshot-source select.
+		*/
+		enabled: boolean().optional(),
 		videoCodecType: string().nullable().optional(),
 		maxFrameRate: number().nullable().optional(),
 		videoQualityControlType: _enum(["VBR", "CBR"]).nullable().optional(),
@@ -35894,6 +36460,21 @@ var hikvisionCameraSchema = object({
 		"off"
 	]).default("auto").describe("Two-way audio source (auto/isapi/onvif/off)"),
 	/**
+	* ISAPI streaming channel the `snapshot` cap captures from
+	* (`/ISAPI/Streaming/channels/{id}/picture`).
+	*
+	* Empty string = "not chosen" → the provider's historical channel
+	* (`{cameraNumber}01`, the main stream). That sentinel is what makes an
+	* upgrade a no-op: the setting starts at the channel already in use and only
+	* an explicit operator save moves it.
+	*
+	* Options are PROBED from `/ISAPI/Streaming/channels` (persisted into
+	* `deviceCache.streamSnapshots`), never hardcoded. A stored id the camera
+	* stops enumerating falls back to the default and the provider logs it —
+	* see `resolveSnapshotChannelId`.
+	*/
+	snapshotChannelId: string().default("").describe("ISAPI channel used for snapshots (empty = main stream)"),
+	/**
 	* Motion detection master switch + sensitivity (0..100). Maps to
 	* ISAPI `/ISAPI/System/Video/inputs/channels/{cam}/motionDetection`.
 	* Disabling this stops the camera from emitting `<eventType>VMD</eventType>`
@@ -36178,6 +36759,9 @@ var HikvisionCamera = class HikvisionCamera extends BaseDevice {
 	*  plenty; the cap's own getStatus refreshes on demand for the
 	*  universal overlay UI. */
 	osdPollTimer = null;
+	/** Last snapshot channel we logged, so `resolveSnapshotChannel` emits one
+	*  line per CHANGE instead of one per capture. */
+	lastSnapshotChannelLogged = null;
 	static OSD_POLL_INTERVAL_MS = 3e5;
 	/** Control-plane reachability poll — drives `device.online` from ISAPI
 	*  `getDeviceInfo` liveness, decoupled from stream-broker video health.
@@ -36197,7 +36781,7 @@ var HikvisionCamera = class HikvisionCamera extends BaseDevice {
 			getSnapshot: async ({ deviceId }) => {
 				if (deviceId !== this.id) throw new Error(`HikvisionCamera: deviceId mismatch, expected ${this.id}, got ${deviceId}`);
 				const isapi = this.ensureClient();
-				const channelId = `101`;
+				const channelId = this.resolveSnapshotChannel();
 				try {
 					const { buffer, contentType } = await isapi.getSnapshot(channelId);
 					return {
@@ -36256,6 +36840,62 @@ var HikvisionCamera = class HikvisionCamera extends BaseDevice {
 		});
 	}
 	/**
+	* The probed streaming channels, as the snapshot-source select needs them.
+	* Sourced from `deviceCache.streamSnapshots`, which the connect-time probe
+	* fills from `/ISAPI/Streaming/channels` — never a hardcoded main/sub pair.
+	* Empty until the first successful probe; the select is then not rendered
+	* at all rather than offering a channel we have not confirmed exists.
+	*/
+	probedSnapshotChannels() {
+		const snapshots = this.config.get("deviceCache")?.streamSnapshots ?? {};
+		return Object.entries(snapshots).map(([channelId, snap]) => ({
+			channelId,
+			channelName: snap.channelName ?? null,
+			enabled: snap.enabled,
+			codec: snap.videoCodecType ?? null,
+			width: snap.resolutionWidth ?? null,
+			height: snap.resolutionHeight ?? null
+		}));
+	}
+	/**
+	* The ISAPI channel the next snapshot is taken from.
+	*
+	* Unset setting → `{cam}01`, the channel the provider used before this
+	* setting existed. A stored channel the camera no longer enumerates falls
+	* back to that default and WARNS: a snapshot silently coming from a
+	* different channel than the operator picked is precisely the kind of
+	* substitution that reads as "the setting never worked".
+	*
+	* The info line fires only when the effective channel CHANGES, so a
+	* per-second snapshot poll does not become a log stream.
+	*/
+	resolveSnapshotChannel() {
+		const fallback = defaultSnapshotChannelId(1);
+		const configured = this.config.get("snapshotChannelId") ?? "";
+		const available = this.probedSnapshotChannels().map((c) => c.channelId);
+		const resolved = resolveSnapshotChannelId(configured, available, fallback);
+		if (resolved.source === "fallback-unknown") this.ctx.logger.warn("hikvision snapshot channel not offered by camera — using default", {
+			tags: { deviceId: this.id },
+			meta: {
+				configured,
+				fallback,
+				available
+			}
+		});
+		if (this.lastSnapshotChannelLogged !== resolved.channelId) {
+			this.lastSnapshotChannelLogged = resolved.channelId;
+			this.ctx.logger.info("hikvision snapshot source channel resolved", {
+				tags: { deviceId: this.id },
+				meta: {
+					channelId: resolved.channelId,
+					source: resolved.source,
+					configured
+				}
+			});
+		}
+		return resolved.channelId;
+	}
+	/**
 	* Register the device-scoped `stream-catalog` cap — the broker pulls
 	* this to (re)build its cam-stream registry. Sources its descriptors
 	* from `buildStreamCatalog`, which also reconciles the local `published`
@@ -36993,6 +37633,7 @@ var HikvisionCamera = class HikvisionCamera extends BaseDevice {
 				if (!cfg) continue;
 				snapshots[channel.id] = {
 					channelName: cfg.channelName,
+					enabled: cfg.enabled,
 					videoCodecType: cfg.videoCodecType,
 					maxFrameRate: cfg.maxFrameRate,
 					videoQualityControlType: cfg.videoQualityControlType,
@@ -38297,6 +38938,7 @@ var HikvisionCamera = class HikvisionCamera extends BaseDevice {
 	}
 	getSettingsUISchema() {
 		const osdValues = this.osdSnapshotForUi();
+		const snapshotChannelOptions = buildSnapshotChannelOptions(this.probedSnapshotChannels());
 		return hydrateSchema({ sections: [
 			{
 				id: "connection",
@@ -38747,6 +39389,20 @@ var HikvisionCamera = class HikvisionCamera extends BaseDevice {
 					}] : []
 				]
 			}] : [],
+			...snapshotChannelOptions.length > 0 ? [{
+				id: "snapshot-source",
+				tab: "streaming",
+				title: "Snapshot source",
+				description: "Which ISAPI streaming channel the still image is captured from (`/ISAPI/Streaming/channels/{id}/picture`). The list is read off this camera. Default is the main stream — the channel the provider has always used — so leaving this alone changes nothing. Pick the sub stream when the main stream is 4K and the snapshot only feeds thumbnails.",
+				columns: 1,
+				fields: [{
+					type: "select",
+					key: "snapshotChannelId",
+					label: "Snapshot channel",
+					default: defaultSnapshotChannelId(1),
+					options: [...snapshotChannelOptions]
+				}]
+			}] : [],
 			{
 				id: "alarms",
 				tab: "alarms",
@@ -38903,6 +39559,7 @@ var HikvisionCamera = class HikvisionCamera extends BaseDevice {
 			username: this.config.get("username"),
 			password: this.config.get("password"),
 			rtspTransport: this.config.get("rtspTransport") ?? "unicast",
+			snapshotChannelId: this.resolveSnapshotChannel(),
 			motionEnabled: this.config.get("motionEnabled") ?? true,
 			motionSensitivity: this.config.get("motionSensitivity") ?? 60,
 			vcaResource: this.config.get("vcaResource") ?? "smart",
@@ -38961,6 +39618,7 @@ var HikvisionCamera = class HikvisionCamera extends BaseDevice {
 	}
 	async applySettingsPatch(patch) {
 		const cleaned = stripOsdShadowFields(patch);
+		const previousSnapshotChannel = this.resolveSnapshotChannel();
 		await this.config.setAll(cleaned);
 		const typed = cleaned;
 		if (typed.host !== void 0 || typed.port !== void 0 || typed.https !== void 0 || typed.username !== void 0 || typed.password !== void 0) {
@@ -38973,6 +39631,35 @@ var HikvisionCamera = class HikvisionCamera extends BaseDevice {
 			});
 			this.ensureAlarmSubscription();
 		}
+		if (typed.snapshotChannelId !== void 0) {
+			const nextSnapshotChannel = this.resolveSnapshotChannel();
+			if (nextSnapshotChannel !== previousSnapshotChannel) {
+				this.ctx.logger.info("hikvision snapshot channel changed", {
+					tags: { deviceId: this.id },
+					meta: {
+						from: previousSnapshotChannel,
+						to: nextSnapshotChannel
+					}
+				});
+				try {
+					const proxy = await this.ctx.fetchDevice(this.id);
+					if (proxy.snapshot === void 0) this.ctx.logger.info("no snapshot wrapper bound — nothing to flush", {
+						tags: { deviceId: this.id },
+						meta: { to: nextSnapshotChannel }
+					});
+					else await proxy.snapshot.invalidateCache({});
+				} catch (err) {
+					this.ctx.logger.warn("snapshot cache flush after channel change failed", {
+						tags: { deviceId: this.id },
+						meta: {
+							from: previousSnapshotChannel,
+							to: nextSnapshotChannel,
+							error: err instanceof Error ? err.message : String(err)
+						}
+					});
+				}
+			}
+		}
 		if (typed.motionEnabled !== void 0 || typed.motionSensitivity !== void 0) try {
 			await this.ensureClient().setMotionDetection(1, {
 				enabled: typed.motionEnabled,