@camstack/addon-pipeline 1.1.34 → 1.1.35

package/dist/decoder-nodeav/index.mjs

@@ -1,1414 +0,0 @@
-import { B as errMsg, V as BaseAddon, d as HWACCEL_OPTIONS, s as DEFAULT_DECODER_HWACCEL_CONFIG, x as decoderCapability } from "../dist-CfSORkv2.mjs";
-import { a as resolveDecoderBackend, i as NotifyingRingBuffer, n as RING_BUDGET_MB, o as resolveDecoderHwAccel, r as makeSegmentName, t as DecoderFrameRingSink } from "../frame-ring-sink-1aLGcNNf.mjs";
-import { f as rankDecodeHwAccels } from "../ffmpeg-args-CpeRWwL4.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
-/**
-* Pull-mode re-dial backoff. On a pull input error/EOF the loop waits this long
-* before re-opening the URL — mirrors the ffmpeg pull decoder's 3s re-dial so a
-* transient RTSP restream blip (source suspended on idle, keyframe wait) does
-* not hot-loop `Demuxer.open`.
-*/
-var PULL_REDIAL_MS = 3e3;
-/** 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("node-av");
-	return _nav;
-}
-async function getConstants() {
-	if (!_consts) _consts = await import("node-av/constants");
-	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;
-	/** True once `openStream` has armed the pull loop; drives `isPullMode`. */
-	pullActive = false;
-	/** One-shot guard so a stray push into a pull session logs once, not per-packet. */
-	pullStrayPushLogged = false;
-	/** The URL the pull loop (re)dials — updatable while active. */
-	pullUrl = null;
-	/** Pending re-dial timer + its resolver, so `destroy` can wake it instantly. */
-	pullRedialTimer = null;
-	pullRedialResolve = null;
-	/** High-level demuxer/decoder for the CURRENT dial — recreated per re-dial. */
-	pullDemuxer = null;
-	pullDecoder = null;
-	/** HW context — resolved once, reused across re-dials, freed in `destroy`. */
-	pullHwContext = 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;
-		}
-	}
-	/**
-	* Start PULL mode: libav dials `url` and demuxes it in-process, decoding
-	* every frame through the same emit path as push mode. Idempotent while
-	* active (updates the re-dial target). Throws if the session already took a
-	* push packet — a session is push-mode or pull-mode for its whole life.
-	*/
-	openStream(url) {
-		if (this.destroyed) return Promise.resolve();
-		if (this.inputPackets > 0 || this.initialized || this.initializing) throw new Error("node-av decoder: openStream on a push-fed session — a session is push-mode or pull-mode, never both");
-		if (this.pullActive) {
-			this.pullUrl = url;
-			return Promise.resolve();
-		}
-		this.pullActive = true;
-		this.pullUrl = url;
-		this.logger.info("node-av decoder: pull-mode openStream — dialing input URL", { meta: { url } });
-		this.runPullLoop().catch((err) => {
-			this.logger.error("node-av decoder: pull loop crashed", { meta: { error: errMsg(err) } });
-		});
-		return Promise.resolve();
-	}
-	/**
-	* The pull-mode supervisor loop: resolve HW once, then repeatedly dial +
-	* decode the URL, re-dialing after {@link PULL_REDIAL_MS} on any exit/error
-	* until the session is destroyed. Each iteration rebuilds a fresh
-	* demuxer/decoder (the previous one is disposed in `closePullInput`).
-	*/
-	async runPullLoop() {
-		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;
-		nav.Log.setLevel(C.AV_LOG_FATAL);
-		if (this.outputMode === "jpeg" && !this.sharpFn) this.sharpFn = await getSharp();
-		await this.ensurePullHwContext(nav, C);
-		while (!this.destroyed && this.pullActive) {
-			const url = this.pullUrl;
-			if (!url) break;
-			try {
-				await this.pullDialAndDecode(nav, C, url);
-			} catch (err) {
-				if (this.destroyed) break;
-				this.logger.warn("node-av decoder: pull-mode dial ended — re-dial scheduled", { meta: {
-					error: errMsg(err),
-					redialInMs: PULL_REDIAL_MS
-				} });
-			} finally {
-				this.closePullInput();
-			}
-			if (this.destroyed || !this.pullActive) break;
-			await this.pullSleep(PULL_REDIAL_MS);
-		}
-	}
-	/**
-	* One dial: open the demuxer, pick the video stream, create a HW/SW decoder
-	* that downloads + normalises frames to YUV420P (so the shared scaler in
-	* `emitDecodedFrame` reads plain software planes regardless of hwaccel), and
-	* pump `demuxer.packets(video) → decoder.frames → emitDecodedFrame` until the
-	* stream ends or the session is torn down.
-	*/
-	async pullDialAndDecode(nav, C, url) {
-		const demuxer = await nav.Demuxer.open(url, { options: { rtsp_transport: "tcp" } });
-		if (this.destroyed || !this.pullActive) {
-			demuxer[Symbol.dispose]?.();
-			return;
-		}
-		this.pullDemuxer = demuxer;
-		const videoStream = demuxer.video();
-		if (!videoStream) throw new Error("node-av decoder: pull input has no video stream");
-		const decoder = await nav.Decoder.create(videoStream, {
-			...this.pullHwContext ? { hardware: this.pullHwContext } : {},
-			rescale: { pixelFormat: C.AV_PIX_FMT_YUV420P }
-		});
-		if (this.destroyed || !this.pullActive) {
-			decoder[Symbol.dispose]?.();
-			return;
-		}
-		this.pullDecoder = decoder;
-		this.logger.info("node-av pull decoder initialized", { meta: {
-			codec: this.config.codec,
-			output: this.outputMode,
-			hwAccel: this.activeHwAccel,
-			streamIndex: videoStream.index
-		} });
-		for await (const frame of decoder.frames(demuxer.packets(videoStream.index))) {
-			if (this.destroyed || !this.pullActive) break;
-			if (!frame) continue;
-			this.inputPackets++;
-			try {
-				this.emitDecodedFrame(frame);
-			} finally {
-				frame.free();
-			}
-		}
-	}
-	/**
-	* Resolve and build the HW context for pull mode ONCE. Explicit backend →
-	* single try; `'auto'` → the kernel resolver's ordered list; no resolver →
-	* software. The first `HardwareContext.create` that succeeds wins; all
-	* failures fall through to software decode (`hardware: null`).
-	*/
-	async ensurePullHwContext(nav, C) {
-		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"
-		};
-		for (const backend of resolution.preferred) {
-			const deviceType = backendToHwDeviceConst(backend, C);
-			if (!deviceType) continue;
-			const hw = nav.HardwareContext.create(deviceType);
-			if (!hw) {
-				this.logger.warn("node-av: pull hwaccel context create failed — trying next", { meta: { backend } });
-				continue;
-			}
-			this.pullHwContext = hw;
-			this.activeHwAccel = backend;
-			return;
-		}
-		this.logger.warn("node-av: no pull hwaccel backend initialised — using software", { meta: {
-			attempted: resolution.preferred.join(","),
-			rationale: resolution.rationale
-		} });
-		this.activeHwAccel = "none";
-	}
-	/** Dispose the CURRENT dial's demuxer + decoder (HW context is reused). */
-	closePullInput() {
-		if (this.pullDecoder) {
-			this.pullDecoder[Symbol.dispose]?.();
-			this.pullDecoder = null;
-		}
-		if (this.pullDemuxer) {
-			this.pullDemuxer[Symbol.dispose]?.();
-			this.pullDemuxer = null;
-		}
-	}
-	/** Interruptible sleep for the re-dial backoff — `destroy` resolves it early. */
-	pullSleep(ms) {
-		return new Promise((resolve) => {
-			this.pullRedialResolve = resolve;
-			this.pullRedialTimer = setTimeout(() => {
-				this.pullRedialTimer = null;
-				this.pullRedialResolve = null;
-				resolve();
-			}, ms);
-		});
-	}
-	pushPacket(packet) {
-		if (this.destroyed) return;
-		if (this.pullActive) {
-			if (!this.pullStrayPushLogged) {
-				this.pullStrayPushLogged = true;
-				this.logger.debug("node-av decoder: pushPacket on a pull-mode session — ignored");
-			}
-			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.pullActive = false;
-		if (this.pullRedialTimer) {
-			clearTimeout(this.pullRedialTimer);
-			this.pullRedialTimer = null;
-		}
-		if (this.pullRedialResolve) {
-			const resolve = this.pullRedialResolve;
-			this.pullRedialResolve = null;
-			resolve();
-		}
-		this.closePullInput();
-		if (this.pullHwContext) {
-			if (!this.pullHwContext.isDisposed) this.pullHwContext.dispose();
-			this.pullHwContext = null;
-		}
-		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 this.pullActive;
-	}
-};
-//#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,
-				perNode: 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 the SHARED
-	* per-node override from the `decoder-ffmpeg` OWNER — the single value the
-	* Pipeline UI edits — exactly as `resolveDecoderBackend` reads the owner's
-	* `backend`. This makes a manual hwaccel override take effect even when
-	* node-av is the active backend (its OWN `hwaccel@node` is never surfaced by
-	* the UI). `'auto'` defers to the session's local resolver
-	* (`ctx.kernel.hwaccel`). Fails safe to `'auto'`.
-	*/
-	resolveHwAccelPref() {
-		return resolveDecoderHwAccel(this.ctx.api, this.resolveLocalNodeId(), this.ctx.logger);
-	}
-	/**
-	* 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 = rankDecodeHwAccels(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: true,
-			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 = await 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) {
-		const session = this.sessions.get(input.sessionId);
-		if (!session) throw new Error(`decoder-nodeav: unknown sessionId ${input.sessionId}`);
-		await session.openStream(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 };