@camstack/addon-pipeline 1.2.222 → 1.2.224

package/dist/stream-broker/index.mjs

@@ -9405,42 +9405,14 @@ function extractQuoted(header, key) {
 	const unquotedRegex = new RegExp(`${key}=([^,\\s]+)`, "i");
 	return header.match(unquotedRegex)?.[1];
 }
-//#endregion
-//#region src/stream-broker/stream-broker/audio-chunk-plane.ts
-/**
-* `AudioChunkPlane` — the broker's serialisable decoded audio-chunk surface
-* (Phase 5 / D9).
-*
-* This is the poll-based replacement for `StreamBroker.onDecodedAudioChunk`'s
-* live-object callback path. A live callback cannot cross a process boundary;
-* once the `pipeline` group is dissolved (Task 8) the audio consumer
-* (`pipeline-orchestrator`) runs in a different process from the broker, so
-* audio delivery must go over tRPC like the video frame plane.
-*
-* ## Why no shared memory
-*
-* Unlike video frames (~6 MB at 1080p RGB), a decoded audio chunk is tiny — a
-* ~500ms `AudioCodecSession` window is a few KB of Float32 PCM. Tiny payloads
-* serialise over tRPC cheaply, so audio ships its bytes INLINE on the RPC
-* wire; there is no shm ring.
-*
-* ## FIFO / no-drop queue policy
-*
-* Audio wants FIFO arrival order with no latest-wins drop: a missing chunk is
-* an audible gap and breaks the audio analyzer's fixed-length analysis
-* window. Each subscription therefore owns a generously-sized FIFO queue
-* (`AUDIO_QUEUE_CAPACITY`). Chunks arrive roughly every
-* `AudioCodecSession`-window (~500ms), so the queue buffers tens of seconds
-* of audio — a healthy poll loop never fills it. The queue only drops its
-* OLDEST chunk if a truly stalled consumer lets it overflow (a bounded safety
-* valve, not the steady-state behaviour).
-*/
 /**
-* Per-subscription FIFO capacity. A chunk is a few KB and arrives ~every
-* 500ms, so 64 buffers ~30s of audio between two `pullAudioChunks` polls
-* without unbounded growth.
+* Re-state a standing overflow at most this often (D465). The line fires when a
+* subscription STARTS overwriting, and again every 30 s while it still is — a
+* per-chunk warn is ~25 writes/s per camera of synchronous winston on the
+* broker's event loop, which is the cost the `pullPcm` warn coalescing exists
+* to avoid.
 */
