@camstack/addon-pipeline 1.1.26 → 1.1.28

package/dist/decoder-nodeav/index.mjs

@@ -0,0 +1,1210 @@
+import { B as errMsg, V as BaseAddon, d as HWACCEL_OPTIONS, s as DEFAULT_DECODER_HWACCEL_CONFIG, x as decoderCapability } from "../dist-C6_wgXqF.mjs";
+import { a as resolveDecoderBackend, i as NotifyingRingBuffer, n as RING_BUDGET_MB, r as makeSegmentName, t as DecoderFrameRingSink } from "../frame-ring-sink-Cs9vby6v.mjs";
+import { FrameRingReaderCache } from "@camstack/shm-ring";
+import { randomUUID } from "node:crypto";
+//#region src/decoder-nodeav/scaler-geometry.ts
+/**
+* Decide the scaler action for an incoming frame's source geometry.
+*
+* @param current  The scaler's configured source geometry, or `null` when no
+*                 scaler has been built yet.
+* @param incoming The source geometry of the frame about to be scaled.
+*/
+function resolveScalerAction(current, incoming) {
+	if (current === null) return "init";
+	if (current.width === incoming.width && current.height === incoming.height && current.format === incoming.format) return "reuse";
+	return "rebuild";
+}
+//#endregion
+//#region src/decoder-nodeav/nodeav-decoder-session.ts
+/** Map our canonical backend name to the node-av `AV_HWDEVICE_TYPE_*` constant. */
+function backendToHwDeviceConst(backend, consts) {
+	switch (backend) {
+		case "videotoolbox": return consts.AV_HWDEVICE_TYPE_VIDEOTOOLBOX;
+		case "cuda": return consts.AV_HWDEVICE_TYPE_CUDA;
+		case "nvdec": return consts.AV_HWDEVICE_TYPE_CUDA;
+		case "vaapi": return consts.AV_HWDEVICE_TYPE_VAAPI;
+		case "qsv": return consts.AV_HWDEVICE_TYPE_QSV;
+		case "d3d11va": return consts.AV_HWDEVICE_TYPE_D3D11VA;
+		case "dxva2": return consts.AV_HWDEVICE_TYPE_DXVA2;
+		case "amf": return consts.AV_HWDEVICE_TYPE_AMF;
+		case "vdpau": return consts.AV_HWDEVICE_TYPE_VDPAU;
+		case "drm": return consts.AV_HWDEVICE_TYPE_DRM;
+		default: return null;
+	}
+}
+/** Pick the hw pixel format for a given backend — used in get_format callback. */
+function backendToHwPixFmt(backend, consts) {
+	switch (backend) {
+		case "videotoolbox": return consts.AV_PIX_FMT_VIDEOTOOLBOX;
+		case "cuda": return consts.AV_PIX_FMT_CUDA;
+		case "nvdec": return consts.AV_PIX_FMT_CUDA;
+		case "vaapi": return consts.AV_PIX_FMT_VAAPI;
+		case "qsv": return consts.AV_PIX_FMT_QSV;
+		case "d3d11va": return consts.AV_PIX_FMT_D3D11;
+		case "dxva2": return consts.AV_PIX_FMT_DXVA2_VLD;
+		case "amf": return consts.AV_PIX_FMT_D3D11;
+		case "vdpau": return consts.AV_PIX_FMT_VDPAU;
+		case "drm": return consts.AV_PIX_FMT_DRM_PRIME;
+		default: return null;
+	}
+}
+var _nav = null;
+var _consts = null;
+var _sharp = null;
+async function getNodeAv() {
+	if (!_nav) _nav = await import("../dist-DluJuxV5.mjs");
+	return _nav;
+}
+async function getConstants() {
+	if (!_consts) _consts = await import("../constants-oYgW36Ty.mjs");
+	return _consts;
+}
+async function getSharp() {
+	if (!_sharp) _sharp = (await import("sharp")).default;
+	return _sharp;
+}
+var noopLogger = {
+	debug() {},
+	info() {},
+	warn() {},
+	error() {},
+	child() {
+		return noopLogger;
+	},
+	withTags() {
+		return noopLogger;
+	}
+};
+var NodeAvDecoderSession = class NodeAvDecoderSession {
+	config;
+	logger;
+	frameCallbacks = /* @__PURE__ */ new Set();
+	handleCallbacks = /* @__PURE__ */ new Set();
+	destroyed = false;
+	/**
+	* Frame delivery mode (see {@link DecoderFrameSink}). `'shm'` lazily
+	* constructs `frameRingSink` and routes every decoded frame through it.
+	*/
+	frameSink;
+	/**
+	* The shared-memory ring writer for this stream. Created lazily on the
+	* first decoded frame in `'shm'` mode (the segment cannot be sized until
+	* the output geometry is known) and torn down in `destroy`.
+	*/
+	frameRingSink = null;
+	parser = null;
+	codecCtx = null;
+	scaler = null;
+	avPacket = null;
+	avFrame = null;
+	dstFrame = null;
+	EAGAIN = -11;
+	PIX_FMT_GRAY8 = 8;
+	PIX_FMT_RGB24 = 2;
+	SWS_FAST_BILINEAR = 1;
+	/**
+	* Decoder output mode. Drives both the scaler's destination pixel
+	* format and whether sharp runs the JPEG encode at the end:
+	*
+	* - `'jpeg'` — scaler→RGB24 → sharp encode → emit JPEG bytes
+	* - `'rgb'`  — scaler→RGB24 → emit raw RGB24 (no sharp)
+	* - `'gray'` — scaler→GRAY8 → emit raw GRAY8 (no sharp)
+	*
+	* The broker holds the policy decision on which mode to request based
+	* on its active subscribers; on-the-fly conversion (e.g. RGB→JPEG for
+	* a WebRTC consumer that joined while detection holds the decoder in
+	* RGB mode) happens broker-side via the per-frame conversion cache.
+	*/
+	outputMode;
+	sharpFn = null;
+	/**
+	* Backpressure for the sharp JPEG encode pipeline. The broker
+	* currently creates sessions with `maxFps: 0` (unlimited) and relies
+	* on per-subscriber throttling, so without a bound the
+	* fire-and-forget `sharp(...).toBuffer()` chain would accumulate
+	* unboundedly whenever sharp falls behind the decoder. Cap at
+	* `MAX_JPEG_INFLIGHT` pending encodes per session — any frame that
+	* arrives while the cap is saturated is dropped and counted.
+	*/
+	static MAX_JPEG_INFLIGHT = 2;
+	jpegEncodeInFlight = 0;
+	/**
+	* Map a `DecoderSessionConfig.outputFormat` value to one of the three
+	* native scaler/encoder modes the session understands. The cap-level
+	* format vocabulary is broader (it accepts `bgr`, `yuv420`) than what
+	* libav's scaler is wired for here — anything else degrades to RGB
+	* (the canonical raw mode) and the broker is expected to convert
+	* downstream if a subscriber needs a different shape.
+	*/
+	static resolveOutputMode(format) {
+		if (format === "jpeg" || format === void 0) return "jpeg";
+		if (format === "gray") return "gray";
+		return "rgb";
+	}
+	initialized = false;
+	initializing = false;
+	scalerInitializing = false;
+	/**
+	* Monotonic counter incremented by `updateConfig` whenever the
+	* scaler + dstFrame get invalidated (e.g. output format toggle).
+	* `initScaler` captures the current value at entry and aborts — or
+	* disposes the locally-built scaler — if the epoch moved while
+	* its async init was in flight. Without this, a toggle racing an
+	* in-flight init could leave two scalers allocated natively while
+	* `this.scaler` only holds a reference to one → libav leak.
+	*/
+	scalerEpoch = 0;
+	/**
+	* One-shot guard for the "first frame" diagnostic log + raw frame
+	* dump. Setting this synchronously inside `emitDecodedFrame`
+	* prevents re-entry — without it we were using `outputFrames === 0`
+	* which stays true until the async sharp encode callback runs, so
+	* several decoded frames could trigger the dump before the first
+	* JPEG landed.
+	*/
+	firstFrameLogged = false;
+	outWidth = 0;
+	outHeight = 0;
+	/**
+	* The SOURCE geometry the current `scaler` was built for. `sws_scale` trusts
+	* these dimensions blindly; if a later decoded frame arrives with different
+	* width/height/format we MUST rebuild the scaler rather than feed it mismatched
+	* planes (an out-of-bounds read/write → uncatchable SIGBUS). `-1` means "no
+	* scaler built yet" (mirrors `this.scaler === null`).
+	*/
+	scalerSrcW = -1;
+	scalerSrcH = -1;
+	scalerSrcFmt = -1;
+	lastEmitTime = 0;
+	minIntervalMs;
+	inputPackets = 0;
+	outputFrames = 0;
+	droppedFrames = 0;
+	totalDecodeTimeMs = 0;
+	startTime = Date.now();
+	hwaccelPref;
+	hwaccelResolver;
+	/** Cluster node id stamped into every `FrameHandle` the `'shm'` sink emits. */
+	nodeId;
+	/** The backend that actually initialised successfully — `'none'` = software fallback. */
+	activeHwAccel = "none";
+	hwDevice = null;
+	swTransferFrame = null;
+	constructor(config, logger = noopLogger, options) {
+		this.config = { ...config };
+		const sessionTags = {};
+		if (typeof config.deviceId === "number") sessionTags["deviceId"] = config.deviceId;
+		if (typeof config.tag === "string" && config.tag.length > 0) sessionTags["tag"] = config.tag;
+		this.logger = Object.keys(sessionTags).length > 0 ? logger.withTags(sessionTags) : logger;
+		this.minIntervalMs = config.maxFps > 0 ? 1e3 / config.maxFps : 0;
+		this.outputMode = NodeAvDecoderSession.resolveOutputMode(config.outputFormat);
+		this.hwaccelPref = options?.hwaccel ?? "auto";
+		this.hwaccelResolver = options?.hwaccelResolver ?? null;
+		this.frameSink = options?.frameSink ?? "callback";
+		this.nodeId = options?.nodeId ?? "local";
+	}
+	/**
+	* The shared-memory ring sink for this stream, or `null` before the first
+	* `'shm'`-mode frame lazily creates it. Exposed so the owning addon can
+	* surface ring stats via `decoder.getShmStats`.
+	*/
+	get frameRingSinkOrNull() {
+		return this.frameRingSink;
+	}
+	/**
+	* Lazily build the shared-memory ring sink for this stream. The segment
+	* itself is still created lazily by the sink on its first `writeFrame`,
+	* once the decoded geometry is known.
+	*/
+	ensureFrameRingSink() {
+		if (this.frameRingSink === null) {
+			const seedParts = [];
+			if (typeof this.config.deviceId === "number") seedParts.push(String(this.config.deviceId));
+			if (typeof this.config.tag === "string" && this.config.tag.length > 0) seedParts.push(this.config.tag);
+			const seed = seedParts.length > 0 ? seedParts.join(":") : "anon";
+			this.frameRingSink = new DecoderFrameRingSink({
+				seed,
+				logger: this.logger,
+				nodeId: this.nodeId
+			});
+		}
+		return this.frameRingSink;
+	}
+	/**
+	* Resolve the backend preference list and try each one against
+	* node-av's HW context APIs. The first backend whose
+	* `HardwareDeviceContext.create()` succeeds gets attached to
+	* `codecCtx.hwDeviceCtx` + its hw pixel format registered via
+	* `setHardwarePixelFormat`. On any failure, falls through to the
+	* next backend; if all fail, returns with `activeHwAccel='none'`
+	* and the decoder runs in software on the same context.
+	*/
+	async tryAttachHwAccel(nav, C) {
+		if (!this.codecCtx) return;
+		if (this.hwaccelPref === "none") {
+			this.activeHwAccel = "none";
+			return;
+		}
+		const explicit = this.hwaccelPref === "auto" ? null : this.hwaccelPref;
+		const resolution = this.hwaccelResolver ? await this.hwaccelResolver.resolve(explicit) : explicit ? {
+			preferred: [explicit],
+			rationale: "explicit (no resolver)"
+		} : {
+			preferred: [],
+			rationale: "auto + no resolver → software"
+		};
+		if (resolution.preferred.length === 0) {
+			this.activeHwAccel = "none";
+			return;
+		}
+		for (const backend of resolution.preferred) {
+			const deviceType = backendToHwDeviceConst(backend, C);
+			const hwPixFmt = backendToHwPixFmt(backend, C);
+			if (!deviceType || !hwPixFmt) continue;
+			const device = new nav.HardwareDeviceContext();
+			const rc = device.create(deviceType);
+			if (rc < 0) {
+				this.logger.warn("node-av: hwaccel device create failed — trying next", { meta: {
+					backend,
+					rc
+				} });
+				device.free();
+				continue;
+			}
+			try {
+				this.codecCtx.hwDeviceCtx = device;
+				this.codecCtx.setHardwarePixelFormat(hwPixFmt);
+			} catch (err) {
+				this.logger.warn("node-av: hwaccel context attach failed — trying next", { meta: {
+					backend,
+					error: errMsg(err)
+				} });
+				device.free();
+				continue;
+			}
+			this.hwDevice = device;
+			this.activeHwAccel = backend;
+			return;
+		}
+		this.logger.warn("node-av: no hwaccel backend initialised — using software", { meta: {
+			attempted: resolution.preferred.join(","),
+			rationale: resolution.rationale
+		} });
+		this.activeHwAccel = "none";
+	}
+	/**
+	* Download a HW frame (format == hw pix fmt) into a SW frame so the
+	* rest of the pipeline (scaler, JPEG encoder, grayscale passthrough)
+	* handles it identically to the pure-software path. Uses the sync
+	* variant so the synchronous receive loop below doesn't need to be
+	* async-ified. Returns `null` on transfer failure, meaning the
+	* caller should drop the frame.
+	*/
+	transferHwFrame(hwFrame) {
+		if (this.activeHwAccel === "none" || !this.swTransferFrame) return hwFrame;
+		const rc = hwFrame.hwframeTransferDataSync(this.swTransferFrame, 0);
+		if (rc < 0) {
+			this.logger.warn("node-av: hwframeTransferData failed", { meta: { rc } });
+			return null;
+		}
+		return this.swTransferFrame;
+	}
+	/**
+	* Initialize the decoder pipeline on the first keyframe.
+	* After this returns, all hot-path methods are fully synchronous (except JPEG encode).
+	*/
+	async initDecoder() {
+		if (this.initialized || this.initializing || this.destroyed) return;
+		this.initializing = true;
+		try {
+			const nav = await getNodeAv();
+			const C = await getConstants();
+			this.EAGAIN = C.AVERROR_EAGAIN;
+			this.PIX_FMT_GRAY8 = C.AV_PIX_FMT_GRAY8;
+			this.PIX_FMT_RGB24 = C.AV_PIX_FMT_RGB24;
+			this.SWS_FAST_BILINEAR = C.SWS_FAST_BILINEAR;
+			if (this.outputMode === "jpeg") this.sharpFn = await getSharp();
+			nav.Log.setLevel(C.AV_LOG_FATAL);
+			const codecId = this.config.codec === "h265" || this.config.codec === "hevc" ? C.AV_CODEC_ID_HEVC : C.AV_CODEC_ID_H264;
+			this.parser = new nav.CodecParser();
+			this.parser.init(codecId);
+			const codec = nav.Codec.findDecoder(codecId);
+			if (!codec) {
+				this.logger.error("node-av: no decoder found", { meta: { codec: this.config.codec } });
+				return;
+			}
+			this.codecCtx = new nav.CodecContext();
+			this.codecCtx.allocContext3(codec);
+			if (this.config.width && this.config.height) {
+				this.codecCtx.width = this.config.width;
+				this.codecCtx.height = this.config.height;
+			}
+			this.codecCtx.threadCount = 1;
+			await this.tryAttachHwAccel(nav, C);
+			const ret = await this.codecCtx.open2(codec);
+			if (ret < 0) if (this.activeHwAccel !== "none") {
+				this.logger.warn("node-av: open2 failed with hwaccel — retrying in software", { meta: {
+					ret,
+					hwAccel: this.activeHwAccel
+				} });
+				this.hwDevice?.free();
+				this.hwDevice = null;
+				this.activeHwAccel = "none";
+				this.codecCtx = new nav.CodecContext();
+				this.codecCtx.allocContext3(codec);
+				if (this.config.width && this.config.height) {
+					this.codecCtx.width = this.config.width;
+					this.codecCtx.height = this.config.height;
+				}
+				this.codecCtx.threadCount = 1;
+				const retry = await this.codecCtx.open2(codec);
+				if (retry < 0) {
+					this.logger.error("node-av: failed to open decoder (sw fallback)", { meta: { ret: retry } });
+					return;
+				}
+			} else {
+				this.logger.error("node-av: failed to open decoder", { meta: { ret } });
+				return;
+			}
+			if (this.activeHwAccel !== "none") {
+				this.swTransferFrame = new nav.Frame();
+				this.swTransferFrame.alloc();
+			}
+			this.avPacket = new nav.Packet();
+			this.avPacket.alloc();
+			this.avFrame = new nav.Frame();
+			this.avFrame.alloc();
+			this.initialized = true;
+			this.logger.info("node-av push decoder initialized", { meta: {
+				codec: this.config.codec,
+				output: this.outputMode,
+				hwAccel: this.activeHwAccel
+			} });
+		} catch (err) {
+			this.logger.error("node-av init error", { meta: { error: errMsg(err) } });
+		} finally {
+			this.initializing = false;
+		}
+	}
+	/**
+	* Initialize the scaler after the first frame tells us the actual
+	* dimensions. Output pixel format: RGB24 for JPEG encoding, GRAY8
+	* for raw motion.
+	*
+	* Builds `scaler` + `dstFrame` on local variables and publishes
+	* them onto `this` in a single atomic step at the end. Captures
+	* `scalerEpoch` at entry; if `updateConfig` invalidated the scaler
+	* while this init was in flight (epoch mismatch), the locally
+	* built pair is disposed and discarded so the later init wins.
+	* Without the local-first approach, partial state (scaler set,
+	* dstFrame still null) could be observed by a concurrent
+	* `emitDecodedFrame` call.
+	*/
+	async initScaler(srcW, srcH, srcFmt) {
+		if (this.scalerInitializing) return;
+		this.scalerInitializing = true;
+		const myEpoch = this.scalerEpoch;
+		let localScaler = null;
+		let localDstFrame = null;
+		try {
+			const nav = await getNodeAv();
+			if (this.destroyed || myEpoch !== this.scalerEpoch) return;
+			const scale = this.config.scale > 1 ? this.config.scale : 1;
+			const maxW = Math.floor(640 / scale);
+			const outWidth = Math.min(srcW, maxW);
+			const outHeight = Math.round(outWidth * srcH / srcW);
+			const dstFmt = this.outputMode === "gray" ? this.PIX_FMT_GRAY8 : this.PIX_FMT_RGB24;
+			const fmtName = this.outputMode === "gray" ? "gray8" : "rgb24";
+			localScaler = new nav.SoftwareScaleContext();
+			localScaler.getContext(srcW, srcH, srcFmt, outWidth, outHeight, dstFmt, this.SWS_FAST_BILINEAR);
+			const ret = localScaler.initContext();
+			if (ret < 0) {
+				this.logger.error("node-av: sws_init_context failed", { meta: { ret } });
+				return;
+			}
+			localDstFrame = new nav.Frame();
+			localDstFrame.alloc();
+			localDstFrame.width = outWidth;
+			localDstFrame.height = outHeight;
+			localDstFrame.format = dstFmt;
+			const allocRet = localDstFrame.allocBuffer();
+			if (allocRet < 0) {
+				this.logger.error("node-av: dst frame allocBuffer failed", { meta: { ret: allocRet } });
+				return;
+			}
+			if (this.destroyed || myEpoch !== this.scalerEpoch) return;
+			this.scaler?.[Symbol.dispose]?.();
+			this.dstFrame?.[Symbol.dispose]?.();
+			this.scaler = localScaler;
+			this.dstFrame = localDstFrame;
+			this.outWidth = outWidth;
+			this.outHeight = outHeight;
+			this.scalerSrcW = srcW;
+			this.scalerSrcH = srcH;
+			this.scalerSrcFmt = srcFmt;
+			localScaler = null;
+			localDstFrame = null;
+			this.logger.info("node-av scaler initialized", { meta: {
+				srcWidth: srcW,
+				srcHeight: srcH,
+				outWidth,
+				outHeight,
+				format: fmtName
+			} });
+		} catch (err) {
+			this.logger.error("Scaler init failed", { meta: { error: errMsg(err) } });
+		} finally {
+			localScaler?.[Symbol.dispose]?.();
+			localDstFrame?.[Symbol.dispose]?.();
+			this.scalerInitializing = false;
+		}
+	}
+	pushPacket(packet) {
+		if (this.destroyed) return;
+		this.inputPackets++;
+		if (!this.initialized && !this.initializing && packet.keyframe) {
+			this.initDecoder().then(() => {
+				if (this.initialized) this.decodeRawData(packet.data, packet.pts ?? Date.now());
+			}).catch((err) => {
+				this.logger.error("node-av init failed", { meta: { error: errMsg(err) } });
+			});
+			return;
+		}
+		if (!this.initialized) return;
+		this.decodeRawData(packet.data, packet.pts ?? Date.now());
+	}
+	decodeRawData(data, pts) {
+		if (!this.parser || !this.codecCtx || !this.avPacket || !this.avFrame) return;
+		const buf = Buffer.isBuffer(data) ? data : Buffer.from(data);
+		const bigPts = BigInt(pts);
+		let offset = 0;
+		while (offset < buf.length) {
+			const remaining = buf.subarray(offset);
+			const consumed = this.parser.parse2(this.codecCtx, this.avPacket, remaining, bigPts, bigPts, offset);
+			if (consumed < 0) {
+				this.logger.warn("node-av parser error", { meta: { ret: consumed } });
+				break;
+			}
+			offset += consumed;
+			if (this.avPacket.size > 0) {
+				this.decodePacket();
+				this.avPacket.unref();
+			}
+		}
+	}
+	decodePacket() {
+		if (!this.codecCtx || !this.avFrame) return;
+		const sendRet = this.codecCtx.sendPacketSync(this.avPacket);
+		if (sendRet < 0 && sendRet !== this.EAGAIN) {
+			this.logger.warn("node-av sendPacket error", { meta: { ret: sendRet } });
+			return;
+		}
+		while (true) {
+			if (this.codecCtx.receiveFrameSync(this.avFrame) < 0) break;
+			const frame = this.transferHwFrame(this.avFrame);
+			if (!frame) continue;
+			this.emitDecodedFrame(frame);
+		}
+	}
+	emitDecodedFrame(frame) {
+		const now = performance.now();
+		if (this.minIntervalMs > 0 && now - this.lastEmitTime < this.minIntervalMs) {
+			this.droppedFrames++;
+			return;
+		}
+		if (this.scalerInitializing) return;
+		const incoming = {
+			width: frame.width,
+			height: frame.height,
+			format: frame.format
+		};
+		const current = this.scaler !== null ? {
+			width: this.scalerSrcW,
+			height: this.scalerSrcH,
+			format: this.scalerSrcFmt
+		} : null;
+		const action = resolveScalerAction(current, incoming);
+		if (action === "init") {
+			this.initScaler(incoming.width, incoming.height, incoming.format);
+			return;
+		}
+		if (action === "rebuild") {
+			this.logger.info("node-av: decoded source geometry changed — rebuilding scaler", { meta: {
+				from: current,
+				to: incoming
+			} });
+			this.scalerEpoch++;
+			this.scaler?.[Symbol.dispose]?.();
+			this.scaler = null;
+			this.dstFrame?.[Symbol.dispose]?.();
+			this.dstFrame = null;
+			this.scalerSrcW = -1;
+			this.scalerSrcH = -1;
+			this.scalerSrcFmt = -1;
+			this.initScaler(incoming.width, incoming.height, incoming.format);
+			return;
+		}
+		if (!this.dstFrame || !this.scaler) return;
+		const decodeStart = performance.now();
+		if (this.frameSink === "shm" && this.outputMode !== "jpeg") {
+			this.scaleIntoRingSlot(frame, decodeStart);
+			return;
+		}
+		try {
+			this.dstFrame.makeWritable();
+			this.scaler.scaleFrameSync(this.dstFrame, frame);
+		} catch (err) {
+			this.logger.warn("node-av scale error", { meta: { error: errMsg(err) } });
+			return;
+		}
+		if (!this.firstFrameLogged) {
+			this.firstFrameLogged = true;
+			const channels = this.outputMode === "gray" ? 1 : 3;
+			const ls = this.dstFrame.linesize;
+			const buf = this.dstFrame.toBuffer();
+			this.logger.info("dstFrame after scale", { meta: {
+				phase: "frame-debug",
+				width: this.dstFrame.width,
+				height: this.dstFrame.height,
+				linesize: [
+					ls[0],
+					ls[1],
+					ls[2]
+				],
+				expectedStride: this.dstFrame.width * channels,
+				bufLen: buf.length,
+				expectedPacked: this.dstFrame.width * channels * this.dstFrame.height,
+				srcFormat: frame.format ?? "?"
+			} });
+			if (this.outputMode !== "gray") import("node:fs").then((fsModule) => {
+				import("node:path").then((pathModule) => {
+					const dumpPath = pathModule.join(process.cwd(), "camstack-data", "debug-frame-rgb24.raw");
+					fsModule.writeFileSync(dumpPath, buf);
+					this.logger.info("Dumped first RGB24 frame", { meta: {
+						phase: "frame-debug",
+						path: dumpPath,
+						bytes: buf.length
+					} });
+				}).catch(() => {});
+			}).catch(() => {});
+		}
+		const rawBuf = this.extractPackedBuffer(this.dstFrame);
+		if (this.outputMode === "jpeg") this.encodeAndEmitJpeg(rawBuf, decodeStart);
+		else if (this.outputMode === "rgb") this.emitRawFrame(rawBuf, "rgb", decodeStart);
+		else this.emitRawFrame(rawBuf, "gray", decodeStart);
+	}
+	/**
+	* Scale a decoded frame **directly into a shared-memory ring slot** — the
+	* zero write-side copy path (Phase 5 / D9 Task 7c).
+	*
+	* `beginFrame` reserves the slot (its seqlock open / odd — readers skip it);
+	* `SoftwareScaleContext.scaleSync` (the low-level `sws_scale` mapping) writes
+	* the packed pixels straight into the slot buffer with `linesize = width ×
+	* bpp` — no linesize padding, so there is nothing to strip and nothing to
+	* memcpy; `commitFrame` writes the metadata, closes the seqlock and publishes
+	* the slot. The decoded source planes feed `scaleSync` as `srcSlice` +
+	* `srcStride` (`frame.data` / `frame.linesize`).
+	*
+	* Used only for raw output formats (rgb/bgr/gray). The jpeg path keeps the
+	* `dstFrame` + sharp encode route because sharp must consume an RGB buffer
+	* before the final (variable-length) jpeg bytes exist.
+	*/
+	scaleIntoRingSlot(frame, decodeStart) {
+		if (!this.scaler) return;
+		const format = this.outputMode === "gray" ? "gray" : "rgb";
+		const channels = this.outputMode === "gray" ? 1 : 3;
+		const sink = this.ensureFrameRingSink();
+		const reserved = sink.beginFrame(this.outWidth, this.outHeight, format);
+		if (reserved === null) {
+			this.droppedFrames++;
+			return;
+		}
+		const srcPlanes = frame.data;
+		if (!srcPlanes || srcPlanes.length === 0) {
+			sink.abortFrame(reserved.slot);
+			this.droppedFrames++;
+			return;
+		}
+		const dstStride = this.outWidth * channels;
+		const needed = dstStride * this.outHeight;
+		if (reserved.buffer.length < needed) {
+			this.logger.warn("node-av: ring slot too small for scaled frame — dropping", { meta: {
+				needed,
+				slotBytes: reserved.buffer.length,
+				width: this.outWidth,
+				height: this.outHeight
+			} });
+			sink.abortFrame(reserved.slot);
+			this.droppedFrames++;
+			return;
+		}
+		try {
+			const srcStrides = Array.from(frame.linesize).slice(0, srcPlanes.length);
+			this.scaler.scaleSync(Array.from(srcPlanes), srcStrides, 0, frame.height, [reserved.buffer], [dstStride]);
+		} catch (err) {
+			this.logger.warn("node-av scale-into-slot error", { meta: { error: errMsg(err) } });
+			sink.abortFrame(reserved.slot);
+			this.droppedFrames++;
+			return;
+		}
+		const decodeMs = performance.now() - decodeStart;
+		this.totalDecodeTimeMs += decodeMs;
+		this.outputFrames++;
+		this.lastEmitTime = performance.now();
+		if (!this.firstFrameLogged) {
+			this.firstFrameLogged = true;
+			this.logger.info("node-av: scaled directly into shm ring slot", { meta: {
+				phase: "frame-debug",
+				width: this.outWidth,
+				height: this.outHeight,
+				dstStride,
+				format
+			} });
+		}
+		if (this.outputFrames === 1 || this.outputFrames % 500 === 0) this.logger.info("node-av frame emitted", { meta: {
+			frameNumber: this.outputFrames,
+			width: this.outWidth,
+			height: this.outHeight,
+			format,
+			decodeMs,
+			sink: "shm",
+			subs: this.handleCallbacks.size
+		} });
+		const handle = sink.commitFrame(reserved.slot, {
+			width: this.outWidth,
+			height: this.outHeight,
+			format,
+			pts: performance.now(),
+			byteLength: dstStride * this.outHeight
+		});
+		if (handle === null) {
+			this.droppedFrames++;
+			return;
+		}
+		const delivered = {
+			handle,
+			timestamp: Date.now()
+		};
+		for (const cb of this.handleCallbacks) cb(delivered);
+	}
+	/**
+	* Extract packed pixel buffer from a decoded frame.
+	* FFmpeg's av_frame_get_buffer() may pad each row to alignment (32/64 bytes).
+	* Sharp and WASM consumers expect tightly-packed rows (stride = width * channels).
+	* If linesize matches expected stride, return the buffer directly (zero-copy).
+	*/
+	extractPackedBuffer(frame) {
+		const channels = this.outputMode === "gray" ? 1 : 3;
+		const expectedStride = frame.width * channels;
+		const actualStride = frame.linesize[0] ?? expectedStride;
+		const src = frame.data?.[0];
+		if (!src) return frame.toBuffer();
+		if (actualStride === expectedStride) return Buffer.from(src.buffer, src.byteOffset, expectedStride * frame.height);
+		const dst = Buffer.allocUnsafe(expectedStride * frame.height);
+		for (let y = 0; y < frame.height; y++) src.copy(dst, y * expectedStride, y * actualStride, y * actualStride + expectedStride);
+		return dst;
+	}
+	/**
+	* Encode RGB24 raw buffer as JPEG and emit.
+	*
+	* Drops the frame (and counts it) when `MAX_JPEG_INFLIGHT` encodes
+	* are already pending — prevents unbounded growth of the
+	* fire-and-forget promise chain when sharp cannot keep up with the
+	* decode rate.
+	*/
+	encodeAndEmitJpeg(rgb, decodeStart) {
+		if (!this.sharpFn) return;
+		if (this.jpegEncodeInFlight >= NodeAvDecoderSession.MAX_JPEG_INFLIGHT) {
+			this.droppedFrames++;
+			return;
+		}
+		this.jpegEncodeInFlight++;
+		this.sharpFn(rgb, { raw: {
+			width: this.outWidth,
+			height: this.outHeight,
+			channels: 3
+		} }).jpeg({
+			quality: 80,
+			mozjpeg: false
+		}).toBuffer().then((jpegBuf) => {
+			if (this.destroyed) return;
+			this.emitRawFrame(jpegBuf, "jpeg", decodeStart);
+		}).catch((err) => {
+			this.logger.warn("sharp jpeg encode error", { meta: { error: errMsg(err) } });
+		}).finally(() => {
+			this.jpegEncodeInFlight--;
+		});
+	}
+	emitRawFrame(data, format, decodeStart) {
+		const decodeMs = performance.now() - decodeStart;
+		this.totalDecodeTimeMs += decodeMs;
+		this.outputFrames++;
+		this.lastEmitTime = performance.now();
+		if (this.outputFrames === 1 || this.outputFrames % 500 === 0) this.logger.info("node-av frame emitted", { meta: {
+			frameNumber: this.outputFrames,
+			width: this.outWidth,
+			height: this.outHeight,
+			format,
+			decodeMs,
+			sink: this.frameSink,
+			subs: this.frameSink === "shm" ? this.handleCallbacks.size : this.frameCallbacks.size
+		} });
+		if (this.frameSink === "shm") {
+			this.emitShmFrame(data, format);
+			return;
+		}
+		const decodedFrame = {
+			data,
+			width: this.outWidth,
+			height: this.outHeight,
+			format,
+			timestamp: Date.now()
+		};
+		for (const cb of this.frameCallbacks) cb(decodedFrame);
+	}
+	/**
+	* Write a decoded frame into this stream's shared-memory ring and deliver
+	* the resulting `FrameHandle` to `onFrameHandle` subscribers. No pixel
+	* `Buffer` is handed to callbacks — consumers open the segment and read the
+	* pixels zero-copy via a `FrameRingReader`.
+	*/
+	emitShmFrame(data, format) {
+		const handle = this.ensureFrameRingSink().writeFrame(data, {
+			width: this.outWidth,
+			height: this.outHeight,
+			format,
+			pts: performance.now(),
+			byteLength: data.byteLength
+		});
+		if (handle === null) {
+			this.droppedFrames++;
+			return;
+		}
+		const frame = {
+			handle,
+			timestamp: Date.now()
+		};
+		for (const cb of this.handleCallbacks) cb(frame);
+	}
+	onFrame(callback) {
+		this.frameCallbacks.add(callback);
+		return () => {
+			this.frameCallbacks.delete(callback);
+		};
+	}
+	/**
+	* Subscribe to shared-memory frame handles. Fires only when the session was
+	* created with `frameSink: 'shm'`; in the legacy `'callback'` mode no
+	* handles are produced and this subscription never fires.
+	*/
+	onFrameHandle(callback) {
+		this.handleCallbacks.add(callback);
+		return () => {
+			this.handleCallbacks.delete(callback);
+		};
+	}
+	updateConfig(update) {
+		const prevFormat = this.config.outputFormat;
+		this.config = {
+			...this.config,
+			...update
+		};
+		if (update.maxFps !== void 0) this.minIntervalMs = update.maxFps > 0 ? 1e3 / update.maxFps : 0;
+		if (update.outputFormat !== void 0 && update.outputFormat !== prevFormat) {
+			const prevMode = this.outputMode;
+			this.outputMode = NodeAvDecoderSession.resolveOutputMode(update.outputFormat);
+			if (this.outputMode === prevMode) return;
+			this.scalerEpoch++;
+			if (this.scaler) {
+				this.scaler[Symbol.dispose]?.();
+				this.scaler = null;
+			}
+			if (this.dstFrame) {
+				this.dstFrame[Symbol.dispose]?.();
+				this.dstFrame = null;
+			}
+			this.scalerSrcW = -1;
+			this.scalerSrcH = -1;
+			this.scalerSrcFmt = -1;
+			if (this.outputMode === "jpeg" && !this.sharpFn) getSharp().then((fn) => {
+				this.sharpFn = fn;
+			}).catch(() => {});
+			this.logger.info("node-av: output format changed — scaler will reinit", { meta: {
+				from: prevFormat,
+				to: update.outputFormat,
+				mode: this.outputMode
+			} });
+		}
+	}
+	async destroy() {
+		if (this.destroyed) return;
+		this.destroyed = true;
+		this.frameCallbacks.clear();
+		this.handleCallbacks.clear();
+		this.frameRingSink?.destroy();
+		this.frameRingSink = null;
+		this.dstFrame?.[Symbol.dispose]?.();
+		this.avFrame?.[Symbol.dispose]?.();
+		this.avPacket?.[Symbol.dispose]?.();
+		this.scaler?.[Symbol.dispose]?.();
+		this.parser?.[Symbol.dispose]?.();
+		this.swTransferFrame?.[Symbol.dispose]?.();
+		this.codecCtx?.[Symbol.dispose]?.();
+		this.hwDevice?.free();
+		this.dstFrame = null;
+		this.avFrame = null;
+		this.avPacket = null;
+		this.scaler = null;
+		this.parser = null;
+		this.codecCtx = null;
+		this.swTransferFrame = null;
+		this.hwDevice = null;
+	}
+	getStats() {
+		const uptimeSec = Math.max((Date.now() - this.startTime) / 1e3, 1);
+		return {
+			inputFps: this.inputPackets / uptimeSec,
+			outputFps: this.outputFrames / uptimeSec,
+			avgDecodeTimeMs: this.outputFrames > 0 ? this.totalDecodeTimeMs / this.outputFrames : 0,
+			droppedFrames: this.droppedFrames
+		};
+	}
+	get isPullMode() {
+		return false;
+	}
+};
+//#endregion
+//#region src/decoder-nodeav/addon/index.ts
+var FRAME_BUFFER_CAPACITY = 32;
+var DecoderNodeAvAddon = class extends BaseAddon {
+	/**
+	* Sessions are stored as the concrete `NodeAvDecoderSession` (the only type
+	* this addon ever creates) so `getShmStats` can reach the per-session shm
+	* ring sink — `IDecoderSession` does not expose it.
+	*/
+	sessions = /* @__PURE__ */ new Map();
+	/** Pixel-frame buffers — populated only for `frameSink: 'callback'` sessions. */
+	frameBuffers = /* @__PURE__ */ new Map();
+	/** `FrameHandle` buffers — populated only for `frameSink: 'shm'` sessions. */
+	handleBuffers = /* @__PURE__ */ new Map();
+	unsubscribers = /* @__PURE__ */ new Map();
+	sessionMeta = /* @__PURE__ */ new Map();
+	/**
+	* Per-shm-segment `FrameRingReader` cache backing `getFrame`. Opens each
+	* named segment once and reuses the reader for every later handle on it;
+	* built in `onInitialize` (it needs the scoped logger) and closed in
+	* `onShutdown`.
+	*/
+	frameReaders = null;
+	/** Running `getFrame` hit/miss counters surfaced via `getShmStats`. */
+	getFrameHits = 0;
+	getFrameMisses = 0;
+	constructor() {
+		super(DEFAULT_DECODER_HWACCEL_CONFIG);
+	}
+	globalSettingsSchema() {
+		return this.schema({ sections: [{
+			id: "hwaccel",
+			title: "Hardware acceleration",
+			tab: "decoder",
+			description: "Backend used by node-av decoder sessions. \"Auto\" defers to the probed best; concrete backends force it. Changes apply to NEW sessions — existing sessions keep the backend they were created with.",
+			fields: [this.field({
+				type: "select",
+				key: "hwaccel",
+				label: "Preferred backend",
+				options: [...HWACCEL_OPTIONS],
+				default: "auto",
+				immediate: true
+			}), this.field({
+				type: "text",
+				key: "probedBestHwaccel",
+				label: "Probed best",
+				description: "Auto-detected best decoder backend on this host. Click the refresh icon to re-run the probe.",
+				readonlyField: true,
+				default: "",
+				perNode: true,
+				actions: [{
+					action: "reprobe-hwaccel",
+					icon: "refresh-cw",
+					tooltip: "Re-probe hwaccel"
+				}]
+			})]
+		}] });
+	}
+	async onInitialize() {
+		const backend = await resolveDecoderBackend(this.ctx.api, this.resolveLocalNodeId(), this.ctx.logger);
+		if (backend !== "nodeav") {
+			this.ctx.logger.info("node-av decoder: this node selects a different decoder backend — standing down (no decoder provider registered)", { meta: { selectedBackend: backend } });
+			return [];
+		}
+		this.ctx.logger.info("node-av decoder addon initialized", { meta: { selectedBackend: backend } });
+		this.frameReaders = new FrameRingReaderCache(this.ctx.logger);
+		if (!this.config.probedBestHwaccel) this.reprobeHwaccel().catch((err) => {
+			this.ctx.logger.warn("nodeav: auto-reprobe hwaccel failed", { meta: { error: err instanceof Error ? err.message : String(err) } });
+		});
+		return [{
+			capability: decoderCapability,
+			provider: this
+		}];
+	}
+	/**
+	* Resolve the effective hwaccel backend for a new session. Reads
+	* this addon's own `hwaccel` setting first. `'auto'` defers to the
+	* session's local resolver (`ctx.kernel.hwaccel`) which probes the
+	* host and picks. No more orchestrator round-trip — decoder addon
+	* is self-sufficient for this setting as of phase 2d.
+	*/
+	resolveHwAccelPref() {
+		return this.config.hwaccel;
+	}
+	/**
+	* Re-run the platform probe on this host and persist the detected
+	* backend as `probedBestHwaccel`. The operator's `hwaccel` setting
+	* is intentionally left alone — the probe only updates the hint.
+	*/
+	async reprobeHwaccel() {
+		const resolver = this.ctx.kernel.hwaccel;
+		if (!resolver) {
+			this.ctx.logger.warn("reprobeHwaccel: no kernel hwaccel resolver — returning none");
+			await this.updateGlobalSettings({ probedBestHwaccel: "none" });
+			return { backend: "none" };
+		}
+		try {
+			const res = await resolver.resolve();
+			const backend = res.preferred[0] ?? "none";
+			await this.updateGlobalSettings({ probedBestHwaccel: backend });
+			this.ctx.logger.info("reprobeHwaccel: wrote probedBestHwaccel", { meta: {
+				backend,
+				rationale: res.rationale,
+				preferred: res.preferred
+			} });
+			return { backend };
+		} catch (err) {
+			this.ctx.logger.warn("reprobeHwaccel failed", { meta: { error: err instanceof Error ? err.message : String(err) } });
+			await this.updateGlobalSettings({ probedBestHwaccel: "none" });
+			return { backend: "none" };
+		}
+	}
+	async supportsCodec(input) {
+		return [
+			"h264",
+			"h265",
+			"hevc"
+		].includes(input.codec.toLowerCase());
+	}
+	async getInfo() {
+		return {
+			id: "decoder-nodeav",
+			name: "Decoder (node-av)",
+			isPullMode: false,
+			priority: 10
+		};
+	}
+	/**
+	* The cluster node id of this decoder — the Moleculer nodeID (`hub`,
+	* `dev-agent-0`, …), not the addon id. Stamped into session-owned
+	* `FrameHandle`s so a downstream consumer routes `getFrame` to the node
+	* that holds the shm ring. A hierarchical broker nodeID (`hub/...`) is
+	* collapsed to the cluster-visible parent; in-process boot is left as-is.
+	* Mirrors the resolution `PipelineRunnerAddon.onInitialize` performs.
+	*/
+	resolveLocalNodeId() {
+		const raw = this.ctx.kernel.localNodeId ?? this.ctx.id;
+		return raw.includes("/") ? raw.split("/")[0] : raw;
+	}
+	async createSession(config) {
+		const sessionId = randomUUID();
+		const hwaccel = this.resolveHwAccelPref();
+		const { frameSink } = config;
+		const nodeId = this.resolveLocalNodeId();
+		const session = new NodeAvDecoderSession(config, this.ctx.logger, {
+			hwaccel,
+			hwaccelResolver: this.ctx.kernel.hwaccel,
+			frameSink,
+			nodeId
+		});
+		const unsub = frameSink === "shm" ? this.wireShmSink(sessionId, session) : this.wireCallbackSink(sessionId, session);
+		this.sessions.set(sessionId, session);
+		this.unsubscribers.set(sessionId, unsub);
+		this.sessionMeta.set(sessionId, {
+			codec: config.codec,
+			outputFormat: config.outputFormat,
+			createdAtMs: Date.now()
+		});
+		this.ctx.logger.info("node-av: created session", { meta: {
+			sessionId,
+			codec: config.codec,
+			hwaccelPref: hwaccel,
+			frameSink,
+			nodeId
+		} });
+		return {
+			sessionId,
+			nodeId
+		};
+	}
+	/**
+	* Subscribe a `'callback'` session's pixel frames into a per-session
+	* ring buffer drained by `pullFrames`.
+	*/
+	wireCallbackSink(sessionId, session) {
+		const ringBuffer = new NotifyingRingBuffer(FRAME_BUFFER_CAPACITY);
+		this.frameBuffers.set(sessionId, ringBuffer);
+		return session.onFrame((frame) => {
+			const { format } = frame;
+			if (format !== "jpeg" && format !== "rgb" && format !== "bgr" && format !== "yuv420" && format !== "gray") return;
+			const arrayBuf = new ArrayBuffer(frame.data.byteLength);
+			new Uint8Array(arrayBuf).set(frame.data);
+			const capFrame = {
+				data: new Uint8Array(arrayBuf),
+				width: frame.width,
+				height: frame.height,
+				format,
+				timestamp: frame.timestamp
+			};
+			ringBuffer.push(capFrame);
+		});
+	}
+	/**
+	* Subscribe a `'shm'` session's `FrameHandle`s into a per-session ring
+	* buffer drained by `pullHandles`. No pixel bytes cross the cap boundary
+	* — the broker opens the named segment and reads the pixels zero-copy.
+	*/
+	wireShmSink(sessionId, session) {
+		const handleRing = new NotifyingRingBuffer(FRAME_BUFFER_CAPACITY);
+		this.handleBuffers.set(sessionId, handleRing);
+		return session.onFrameHandle((frame) => {
+			handleRing.push(frame.handle);
+		});
+	}
+	async destroySession(input) {
+		const { sessionId } = input;
+		const session = this.sessions.get(sessionId);
+		if (!session) throw new Error(`decoder-nodeav: unknown sessionId ${sessionId}`);
+		const unsub = this.unsubscribers.get(sessionId);
+		if (unsub) unsub();
+		this.frameBuffers.get(sessionId)?.cancel();
+		this.handleBuffers.get(sessionId)?.cancel();
+		await session.destroy();
+		this.sessions.delete(sessionId);
+		this.frameBuffers.delete(sessionId);
+		this.handleBuffers.delete(sessionId);
+		this.unsubscribers.delete(sessionId);
+		this.sessionMeta.delete(sessionId);
+		this.ctx.logger.info("node-av: destroyed session", { meta: { sessionId } });
+	}
+	async listActiveSessions() {
+		const out = [];
+		for (const [sessionId, meta] of this.sessionMeta) out.push({
+			sessionId,
+			codec: meta.codec,
+			outputFormat: meta.outputFormat,
+			createdAtMs: meta.createdAtMs
+		});
+		return out;
+	}
+	async pushPacket(input) {
+		const session = this.sessions.get(input.sessionId);
+		if (!session) throw new Error(`decoder-nodeav: unknown sessionId ${input.sessionId}`);
+		const rawData = input.packet.data;
+		const data = Buffer.isBuffer(rawData) ? rawData : rawData instanceof Uint8Array ? Buffer.from(rawData.buffer, rawData.byteOffset, rawData.byteLength) : Buffer.from(rawData);
+		session.pushPacket({
+			...input.packet,
+			data
+		});
+	}
+	async openStream(input) {
+		if (!this.sessions.get(input.sessionId)) throw new Error(`decoder-nodeav: unknown sessionId ${input.sessionId}`);
+		input.url;
+	}
+	async pullFrames(input) {
+		if (!this.sessions.has(input.sessionId)) throw new Error(`decoder-nodeav: unknown sessionId ${input.sessionId}`);
+		const ringBuffer = this.frameBuffers.get(input.sessionId);
+		if (!ringBuffer) return [];
+		if (ringBuffer.size === 0 && input.waitMs) await ringBuffer.waitForItem(input.waitMs);
+		return ringBuffer.drain(input.maxCount);
+	}
+	async pullHandles(input) {
+		if (!this.sessions.has(input.sessionId)) throw new Error(`decoder-nodeav: unknown sessionId ${input.sessionId}`);
+		const handleRing = this.handleBuffers.get(input.sessionId);
+		if (!handleRing) return [];
+		if (handleRing.size === 0 && input.waitMs) await handleRing.waitForItem(input.waitMs);
+		return handleRing.drain(input.maxCount);
+	}
+	async updateConfig(input) {
+		const session = this.sessions.get(input.sessionId);
+		if (!session) throw new Error(`decoder-nodeav: unknown sessionId ${input.sessionId}`);
+		session.updateConfig(input.config);
+	}
+	async getStats(input) {
+		const session = this.sessions.get(input.sessionId);
+		if (!session) throw new Error(`decoder-nodeav: unknown sessionId ${input.sessionId}`);
+		return session.getStats();
+	}
+	/**
+	* Read back the pixels a `FrameHandle` refers to from this node's shm ring
+	* (Phase 5 / D9 downstream access). Returns `null` when the slot was
+	* already recycled (latest-wins drop) or the segment could not be opened.
+	* The reader cache opens each named segment once and reuses the reader.
+	*
+	* The reader hands back a `Buffer` view over its **reusable scratch
+	* buffer**, only valid until the next `read` on the same reader; the
+	* cap caller may keep the frame across reads, so the pixels are copied
+	* into a fresh detached `ArrayBuffer` here. This matches the existing
+	* callback-path copy in `wireCallbackSink`.
+	*/
+	async getFrame(input) {
+		const frame = this.frameReaders?.read(input.handle) ?? null;
+		if (!frame) {
+			this.getFrameMisses += 1;
+			return null;
+		}
+		this.getFrameHits += 1;
+		const arrayBuf = new ArrayBuffer(frame.data.byteLength);
+		new Uint8Array(arrayBuf).set(frame.data);
+		return {
+			data: new Uint8Array(arrayBuf),
+			width: frame.width,
+			height: frame.height,
+			format: frame.format,
+			timestamp: frame.timestamp
+		};
+	}
+	/**
+	* shm ring usage stats for a `frameSink: 'shm'` session — slot geometry,
+	* frames written, byte budget, plus this addon's running `getFrame`
+	* hit/miss counters. Returns `null` for an unknown session or one whose
+	* shm ring has not yet been armed by a first decoded frame.
+	*/
+	async getShmStats(input) {
+		const stats = this.sessions.get(input.sessionId)?.frameRingSinkOrNull?.getShmStats() ?? null;
+		if (!stats) return null;
+		return {
+			sessionId: input.sessionId,
+			...stats,
+			budgetMb: RING_BUDGET_MB,
+			getFrameHits: this.getFrameHits,
+			getFrameMisses: this.getFrameMisses
+		};
+	}
+	async onShutdown() {
+		this.ctx.logger.info("node-av decoder addon shutdown — destroying all sessions");
+		const destroyPromises = [];
+		for (const [sessionId, session] of this.sessions) {
+			const unsub = this.unsubscribers.get(sessionId);
+			if (unsub) unsub();
+			destroyPromises.push(session.destroy());
+		}
+		await Promise.all(destroyPromises);
+		this.sessions.clear();
+		this.frameBuffers.clear();
+		this.handleBuffers.clear();
+		this.unsubscribers.clear();
+		this.sessionMeta.clear();
+		this.frameReaders?.close();
+		this.frameReaders = null;
+	}
+};
+//#endregion
+export { DecoderFrameRingSink, DecoderNodeAvAddon, DecoderNodeAvAddon as default, NodeAvDecoderSession, makeSegmentName };