@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.
- package/README.md +86 -0
- package/dist/MacAudioProvider.d.ts +102 -0
- package/dist/MacAudioProvider.d.ts.map +1 -0
- package/dist/MacAudioProvider.js +218 -0
- package/dist/MacAudioProvider.js.map +1 -0
- package/dist/RTSPAudioProvider.d.ts +330 -0
- package/dist/RTSPAudioProvider.d.ts.map +1 -0
- package/dist/RTSPAudioProvider.js +731 -0
- package/dist/RTSPAudioProvider.js.map +1 -0
- package/dist/RTSPCameraProvider.d.ts +2 -0
- package/dist/RTSPCameraProvider.d.ts.map +1 -1
- package/dist/RTSPCameraProvider.js +3 -1
- package/dist/RTSPCameraProvider.js.map +1 -1
- package/dist/index.d.ts +4 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +14 -1
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
|
@@ -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
|