@camstack/addon-export-hap 1.2.14 → 1.2.15

package/dist/export-hap.addon.mjs

@@ -1,9 +1,9 @@
 import { createRequire } from "node:module";
-import { createHash, randomBytes } from "node:crypto";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
 import * as path from "node:path";
 import { readFileSync } from "node:fs";
 import { spawn } from "node:child_process";
-import { Accessory, AudioBitrate, AudioStreamingCodecType, AudioStreamingSamplerate, CameraController, Categories, Characteristic, DoorbellController, H264Level, H264Profile, HAPStorage, SRTPCryptoSuites, Service, uuid } from "@homebridge/hap-nodejs";
+import { Accessory, AudioBitrate, AudioRecordingCodecType, AudioRecordingSamplerate, AudioStreamingCodecType, AudioStreamingSamplerate, CameraController, Categories, Characteristic, DoorbellController, H264Level, H264Profile, HAPStorage, HDSProtocolError, HDSProtocolSpecificErrorReason, MediaContainerType, SRTPCryptoSuites, Service, VideoCodecType, uuid } from "@homebridge/hap-nodejs";
 import * as fs from "node:fs/promises";
 import { createSocket } from "node:dgram";
 import { networkInterfaces } from "node:os";
@@ -6510,7 +6510,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
@@ -7041,104 +7054,7 @@ method(object({ deviceId: number() }), array(StreamSourceEntrySchema)), method(o
 	input: unknown()
 }), unknown(), { kind: "mutation" }), method(object({ deviceId: number() }), _void(), { kind: "mutation" }), method(object({ deviceId: number() }), unknown().nullable()), method(object({ deviceId: number() }), RawStateResultSchema.nullable(), { auth: "protected" });
 //#endregion
-//#region ../types/dist/canonical-hash-7nfBbEqR.mjs
-/**
-* Deterministic SHA-256 hash of an arbitrary serialisable value. The
-* canonical form sorts object keys alphabetically at every depth so two
-* structurally-equal inputs with different key insertion orders produce
-* the same hash. Returns a 64-char lowercase hex digest.
-*
-* Used by export adapters (Alexa, HAP) to short-circuit re-discovery /
-* accessory-rebuild work when the upstream shape is byte-identical to
-* the last applied state — preventing user-visible "re-discovery"
-* notifications on every addon-runner respawn. Each respawn re-fires
-* `DeviceBindingsChanged` for every cap registration, which without
-* this guard would propagate redundant pushes.
-*
-* Note: this is a SYMPTOMATIC fix layered on top of the binding-change
-* subscription. The proper fix is a single "device ready" lifecycle
-* barrier so exports react only when the full cap set has landed —
-* tracked separately for post-HA-integration work.
-*/
-function canonicalHash(value) {
-	const canonical = JSON.stringify(value, replaceWithSortedKeys);
-	return createHash("sha256").update(canonical ?? "").digest("hex");
-}
-function replaceWithSortedKeys(_key, value) {
-	if (value && typeof value === "object" && !Array.isArray(value)) {
-		const obj = value;
-		const out = {};
-		for (const k of Object.keys(obj).toSorted()) out[k] = obj[k];
-		return out;
-	}
-	return value;
-}
-var EncodeProfileSchema = object({
-	video: object({
-		codec: _enum([
-			"h264",
-			"h265",
-			"copy"
-		]),
-		profile: _enum([
-			"baseline",
-			"main",
-			"high"
-		]).optional(),
-		/**
-		* `-level`, e.g. `'3.1'`. A consumer that ADVERTISES a level in its SDP
-		* (`profile-level-id=42e01f` is Baseline 3.1) must constrain the encoder to
-		* it, or it ships a stream that does not match its own advertisement — the
-		* defect class that kept HomeKit black for a year and that Alexa carried
-		* silently. Optional because a browser negotiates the level itself.
-		*/
-		level: string().optional(),
-		width: number().int().positive().optional(),
-		height: number().int().positive().optional(),
-		fps: number().positive().optional(),
-		bitrateKbps: number().int().positive().optional(),
-		gopFrames: number().int().positive().optional(),
-		bf: number().int().min(0).optional(),
-		preset: _enum([
-			"ultrafast",
-			"superfast",
-			"veryfast",
-			"faster",
-			"fast",
-			"medium"
-		]).optional(),
-		tune: _enum([
-			"zerolatency",
-			"film",
-			"animation"
-		]).optional()
-	}),
-	audio: union([literal("passthrough"), object({
-		codec: _enum([
-			"opus",
-			"aac",
-			"pcmu",
-			"pcma",
-			"copy"
-		]),
-		bitrateKbps: number().int().positive().optional(),
-		sampleRateHz: number().int().positive().optional(),
-		channels: union([literal(1), literal(2)]).optional()
-	})]),
-	/**
-	* ffmpeg input-side args, inserted between the fixed global flags
-	* (`-hide_banner -loglevel error`) and `-i pipe:0`. Free-text array
-	* — the widget surfaces a textarea + suggestion chips for the most-
-	* used demuxer/format options.
-	*/
-	inputArgs: array(string()).optional(),
-	/**
-	* ffmpeg output-side args, inserted between the encode block and
-	* the final `-f <muxer> pipe:1`. Use for muxer options, bitstream
-	* filters, codec-specific overrides. Free-text array.
-	*/
-	outputArgs: array(string()).optional()
-});
+//#region ../types/dist/fmp4-box-splitter-B53u9-Nu.mjs
 var AUDIO_ENCODER_BY_CODEC = {
 	opus: "libopus",
 	aac: "aac",
@@ -7319,13 +7235,42 @@ function buildStdoutOrRtspSinkArgs(sink) {
 		"pipe:1"
 	];
 }