-var AUDIO_QUEUE_CAPACITY = 64;
+var OVERFLOW_RELOG_MS = 3e4;
 /**
 * How long a subscription may go without a `pull` before the plane releases it
 * (D461).
@@ -9511,10 +9483,13 @@ var AudioChunkPlane = class {
 			id: subscriptionId,
 			tag: input?.tag ?? "unknown",
 			subscribedAt: Date.now(),
-			queue: new RingBuffer(AUDIO_QUEUE_CAPACITY),
+			queue: new RingBuffer(64),
 			accept: new Set(input?.accept ?? []),
 			servedKey: null,
 			chunksDelivered: 0,
+			chunksDropped: 0,
+			overflowing: false,
+			lastOverflowLogAt: 0,
 			lastPulledAt: Date.now()
 		};
 		this.subscriptions.set(subscriptionId, subscription);
@@ -9566,6 +9541,7 @@ var AudioChunkPlane = class {
 				leaseMs: AUDIO_SUBSCRIPTION_IDLE_MS,
 				queued: subscription.queue.size,
 				chunksDelivered: subscription.chunksDelivered,
+				chunksDropped: subscription.chunksDropped,
 				hint: "the consumer process died without detaching — its subscription was holding this broker in demand"
 			} });
 		}
@@ -9601,13 +9577,47 @@ var AudioChunkPlane = class {
 		for (const subscription of this.subscriptions.values()) {
 			if (sourceFormat === "f32le" || subscription.accept.has(sourceFormat)) {
 				this.noteServed(subscription, sourceFormat, sourceFormat);
-				subscription.queue.push(chunk);
+				this.enqueue(subscription, chunk);
 				continue;
 			}
 			expanded ??= expandChunk(chunk, sourceFormat);
 			this.noteServed(subscription, sourceFormat, "f32le");
-			subscription.queue.push(expanded);
+			this.enqueue(subscription, expanded);
+		}
+	}
+	/**
+	* Push one chunk into a subscription's FIFO and NAME the loss when the FIFO
+	* had no room (D465).
+	*
+	* `RingBuffer.push` overwrites its oldest entry. Every docblock on this path
+	* called that "a bounded safety valve, not the steady-state behaviour" and
+	* nothing ever said when the valve opened, so a consumer polling too slowly
+	* for its producer lost audio permanently and in silence — the exact shape
+	* CLAUDE.md forbids. The realistic cause is a cadence chosen for the
+	* BOUNDARY rather than for the producer's chunk rate: 500 ms of a ~42 ms AAC
+	* chunk is ~12 chunks against a batch that used to drain 8.
+	*/
+	enqueue(subscription, chunk) {
+		const wasFull = subscription.queue.size >= 64;
+		subscription.queue.push(chunk);
+		if (!wasFull) {
+			subscription.overflowing = false;
+			return;
 		}
+		subscription.chunksDropped += 1;
+		const now = Date.now();
+		const isNewEpisode = !subscription.overflowing;
+		subscription.overflowing = true;
+		if (!isNewEpisode && now - subscription.lastOverflowLogAt < OVERFLOW_RELOG_MS) return;
+		subscription.lastOverflowLogAt = now;
+		this.logger?.warn("audio-chunk subscription OVERFLOW — oldest audio overwritten", { meta: {
+			subscriptionId: subscription.id,
+			tag: subscription.tag,
+			capacity: 64,
+			chunksDropped: subscription.chunksDropped,
+			chunksDelivered: subscription.chunksDelivered,
+			hint: "the consumer is pulling slower than this camera produces — its poll cadence or drain batch is wrong for the producer, not the boundary"
+		} });
 	}
 	/**
 	* Run the idle-lease sweep on a cadence rather than on every chunk. A quarter
@@ -9665,10 +9675,6 @@ var AudioChunkPlane = class {
 		this.subscriptions.clear();
 	}
 };
-//#endregion
-//#region src/stream-broker/stream-broker/audio-codec-session.ts
-var POLL_INTERVAL_MS$1 = 40;
-var MAX_PCM_PER_POLL = 16;
 var RTP_HEADER_LENGTH = 12;
 var WARN_THROTTLE_MS$1 = 5e3;
 var SESSION_NOT_FOUND_RE$1 = /decode session\b.*\bnot found\b/;
@@ -9680,19 +9686,23 @@ var AudioCodecSession = class {
 	cfg;
 	emit;
 	logger;
+	realtimeDemand;
 	sessionId = null;
 	sessionNodeId = null;
 	creating = null;
 	pollTimer = null;
+	/** The cadence the loop last armed, so a change can be NAMED once (D465). */
+	pollIntervalMs = null;
 	closed = false;
 	packetsIn = 0;
 	packetsDropped = 0;
 	warnState = /* @__PURE__ */ new Map();
