@camstack/addon-pipeline 1.2.68 → 1.2.70

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-Bv9CqUAF.js");
+const require_dist = require("../dist-cR-pvD_z.js");
 const require_remote_restream = require("../remote-restream-BYbAsgUf.js");
 let node_crypto = require("node:crypto");
 node_crypto = require_chunk.__toESM(node_crypto, 1);
@@ -1015,6 +1015,111 @@ function buildDerivedTranscodeArgs(profile, loopbackUrl, decodeHwAccel = null) {
 		decodeHwAccel
 	}));
 }
+/**
+* Ceiling for a configured pre-roll.
+*
+* Three costs grow with this number and none of them is the operator's to
+* discover: retained RTP bytes on the ingest node, the media backlog a decoder
+* must drain before it reaches the live edge, and the span a detection burst is
+* allowed to carry past the D57 bound. 6 s covers a 4-5 s IDR interval plus a
+* full GOP of head-room and matches the decoder-seed ring's own retention, so
+* both planes can honour the same maximum.
+*/
+var PRE_ROLL_MAX_MS = 6e3;
+var NOTHING = {
+	startIndex: -1,
+	ageMs: 0,
+	gopsBack: 0
+};
+/** A configured pre-roll in ms, or `0` when the input carries no instruction. */
+function usablePreRoll(value) {
+	if (value === void 0) return 0;
+	if (!Number.isFinite(value) || value <= 0) return 0;
+	return Math.min(PRE_ROLL_MAX_MS, Math.max(250, value));
+}
+/**
+* Choose the keyframe access unit a pre-roll burst starts at.
+*
+* The OLDEST mark that is still inside the window wins; when none is (the
+* current GOP is itself older than `preRollMs`, i.e. a long-GOP camera with a
+* short pre-roll) the newest mark is returned, because the alternative to the
+* current GOP is nothing at all — the blind start Stage 0 exists to prevent.
+*
+* The boundary is INCLUSIVE: a keyframe exactly `preRollMs` old is inside.
+* Everything delivered after a keyframe is younger than it, so starting at a
+* mark inside the window is what makes "no frame older than `preRollMs` is
+* delivered" a property of the slice rather than a per-packet filter.
+*
+* Scans instead of assuming order: a caller that appends marks and rebases
+* indices after a trim is one refactor away from handing this an unsorted
+* array, and the failure would be a silently wider window.
+*/
+function selectPreRollStart(marks, preRollMs) {
+	if (marks.length === 0) return NOTHING;
+	const window = usablePreRoll(preRollMs);
+	let newest = marks[0];
+	let chosen = null;
+	for (const mark of marks) {
+		if (mark.ageMs < newest.ageMs) newest = mark;
+		if (window > 0 && mark.ageMs <= window && (chosen === null || mark.ageMs > chosen.ageMs)) chosen = mark;
+	}
+	const pick = chosen ?? newest;
+	let gopsBack = 0;
+	for (const mark of marks) if (mark.ageMs < pick.ageMs) gopsBack++;
+	return {
+		startIndex: pick.index,
+		ageMs: pick.ageMs,
+		gopsBack
+	};
+}
+/**
+* Combine the cluster default and the per-camera-stream override into the one
+* pre-roll a broker applies. Precedence: stream override → cluster default →
+* OFF. Each layer is validated independently, so a bad override falls back to a
+* good cluster value rather than to nothing.
+*
+* `0` means INHERIT, never "off for this stream". It is what a cleared number
+* input posts, and the shipped cluster default is 0, so inherit and off
+* coincide on every unconfigured stream.
+*/
+function resolvePreRollMs(input) {
+	const override = usablePreRoll(input.overrides?.[input.camStreamId]);
+	if (override > 0) return override;
+	if (input.terminalRelay === true) return 0;
+	return usablePreRoll(input.clusterMs);
+}
+/**
+* The packet ceiling for a burst carrying `preRollMs` of pre-roll.
+*
+* `PRIME_MAX_PACKETS` is a defensive backstop against RTP timestamps that
+* stopped describing the stream — "far more packets than this much media time
+* can contain" — not a tuning knob. Read as an absolute it would silently kill
+* pre-roll on exactly the cameras that need it (a 4K main stream at 8 Mbps
+* fills 2 000 MTU-sized packets in under 3 s), so it is applied as the RATE it
+* always was: the same packets-per-span, over the span actually requested.
+* Never shrinks the ceiling.
+*/
+function preRollPacketCeiling(bound, preRollMs) {
+	const window = usablePreRoll(preRollMs);
+	if (window <= 0 || bound.maxSpanMs <= 0) return bound.maxPackets;
+	const factor = Math.max(1, Math.ceil(window / bound.maxSpanMs));
+	return bound.maxPackets * factor;
+}
+/**
+* The span bound a DETECTION session's burst is held to while pre-roll is on.
+*
+* D57's bound is untouched for every other consumer; for this one it becomes
+* the wider of the two, because withholding a burst for being as wide as the
+* operator configured would make the knob read as ON and behave as OFF.
+*/
+function preRollSpanBound(bound, preRollMs) {
+	const window = usablePreRoll(preRollMs);
+	if (window <= 0) return bound;
+	return {
+		maxSpanMs: Math.max(bound.maxSpanMs, window),
+		maxPackets: preRollPacketCeiling(bound, window)
+	};
+}
 //#endregion
 //#region src/stream-broker/rtsp/ffmpeg-source-reader-args.ts
 /** MJPEG cannot enter the broker's MPEG-TS demuxer directly; normalize it. */