+/**
+* How far BELOW the negotiated fragment length `-min_frag_duration` is set.
+*
+* `-min_frag_duration` refuses to cut before that much media has accumulated,
+* and then waits for the next key frame. Set to exactly `fragmentMs`, the
+* commonest camera configuration in existence — a key-frame grid EQUAL to the
+* requested fragment length — lands the deadline on the same instant as the key
+* frame, loses the race, and skips to the following one: **every fragment comes
+* out at twice the requested length.**
+*
+* Measured on the live fleet 2026-08-07, camera 615, `-c:v copy` (D84):
+*
+* | slot | GOP | `-min_frag_duration` | median gap |
+* | --- | --- | --- | --- |
+* | 1280×720 | 40 f @ 10 fps = 4.0 s | 4000 ms | **7944 ms** |
+* | 1280×720 | 40 f @ 10 fps = 4.0 s | 3600 ms | 3973 ms |
+* | 3840×2160 | 100 f @ 25 fps = 4.0 s | 4000 ms | 8042 ms |
+* | 3840×2160 | 100 f @ 25 fps = 4.0 s | 3600 ms | 3998 ms |
+*
+* A doubled fragment is not a cosmetic overshoot: HKSV requires every fragment
+* to be no longer than the length the controller SELECTED, so the shipped-but-
+* inert phase-1 sink would have violated the contract on its first real clip.
+*
+* 10 % is chosen against the two failures either side of it. Too small and
+* ordinary jitter (measured spread 3953-4096 ms) re-loses the race; too large
+* and a source with a key frame slightly EARLY than the grid gets cut there,
+* yielding a short fragment for no reason.
+*/
+var FMP4_MIN_FRAG_MARGIN = .9;
 /** `-movflags … -min_frag_duration <us> -f mp4 pipe:1`. */
 function buildFmp4SinkArgs(sink) {
 	return [
 		"-movflags",
 		FMP4_MOVFLAGS,
 		"-min_frag_duration",
-		String(Math.max(0, Math.round(sink.fragmentMs * 1e3))),
+		String(Math.max(0, Math.round(sink.fragmentMs * FMP4_MIN_FRAG_MARGIN * 1e3))),
 		"-f",
 		"mp4",
 		"pipe:1"
@@ -7404,6 +7349,287 @@ function buildFfmpegArgs(inv) {
 	];
 }
 /**
+* Deterministic SHA-256 hash of an arbitrary serialisable value. The
+* canonical form sorts object keys alphabetically at every depth so two
+* structurally-equal inputs with different key insertion orders produce
+* the same hash. Returns a 64-char lowercase hex digest.
+*
+* Used by export adapters (Alexa, HAP) to short-circuit re-discovery /
+* accessory-rebuild work when the upstream shape is byte-identical to
+* the last applied state — preventing user-visible "re-discovery"
+* notifications on every addon-runner respawn. Each respawn re-fires
+* `DeviceBindingsChanged` for every cap registration, which without
+* this guard would propagate redundant pushes.
+*
+* Note: this is a SYMPTOMATIC fix layered on top of the binding-change
+* subscription. The proper fix is a single "device ready" lifecycle
+* barrier so exports react only when the full cap set has landed —
+* tracked separately for post-HA-integration work.
+*/
+function canonicalHash(value) {
+	const canonical = JSON.stringify(value, replaceWithSortedKeys);
+	return createHash("sha256").update(canonical ?? "").digest("hex");
+}
+function replaceWithSortedKeys(_key, value) {
+	if (value && typeof value === "object" && !Array.isArray(value)) {
+		const obj = value;
+		const out = {};
+		for (const k of Object.keys(obj).toSorted()) out[k] = obj[k];
+		return out;
+	}
+	return value;
+}
+var DEFAULT_MAX_UNIT_BYTES = 16 * 1024 * 1024;
+/** Header size for a normal box, and for one carrying a 64-bit `largesize`. */
+var BOX_HEADER_BYTES = 8;
+var LARGE_BOX_HEADER_BYTES = 16;
+var Fmp4BoxSplitter = class {
+	maxUnitBytes;
+	/** Bytes of the CURRENT unit plus any partial box after it. */
+	buffer = new Uint8Array(0);
+	/** Where the current unit starts inside {@link buffer}. */
+	unitStart = 0;
+	/** Where the box scanner has reached inside {@link buffer}. */
+	cursor = 0;
+	state = "init";
+	nextSequence = 0;
+	faultReason = null;
+	interstitial = /* @__PURE__ */ new Set();
+	constructor(options = {}) {
+		this.maxUnitBytes = options.maxUnitBytes ?? DEFAULT_MAX_UNIT_BYTES;
+	}
+	/**
+	* Non-null once the stream cannot be split. The splitter emits nothing
+	* further, so a caller polls this to kill the child rather than watching a
+	* silent stall — a fragmenter that quietly stops producing looks exactly like
+	* a camera with no motion.
+	*/
+	get fault() {
+		return this.faultReason;
+	}
+	/** Bytes currently held. The memory bound, observable rather than asserted. */
+	get pendingBytes() {
+		return this.buffer.length - this.unitStart;
+	}
+	/**
+	* Top-level box types seen BETWEEN fragments and discarded — `mfra`, `free`,
+	* a stray `sidx`. Reported rather than dropped in silence: they are legal and
+	* useless to a fragment consumer, but a type nobody expected showing up here
+	* is the first symptom of a muxer that is not writing what we think it is.
+	*/
+	get discardedInterstitialTypes() {
+		return [...this.interstitial];
+	}
+	/**
+	* Feed bytes; get back whatever units completed. Returns `[]` once faulted.
+	*/
+	push(chunk) {
+		if (this.faultReason !== null || chunk.length === 0) return [];
+		this.append(chunk);
+		if (this.pendingBytes > this.maxUnitBytes) return this.fail(`a single fMP4 unit exceeded ${this.maxUnitBytes} bytes — this stream is not fragmented`);
+		return this.drainBoxes();
+	}
+	append(chunk) {
+		if (this.buffer.length === 0) {
+			this.buffer = chunk.slice();
+			return;
+		}
+		const next = new Uint8Array(this.buffer.length + chunk.length);
+		next.set(this.buffer, 0);
+		next.set(chunk, this.buffer.length);
+		this.buffer = next;
+	}
+	/** Consume every COMPLETE top-level box now in the buffer. */
+	drainBoxes() {
+		const units = [];
+		for (;;) {
+			const header = this.readHeader();
+			if (this.faultReason !== null) return units;
+			if (header === null) break;
+			if (this.cursor + header.totalBytes > this.buffer.length) break;
+			const boxStart = this.cursor;
+			const boxEnd = boxStart + header.totalBytes;
+			this.cursor = boxEnd;
+			const unit = this.consumeBox(header.type, boxStart, boxEnd);
+			if (this.faultReason !== null) return units;
+			if (unit !== null) units.push(unit);
+		}
+		this.compact();
+		return units;
+	}
+	/**
+	* Apply one box to the state machine. Returns a unit when this box CLOSED
+	* one, `null` otherwise.
+	*/
+	consumeBox(type, boxStart, boxEnd) {
+		if (this.state === "init") {
+			if (type !== "moof") return null;
+			if (boxStart === this.unitStart) {
+				this.fail("a moof arrived before any initialisation box — there is no ftyp/moov to send");
+				return null;
+			}
+			const init = this.emit("init", this.unitStart, boxStart);
+			this.unitStart = boxStart;
+			this.state = "fragment";
+			return init;
+		}
+		if (this.state === "idle") {
+			if (type !== "moof") {
+				this.interstitial.add(type);
+				this.unitStart = boxEnd;
+				return null;
+			}
+			this.unitStart = boxStart;
+			this.state = "fragment";
+			return null;
+		}
+		if (type !== "mdat") return null;
+		const fragment = this.emit("fragment", this.unitStart, boxEnd);
+		this.unitStart = boxEnd;
+		this.state = "idle";
+		return fragment;
+	}
+	/**
+	* Parse the header at {@link cursor}, or `null` when too few bytes have
+	* arrived to know. Faults on a size the splitter cannot honour.
+	*/
+	readHeader() {
+		const available = this.buffer.length - this.cursor;
+		if (available < BOX_HEADER_BYTES) return null;
+		const view = new DataView(this.buffer.buffer, this.buffer.byteOffset, this.buffer.byteLength);
+		const size = view.getUint32(this.cursor);
+		const type = String.fromCharCode(this.buffer[this.cursor + 4] ?? 0, this.buffer[this.cursor + 5] ?? 0, this.buffer[this.cursor + 6] ?? 0, this.buffer[this.cursor + 7] ?? 0);
+		if (size === 0) {
+			this.fail(`box "${type}" declares size 0 (to EOF) — an unbounded box cannot be fragmented`);
+			return null;
+		}
+		if (size === 1) {
+			if (available < LARGE_BOX_HEADER_BYTES) return null;
+			const large = view.getBigUint64(this.cursor + BOX_HEADER_BYTES);
+			if (large > BigInt(this.maxUnitBytes)) {
+				this.fail(`box "${type}" declares ${large} bytes, over the ${this.maxUnitBytes} byte bound`);
+				return null;
+			}
+			return {
+				type,
+				totalBytes: Number(large)
+			};
+		}
+		if (size < BOX_HEADER_BYTES) {
+			this.fail(`box "${type}" declares an impossible size of ${size} bytes`);
+			return null;
+		}
+		return {
+			type,
+			totalBytes: size
+		};
+	}
+	emit(kind, start, end) {
+		const sequence = this.nextSequence;
+		this.nextSequence += 1;
+		return {
+			kind,
+			data: this.buffer.slice(start, end),
+			sequence
+		};
+	}
+	/**
+	* Drop everything already emitted or discarded. Without this the buffer is
+	* the whole stream and the process dies in hours, not minutes.
+	*/
+	compact() {
+		if (this.unitStart === 0) return;
+		this.buffer = this.buffer.slice(this.unitStart);
+		this.cursor -= this.unitStart;
+		this.unitStart = 0;
+	}
+	fail(reason) {
+		this.faultReason = reason;
+		this.buffer = new Uint8Array(0);
+		this.unitStart = 0;
+		this.cursor = 0;
+		return [];
+	}
+};
+//#endregion
+//#region ../types/dist/err-msg-IQTHeDzc.mjs
+/**
+import { errMsg } from '@camstack/types'
+* Extract a human-readable message from an unknown error value.
+* Replaces the ubiquitous `errMsg(err)` pattern.
+*/
+function errMsg$12(err) {
+	if (err instanceof Error) return err.message;
+	if (typeof err === "string") return err;
+	return String(err);
+}
+var EncodeProfileSchema = object({
+	video: object({
+		codec: _enum([
+			"h264",
+			"h265",
+			"copy"
+		]),
+		profile: _enum([
+			"baseline",
+			"main",
+			"high"
+		]).optional(),
+		/**
+		* `-level`, e.g. `'3.1'`. A consumer that ADVERTISES a level in its SDP
+		* (`profile-level-id=42e01f` is Baseline 3.1) must constrain the encoder to
+		* it, or it ships a stream that does not match its own advertisement — the
+		* defect class that kept HomeKit black for a year and that Alexa carried
+		* silently. Optional because a browser negotiates the level itself.
+		*/
+		level: string().optional(),
+		width: number().int().positive().optional(),
+		height: number().int().positive().optional(),
+		fps: number().positive().optional(),
+		bitrateKbps: number().int().positive().optional(),
+		gopFrames: number().int().positive().optional(),
+		bf: number().int().min(0).optional(),
+		preset: _enum([
+			"ultrafast",
+			"superfast",
+			"veryfast",
+			"faster",
+			"fast",
+			"medium"
+		]).optional(),
+		tune: _enum([
+			"zerolatency",
+			"film",
+			"animation"
+		]).optional()
+	}),
+	audio: union([literal("passthrough"), object({
+		codec: _enum([
+			"opus",
+			"aac",
+			"pcmu",
+			"pcma",
+			"copy"
+		]),
+		bitrateKbps: number().int().positive().optional(),
+		sampleRateHz: number().int().positive().optional(),
+		channels: union([literal(1), literal(2)]).optional()
+	})]),
+	/**
+	* ffmpeg input-side args, inserted between the fixed global flags
+	* (`-hide_banner -loglevel error`) and `-i pipe:0`. Free-text array
+	* — the widget surfaces a textarea + suggestion chips for the most-
+	* used demuxer/format options.
+	*/
+	inputArgs: array(string()).optional(),
+	/**
+	* ffmpeg output-side args, inserted between the encode block and
+	* the final `-f <muxer> pipe:1`. Use for muxer options, bitstream
+	* filters, codec-specific overrides. Free-text array.
+	*/
+	outputArgs: array(string()).optional()
+});
+/**
 * The shape every live egress starts from: H.264 Baseline 3.1 at 720p25.
 * Baseline because it is the one profile every consumer in this repo decodes
 * (Echo, iOS, an old browser); 3.1 because that is what the SDPs advertise.
@@ -7523,6 +7749,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
 *
@@ -7584,6 +7823,7 @@ var CameraSwitchIdSchema = _enum([
 	"object-detection",
 	"privacy-mask",
 	"device-audio",
+	"broker-audio",
 	"audio-analysis",
 	"recording",
 	"notifications"
@@ -7609,7 +7849,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
@@ -9860,7 +10101,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
@@ -15183,6 +15442,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.
@@ -15192,18 +15475,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.
@@ -15217,7 +15513,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(),
@@ -15262,7 +15583,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(),
@@ -15476,7 +15798,8 @@ var KeyEventSchema = object({
 	bestEventId: string(),
 	/** Track lifetime in ms (lastSeen - firstSeen). */
 	windowMs: number().optional(),
-	...TrackFlagFields
+	...TrackFlagFields,
+	...TrackRetrainFields
 });
 object({
 	trackId: string(),
@@ -15737,6 +16060,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()
@@ -21397,6 +21726,173 @@ DeviceType.Camera, method(object({
 	status: OsdStatusSchema
 });
 /**
+* `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.
@@ -26352,6 +26848,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",
@@ -26514,6 +27052,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",
@@ -27990,6 +28540,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",
@@ -28110,6 +28666,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",
@@ -28978,6 +29540,506 @@ function resolveExportFingerprint(input) {
 	if (input.ready) return input.fresh;
 	return input.persisted ?? input.fresh;
 }
+/**
+* Fmp4FragmentPlane — a SUBSCRIBABLE fragmented-MP4 plane, fed by one
+* {@link import('./fmp4-box-splitter.js').Fmp4BoxSplitter}.
+*
+* ## Why a plane and not a callback
+*
+* The operator's requirement for HKSV was explicit: the live fMP4 source built
+* for it must be **dual-use**, so a HomeKit-triggered recording also lands in
+* CamStack as an additional videoclip source alongside the recorder and the NC
+* clip ring — *one fragmenter, two consumers; do not build an HKSV-only pipe*
+* (`docs/roadmap.md` item 4b). A single-callback pipe makes the second consumer
+* a second ffmpeg child of the same camera. So this is the same shape the
+* broker's other multi-consumer surfaces already have
+* (`AudioChunkPlane`, the push packet plane): N independent subscriptions over
+* one producer.
+*
+* **Nothing consumes it yet.** Phase 4 brings the HKSV delegate and phase 4b the
+* clip source; both are named here so the seam is not re-invented, and neither
+* is built.
+*
+* ## The init segment is RETAINED
+*
+* A subscriber that attaches mid-stream — the clip consumer joining an already
+* running HKSV session, which is the whole dual-use case — receives the
+* retained `ftyp`+`moov` as its first packet and then live fragments. Without
+* retention its fragments are undecodable and the failure looks like a codec
+* problem.
+*
+* ## A slow subscriber is CLOSED, never silently gapped
+*
+* `AudioChunkPlane` drops its oldest chunk on overflow, which for audio costs a
+* click. An fMP4 stream with a hole is not a shorter clip, it is a corrupt one:
+* `moof` sequence numbers jump, the consumer's demuxer desynchronises, and HKSV
+* shows a clip that fails to play with nothing anywhere saying why. So a
+* subscription whose queue overflows is ENDED with a reason, loudly, and the
+* other subscriptions are untouched.
+*
+* ## The PREBUFFER (phase 3)
+*
+* HKSV asks for context BEFORE the trigger — `CameraRecordingOptions.prebufferLength`
+* is a HAP-mandated minimum of 4000 ms — and a subscriber that attaches at the
+* motion edge has none. So the plane optionally retains the last few fragments
+* and replays them to a subscriber that asks for them.
+*
+* Three things this ring gets right, each of which is a measured fact rather
+* than a preference (see [D84](../../../../docs/decisions/adr-0084.md)):
+*
+*  - **It is bounded by TIME *and* BYTES.** On the live fleet a 720p copy
+*    fragment is ~255 KB and a 4K one is ~6.35 MB — a 25× spread over the same
+*    window. A time-only bound is a per-camera RAM figure nobody can predict.
+*  - **The window is measured on ARRIVAL, not parsed from `tfdt`.** The
+*    splitter deliberately never computes a fragment's duration (a second
+*    opinion about a fact the muxer owns), and a prebuffer cares about how long
+*    ago the bytes turned up, which is exactly what arrival time answers.
+*  - **A replay is not backlog.** A subscriber taking N retained fragments gets
+*    its queue capacity raised by N for them, because closing a subscriber as a
+*    slow consumer for the prebuffer it explicitly asked for would be the
+*    stupidest possible failure — and, with `DEFAULT_QUEUE_CAPACITY` of 4 and a
+*    ring of 4, the guaranteed one.
+*
+* ## `isLast`
+*
+* hap-nodejs requires the delegate to mark exactly one `RecordingPacket` with
+* `isLast` — a generator that finishes without it produces the twelve-second
+* timeout loop [D50](../../../../../docs/decisions/adr-0050.md) deleted. The
+* plane therefore computes it at DELIVERY time: a packet is last when the plane
+* has ended and nothing remains queued behind it. A subscription that ends
+* having delivered NOTHING says so through {@link Fmp4Subscription.delivered};
+* the future delegate must not open an HDS stream it cannot feed.
+*/
+var DEFAULT_QUEUE_CAPACITY = 4;
+var Fmp4FragmentPlane = class {
+	logger;
+	prebuffer;
+	now;
+	subscriptions = /* @__PURE__ */ new Map();
+	/** The last init unit seen, handed to every later subscriber. */
+	retainedInit = null;
+	ended = false;
+	/** Oldest first. Empty unless {@link Fmp4PrebufferOptions} was supplied. */
+	ring = [];
+	ringBytes = 0;
+	constructor(logger, prebuffer, now = Date.now) {
+		this.logger = logger;
+		this.prebuffer = prebuffer;
+		this.now = now;
+	}
+	get subscriberCount() {
+		return this.subscriptions.size;
+	}
+	/** True once {@link end} has been called — no further units are accepted. */
+	get isEnded() {
+		return this.ended;
+	}
+	/** What the prebuffer ring holds right now. All zeroes when disabled. */
+	prebufferStats() {
+		const oldest = this.ring[0];
+		return {
+			fragments: this.ring.length,
+			bytes: this.ringBytes,
+			spanMs: oldest === void 0 ? 0 : this.now() - oldest.arrivedAt
+		};
+	}
+	subscribe(input) {
+		const replay = input.withPrebuffer === true ? this.trimmedRing() : [];
+		const requested = Math.max(1, input.queueCapacity ?? DEFAULT_QUEUE_CAPACITY);
+		const sub = {
+			id: `fmp4-${randomUUID()}`,
+			tag: input.tag,
+			subscribedAt: this.now(),
+			capacity: requested + replay.length,
+			queue: [],
+			delivered: 0,
+			closedReason: null,
+			wake: null,
+			iterating: false
+		};
+		this.subscriptions.set(sub.id, sub);
+		if (this.retainedInit !== null) this.enqueue(sub, this.retainedInit);
+		for (const retained of replay) this.enqueue(sub, retained.unit);
+		if (this.ended) this.closeSubscription(sub, "ended");
+		this.logger?.info("fmp4 plane: subscribed", { meta: {
+			subscriptionId: sub.id,
+			tag: sub.tag,
+			hasRetainedInit: this.retainedInit !== null,
+			prebufferFragments: replay.length,
+			prebufferBytes: replay.reduce((n, r) => n + r.unit.data.length, 0)
+		} });
+		return this.facade(sub);
+	}
+	/**
+	* Fan one splitter unit out. An `init` REPLACES the retained one — ffmpeg
+	* emits exactly one per child, and a second means the child was respawned, in
+	* which case the old one describes a stream that no longer exists.
+	*/
+	publish(unit) {
+		if (this.ended) return;
+		if (unit.kind === "init") {
+			this.retainedInit = unit;
+			this.ring.length = 0;
+			this.ringBytes = 0;
+		} else this.retain(unit);
+		for (const sub of this.subscriptions.values()) {
+			if (sub.closedReason !== null) continue;
+			this.enqueue(sub, unit);
+		}
+	}
+	/**
+	* The producer stopped. Every subscriber drains what it holds; its final
+	* packet carries `isLast`, and its generator then completes.
+	*/
+	end(reason = "producer ended") {
+		if (this.ended) return;
+		this.ended = true;
+		this.logger?.info("fmp4 plane: ended", { meta: {
+			reason,
+			subscribers: this.subscriptions.size
+		} });
+		for (const sub of this.subscriptions.values()) if (sub.closedReason === null) this.closeSubscription(sub, "ended");
+	}
+	listSubscribers() {
+		return [...this.subscriptions.values()].map((s) => ({
+			tag: s.tag,
+			subscribedAt: s.subscribedAt,
+			delivered: s.delivered,
+			closedReason: s.closedReason
+		}));
+	}
+	/** End and forget everything. Idempotent. */
+	dispose() {
+		this.end("disposed");
+		this.subscriptions.clear();
+		this.retainedInit = null;
+		this.ring.length = 0;
+		this.ringBytes = 0;
+	}
+	/**
+	* Add one fragment to the ring and evict from the front until BOTH bounds
+	* hold. Eviction is oldest-first, which is the one place in this file where
+	* dropping is correct: the ring is context, not stream — nobody is mid-decode
+	* on it, and a subscriber only ever receives a contiguous tail of it.
+	*/
+	retain(unit) {
+		const prebuffer = this.prebuffer;
+		if (prebuffer === void 0) return;
+		const arrivedAt = this.now();
+		this.ring.push({
+			unit,
+			arrivedAt
+		});
+		this.ringBytes += unit.data.length;
+		const cutoff = arrivedAt - prebuffer.windowMs;
+		while (this.ring.length > 0) {
+			const oldest = this.ring[0];
+			if (oldest === void 0) break;
+			const tooOld = oldest.arrivedAt < cutoff;
+			const tooBig = this.ringBytes > prebuffer.maxBytes;
+			if (!tooOld && !tooBig || this.ring.length === 1) break;
+			this.ring.shift();
+			this.ringBytes -= oldest.unit.data.length;
+		}
+	}
+	/**
+	* The ring as a subscriber should receive it — window applied AT SUBSCRIBE
+	* time, not only at publish time. A camera that went quiet keeps its last
+	* fragment in the ring indefinitely (see the never-evict-the-newest rule),
+	* and replaying a 40-second-old fragment as "prebuffer" would put stale video
+	* at the head of a clip iOS presents as the moment of the event.
+	*/
+	trimmedRing() {
+		const prebuffer = this.prebuffer;
+		if (prebuffer === void 0) return [];
+		const cutoff = this.now() - prebuffer.windowMs;
+		return this.ring.filter((r) => r.arrivedAt >= cutoff);
+	}
+	enqueue(sub, unit) {
+		if (sub.queue.length >= sub.capacity) {
+			this.logger?.warn("fmp4 plane: subscriber fell behind — CLOSING it rather than gapping it", { meta: {
+				subscriptionId: sub.id,
+				tag: sub.tag,
+				capacity: sub.capacity,
+				delivered: sub.delivered
+			} });
+			this.closeSubscription(sub, "slow-consumer");
+			return;
+		}
+		sub.queue.push({
+			kind: unit.kind,
+			data: unit.data,
+			sequence: unit.sequence,
+			isLast: false
+		});
+		this.wake(sub);
+	}
+	closeSubscription(sub, reason) {
+		if (sub.closedReason !== null) return;
+		sub.closedReason = reason;
+		if (reason === "slow-consumer") sub.queue.length = 0;
+		this.wake(sub);
+	}
+	wake(sub) {
+		const resume = sub.wake;
+		sub.wake = null;
+		resume?.();
+	}
+	facade(sub) {
+		const plane = this;
+		return {
+			id: sub.id,
+			tag: sub.tag,
+			get delivered() {
+				return sub.delivered;
+			},
+			get closedReason() {
+				return sub.closedReason;
+			},
+			packets: () => plane.iterate(sub),
+			release: () => {
+				plane.closeSubscription(sub, "released");
+				plane.subscriptions.delete(sub.id);
+			}
+		};
+	}
+	async *iterate(sub) {
+		if (sub.iterating) throw new Error(`fmp4 plane: subscription ${sub.tag} is already being consumed — take a second subscription`);
+		sub.iterating = true;
+		for (;;) {
+			const next = sub.queue.shift();
+			if (next === void 0) {
+				if (sub.closedReason !== null) return;
+				await new Promise((resolve) => {
+					sub.wake = resolve;
+				});
+				continue;
+			}
+			const isLast = sub.closedReason === "ended" && sub.queue.length === 0;
+			sub.delivered += 1;
+			yield {
+				...next,
+				isLast
+			};
+			if (isLast) return;
+		}
+	}
+};
+var DEFAULT_FIRST_UNIT_TIMEOUT_MS = 12e3;
+/** Heartbeat cadence — ~2 minutes of 4 s fragments. */
+var FRAGMENT_LOG_EVERY = 30;
+var Fmp4FragmentChild = class {
+	deps;
+	args;
+	child = null;
+	splitter = new Fmp4BoxSplitter();
+	stopped = false;
+	unitsOut = 0;
+	activeHwAccel = null;
+	constructor(deps, args) {
+		this.deps = deps;
+		this.args = args;
+	}
+	/** Spawn, and resolve once the INIT segment has been cut out of stdout. */
+	async start() {
+		const requested = this.args.invocation.decodeHwAccel;
+		this.activeHwAccel = requested;
+		try {
+			await this.spawnAttempt(requested);
+			return;
+		} catch (err) {
+			if (this.stopped) throw err;
+			if (requested === null || isSoftwareDecode(requested)) throw err;
+			this.deps.logger.warn("fmp4 fragment child: hardware decode produced NO fragment — retrying in SOFTWARE", {
+				tags: { deviceId: this.args.deviceId },
+				meta: {
+					sourceId: this.args.sourceId,
+					decodeHwAccel: requested,
+					error: errMsg$12(err)
+				}
+			});
+			this.killChild();
+			this.splitter = new Fmp4BoxSplitter();
+			this.activeHwAccel = null;
+			await this.spawnAttempt(null);
+		}
+	}
+	/** The backend the child ACTUALLY ran with — `null` for software. */
+	activeDecodeHwAccel() {
+		const value = this.activeHwAccel;
+		return value === null || value === "none" || value === "copy" ? null : value;
+	}
+	/** Kill ffmpeg and end the plane. Idempotent. */
+	async stop() {
+		if (this.stopped) return;
+		this.stopped = true;
+		this.killChild();
+		this.args.plane.end("the fragment child stopped");
+	}
+	spawnAttempt(decodeHwAccel) {
+		const args = buildFfmpegArgs({
+			...this.args.invocation,
+			decodeHwAccel,
+			sink: {
+				kind: "stdout",
+				container: "mp4",
+				fragmentMs: this.args.fragmentMs
+			}
+		});
+		this.deps.logger.info("fmp4 fragment child: spawning ffmpeg", {
+			tags: { deviceId: this.args.deviceId },
+			meta: {
+				sourceId: this.args.sourceId,
+				fragmentMs: this.args.fragmentMs,
+				decodeHwAccel: decodeHwAccel ?? "software",
+				argv: args.join(" ")
+			}
+		});
+		return new Promise((resolve, reject) => {
+			const child = this.deps.spawnFn(this.deps.ffmpegBinaryPath, args, { stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			] });
+			this.child = child;
+			let settled = false;
+			/**
+			* This attempt FAILED. Set before the kill, because SIGTERM makes the
+			* child exit and that exit must not be reported as a death: the retry —
+			* or the caller's rejection — already owns what happens next. Without it
+			* the timeout path ends the plane the software retry is about to fill,
+			* and the consumer sees a stream that stopped for no reason. A "which
+			* spawn is current" counter does NOT cover this: the retry has not been
+			* spawned when the kill's exit arrives.
+			*/
+			let failed = false;
+			/**
+			* This attempt is still the live producer: it has not failed (a failure
+			* hands ownership to the retry, or to the caller's rejection) and nothing
+			* has stopped the child. Those two cover every way an attempt stops being
+			* current — `start` only respawns after a rejection.
+			*/
+			const isCurrent = () => !this.stopped && !failed;
+			const timeoutMs = this.deps.firstUnitTimeoutMs ?? DEFAULT_FIRST_UNIT_TIMEOUT_MS;
+			const settle = (fail) => {
+				if (settled) return;
+				settled = true;
+				clearTimeout(timer);
+				if (fail) {
+					failed = true;
+					reject(fail);
+				} else resolve();
+			};
+			const timer = setTimeout(() => {
+				settle(/* @__PURE__ */ new Error(`fmp4 fragment child: no fragment within ${timeoutMs}ms`));
+				this.killChild();
+			}, timeoutMs);
+			timer.unref?.();
+			child.stdout?.on("data", (chunk) => {
+				for (const unit of this.splitter.push(chunk)) {
+					this.unitsOut += 1;
+					this.args.plane.publish(unit);
+					if (unit.kind === "init") {
+						this.deps.logger.info("fmp4 fragment child: INIT segment cut", {
+							tags: { deviceId: this.args.deviceId },
+							meta: {
+								sourceId: this.args.sourceId,
+								bytes: unit.data.length
+							}
+						});
+						settle();
+					} else if (this.unitsOut % FRAGMENT_LOG_EVERY === 0) this.deps.logger.info("fmp4 fragment child: fragments still flowing", {
+						tags: { deviceId: this.args.deviceId },
+						meta: {
+							sourceId: this.args.sourceId,
+							unitsOut: this.unitsOut,
+							bytes: unit.data.length,
+							subscribers: this.args.plane.subscriberCount
+						}
+					});
+				}
+				const fault = this.splitter.fault;
+				if (fault !== null) this.onFault(fault, settled, isCurrent(), settle);
+			});
+			child.stderr?.setEncoding("utf8");
+			child.stderr?.on("data", (line) => {
+				this.deps.logger.debug("fmp4 fragment child ffmpeg", {
+					tags: { deviceId: this.args.deviceId },
+					meta: {
+						sourceId: this.args.sourceId,
+						line: line.trim()
+					}
+				});
+			});
+			child.once("error", (err) => {
+				if (!settled) {
+					settle(err);
+					return;
+				}
+				if (!isCurrent()) return;
+				this.args.plane.end("the fragment child errored");
+				this.deps.onChildExit?.(err);
+			});
+			child.once("exit", (code, signal) => {
+				if (!settled) {
+					settle(/* @__PURE__ */ new Error(`fmp4 fragment child: ffmpeg exited before any fragment (code=${code} signal=${signal})`));
+					return;
+				}
+				if (!isCurrent()) return;
+				const error = /* @__PURE__ */ new Error(`fmp4 fragment child: ffmpeg exited while live (code=${code} signal=${signal})`);
+				this.deps.logger.warn("fmp4 fragment child: ffmpeg exited while live", {
+					tags: { deviceId: this.args.deviceId },
+					meta: {
+						sourceId: this.args.sourceId,
+						code,
+						signal,
+						unitsOut: this.unitsOut
+					}
+				});
+				this.args.plane.end("the fragment child exited");
+				this.deps.onChildExit?.(error);
+			});
+		});
+	}
+	/**
+	* The byte stream stopped being splittable. Not recoverable — the splitter
+	* cannot resynchronise mid-box — so the child is a corpse and every consumer
+	* has to be told, loudly, with the reason.
+	*/
+	onFault(reason, wasLive, current, settle) {
+		const error = /* @__PURE__ */ new Error(`fmp4 fragment child: ${reason}`);
+		this.deps.logger.error("fmp4 fragment child: the ffmpeg output stopped parsing as fMP4", {
+			tags: { deviceId: this.args.deviceId },
+			meta: {
+				sourceId: this.args.sourceId,
+				unitsOut: this.unitsOut,
+				interstitial: this.splitter.discardedInterstitialTypes,
+				reason
+			}
+		});
+		this.killChild();
+		settle(error);
+		if (wasLive && current) {
+			this.args.plane.end("the fragment child produced unsplittable output");
+			this.deps.onChildExit?.(error);
+		}
+	}
+	killChild() {
+		const child = this.child;
+		this.child = null;
+		if (child && !child.killed) try {
+			child.kill("SIGTERM");
+		} catch (err) {
+			this.deps.logger.warn("fmp4 fragment child: kill error", {
+				tags: { deviceId: this.args.deviceId },
+				meta: {
+					sourceId: this.args.sourceId,
+					error: errMsg$12(err)
+				}
+			});
+		}
+	}
+};
 //#endregion
 //#region src/accessory-publisher.ts
 /**
@@ -42634,9 +43696,18 @@ async function buildIntercom(input) {
 *    (`proxy.motion.isDetected({})`) when the motion cap is bound.
 */
 var RESET_DEBOUNCE_MS = 5e3;
-async function buildMotionSensor(bctx) {
+/**
+* @param existing - The controller's OWN `MotionSensor`, when HomeKit Secure
+*  Video is advertised. HKSV derives its `EventTriggerOption.MOTION` from the
+*  service the `CameraController` created (`sensors: { motion: true }`) and is
+*  blind to any other one — a second MotionSensor added here would keep working
+*  as a sensor in the Home app while silently triggering no recording at all.
+*  `null` when recording is off, in which case this builder owns the service as
+*  it always has.
+*/
+async function buildMotionSensor(bctx, existing = null) {
 	const { ctx, accessory, proxy, numericDeviceId, displayName } = bctx;
-	const motionService = accessory.addService(Service.MotionSensor, hapServiceName([displayName], `Camera ${numericDeviceId}`));
+	const motionService = existing ?? accessory.addService(Service.MotionSensor, hapServiceName([displayName], `Camera ${numericDeviceId}`));
 	motionService.setCharacteristic(Characteristic.MotionDetected, false);
 	try {
 		const detected = await proxy.motion?.isDetected({});
@@ -43032,6 +44103,814 @@ async function probe(call, label, log) {
 	}
 }
 //#endregion
+//#region src/hksv/recording-options.ts
+/**
+* The HomeKit Secure Video ADVERTISEMENT — `CameraRecordingOptions`, derived
+* from what the fMP4 sink will actually produce for THIS camera.
+*
+* ## The rule this file exists to enforce
+*
+* Never advertise something we cannot serve. That is not a slogan here: it is
+* the diagnosis of [D50](../../../../docs/decisions/adr-0050.md) — an
+* advertised `recording` whose delegate yielded nothing put every motion-capable
+* camera into a ~12 s timeout loop every 20-60 s, all day. So every number below
+* is derived from the picked source (`recording-source.ts`) or from a measured
+* property of the sink, and none of them is a plausible-looking constant.
+*
+* ## The fragment length is the subtle one
+*
+* HKSV requires every media fragment to be **no longer** than the length the
+* controller selected. On the copy branch the fragment length is the SOURCE's
+* key-frame cadence ([D80](../../../../docs/decisions/adr-0080.md)) — we do not
+* get to choose it, we can only be honest about it. So:
+*
+*  - when the camera reports its GOP (`stream-params`), the advertised length is
+*    the smallest offered value that COVERS it;
+*  - when it does not, we advertise the 4000 ms every HKSV camera uses and the
+*    delegate warns at `warn` with `tags: { deviceId }` if the fragments that
+*    actually arrive are longer.
+*
+* A camera whose GOP exceeds the longest value we offer does not advertise
+* recording at all. See {@link deriveFragmentLengthMs}.
+*/
+/**
+* The prebuffer we promise. HAP's floor is 4000 ms and its documented sensible
+* range is [4000, 8000]; the plane's ring is sized from this, so the two cannot
+* disagree. Asking for more than we retain would be the same lie in the other
+* direction.
+*/
+var HKSV_PREBUFFER_MS = 4e3;
+/**
+* The fragment lengths we are willing to advertise, shortest first. 4000 ms is
+* what every shipping HKSV camera uses; 8000 exists for a camera whose GOP is
+* 8 s, which is common enough on this fleet's defaults to be worth covering
+* rather than refusing.
+*/
+var HKSV_FRAGMENT_LENGTHS_MS = [4e3, 8e3];
+/**
+* AAC-LC at 24 kHz mono. Fixed rather than negotiated: an fMP4 fragment carries
+* its audio in-band, so unlike the live SRTP path there is no second plane on
+* which to answer a different sample rate, and D80 records that HKSV takes AAC
+* and nothing else.
+*/
+var HKSV_AUDIO_SAMPLE_RATE_HZ = 24e3;
+/**
+* The advertised fragment length for a camera whose key-frame cadence is
+* `sourceGopMs`, or `null` when no offered length covers it.
+*
+* `undefined` — the camera does not report a GOP — takes the shortest offered
+* length. That is a guess, and it is the RIGHT guess (4 s is the near-universal
+* default), but it is a guess: the delegate measures the arriving cadence and
+* says so when reality disagrees.
+*/
+function deriveFragmentLengthMs(sourceGopMs) {
+	const shortest = HKSV_FRAGMENT_LENGTHS_MS[0];
+	if (shortest === void 0) return null;
+	if (sourceGopMs === void 0 || sourceGopMs <= 0) return shortest;
+	return HKSV_FRAGMENT_LENGTHS_MS.find((ms) => ms >= sourceGopMs) ?? null;
+}
+/**
+* Build the advertisement.
+*
+* ONE resolution is advertised — the one slot the recording child pulls. HAP's
+* documentation lists 1920×1080 and 1280×720 as "required to be supported", and
+* listing both when the source is only one of them is precisely the D50 failure
+* in miniature: iOS would select a configuration we then cannot deliver, on the
+* copy branch, with no encoder to resize with.
+*/
+function buildRecordingOptions(input) {
+	const resolution = [
+		input.width,
+		input.height,
+		Math.max(1, Math.round(input.fps))
+	];
+	return {
+		prebufferLength: HKSV_PREBUFFER_MS,
+		mediaContainerConfiguration: {
+			type: MediaContainerType.FRAGMENTED_MP4,
+			fragmentLength: input.fragmentLengthMs
+		},
+		video: {
+			type: VideoCodecType.H264,
+			parameters: {
+				profiles: [
+					H264Profile.BASELINE,
+					H264Profile.MAIN,
+					H264Profile.HIGH
+				],
+				levels: [
+					H264Level.LEVEL3_1,
+					H264Level.LEVEL3_2,
+					H264Level.LEVEL4_0
+				]
+			},
+			resolutions: [resolution]
+		},
+		audio: { codecs: [{
+			type: AudioRecordingCodecType.AAC_LC,
+			audioChannels: 1,
+			bitrateMode: AudioBitrate.VARIABLE,
+			samplerate: [AudioRecordingSamplerate.KHZ_24]
+		}] }
+	};
+}
+//#endregion
+//#region src/hksv/fragment-source.ts
+/**
+* How far back the prebuffer ring reaches.
+*
+* Twice {@link HKSV_PREBUFFER_MS}, and the factor is structural rather than
+* generous: the ring holds WHOLE fragments, so a window of exactly 4 s can hold
+* a single 4 s fragment that is about to age out — a trigger landing a moment
+* later would replay nothing. Two fragment lengths guarantee at least one
+* covering fragment at every instant.
+*/
+var PREBUFFER_WINDOW_MS = HKSV_PREBUFFER_MS * 2;
+/**
+* The ring's hard byte ceiling, per camera.
+*
+* Measured fragment sizes on this fleet: ~145 KB for 4 s at 720p, ~3.6 MB for
+* 4 s at 4K. 16 MB covers two 4K fragments with room and bounds the exporter's
+* heap at a figure an operator can multiply by the camera count — which is the
+* number a time-only bound refuses to give.
+*/
+var PREBUFFER_MAX_BYTES = 16 * 1024 * 1024;
+/** Backoff after a child that died while live. Bounded, never a tight loop. */
+var RESPAWN_BACKOFF_MS = [
+	2e3,
+	5e3,
+	15e3,
+	3e4
+];
+var HksvFragmentSource = class {
+	input;
+	plane = null;
+	child = null;
+	stopped = false;
+	starting = null;
+	respawnAttempt = 0;
+	respawnTimer = null;
+	audioActive;
+	log;
+	constructor(input) {
+		this.input = input;
+		this.audioActive = input.audioActive;
+		this.log = input.logger;
+	}
+	/** True once a child has produced its initialisation segment. */
+	get isRunning() {
+		return this.child !== null && this.plane !== null && !this.plane.isEnded;
+	}
+	/**
+	* Spawn the child and start filling the ring. Idempotent, and concurrent
+	* calls share one attempt — `updateRecordingActive(true)` and a stream
+	* request can arrive in either order.
+	*/
+	async start() {
+		if (this.stopped) throw new Error("hksv fragment source: already stopped");
+		if (this.isRunning) return;
+		const inflight = this.starting;
+		if (inflight !== null) return inflight;
+		const attempt = this.spawn();
+		this.starting = attempt;
+		try {
+			await attempt;
+		} finally {
+			this.starting = null;
+		}
+	}
+	/** Stop the child, end the plane, forget the ring. Idempotent. */
+	async stop(reason) {
+		if (this.stopped) return;
+		this.stopped = true;
+		this.clearRespawn();
+		this.log.info("hksv fragment source: stopping", {
+			tags: { deviceId: this.input.deviceId },
+			meta: {
+				reason,
+				brokerId: this.input.source.brokerId
+			}
+		});
+		const child = this.child;
+		this.child = null;
+		if (child) await child.stop();
+		this.plane?.dispose();
+		this.plane = null;
+	}
+	/**
+	* iOS turned recording audio on or off. Respawns onto the other url when it
+	* genuinely changed — the fragments themselves must carry or omit the track,
+	* there is nothing to strip downstream.
+	*/
+	async setAudioActive(active) {
+		if (active === this.audioActive) return;
+		this.audioActive = active;
+		this.log.info("hksv fragment source: RecordingAudioActive changed — respawning the child", {
+			tags: { deviceId: this.input.deviceId },
+			meta: {
+				audioActive: active,
+				brokerId: this.input.source.brokerId
+			}
+		});
+		if (!this.isRunning) return;
+		const child = this.child;
+		this.child = null;
+		if (child) await child.stop();
+		this.plane?.dispose();
+		this.plane = null;
+		await this.start();
+	}
+	/**
+	* Subscribe to the live fragments, replaying the prebuffer first.
+	*
+	* Returns `null` when there is no plane — the caller MUST treat that as
+	* "cannot serve this recording" rather than opening an HDS stream it cannot
+	* feed, which is the D50 failure exactly.
+	*/
+	subscribe(tag) {
+		const plane = this.plane;
+		if (plane === null || plane.isEnded) return null;
+		const stats = plane.prebufferStats();
+		this.log.info("hksv fragment source: subscribing a recording stream", {
+			tags: { deviceId: this.input.deviceId },
+			meta: {
+				tag,
+				prebufferFragments: stats.fragments,
+				prebufferBytes: stats.bytes,
+				prebufferSpanMs: stats.spanMs
+			}
+		});
+		return plane.subscribe({
+			tag,
+			withPrebuffer: true
+		});
+	}
+	/** What the ring holds — surfaced so the delegate can log what it served. */
+	prebufferSpanMs() {
+		return this.plane?.prebufferStats().spanMs ?? 0;
+	}
+	async spawn() {
+		const plane = new Fmp4FragmentPlane(this.log.child("hksv-plane"), {
+			windowMs: PREBUFFER_WINDOW_MS,
+			maxBytes: PREBUFFER_MAX_BYTES
+		}, this.input.now ?? Date.now);
+		const child = new Fmp4FragmentChild({
+			logger: this.log.child("hksv-fmp4"),
+			ffmpegBinaryPath: this.input.ffmpegBinaryPath,
+			spawnFn: this.input.spawnFn,
+			onChildExit: (error) => this.onChildExit(error)
+		}, {
+			sourceId: `hksv/${this.input.deviceId}`,
+			deviceId: this.input.deviceId,
+			fragmentMs: this.input.fragmentMs,
+			invocation: this.buildInvocation(),
+			plane
+		});
+		this.plane = plane;
+		this.child = child;
+		try {
+			await child.start();
+			this.respawnAttempt = 0;
+			this.log.info("hksv fragment source: prebuffer running", {
+				tags: { deviceId: this.input.deviceId },
+				meta: {
+					brokerId: this.input.source.brokerId,
+					resolution: `${this.input.source.width}x${this.input.source.height}`,
+					fragmentMs: this.input.fragmentMs,
+					audioActive: this.audioActive,
+					windowMs: PREBUFFER_WINDOW_MS
+				}
+			});
+		} catch (err) {
+			this.plane = null;
+			this.child = null;
+			plane.dispose();
+			throw err;
+		}
+	}
+	/**
+	* The child died while live. The prebuffer is gone with it — and saying so is
+	* the point: a source that silently stopped filling reads, from the delegate,
+	* exactly like a camera nothing ever happens on.
+	*/
+	onChildExit(error) {
+		if (this.stopped) return;
+		this.child = null;
+		this.plane = null;
+		const delay = RESPAWN_BACKOFF_MS[Math.min(this.respawnAttempt, RESPAWN_BACKOFF_MS.length - 1)];
+		this.respawnAttempt += 1;
+		this.log.warn("hksv fragment source: the child DIED — the prebuffer is empty until it respawns", {
+			tags: { deviceId: this.input.deviceId },
+			meta: {
+				brokerId: this.input.source.brokerId,
+				attempt: this.respawnAttempt,
+				respawnInMs: delay,
+				error: error.message
+			}
+		});
+		this.clearRespawn();
+		const schedule = this.input.setTimeoutFn ?? setTimeout;
+		this.respawnTimer = schedule(() => {
+			this.respawnTimer = null;
+			if (this.stopped) return;
+			this.start().catch((err) => {
+				this.log.warn("hksv fragment source: respawn failed", {
+					tags: { deviceId: this.input.deviceId },
+					meta: {
+						brokerId: this.input.source.brokerId,
+						error: err instanceof Error ? err.message : String(err)
+					}
+				});
+			});
+		}, delay ?? 3e4);
+		this.respawnTimer?.unref?.();
+	}
+	clearRespawn() {
+		if (this.respawnTimer !== null) {
+			clearTimeout(this.respawnTimer);
+			this.respawnTimer = null;
+		}
+	}
+	/**
+	* The invocation, minus the sink the child owns.
+	*
+	* `kind: 'copy'` is not a preference: it is the 128× measurement, and it is
+	* why `pickRecordingSource` refuses a camera whose only slots are H.265. The
+	* audio IS encoded — the source mic is G.711/PCM depending on vendor and HKSV
+	* takes AAC only — which the same measurement priced at 0.4 % of a core.
+	*/
+	buildInvocation() {
+		const audio = this.audioActive ? {
+			kind: "encode",
+			codec: "aac",
+			bitrateKbps: 32,
+			sampleRateHz: HKSV_AUDIO_SAMPLE_RATE_HZ,
+			channels: 1
+		} : { kind: "none" };
+		return {
+			logLevel: "error",
+			decodeHwAccel: null,
+			input: {
+				url: this.audioActive ? this.input.source.url : this.input.source.mutedUrl,
+				rtspTransport: "tcp",
+				analyzeDurationUs: 1e6,
+				probeSizeBytes: 1e6
+			},
+			video: { kind: "copy" },
+			audio,
+			threadCount: 0,
+			outputArgs: []
+		};
+	}
+};
+//#endregion
+//#region src/hksv/recording-delegate.ts
+/**
+* `HDSProtocolSpecificErrorReason` is a `const enum`, so there is no reverse
+* map to index — and a bare number in the log is the difference between "iOS
+* closed it normally" and "iOS rejected our data", which is the whole reason
+* this line exists.
+*/
+var HDS_REASON_NAMES = {
+	[HDSProtocolSpecificErrorReason.NORMAL]: "normal",
+	[HDSProtocolSpecificErrorReason.NOT_ALLOWED]: "not-allowed",
+	[HDSProtocolSpecificErrorReason.BUSY]: "busy",
+	[HDSProtocolSpecificErrorReason.CANCELLED]: "cancelled",
+	[HDSProtocolSpecificErrorReason.UNSUPPORTED]: "unsupported",
+	[HDSProtocolSpecificErrorReason.UNEXPECTED_FAILURE]: "unexpected-failure",
+	[HDSProtocolSpecificErrorReason.TIMEOUT]: "timeout",
+	[HDSProtocolSpecificErrorReason.BAD_DATA]: "bad-data",
+	[HDSProtocolSpecificErrorReason.PROTOCOL_ERROR]: "protocol-error",
+	[HDSProtocolSpecificErrorReason.INVALID_CONFIGURATION]: "invalid-configuration"
+};
+function hdsReasonName(reason) {
+	return HDS_REASON_NAMES[reason] ?? `unknown(${String(reason)})`;
+}
+var HksvRecordingDelegate = class {
+	input;
+	active = false;
+	configuration = void 0;
+	source = null;
+	log;
+	/** The stream currently being yielded, so `closeRecordingStream` can end it. */
+	open = null;
+	constructor(input) {
+		this.input = input;
+		this.log = input.logger;
+	}
+	/** Test/diagnostic view — the prebuffer is running for this camera. */
+	get prebufferRunning() {
+		return this.source?.isRunning === true;
+	}
+	updateRecordingActive(active) {
+		if (active === this.active) return;
+		this.active = active;
+		this.log.info("hksv: recording active changed", {
+			tags: { deviceId: this.input.deviceId },
+			meta: {
+				active,
+				hasConfiguration: this.configuration !== void 0
+			}
+		});
+		this.reconcile("recording-active");
+	}
+	updateRecordingConfiguration(configuration) {
+		this.configuration = configuration;
+		if (configuration === void 0) {
+			this.log.info("hksv: the selected configuration was CLEARED — stopping the prebuffer", { tags: { deviceId: this.input.deviceId } });
+			this.reconcile("configuration-cleared");
+			return;
+		}
+		const selectedMs = configuration.mediaContainerConfiguration.fragmentLength;
+		this.log.info("hksv: iOS selected a recording configuration", {
+			tags: { deviceId: this.input.deviceId },
+			meta: {
+				fragmentLengthMs: selectedMs,
+				prebufferLengthMs: configuration.prebufferLength,
+				resolution: configuration.videoCodec.resolution.join("x"),
+				audioCodec: configuration.audioCodec.type,
+				eventTriggers: configuration.eventTriggerTypes
+			}
+		});
+		if (selectedMs < this.input.advertisedFragmentMs) this.log.warn("hksv: iOS selected a SHORTER fragment length than the source can cut", {
+			tags: { deviceId: this.input.deviceId },
+			meta: {
+				selectedMs,
+				advertisedMs: this.input.advertisedFragmentMs
+			}
+		});
+		this.reconcile("configuration-selected");
+	}
+	async *handleRecordingStreamRequest(streamId, signal) {
+		const source = this.source;
+		if (source === null || !source.isRunning) {
+			this.log.warn("hksv: recording stream requested with NO prebuffer running — refusing", {
+				tags: { deviceId: this.input.deviceId },
+				meta: {
+					streamId,
+					active: this.active,
+					hasConfiguration: this.configuration !== void 0
+				}
+			});
+			throw new HDSProtocolError(HDSProtocolSpecificErrorReason.NOT_ALLOWED);
+		}
+		const subscription = source.subscribe(`hksv/${this.input.deviceId}#${streamId}`);
+		if (subscription === null) {
+			this.log.warn("hksv: the fragment plane refused a subscription — refusing the stream", {
+				tags: { deviceId: this.input.deviceId },
+				meta: { streamId }
+			});
+			throw new HDSProtocolError(HDSProtocolSpecificErrorReason.NOT_ALLOWED);
+		}
+		this.open = {
+			streamId,
+			subscription
+		};
+		const startedAt = Date.now();
+		const prebufferSpanMs = source.prebufferSpanMs();
+		let packets = 0;
+		let bytes = 0;
+		let markedLast = false;
+		let longestFragmentGapMs = 0;
+		let lastPacketAt = startedAt;
+		try {
+			for await (const packet of subscription.packets()) {
+				if (signal?.aborted === true) {
+					this.log.info("hksv: the recording stream was aborted — ending the generator", {
+						tags: { deviceId: this.input.deviceId },
+						meta: {
+							streamId,
+							packets
+						}
+					});
+					return;
+				}
+				packets += 1;
+				bytes += packet.data.length;
+				if (packet.kind === "fragment") {
+					const now = Date.now();
+					longestFragmentGapMs = Math.max(longestFragmentGapMs, now - lastPacketAt);
+					lastPacketAt = now;
+				}
+				markedLast = markedLast || packet.isLast;
+				yield {
+					data: Buffer.from(packet.data),
+					isLast: packet.isLast
+				};
+				if (packet.isLast) return;
+			}
+			if (!markedLast && subscription.closedReason !== "released") {
+				this.log.warn("hksv: the fragment stream ended without a final packet", {
+					tags: { deviceId: this.input.deviceId },
+					meta: {
+						streamId,
+						packets,
+						closedReason: subscription.closedReason,
+						truncated: subscription.closedReason === "slow-consumer"
+					}
+				});
+				if (packets === 0) throw new HDSProtocolError(HDSProtocolSpecificErrorReason.UNEXPECTED_FAILURE);
+				yield {
+					data: Buffer.alloc(0),
+					isLast: true
+				};
+			}
+		} finally {
+			subscription.release();
+			if (this.open?.streamId === streamId) this.open = null;
+			const fragmentOverrun = longestFragmentGapMs > this.input.advertisedFragmentMs * 1.5;
+			this.log.info("hksv: recording stream finished", {
+				tags: { deviceId: this.input.deviceId },
+				meta: {
+					streamId,
+					packets,
+					bytes,
+					durationMs: Date.now() - startedAt,
+					prebufferSpanMs,
+					longestFragmentGapMs,
+					closedReason: subscription.closedReason,
+					markedLast
+				}
+			});
+			if (fragmentOverrun) this.log.warn("hksv: fragments arrived LONGER than the advertised length", {
+				tags: { deviceId: this.input.deviceId },
+				meta: {
+					longestFragmentGapMs,
+					advertisedMs: this.input.advertisedFragmentMs
+				}
+			});
+		}
+	}
+	acknowledgeStream(streamId) {
+		this.log.info("hksv: iOS acknowledged the end of stream — the clip landed", {
+			tags: { deviceId: this.input.deviceId },
+			meta: { streamId }
+		});
+	}
+	closeRecordingStream(streamId, reason) {
+		this.log.info("hksv: the recording stream was closed by the controller", {
+			tags: { deviceId: this.input.deviceId },
+			meta: {
+				streamId,
+				reason: reason === void 0 ? "connection-closed" : hdsReasonName(reason)
+			}
+		});
+		const open = this.open;
+		if (open?.streamId === streamId) {
+			open.subscription.release();
+			this.open = null;
+		}
+	}
+	/** Tear the prebuffer down — the accessory is being unexposed. */
+	async dispose() {
+		this.open?.subscription.release();
+		this.open = null;
+		const source = this.source;
+		this.source = null;
+		if (source) await source.stop("accessory disposed");
+	}
+	/**
+	* Start the prebuffer when iOS wants recording AND has chosen how, stop it
+	* otherwise. Called from every state edge rather than each edge deciding for
+	* itself: the two characteristics arrive in an order hap-nodejs explicitly
+	* does not guarantee, and a per-edge decision has to re-derive the same
+	* conjunction in two places.
+	*/
+	async reconcile(trigger) {
+		if (!(this.active && this.configuration !== void 0)) {
+			const source = this.source;
+			this.source = null;
+			if (source) await source.stop(`recording no longer wanted (${trigger})`);
+			return;
+		}
+		const configuration = this.configuration;
+		if (configuration === void 0) return;
+		const audioActive = this.input.isAudioActive();
+		const existing = this.source;
+		if (existing !== null) {
+			await existing.setAudioActive(audioActive);
+			if (!existing.isRunning) await existing.start();
+			return;
+		}
+		const source = this.input.createSource({
+			fragmentMs: configuration.mediaContainerConfiguration.fragmentLength,
+			audioActive
+		});
+		this.source = source;
+		try {
+			await source.start();
+		} catch (err) {
+			this.source = null;
+			this.log.error("hksv: the prebuffer FAILED to start — this camera will record nothing", {
+				tags: { deviceId: this.input.deviceId },
+				meta: {
+					trigger,
+					error: err instanceof Error ? err.message : String(err)
+				}
+			});
+		}
+	}
+};
+//#endregion
+//#region src/hksv/recording-source.ts
+/** The tallest frame the recording path will hold in its prebuffer. */
+var MAX_RECORDING_HEIGHT = 1080;
+/** HKSV takes H.264 only — AAC audio and H.264 video, no negotiation. */
+var RECORDABLE_CODEC = "h264";
+/**
+* Pick the slot the recording child pulls.
+*
+* Deliberately NOT `pickPreferredRtspEntry`: that picker resolves the operator's
+* LIVE preference and, on `auto`, steers by the resolution iOS negotiated for a
+* live session — neither is a fact about recording, and on 615 it selects `mid`,
+* a 10 fps slot. Recording has one criterion, applied here and nowhere else:
+* the largest copyable frame that does not exceed {@link MAX_RECORDING_HEIGHT}.
+*/
+function pickRecordingSource(entries) {
+	const enabled = entries.filter((e) => e.enabled);
+	if (enabled.length === 0) return {
+		ok: false,
+		refusal: "no-enabled-stream"
+	};
+	const h264 = enabled.filter((e) => normaliseCodec(e.codec) === RECORDABLE_CODEC);
+	if (h264.length === 0) return {
+		ok: false,
+		refusal: "no-h264-stream"
+	};
+	const sized = h264.filter(hasUsableResolution);
+	if (sized.length === 0) return {
+		ok: false,
+		refusal: "no-resolution"
+	};
+	const withinCeiling = sized.filter((e) => height(e) <= MAX_RECORDING_HEIGHT);
+	const best = [...withinCeiling.length > 0 ? withinCeiling : sized].sort((a, b) => withinCeiling.length > 0 ? height(b) - height(a) : height(a) - height(b))[0];
+	if (best === void 0 || best.resolution === void 0) return {
+		ok: false,
+		refusal: "no-resolution"
+	};
+	return {
+		ok: true,
+		source: {
+			brokerId: best.brokerId,
+			profile: best.profile ?? best.brokerId,
+			url: best.url,
+			mutedUrl: best.mutedUrl,
+			width: best.resolution.width,
+			height: best.resolution.height
+		}
+	};
+}
+/** A one-line reason for the log — silence about a withdrawn service reads as a bug. */
+function refusalReason(refusal) {
+	switch (refusal) {
+		case "no-enabled-stream": return "the camera has no enabled RTSP profile";
+		case "no-h264-stream": return "every enabled profile is H.265 — HKSV takes H.264 only, and a permanent transcode costs 128x a copy";
+		case "no-resolution": return "no enabled profile declares a resolution, so nothing honest could be advertised";
+	}
+}
+function height(entry) {
+	return entry.resolution?.height ?? 0;
+}
+function hasUsableResolution(entry) {
+	const r = entry.resolution;
+	return r !== void 0 && r.width > 0 && r.height > 0;
+}
+/** Publishers spell H.265 four ways; the same normalisation the broker uses. */
+function normaliseCodec(codec) {
+	return (codec ?? "").toLowerCase().replace(/[.\s-]/g, "");
+}
+//#endregion
+//#region src/hksv/build-recording.ts
+/**
+* Assemble HomeKit Secure Video for one camera — the ADVERTISEMENT and the
+* DELEGATE, together, or neither.
+*
+* That pairing is the whole rule and it is why nothing shipped for HKSV before
+* this: `recording` is optional on `CameraControllerOptions`, and passing it IS
+* the entire user-visible change. There is no "phase 1 behind a flag" for an
+* advertisement — either iOS is offered a recording toggle backed by a delegate
+* that yields real fragments, or the services are not on the accessory at all
+* ([D50](../../../../docs/decisions/adr-0050.md)).
+*
+* So this returns `null` for every reason a camera cannot record, and each of
+* them is logged at `info`/`warn` with `tags: { deviceId }`. A withdrawn
+* capability that says nothing is indistinguishable from a bug — and on this
+* surface the operator's first question is always "why does 617 have it and 615
+* not?".
+*/
+/**
+* The ffmpeg on `PATH`, exactly as the live streaming path resolves it
+* (`camera-streams.ts` spawns `'ffmpeg'`). One resolution per addon, not two.
+*/
+var FFMPEG_BINARY = "ffmpeg";
+/** Fallback when nothing measured a rate for the picked slot. */
+var ASSUMED_RECORDING_FPS = 15;
+async function buildHksvRecording(input) {
+	const { bctx } = input;
+	const { ctx, numericDeviceId } = bctx;
+	const log = ctx.logger.withTags({ deviceId: numericDeviceId });
+	const entries = await readProfileEntries(bctx);
+	if (entries === null) {
+		log.warn("export-hap: HKSV withheld — could not read the camera profiles", {});
+		return null;
+	}
+	const choice = pickRecordingSource(entries);
+	if (!choice.ok) {
+		log.info("export-hap: HKSV withheld — no recordable stream", { meta: {
+			refusal: choice.refusal,
+			reason: refusalReason(choice.refusal)
+		} });
+		return null;
+	}
+	const source = choice.source;
+	const gopMs = await readSourceGopMs(bctx, source.width, source.height);
+	const fragmentLengthMs = deriveFragmentLengthMs(gopMs);
+	if (fragmentLengthMs === null) {
+		log.warn("export-hap: HKSV withheld — the camera key-frame interval is longer than any fragment length we advertise", { meta: {
+			gopMs,
+			brokerId: source.brokerId
+		} });
+		return null;
+	}
+	const fps = resolveFps(input.fpsByProfile, source.profile);
+	const options = buildRecordingOptions({
+		width: source.width,
+		height: source.height,
+		fps,
+		fragmentLengthMs
+	});
+	const delegate = new HksvRecordingDelegate({
+		logger: log,
+		deviceId: numericDeviceId,
+		isAudioActive: input.isAudioActive,
+		advertisedFragmentMs: fragmentLengthMs,
+		createSource: ({ fragmentMs, audioActive }) => new HksvFragmentSource({
+			logger: log,
+			deviceId: numericDeviceId,
+			ffmpegBinaryPath: FFMPEG_BINARY,
+			spawnFn: spawn,
+			source,
+			fragmentMs,
+			audioActive
+		})
+	});
+	log.info("export-hap: HKSV ADVERTISED — recording is offered for this camera", { meta: {
+		brokerId: source.brokerId,
+		profile: source.profile,
+		resolution: `${source.width}x${source.height}`,
+		fps,
+		fragmentLengthMs,
+		sourceGopMs: gopMs ?? "unknown"
+	} });
+	return {
+		options,
+		delegate,
+		dispose: () => delegate.dispose()
+	};
+}
+/** `cameraStreams.getProfileRtspEntries`, or `null` when the cap is unreachable. */
+async function readProfileEntries(bctx) {
+	try {
+		return await bctx.proxy.cameraStreams?.getProfileRtspEntries({}) ?? null;
+	} catch {
+		return null;
+	}
+}
+/**
+* The camera's own key-frame interval in ms, from `stream-params`, matched to
+* the picked slot BY RESOLUTION.
+*
+* By resolution and not by name on purpose: `stream-params` names its profiles
+* `main`/`sub`/`ext` while the broker names its slots `high`/`mid`/`low`, and
+* on 615 `ext` is the 1280×720 slot the broker calls `mid` — a name-based match
+* would silently read the 4K slot's GOP for a 720p recording.
+*
+* `undefined` when the cap is not bound, which is most non-Hikvision providers.
+*/
+async function readSourceGopMs(bctx, width, height) {
+	try {
+		const status = await bctx.proxy.streamParams?.getStatus({});
+		if (!status) return void 0;
+		for (const profile of [
+			status.main,
+			status.sub,
+			status.ext
+		]) {
+			if (!profile) continue;
+			if (profile.width !== width || profile.height !== height) continue;
+			const { gop, framerate } = profile;
+			if (gop === void 0 || gop <= 0 || framerate <= 0) return void 0;
+			return Math.round(gop / framerate * 1e3);
+		}
+		return;
+	} catch {
+		return;
+	}
+}
+function resolveFps(fpsByProfile, profile) {
+	return fpsByProfile.get(profile)?.fps ?? ASSUMED_RECORDING_FPS;
+}
+//#endregion
 //#region src/mappers/builders/child-switch.ts
 /**
 * Child-switch builder — turns a camstack accessory child device (siren,
@@ -43237,19 +45116,39 @@ async function buildCameraAccessory(input) {
 		displayName,
 		options
 	};
-	const streams = buildCameraStreamingDelegate(bctx, await probeAdvertisedVideoProfile(bctx));
+	const advertisedVideo = await probeAdvertisedVideoProfile(bctx);
+	const streams = buildCameraStreamingDelegate(bctx, advertisedVideo);
 	const handles = [];
 	if (capNames.has("intercom")) handles.push(await buildIntercom({
 		bctx,
 		streamingOptions: streams.streamingOptions
 	}));
+	const recordingEnabled = options.hapDeviceSettings.hksvRecording === true;
+	let recordingAudioActive = true;
+	const recording = recordingEnabled ? await buildHksvRecording({
+		bctx,
+		fpsByProfile: advertisedVideo.fpsByProfile,
+		isAudioActive: () => recordingAudioActive
+	}) : null;
 	const controller = new (isDoorbell ? DoorbellController : CameraController)({
 		delegate: streams.delegate,
 		streamingOptions: streams.streamingOptions,
-		cameraStreamCount: 2
+		cameraStreamCount: 2,
+		...recording === null ? {} : { recording },
+		...recording === null || !capNames.has("motion-detection") ? {} : { sensors: { motion: true } }
 	});
 	accessory.configureController(controller);
-	if (capNames.has("motion-detection")) handles.push(await buildMotionSensor(bctx));
+	if (recording !== null) {
+		handles.push({ dispose: () => recording.dispose() });
+		const audioCharacteristic = (controller.recordingManagement?.operatingModeService)?.getCharacteristic(Characteristic.RecordingAudioActive);
+		if (audioCharacteristic) {
+			recordingAudioActive = audioCharacteristic.value !== 0 && audioCharacteristic.value !== false;
+			audioCharacteristic.on("change", ({ newValue }) => {
+				recordingAudioActive = newValue !== 0 && newValue !== false;
+			});
+		}
+	}
+	if (capNames.has("motion-detection")) handles.push(await buildMotionSensor(bctx, recording === null ? null : controller.motionService ?? null));
 	if (isDoorbell && controller instanceof DoorbellController) handles.push(await buildDoorbell({
 		bctx,
 		controller
@@ -43494,7 +45393,10 @@ function syncStateToJson(map) {
 * intercom upload bridge, HomeKit Secure Video, recording, native
 * H.264 stream tap (currently uses RTSP + ffmpeg copy).
 */
-var DEFAULT_DEVICE_SETTINGS = { streamPreference: "auto" };
+var DEFAULT_DEVICE_SETTINGS = {
+	streamPreference: "auto",
+	hksvRecording: false
+};
 var HAP_STREAM_PREFERENCE_OPTIONS = [
 	{
 		value: "auto",
@@ -43769,7 +45671,10 @@ var ExportHapAddon = class extends BaseAddon {
 			options: {
 				ptzPulseMs: this.config.ptzPulseMs,
 				decodeMemos: this.decodeMemos,
-				hapDeviceSettings: { streamPreference: entrySettings.streamPreference ?? "auto" }
+				hapDeviceSettings: {
+					streamPreference: entrySettings.streamPreference ?? "auto",
+					hksvRecording: entrySettings.hksvRecording === true
+				}
 			}
 		});
 		for (const accessory of mapper.accessories) await publishStandalone(accessory, {
@@ -44044,6 +45949,7 @@ var ExportHapAddon = class extends BaseAddon {
 		const enabled = entry !== null;
 		const enabledKey = `hap:${deviceId}:enabled`;
 		const streamPreferenceKey = `hap:${deviceId}:streamPreference`;
+		const hksvKey = `hap:${deviceId}:hksvRecording`;
 		const mapper = this.exposed.get(String(deviceId)) ?? null;
 		const paired = mapper ? accessoryPaired(mapper.accessory) : false;
 		const name = entry?.displayName ?? `Device ${deviceId}`;
@@ -44111,6 +46017,19 @@ var ExportHapAddon = class extends BaseAddon {
 							equals: true
 						},
 						immediate: true
+					},
+					{
+						type: "boolean",
+						key: hksvKey,
+						label: "HomeKit recording (Secure Video)",
+						description: "Offer “Stream and Allow Recording” in iOS Home. Requires iCloud+ and a home hub. Keeps a continuous 8s prebuffer for this camera (~0.7% of one CPU core, H.264 sources only).",
+						style: "switch",
+						value: settings.hksvRecording === true,
+						showWhen: {
+							field: enabledKey,
+							equals: true
+						},
+						immediate: true
 					}
 				]
 			}]
@@ -44135,12 +46054,15 @@ var ExportHapAddon = class extends BaseAddon {
 		const wasEnabled = this.exposed.has(deviceIdStr);
 		const enabledKey = `hap:${deviceId}:enabled`;
 		const streamPreferenceKey = `hap:${deviceId}:streamPreference`;
+		const hksvKey = `hap:${deviceId}:hksvRecording`;
 		const enabledValue = enabledKey in patch ? Boolean(patch[enabledKey]) : wasEnabled;
 		const streamPreferenceRaw = streamPreferenceKey in patch ? patch[streamPreferenceKey] : current?.settings?.streamPreference;
 		const streamPreference = typeof streamPreferenceRaw === "string" && streamPreferenceRaw.trim().length > 0 ? streamPreferenceRaw : "auto";
+		const hksvRecording = hksvKey in patch ? Boolean(patch[hksvKey]) : current?.settings?.hksvRecording === true;
 		const nextSettings = {
 			...current?.settings ?? DEFAULT_DEVICE_SETTINGS,
-			streamPreference
+			streamPreference,
+			hksvRecording
 		};
 		if (!enabledValue) {
 			if (wasEnabled) await this.unexposeDevice(deviceIdStr);
@@ -44152,17 +46074,24 @@ var ExportHapAddon = class extends BaseAddon {
 			return { success: true };
 		}
 		const currentPref = current?.settings?.streamPreference ?? "auto";
+		const currentHksv = current?.settings?.hksvRecording === true;
 		await this.updateEntrySettings(deviceIdStr, nextSettings);
-		if (currentPref !== streamPreference) {
-			log.info("export-hap: streamPreference changed — refreshing accessory", { meta: {
-				from: currentPref,
-				to: streamPreference
+		if (currentPref !== streamPreference || currentHksv !== hksvRecording) {
+			log.info("export-hap: per-camera export settings changed — refreshing accessory", { meta: {
+				streamPreference: {
+					from: currentPref,
+					to: streamPreference
+				},
+				hksvRecording: {
+					from: currentHksv,
+					to: hksvRecording
+				}
 			} });
 			try {
 				await this.unexposeDevice(deviceIdStr, { clearPairing: false });
 				await this.exposeDevice(deviceIdStr);
 			} catch (err) {
-				log.warn("export-hap: failed to refresh accessory after streamPreference change", { meta: { error: errMsg(err) } });
+				log.warn("export-hap: failed to refresh accessory after a settings change", { meta: { error: errMsg(err) } });
 			}
 		}
 		return { success: true };