-	constructor(api, cfg, emit, logger) {
+	constructor(api, cfg, emit, logger, realtimeDemand) {
 		this.api = api;
 		this.cfg = cfg;
 		this.emit = emit;
 		this.logger = logger;
+		this.realtimeDemand = realtimeDemand;
 	}
 	processPacket(rtpData) {
 		if (this.closed) return;
@@ -9760,7 +9770,7 @@ var AudioCodecSession = class {
 		if (this.creating) await this.creating;
 		if (this.closed) return;
 		if (this.pollTimer) {
-			clearInterval(this.pollTimer);
+			clearTimeout(this.pollTimer);
 			this.pollTimer = null;
 		}
 		if (!this.sessionId) return;
@@ -9782,7 +9792,7 @@ var AudioCodecSession = class {
 		if (this.closed) return;
 		this.closed = true;
 		if (this.pollTimer) {
-			clearInterval(this.pollTimer);
+			clearTimeout(this.pollTimer);
 			this.pollTimer = null;
 		}
 		if (this.sessionId) {
@@ -9848,11 +9858,43 @@ var AudioCodecSession = class {
 		})();
 		return this.creating;
 	}
+	/**
+	* The cadence this tick should use. Re-read every tick rather than latched at
+	* arm time: a WebRTC session attaching mid-stream must be served at
+	* {@link REALTIME_POLL_INTERVAL_MS}, and it costs at most one idle interval
+	* (400 ms) to notice — against an ICE/DTLS handshake measured in seconds.
+	*/
+	currentPollIntervalMs() {
+		if (!this.realtimeDemand) return 40;
+		return this.realtimeDemand() ? 40 : 400;
+	}
 	startPollLoop() {
 		if (this.pollTimer || this.closed) return;
-		this.pollTimer = setInterval(() => {
-			this.pollOnce();
-		}, POLL_INTERVAL_MS$1);
+		this.scheduleNextPoll();
+	}
+	/**
+	* Self-scheduling tick. `setInterval` cannot change period, and the period is
+	* now a property of who is listening (D465), so the loop re-arms itself.
+	*/
+	scheduleNextPoll() {
+		if (this.closed || !this.sessionId) return;
+		const intervalMs = this.currentPollIntervalMs();
+		if (intervalMs !== this.pollIntervalMs) {
+			const previous = this.pollIntervalMs;
+			this.pollIntervalMs = intervalMs;
+			this.logger?.info("audio-codec: poll cadence", { meta: {
+				intervalMs,
+				previousMs: previous,
+				reason: intervalMs === 40 ? "realtime-consumer" : "plane-only",
+				maxPcmPerPoll: 32
+			} });
+		}
+		this.pollTimer = setTimeout(() => {
+			this.pollTimer = null;
+			this.pollOnce().finally(() => {
+				this.scheduleNextPoll();
+			});
+		}, intervalMs);
 		if (typeof this.pollTimer.unref === "function") this.pollTimer.unref();
 	}
 	async pollOnce() {
@@ -9863,7 +9905,7 @@ var AudioCodecSession = class {
 			const pcms = await this.api.pullPcm({
 				sessionId: sid,
 				...nodeId ? { nodeId } : {},
-				maxCount: MAX_PCM_PER_POLL
+				maxCount: 32
 			});
 			for (const pcm of pcms) this.appendPcm(pcm);
 		} catch (err) {
@@ -9907,7 +9949,7 @@ var AudioCodecSession = class {
 		this.sessionId = null;
 		this.sessionNodeId = null;
 		if (this.pollTimer) {
-			clearInterval(this.pollTimer);
+			clearTimeout(this.pollTimer);
 			this.pollTimer = null;
 		}
 		this.warnThrottled("audio-codec: session reaped upstream — will re-create on next packet", `staleSessionId=${staleSid}`);
@@ -12615,7 +12657,7 @@ var StreamBroker = class StreamBroker {
 				this.logger?.debug("audio-codec: prior session close failed", { meta: { error: errMsg(err) } });
 			});
 		}
-		this.audioCodecSession = new AudioCodecSession(this.audioCodecApi, cfg, this.buildAudioCodecEmitCallback(), this.logger?.child("audio-codec"));
+		this.audioCodecSession = new AudioCodecSession(this.audioCodecApi, cfg, this.buildAudioCodecEmitCallback(), this.logger?.child("audio-codec"), () => this.encodedCallbacks.size > 0);
 		this.logger?.info("push-audio: decode session armed", { meta: {
 			codec: cfg.codec,
 			sourceSampleRate: cfg.sourceSampleRate,
@@ -13821,7 +13863,7 @@ var StreamBroker = class StreamBroker {
 								this.logger?.debug("audio-codec: prior RTSP session close failed", { meta: { error: errMsg(err) } });
 							});
 						}
-						this.audioCodecSession = new AudioCodecSession(this.audioCodecApi, capCfg, this.buildAudioCodecEmitCallback(), this.logger?.child("audio-codec"));
+						this.audioCodecSession = new AudioCodecSession(this.audioCodecApi, capCfg, this.buildAudioCodecEmitCallback(), this.logger?.child("audio-codec"), () => this.encodedCallbacks.size > 0);
 						this.logger?.info("audio-codec: decode session armed", { meta: {
 							codec: capCfg.codec,
 							sourceSampleRate: capCfg.sourceSampleRate,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/addon-pipeline",
-  "version": "1.2.222",
+  "version": "1.2.224",
   "description": "Pipeline bundle — runner, detection, motion, audio + stream broker. Multi-entry npm package shipping pipeline addons under a single bundle.",
   "keywords": [
     "camstack",