@camstack/addon-pipeline 1.1.53 → 1.1.54

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

@@ -1,11 +1,85 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_chunk = require("../chunk-D6vf50IK.js");
-const require_worker_protocol = require("../worker-protocol-BCfO8gUF.js");
+const require_worker_protocol = require("../worker-protocol-DkL6GDxe.js");
 let node_url = require("node:url");
 let node_fs = require("node:fs");
 node_fs = require_chunk.__toESM(node_fs);
 let node_path = require("node:path");
 node_path = require_chunk.__toESM(node_path);
+//#region src/session-decode/crop-geometry.ts
+/** Clamp to [min,max] then floor to the nearest even number (YUV420P chroma is 2x2 subsampled). */
+function clampEven(value, min, max) {
+	const bounded = Math.min(Math.max(value, min), max);
+	return bounded - bounded % 2;
+}
+/** Resolve `FrameImageOptions.crop` against the decoded frame's dimensions, defaulting to the full frame. */
+function resolveCropRegion(frameWidth, frameHeight, crop) {
+	const left = clampEven(crop?.left ?? 0, 0, Math.max(0, frameWidth - 2));
+	const top = clampEven(crop?.top ?? 0, 0, Math.max(0, frameHeight - 2));
+	return {
+		left,
+		top,
+		width: clampEven(crop?.width ?? frameWidth - left, 2, frameWidth - left),
+		height: clampEven(crop?.height ?? frameHeight - top, 2, frameHeight - top)
+	};
+}
+/** Resolve `FrameImageOptions.resize`, defaulting to the (already cropped) source dimensions. */
+function resolveResizeTarget(cropWidth, cropHeight, resize) {
+	if (!resize) return {
+		width: cropWidth,
+		height: cropHeight
+	};
+	return {
+		width: Math.max(1, Math.round(resize.width)),
+		height: Math.max(1, Math.round(resize.height))
+	};
+}
+/** Whether `region` covers the entire `srcW x srcH` frame (i.e. no real crop). */
+function isFullFrameRegion(region, srcW, srcH) {
+	return region.left === 0 && region.top === 0 && region.width === srcW && region.height === srcH;
+}
+/**
+* Resolve a NORMALIZED [0,1] bbox against a native frame's real pixel dims into
+* an even-aligned pixel crop region. Clamps the box inside the frame so a
+* padded / slightly-out-of-frame bbox never reads past the plane; a degenerate
+* (zero-area) box is widened to the 2px chroma minimum by
+* {@link resolveCropRegion}'s own clamps.
+*/
+function normalizedBboxToCrop(frameWidth, frameHeight, bbox) {
+	return {
+		left: Math.round(bbox.x * frameWidth),
+		top: Math.round(bbox.y * frameHeight),
+		width: Math.max(2, Math.round(bbox.w * frameWidth)),
+		height: Math.max(2, Math.round(bbox.h * frameHeight))
+	};
+}
+/**
+* Aspect-preserving cap of a native crop region to `maxWidth`. Returns
+* `undefined` (no resize → true native crop) when `maxWidth` is absent or the
+* region is already within it.
+*/
+function resolveNativeCropTarget(region, maxWidth) {
+	if (maxWidth === void 0 || maxWidth <= 0 || region.width <= maxWidth) return void 0;
+	const width = Math.round(maxWidth);
+	return {
+		width,
+		height: Math.max(1, Math.round(width * region.height / region.width))
+	};
+}
+/**
+* Full native-crop geometry: normalized bbox → even-aligned source region +
+* (optionally width-capped) output target. The single mapping the decode worker
+* uses to turn a detection-res bbox into a native-res crop request.
+*/
+function resolveNativeCropGeometry(frameWidth, frameHeight, bbox, maxWidth) {
+	const region = resolveCropRegion(frameWidth, frameHeight, normalizedBboxToCrop(frameWidth, frameHeight, bbox));
+	const resize = resolveNativeCropTarget(region, maxWidth);
+	return {
+		region,
+		target: resolveResizeTarget(region.width, region.height, resize)
+	};
+}
+//#endregion
 //#region src/session-decode/frame-slot.ts
 function toReply(held) {
 	return {
@@ -20,6 +94,10 @@ function toReply(held) {
 * pending-pull flag. One instance per decode-worker child session.
 */
 var FrameSlot = class {
+	retainSuperseded;
+	constructor(options) {
+		this.retainSuperseded = options?.retainSuperseded;
+	}
 	nextFrameId = 1;
 	slot = null;
 	/**
@@ -104,11 +182,61 @@ var FrameSlot = class {
 		const previousReserved = this.reserved;
 		this.reserved = held;
 		this.slot = null;
-		previousReserved?.frame.free();
+		if (previousReserved) {
+			if (!(this.retainSuperseded?.(previousReserved.frameId, previousReserved.frame) ?? false)) previousReserved.frame.free();
+		}
 		return toReply(held);
 	}
 };
 //#endregion
+//#region src/session-decode/native-frame-ring.ts
+/**
+* A hard-capped, insertion-ordered map from worker frameId → retained frame.
+* `capacity <= 0` disables retention entirely (every `retain` frees immediately
+* and returns false) — the safe "keep the ring off" knob.
+*/
+var NativeFrameRing = class {
+	capacity;
+	/** Insertion-ordered (Map preserves insertion order) frameId → frame. */
+	frames = /* @__PURE__ */ new Map();
+	constructor(capacity) {
+		this.capacity = capacity;
+	}
+	/** Number of frames currently retained (for tests / metrics). */
+	get size() {
+		return this.frames.size;
+	}
+	/**
+	* Take ownership of `frame` under `frameId`. Frees the oldest retained frame
+	* when the cap is exceeded (FIFO by frameId insertion). Returns `true` when
+	* the ring took ownership (caller MUST NOT free), `false` when retention is
+	* disabled (`capacity <= 0`) and the caller still owns/should free the frame.
+	*/
+	retain(frameId, frame) {
+		if (this.capacity <= 0) return false;
+		const existing = this.frames.get(frameId);
+		if (existing) existing.free();
+		this.frames.set(frameId, frame);
+		while (this.frames.size > this.capacity) {
+			const oldestKey = this.frames.keys().next().value;
+			if (oldestKey === void 0) break;
+			const oldest = this.frames.get(oldestKey);
+			this.frames.delete(oldestKey);
+			oldest?.free();
+		}
+		return true;
+	}
+	/** The retained frame for `frameId`, or `null` if never retained / already evicted. */
+	get(frameId) {
+		return this.frames.get(frameId) ?? null;
+	}
+	/** Free and drop every retained frame. Idempotent (re-dial + teardown call it). */
+	clear() {
+		for (const frame of this.frames.values()) frame.free();
+		this.frames.clear();
+	}
+};
+//#endregion
 //#region src/session-decode/decode-worker-child.ts
 /**
 * Decode-worker CHILD entry point — Epic C P1, Task 2.
@@ -139,6 +267,20 @@ var REDIAL_MS = 3e3;
 /** How often the worker emits its `framesDecoded/framesSkipped/deliveredFps` line. */
 var METRICS_INTERVAL_MS = 1e4;
 /**
+* 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
+* retained slot pins a GPU/VAAPI surface out of the decoder pool (the historic
+* leak site), so the cap MUST stay small; a miss is free (caller falls back to
+* today's detection-frame crop). Override with `CAMSTACK_SESSION_NATIVE_CROP_RING`
+* (0 disables retention entirely); clamped to [0,4], default 2.
+*/
+var NATIVE_RING_CAP = (() => {
+	const raw = Number(process.env["CAMSTACK_SESSION_NATIVE_CROP_RING"]);
+	if (!Number.isFinite(raw)) return 2;
+	return Math.min(4, Math.max(0, Math.floor(raw)));
+})();
+/**
 * The libav GPU scale filter for a hwaccel backend, or `null` when none is
 * known here — those backends fall back to the software crop+scale path.
 * Mirrors `addon-decoder-ffmpeg/src/ffmpeg-args.ts` `gpuScaleFilterForBackend`.
@@ -276,37 +418,6 @@ function backendToHwDeviceConst(backend, consts) {
 		default: return null;
 	}
 }
-/** Clamp to [min,max] then floor to the nearest even number (YUV420P chroma is 2x2 subsampled). */
-function clampEven(value, min, max) {
-	const bounded = Math.min(Math.max(value, min), max);
-	return bounded - bounded % 2;
-}
-/** Resolve `FrameImageOptions.crop` against the decoded frame's dimensions, defaulting to the full frame. */
-function resolveCropRegion(frameWidth, frameHeight, crop) {
-	const left = clampEven(crop?.left ?? 0, 0, Math.max(0, frameWidth - 2));
-	const top = clampEven(crop?.top ?? 0, 0, Math.max(0, frameHeight - 2));
-	return {
-		left,
-		top,
-		width: clampEven(crop?.width ?? frameWidth - left, 2, frameWidth - left),
-		height: clampEven(crop?.height ?? frameHeight - top, 2, frameHeight - top)
-	};
-}
-/** Resolve `FrameImageOptions.resize`, defaulting to the (already cropped) source dimensions. */
-function resolveResizeTarget(cropWidth, cropHeight, resize) {
-	if (!resize) return {
-		width: cropWidth,
-		height: cropHeight
-	};
-	return {
-		width: Math.max(1, Math.round(resize.width)),
-		height: Math.max(1, Math.round(resize.height))
-	};
-}
-/** Whether `region` covers the entire `srcW x srcH` frame (i.e. no real crop). */
-function isFullFrameRegion(region, srcW, srcH) {
-	return region.left === 0 && region.top === 0 && region.width === srcW && region.height === srcH;
-}
 /**
 * Build the libav filtergraph description for the GPU crop+scale path.
 *
@@ -388,6 +499,30 @@ var DecodeWorkerChild = class {
 	*/
 	hwFilter = null;
 	hwFilterKey = "";
+	/**
+	* DEDICATED native-crop GPU filtergraph + software scaler, kept SEPARATE from
+	* the detection {@link hwFilter}/{@link scaler} so a native-crop request never
+	* evicts (rebuilds) the hot-path detection filter cache — the crop geometry
+	* differs from the stable detection geometry, so sharing one cache would
+	* thrash it. Same dispose discipline: both are closed on every re-dial
+	* ({@link closeInput}) and on teardown. Rebuilt lazily per crop geometry.
+	*/
+	nativeCropHwFilter = null;
+	nativeCropHwFilterKey = "";
+	nativeCropScaler = null;
+	nativeCropScalerKey = "";
+	/**
+	* Bounded native-frame retention ring — the survival window for a frame's
+	* NATIVE surface between detection (on the shipped small frame) and the crop
+	* request that follows. Hard-capped at {@link NATIVE_RING_CAP}; single
+	* ownership via the {@link FrameSlot} `retainSuperseded` hook (a frame enters
+	* the ring exactly when the slot would otherwise free it). Cleared on every
+	* re-dial + teardown (see {@link closeInput}).
+	*/
+	nativeRing = new NativeFrameRing(NATIVE_RING_CAP);
+	/** Throttled native-crop hit/miss counters, emitted with the throughput line. */
+	nativeCropHits = 0;
+	nativeCropMisses = 0;
 	/** Scrypted-style throughput counters (plain integers, no per-frame allocation). */
 	framesDecoded = 0;
 	/** Child-side skips only (HW-guard drops + probe/degrade frees); slot drops add {@link FrameSlot.droppedCount}. */
@@ -420,7 +555,7 @@ var DecodeWorkerChild = class {
 	* the reserve-on-pull invariant (`e3c78a9b`) is unit-tested without
 	* node-av. See that file's doc comment for the full semantics.
 	*/
-	frames = new FrameSlot();
+	frames = new FrameSlot({ retainSuperseded: (frameId, frame) => this.nativeRing.retain(frameId, frame) });
 	/**
 	* Mirrors whether `this.frames` currently has a pull waiting, so
 	* `teardown` knows to resolve it with `{kind:'ended'}` — `FrameSlot`
@@ -446,6 +581,9 @@ var DecodeWorkerChild = class {
 			case "toBuffer":
 				this.handleToBuffer(message.frameId, message.opts);
 				return;
+			case "nativeCrop":
+				this.handleNativeCrop(message.requestId, message.frameId, message.bbox, message.maxWidth);
+				return;
 			case "stop":
 				this.handleStop();
 				return;
@@ -470,6 +608,9 @@ var DecodeWorkerChild = class {
 		this.scaler?.[Symbol.dispose]?.();
 		this.scaler = null;
 		this.scalerKey = "";
+		this.nativeCropScaler?.[Symbol.dispose]?.();
+		this.nativeCropScaler = null;
+		this.nativeCropScalerKey = "";
 		this.hwContext?.[Symbol.dispose]?.();
 		this.hwContext = null;
 		if (this.pendingPull) {
@@ -484,7 +625,7 @@ var DecodeWorkerChild = class {
 		const deliveredDelta = this.framesDelivered - this.lastDeliveredSnapshot;
 		const deliveredFps = Math.round(deliveredDelta / windowMs * 1e3 * 10) / 10;
 		const skipped = this.framesSkipped + this.frames.droppedCount;
-		this.emitStderr(`session-decode metrics {framesDecoded:${this.framesDecoded}, framesSkipped:${skipped}, deliveredFps:${deliveredFps}}${final ? " (final)" : ""}\n`);
+		this.emitStderr(`session-decode metrics {framesDecoded:${this.framesDecoded}, framesSkipped:${skipped}, deliveredFps:${deliveredFps}, nativeCropHits:${this.nativeCropHits}, nativeCropMisses:${this.nativeCropMisses}}${final ? " (final)" : ""}\n`);
 		this.lastMetricsAt = now;
 		this.lastDeliveredSnapshot = this.framesDelivered;
 	}
@@ -534,6 +675,145 @@ var DecodeWorkerChild = class {
 			this.sendError(`decode-worker-child: toBuffer failed — ${errMessage(err)}`, frameId);
 		}
 	}
+	/**
+	* Best-effort NATIVE-resolution crop of a still-retained frame. Resolves the
+	* frame from the reserved slot (the latest, most common case) or the
+	* retention ring (an older frame detection has since moved past). A miss
+	* (frame aged out) or ANY crop error replies `nativeCropMiss` so the caller
+	* falls back to today's detection-frame crop — it NEVER degrades the
+	* detection session (unlike {@link hwScaleToBuffer}, which flips the whole
+	* session to software on a GPU-filter error).
+	*/
+	handleNativeCrop(requestId, frameId, bbox, maxWidth) {
+		const frame = this.nativeRing.get(frameId) ?? this.frames.toBuffer(frameId);
+		if (!frame) {
+			this.nativeCropMisses++;
+			this.send({
+				kind: "nativeCropMiss",
+				requestId
+			});
+			return;
+		}
+		try {
+			const resolved = this.resolveNativeCrop(frame, bbox, maxWidth);
+			const bytes = frame.isHwFrame() ? this.nativeHwCropToBuffer(frame, resolved) : this.nativeScaleCropToBuffer(frame, resolved);
+			this.nativeCropHits++;
+			this.send({
+				kind: "nativeCropResult",
+				requestId,
+				bytes,
+				width: resolved.target.width,
+				height: resolved.target.height
+			});
+		} catch (err) {
+			this.nativeCropMisses++;
+			this.emitStderr(`decode-worker-child: native crop failed (requestId ${requestId}) — ${errMessage(err)}\n`);
+			this.send({
+				kind: "nativeCropMiss",
+				requestId
+			});
+		}
+	}
+	/** Map a normalized bbox to an even-aligned pixel crop + (optionally capped) target. */
+	resolveNativeCrop(frame, bbox, maxWidth) {
+		return resolveNativeCropGeometry(frame.width, frame.height, bbox, maxWidth);
+	}
+	/**
+	* Software native crop — the leak-free path: offset the retained YUV420P
+	* frame's plane pointers to the crop origin (zero-copy) and scale ONLY the
+	* ROI into a tightly-packed rgb buffer via a DEDICATED scaler (never the
+	* detection {@link scaler}). Mirrors {@link scaleRoiToBuffer}, rgb-fixed.
+	*/
+	nativeScaleCropToBuffer(frame, resolved) {
+		const nav = this.nav;
+		const C = this.consts;
+		if (!nav || !C) throw new Error("node-av not initialized");
+		const { region, target } = resolved;
+		const planes = frame.data;
+		const strides = frame.linesize;
+		const yPlane = planes?.[0];
+		const uPlane = planes?.[1];
+		const vPlane = planes?.[2];
+		if (!yPlane || !uPlane || !vPlane) throw new Error("decode-worker-child: retained frame missing planar YUV420P data");
+		const yStride = strides[0] ?? 0;
+		const cStride = strides[1] ?? 0;
+		const ySlice = yPlane.subarray(region.top * yStride + region.left);
+		const uSlice = uPlane.subarray(region.top / 2 * cStride + region.left / 2);
+		const vSlice = vPlane.subarray(region.top / 2 * cStride + region.left / 2);
+		const scaler = this.ensureNativeCropScaler(nav, C, region.width, region.height, target.width, target.height);
+		const dstStride = target.width * 3;
+		const dstBuffer = Buffer.allocUnsafe(dstStride * target.height);
+		const scaledHeight = scaler.scaleSync([
+			ySlice,
+			uSlice,
+			vSlice
+		], [
+			yStride,
+			cStride,
+			cStride
+		], 0, region.height, [dstBuffer], [dstStride]);
+		if (scaledHeight < 0) throw new Error(`native crop sws_scale failed: ${scaledHeight}`);
+		if (scaledHeight !== target.height) throw new Error(`native crop scaler produced ${scaledHeight} of ${target.height} rows`);
+		return dstBuffer;
+	}
+	/**
+	* Hardware native crop — run the retained GPU surface through a DEDICATED
+	* crop filtergraph (`hwdownload,format=nv12,crop=…,scale=…,format=rgb24`) and
+	* pack the small result. Mirrors {@link hwScaleToBuffer} but uses its OWN
+	* cached filter and, on error, throws WITHOUT degrading the session.
+	*/
+	nativeHwCropToBuffer(frame, resolved) {
+		const { region, target } = resolved;
+		const outputs = this.ensureNativeCropHwFilter(region, target).processAllSync(frame);
+		const first = outputs[0];
+		if (!first) {
+			for (const out of outputs) out.free();
+			throw new Error("native crop GPU filtergraph produced no frame");
+		}
+		try {
+			const plane = first.data?.[0];
+			if (!plane) throw new Error("native crop GPU frame missing packed plane data");
+			return packSinglePlane(plane, first.linesize[0] ?? 0, target.width, target.height, 3);
+		} finally {
+			for (const out of outputs) out.free();
+		}
+	}
+	/** Build-once / reuse the dedicated native-crop software scaler (rgb out). */
+	ensureNativeCropScaler(nav, C, srcW, srcH, dstW, dstH) {
+		const key = `${srcW}x${srcH}->${dstW}x${dstH}`;
+		const cached = this.nativeCropScaler;
+		if (cached && key === this.nativeCropScalerKey) return cached;
+		this.nativeCropScaler?.[Symbol.dispose]?.();
+		this.nativeCropScaler = null;
+		this.nativeCropScalerKey = "";
+		const scaler = new nav.SoftwareScaleContext();
+		scaler.getContext(srcW, srcH, C.AV_PIX_FMT_YUV420P, dstW, dstH, C.AV_PIX_FMT_RGB24, C.SWS_FAST_BILINEAR);
+		const initRet = scaler.initContext();
+		if (initRet < 0) {
+			scaler[Symbol.dispose]?.();
+			throw new Error(`native crop sws_init_context failed: ${initRet}`);
+		}
+		this.nativeCropScaler = scaler;
+		this.nativeCropScalerKey = key;
+		return scaler;
+	}
+	/** Build-once / reuse the dedicated native-crop GPU filtergraph (rgb out). */
+	ensureNativeCropHwFilter(region, target) {
+		const nav = this.nav;
+		const scaleFilter = this.gpuScaleFilter;
+		if (!nav || !scaleFilter || !this.hwContext) throw new Error("decode-worker-child: native GPU crop requested without a HW context");
+		const key = `${region.left},${region.top},${region.width},${region.height}->${target.width}x${target.height}`;
+		const cached = this.nativeCropHwFilter;
+		if (cached && key === this.nativeCropHwFilterKey) return cached;
+		this.nativeCropHwFilter?.close();
+		this.nativeCropHwFilter = null;
+		this.nativeCropHwFilterKey = "";
+		const description = buildGpuFilterDescription(scaleFilter, region, target, false, "rgb24");
+		const filter = nav.FilterAPI.create(description, { hardware: this.hwContext });
+		this.nativeCropHwFilter = filter;
+		this.nativeCropHwFilterKey = key;
+		return filter;
+	}
 	handleStop() {
 		this.teardown();
 		process.exit(0);
@@ -887,6 +1167,10 @@ var DecodeWorkerChild = class {
 	* the next dial's first `toBuffer`.
 	*/
 	closeInput() {
+		this.nativeRing.clear();
+		this.nativeCropHwFilter?.close();
+		this.nativeCropHwFilter = null;
+		this.nativeCropHwFilterKey = "";
 		this.hwFilter?.close();
 		this.hwFilter = null;
 		this.hwFilterKey = "";