@camstack/addon-pipeline 1.2.213 → 1.2.214

package/dist/session-decode/decode-worker-child.js

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_worker_protocol = require("../worker-protocol-CYopQrkK.js");
-const require_lazy_sharp = require("../lazy-sharp-BawPy_a9.js");
+const require_worker_protocol = require("../worker-protocol-BWO2WNjw.js");
+const require_lazy_sharp = require("../lazy-sharp-BeeQGCUu.js");
 //#region src/session-decode/color-conversion.ts
 /**
 * Explicit YUV→RGB colorspace/range resolution for the session-decode worker.
@@ -208,7 +208,9 @@ function toReply(held) {
 		frameId: held.frameId,
 		timestamp: held.timestamp,
 		width: held.width,
-		height: held.height
+		height: held.height,
+		capturedAt: held.capturedAt,
+		preRoll: held.preRoll
 	};
 }
 /**
@@ -252,7 +254,7 @@ var FrameSlot = class {
 	* immediately and reserving the frame); otherwise returns `null` and the
 	* frame simply waits in the slot for the next `pull`.
 	*/
-	publish(frame, timestamp, minIntervalMs) {
+	publish(frame, timestamp, minIntervalMs, meta) {
 		if (minIntervalMs > 0 && this.lastPublishedAt !== null && timestamp - this.lastPublishedAt < minIntervalMs) {
 			this.throttledCount++;
 			frame.free();
@@ -266,7 +268,9 @@ var FrameSlot = class {
 			frame,
 			timestamp,
 			width: frame.width,
-			height: frame.height
+			height: frame.height,
+			capturedAt: meta?.capturedAt ?? timestamp,
+			preRoll: meta?.preRoll ?? false
 		};
 		if (previous) this.supersededCount++;
 		previous?.frame.free();
@@ -319,6 +323,153 @@ var FrameSlot = class {
 	}
 };
 //#endregion
+//#region src/session-decode/media-clock.ts
+/**
+* Convert a container pts to milliseconds.
+*
+* Returns `null` — never a fabricated `0` — for a time base that cannot
+* describe a duration. A zero here would place every frame of the session at
+* the anchor, i.e. a whole burst of detections sharing one instant, which is
+* exactly the kind of plausible-looking wrong timestamp this module exists to
+* refuse. The caller degrades to the wall clock instead.
+*/
+function ptsToMs(pts, timeBase) {
+	if (!Number.isFinite(timeBase.num) || !Number.isFinite(timeBase.den)) return null;
+	if (timeBase.num <= 0 || timeBase.den <= 0) return null;
+	return Number(pts) * timeBase.num * 1e3 / timeBase.den;
+}
+/** Anchor the session's media clock on its first decoded frame. */
+function anchorMediaClock(input) {
+	const preRoll = Number.isFinite(input.preRollMs) && input.preRollMs > 0 ? input.preRollMs : 0;
+	return {
+		firstPtsMs: input.firstPtsMs,
+		wallAtFirstPts: input.nowWall - preRoll
+	};
+}
+/**
+* The wall clock at which the frame with `ptsMs` was shot.
+*
+* Clamped to `nowWall`: a container whose pts runs past the anchor (a clock
+* jump, a source whose pts is not wall-clock-shaped, a re-dial that reset it)
+* must never produce a track that starts in the FUTURE. A future `firstSeen`
+* sorts a track ahead of everything, and no later pass can detect that it is
+* wrong. Clamping loses precision on a pathological source and keeps the
+* ordering property every consumer relies on.
+*/
+function mediaWallClockOf(anchor, ptsMs, nowWall) {
+	const shotAt = anchor.wallAtFirstPts + (ptsMs - anchor.firstPtsMs);
+	return shotAt > nowWall ? nowWall : shotAt;
+}
+//#endregion
+//#region src/session-decode/pre-roll-burst.ts
+var ADMITTED = { admitted: true };
+/**
+* Choose the media stride for one burst.
+*
+* `plannedFrames` is what the stride actually yields, so a caller can log the
+* intent next to the outcome — a budget that is never reached and a budget that
+* is always hit are different problems and used to read the same.
+*/
+function planPreRollBurst(input) {
+	const span = Number.isFinite(input.spanMs) && input.spanMs > 0 ? input.spanMs : 0;
+	const fps = Number.isFinite(input.detectionFps) && input.detectionFps > 0 ? input.detectionFps : 1;
+	const maxFrames = Number.isFinite(input.maxFrames) && input.maxFrames > 0 ? input.maxFrames : 0;
+	if (span === 0 || maxFrames === 0) return {
+		strideMs: Number.POSITIVE_INFINITY,
+		plannedFrames: 0,
+		subsampled: false
+	};
+	const cadenceMs = 1e3 / fps;
+	const budgetStrideMs = span / maxFrames;
+	const subsampled = budgetStrideMs > cadenceMs;
+	const strideMs = subsampled ? budgetStrideMs : cadenceMs;
+	return {
+		strideMs,
+		plannedFrames: Math.min(maxFrames, Math.max(1, Math.floor(span / strideMs))),
+		subsampled
+	};
+}
+/**
+* The live, per-session budget. Stateful by necessity — a stride is a decision
+* about the PREVIOUS admission — and deliberately free of any clock of its own:
+* both times are passed in, so a test can drive a catch-up burst without
+* pretending 4 s of media takes 4 s to decode.
+*/
+var PreRollBurst = class {
+	budget;
+	plan;
+	startedAtWall;
+	liveEdgeWall;
+	lastAdmittedMediaWall = null;
+	offered = 0;
+	inferred = 0;
+	done = false;
+	drops = {
+		stride: 0,
+		"budget-frames": 0,
+		"budget-wall-ms": 0,
+		"live-edge": 0
+	};
+	constructor(input) {
+		this.budget = input.budget;
+		this.plan = input.plan;
+		this.startedAtWall = input.startedAtWall;
+		this.liveEdgeWall = input.liveEdgeWall;
+	}
+	/** True once the burst has ended — by budget, or by reaching the live edge. */
+	get finished() {
+		return this.done;
+	}
+	/**
+	* Offer one decoded history frame.
+	*
+	* `mediaWall` is the frame's OWN moment (see `media-clock.ts`); `nowWall` is
+	* the wall clock of the offer. The two are different by construction during
+	* catch-up, which is the whole reason this class exists.
+	*/
+	offer(mediaWall, nowWall) {
+		this.offered++;
+		if (this.done) return this.drop("budget-frames");
+		if (mediaWall >= this.liveEdgeWall) {
+			this.done = true;
+			return this.drop("live-edge");
+		}
+		if (nowWall - this.startedAtWall >= this.budget.maxWallMs) {
+			this.done = true;
+			return this.drop("budget-wall-ms");
+		}
+		if (this.inferred >= this.budget.maxFrames) {
+			this.done = true;
+			return this.drop("budget-frames");
+		}
+		if (this.lastAdmittedMediaWall !== null && mediaWall - this.lastAdmittedMediaWall < this.plan.strideMs) return this.drop("stride");
+		this.lastAdmittedMediaWall = mediaWall;
+		this.inferred++;
+		return ADMITTED;
+	}
+	/** End the burst without offering a frame (session torn down, decode ended). */
+	finish() {
+		this.done = true;
+	}
+	report() {
+		return {
+			offered: this.offered,
+			inferred: this.inferred,
+			dropped: this.offered - this.inferred,
+			droppedByReason: { ...this.drops },
+			strideMs: Math.round(this.plan.strideMs),
+			subsampled: this.plan.subsampled
+		};
+	}
+	drop(reason) {
+		this.drops[reason]++;
+		return {
+			admitted: false,
+			reason
+		};
+	}
+};
+//#endregion
 //#region src/session-decode/lease-activity-gate.ts
 /**
 * Demand-driven gate for the native-frame lease capture (see
@@ -1523,6 +1674,18 @@ var REDIAL_MS = 3e3;
 /** How often the worker emits its `framesDecoded/framesSkipped/deliveredFps` line. */
 var METRICS_INTERVAL_MS = 1e4;
 /**
+* Wall-clock ceiling on one pre-roll catch-up burst.
+*
+* A burst is a race against the live edge it is trying to get ahead of. Two
+* seconds in, the decoder has either caught up (the burst ended on its own) or
+* something is wrong — a cold GPU, a node under load, a camera whose GOP is
+* longer than its history — and continuing to spend inference on footage that
+* is now three or four seconds stale buys an operator nothing while a live
+* frame waits. The frame budget bounds the WORK; this bounds the WINDOW in
+* which that work is still worth doing.
+*/
+var PRE_ROLL_BURST_MAX_WALL_MS = 2e3;
+/**
 * Hard cap on the native-frame retention ring (native-res crop feature). Kept
 * DELIBERATELY TINY — its only job is to cover the detection→crop latency
 * (typically 1-4 frames), NOT the full shm ring depth. On the HW path every
@@ -2156,6 +2319,23 @@ var DecodeWorkerChild = class {
 	sessionFormat = "rgb";
 	minIntervalMs = 0;
 	/**
+	* Session media clock, anchored on the FIRST decoded frame. Null until that
+	* frame arrives, or forever on a source whose pts cannot be read — in which
+	* case every frame falls back to the wall clock, exactly as before.
+	*/
+	mediaClock = null;
+	/** History this dial asked the broker for; `0` ⇒ there is no burst. */
+	preRollMs = 0;
+	/** Frames the catch-up burst may send to inference. */
+	preRollMaxFrames = 0;
+	/** The live catch-up burst, or null once it has ended (or never started). */
+	preRollBurst = null;
+	/** Whether the burst's report has already been sent — it is sent exactly once. */
+	preRollReported = false;
+	/** Media wall clock of the OLDEST and NEWEST frames the burst admitted. */
+	preRollFirstMediaWall = null;
+	preRollLastMediaWall = null;
+	/**
 	* The latest-wins decoded-frame slot + reserved-for-`toBuffer` holder +
 	* pending-pull flag — extracted to `FrameSlot` (Epic C P2 Task 2 / I2) so
 	* the reserve-on-pull invariant (`e3c78a9b`) is unit-tested without
@@ -2217,6 +2397,7 @@ var DecodeWorkerChild = class {
 			this.metricsTimer = null;
 		}
 		if (this.started) this.logMetrics(true);
+		this.endPreRollBurst();
 		this.abortController?.abort();
 		this.frames.free();
 		this.closeInput();
@@ -2276,6 +2457,8 @@ var DecodeWorkerChild = class {
 		this.emitStderr(`decode-worker-child: ${require_worker_protocol.formatNativeLeaseKnobs(NATIVE_LEASE_KNOBS)}\n`, "info");
 		this.sessionFormat = opts.format ?? "rgb";
 		this.minIntervalMs = opts.fps && opts.fps > 0 ? 1e3 / opts.fps : 0;
+		this.preRollMs = opts.preRollMs && opts.preRollMs > 0 ? opts.preRollMs : 0;
+		this.preRollMaxFrames = opts.preRollMaxFrames && opts.preRollMaxFrames > 0 ? opts.preRollMaxFrames : 0;
 		this.lastMetricsAt = Date.now();
 		this.metricsTimer = setInterval(() => this.logMetrics(false), METRICS_INTERVAL_MS);
 		this.metricsTimer.unref?.();
@@ -3108,14 +3291,140 @@ var DecodeWorkerChild = class {
 		}
 		this.publishFrame(frame);
 	}
-	/** Publish to the latest-wins slot; deliver immediately if a `pull` is pending. */
+	/**
+	* Publish to the latest-wins slot; deliver immediately if a `pull` is pending.
+	*
+	* ## Where the pre-roll used to die
+	*
+	* This method used to be one line: `this.frames.publish(frame, Date.now(),
+	* this.minIntervalMs)`. `FrameSlot.publish` throttles by comparing that
+	* `Date.now()` against the previous publish's, and during a catch-up burst
+	* that comparison is meaningless — the restreamer replays ~4 s of retained
+	* media and the decoder chews through all of it inside a few hundred
+	* milliseconds of WALL clock. So the throttle admitted one or two frames of
+	* the whole window and `frame.free()`d the rest, and the two frames on which
+	* device 617's cyclist scored above the vehicle floor (0.5669 and 0.5366,
+	* 1.68 s before the live track was born) were freed here, having been
+	* received, decoded and paid for in full.
+	*
+	* The fix is not to weaken the throttle. A live frame still paces on wall
+	* clock, unchanged. A HISTORY frame paces on its own MEDIA clock instead,
+	* under an explicit budget, because media time is the only clock on which
+	* "one frame per 333 ms of footage" means what it says.
+	*/
 	publishFrame(frame) {
-		const reply = this.frames.publish(frame, Date.now(), this.minIntervalMs);
+		const now = Date.now();
+		const mediaWall = this.mediaWallClockOfFrame(frame, now);
+		const verdict = this.offerToPreRollBurst(mediaWall, now);
+		if (verdict === "dropped") {
+			this.framesSkipped++;
+			frame.free();
+			return;
+		}
+		const preRoll = verdict === "pre-roll";
+		const reply = this.frames.publish(frame, preRoll ? mediaWall : now, preRoll ? 0 : this.minIntervalMs, {
+			capturedAt: mediaWall,
+			preRoll
+		});
 		if (reply) {
 			this.pendingPull = false;
 			this.deliverFrame(reply);
 		}
 	}
+	/**
+	* The frame's own moment, from its pts — or the wall clock when the source
+	* cannot say.
+	*
+	* The media clock is anchored on the FIRST frame of the session: that frame
+	* is `preRollMs` old by construction, because the pre-roll is what the dial
+	* asked for and the restreamer serves it before anything live. A source whose
+	* pts cannot be converted (no time base, a zero denominator) gets no clock at
+	* all and therefore no burst — a fabricated media time would date a whole
+	* burst of detections at one wrong instant, which is worse than not inferring
+	* them at all.
+	*/
+	mediaWallClockOfFrame(frame, now) {
+		const ptsMs = this.frameMediaPtsMs(frame);
+		if (ptsMs === null) return now;
+		if (!this.mediaClock) {
+			this.mediaClock = anchorMediaClock({
+				firstPtsMs: ptsMs,
+				preRollMs: this.preRollMs,
+				nowWall: now
+			});
+			if (this.preRollMs > 0 && this.preRollMaxFrames > 0) this.preRollBurst = new PreRollBurst({
+				budget: {
+					maxFrames: this.preRollMaxFrames,
+					maxWallMs: PRE_ROLL_BURST_MAX_WALL_MS
+				},
+				plan: planPreRollBurst({
+					spanMs: this.preRollMs,
+					detectionFps: this.minIntervalMs > 0 ? 1e3 / this.minIntervalMs : 1,
+					maxFrames: this.preRollMaxFrames
+				}),
+				startedAtWall: now,
+				liveEdgeWall: now
+			});
+		}
+		return mediaWallClockOf(this.mediaClock, ptsMs, now);
+	}
+	/** This frame's pts in ms, or `null` when the source cannot express one. */
+	frameMediaPtsMs(frame) {
+		const pts = frame.pts;
+		const timeBase = frame.timeBase;
+		if (typeof pts !== "bigint") return null;
+		if (typeof timeBase !== "object" || timeBase === null) return null;
+		const num = Reflect.get(timeBase, "num");
+		const den = Reflect.get(timeBase, "den");
+		if (typeof num !== "number" || typeof den !== "number") return null;
+		return ptsToMs(pts, {
+			num,
+			den
+		});
+	}
+	/**
+	* Ask the burst whether this frame is history worth inferring.
+	*
+	* `'live'` — no burst, or the burst has ended. The ordinary path, untouched.
+	* `'pre-roll'` — inside the budget; delivered marked, to the runner's lane.
+	* `'dropped'` — history the budget refused. Freed by the caller and counted.
+	*/
+	offerToPreRollBurst(mediaWall, now) {
+		const burst = this.preRollBurst;
+		if (!burst) return "live";
+		const verdict = burst.offer(mediaWall, now);
+		if (verdict.admitted) {
+			if (this.preRollFirstMediaWall === null) this.preRollFirstMediaWall = mediaWall;
+			this.preRollLastMediaWall = mediaWall;
+			return "pre-roll";
+		}
+		if (burst.finished) {
+			this.endPreRollBurst();
+			return verdict.reason === "live-edge" ? "live" : "dropped";
+		}
+		return "dropped";
+	}
+	/** Close the burst and send its accounting — exactly once per session. */
+	endPreRollBurst() {
+		const burst = this.preRollBurst;
+		this.preRollBurst = null;
+		if (!burst || this.preRollReported) return;
+		this.preRollReported = true;
+		burst.finish();
+		const report = burst.report();
+		const first = this.preRollFirstMediaWall;
+		const last = this.preRollLastMediaWall;
+		this.send({
+			kind: "preRollReport",
+			offered: report.offered,
+			inferred: report.inferred,
+			dropped: report.dropped,
+			droppedByReason: report.droppedByReason,
+			strideMs: report.strideMs,
+			subsampled: report.subsampled,
+			spanMs: first !== null && last !== null ? Math.round(last - first) : 0
+		});
+	}
 	/** Send a `frame` reply to the parent and count it toward `deliveredFps`. */
 	deliverFrame(reply) {
 		this.framesDelivered++;
@@ -3172,7 +3481,9 @@ var DecodeWorkerChild = class {
 			timestamp: reply.timestamp,
 			width: reply.width,
 			height: reply.height,
-			format: this.sessionFormat
+			format: this.sessionFormat,
+			capturedAt: reply.capturedAt,
+			...reply.preRoll ? { preRoll: true } : {}
 		};
 	}
 	/**