@@ -1645,6 +1750,20 @@ var RtspRestreamer = class {
 	*/
 	primeBoundSupplier = null;
 	/**
+	* Supplies the PRE-ROLL window — the current GOP plus up to `preRollMs` of
+	* the history before it, keyframe-aligned (motion-start Stage 2).
+	*
+	* A second supplier and not a widening of {@link rtpPreBufferSupplier},
+	* because the two feed different populations: that one is also the WebRTC
+	* bootstrap and every ordinary RTSP join, and handing them history is the
+	* D57 failure. Only a session that declared the detection intent on its dial
+	* path is served from this one.
+	*
+	* Pulled per join for the same reason as the bound: a broker outlives the
+	* setting.
+	*/
+	preRollSupplier = null;
+	/**
 	* In-flight paced join replays, keyed by session id. A session with an entry
 	* here has been removed from {@link pendingKeyframe} but is NOT yet on the
 	* live feed: live packets are appended to its replay tail via `enqueue`, so
@@ -1687,6 +1806,10 @@ var RtspRestreamer = class {
 	setPrimeBoundSupplier(supplier) {
 		this.primeBoundSupplier = supplier;
 	}
+	/** Wire the pre-roll window accessor (see field doc). */
+	setPreRollSupplier(supplier) {
+		this.preRollSupplier = supplier;
+	}
 	/** The bound in force right now; {@link DEFAULT_PRIME_BURST_BOUND} unwired. */
 	currentPrimeBound() {
 		return this.primeBoundSupplier?.() ?? DEFAULT_PRIME_BURST_BOUND;
@@ -1928,16 +2051,37 @@ var RtspRestreamer = class {
 			if (this.sessions.get(sessionId)?.isPlaying()) ready.push(sessionId);
 		}
 		if (ready.length === 0) return;
+		const preRoll = this.preRollSupplier?.();
+		const preRollPackets = fromRing && preRoll && preRoll.preRollMs > 0 && preRoll.packets.length > primePackets.length ? preRoll.packets.map((data) => ({
+			data,
+			marker: (data[1] & 128) !== 0
+		})) : [];
+		const preRollActive = preRollPackets.length > 0;
+		const preRollSpanMs = preRollActive ? (preRollPackets[preRollPackets.length - 1].data.readUInt32BE(4) - preRollPackets[0].data.readUInt32BE(4) | 0) / 90 : 0;
 		const bound = this.currentPrimeBound();
 		const overSpan = spanMs > bound.maxSpanMs;
 		const overPackets = primePackets.length > bound.maxPackets;
+		const preRollBound = preRollActive ? preRollSpanBound(bound, preRoll?.preRollMs ?? 0) : bound;
+		const preRollOverBound = preRollActive ? preRollSpanMs > preRollBound.maxSpanMs || preRollPackets.length > preRollBound.maxPackets : false;
 		const served = [];
+		const servedPreRoll = /* @__PURE__ */ new Set();
 		let withheld = 0;
 		let detectionIntentServed = 0;
 		for (const sessionId of ready) {
 			const session = this.sessions.get(sessionId);
 			if (!session) continue;
 			const detectionIntent = session.isDetectionIntent();
+			if (detectionIntent && preRollActive) {
+				if (preRollOverBound) {
+					this.dropsWithheldSpan++;
+					withheld++;
+					continue;
+				}
+				detectionIntentServed++;
+				servedPreRoll.add(sessionId);
+				served.push(sessionId);
+				continue;
+			}
 			if (session.isMuted() && !detectionIntent) {
 				if (!fromRing || spanMs > LIVE_EDGE_MAX_SPAN_MS) {
 					this.dropsWithheldMutedLiveEdge++;
@@ -1966,7 +2110,11 @@ var RtspRestreamer = class {
 				boundSpanMs: bound.maxSpanMs,
 				boundPackets: bound.maxPackets,
 				withheld,
-				detectionIntentServed
+				detectionIntentServed,
+				preRollMs: preRoll?.preRollMs ?? 0,
+				preRollSpanMs: preRollActive ? Math.round(preRollSpanMs) : 0,
+				preRollPackets: preRollPackets.length,
+				preRollServed: servedPreRoll.size
 			}
 		});
 		const items = primePackets.map((packet) => ({
@@ -1974,9 +2122,14 @@ var RtspRestreamer = class {
 			prime: true,
 			keyframeAuStart: false
 		}));
+		const preRollItems = servedPreRoll.size > 0 ? preRollPackets.map((packet) => ({
+			packet,
+			prime: true,
+			keyframeAuStart: false
+		})) : [];
 		for (const sessionId of served) {
 			this.pendingKeyframe.delete(sessionId);
-			this.startPrimeReplay(sessionId, items);
+			this.startPrimeReplay(sessionId, servedPreRoll.has(sessionId) ? preRollItems : items);
 		}
 	}
 	/**
@@ -10468,11 +10621,14 @@ var StreamBroker = class StreamBroker {
 	* WebRTC viewer — that closed the broker, tore the lib's session
 	* down, and on reopen the dedicated session attached cleanly.
 	*
-	* This watchdog automates that: it arms when the rfc4571 reader's
-	* `onVideoTrack` fires (TCP up, SDP parsed) and cancels at the first
+	* This watchdog automates that: it arms when either reader's
+	* `onVideoTrack` fires (TCP up, SDP parsed) — the callback factory is
+	* shared, so native RTSP arms it too — and cancels at the first
 	* `onVideoRtp` callback. If it elapses without a single video RTP
-	* packet, it destroys the reader, asks the publisher for a fresh
-	* source, and re-dials — exactly what the manual restart did.
+	* packet (measured PER DIAL — `videoRtpSeen` is reset on every dial),
+	* it destroys the reader and re-dials; for an `rfc4571` loopback source
+	* it also asks the publisher for a fresh source first. Exactly what the
+	* manual restart did.
 	*/
 	firstVideoWatchdog;
 	/**
@@ -10487,23 +10643,27 @@ var StreamBroker = class StreamBroker {
 	static FIRST_VIDEO_TIMEOUT_MS = 8e3;
 	/**
 	* Rolling source-RTP activity watchdog. Distinct from the first-video
-	* watchdog: this one ARMS on the first RTP packet (video or audio) and
-	* RESETS on every subsequent packet. If no packet arrives within
+	* watchdog: this one ARMS at DIAL time (so a connection that opens the
+	* loopback TCP but never delivers media is still detected) and RESETS on
+	* every RTP packet thereafter. If no packet arrives within
 	* `RTP_ACTIVITY_TIMEOUT_MS`, the reader is torn down and reconnected.
 	*
-	* Wi-Fi-attached IP cameras silently stall the RTSP/TCP source under
-	* packet loss: ICE/DTLS stay healthy, `rtpPacketsSent` keeps advancing
-	* (replaying the GOP cache), but the source-side audio/video time
-	* progresses only in tiny bursts. The user sees a frozen viewport with
-	* no recovery because the existing code path never noticed the stall.
+	* Two failure modes, one timer:
+	*  - a rebooted-Reolink rfc4571 source that opens the socket but never
+	*    starts its dedicated session (arm-at-dial catches this in ~8s); and
+	*  - a Wi-Fi-attached IP camera that silently stalls mid-stream under
+	*    packet loss — ICE/DTLS stay healthy and `rtpPacketsSent` keeps
+	*    advancing (replaying the GOP cache), but source-side time progresses
+	*    only in tiny bursts, so the viewer freezes with no recovery.
 	*
-	* The watchdog resets on every RTP packet and kills+restarts the reader
-	* when no data arrives within `RTP_ACTIVITY_TIMEOUT_MS` (~10s).
+	* The watchdog kills+restarts the reader when no data arrives within
+	* `RTP_ACTIVITY_TIMEOUT_MS` (8s — same as `FIRST_VIDEO_TIMEOUT_MS`).
 	*
 	* Reused across the native RTSP and RFC 4571 readers — both flow through
 	* `buildRtpStreamCallbacks` and call `kickRtpActivityWatchdog()` per
-	* packet. push-rtp / push (provider-driven) and RTMP sources sit out
-	* because they have no native reader to tear down.
+	* packet, and both arm it at dial. push-rtp arms it on its first pushed
+	* packet; push / RTMP (provider-driven) sources sit out because they have
+	* no native reader to tear down.
 	*/
 	rtpActivityWatchdog;
 	/** Number of times the activity watchdog fired in this broker's lifetime
@@ -10633,6 +10793,28 @@ var StreamBroker = class StreamBroker {
 	rtpRingHasKeyframe = false;
 	rtpRingBytes = 0;
 	/**
+	* Index + 90 kHz timestamp of the first packet of every keyframe AU still in
+	* {@link rtpRing}, oldest first.
+	*
+	* Exists because pre-roll needs to start a burst at an EARLIER keyframe and
+	* nothing in an RTP header says "keyframe" — keyframe-ness is known only at
+	* capture time, from the depacketizer flags. Without these marks the only
+	* reachable start is "the whole ring", which is a mid-GOP cut the moment the
+	* ring holds more than one GOP: undecodable, and exactly what D57 refuses.
+	*
+	* Indices are rebased on every head trim, so the last entry is always the
+	* newest keyframe AU — the current GOP's start, which is what
+	* {@link getRtpPreBuffer} keeps handing WebRTC and the plain RTSP join.
+	*/
+	rtpRingKeyframeMarks = [];
+	/**
+	* Media time (ms) of history a DETECTION decode dial may be handed before the
+	* live edge — motion-start Stage 2. `0` (default) = off, and every path here
+	* then behaves exactly as it did before pre-roll existed. Resolved per stream
+	* by `resolvePreRollMs` and pushed by the manager.
+	*/
+	preRollMs = 0;
+	/**
 	* Effective join-burst bound for this stream's RTSP restream — the cluster
 	* default, or this camera stream's override. Applies to the RESTREAM
 	* consumers only; the WebRTC bootstrap reads the ring directly and is
@@ -10645,6 +10827,20 @@ var StreamBroker = class StreamBroker {
 	*  long-GOP high-bitrate stream) drops the bootstrap rather than balloon
 	*  memory — late joiners fall back to waiting for the next keyframe. */
 	static RTP_RING_MAX_BYTES = 24 * 1024 * 1024;
+	/**
+	* Byte budget for the EXTRA history pre-roll retains, over and above the
+	* current GOP.
+	*
+	* Its own budget rather than a share of {@link RTP_RING_MAX_BYTES} because
+	* the two failures are different: reaching the ring cap calls
+	* `resetRtpPreBuffer`, which drops the join bootstrap of EVERY consumer —
+	* WebRTC viewers included — for as long as the condition holds. A pre-roll
+	* that pushed a 4K stream into that state would be a knob for one camera's
+	* detection quietly degrading everybody else's picture. Over this budget the
+	* OLDEST retained GOP is dropped whole (never a tail cut), so the window
+	* stays decodable and simply carries less history than asked for.
+	*/
+	static PRE_ROLL_MAX_BYTES = 8 * 1024 * 1024;
 	/** Stream stats tracking */
 	totalBytes = 0;
 	bytesInWindow = 0;
@@ -10684,6 +10880,10 @@ var StreamBroker = class StreamBroker {
 		if (logger) this.rtspRestreamer.setLogger(logger.child("rtsp"));
 		this.rtspRestreamer.setRtpPreBufferSupplier(() => this.getRtpPreBuffer());
 		this.rtspRestreamer.setPrimeBoundSupplier(() => this.joinBurstBound);
+		this.rtspRestreamer.setPreRollSupplier(() => ({
+			packets: this.getRtpPreRollBuffer(),
+			preRollMs: this.preRollMs
+		}));
 		this.preBuffer = new EncodedRingBuffer(StreamBroker.DEFAULT_PRE_BUFFER_SEC);
 		this.decoderSeedBuffer = new EncodedRingBuffer(StreamBroker.DECODER_SEED_BUFFER_SEC);
 		this.audioChunkPlane = new AudioChunkPlane(logger?.child("audio-chunk-plane"));
@@ -10892,6 +11092,7 @@ var StreamBroker = class StreamBroker {
 		this._status = "connecting";
 		if (this.dialCount > 0) this.notifySourceRestart();
 		this.dialCount += 1;
+		this.videoRtpSeen = 0;
 		if (source.ffmpegParser) {
 			this._status = "connecting";
 			this.startFfmpegSourceReader(source);
@@ -11587,11 +11788,16 @@ var StreamBroker = class StreamBroker {
 		this.rtpRing.push(rtpData);
 		this.rtpRingBytes += rtpData.length;
 		if (this._lastNalParamSet || this._lastNalKeyframe) {
-			if (this.rtpRingCurAuStart > 0) {
-				const dropped = this.rtpRing.splice(0, this.rtpRingCurAuStart);
-				for (const b of dropped) this.rtpRingBytes -= b.length;
-				this.rtpRingCurAuStart = 0;
+			const auStart = this.rtpRingCurAuStart;
+			const lastMark = this.rtpRingKeyframeMarks[this.rtpRingKeyframeMarks.length - 1];
+			if (!lastMark || lastMark.index !== auStart) {
+				const auPacket = this.rtpRing[auStart];
+				if (auPacket && auPacket.length >= 8) this.rtpRingKeyframeMarks.push({
+					index: auStart,
+					ts: auPacket.readUInt32BE(4)
+				});
 			}
+			this.trimRtpRingToPreRollWindow();
 			this.rtpRingHasKeyframe = true;
 		}
 		this.rtpRingPrevMarker = marker;
@@ -11679,6 +11885,95 @@ var StreamBroker = class StreamBroker {
 		this.rtpRingCurAuStart = 0;
 		this.rtpRingPrevMarker = true;
 		this.rtpRingHasKeyframe = false;
+		this.rtpRingKeyframeMarks = [];
+	}
+	/**
+	* Configure how much history a DETECTION dial may be handed (Stage 2).
+	*
+	* Also widens the decoder-seed ring so the PUSH (Annex-B) plane can honour
+	* the same number: that ring is what `getSeedPackets` replays into a
+	* freshly-armed decoder, and a 6 s retention cannot serve a 6 s pre-roll plus
+	* the GOP that carries it.
+	*/
+	setPreRollMs(ms) {
+		const next = Number.isFinite(ms) && ms > 0 ? ms : 0;
+		if (next === this.preRollMs) return;
+		this.preRollMs = next;
+		const seedSec = Math.max(StreamBroker.DECODER_SEED_BUFFER_SEC, Math.ceil(next / 1e3) + 2);
+		this.decoderSeedBuffer.setDuration(seedSec);
+	}
+	/** The pre-roll in force for this stream (ms). `0` = off. */
+	getPreRollMs() {
+		return this.preRollMs;
+	}
+	/**
+	* The seed replayed into a freshly-armed PUSH-mode decoder session.
+	*
+	* The current GOP (`getPackets()`) while pre-roll is off — today's behaviour —
+	* and the same keyframe-aligned pre-roll window otherwise, cut from the seed
+	* ring's whole retention rather than from its last keyframe. This is the
+	* push/Annex-B counterpart of {@link getRtpPreRollBuffer}: RTP sources decode
+	* in PULL mode off the restream and take their pre-roll as the join burst,
+	* push sources are fed packet by packet and take it here. One selector serves
+	* both, so a fix to the boundary cannot land on only one plane.
+	*/
+	getDecoderSeedPackets() {
+		if (this.preRollMs <= 0) return this.decoderSeedBuffer.getPackets();
+		const all = this.decoderSeedBuffer.getAllPackets();
+		if (all.length === 0) return [];
+		const newestPts = all[all.length - 1].pts;
+		const marks = [];
+		for (let i = 0; i < all.length; i++) {
+			const packet = all[i];
+			if (packet.keyframe && packet.type === "video") marks.push({
+				index: i,
+				ageMs: newestPts - packet.pts
+			});
+		}
+		const selection = selectPreRollStart(marks, this.preRollMs);
+		return selection.startIndex < 0 ? [] : all.slice(selection.startIndex);
+	}
+	/** Retained keyframe AUs as ages in ms of media time behind `newestTs`. */
+	rtpPreRollMarks(newestTs) {
+		return this.rtpRingKeyframeMarks.map((mark) => ({
+			index: mark.index,
+			ageMs: (newestTs - mark.ts | 0) / 90
+		}));
+	}
+	/**
+	* Trim the RTP ring's head to the oldest keyframe AU still inside the
+	* pre-roll window, then to the pre-roll byte budget.
+	*
+	* With `preRollMs === 0` the selection is the newest keyframe AU, so this is
+	* the pre-existing "trim to the current GOP" behaviour with no change in
+	* retained bytes. Whole GOPs only, from the head: a tail cut no longer starts
+	* at a keyframe (D57).
+	*/
+	trimRtpRingToPreRollWindow() {
+		if (this.rtpRingKeyframeMarks.length === 0 || this.rtpRing.length === 0) return;
+		const newestTs = this.rtpRing[this.rtpRing.length - 1].readUInt32BE(4);
+		let cut = selectPreRollStart(this.rtpPreRollMarks(newestTs), this.preRollMs).startIndex;
+		if (cut < 0) return;
+		if (this.preRollMs > 0) {
+			const historyEnd = this.rtpRingKeyframeMarks[this.rtpRingKeyframeMarks.length - 1].index;
+			let retained = 0;
+			for (let i = cut; i < historyEnd; i++) retained += this.rtpRing[i].length;
+			let markIdx = this.rtpRingKeyframeMarks.findIndex((m) => m.index === cut);
+			while (retained > StreamBroker.PRE_ROLL_MAX_BYTES && markIdx >= 0 && markIdx < this.rtpRingKeyframeMarks.length - 1) {
+				const nextCut = this.rtpRingKeyframeMarks[markIdx + 1].index;
+				for (let i = cut; i < nextCut; i++) retained -= this.rtpRing[i].length;
+				cut = nextCut;
+				markIdx++;
+			}
+		}
+		if (cut <= 0) return;
+		const dropped = this.rtpRing.splice(0, cut);
+		for (const b of dropped) this.rtpRingBytes -= b.length;
+		this.rtpRingKeyframeMarks = this.rtpRingKeyframeMarks.filter((mark) => mark.index >= cut).map((mark) => ({
+			index: mark.index - cut,
+			ts: mark.ts
+		}));
+		this.rtpRingCurAuStart = Math.max(0, this.rtpRingCurAuStart - cut);
 	}
 	/**
 	* Snapshot of the source-RTP pre-buffer (the current GOP from its
@@ -11688,7 +11983,25 @@ var StreamBroker = class StreamBroker {
 	* falls back to waiting for the camera's next keyframe.
 	*/
 	getRtpPreBuffer() {
-		return this.rtpRingHasKeyframe ? this.rtpRing.slice() : [];
+		if (!this.rtpRingHasKeyframe) return [];
+		const newest = this.rtpRingKeyframeMarks[this.rtpRingKeyframeMarks.length - 1];
+		return newest ? this.rtpRing.slice(newest.index) : this.rtpRing.slice();
+	}
+	/**
+	* Snapshot for a DETECTION decode dial: the current GOP plus up to
+	* {@link preRollMs} of the history before it, starting at a keyframe AU.
+	*
+	* Identical to {@link getRtpPreBuffer} while pre-roll is off, and it degrades
+	* to it whenever the ring holds no older keyframe — a source that was idle
+	* when motion fired retained nothing, and the honest outcome there is the
+	* Stage 0 burst rather than a pretend one.
+	*/
+	getRtpPreRollBuffer() {
+		if (!this.rtpRingHasKeyframe) return [];
+		if (this.preRollMs <= 0 || this.rtpRing.length === 0) return this.getRtpPreBuffer();
+		const newestTs = this.rtpRing[this.rtpRing.length - 1].readUInt32BE(4);
+		const selection = selectPreRollStart(this.rtpPreRollMarks(newestTs), this.preRollMs);
+		return selection.startIndex < 0 ? [] : this.rtpRing.slice(selection.startIndex);
 	}
 	getSourceType() {
 		return this.source?.type ?? null;
@@ -11787,6 +12100,19 @@ var StreamBroker = class StreamBroker {
 		};
 	}
 	/**
+	* Test seam exposing the first-video watchdog state and the per-dial video
+	* RTP counter. Production code MUST NOT read this — it exists so unit tests
+	* can assert the counter resets on every dial (regression: a broker-lifetime
+	* counter left the first-video watchdog dead on every re-dial) and that the
+	* watchdog stands down once video flows.
+	*/
+	getFirstVideoWatchdogStatus() {
+		return {
+			armed: this.firstVideoWatchdog !== void 0,
+			videoRtpSeen: this.videoRtpSeen
+		};
+	}
+	/**
 	* Open a decoded audio-chunk subscription — the poll-based, tRPC-reachable
 	* replacement for the live-object `onDecodedAudioChunk` callback. The
 	* broker registers a per-subscription FIFO queue and returns a
@@ -11840,7 +12166,7 @@ var StreamBroker = class StreamBroker {
 			logger: this.logger?.child("frame-handle-plane"),
 			resolveStreamInfo: () => this.resolveFrameHandleStreamInfo(),
 			localNodeId: this.localNodeId,
-			getSeedPackets: () => this.decoderSeedBuffer.getPackets(),
+			getSeedPackets: () => this.getDecoderSeedPackets(),
 			isDebugEnabled: () => this.streamingDebug
 		});
 		return this.frameHandlePlane;
@@ -12219,7 +12545,7 @@ var StreamBroker = class StreamBroker {
 	* runs `destroyNativeClient`; the RFC 4571 reader closes the TCP
 	* socket and clears its handle).
 	*/
-	buildRtpStreamCallbacks(label, onTerminate) {
+	buildRtpStreamCallbacks(label, onTerminate, isStale) {
 		return {
 			onVideoTrack: (track, sdpText) => {
 				this.detectedCodec = track.codec;
@@ -12392,7 +12718,18 @@ var StreamBroker = class StreamBroker {
 				this.scheduleReconnect();
 			},
 			onTeardown: () => {
+				if (this.manualStop || this.stopping) return;
+				if (isStale?.()) return;
 				onTerminate();
+				this._status = "error";
+				this.logger?.warn(`${label}: source closed — treating as failure edge`, {
+					tags: { deviceId: this.numericDeviceId },
+					meta: { ...this.sourceMetaForLog() }
+				});
+				if (this.source?.type === "rfc4571") {
+					this.notifySourceRefresh();
+					this.scheduleReconnect();
+				}
 			}
 		};
 	}
@@ -12401,7 +12738,7 @@ var StreamBroker = class StreamBroker {
 		const client = new NativeRtspClient({
 			url: source.url,
 			logger: this.logger?.child("rtsp-native")
-		}, this.buildRtpStreamCallbacks("native RTSP", () => this.destroyNativeClient()));
+		}, this.buildRtpStreamCallbacks("native RTSP", () => this.destroyNativeClient(), () => this.nativeClient !== client));
 		this.nativeClient = client;
 		client.connect().catch((err) => {
 			if (this.manualStop || this._suspended) return;
@@ -12413,6 +12750,7 @@ var StreamBroker = class StreamBroker {
 			this._status = "error";
 			this.scheduleReconnect();
 		});
+		this.kickRtpActivityWatchdog();
 	}
 	/**
 	* Handle a complete NAL from the RTP depacketizer.
@@ -12563,15 +12901,29 @@ var StreamBroker = class StreamBroker {
 		this.firstVideoWatchdog = setTimeout(() => {
 			this.firstVideoWatchdog = void 0;
 			if (this.manualStop || this.stopping) return;
-			if (this.videoRtpSeen > 0) return;
-			this.logger?.warn("first-video watchdog: no video RTP after rfc4571 connect — forcing reconnect", { meta: { timeoutMs: StreamBroker.FIRST_VIDEO_TIMEOUT_MS } });
-			this.videoRtpSeen = 0;
+			if (this.videoRtpSeen > 0) {
+				this.logger?.info("first-video watchdog: video flowing — standing down", {
+					tags: { deviceId: this.numericDeviceId },
+					meta: {
+						videoRtpSeen: this.videoRtpSeen,
+						...this.sourceMetaForLog()
+					}
+				});
+				return;
+			}
+			this.logger?.warn("first-video watchdog: no video RTP after source connect — forcing reconnect", {
+				tags: { deviceId: this.numericDeviceId },
+				meta: {
+					timeoutMs: StreamBroker.FIRST_VIDEO_TIMEOUT_MS,
+					...this.sourceMetaForLog()
+				}
+			});
 			this.destroyRfc4571Reader();
 			this._status = "error";
 			this.reconnectDelayMs = INITIAL_RECONNECT_DELAY_MS;
 			this.nextDialAllowedAt = 0;
 			this.lastRefreshRequestAt = 0;
-			this.notifySourceRefresh();
+			if (this.source?.type === "rfc4571") this.notifySourceRefresh();
 			this.scheduleReconnect();
 		}, StreamBroker.FIRST_VIDEO_TIMEOUT_MS);
 	}
@@ -12796,7 +13148,7 @@ var StreamBroker = class StreamBroker {
 			url: source.url,
 			sdp,
 			...this.logger ? { logger: this.logger.child("rfc4571") } : {}
-		}, this.buildRtpStreamCallbacks("rfc4571", () => this.destroyRfc4571Reader()));
+		}, this.buildRtpStreamCallbacks("rfc4571", () => this.destroyRfc4571Reader(), () => this.rfc4571Reader !== reader));
 		this.rfc4571Reader = reader;
 		reader.connect().catch((err) => {
 			if (this.manualStop || this._suspended) return;
@@ -12809,6 +13161,7 @@ var StreamBroker = class StreamBroker {
 			this.notifySourceRefresh();
 			this.scheduleReconnect();
 		});
+		this.kickRtpActivityWatchdog();
 	}
 	destroyRfc4571Reader() {
 		if (this.rfc4571Reader) {
@@ -13484,6 +13837,7 @@ var SourceParserArgsEntrySchema = require_dist.object({
 var DeviceOverrideSchema = require_dist.object({
 	preBuffer: require_dist.record(require_dist.string(), StreamPreBufferSchema).optional(),
 	joinBurstMaxSpanMs: require_dist.record(require_dist.string(), require_dist.number()).optional(),
+	preRollMs: require_dist.record(require_dist.string(), require_dist.number()).optional(),
 	streamingDebug: require_dist.boolean().optional(),
 	audioMuted: require_dist.boolean().optional(),
 	webrtcDebug: require_dist.boolean().optional(),
@@ -13545,6 +13899,18 @@ function resolveBrokerTier(brokerId, localLookup, remoteBrokerTiers) {
 * Watchdog parameters for the stream-health emitter. Brokers that have
 * received zero video packets for STREAM_STALE_TIMEOUT_MS are reported
 * as `stream.offline`; the next packet flips them back to `stream.online`.
+*
+* THE TWO MINUTES ARE AN OPERATOR CONTRACT, not a tuning knob (2026-08-12).
+* A `stale-timeout` is the ONLY thing downstream is allowed to call an outage
+* (Notification Center: `notification-center/event-intake.ts`,
+* `NC_STREAM_OFFLINE_REASON`), and the operator's rule for it is "a camera
+* reboot must not get through" — a stream that comes back inside this window
+* produces no notification at all, because no `stream.offline` is emitted in
+* the first place. Shortening this window shortens that promise, and nothing
+* downstream re-checks it: this constant IS the two minutes.
+*
+* Nothing emits `stream.offline` faster. The rfc4571 clean-FIN failure edge
+* (`onTeardown`) sets `_status='error'` and reconnects; it does not emit.
 */
 var STREAM_STALE_TIMEOUT_MS = 12e4;
 var STREAM_HEALTH_POLL_MS = 15e3;
@@ -13655,6 +14021,15 @@ var StreamBrokerManager = class StreamBrokerManager {
 	* regardless of prior state.
 	*/
 	streamHealthByBroker = /* @__PURE__ */ new Map();
+	/**
+	* Why each broker last went UNhealthy. Read when it comes back so the
+	* recovery names the same kind of transition its outage did: a broker that
+	* went quiet because the last consumer left comes back `resumed`, not
+	* `recovered`. Without this, an intentional suspend/resume cycle emitted the
+	* same pair a two-minute outage does, and every consumer downstream had to
+	* guess which one it was looking at.
+	*/
+	streamOfflineReasonByBroker = /* @__PURE__ */ new Map();
 	streamHealthTimer;
 	/**
 	* Routes a frame-handle `subscriptionId` (Phase 5 / D9) back to its owning
@@ -13747,6 +14122,13 @@ var StreamBrokerManager = class StreamBrokerManager {
 	* happened to own its ingest (D52/D56).
 	*/
 	defaultJoinBurstMaxSpanMs;
+	/**
+	* Cluster-wide default pre-roll (ms) — motion-start Stage 2. Cluster-scoped
+	* for the same reason as the join-burst bound (a movable ingest role must not
+	* change a camera's behaviour), and 0 by default: pre-roll spends retained
+	* bytes on the ingest node, so it is turned on per camera that needs it.
+	*/
+	defaultPreRollMs = 0;
 	webrtcServer = null;
 	/**
 	* brokerId → the remote-encoded adapter backing a non-owned camera's WebRTC
@@ -14361,6 +14743,32 @@ var StreamBrokerManager = class StreamBrokerManager {
 			overrides: this.deviceOverrides.get(deviceId)?.joinBurstMaxSpanMs
 		}));
 	}
+	/**
+	* Set the cluster-wide default pre-roll and push the newly effective value
+	* into every live broker — same reasoning as the join-burst bound: a broker
+	* outlives the setting that configured it.
+	*/
+	setDefaultPreRollMs(ms) {
+		this.defaultPreRollMs = ms;
+		for (const [brokerId, broker] of this.brokers) {
+			const parsed = parseBrokerId(brokerId);
+			if (!parsed) continue;
+			this.applyPreRoll(broker, parsed.deviceId, parsed.camStreamId);
+		}
+	}
+	/**
+	* Resolve and install this stream's pre-roll (Stage 2). A `pull-http` relay
+	* — the terminal cameras — takes the cluster default as 0 (operator
+	* decision); an explicit per-stream override still reaches it.
+	*/
+	applyPreRoll(broker, deviceId, camStreamId) {
+		broker.setPreRollMs(resolvePreRollMs({
+			camStreamId,
+			clusterMs: this.defaultPreRollMs,
+			overrides: this.deviceOverrides.get(deviceId)?.preRollMs,
+			terminalRelay: this.cameraStreams.get(deviceId)?.get(camStreamId)?.kind === "pull-http"
+		}));
+	}
 	setEventBus(bus) {
 		this.eventBus = bus;
 		this.startStreamHealthWatchdog();
@@ -15922,6 +16330,7 @@ var StreamBrokerManager = class StreamBrokerManager {
 		await Promise.all(stopPromises);
 		this.brokers.clear();
 		this.streamHealthByBroker.clear();
+		this.streamOfflineReasonByBroker.clear();
 		this.frameSubscriptionBroker.clear();
 		this.audioSubscriptionBroker.clear();
 		await this.rtspServer.stop();
@@ -15930,6 +16339,18 @@ var StreamBrokerManager = class StreamBrokerManager {
 		if (this.streamHealthTimer) return;
 		this.streamHealthTimer = setInterval(() => this.evaluateStreamHealth(), STREAM_HEALTH_POLL_MS);
 	}
+	/**
+	* @internal Test seam. Registers a pre-built broker under `brokerId` and runs
+	* ONE stream-health evaluation pass synchronously. Production registers
+	* brokers through the publish/assignment path and runs the sweep on the
+	* {@link STREAM_HEALTH_POLL_MS} interval; this exists only so the
+	* level-triggered phantom-streaming redial (the self-healing backstop) can be
+	* asserted in isolation without standing up the full assignment pipeline.
+	*/
+	runStreamHealthSweepForTest(brokerId, broker) {
+		this.brokers.set(brokerId, broker);
+		this.evaluateStreamHealth();
+	}
 	evaluateStreamHealth() {
 		if (!this.eventBus) return;
 		const now = Date.now();
@@ -15940,8 +16361,12 @@ var StreamBrokerManager = class StreamBrokerManager {
 			const lastPacketAt = broker.getLastPacketAt();
 			const wasHealthy = this.streamHealthByBroker.get(brokerId);
 			const isHealthy = lastPacketAt > 0 && now - lastPacketAt <= STREAM_STALE_TIMEOUT_MS;
+			if (!isHealthy && broker.getStats().status === "streaming") broker.redial("stream-health sweep: phantom streaming, no packets within stale window");
 			if (wasHealthy === isHealthy) continue;
 			this.streamHealthByBroker.set(brokerId, isHealthy);
+			const reason = isHealthy ? wasHealthy === void 0 ? "first-packet" : this.streamOfflineReasonByBroker.get(brokerId) === "suspended" ? "resumed" : "recovered" : broker.suspended ? "suspended" : "stale-timeout";
+			if (isHealthy) this.streamOfflineReasonByBroker.delete(brokerId);
+			else this.streamOfflineReasonByBroker.set(brokerId, reason);
 			this.emitStreamHealth(isHealthy, {
 				deviceId,
 				camStreamId,
@@ -15949,7 +16374,7 @@ var StreamBrokerManager = class StreamBrokerManager {
 				brokerId,
 				sourceType: broker.getActiveSourceType(),
 				lastPacketAt,
-				reason: isHealthy ? wasHealthy === void 0 ? "first-packet" : "recovered" : "stale-timeout"
+				reason
 			});
 		}
 	}
@@ -16444,6 +16869,19 @@ var StreamBrokerManager = class StreamBrokerManager {
 					default: 0,
 					value: override?.joinBurstMaxSpanMs?.[camStreamId] ?? 0
 				},
+				{
+					type: "number",
+					key: `preRollMs:${camStreamId}`,
+					label: "Detection pre-roll",
+					description: "How much video from BEFORE the motion edge a detection decode is handed when it attaches, so the first analysed frames predate the trigger. Costs retained memory on the ingest node while this stream is dialed, and only reaches back as far as the stream has been warm — it never dials a camera. Served to the detection decode alone: viewers, recordings and HomeKit legs are unaffected. 0 = inherit the cluster default (off).",
+					min: 0,
+					max: PRE_ROLL_MAX_MS,
+					step: 250,
+					unit: "ms",
+					span: 2,
+					default: 0,
+					value: override?.preRollMs?.[camStreamId] ?? 0
+				},
 				{
 					type: "select",
 					key: `hwaccel:${camStreamId}`,
@@ -16699,6 +17137,22 @@ var StreamBrokerManager = class StreamBrokerManager {
 				}));
 				continue;
 			}
+			if (fieldKey.startsWith("preRollMs:")) {
+				const camStreamId = fieldKey.slice(10);
+				overrideDirty = true;
+				const pr = { ...nextOverride.preRollMs };
+				if (typeof value === "number" && Number.isFinite(value) && value > 0) pr[camStreamId] = Math.min(PRE_ROLL_MAX_MS, Math.max(250, value));
+				else delete pr[camStreamId];
+				nextOverride.preRollMs = pr;
+				const broker = this.brokers.get(brokerIdFor(deviceId, camStreamId));
+				if (broker) broker.setPreRollMs(resolvePreRollMs({
+					camStreamId,
+					clusterMs: this.defaultPreRollMs,
+					overrides: pr,
+					terminalRelay: this.cameraStreams.get(deviceId)?.get(camStreamId)?.kind === "pull-http"
+				}));
+				continue;
+			}
 			if (fieldKey.startsWith("hwaccel:")) {
 				const camStreamId = fieldKey.slice(8);
 				overrideDirty = true;
@@ -17386,6 +17840,7 @@ var StreamBrokerManager = class StreamBrokerManager {
 		this.applyPreBufferConfig(broker, deviceId, camStreamId);
 		this.applyAudioMuteConfig(broker, deviceId);
 		this.applyJoinBurstBound(broker, deviceId, camStreamId);
+		this.applyPreRoll(broker, deviceId, camStreamId);
 		this.applyClipRetention(deviceId);
 		if (this.deviceOverrides.get(deviceId)?.streamingDebug) broker.setStreamingDebug(true);
 		broker.setSourceProvider(() => {
@@ -17435,6 +17890,7 @@ var StreamBrokerManager = class StreamBrokerManager {
 			reason: "broker-destroyed"
 		});
 		this.streamHealthByBroker.delete(brokerId);
+		this.streamOfflineReasonByBroker.delete(brokerId);
 		await broker.stop();
 		this.brokers.delete(brokerId);
 		this.sweepFrameSubscriptions(brokerId);
@@ -33607,6 +34063,7 @@ var StreamBrokerAddon = class extends require_dist.BaseAddon {
 			maxReconnectDelayMs: 3e4,
 			catalogReconcileIntervalSec: 30,
 			joinBurstMaxSpanMs: DEFAULT_PRIME_BURST_BOUND.maxSpanMs,
+			preRollMs: 0,
 			binaryPath: "",
 			hwaccel: "copy"
 		});
@@ -33665,6 +34122,7 @@ var StreamBrokerAddon = class extends require_dist.BaseAddon {
 		this.brokerManager = new StreamBrokerManager(void 0, this.ctx.logger);
 		this.brokerManager.setDefaultPreBufferSec(this.config.defaultPreBufferSec);
 		this.brokerManager.setDefaultJoinBurstMaxSpanMs(this.config.joinBurstMaxSpanMs);
+		this.brokerManager.setDefaultPreRollMs(this.config.preRollMs);
 		this.brokerManager.setEventBus(this.ctx.eventBus);
 		const localNode = this.ctx.kernel.localNodeId;
 		const localNodeId = localNode ? localNode.includes("/") ? localNode.split("/")[0] : localNode : void 0;
@@ -34200,6 +34658,17 @@ var StreamBrokerAddon = class extends require_dist.BaseAddon {
 					default: DEFAULT_PRIME_BURST_BOUND.maxSpanMs,
 					unit: "ms"
 				},
+				{
+					type: "number",
+					key: "preRollMs",
+					label: "Detection pre-roll",
+					description: "Cluster-wide default for how much video from BEFORE the motion edge a detection decode is handed when it attaches, so the first analysed frames predate the trigger. Off (0) by default: it retains extra video in memory on whichever node ingests the camera, and it can only reach as far back as that stream has been warm — it never dials a camera on its own. Only the detection decode receives it; viewers, recordings and HomeKit legs keep the ordinary join burst. Terminal (MJPEG relay) cameras ignore this default. Override per camera stream.",
+					min: 0,
+					max: PRE_ROLL_MAX_MS,
+					step: 250,
+					default: 0,
+					unit: "ms"
+				},
 				{
 					type: "number",
 					key: "catalogReconcileIntervalSec",