@camstack/addon-pipeline 1.1.26 → 1.1.27

package/dist/decoder-ffmpeg/index.js

@@ -3,6 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_dist = require("../dist-DAIlCdAx.js");
+const require_frame_ring_sink = require("../frame-ring-sink-BbzrqTWj.js");
 const require_frame_dropper = require("../frame-dropper-7RTo_YyG.js");
 let _camstack_shm_ring = require("@camstack/shm-ring");
 let node_crypto = require("node:crypto");
@@ -300,270 +301,6 @@ function rankDecodeHwAccels(preferred, supportedMethods) {
 	return candidates.sort((a, b) => decodeHwAccelRankIndex(a) - decodeHwAccelRankIndex(b));
 }
 //#endregion
-//#region src/decoder-ffmpeg/frame-ring-sink.ts
-/**
-* `DecoderFrameRingSink` — the decoder's shared-memory write side (Phase 5 / D9).
-*
-* When a decoder session is configured with `frameSink: 'shm'`, the decoder
-* **owns** the shared-memory ring segment for that stream: it creates the
-* segment on the first decoded frame (when the output geometry is known),
-* writes every subsequent decoded frame into the ring via a `FrameRingWriter`,
-* and closes + unlinks the segment when the session is destroyed.
-*
-* What leaves the decoder is no longer the pixel `Buffer` — it is a tiny,
-* serialisable `FrameHandle` (`FrameRingWriter.writeFrame`'s return value).
-* Same-host consumers (motion, detection, the WebRTC encoder) open the same
-* segment with a `FrameRingReader` and read the pixels zero-copy.
-*
-* ## Lazy segment creation
-*
-* The segment cannot be sized until the first frame: `slotByteLength` is
-* `width × height × bytesPerPixel`, and the output dimensions are only known
-* once the scaler has produced its first `dstFrame`. So `writeFrame` is a
-* no-op-until-armed: the first call sizes + creates the segment, every later
-* call writes into it.
-*
-* ## Resolution-change decision
-*
-* A live camera stream can change resolution mid-stream (the decoder's scaler
-* is rebuilt on a config toggle, or the source renegotiates). The slot is
-* sized for the **first** frame's geometry. A later frame that no longer fits
-* the slot triggers a **segment re-create**: the old segment is closed +
-* unlinked and a fresh, larger segment is created under a new generation-tagged
-* name. This is simpler and leak-free versus over-allocating slots for a
-* worst-case 4K frame on every stream; resolution changes on a live camera are
-* rare, and a brief gap while consumers re-open the segment is acceptable
-* (latest-wins — a missed frame is correct behaviour).
-*/
-/**
-* Per-ring shared-memory budget (MB) — the slot count is derived per-resolution
-* from this budget via {@link deriveSlotCount}, so a 360p stream gets many
-* slots and a 4K stream a few, both inside the same memory footprint.
-*
-* Read ONCE at module load from `CAMSTACK_SHM_RING_BUDGET_MB`; a non-finite or
-* non-positive value falls back to the 16 MB default.
-*
-* The default is deliberately small (16 MB) so many concurrent per-camera rings
-* fit inside a bounded `/dev/shm`. The decoder output is capped at 640px wide, so
-* a slot is ≤ ~920 KB and 16 MB still yields ~17–70 latest-wins slots. A ring
-* segment larger than the container's `/dev/shm` tmpfs backing (Docker default is
-* only 64 MB) faults an **uncatchable SIGBUS** on write past `st_size` — the old
-* 128 MB default overflowed a 64 MB `/dev/shm` and crashed the decoder on 8MP
-* streams. Pair this with a `--shm-size` that scales with concurrent-decode load.
-*/
-var RING_BUDGET_MB = (() => {
-	const raw = Number(process.env["CAMSTACK_SHM_RING_BUDGET_MB"]);
-	return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : 16;
-})();
-/** {@link RING_BUDGET_MB} in bytes — the budget passed to `deriveSlotCount`. */
-var RING_BUDGET_BYTES = RING_BUDGET_MB * 1024 * 1024;
-/** A unique, stable shared-memory segment name for a decoder stream.
-*
-* macOS POSIX shm names are capped at ~31 characters (`PSHMNAMLEN`). A
-* `camstack.frames.<deviceId>.<streamId>` scheme overflows that for realistic
-* ids, so the sink uses a short, collision-resistant scheme instead:
-* `csf.<base36 hash>.<gen>`. The hash folds the device id, the session tag
-* and a per-process random salt; the generation suffix makes a re-created
-* segment (resolution change) a distinct name so a stale consumer mapping is
-* never silently reused.
-*/
-function makeSegmentName(seed, generation) {
-	let hash = 5381;
-	for (let i = 0; i < seed.length; i += 1) hash = (hash << 5) + hash + seed.charCodeAt(i) | 0;
-	return `csf.${(hash >>> 0).toString(36)}.${generation}`;
-}
-/**
-* The decoder-side owner of one stream's shared-memory frame ring.
-*
-* Not constructed until a session actually uses the shm sink; the segment
-* itself is created lazily on the first `writeFrame`.
-*/
-var DecoderFrameRingSink = class {
-	seed;
-	logger;
-	nodeId;
-	segment = null;
-	writer = null;
-	segmentName = null;
-	slotByteLength = 0;
-	generation = 0;
-	destroyed = false;
-	/** Frames committed into the ring across this sink's lifetime (all generations). */
-	framesWritten = 0;
-	constructor(options) {
-		const salt = Math.random().toString(36).slice(2, 8);
-		this.seed = `${options.seed}.${salt}`;
-		this.logger = options.logger;
-		this.nodeId = options.nodeId;
-	}
-	/** Whether a segment has been created (i.e. at least one frame written). */
-	get isArmed() {
-		return this.writer !== null;
-	}
-	/** The current segment name, or `null` before the first frame. */
-	get currentSegmentName() {
-		return this.segmentName;
-	}
-	/**
-	* Write one decoded frame into the ring and return its `FrameHandle`.
-	*
-	* On the first call (or after a geometry change that overflows the current
-	* slot) the segment is created / re-created sized for this frame. Returns
-	* `null` only when the sink has been destroyed.
-	*
-	* This is the copy-in convenience form (it copies `pixels` into the slot).
-	* The decoder's hot path uses the zero-copy {@link beginFrame} /
-	* {@link commitFrame} scatter-write pair instead — the scaler produces its
-	* packed output directly into the slot, eliminating the write-side memcpy.
-	*/
-	writeFrame(pixels, meta) {
-		if (this.destroyed) return null;
-		if (this.writer === null || (0, _camstack_shm_ring.computeSlotByteLength)(meta.width, meta.height, meta.format) > this.slotByteLength) this.recreateSegment((0, _camstack_shm_ring.computeSlotByteLength)(meta.width, meta.height, meta.format));
-		const writer = this.writer;
-		if (writer === null) return null;
-		const handle = writer.writeFrame(pixels, meta);
-		this.framesWritten += 1;
-		return handle;
-	}
-	/**
-	* Reserve a ring slot for a frame of the given geometry — the **zero-copy**
-	* scatter-write entry point (Phase 5 / D9 Task 7c).
-	*
-	* The segment is created / re-created here if this is the first frame or the
-	* geometry overflows the current slot capacity, so the slot is correctly
-	* sized before the caller fills it. The returned `buffer` is a writable view
-	* **directly over the mapped segment** — the node-av scaler scatters its
-	* packed output straight into it, with no intermediate copy. The caller MUST
-	* call {@link commitFrame} with the returned `slot` once the slot is filled.
-	*
-	* Returns `null` when the sink is destroyed or the segment cannot be created.
-	*/
-	beginFrame(width, height, format) {
-		if (this.destroyed) return null;
-		const requiredSlotBytes = (0, _camstack_shm_ring.computeSlotByteLength)(width, height, format);
-		if (this.writer === null || requiredSlotBytes > this.slotByteLength) this.recreateSegment(requiredSlotBytes);
-		const writer = this.writer;
-		if (writer === null) return null;
-		const { slot, buffer } = writer.beginFrame();
-		return {
-			slot,
-			buffer
-		};
-	}
-	/**
-	* Publish the frame whose slot was reserved by {@link beginFrame} and filled
-	* in place by the caller. `slot` MUST be the value from the matching
-	* `beginFrame`. Returns the published `FrameHandle`, or `null` if the sink
-	* was destroyed (or the segment lost) between begin and commit.
-	*/
-	commitFrame(slot, meta) {
-		if (this.destroyed) return null;
-		const writer = this.writer;
-		if (writer === null) return null;
-		const handle = writer.commitFrame(slot, meta);
-		this.framesWritten += 1;
-		return handle;
-	}
-	/**
-	* Current shm ring usage — `null` until the first frame arms the segment.
-	* Surfaced through `decoder.getShmStats` so a downstream consumer can
-	* observe ring pressure (slot depth, byte budget, frames written).
-	*/
-	getShmStats() {
-		if (this.writer === null) return null;
-		return {
-			slotCount: this.writer.slotCount,
-			slotByteLength: this.slotByteLength,
-			segmentBytes: (0, _camstack_shm_ring.computeSegmentSize)(this.writer.slotCount, this.slotByteLength),
-			framesWritten: this.framesWritten
-		};
-	}
-	/**
-	* Abandon a slot reserved by {@link beginFrame} **without publishing it** —
-	* the degenerate-path counterpart of {@link commitFrame}.
-	*
-	* A caller that reserved a slot but then could not produce valid pixels (no
-	* decoded source planes, or the scaler threw) MUST call this instead of
-	* `commitFrame`: it closes the open seqlock without advancing `writeIndex`,
-	* so no reader ever sees the slot's uninitialised bytes as a real frame, and
-	* no `FrameHandle` is handed downstream. `slot` MUST be the value from the
-	* matching `beginFrame`. A no-op if the sink was destroyed (or the segment
-	* lost) between begin and abort.
-	*/
-	abortFrame(slot) {
-		if (this.destroyed) return;
-		const writer = this.writer;
-		if (writer === null) return;
-		writer.abortFrame(slot);
-	}
-	/** Close + unlink the segment. Idempotent. */
-	destroy() {
-		if (this.destroyed) return;
-		this.destroyed = true;
-		this.releaseSegment();
-	}
-	/**
-	* Create a fresh segment sized for at least `slotByteLength` bytes per slot,
-	* replacing any prior one. A re-create bumps the generation so the new
-	* segment has a distinct name — a consumer holding the old mapping is never
-	* silently handed a resized segment.
-	*/
-	recreateSegment(slotByteLength) {
-		this.releaseSegment();
-		this.generation += 1;
-		const name = makeSegmentName(this.seed, this.generation);
-		const slotCount = (0, _camstack_shm_ring.deriveSlotCount)(RING_BUDGET_BYTES, slotByteLength);
-		if (slotCount === _camstack_shm_ring.MIN_RING_SLOTS && _camstack_shm_ring.MIN_RING_SLOTS * slotByteLength > RING_BUDGET_BYTES) this.logger.warn("decoder shm ring: budget too small for resolution — using MIN slots", { meta: {
-			slotByteLength,
-			budgetMb: RING_BUDGET_MB
-		} });
-		const totalBytes = (0, _camstack_shm_ring.computeSegmentSize)(slotCount, slotByteLength);
-		try {
-			const segment = (0, _camstack_shm_ring.createSegment)(name, totalBytes);
-			this.segment = segment;
-			this.segmentName = name;
-			this.slotByteLength = slotByteLength;
-			this.writer = new _camstack_shm_ring.FrameRingWriter(segment.buffer, name, slotCount, slotByteLength, this.nodeId);
-			this.logger.info("decoder shm ring: segment created", { meta: {
-				segment: name,
-				slotCount,
-				slotByteLength,
-				totalBytes,
-				generation: this.generation
-			} });
-		} catch (err) {
-			this.segment = null;
-			this.writer = null;
-			this.segmentName = null;
-			this.slotByteLength = 0;
-			this.logger.error("decoder shm ring: segment create failed", { meta: {
-				segment: name,
-				slotByteLength,
-				error: err instanceof Error ? err.message : String(err)
-			} });
-		}
-	}
-	/** Unmap + unlink the current segment, if any. */
-	releaseSegment() {
-		const segment = this.segment;
-		if (segment === null) return;
-		this.segment = null;
-		this.writer = null;
-		const name = this.segmentName;
-		this.segmentName = null;
-		try {
-			segment.close();
-			segment.unlink();
-			this.logger.info("decoder shm ring: segment released", { meta: { segment: name } });
-		} catch (err) {
-			this.logger.warn("decoder shm ring: segment release failed", { meta: {
-				segment: name,
-				error: err instanceof Error ? err.message : String(err)
-			} });
-		}
-	}
-};
-//#endregion
 //#region src/decoder-ffmpeg/frame-stream-splitter.ts
 var FrameStreamSplitter = class {
 	frameSize;
@@ -699,6 +436,14 @@ var FfmpegDecoderSession = class {
 	process = null;
 	spawnedAtMs = 0;
 	/**
+	* Whether a spawn has ever been attempted. Drives the LAZY first spawn
+	* (first `pushPacket` / `openStream`) and preserves the recovery semantics
+	* afterwards: a push-mode child that later dies is NOT respawned by the
+	* packet feed (the consumer / frame-plane self-heal recreates the session),
+	* and `updateConfig` only restarts a session that has already spawned.
+	*/
+	spawnAttempted = false;
+	/**
 	* PULL-MODE input URL (P2b). `null` = push mode (packets via stdin — the
 	* default). Set by {@link openStream}; every (re)spawn since reads this URL
 	* directly instead of `pipe:0`. A session is push-mode or pull-mode for its
@@ -754,7 +499,6 @@ var FfmpegDecoderSession = class {
 		this.channels = channelsForPixel(this.pixel);
 		this.frameFormat = this.pixel === "gray" ? "gray" : "rgb";
 		this.frameDropper = new require_frame_dropper.FrameDropper(config.maxFps);
-		this.spawnFfmpeg();
 	}
 	/** Exposed so the owning addon can surface ring stats via `getShmStats`. */
 	get frameRingSinkOrNull() {
@@ -787,7 +531,7 @@ var FfmpegDecoderSession = class {
 			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({
+			this.frameRingSink = new require_frame_ring_sink.DecoderFrameRingSink({
 				seed,
 				logger: this.logger,
 				nodeId: this.nodeId
@@ -797,6 +541,7 @@ var FfmpegDecoderSession = class {
 	}
 	spawnFfmpeg() {
 		if (this.destroyed) return;
+		this.spawnAttempted = true;
 		this.clearPullRedial();
 		this.killFfmpeg();
 		this.abortOpenSlot();
@@ -827,12 +572,19 @@ var FfmpegDecoderSession = class {
 		this.process = child;
 		this.spawnedAtMs = Date.now();
 		child.stdin?.on("error", () => {});
-		child.stdout?.on("data", (chunk) => this.handleStdout(chunk));
-		child.stderr?.on("data", (data) => this.handleStderr(data));
+		child.stdout?.on("data", (chunk) => {
+			if (child === this.process) this.handleStdout(chunk);
+		});
+		child.stderr?.on("data", (data) => {
+			if (child === this.process) this.handleStderr(data);
+		});
 		child.on("error", (err) => {
+			if (child !== this.process) return;
 			this.logger.error("ffmpeg decoder: process error", { meta: { error: err.message } });
 		});
-		child.on("exit", (code, signal) => this.handleExit(code, signal));
+		child.on("exit", (code, signal) => {
+			if (child === this.process) this.handleExit(code, signal);
+		});
 		this.logger.info("ffmpeg decoder: spawned", { meta: {
 			hwaccel: this.hwaccel,
 			gpuScale: this.activeGpuScaleFilter ?? "cpu",
@@ -845,6 +597,9 @@ var FfmpegDecoderSession = class {
 		const child = this.process;
 		if (!child) return;
 		this.process = null;
+		child.stdout?.removeAllListeners("data");
+		child.stderr?.removeAllListeners("data");
+		child.removeAllListeners("exit");
 		try {
 			child.stdin?.end();
 		} catch {}
@@ -1028,6 +783,7 @@ var FfmpegDecoderSession = class {
 	pushPacket(packet) {
 		if (this.destroyed) return;
 		if (this.pullUrl !== null) return;
+		if (this.process === null && !this.spawnAttempted) this.spawnFfmpeg();
 		const stdin = this.process?.stdin;
 		if (!stdin) return;
 		this.inputPackets++;
@@ -1055,7 +811,7 @@ var FfmpegDecoderSession = class {
 			...update
 		};
 		if (update.maxFps !== void 0) this.frameDropper.setMaxFps(update.maxFps);
-		if (needsRestart) this.spawnFfmpeg();
+		if (needsRestart && this.spawnAttempted) this.spawnFfmpeg();
 	}
 	async destroy() {
 		if (this.destroyed) return;
@@ -1201,7 +957,12 @@ var DecoderFfmpegAddon = class extends require_dist.BaseAddon {
 		}] });
 	}
 	async onInitialize() {
-		this.ctx.logger.info("ffmpeg decoder addon initialized");
+		const backend = await require_frame_ring_sink.resolveDecoderBackend(this.ctx.settings, this.resolveLocalNodeId(), this.ctx.logger);
+		if (backend !== "ffmpeg") {
+			this.ctx.logger.info("ffmpeg decoder: this node selects a different decoder backend — standing down (no decoder provider registered)", { meta: { selectedBackend: backend } });
+			return [];
+		}
+		this.ctx.logger.info("ffmpeg decoder addon initialized", { meta: { selectedBackend: backend } });
 		this.frameReaders = new _camstack_shm_ring.FrameRingReaderCache(this.ctx.logger);
 		this.ffmpegPath = await this.resolveFfmpegBinaryPath();
 		this.probedGpuScaleFilters = await probeGpuScaleFilters(this.ffmpegPath, this.ctx.logger);
@@ -1466,7 +1227,7 @@ var DecoderFfmpegAddon = class extends require_dist.BaseAddon {
 		return {
 			sessionId: input.sessionId,
 			...stats,
-			budgetMb: RING_BUDGET_MB,
+			budgetMb: require_frame_ring_sink.RING_BUDGET_MB,
 			getFrameHits: this.getFrameHits,
 			getFrameMisses: this.getFrameMisses
 		};