@camstack/addon-pipeline 1.2.46 → 1.2.48

package/dist/stream-broker/index.js

@@ -3,7 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_chunk = require("../chunk-emK7D4bc.js");
-const require_dist = require("../dist-CPfFUIl9.js");
+const require_dist = require("../dist-CksKE1Sn.js");
 const require_remote_restream = require("../remote-restream-CO36Sr30.js");
 const require_model_download_service_D8B_4ktF = require("../model-download-service-D8B-4ktF-7-YxE9Wx.js");
 let node_crypto = require("node:crypto");
@@ -3011,6 +3011,79 @@ function buildAudioCodecCapApi(api) {
 		flushEncode: (input) => router.flushEncode.mutate(input)
 	};
 }
+/**
+* Minimum gap between two re-dials of the same device. A re-dial costs a
+* ~2 s video interruption on every source of the camera; at the 30 s
+* reconcile cadence, an un-cooled loop against a camera whose audio genuinely
+* cannot come back would be a permanent stutter.
+*/
+var AUDIO_PLANE_REDIAL_COOLDOWN_MS = 5 * 6e4;
+var EMPTY_AUDIO_PLANE_STATE = {
+	disagreements: 0,
+	redials: 0,
+	lastRedialMs: 0,
+	gaveUp: false
+};
+/**
+* Decide what one pass should do. Pure: no clock, no I/O, no broker.
+*
+* `nowMs` is passed in rather than read so the cooldown is testable without
+* waiting five minutes for it.
+*/
+function decideAudioPlaneAction(observation, state, nowMs) {
+	switch (observation.kind) {
+		case "broker-muted":
+		case "no-live-source":
+		case "audio-present":
+		case "declared-off": return {
+			action: { kind: "none" },
+			nextState: EMPTY_AUDIO_PLANE_STATE
+		};
+		case "read-failed":
+		case "audio-unknown": return {
+			action: { kind: "none" },
+			nextState: state
+		};
+		case "declared-on": {
+			if (state.gaveUp) return {
+				action: { kind: "none" },
+				nextState: state
+			};
+			const disagreements = state.disagreements + 1;
+			if (disagreements < 2) return {
+				action: { kind: "await-second-pass" },
+				nextState: {
+					...state,
+					disagreements
+				}
+			};
+			if (state.redials >= 3) return {
+				action: { kind: "give-up" },
+				nextState: {
+					...state,
+					disagreements,
+					gaveUp: true
+				}
+			};
+			if (state.lastRedialMs > 0 && nowMs - state.lastRedialMs < 3e5) return {
+				action: { kind: "cooldown" },
+				nextState: {
+					...state,
+					disagreements: 2
+				}
+			};
+			return {
+				action: { kind: "redial" },
+				nextState: {
+					disagreements: 0,
+					redials: state.redials + 1,
+					lastRedialMs: nowMs,
+					gaveUp: false
+				}
+			};
+		}
+	}
+}
 //#endregion
 //#region src/stream-broker/stream-broker/dead-decode-backends.ts
 /**
@@ -5031,6 +5104,69 @@ var EgressTranscodeManager = class {
 		};
 	}
 };
+var EventMediaStore = class {
+	deps;
+	/** Insertion-ordered — `Map` iteration order IS the eviction order. */
+	items = /* @__PURE__ */ new Map();
+	totalBytes = 0;
+	constructor(deps = {}) {
+		this.deps = deps;
+	}
+	get size() {
+		return this.items.size;
+	}
+	get bytes() {
+		return this.totalBytes;
+	}
+	/** Store one artifact and return its handle. */
+	put(input) {
+		const now = this.deps.now ?? Date.now;
+		this.sweep();
+		const handle = `evm_${input.deviceId}_${(this.deps.makeId ?? defaultId)()}`;
+		this.items.set(handle, {
+			handle,
+			storedAt: now(),
+			...input
+		});
+		this.totalBytes += input.bytes.length;
+		const maxBytes = this.deps.maxBytes ?? 67108864;
+		while (this.totalBytes > maxBytes && this.items.size > 1) {
+			const oldest = this.items.keys().next().value;
+			if (oldest === void 0) break;
+			this.drop(oldest);
+		}
+		return handle;
+	}
+	/** Redeem a handle. `null` when it never existed or has expired. */
+	get(handle) {
+		this.sweep();
+		return this.items.get(handle) ?? null;
+	}
+	/** Drop everything — shutdown. */
+	clear() {
+		this.items.clear();
+		this.totalBytes = 0;
+	}
+	sweep() {
+		const now = (this.deps.now ?? Date.now)();
+		const ttl = this.deps.ttlMs ?? 3e5;
+		for (const [handle, item] of this.items) {
+			if (now - item.storedAt < ttl) break;
+			this.drop(handle);
+		}
+	}
+	drop(handle) {
+		const item = this.items.get(handle);
+		if (item === void 0) return;
+		this.items.delete(handle);
+		this.totalBytes -= item.bytes.length;
+	}
+};
+var counter = 0;
+function defaultId() {
+	counter += 1;
+	return `${Date.now().toString(36)}${counter.toString(36)}`;
+}
 //#endregion
 //#region src/stream-broker/webrtc/nal-utils.ts
 var NAL_START_CODE_4B = Buffer.from([
@@ -5555,6 +5691,46 @@ function pickClipProfile(assigned, requested) {
 	return null;
 }
 /**
+* The tallest rendition an event clip is cut from.
+*
+* 1080 and not 720: the attachment is native-resolution H.264 that nothing
+* re-encodes, and the operator asked for a clip they could actually watch. A
+* few seconds of 4K copy is megabytes, which is the difference between "every
+* notifier takes it" and "pushover drops it at 5 MiB".
+*/
+var EVENT_CLIP_MAX_HEIGHT = 1080;
+/**
+* The rendition an EVENT production should cut from — the opposite default to
+* {@link pickClipProfile}.
+*
+* `pickClipProfile` takes the cheapest assigned slot, which was right when a
+* notification attachment was a 480 px thumbnail with motion. It is wrong now:
+* on this fleet the cheapest slot is a 640×360 substream, and a gif derived
+* from it is the "de-pixellated" attachment the operator reported. So an event
+* production prefers the LARGEST H.264 rendition at or below
+* {@link EVENT_CLIP_MAX_HEIGHT}:
+*
+*  - **H.264, because that is what can be COPIED.** An H.265 slot forces a
+*    re-encode, which is both expensive and not universally playable on the
+*    phones notifications land on.
+*  - **At or below 1080p**, falling back to the smallest slot above it when a
+*    camera offers nothing else — a 4K-only camera still gets a clip, it just
+*    pays for it.
+*
+* `null` when no rendition qualifies; the caller then falls back to
+* `pickClipProfile` and the answer reports which was used.
+*/
+function pickBestClipProfile(candidates) {
+	const usable = candidates.filter((c) => normaliseCodec$1(c.codec) === "h264" && (c.height ?? 0) > 0 && (c.width ?? 0) > 0);
+	if (usable.length === 0) return null;
+	const within = usable.filter((c) => (c.height ?? 0) <= EVENT_CLIP_MAX_HEIGHT);
+	return [...within.length > 0 ? within : usable].sort((a, b) => within.length > 0 ? (b.height ?? 0) - (a.height ?? 0) : (a.height ?? 0) - (b.height ?? 0))[0]?.profile ?? null;
+}
+/** Publishers spell H.265 four ways; the same normalisation the broker uses. */
+function normaliseCodec$1(codec) {
+	return (codec ?? "").toLowerCase().replace(/[.\s-]/g, "");
+}
+/**
 * Placeholder packets ("RECONNECTING"/"SLEEPING" keyframes the broker pumps at
 * 1 Hz while no RTP flows) are a DIFFERENT resolution and parameter set —
 * muxing them into a clip corrupts the decode and produces a file that freezes
@@ -5611,6 +5787,33 @@ function windowAround(input) {
 	if (momentPts > newest.pts || momentPts < oldest.pts) return [];
 	return sliceFromKeyframe(video, startPts, endPts);
 }
+/**
+* What the selected window covers, in WALL CLOCK.
+*
+* The same anchoring {@link windowAround} selects by, and for the same reason:
+* `pts` is a stream clock with an arbitrary origin, so the only fixed point is
+* that the newest retained packet arrived (near enough) at `nowMs`. Every
+* earlier packet is `newest.pts − p.pts` milliseconds before it.
+*
+* This exists so a caller can say "the clip starts 4.1 s BEFORE the event"
+* instead of inferring it from a duration and a hope. A production whose
+* `fromTs` is after the event has no pre-roll, which is precisely the defect
+* that has to be visible rather than plausible.
+*/
+function windowCoverage(packets, window, nowMs) {
+	const video = decodableVideo(packets);
+	const newest = video[video.length - 1];
+	const first = window[0];
+	const last = window[window.length - 1];
+	if (newest === void 0 || first === void 0 || last === void 0) return {
+		fromTs: nowMs,
+		toTs: nowMs
+	};
+	return {
+		fromTs: nowMs - (newest.pts - first.pts),
+		toTs: nowMs - (newest.pts - last.pts)
+	};
+}
 /** True for an HEVC packet — the container flag and the demuxer both differ. */
 function isHevcPacket(packet) {
 	const codec = (packet?.codec ?? "h264").toLowerCase();
@@ -5643,12 +5846,78 @@ function toElementaryStream(window, sdpParameterSets) {
 	return Buffer.concat(parts);
 }
 var RENDER_TIMEOUT_MS = 2e4;
+/**
+* The widest an event clip is RE-ENCODED at — 720p.
+*
+* Only ever reached when the render already forced a decode (a speed other than
+* real time, or an H.265 source). At real time the width must stay the source's
+* own, because an identity scale is precisely what `clipCanCopy` looks for.
+*
+* Measured on a real 615 720p window, `-preset veryfast`: crf 23 at 1280 is
+* 254 KB and 0.23 s of encode, against the 922 KB the copy of the same window
+* carried. Capping wider renditions here costs nothing an operator can see on a
+* phone and keeps the burst bounded on a hub that is already busy.
+*/
+var EVENT_CLIP_ENCODE_MAX_WIDTH = 1280;
+/**
+* The width to render an event clip at, given what the source is and whether
+* the caller asked for real time.
+*
+* One function because two call sites have to agree: the mux and the
+* `copy`/`encode` the production REPORTS. They disagreed once already — a
+* reported mode that does not match the render is a log line that lies.
+*/
+function eventClipEncodeWidth(sourceWidth, speed) {
+	const source = Math.max(1, Math.round(sourceWidth));
+	if (speed === 1) return source;
+	return Math.min(source, EVENT_CLIP_ENCODE_MAX_WIDTH);
+}
+/**
+* Format a frame rate for an ffmpeg filter argument.
+*
+* `12 / 4` must reach the filter as `3` and `15 / 4` as `3.75`, not as a float
+* tail that `av_parse_video_rate` then has to guess at.
+*/
+function ffmpegRate(rate) {
+	return String(Math.round(rate * 1e3) / 1e3);
+}
+/**
+* Whether this render can COPY the camera's own H.264 instead of re-encoding it.
+*
+* The ring already holds the camera's elementary stream. Re-encoding it is only
+* ever necessary to change something, so the question is entirely "is anything
+* being changed":
+*
+*  - **A scale is a change.** Only when the caller asks for at least the
+*    source's own width is the `scale` filter an identity. `sourceWidth === 0`
+*    means nobody knows the source's width, and a copy would then be a guess —
+*    so it re-encodes, which is what it always did.
+*  - **A speed is a change.** `setpts` rewrites the timeline.
+*  - **H.265 is a change we WANT.** The mp4 lands on phones, and HEVC in an mp4
+*    is not universally playable there; transcoding an H.265 camera's clip to
+*    H.264 is the one case where the re-encode is the feature. (It is also why
+*    the clip ring remains the fallback for an H.265-only camera rather than
+*    something to delete.)
+*  - **A GIF is a re-encode by definition.**
+*
+* Copying is what makes a notification clip the camera's own 1280×720 picture
+* rather than `libx264 -crf 28` at 480 px — measured on 615, the same eleven
+* seconds are 224 KB copied against a visibly softer re-encode, and the gif
+* derived from it stops looking pixellated for the same reason.
+*/
+function clipCanCopy(input) {
+	if (input.format !== "mp4") return false;
+	if (input.hevc === true) return false;
+	if ((input.speed ?? 2) !== 1) return false;
+	return input.sourceWidth > 0 && input.maxWidth >= input.sourceWidth;
+}
 /** ffmpeg args for the chosen container, reading an annex-B stream from stdin. */
 function clipFfmpegArgs(input) {
 	const scale = `scale=${input.maxWidth}:-2:flags=lanczos`;
 	const demuxer = input.hevc === true ? "hevc" : "h264";
 	const speed = input.speed ?? 2;
 	const setpts = speed !== 1 ? `,setpts=PTS/${speed}` : "";
+	const gifSetpts = speed !== 1 ? `${setpts},fps=${ffmpegRate(input.fps * speed)}` : setpts;
 	if (input.format === "gif") return [
 		"-y",
 		"-f",
@@ -5656,13 +5925,28 @@ function clipFfmpegArgs(input) {
 		"-i",
 		"pipe:0",
 		"-filter_complex",
-		`[0:v]fps=${input.fps}${setpts},${scale},split[a][b];[a]palettegen=stats_mode=diff[p];[b][p]paletteuse=dither=bayer:bayer_scale=5:diff_mode=rectangle`,
+		`[0:v]fps=${ffmpegRate(input.fps)}${gifSetpts},${scale},split[a][b];[a]palettegen=stats_mode=diff[p];[b][p]paletteuse=dither=bayer:bayer_scale=5:diff_mode=rectangle`,
 		"-loop",
 		"0",
 		"-f",
 		"gif",
 		"pipe:1"
 	];
+	if (input.copyVideo === true) return [
+		"-y",
+		"-f",
+		demuxer,
+		"-i",
+		"pipe:0",
+		"-c:v",
+		"copy",
+		"-movflags",
+		"frag_keyframe+empty_moov",
+		"-an",
+		"-f",
+		"mp4",
+		"pipe:1"
+	];
 	return [
 		"-y",
 		"-f",
@@ -5676,7 +5960,7 @@ function clipFfmpegArgs(input) {
 		"-preset",
 		"veryfast",
 		"-crf",
-		"28",
+		"23",
 		"-pix_fmt",
 		"yuv420p",
 		"-movflags",
@@ -5699,9 +5983,17 @@ async function renderPreBufferClip(input) {
 	if (window.length === 0) throw new Error("pre-buffer holds no decodable video for this window");
 	return new Promise((resolve, reject) => {
 		const hevc = isHevcPacket(window[0]);
+		const copyVideo = clipCanCopy({
+			format: input.format,
+			maxWidth: input.maxWidth,
+			...input.speed !== void 0 ? { speed: input.speed } : {},
+			hevc,
+			sourceWidth: input.sourceWidth ?? 0
+		});
 		const proc = input.spawn(input.ffmpegPath ?? "ffmpeg", clipFfmpegArgs({
 			...input,
-			hevc
+			hevc,
+			copyVideo
 		}));
 		const chunks = [];
 		let stderrTail = "";
@@ -5744,6 +6036,142 @@ async function renderPreBufferClip(input) {
 		proc.stdin?.end();
 	});
 }
+/**
+* The factor the derive must apply ON TOP of the speed the mp4 already carries.
+*
+* The gif is derived from the muxed mp4, so if that mux already ran `setpts` at
+* the caller's `speed`, applying the absolute gif rate again would compound
+* them — a 4× gif beside a 2× video would come out at 8×. Discounting here is
+* what keeps {@link GIF_SPEED} an ABSOLUTE rate against real time whatever the
+* video does.
+*/
+function gifDeriveSpeed(gifSpeed, videoSpeed) {
+	if (!Number.isFinite(videoSpeed) || videoSpeed <= 0) return gifSpeed;
+	return gifSpeed / videoSpeed;
+}
+/** A derive that has not finished by now will not finish inside the drain. */
+var GIF_RENDER_TIMEOUT_MS = 2e4;
+/**
+* The filter chain. Extracted so a test can assert the palette pair without
+* spawning ffmpeg — an argv test cannot see quality, but it can see a filter
+* that somebody deleted.
+*/
+function gifFilterComplex(input) {
+	const speed = input.speed > 0 ? input.speed : 1;
+	if (speed === 1) return `[0:v]fps=${ffmpegRate(input.fps)},scale=${input.maxWidth}:-2:flags=lanczos,split[a][b];[a]palettegen=stats_mode=diff[p];[b][p]paletteuse=dither=bayer:bayer_scale=5:diff_mode=rectangle`;
+	return `[0:v]fps=${ffmpegRate(input.fps / speed)},setpts=PTS/${speed},fps=${ffmpegRate(input.fps)},scale=${input.maxWidth}:-2:flags=lanczos,split[a][b];[a]palettegen=stats_mode=diff[p];[b][p]paletteuse=dither=bayer:bayer_scale=5:diff_mode=rectangle`;
+}
+/** The full argv, for the same reason. */
+function gifFromMp4Args(input) {
+	return [
+		"-y",
+		"-v",
+		"error",
+		"-f",
+		"mp4",
+		"-i",
+		"pipe:0",
+		"-filter_complex",
+		gifFilterComplex(input),
+		"-loop",
+		"0",
+		"-f",
+		"gif",
+		"pipe:1"
+	];
+}
+/**
+* Derive the gif. `null` on every failure — a notification that lost its gif is
+* a notification, and one that failed is not.
+*
+* The child is guaranteed dead before this settles: these run on every
+* notification that asks for a gif, and a leaked ffmpeg accumulates on the node
+* until somebody notices the host is slow.
+*/
+async function gifFromMp4(input) {
+	const args = gifFromMp4Args({
+		maxWidth: input.maxWidth ?? 640,
+		fps: input.fps ?? 12,
+		speed: input.speed ?? 4
+	});
+	const startedAt = Date.now();
+	try {
+		const bytes = await runGif(input, args);
+		input.logger?.info("nc gif: derived from the notification video", {
+			tags: { deviceId: input.deviceId },
+			meta: {
+				sourceBytes: input.mp4.length,
+				gifBytes: bytes.length,
+				width: input.maxWidth ?? 640,
+				fps: input.fps ?? 12,
+				speed: input.speed ?? 4,
+				encodeMs: Date.now() - startedAt
+			}
+		});
+		return bytes;
+	} catch (err) {
+		input.logger?.warn("nc gif: the derive failed — this notification ships without a gif", {
+			tags: { deviceId: input.deviceId },
+			meta: {
+				sourceBytes: input.mp4.length,
+				error: err instanceof Error ? err.message : String(err)
+			}
+		});
+		return null;
+	}
+}
+function runGif(input, args) {
+	return new Promise((resolve, reject) => {
+		const proc = input.spawnFn(input.ffmpegPath ?? "ffmpeg", [...args], { stdio: [
+			"pipe",
+			"pipe",
+			"pipe"
+		] });
+		const chunks = [];
+		let stderrTail = "";
+		let done = false;
+		let timer = null;
+		const settle = (err, out) => {
+			if (done) return;
+			done = true;
+			if (timer !== null) clearTimeout(timer);
+			if (proc.exitCode === null && proc.signalCode === null) try {
+				proc.kill("SIGKILL");
+			} catch {}
+			try {
+				proc.stdout?.removeAllListeners();
+				proc.stderr?.removeAllListeners();
+				proc.stdin?.destroy();
+			} catch {}
+			if (err !== null) reject(err);
+			else resolve(out ?? new Uint8Array(0));
+		};
+		timer = setTimeout(() => settle(/* @__PURE__ */ new Error("gif derive timed out")), GIF_RENDER_TIMEOUT_MS);
+		timer.unref?.();
+		proc.stdout?.on("data", (c) => chunks.push(c));
+		proc.stderr?.on("data", (c) => {
+			stderrTail = (stderrTail + c.toString()).slice(-400);
+		});
+		proc.on("error", (err) => settle(err instanceof Error ? err : new Error(String(err))));
+		proc.on("close", (code) => {
+			if (code !== 0) {
+				settle(/* @__PURE__ */ new Error(`ffmpeg gif derive exited ${code}: ${stderrTail}`));
+				return;
+			}
+			const out = Buffer.concat(chunks);
+			if (out.byteLength === 0) {
+				settle(/* @__PURE__ */ new Error("gif derive produced no bytes"));
+				return;
+			}
+			const bytes = new Uint8Array(out.byteLength);
+			bytes.set(out);
+			settle(null, bytes);
+		});
+		proc.stdin?.on("error", () => {});
+		proc.stdin?.write(Buffer.from(input.mp4));
+		proc.stdin?.end();
+	});
+}
 //#endregion
 //#region src/stream-broker/stream-broker/profile-restreamers.ts
 /**
@@ -12541,79 +12969,6 @@ function hexToBytes(hex) {
 	}
 	return out;
 }
-/**
-* Minimum gap between two re-dials of the same device. A re-dial costs a
-* ~2 s video interruption on every source of the camera; at the 30 s
-* reconcile cadence, an un-cooled loop against a camera whose audio genuinely
-* cannot come back would be a permanent stutter.
-*/
-var AUDIO_PLANE_REDIAL_COOLDOWN_MS = 5 * 6e4;
-var EMPTY_AUDIO_PLANE_STATE = {
-	disagreements: 0,
-	redials: 0,
-	lastRedialMs: 0,
-	gaveUp: false
-};
-/**
-* Decide what one pass should do. Pure: no clock, no I/O, no broker.
-*
-* `nowMs` is passed in rather than read so the cooldown is testable without
-* waiting five minutes for it.
-*/
-function decideAudioPlaneAction(observation, state, nowMs) {
-	switch (observation.kind) {
-		case "broker-muted":
-		case "no-live-source":
-		case "audio-present":
-		case "declared-off": return {
-			action: { kind: "none" },
-			nextState: EMPTY_AUDIO_PLANE_STATE
-		};
-		case "read-failed":
-		case "audio-unknown": return {
-			action: { kind: "none" },
-			nextState: state
-		};
-		case "declared-on": {
-			if (state.gaveUp) return {
-				action: { kind: "none" },
-				nextState: state
-			};
-			const disagreements = state.disagreements + 1;
-			if (disagreements < 2) return {
-				action: { kind: "await-second-pass" },
-				nextState: {
-					...state,
-					disagreements
-				}
-			};
-			if (state.redials >= 3) return {
-				action: { kind: "give-up" },
-				nextState: {
-					...state,
-					disagreements,
-					gaveUp: true
-				}
-			};
-			if (state.lastRedialMs > 0 && nowMs - state.lastRedialMs < 3e5) return {
-				action: { kind: "cooldown" },
-				nextState: {
-					...state,
-					disagreements: 2
-				}
-			};
-			return {
-				action: { kind: "redial" },
-				nextState: {
-					disagreements: 0,
-					redials: state.redials + 1,
-					lastRedialMs: nowMs,
-					gaveUp: false
-				}
-			};
-		}
-	}
-}
 //#endregion
 //#region src/stream-broker/stream-broker/transcode-pipeline.ts
 /**
@@ -13176,13 +13531,6 @@ function formatClockHHMM(at) {
 *  reach `streaming` with audio detected, and the stats poll cadence. */
 var PROBE_STREAM_TIMEOUT_MS = 6e3;
 var PROBE_STREAM_POLL_MS = 250;
-/**
-* Seconds of encoded video kept for notification clips, on the cheapest
-* assigned profile only. Sized to cover the longest allowed pre-roll (20 s)
-* plus the seconds a rule takes to reach the dispatcher; the low-profile
-* rendition costs a few MB for that window, and nothing at all while the
-* camera is idle.
-*/
 var CLIP_RETENTION_SEC = 25;
 /** Cheapest-first — the profile a clip is cut from when the rule says nothing. */
 var CLIP_PROFILE_BY_COST = [
@@ -14905,6 +15253,160 @@ var StreamBrokerManager = class StreamBrokerManager {
 	* of the event, not of the present.
 	*/
 	async renderPreBufferClip(input) {
+		const cut = await this.selectClipWindow({
+			deviceId: input.deviceId,
+			aroundMs: input.aroundMs,
+			preRollSec: input.preRollSec,
+			postRollSec: input.postRollSec,
+			...input.profile !== void 0 ? { profile: input.profile } : {}
+		});
+		const bytes = await this.muxClipWindow(cut, {
+			format: input.format,
+			maxWidth: input.maxWidth,
+			fps: input.fps,
+			...input.speed !== void 0 ? { speed: input.speed } : {}
+		});
+		const first = cut.window[0];
+		const last = cut.window[cut.window.length - 1];
+		return {
+			base64: Buffer.from(bytes).toString("base64"),
+			mime: input.format === "gif" ? "image/gif" : "video/mp4",
+			bytes: bytes.byteLength,
+			profile: cut.profile,
+			durationMs: first && last ? Math.max(0, last.pts - first.pts) : 0
+		};
+	}
+	/**
+	* ONE cut of an event, in every container the caller asked for — the
+	* production point every consumer of event media goes through.
+	*
+	* See the cap docblock for why this is one method rather than one call per
+	* format. The short version is that `renderPreBufferClip` renders one format
+	* per call, so a caller wanting a gif AND a video made two calls, got two
+	* windows, and shipped a notification whose two attachments showed different
+	* moments.
+	*
+	* The window comes out of the broker's own AnnexB retention ring — packets
+	* that were already in RAM — so a production reaches BACKWARDS from the event
+	* with nothing spawned and nothing kept warm. The mp4 is muxed once, COPYING
+	* the camera's own H.264 whenever nothing is being changed, and any gif is
+	* derived from that same mp4 rather than rendered a second time from the
+	* packets: same window, same pixels, by construction.
+	*/
+	async produceEventMedia(input) {
+		const preferred = input.profile ?? this.bestClipProfile(input.deviceId) ?? void 0;
+		const cut = await this.selectClipWindow({
+			deviceId: input.deviceId,
+			aroundMs: input.aroundMs,
+			preRollSec: input.preSeconds,
+			postRollSec: input.postSeconds,
+			...preferred !== void 0 ? { profile: preferred } : {}
+		});
+		const clipWidth = eventClipEncodeWidth(cut.sourceWidth, input.speed);
+		const mp4 = await this.muxClipWindow(cut, {
+			format: "mp4",
+			maxWidth: clipWidth,
+			fps: 0,
+			speed: input.speed
+		});
+		const media = [];
+		if (input.kinds.includes("mp4")) media.push({
+			kind: "mp4",
+			handle: this.eventMedia.put({
+				deviceId: input.deviceId,
+				kind: "mp4",
+				mime: "video/mp4",
+				bytes: mp4
+			}),
+			nodeId: this.localNodeId ?? "",
+			mime: "video/mp4",
+			bytes: mp4.byteLength,
+			width: clipWidth,
+			height: scaledHeight(cut, clipWidth)
+		});
+		const gifSpeed = input.gifSpeed ?? 4;
+		if (input.kinds.includes("gif")) {
+			const gif = await gifFromMp4({
+				mp4,
+				deviceId: input.deviceId,
+				maxWidth: input.gifMaxWidth,
+				fps: input.gifFps,
+				speed: gifDeriveSpeed(gifSpeed, input.speed),
+				...this.logger !== void 0 ? { logger: this.logger } : {},
+				spawnFn: node_child_process.spawn,
+				...this.ffmpegConfig.binaryPath !== void 0 ? { ffmpegPath: this.ffmpegConfig.binaryPath } : {}
+			});
+			if (gif !== null) {
+				const height = scaledHeight(cut, input.gifMaxWidth);
+				media.push({
+					kind: "gif",
+					handle: this.eventMedia.put({
+						deviceId: input.deviceId,
+						kind: "gif",
+						mime: "image/gif",
+						bytes: gif
+					}),
+					nodeId: this.localNodeId ?? "",
+					mime: "image/gif",
+					bytes: gif.byteLength,
+					width: input.gifMaxWidth,
+					height
+				});
+			}
+		}
+		const video = this.clipVideoMode(cut, {
+			format: "mp4",
+			maxWidth: clipWidth,
+			speed: input.speed
+		});
+		this.logger?.info("event media produced — one window, every container", {
+			tags: { deviceId: input.deviceId },
+			meta: {
+				profile: cut.profile,
+				video,
+				resolution: `${cut.sourceWidth}x${cut.sourceHeight}`,
+				packets: cut.window.length,
+				kinds: [...input.kinds].join(","),
+				artifacts: media.map((m) => `${m.kind}:${m.bytes}`).join(" "),
+				speed: input.speed,
+				gifSpeed,
+				startOffsetMs: cut.coverage.fromTs - input.aroundMs,
+				endOffsetMs: cut.coverage.toTs - input.aroundMs
+			}
+		});
+		return {
+			media,
+			coverage: {
+				fromTs: cut.coverage.fromTs,
+				toTs: cut.coverage.toTs,
+				packets: cut.window.length
+			},
+			profile: cut.profile,
+			video
+		};
+	}
+	/** Redeem an artifact handle. `null` once it has expired (see
+	*  {@link EventMediaStore}). */
+	async fetchEventMedia(input) {
+		const item = this.eventMedia.get(input.handle);
+		if (item === null) {
+			this.logger?.warn("event media: handle expired or unknown — nothing to fetch", { meta: { handle: input.handle } });
+			return null;
+		}
+		return {
+			base64: Buffer.from(item.bytes).toString("base64"),
+			mime: item.mime,
+			bytes: item.bytes.length
+		};
+	}
+	/**
+	* Wait out the post-roll, then select the retained window around the moment.
+	*
+	* Shared by `renderPreBufferClip` and `produceEventMedia` deliberately: two
+	* copies of "which profile, which packets, which resolution" is exactly how
+	* the two paths would start disagreeing again.
+	*/
+	async selectClipWindow(input) {
 		const map = this.assignments.get(input.deviceId)?.map ?? {};
 		const assigned = CLIP_PROFILE_BY_COST.filter((p) => map[p] !== void 0);
 		const wanted = pickClipProfile(assigned, input.profile);
@@ -14915,19 +15417,26 @@ var StreamBrokerManager = class StreamBrokerManager {
 		const candidates = [wanted, ...assigned.filter((p) => p !== wanted)];
 		let profile = null;
 		let window = [];
+		let coverage = {
+			fromTs: input.aroundMs,
+			toTs: input.aroundMs
+		};
 		for (const candidate of candidates) {
 			const broker = this.brokerFor(input.deviceId, map[candidate]);
 			if (!broker) continue;
+			const packets = broker.getClipBuffer();
+			const nowMs = Date.now();
 			const found = windowAround({
-				packets: broker.getClipBuffer(),
+				packets,
 				aroundMs: input.aroundMs,
 				preRollSec: input.preRollSec,
 				postRollSec: input.postRollSec,
-				nowMs: Date.now()
+				nowMs
 			});
 			if (found.length > 0) {
 				profile = candidate;
 				window = found;
+				coverage = windowCoverage(packets, found, nowMs);
 				break;
 			}
 		}
@@ -14941,29 +15450,77 @@ var StreamBrokerManager = class StreamBrokerManager {
 		});
 		const broker = this.brokerFor(input.deviceId, map[profile]);
 		if (!broker) throw new Error(`No live broker for device ${input.deviceId} (${profile})`);
-		const bytes = await renderPreBufferClip({
+		const cam = this.cameraStreams.get(input.deviceId)?.get(map[profile] ?? "");
+		return {
+			deviceId: input.deviceId,
+			profile,
 			window,
-			format: input.format,
-			maxWidth: input.maxWidth,
-			fps: input.fps,
-			...input.speed !== void 0 ? { speed: input.speed } : {},
+			coverage,
+			broker,
+			sourceWidth: cam?.resolution?.width ?? 0,
+			sourceHeight: cam?.resolution?.height ?? 0
+		};
+	}
+	/** The rendition an event production prefers for this camera, or null when
+	*  nothing qualifies (every slot H.265, or none publishes a resolution). */
+	bestClipProfile(deviceId) {
+		const map = this.assignments.get(deviceId)?.map ?? {};
+		const streams = this.cameraStreams.get(deviceId);
+		const candidates = [];
+		for (const profile of CLIP_PROFILE_BY_COST) {
+			const camStreamId = map[profile];
+			if (camStreamId === void 0) continue;
+			const cam = streams?.get(camStreamId);
+			candidates.push({
+				profile,
+				...cam?.codec !== void 0 ? { codec: cam.codec } : {},
+				...cam?.resolution?.width !== void 0 ? { width: cam.resolution.width } : {},
+				...cam?.resolution?.height !== void 0 ? { height: cam.resolution.height } : {}
+			});
+		}
+		return pickBestClipProfile(candidates);
+	}
+	/** `copy` or `encode` for this cut — reported, never inferred from a size. */
+	clipVideoMode(cut, render) {
+		return clipCanCopy({
+			format: render.format,
+			maxWidth: render.maxWidth,
+			...render.speed !== void 0 ? { speed: render.speed } : {},
+			hevc: isHevcPacket(cut.window[0]),
+			sourceWidth: cut.sourceWidth
+		}) ? "copy" : "encode";
+	}
+	async muxClipWindow(cut, render) {
+		const bytes = await renderPreBufferClip({
+			window: cut.window,
+			format: render.format,
+			maxWidth: render.maxWidth,
+			fps: render.fps,
+			sourceWidth: cut.sourceWidth,
+			...render.speed !== void 0 ? { speed: render.speed } : {},
 			spawn: (cmd, args) => (0, node_child_process.spawn)(cmd, [...args], { stdio: [
 				"pipe",
 				"pipe",
 				"pipe"
 			] }),
 			ffmpegPath: this.ffmpegConfig.binaryPath,
-			sdpParameterSets: broker.getSdpParameterSets()
+			sdpParameterSets: cut.broker.getSdpParameterSets()
 		});
-		const first = window[0];
-		const last = window[window.length - 1];
-		return {
-			base64: bytes.toString("base64"),
-			mime: input.format === "gif" ? "image/gif" : "video/mp4",
-			bytes: bytes.byteLength,
-			profile,
-			durationMs: first && last ? Math.max(0, last.pts - first.pts) : 0
-		};
+		this.logger?.info("pre-buffer clip rendered", {
+			tags: { deviceId: cut.deviceId },
+			meta: {
+				profile: cut.profile,
+				format: render.format,
+				video: this.clipVideoMode(cut, render),
+				sourceWidth: cut.sourceWidth,
+				maxWidth: render.maxWidth,
+				speed: render.speed ?? null,
+				packets: cut.window.length,
+				bytes: bytes.byteLength,
+				coverageMs: cut.coverage.toTs - cut.coverage.fromTs
+			}
+		});
+		return bytes;
 	}
 	getCameraStreamsForDevice(deviceId) {
 		const streamMap = this.cameraStreams.get(deviceId);
@@ -16403,6 +16960,8 @@ var StreamBrokerManager = class StreamBrokerManager {
 	* within the minute — a rule asking for `high` fell back to `low` forever
 	* and looked like the choice did nothing.
 	*/
+	/** Produced event artifacts waiting to be fetched by handle (D9/D18). */
+	eventMedia = new EventMediaStore();
 	clipRetentionArmed = /* @__PURE__ */ new Map();
 	armClipRetention(deviceId, profile) {
 		const armed = this.clipRetentionArmed.get(deviceId) ?? /* @__PURE__ */ new Set();
@@ -17068,6 +17627,17 @@ var StreamBrokerManager = class StreamBrokerManager {
 		}
 	}
 };
+/**
+* The height a render lands at, once `scale=W:-2` has picked it.
+*
+* `-2` means "keep the aspect, round to an EVEN number" — libx264 rejects an
+* odd dimension in yuv420p. Reporting the arithmetic without the rounding is
+* how an artifact ends up one pixel taller than the file it describes.
+*/
+function scaledHeight(cut, width) {
+	if (cut.sourceWidth <= 0 || cut.sourceHeight <= 0) return 0;
+	return 2 * Math.round(width / cut.sourceWidth * cut.sourceHeight / 2);
+}
 //#endregion
 //#region src/stream-broker/encode-profile-resolver.ts
 /**