@trillboards/edge-platform-rtsp 0.2.1 → 0.2.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,731 @@
1
+ "use strict";
2
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
3
+ if (k2 === undefined) k2 = k;
4
+ var desc = Object.getOwnPropertyDescriptor(m, k);
5
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
6
+ desc = { enumerable: true, get: function() { return m[k]; } };
7
+ }
8
+ Object.defineProperty(o, k2, desc);
9
+ }) : (function(o, m, k, k2) {
10
+ if (k2 === undefined) k2 = k;
11
+ o[k2] = m[k];
12
+ }));
13
+ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
14
+ Object.defineProperty(o, "default", { enumerable: true, value: v });
15
+ }) : function(o, v) {
16
+ o["default"] = v;
17
+ });
18
+ var __importStar = (this && this.__importStar) || function (mod) {
19
+ if (mod && mod.__esModule) return mod;
20
+ var result = {};
21
+ if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
22
+ __setModuleDefault(result, mod);
23
+ return result;
24
+ };
25
+ Object.defineProperty(exports, "__esModule", { value: true });
26
+ exports.RTSPAudioProvider = exports.audioSessionStatsFor = exports.__resetAudioAdmissionForTests = exports.BoundedSessionStderr = exports.RtspAudioNoTrackError = exports.RtspAudioAdmissionError = void 0;
27
+ const child_process_1 = require("child_process");
28
+ const fs = __importStar(require("fs"));
29
+ const os = __importStar(require("os"));
30
+ const path = __importStar(require("path"));
31
+ const RTSPCameraProvider_1 = require("./RTSPCameraProvider");
32
+ /**
33
+ * RTSPAudioProvider — continuous audio off an RTSP camera/NVR channel, as a
34
+ * LONG-LIVED ffmpeg session feeding a bounded ring buffer.
35
+ *
36
+ * ── THE DESIGN PROBLEM, AND IT IS THE WHOLE FILE. Video capture in this
37
+ * package is ONE-SHOT-PER-FRAME behind a recorder-scoped admission gate
38
+ * (`CaptureAdmission`, default 2 concurrent pulls per host:port). That gate is
39
+ * incident-derived: a 32-channel NVR accumulated 28 simultaneous ffmpeg
40
+ * children when pulls started outliving the cadence, and the recorder answered
41
+ * with rotating timeouts, CSeq mismatches and cameras flapping into "needs
42
+ * attention" (.claude/lessons/2026-08-17-rtsp-session-admission-and-frame-integrity.md).
43
+ * The rule that came out of it is that admission must be shared by PHYSICAL
44
+ * RECORDER (host:port), never scoped to a provider instance.
45
+ *
46
+ * Audio cannot be one-shot. Sampling three seconds out of every thirty misses
47
+ * ~90% of the events audio exists to catch, and the point of the acoustic
48
+ * channel is precisely to hear what happens BETWEEN frame pulls. So it needs a
49
+ * session that stays open — which is the one shape the existing gate is least
50
+ * able to absorb, because a permanent holder of a 2-slot pool is a 50%
51
+ * permanent tax on frame capture for that recorder, and two of them deadlock
52
+ * video entirely.
53
+ *
54
+ * ── THE RESOLUTION: A SECOND, SEPARATE LANE ON THE SAME RECORDER KEY.
55
+ * Long-lived audio sessions are admitted from `audioAdmissionBySource`, keyed
56
+ * by the SAME `captureSourceKey(url)` — host:port, credentials and channel path
57
+ * deliberately excluded so 32 channels of one NVR share one budget — but
58
+ * counted in their OWN pool with its own cap (`maxAudioSessionsPerSource`,
59
+ * DEFAULT 1). Three properties fall out, and all three are the point:
60
+ *
61
+ * 1. Audio can NEVER consume a video pull slot, so the incident's failure
62
+ * mode is untouched: frame capture's concurrency against a recorder is
63
+ * exactly what it was before this file existed.
64
+ * 2. Audio is bounded per PHYSICAL RECORDER, which is the lesson's actual
65
+ * rule. A 32-channel NVR gets ONE continuous audio session, not 32 — the
66
+ * naive per-camera design would recreate the incident with processes that
67
+ * never exit, which is strictly worse than the one we already had.
68
+ * 3. The bound is on ADMISSION, so it cannot be exceeded and then reconciled.
69
+ *
70
+ * ── THE SESSION IS ALSO WHY AUDIO IS CHEAP, AND THAT WAS MEASURED ELSEWHERE.
71
+ * `buildCaptureArgs` spawns ONE ffmpeg per grab, so every video look pays a full
72
+ * RTSP handshake plus a keyframe wait: p50 ~2,000 ms against a real stream
73
+ * versus 20–30 ms against a local file, i.e. ~99% of a look is session SETUP,
74
+ * not imaging. That per-look tax is what caps the video cadence. This provider
75
+ * pays it ONCE per recorder and then streams, so the acoustic channel gets
76
+ * CONTINUOUS coverage for a single handshake while video gets one instant per
77
+ * ~2 s of setup. Audio is therefore structurally cheaper per unit of coverage
78
+ * than video is, and it is cheapest exactly where video is dearest — between
79
+ * looks, which is the interval the whole acoustic channel exists to cover. The
80
+ * one-shot/long-lived split is not an awkward asymmetry to be tidied away
81
+ * later; it is the reason this design earns its keep.
82
+ *
83
+ * ── DROP, NEVER QUEUE. A camera that cannot get the slot runs WITHOUT audio
84
+ * and says so (`RtspAudioAdmissionError`); it does not wait. This mirrors
85
+ * `VlmAdmissionGate` for the same reason — a queued audio session would be
86
+ * admitted minutes later against a scene nobody is asking about any more — and
87
+ * it keeps audio strictly supplementary: no failure in this file may ever be
88
+ * able to stop a camera from producing frames.
89
+ *
90
+ * ── A CAMERA WITH NO AUDIO TRACK MUST NOT HOLD THE SLOT. Most CCTV channels
91
+ * carry no audio at all. If such a feed took the recorder's single audio slot
92
+ * and then sat there failing, it would silently deny audio to the one camera on
93
+ * that NVR that actually has a microphone — a defect that looks exactly like
94
+ * "audio doesn't work" and is invisible to every health check. So a missing
95
+ * audio stream is classified as its own PERMANENT outcome: the session stops,
96
+ * the slot is RELEASED immediately, and `open()` rejects with
97
+ * `RtspAudioNoTrackError`. Re-probing is the caller's explicit decision, never
98
+ * a silent retry loop against a recorder.
99
+ *
100
+ * ── RESTARTS RE-ARM, AT STARTUP AS WELL AS AT RUNTIME. Any other failure
101
+ * (dropped TCP, recorder reboot, network blip) is transient. A RUNNING session
102
+ * is retried with exponential backoff capped at `maxRestartDelayMs` and NEVER
103
+ * permanently retires the feed while the provider is open. An OPENING session
104
+ * gets `openValidationAttempts` tries (default 4, mirroring
105
+ * `RTSPCameraProvider`) — because a supervisor that only covers the running
106
+ * case leaves the hole exactly where an unattended 24/7 connector is most
107
+ * likely to fall in it: a recorder that is merely slow or rebooting at boot
108
+ * would otherwise cost that feed its audio for the LIFE OF THE PROCESS. That is deliberate and incident-derived from the other direction:
109
+ * on the Ember fleet `shouldGiveUp` retired a camera permanently after a fixed
110
+ * 411 s and NOTHING re-armed it — `onCameraStartFailed` was telemetry-only, no
111
+ * config push restarted the analyzer, and `setMaxRetries` had zero call sites,
112
+ * so 7,359 escalations became permanent silence
113
+ * (docs/runbooks/ember-camera-health-taxonomy.md). A capped-backoff retry that
114
+ * never gives up IS the re-arm; the cap is what keeps it from being a hammer.
115
+ *
116
+ * ── SECRET HYGIENE, INHERITED. RTSP URLs carry passwords. Exactly as
117
+ * `RTSPCameraProvider` does, the URL is written to a 0600 ffconcat file and
118
+ * only the temp path reaches argv, so a password never appears in `ps` output;
119
+ * stderr is scrubbed through `sanitizeStreamUrlForLog` before it can reach a
120
+ * log line.
121
+ *
122
+ * ── A NON-MONOTONIC AUDIO DTS CANNOT CORRUPT THIS RING, AND THAT IS MEASURED.
123
+ * The 2026-08-18 camera validation logged ffmpeg's non-monotonic DTS warning on
124
+ * Happytime's PCMU track over RTSP/UDP. It does not follow that this provider
125
+ * is affected, and it is not — for two independent reasons, both checked rather
126
+ * than reasoned:
127
+ * 1. The OUTPUT stage is `-f s16le`, a headerless raw-PCM muxer that performs
128
+ * no timestamp monotonicity check. Fed an input with a deliberate backwards
129
+ * audio DTS jump (581040 -> 126000, built with the concat protocol over two
130
+ * identical MPEG-TS segments), this exact arg vector emitted ZERO
131
+ * non-monotonic complaints and dropped no audio.
132
+ * 2. `consumePcm` never reads a media timestamp. Samples are appended to the
133
+ * ring in arrival order and stamped with `this.now()` — WALL CLOCK — so a
134
+ * demuxer-side timestamp cannot reorder, duplicate or gap the buffer that
135
+ * `AudioOnsetDetector` consumes.
136
+ * Belt and braces: the live wiring in `attachAudioOnset` defaults to
137
+ * `transport: 'tcp'`, and TCP was clean in that run; UDP is reachable only by a
138
+ * caller explicitly asking for it. What the warning DOES cost is diagnostic —
139
+ * it is per-packet, so it fills the stderr budget fast. See `STDERR_HEAD_LIMIT`.
140
+ *
141
+ * ── NO CACHED CAPABILITY BOOLEAN, ON PURPOSE. The obvious addition here is a
142
+ * `cap_audio` flag set once at startup. Do not add one. On the Android DOOH
143
+ * fleet `cap_audio_classification` is `false` FLEET-WIDE — including on devices
144
+ * shipping live YAMNet classifications — because `detectCapabilities()` read a
145
+ * synchronous "still probing" value, the async probe resolved later, and
146
+ * NOTHING ever re-wrote the flag. It is published to DSPs in that state
147
+ * (docs/runbooks/audio-sensing-substrate.md). Audio capability here is
148
+ * genuinely asynchronous for the same reason — whether a stream carries audio
149
+ * is only knowable after ffmpeg has answered — so `getStats()` DERIVES every
150
+ * field live on each call (`running`, `noAudioTrack`, `buffered`,
151
+ * `lastPcmAtMs`) and there is no stored boolean that can outlive its truth. If
152
+ * a caller ever does need a flag, it must be recomputed from these, never
153
+ * latched at boot.
154
+ *
155
+ * ── LAYERING. This package is TRANSPORT. It knows nothing about onsets,
156
+ * motion or models — `AudioOnsetDetector` and the gate wiring live in
157
+ * `@trillboards/edge-sdk`, which is also the only package that may depend on
158
+ * both. `onPcm()` is the seam: this file produces a continuous mono Float32
159
+ * stream, and the SDK decides what it means.
160
+ */
161
+ /** Admission was refused: this recorder already runs its allowed audio sessions. */
162
+ class RtspAudioAdmissionError extends Error {
163
+ constructor(sourceKey, limit) {
164
+ super(`RTSP audio session refused: recorder ${sourceKey} already runs ${limit} audio session(s). ` +
165
+ 'Audio is supplementary; this feed continues without it.');
166
+ this.code = 'RTSP_AUDIO_SESSION_LIMIT';
167
+ this.name = 'RtspAudioAdmissionError';
168
+ }
169
+ }
170
+ exports.RtspAudioAdmissionError = RtspAudioAdmissionError;
171
+ /** The stream carries no audio track. Permanent for this URL until re-probed. */
172
+ class RtspAudioNoTrackError extends Error {
173
+ constructor(url) {
174
+ super(`RTSP stream has no audio track: ${(0, RTSPCameraProvider_1.sanitizeStreamUrlForLog)(url)}`);
175
+ this.code = 'RTSP_AUDIO_NO_TRACK';
176
+ this.name = 'RtspAudioNoTrackError';
177
+ }
178
+ }
179
+ exports.RtspAudioNoTrackError = RtspAudioNoTrackError;
180
+ /** ffmpeg's answer when `-map 0:a` matches nothing, across versions. */
181
+ const NO_AUDIO_STREAM_RE = /(stream map '0:a[^']*' matches no streams|does not contain any stream|audio stream not found|output file #0 does not contain any stream)/i;
182
+ const DEFAULT_SAMPLE_RATE = 16000;
183
+ const DEFAULT_BUFFER_SECONDS = 30;
184
+ const DEFAULT_MAX_AUDIO_SESSIONS_PER_SOURCE = 1;
185
+ const DEFAULT_TIMEOUT_US = 12000000;
186
+ const DEFAULT_RESTART_DELAY_MS = 1000;
187
+ const DEFAULT_MAX_RESTART_DELAY_MS = 60000;
188
+ /** Transient startup misses tolerated before open() gives up, as the camera path does. */
189
+ const DEFAULT_OPEN_VALIDATION_ATTEMPTS = 4;
190
+ /**
191
+ * stderr kept per session for diagnosis, HEAD **and** TAIL.
192
+ *
193
+ * ── WHY NOT HEAD-ONLY, WHICH IS WHAT THIS WAS. The previous accumulator was
194
+ * `if (stderr.length < 8_000) stderr += chunk`, i.e. it kept the FIRST 8 KB and
195
+ * discarded everything after. On the one-shot camera path that is harmless: a
196
+ * frame grab lives ~2 s and never produces 8 KB. This provider is the opposite
197
+ * shape by design — ONE session per recorder, held open for hours — and ffmpeg
198
+ * writes a progress line to stderr the entire time.
199
+ *
200
+ * Measured with this file's exact arg vector against a real RTSP feed
201
+ * (H.264 + PCMU over TCP, ffmpeg 9.0.1): stderr reached 3,724 B at 15 s and
202
+ * 17,283 B at 90 s — a steady **~181 bytes/second on a completely healthy feed,
203
+ * with no warnings at all**. The 8 KB head-only cap is therefore full about
204
+ * **41 seconds** into every session. From that moment the session is
205
+ * diagnostically blind: an auth rotation, a recorder reboot, a network drop
206
+ * hours later has its ffmpeg diagnosis silently discarded, `lastErrorMessage`
207
+ * still reports the startup banner, and `summarizeFfmpegStderr`'s deliberate
208
+ * head+tail split (the decisive ffmpeg line is almost always the LAST one) is
209
+ * handed a buffer whose "tail" is 41-second-old boilerplate.
210
+ *
211
+ * That is the connector's recurring defect class — a signal that cannot report
212
+ * its own failure — sitting in the live path of a shipped feature. The
213
+ * non-monotonic PCMU DTS warning found on 2026-08-18 does not corrupt audio
214
+ * (see `consumePcm`: this provider never reads a media timestamp), but it is a
215
+ * PER-PACKET warning, so on a feed that emits it the 41 seconds collapses to
216
+ * about one, and the blackout starts almost immediately.
217
+ *
218
+ * The total retained is unchanged at 8 KB, so memory is exactly what it was.
219
+ * What changes is WHICH 8 KB: the banner that identifies the build, and the
220
+ * lines that were on screen when the session actually died.
221
+ */
222
+ const STDERR_HEAD_LIMIT = 4000;
223
+ const STDERR_TAIL_LIMIT = 4000;
224
+ /**
225
+ * Bounded head+tail accumulator. Append-only, allocation-bounded, and it says
226
+ * out loud how much it dropped — a truncation that hides its own existence is
227
+ * how a summary becomes a lie.
228
+ */
229
+ class BoundedSessionStderr {
230
+ constructor() {
231
+ this.head = '';
232
+ this.tail = '';
233
+ this.droppedBytes = 0;
234
+ }
235
+ append(text) {
236
+ let rest = text;
237
+ if (this.head.length < STDERR_HEAD_LIMIT) {
238
+ const room = STDERR_HEAD_LIMIT - this.head.length;
239
+ this.head += rest.slice(0, room);
240
+ rest = rest.slice(room);
241
+ }
242
+ if (!rest)
243
+ return;
244
+ this.tail += rest;
245
+ if (this.tail.length > STDERR_TAIL_LIMIT) {
246
+ const excess = this.tail.length - STDERR_TAIL_LIMIT;
247
+ this.droppedBytes += excess;
248
+ this.tail = this.tail.slice(excess);
249
+ }
250
+ }
251
+ text() {
252
+ if (!this.tail)
253
+ return this.head;
254
+ if (this.droppedBytes === 0)
255
+ return this.head + this.tail;
256
+ return `${this.head}\n... ${this.droppedBytes} bytes of ffmpeg output dropped ...\n${this.tail}`;
257
+ }
258
+ }
259
+ exports.BoundedSessionStderr = BoundedSessionStderr;
260
+ /**
261
+ * Recorder-scoped admission for LONG-LIVED audio sessions. Deliberately a
262
+ * different pool from `CaptureAdmission`: same key, separate budget, and
263
+ * `tryAcquire` only — there is no `acquire()` because this lane never queues.
264
+ */
265
+ class AudioSessionAdmission {
266
+ constructor(limit) {
267
+ this.active = 0;
268
+ this.limit = limit;
269
+ }
270
+ /** Tighten only, matching CaptureAdmission: the most cautious caller wins. */
271
+ tightenLimit(limit) {
272
+ this.limit = Math.min(this.limit, limit);
273
+ }
274
+ getLimit() {
275
+ return this.limit;
276
+ }
277
+ getActive() {
278
+ return this.active;
279
+ }
280
+ tryAcquire() {
281
+ if (this.active >= this.limit)
282
+ return null;
283
+ this.active += 1;
284
+ let released = false;
285
+ return () => {
286
+ if (released)
287
+ return;
288
+ released = true;
289
+ this.active = Math.max(0, this.active - 1);
290
+ };
291
+ }
292
+ }
293
+ const audioAdmissionBySource = new Map();
294
+ function audioAdmissionFor(streamUrl, limit) {
295
+ const key = (0, RTSPCameraProvider_1.captureSourceKey)(streamUrl);
296
+ if (!key)
297
+ return null;
298
+ const existing = audioAdmissionBySource.get(key);
299
+ if (existing) {
300
+ existing.tightenLimit(limit);
301
+ return existing;
302
+ }
303
+ const admission = new AudioSessionAdmission(limit);
304
+ audioAdmissionBySource.set(key, admission);
305
+ return admission;
306
+ }
307
+ /** Test seam: forget every recorder's audio budget. */
308
+ function __resetAudioAdmissionForTests() {
309
+ audioAdmissionBySource.clear();
310
+ }
311
+ exports.__resetAudioAdmissionForTests = __resetAudioAdmissionForTests;
312
+ /** Live audio-lane occupancy for a recorder, for diagnostics. */
313
+ function audioSessionStatsFor(streamUrl) {
314
+ const key = (0, RTSPCameraProvider_1.captureSourceKey)(streamUrl);
315
+ if (!key)
316
+ return null;
317
+ const admission = audioAdmissionBySource.get(key);
318
+ if (!admission)
319
+ return null;
320
+ return { key, active: admission.getActive(), limit: admission.getLimit() };
321
+ }
322
+ exports.audioSessionStatsFor = audioSessionStatsFor;
323
+ /**
324
+ * One instance per audio-carrying feed. Implements the SAME `AudioProvider`
325
+ * interface as the Linux/Windows/web providers, so `AudienceSensingService`
326
+ * consumes it unchanged — but the pull (`getAudioChunk`) reads from the ring
327
+ * that the long-lived session is continuously filling, rather than spawning a
328
+ * process per call the way a microphone provider does.
329
+ */
330
+ class RTSPAudioProvider {
331
+ constructor(config) {
332
+ this.ringWrite = 0;
333
+ this.ringFilled = 0;
334
+ this.opened = false;
335
+ this.proc = null;
336
+ this.releaseAdmission = null;
337
+ this.restartTimer = null;
338
+ /** While true, `open()` owns retries and the supervisor must not schedule any. */
339
+ this.startingUp = false;
340
+ this.cleanupInput = null;
341
+ /** Odd trailing byte carried between stdout chunks so samples are never torn. */
342
+ this.pendingByte = null;
343
+ this.listeners = [];
344
+ this.totalSamples = 0;
345
+ this.sessionStarts = 0;
346
+ this.restarts = 0;
347
+ this.noAudioTrack = false;
348
+ this.lastErrorMessage = null;
349
+ this.lastPcmAtMs = null;
350
+ if (!config?.rtspUrl)
351
+ throw new Error('RTSPAudioProvider requires an rtspUrl');
352
+ this.rtspUrl = config.rtspUrl;
353
+ this.sampleRate = config.sampleRate ?? DEFAULT_SAMPLE_RATE;
354
+ const bufferSeconds = config.bufferSeconds ?? DEFAULT_BUFFER_SECONDS;
355
+ this.capacity = Math.max(this.sampleRate, Math.round(this.sampleRate * bufferSeconds));
356
+ this.ring = new Float32Array(this.capacity);
357
+ this.maxAudioSessionsPerSource = Math.max(1, Math.trunc(config.maxAudioSessionsPerSource ?? DEFAULT_MAX_AUDIO_SESSIONS_PER_SOURCE));
358
+ this.transport = config.transport ?? 'tcp';
359
+ this.timeoutUs = config.timeoutUs ?? DEFAULT_TIMEOUT_US;
360
+ this.ffmpegPath = config.ffmpegPath ?? 'ffmpeg';
361
+ this.ffmpegMajorVersion = config.ffmpegMajorVersion ?? 6;
362
+ this.openValidationAttempts = Math.max(1, Math.trunc(config.openValidationAttempts ?? DEFAULT_OPEN_VALIDATION_ATTEMPTS));
363
+ this.restartDelayMs = Math.max(0, config.restartDelayMs ?? DEFAULT_RESTART_DELAY_MS);
364
+ this.maxRestartDelayMs = Math.max(this.restartDelayMs, config.maxRestartDelayMs ?? DEFAULT_MAX_RESTART_DELAY_MS);
365
+ this.currentRestartDelay = this.restartDelayMs;
366
+ this.spawnFn = config.spawnFn ?? child_process_1.spawn;
367
+ this.now = config.now ?? Date.now;
368
+ this.onLog = config.onLog;
369
+ }
370
+ getSampleRate() {
371
+ return this.sampleRate;
372
+ }
373
+ isOpen() {
374
+ return this.opened;
375
+ }
376
+ getStats() {
377
+ return {
378
+ opened: this.opened,
379
+ running: this.proc !== null,
380
+ buffered: this.ringFilled,
381
+ capacity: this.capacity,
382
+ totalSamples: this.totalSamples,
383
+ sessionStarts: this.sessionStarts,
384
+ restarts: this.restarts,
385
+ noAudioTrack: this.noAudioTrack,
386
+ lastErrorMessage: this.lastErrorMessage,
387
+ lastPcmAtMs: this.lastPcmAtMs,
388
+ };
389
+ }
390
+ /**
391
+ * Subscribe to the continuous stream. Returns an unsubscribe function.
392
+ * This is the seam the SDK's onset detector attaches to; `getAudioChunk`
393
+ * remains the pull-based `AudioProvider` contract for everything else.
394
+ */
395
+ onPcm(listener) {
396
+ this.listeners.push(listener);
397
+ return () => {
398
+ this.listeners = this.listeners.filter((l) => l !== listener);
399
+ };
400
+ }
401
+ /**
402
+ * Take a recorder audio slot and start the session. Rejects with
403
+ * `RtspAudioAdmissionError` when the recorder's audio lane is full, and with
404
+ * `RtspAudioNoTrackError` when the stream turns out to carry no audio — both
405
+ * of which a caller should treat as "this feed has no audio", never as a
406
+ * camera fault.
407
+ */
408
+ async open() {
409
+ if (this.opened)
410
+ return;
411
+ const admission = audioAdmissionFor(this.rtspUrl, this.maxAudioSessionsPerSource);
412
+ if (admission) {
413
+ const release = admission.tryAcquire();
414
+ if (!release) {
415
+ throw new RtspAudioAdmissionError((0, RTSPCameraProvider_1.captureSourceKey)(this.rtspUrl) ?? 'unknown', admission.getLimit());
416
+ }
417
+ this.releaseAdmission = release;
418
+ }
419
+ this.opened = true;
420
+ this.noAudioTrack = false;
421
+ this.currentRestartDelay = this.restartDelayMs;
422
+ this.startingUp = true;
423
+ let lastErr;
424
+ try {
425
+ for (let attempt = 1; attempt <= this.openValidationAttempts; attempt++) {
426
+ try {
427
+ await this.startSession();
428
+ return;
429
+ }
430
+ catch (err) {
431
+ lastErr = err;
432
+ // A stream with no audio track is settled — never retried.
433
+ if (err instanceof RtspAudioNoTrackError)
434
+ break;
435
+ this.stopProcess();
436
+ if (attempt < this.openValidationAttempts && this.restartDelayMs > 0) {
437
+ await new Promise((resolve) => setTimeout(resolve, this.restartDelayMs));
438
+ }
439
+ if (!this.opened)
440
+ break; // closed underneath us
441
+ }
442
+ }
443
+ }
444
+ finally {
445
+ this.startingUp = false;
446
+ }
447
+ // Startup failed for good — give the slot back immediately so an
448
+ // audio-carrying camera on the same recorder can use it.
449
+ this.opened = false;
450
+ this.stopProcess();
451
+ this.releaseSlot();
452
+ throw lastErr instanceof Error ? lastErr : new Error(String(lastErr ?? 'RTSP audio open failed'));
453
+ }
454
+ /**
455
+ * Most recent `durationMs` of audio from the ring. Returns whatever is
456
+ * available when the buffer holds less — a short read is a normal startup
457
+ * condition, not an error, and throwing here would make a supplementary
458
+ * signal able to break a caller.
459
+ */
460
+ async getAudioChunk(durationMs) {
461
+ if (!this.opened)
462
+ throw new Error('Audio not opened. Call open() first.');
463
+ const want = Math.max(0, Math.round((this.sampleRate * durationMs) / 1000));
464
+ return this.readMostRecent(Math.min(want, this.ringFilled));
465
+ }
466
+ /** Everything currently buffered, oldest first. */
467
+ drain() {
468
+ return this.readMostRecent(this.ringFilled);
469
+ }
470
+ async close() {
471
+ this.opened = false;
472
+ if (this.restartTimer) {
473
+ clearTimeout(this.restartTimer);
474
+ this.restartTimer = null;
475
+ }
476
+ this.stopProcess();
477
+ this.releaseSlot();
478
+ this.listeners = [];
479
+ }
480
+ // ── internals ────────────────────────────────────────────────────────────
481
+ releaseSlot() {
482
+ if (this.releaseAdmission) {
483
+ this.releaseAdmission();
484
+ this.releaseAdmission = null;
485
+ }
486
+ }
487
+ readMostRecent(count) {
488
+ const n = Math.min(count, this.ringFilled);
489
+ const out = new Float32Array(n);
490
+ if (n === 0)
491
+ return out;
492
+ // The newest sample sits just behind ringWrite.
493
+ let start = this.ringWrite - n;
494
+ while (start < 0)
495
+ start += this.capacity;
496
+ for (let i = 0; i < n; i++) {
497
+ out[i] = this.ring[(start + i) % this.capacity];
498
+ }
499
+ return out;
500
+ }
501
+ appendSamples(samples) {
502
+ for (let i = 0; i < samples.length; i++) {
503
+ this.ring[this.ringWrite] = samples[i];
504
+ this.ringWrite = (this.ringWrite + 1) % this.capacity;
505
+ }
506
+ this.ringFilled = Math.min(this.capacity, this.ringFilled + samples.length);
507
+ this.totalSamples += samples.length;
508
+ }
509
+ /**
510
+ * ffmpeg args for a continuous mono PCM pull. The URL goes into a 0600
511
+ * ffconcat file exactly as the camera path does, so it never reaches argv.
512
+ */
513
+ buildInputArgs() {
514
+ const isRtsp = /^rtsps?:\/\//i.test(this.rtspUrl);
515
+ if (!isRtsp) {
516
+ return { args: ['-i', this.rtspUrl], cleanup: () => undefined };
517
+ }
518
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'trillboards-rtsp-audio-'));
519
+ const file = path.join(dir, 'input.ffconcat');
520
+ const timeoutOpt = this.ffmpegMajorVersion >= 5 ? 'timeout' : 'stimeout';
521
+ fs.writeFileSync(file, [
522
+ 'ffconcat version 1.0',
523
+ `file '${(0, RTSPCameraProvider_1.escapeFfconcatValue)(this.rtspUrl)}'`,
524
+ `option rtsp_transport ${this.transport}`,
525
+ `option ${timeoutOpt} ${this.timeoutUs}`,
526
+ '',
527
+ ].join('\n'), { mode: 0o600 });
528
+ try {
529
+ fs.chmodSync(file, 0o600);
530
+ }
531
+ catch {
532
+ /* best-effort on platforms with ACL semantics */
533
+ }
534
+ return {
535
+ args: ['-protocol_whitelist', 'file,crypto,tcp,tls,rtp,rtsp,udp,http,https', '-safe', '0', '-f', 'concat', '-i', file],
536
+ cleanup: () => {
537
+ try {
538
+ fs.unlinkSync(file);
539
+ }
540
+ catch {
541
+ /* already gone */
542
+ }
543
+ try {
544
+ fs.rmdirSync(dir);
545
+ }
546
+ catch {
547
+ /* best-effort */
548
+ }
549
+ },
550
+ };
551
+ }
552
+ buildArgs() {
553
+ const input = this.buildInputArgs();
554
+ return {
555
+ args: [
556
+ '-nostdin',
557
+ ...input.args,
558
+ '-vn',
559
+ '-map', '0:a:0',
560
+ '-ac', '1',
561
+ '-ar', String(this.sampleRate),
562
+ '-f', 's16le',
563
+ 'pipe:1',
564
+ ],
565
+ cleanup: input.cleanup,
566
+ };
567
+ }
568
+ /**
569
+ * Start one ffmpeg session. Resolves once the process is spawned AND has
570
+ * survived long enough to rule out the "no audio track" classification —
571
+ * ffmpeg reports that within milliseconds, before any PCM flows, so waiting
572
+ * for the FIRST of (first PCM | early exit) settles it without a timer.
573
+ */
574
+ startSession() {
575
+ return new Promise((resolve, reject) => {
576
+ const { args, cleanup } = this.buildArgs();
577
+ this.cleanupInput = cleanup;
578
+ this.sessionStarts++;
579
+ let proc;
580
+ try {
581
+ proc = this.spawnFn(this.ffmpegPath, args, { stdio: ['ignore', 'pipe', 'pipe'] });
582
+ }
583
+ catch (err) {
584
+ cleanup();
585
+ this.cleanupInput = null;
586
+ reject(err instanceof Error ? err : new Error(String(err)));
587
+ return;
588
+ }
589
+ this.proc = proc;
590
+ this.pendingByte = null;
591
+ const stderrBuffer = new BoundedSessionStderr();
592
+ let settled = false;
593
+ const settle = (fn) => {
594
+ if (settled)
595
+ return;
596
+ settled = true;
597
+ fn();
598
+ };
599
+ proc.stdout?.on('data', (chunk) => {
600
+ this.consumePcm(chunk);
601
+ // First PCM proves the stream has audio and the session is healthy.
602
+ this.currentRestartDelay = this.restartDelayMs;
603
+ settle(resolve);
604
+ });
605
+ proc.stderr?.on('data', (chunk) => {
606
+ stderrBuffer.append(chunk.toString());
607
+ });
608
+ proc.on('error', (err) => {
609
+ this.lastErrorMessage = (0, RTSPCameraProvider_1.sanitizeStreamUrlForLog)(err.message);
610
+ settle(() => reject(err));
611
+ this.handleSessionEnd(stderrBuffer.text());
612
+ });
613
+ proc.on('close', () => {
614
+ const stderr = stderrBuffer.text();
615
+ const summary = (0, RTSPCameraProvider_1.summarizeFfmpegStderr)(stderr);
616
+ if (NO_AUDIO_STREAM_RE.test(stderr)) {
617
+ this.noAudioTrack = true;
618
+ this.lastErrorMessage = summary;
619
+ settle(() => reject(new RtspAudioNoTrackError(this.rtspUrl)));
620
+ this.handleSessionEnd(stderr);
621
+ return;
622
+ }
623
+ this.lastErrorMessage = summary;
624
+ settle(() => reject(new Error(`RTSP audio session ended during startup: ${summary}`)));
625
+ this.handleSessionEnd(stderr);
626
+ });
627
+ });
628
+ }
629
+ /** s16le → Float32, carrying an odd trailing byte between chunks. */
630
+ consumePcm(chunk) {
631
+ let buf = chunk;
632
+ if (this.pendingByte) {
633
+ buf = Buffer.concat([this.pendingByte, chunk]);
634
+ this.pendingByte = null;
635
+ }
636
+ const usable = buf.length - (buf.length % 2);
637
+ if (usable < buf.length)
638
+ this.pendingByte = buf.subarray(usable);
639
+ if (usable === 0)
640
+ return;
641
+ const samples = new Float32Array(usable / 2);
642
+ for (let i = 0; i < samples.length; i++) {
643
+ samples[i] = buf.readInt16LE(i * 2) / 32768;
644
+ }
645
+ this.appendSamples(samples);
646
+ const at = this.now();
647
+ this.lastPcmAtMs = at;
648
+ for (const listener of this.listeners) {
649
+ try {
650
+ listener(samples, at);
651
+ }
652
+ catch (err) {
653
+ this.log('warn', `audio listener threw: ${err?.message ?? String(err)}`);
654
+ }
655
+ }
656
+ }
657
+ stopProcess() {
658
+ const proc = this.proc;
659
+ this.proc = null;
660
+ if (proc) {
661
+ try {
662
+ proc.kill('SIGTERM');
663
+ }
664
+ catch {
665
+ /* already gone */
666
+ }
667
+ // Bounded escalation: an ffmpeg wedged on a half-open RTSP socket ignores
668
+ // SIGTERM, and a connector that leaks one child per restart is the
669
+ // 28-children incident wearing a different hat.
670
+ const timer = setTimeout(() => {
671
+ try {
672
+ proc.kill('SIGKILL');
673
+ }
674
+ catch {
675
+ /* already gone */
676
+ }
677
+ }, 2000);
678
+ if (typeof timer.unref === 'function')
679
+ timer.unref();
680
+ }
681
+ if (this.cleanupInput) {
682
+ this.cleanupInput();
683
+ this.cleanupInput = null;
684
+ }
685
+ }
686
+ /**
687
+ * A session ended. If the provider is still open and the stream is not known
688
+ * to be audio-less, schedule a restart with capped exponential backoff. This
689
+ * loop is what re-arms the feed and it is never allowed to give up — see the
690
+ * header on the Ember permanent-retirement failure.
691
+ */
692
+ handleSessionEnd(stderr) {
693
+ if (this.cleanupInput) {
694
+ this.cleanupInput();
695
+ this.cleanupInput = null;
696
+ }
697
+ this.proc = null;
698
+ if (!this.opened)
699
+ return;
700
+ if (this.noAudioTrack) {
701
+ // Never hold a recorder's audio slot for a stream that has no audio.
702
+ this.opened = false;
703
+ this.releaseSlot();
704
+ this.log('info', `RTSP audio: no audio track, releasing recorder slot (${(0, RTSPCameraProvider_1.summarizeFfmpegStderr)(stderr, 200)})`);
705
+ return;
706
+ }
707
+ if (this.startingUp)
708
+ return; // open() owns the retry loop during startup
709
+ if (this.restartTimer)
710
+ return;
711
+ const delay = this.currentRestartDelay;
712
+ this.currentRestartDelay = Math.min(this.maxRestartDelayMs, Math.max(1, this.currentRestartDelay * 2));
713
+ this.restarts++;
714
+ this.log('warn', `RTSP audio session ended, restarting in ${delay}ms`);
715
+ this.restartTimer = setTimeout(() => {
716
+ this.restartTimer = null;
717
+ if (!this.opened)
718
+ return;
719
+ this.startSession().catch((err) => {
720
+ this.lastErrorMessage = (0, RTSPCameraProvider_1.sanitizeStreamUrlForLog)(err?.message ?? String(err));
721
+ });
722
+ }, delay);
723
+ if (typeof this.restartTimer.unref === 'function')
724
+ this.restartTimer.unref();
725
+ }
726
+ log(level, message) {
727
+ this.onLog?.(level, (0, RTSPCameraProvider_1.sanitizeStreamUrlForLog)(message));
728
+ }
729
+ }
730
+ exports.RTSPAudioProvider = RTSPAudioProvider;
731
+ //# sourceMappingURL=RTSPAudioProvider.js.map