@trillboards/edge-platform-rtsp 0.2.4 → 0.2.5

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,1092 @@
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.RTSPStreamCameraProvider = exports.streamSessionStatsFor = exports.__resetStreamAdmissionForTests = exports.FrameRing = exports.MjpegFrameSplitter = exports.jpegFrameEnd = exports.JPEG_MALFORMED = exports.JPEG_NEED_MORE = exports.RtspStreamStaleError = exports.RtspStreamAdmissionError = 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
+ const ffmpegStderr_1 = require("./ffmpegStderr");
33
+ /**
34
+ * RTSPStreamCameraProvider — video frames off an RTSP camera/NVR channel as a
35
+ * LONG-LIVED ffmpeg session feeding a bounded in-memory ring, so that a LOOK
36
+ * becomes a memory read instead of an RTSP handshake.
37
+ *
38
+ * ── THE PROBLEM THIS EXISTS TO REMOVE, AND IT IS ONE MEASUREMENT ───────────
39
+ *
40
+ * `RTSPCameraProvider.buildCaptureArgs` spawns ONE ffmpeg per grab with
41
+ * `-frames:v 1`, so every look pays a process start, a full RTSP
42
+ * DESCRIBE/SETUP/PLAY handshake, and a wait for the camera's next keyframe
43
+ * before anything can be decoded. Measured through that provider against
44
+ * mediamtx re-streaming a real CCTV clip at the documented degraded profile
45
+ * (640x360 / 399 kbps): p50 **1,986-2,025 ms** per grab at a 1-2 s keyframe
46
+ * interval, 4,005 ms at 4 s. The control — the SAME ffmpeg args against a local
47
+ * file, so spawn + decode + scale + pad + JPEG encode with no stream — is
48
+ * **20-30 ms**. So ~99% of a look is session SETUP, not imaging.
49
+ *
50
+ * That is the whole catch-rate problem. An event is catchable only if a look
51
+ * lands inside it, so catch rate is bounded by `E[min(d/T,1)]` for a look
52
+ * cadence `T`; the Brief group (median ~2.4 s, heavy sub-second tail) needs
53
+ * **0.75 s** to clear the 90% target, which is 2.7x BELOW what one grab
54
+ * physically costs. `connectorCadence.ts` says so in as many words: "Closing
55
+ * that gap needs a persistent RTSP session — one long-lived ffmpeg per feed
56
+ * instead of one per grab — which is an architecture change, not a number."
57
+ * This is that change.
58
+ *
59
+ * Measured through THIS provider against the same rig: the handshake is paid
60
+ * ONCE at open, and thereafter frames arrive every ~250 ms (`streamFps` 4) and
61
+ * `getFrame()` returns in **microseconds** because it reads the newest frame
62
+ * out of memory. See `scripts/measure-persistent-capture.mjs` for the driver
63
+ * and the committed numbers.
64
+ *
65
+ * ── PROCESS COUNT GOES DOWN, NOT UP. SAY IT OUT LOUD ───────────────────────
66
+ *
67
+ * A reviewer reads "persistent session" as "more load on the recorder". It is
68
+ * the opposite, and the incident this package is written around is the reason.
69
+ * A 32-channel NVR once accumulated **28 simultaneous ffmpeg children** because
70
+ * one-shot pulls started outliving the cadence, and the recorder answered with
71
+ * rotating timeouts, CSeq mismatches and cameras flapping into "needs
72
+ * attention" — which is why `CaptureAdmission` caps at 2 concurrent pulls per
73
+ * physical recorder
74
+ * (.claude/lessons/2026-08-17-rtsp-session-admission-and-frame-integrity.md).
75
+ *
76
+ * Compare the two designs on the SAME 16-feed recorder:
77
+ *
78
+ * per-grab (today) 16 feeds x 1 look / 16 s = 1.0 RTSP session SETUP per
79
+ * second, forever — 3,600 DESCRIBE/SETUP/PLAY/TEARDOWN
80
+ * cycles per hour and 3,600 process spawns per hour, with
81
+ * 2 concurrent at any instant and an unbounded pile-up
82
+ * under load (the incident).
83
+ *
84
+ * persistent 16 session setups TOTAL, then nothing. 16 processes,
85
+ * bounded by construction, and 16 concurrent substream
86
+ * readers — which is exactly what the recorder's OWN
87
+ * client app opens for a 16-up grid view, i.e. its designed
88
+ * workload.
89
+ *
90
+ * So the churn goes to zero and the process count per hour falls by ~225x. The
91
+ * one number that goes UP is steady-state concurrent sessions (2 -> N), and
92
+ * that is why the persistent lane is bounded per recorder and degrades rather
93
+ * than fails — see ADMISSION below. It is also the honest limit of what was
94
+ * measurable here: mediamtx will serve any number of readers, so the ceiling of
95
+ * a real consumer NVR is NOT established by this work and the default is a
96
+ * stated judgement, not a measurement.
97
+ *
98
+ * ── ADMISSION: A SECOND LANE, AND IT REFUSES RATHER THAN QUEUES ────────────
99
+ *
100
+ * A long-lived session cannot be admitted from `CaptureAdmission`: a permanent
101
+ * holder of a 2-slot pool is a 50% permanent tax on frame capture for that
102
+ * recorder, and two of them deadlock it entirely. So persistent sessions are
103
+ * admitted from `streamAdmissionBySource`, keyed by the SAME
104
+ * `captureSourceKey(url)` — host:port, credentials and channel path
105
+ * deliberately excluded so 32 channels of one NVR share one budget — counted in
106
+ * their OWN pool with its own cap. Exactly the split `RTSPAudioProvider` uses,
107
+ * for exactly the same reason.
108
+ *
109
+ * The lane never queues. A queued video session would be admitted minutes later
110
+ * against a scene nobody is asking about any more, and a feed waiting on a slot
111
+ * is a feed that is not sensing.
112
+ *
113
+ * ── DEGRADE, NEVER FAIL. THIS IS THE PROPERTY THAT LETS THIS SHIP ──────────
114
+ *
115
+ * When the persistent session cannot be had — the recorder's lane is full, or
116
+ * the recorder refuses the session, or ffmpeg cannot hold it open — this
117
+ * provider does NOT throw. It falls back to an internal `RTSPCameraProvider`
118
+ * and runs the per-grab path, which is precisely what the connector does today.
119
+ * So no camera that works today can be broken by this change; the worst case is
120
+ * that it is no faster than it was.
121
+ *
122
+ * The degrade is a REPORTED STATE, never a hidden branch: `getStats().mode` is
123
+ * `'persistent' | 'per_grab'`, `degradedReason` says which of the three causes
124
+ * fired, and it is logged at warn. A silent downgrade would be the same defect
125
+ * as a silent drop — it would move the problem somewhere nobody looks.
126
+ *
127
+ * ── A DEAD STREAM MUST BE LOUD, AND A PERSISTENT SESSION MAKES THAT HARDER ─
128
+ *
129
+ * The connector's recurring defect is a signal that cannot report its own
130
+ * failure: a recorder that accepts a connection and then stops sending frames
131
+ * is ~50 minutes of beacon silence rendered as "connector not running". A
132
+ * persistent session makes that MORE likely, because the process is still
133
+ * alive and the socket is still open. Three things make it loud instead:
134
+ *
135
+ * 1. `getFrame()` NEVER returns a frame it has already returned. It waits up
136
+ * to `frameWaitMs` for a genuinely new one and then throws
137
+ * `RtspStreamStaleError` carrying the age. Handing back a stale frame is
138
+ * the failure mode, not the fallback: it would keep stamping the camera's
139
+ * `lastFrameAtMs`, and a frozen camera would report as healthy forever.
140
+ * 2. The error message is worded so `classifyRtspFailureClass` reads it as
141
+ * `no_frames` — the recorder answered, no video arrived — and NOT as a
142
+ * reachability class, which would wrongly implicate the LAN grant. The
143
+ * ffmpeg stderr summary is deliberately kept OUT of that message and put
144
+ * in `getStats().lastErrorMessage`, so the classification is deterministic
145
+ * instead of depending on which warning ffmpeg happened to print.
146
+ * 3. `getStats()` DERIVES `frameAgeMs`, `running`, `mode` and the counters
147
+ * live on every call. There is no cached capability boolean. On the
148
+ * Android fleet `cap_audio_classification` is false FLEET-WIDE, including
149
+ * on devices shipping live classifications, because a flag was latched at
150
+ * boot from a value that was still "probing" and nothing ever re-wrote it
151
+ * (docs/runbooks/audio-sensing-substrate.md).
152
+ *
153
+ * A CLEAN EXIT IS A FAULT HERE. `code === 0` means success on the one-shot
154
+ * path; on a persistent session it means the stream ended, which is never what
155
+ * we asked for. Measured against the rig: killing the publisher made ffmpeg
156
+ * exit 0 within 26 ms, and freezing it (session held open, no RTP) made ffmpeg
157
+ * exit 0 after ~10 s with "Failed reading RTSP data: End of file". Both are
158
+ * restarts here, both are counted, and neither is ever silent.
159
+ *
160
+ * ── BOUNDED MEMORY, ENFORCED ON ADMISSION ─────────────────────────────────
161
+ *
162
+ * `VlmCandidateBuffer` gets this right and this copies its discipline: the
163
+ * ceiling is checked on the way IN, in exact bytes, and every eviction is
164
+ * COUNTED. A ring that grows under back-pressure is an OOM on a 7 GB box.
165
+ *
166
+ * There are TWO bounds because there are two places bytes accumulate, and the
167
+ * second one is the easy one to miss: the ring holds complete frames, but the
168
+ * SPLITTER holds a partially-received one. A stream that emits an SOI and then
169
+ * never an EOI — a corrupt feed, a mid-frame protocol change — would grow that
170
+ * accumulator without limit. `maxFrameBytes` bounds it, and an overflow resyncs
171
+ * and is counted as `oversizeFrames`.
172
+ *
173
+ * ── JPEG ONLY, ON PURPOSE ─────────────────────────────────────────────────
174
+ *
175
+ * `RTSPCameraProvider` supports `outputFormat: 'rgb24'` for the ONNX face
176
+ * zoo. A persistent rgb24 stream is 640x480x3 = 921,600 bytes per frame, i.e.
177
+ * 3.7 MB/s per camera at 4 fps and ~59 MB/s across 16 feeds, through pipes and
178
+ * into a ring. The same stream as MJPEG is ~0.12 MB/s per camera (measured:
179
+ * 29.6 KB/frame at q:v 11 on the degraded profile). So this provider is JPEG
180
+ * only and the rgb24 zoo keeps the one-shot path, which is also the right split
181
+ * by product: the zoo is the DOOH audience rail, and the look-cadence problem
182
+ * is the CCTV sensing rail.
183
+ *
184
+ * ── RATE LIMITING WITHOUT FABRICATION ─────────────────────────────────────
185
+ *
186
+ * The output is rate-limited with the `fps` filter rather than by an output
187
+ * `-r`, and the difference matters for constraint 3. The `fps` filter is driven
188
+ * BY ARRIVING INPUT FRAMES: when no frames arrive it emits nothing. Verified
189
+ * against the rig — freezing the source produced zero further output, so a
190
+ * frozen camera cannot manufacture "fresh" frames and defeat the staleness
191
+ * signal. Decode cost is unaffected by the filter (ffmpeg must decode the
192
+ * stream to produce any frame at all); what `streamFps` bounds is scale, pad,
193
+ * JPEG encode and pipe traffic.
194
+ *
195
+ * ── SECRET HYGIENE, INHERITED ─────────────────────────────────────────────
196
+ *
197
+ * RTSP URLs carry passwords. Exactly as the other two providers do, the URL is
198
+ * written to a 0600 ffconcat file and only the temp path reaches argv, so a
199
+ * password never appears in `ps` output; stderr is scrubbed through
200
+ * `sanitizeStreamUrlForLog` before it can reach a log line.
201
+ */
202
+ /** The recorder's persistent-session lane is full. Degrade, never queue. */
203
+ class RtspStreamAdmissionError extends Error {
204
+ constructor(sourceKey, limit) {
205
+ super(`RTSP stream session refused: recorder ${sourceKey} already runs ${limit} persistent session(s).`);
206
+ this.code = 'RTSP_STREAM_SESSION_LIMIT';
207
+ this.name = 'RtspStreamAdmissionError';
208
+ }
209
+ }
210
+ exports.RtspStreamAdmissionError = RtspStreamAdmissionError;
211
+ /**
212
+ * No NEW frame arrived within the deadline.
213
+ *
214
+ * The wording is load bearing. `classifyRtspFailureClass` tests, in order,
215
+ * auth -> nvr-busy -> unreachable -> timeout -> decode -> no-frames, so this
216
+ * message must avoid every earlier class's vocabulary ("timeout", "timed out",
217
+ * "refused", "corrupt", "eof") and must contain "no frame". A stale persistent
218
+ * session is not a reachability failure — the recorder answered and the socket
219
+ * is up — and misclassifying it as one would send the health surface to
220
+ * `local_network_denied` and blame the operator's macOS LAN grant for a camera
221
+ * that is plainly reachable.
222
+ */
223
+ class RtspStreamStaleError extends Error {
224
+ constructor(url, ageMs, restarts) {
225
+ super(`RTSP stream produced no frame for ${Math.round(ageMs)}ms ` +
226
+ `(${restarts} session restart(s)): ${(0, RTSPCameraProvider_1.sanitizeStreamUrlForLog)(url)}`);
227
+ this.code = 'RTSP_STREAM_STALE';
228
+ this.name = 'RtspStreamStaleError';
229
+ this.ageMs = ageMs;
230
+ }
231
+ }
232
+ exports.RtspStreamStaleError = RtspStreamStaleError;
233
+ const DEFAULT_STREAM_FPS = 4;
234
+ const DEFAULT_TIMEOUT_US = 12000000;
235
+ /**
236
+ * Persistent sessions allowed per physical recorder.
237
+ *
238
+ * A STATED JUDGEMENT, not a measurement, and it is flagged as such because the
239
+ * measurement is not available here: mediamtx serves any number of readers, so
240
+ * the rig cannot find a real NVR's ceiling. The reasoning is grid-view parity —
241
+ * a 16-channel recorder's own client app opens 16 concurrent substream readers
242
+ * for its 16-up view, so 16 concurrent readers is the workload the box is built
243
+ * for, whereas 3,600 session setups an hour is not.
244
+ *
245
+ * A 32-channel recorder therefore gets 16 persistent sessions and 16 feeds
246
+ * degraded to the per-grab path they run today — loudly, via
247
+ * `getStats().degradedReason` — rather than 32 sessions nobody has measured.
248
+ * Raise it only with a measurement against the real recorder, exactly as
249
+ * `RTSPAudioProvider.maxAudioSessionsPerSource` says.
250
+ */
251
+ const DEFAULT_MAX_STREAM_SESSIONS_PER_SOURCE = 16;
252
+ /**
253
+ * Threads ffmpeg may use for this session.
254
+ *
255
+ * ONE, and it is faster as well as smaller — which is the opposite of the
256
+ * instinct. Measured against the rig (640x360 / 399 kbps substream, 25 s,
257
+ * one feed), default threading versus `-threads 1`:
258
+ *
259
+ * default RSS 89.6 MB first frame 3,156 ms 88 frames
260
+ * threads 1 RSS 26.8 MB first frame 1,690 ms 97 frames
261
+ *
262
+ * RSS falls 3.3x and the first frame arrives 1.5 s sooner, because frame-level
263
+ * threading buys parallelism by holding a PIPELINE of frames in flight — which
264
+ * costs memory per thread and adds a multi-frame delay before anything comes
265
+ * out. Neither is worth having here: a 640x360 substream decodes far faster
266
+ * than real time on one thread, and latency is the entire product of this file.
267
+ *
268
+ * It is also the difference between a 16-feed connector costing ~1.4 GB of
269
+ * ffmpeg RSS and costing ~0.4 GB, on a box the runbooks size at 7 GB.
270
+ *
271
+ * A main-stream (1080p+) feed is a different measurement and this is a config
272
+ * knob for that reason; the connector runs substreams.
273
+ */
274
+ const DEFAULT_DECODER_THREADS = 1;
275
+ /** Complete frames held. The newest is what a look reads; the rest are slack. */
276
+ const DEFAULT_RING_MAX_FRAMES = 4;
277
+ /** Total bytes of complete frames held. ~34x the measured 29.6 KB frame x 4. */
278
+ const DEFAULT_RING_MAX_BYTES = 4 * 1024 * 1024;
279
+ /** Ceiling on ONE partially-received frame, so a missing EOI cannot grow. */
280
+ const DEFAULT_MAX_FRAME_BYTES = 2 * 1024 * 1024;
281
+ /** Session-start attempts before degrading. Lower than the per-grab path's 4
282
+ * because the per-grab provider behind this one does its own validation. */
283
+ const DEFAULT_OPEN_VALIDATION_ATTEMPTS = 2;
284
+ const DEFAULT_RESTART_DELAY_MS = 1000;
285
+ const DEFAULT_MAX_RESTART_DELAY_MS = 60000;
286
+ /** Multiple of the frame interval `getFrame` waits before calling it stale. */
287
+ const STALE_DEADLINE_FRAME_MULTIPLE = 6;
288
+ /** Floor on that deadline, so a fast `streamFps` cannot make it hair-trigger. */
289
+ const MIN_STALE_DEADLINE_MS = 3000;
290
+ // ---------------------------------------------------------------------------
291
+ // MJPEG framing
292
+ // ---------------------------------------------------------------------------
293
+ /** A complete JPEG ends at this offset; -1 = need more bytes; -2 = malformed. */
294
+ exports.JPEG_NEED_MORE = -1;
295
+ exports.JPEG_MALFORMED = -2;
296
+ /**
297
+ * Offset just past the EOI of the JPEG starting at `start`, by walking JPEG
298
+ * segments — NOT by scanning for the `FF D9` byte pair.
299
+ *
300
+ * A plain byte scan is wrong and the failure is silent. Marker segments carry
301
+ * arbitrary payloads (a DQT's 64 quantisation values, a DHT's code lengths, an
302
+ * APPn's contents), any of which may contain `FF D9`, and a scanner that found
303
+ * one would cut the frame short and hand a truncated JPEG downstream — which
304
+ * `RTSPCameraProvider` already refuses on the one-shot path precisely because a
305
+ * truncated JPEG renders as grey and becomes alert evidence.
306
+ *
307
+ * So: step over each segment by its declared length until SOS, then scan the
308
+ * entropy-coded data honouring JPEG byte stuffing (`FF 00` is a literal `FF`,
309
+ * `FF D0`-`FF D7` are restart markers, `FF FF` is fill) until a real marker
310
+ * appears. In ffmpeg's baseline MJPEG output that marker is EOI.
311
+ */
312
+ function jpegFrameEnd(buf, start = 0) {
313
+ if (buf.length < start + 4)
314
+ return exports.JPEG_NEED_MORE;
315
+ if (buf[start] !== 0xff || buf[start + 1] !== 0xd8)
316
+ return exports.JPEG_MALFORMED;
317
+ let i = start + 2;
318
+ while (i + 1 < buf.length) {
319
+ if (buf[i] !== 0xff)
320
+ return exports.JPEG_MALFORMED;
321
+ // Fill bytes: any number of 0xFF may precede a marker code.
322
+ while (i + 1 < buf.length && buf[i + 1] === 0xff)
323
+ i += 1;
324
+ if (i + 1 >= buf.length)
325
+ return exports.JPEG_NEED_MORE;
326
+ const marker = buf[i + 1];
327
+ if (marker === 0xd9)
328
+ return i + 2; // EOI
329
+ if (marker === 0x01 || (marker >= 0xd0 && marker <= 0xd7)) {
330
+ i += 2; // standalone marker, no payload
331
+ continue;
332
+ }
333
+ if (i + 3 >= buf.length)
334
+ return exports.JPEG_NEED_MORE;
335
+ const len = buf.readUInt16BE(i + 2);
336
+ if (len < 2)
337
+ return exports.JPEG_MALFORMED;
338
+ if (marker === 0xda) {
339
+ // SOS — entropy-coded data follows the header, unlengthed.
340
+ let j = i + 2 + len;
341
+ while (j + 1 < buf.length) {
342
+ if (buf[j] !== 0xff) {
343
+ j += 1;
344
+ continue;
345
+ }
346
+ const next = buf[j + 1];
347
+ if (next === 0xff) {
348
+ j += 1; // fill
349
+ continue;
350
+ }
351
+ if (next === 0x00 || (next >= 0xd0 && next <= 0xd7)) {
352
+ j += 2; // stuffed FF, or a restart marker
353
+ continue;
354
+ }
355
+ break; // a real marker — resume the segment walk here
356
+ }
357
+ if (j + 1 >= buf.length)
358
+ return exports.JPEG_NEED_MORE;
359
+ i = j;
360
+ continue;
361
+ }
362
+ i = i + 2 + len;
363
+ }
364
+ return exports.JPEG_NEED_MORE;
365
+ }
366
+ exports.jpegFrameEnd = jpegFrameEnd;
367
+ /**
368
+ * Cuts a byte stream of concatenated JPEGs into whole frames, with a HARD
369
+ * ceiling on the partially-received one.
370
+ *
371
+ * The ceiling is the bound people forget: the ring is bounded, but the thing
372
+ * feeding it is an accumulator, and an accumulator with no cap is the same leak
373
+ * one layer up. On overflow the accumulator is dropped and the splitter resyncs
374
+ * to the next SOI, and the event is COUNTED rather than swallowed.
375
+ */
376
+ class MjpegFrameSplitter {
377
+ constructor(maxFrameBytes) {
378
+ this.maxFrameBytes = maxFrameBytes;
379
+ this.acc = Buffer.alloc(0);
380
+ this.oversize = 0;
381
+ this.resyncs = 0;
382
+ }
383
+ getOversizeFrames() {
384
+ return this.oversize;
385
+ }
386
+ getResyncs() {
387
+ return this.resyncs;
388
+ }
389
+ getPendingBytes() {
390
+ return this.acc.length;
391
+ }
392
+ reset() {
393
+ this.acc = Buffer.alloc(0);
394
+ }
395
+ /** Append a chunk and return every complete frame it completed, in order. */
396
+ push(chunk) {
397
+ this.acc = this.acc.length === 0 ? chunk : Buffer.concat([this.acc, chunk]);
398
+ const out = [];
399
+ for (;;) {
400
+ const end = jpegFrameEnd(this.acc, 0);
401
+ if (end === exports.JPEG_NEED_MORE) {
402
+ if (this.acc.length > this.maxFrameBytes) {
403
+ // Enforced on ADMISSION: the accumulator never exceeds its ceiling
404
+ // and is then reconciled — it is dropped the moment it would.
405
+ this.oversize += 1;
406
+ this.resyncToNextSoi(1);
407
+ continue;
408
+ }
409
+ break;
410
+ }
411
+ if (end === exports.JPEG_MALFORMED) {
412
+ this.resyncs += 1;
413
+ if (!this.resyncToNextSoi(1))
414
+ break;
415
+ continue;
416
+ }
417
+ out.push(this.acc.subarray(0, end));
418
+ this.acc = this.acc.subarray(end);
419
+ if (this.acc.length === 0)
420
+ break;
421
+ }
422
+ return out;
423
+ }
424
+ /** Drop bytes up to the next SOI. Returns false when there is no next SOI. */
425
+ resyncToNextSoi(from) {
426
+ for (let i = from; i + 1 < this.acc.length; i += 1) {
427
+ if (this.acc[i] === 0xff && this.acc[i + 1] === 0xd8) {
428
+ this.acc = this.acc.subarray(i);
429
+ return true;
430
+ }
431
+ }
432
+ // Keep the last byte: an SOI may straddle the chunk boundary.
433
+ this.acc = this.acc.length > 0 ? this.acc.subarray(this.acc.length - 1) : this.acc;
434
+ return false;
435
+ }
436
+ }
437
+ exports.MjpegFrameSplitter = MjpegFrameSplitter;
438
+ /**
439
+ * Bounded newest-first frame ring. Byte- and count-bounded, enforced when a
440
+ * frame is ADMITTED, and every eviction counted — `VlmCandidateBuffer`'s
441
+ * discipline, for the same reason: a silent eviction moves a lost frame from
442
+ * one invisible place to another.
443
+ */
444
+ class FrameRing {
445
+ constructor(maxFrames, maxBytes) {
446
+ this.maxFrames = maxFrames;
447
+ this.maxBytes = maxBytes;
448
+ this.frames = [];
449
+ this.bytes = 0;
450
+ this.evicted = 0;
451
+ this.rejected = 0;
452
+ this.seq = 0;
453
+ }
454
+ /** Admit a frame. Returns its sequence number, or null if it cannot fit. */
455
+ push(bytes, atMs) {
456
+ if (bytes.length > this.maxBytes) {
457
+ // A single frame larger than the whole budget can never be admitted, and
458
+ // evicting the ring to make room for it would trade every frame we have
459
+ // for one we cannot keep either.
460
+ this.rejected += 1;
461
+ return null;
462
+ }
463
+ while (this.frames.length > 0 &&
464
+ (this.frames.length + 1 > this.maxFrames || this.bytes + bytes.length > this.maxBytes)) {
465
+ const oldest = this.frames.shift();
466
+ this.bytes -= oldest.bytes.length;
467
+ this.evicted += 1;
468
+ }
469
+ this.seq += 1;
470
+ this.frames.push({ bytes, atMs, seq: this.seq });
471
+ this.bytes += bytes.length;
472
+ return this.seq;
473
+ }
474
+ newest() {
475
+ return this.frames.length ? this.frames[this.frames.length - 1] : null;
476
+ }
477
+ getBytes() {
478
+ return this.bytes;
479
+ }
480
+ getFrames() {
481
+ return this.frames.length;
482
+ }
483
+ getEvicted() {
484
+ return this.evicted;
485
+ }
486
+ getRejected() {
487
+ return this.rejected;
488
+ }
489
+ clear() {
490
+ this.frames = [];
491
+ this.bytes = 0;
492
+ }
493
+ }
494
+ exports.FrameRing = FrameRing;
495
+ // ---------------------------------------------------------------------------
496
+ // Per-recorder admission for LONG-LIVED video sessions
497
+ // ---------------------------------------------------------------------------
498
+ /**
499
+ * Deliberately a different pool from `CaptureAdmission` AND from
500
+ * `AudioSessionAdmission`: same key, three separate budgets. `tryAcquire` only
501
+ * — this lane never queues.
502
+ */
503
+ class StreamSessionAdmission {
504
+ constructor(limit) {
505
+ this.active = 0;
506
+ this.limit = limit;
507
+ }
508
+ /** Tighten only, matching the other two lanes: the most cautious caller wins. */
509
+ tightenLimit(limit) {
510
+ this.limit = Math.min(this.limit, limit);
511
+ }
512
+ getLimit() {
513
+ return this.limit;
514
+ }
515
+ getActive() {
516
+ return this.active;
517
+ }
518
+ tryAcquire() {
519
+ if (this.active >= this.limit)
520
+ return null;
521
+ this.active += 1;
522
+ let released = false;
523
+ return () => {
524
+ if (released)
525
+ return;
526
+ released = true;
527
+ this.active = Math.max(0, this.active - 1);
528
+ };
529
+ }
530
+ }
531
+ const streamAdmissionBySource = new Map();
532
+ function streamAdmissionFor(streamUrl, limit) {
533
+ const key = (0, RTSPCameraProvider_1.captureSourceKey)(streamUrl);
534
+ if (!key)
535
+ return null;
536
+ const existing = streamAdmissionBySource.get(key);
537
+ if (existing) {
538
+ existing.tightenLimit(limit);
539
+ return existing;
540
+ }
541
+ const admission = new StreamSessionAdmission(limit);
542
+ streamAdmissionBySource.set(key, admission);
543
+ return admission;
544
+ }
545
+ /** Test seam: forget every recorder's persistent-session budget. */
546
+ function __resetStreamAdmissionForTests() {
547
+ streamAdmissionBySource.clear();
548
+ }
549
+ exports.__resetStreamAdmissionForTests = __resetStreamAdmissionForTests;
550
+ /** Live persistent-session occupancy for a recorder, for diagnostics. */
551
+ function streamSessionStatsFor(streamUrl) {
552
+ const key = (0, RTSPCameraProvider_1.captureSourceKey)(streamUrl);
553
+ if (!key)
554
+ return null;
555
+ const admission = streamAdmissionBySource.get(key);
556
+ if (!admission)
557
+ return null;
558
+ return { key, active: admission.getActive(), limit: admission.getLimit() };
559
+ }
560
+ exports.streamSessionStatsFor = streamSessionStatsFor;
561
+ /**
562
+ * One instance per feed. Implements the SAME `CameraProvider` interface as
563
+ * `RTSPCameraProvider`, so every consumer is unchanged — but `getFrame()` reads
564
+ * the newest frame out of the ring the long-lived session is filling, rather
565
+ * than spawning a process and handshaking a stream per call.
566
+ */
567
+ class RTSPStreamCameraProvider {
568
+ constructor(config) {
569
+ this.opened = false;
570
+ this.mode = 'persistent';
571
+ this.degradedReason = null;
572
+ this.fallback = null;
573
+ this.proc = null;
574
+ this.releaseAdmission = null;
575
+ this.restartTimer = null;
576
+ this.cleanupInput = null;
577
+ this.startingUp = false;
578
+ this.sessionStarts = 0;
579
+ this.restarts = 0;
580
+ this.framesDecoded = 0;
581
+ this.framesServed = 0;
582
+ this.staleReads = 0;
583
+ this.lastFrameAtMs = null;
584
+ this.lastServedSeq = 0;
585
+ this.lastErrorMessage = null;
586
+ /** Resolvers waiting for the next frame. Woken by `admitFrame`. */
587
+ this.frameWaiters = [];
588
+ if (!config?.rtspUrl)
589
+ throw new Error('rtspUrl is required for RTSPStreamCameraProvider');
590
+ this.rtspUrl = config.rtspUrl;
591
+ this.width = config.width ?? 640;
592
+ this.height = config.height ?? 480;
593
+ this.crop = config.crop;
594
+ this.transport = config.transport ?? 'tcp';
595
+ this.timeoutUs = config.timeoutUs ?? DEFAULT_TIMEOUT_US;
596
+ this.ffmpegPath = config.ffmpegPath ?? 'ffmpeg';
597
+ this.ffmpegMajorVersion = config.ffmpegMajorVersion ?? 6;
598
+ this.jpegQuality = config.jpegQuality ?? 70;
599
+ this.streamFps = Math.max(0.1, Number(config.streamFps ?? DEFAULT_STREAM_FPS));
600
+ this.frameIntervalMs = 1000 / this.streamFps;
601
+ this.decoderThreads = Math.max(1, Math.trunc(config.decoderThreads ?? DEFAULT_DECODER_THREADS));
602
+ this.maxStreamSessionsPerSource = Math.max(1, Math.trunc(config.maxStreamSessionsPerSource ?? DEFAULT_MAX_STREAM_SESSIONS_PER_SOURCE));
603
+ this.frameWaitMs = Math.max(1, Math.trunc(config.frameWaitMs ??
604
+ Math.max(MIN_STALE_DEADLINE_MS, STALE_DEADLINE_FRAME_MULTIPLE * this.frameIntervalMs)));
605
+ this.openValidationAttempts = Math.max(1, Math.trunc(config.openValidationAttempts ?? DEFAULT_OPEN_VALIDATION_ATTEMPTS));
606
+ this.restartDelayMs = Math.max(0, config.restartDelayMs ?? DEFAULT_RESTART_DELAY_MS);
607
+ this.maxRestartDelayMs = Math.max(this.restartDelayMs, config.maxRestartDelayMs ?? DEFAULT_MAX_RESTART_DELAY_MS);
608
+ this.currentRestartDelay = this.restartDelayMs;
609
+ this.persistentRequested = config.persistent !== false;
610
+ this.spawnFn = config.spawnFn ?? child_process_1.spawn;
611
+ this.now = config.now ?? Date.now;
612
+ this.onLog = config.onLog;
613
+ this.ring = new FrameRing(Math.max(1, Math.trunc(config.ringMaxFrames ?? DEFAULT_RING_MAX_FRAMES)), Math.max(1, Math.trunc(config.ringMaxBytes ?? DEFAULT_RING_MAX_BYTES)));
614
+ this.splitter = new MjpegFrameSplitter(Math.max(1, Math.trunc(config.maxFrameBytes ?? DEFAULT_MAX_FRAME_BYTES)));
615
+ const fallbackConfig = {
616
+ ...(config.fallbackConfig ?? {}),
617
+ rtspUrl: this.rtspUrl,
618
+ width: this.width,
619
+ height: this.height,
620
+ crop: this.crop,
621
+ transport: this.transport,
622
+ timeoutUs: this.timeoutUs,
623
+ ffmpegPath: this.ffmpegPath,
624
+ outputFormat: 'jpeg',
625
+ jpegQuality: this.jpegQuality,
626
+ ...(config.streamUrlResolver ? { streamUrlResolver: config.streamUrlResolver } : {}),
627
+ };
628
+ const make = config.fallbackFactory ?? ((c) => new RTSPCameraProvider_1.RTSPCameraProvider(c));
629
+ this.buildFallback = () => make(fallbackConfig);
630
+ }
631
+ // ── CameraProvider ───────────────────────────────────────────────────────
632
+ /**
633
+ * Take a recorder session slot and start streaming. NEVER throws because the
634
+ * persistent path was unavailable — it degrades to the per-grab provider and
635
+ * says so. It throws only when the per-grab path ALSO fails, which is exactly
636
+ * what the connector does today, so no working camera can be broken here.
637
+ */
638
+ async open(_deviceId) {
639
+ if (this.opened)
640
+ return;
641
+ // A previous open() degraded and left a per-grab provider behind. Re-opening
642
+ // is the manager's reconnect path, and it is also the ONLY chance to retake
643
+ // a persistent session from a recorder that has since rebooted, freed a
644
+ // slot, or come back on the network. Retrying is therefore the re-arm — a
645
+ // provider that degraded once and could never come back would be the Ember
646
+ // permanent-retirement shape (see handleSessionEnd) at the capture layer.
647
+ // Drop the old provider rather than leaking one per reconnect.
648
+ if (this.fallback) {
649
+ const previous = this.fallback;
650
+ this.fallback = null;
651
+ try {
652
+ await previous.close();
653
+ }
654
+ catch {
655
+ /* a closing fallback must not be able to block a re-open */
656
+ }
657
+ }
658
+ if (!this.persistentRequested) {
659
+ await this.degradeTo('disabled');
660
+ return;
661
+ }
662
+ const admission = streamAdmissionFor(this.rtspUrl, this.maxStreamSessionsPerSource);
663
+ if (admission) {
664
+ const release = admission.tryAcquire();
665
+ if (!release) {
666
+ this.lastErrorMessage = new RtspStreamAdmissionError((0, RTSPCameraProvider_1.captureSourceKey)(this.rtspUrl) ?? 'unknown', admission.getLimit()).message;
667
+ await this.degradeTo('session_limit');
668
+ return;
669
+ }
670
+ this.releaseAdmission = release;
671
+ }
672
+ this.opened = true;
673
+ this.mode = 'persistent';
674
+ this.degradedReason = null;
675
+ this.currentRestartDelay = this.restartDelayMs;
676
+ this.startingUp = true;
677
+ let lastErr;
678
+ try {
679
+ for (let attempt = 1; attempt <= this.openValidationAttempts; attempt += 1) {
680
+ try {
681
+ await this.startSession();
682
+ return;
683
+ }
684
+ catch (err) {
685
+ lastErr = err;
686
+ this.stopProcess();
687
+ if (attempt < this.openValidationAttempts && this.restartDelayMs > 0) {
688
+ await new Promise((resolve) => setTimeout(resolve, this.restartDelayMs));
689
+ }
690
+ if (!this.opened)
691
+ break; // closed underneath us
692
+ }
693
+ }
694
+ }
695
+ finally {
696
+ this.startingUp = false;
697
+ }
698
+ // The persistent session could not be held. Give the recorder slot straight
699
+ // back so a feed that CAN hold one is not denied by a feed that cannot, and
700
+ // run the path the connector runs today.
701
+ this.opened = false;
702
+ this.stopProcess();
703
+ this.releaseSlot();
704
+ this.lastErrorMessage = (0, RTSPCameraProvider_1.sanitizeStreamUrlForLog)(lastErr instanceof Error ? lastErr.message : String(lastErr ?? 'stream session failed'));
705
+ await this.degradeTo('session_unavailable');
706
+ }
707
+ /**
708
+ * The newest frame this feed has produced AND NOT YET SERVED.
709
+ *
710
+ * On the persistent path this is a memory read — microseconds — when a fresh
711
+ * frame is in hand, which at `streamFps` 4 against a 500 ms look cadence is
712
+ * every time. When it is not, the call waits up to `frameWaitMs` and is woken
713
+ * by the next arrival; a wait that expires is a STALE STREAM and throws.
714
+ *
715
+ * Never returning a repeat is the whole loudness guarantee. Handing back the
716
+ * same frame would report a frozen camera as healthy forever, and would also
717
+ * feed the motion detector a constant — which is the documented `file://`
718
+ * fixture trap (`-frames:v 1` with no `-ss` returns frame 0 forever), where
719
+ * the gate calibrates against a constant and settles into `no_motion`
720
+ * permanently.
721
+ */
722
+ async getFrame() {
723
+ if (this.fallback)
724
+ return this.fallback.getFrame();
725
+ if (!this.opened)
726
+ throw new Error('Camera not opened. Call open() first.');
727
+ const fresh = this.takeFreshFrame();
728
+ if (fresh)
729
+ return fresh;
730
+ const arrived = await this.waitForFrame(this.frameWaitMs);
731
+ if (arrived) {
732
+ const next = this.takeFreshFrame();
733
+ if (next)
734
+ return next;
735
+ }
736
+ this.staleReads += 1;
737
+ const newest = this.ring.newest();
738
+ const ageMs = newest ? this.now() - newest.atMs : this.frameWaitMs;
739
+ throw new RtspStreamStaleError(this.rtspUrl, ageMs, this.restarts);
740
+ }
741
+ getResolution() {
742
+ return { width: this.width, height: this.height };
743
+ }
744
+ getFps() {
745
+ return this.streamFps;
746
+ }
747
+ isOpen() {
748
+ if (this.fallback)
749
+ return this.fallback.isOpen();
750
+ return this.opened;
751
+ }
752
+ async close() {
753
+ this.opened = false;
754
+ if (this.restartTimer) {
755
+ clearTimeout(this.restartTimer);
756
+ this.restartTimer = null;
757
+ }
758
+ this.stopProcess();
759
+ this.releaseSlot();
760
+ this.ring.clear();
761
+ this.splitter.reset();
762
+ this.wakeWaiters();
763
+ if (this.fallback) {
764
+ await this.fallback.close();
765
+ this.fallback = null;
766
+ }
767
+ }
768
+ /**
769
+ * Every field DERIVED on each call. There is no cached capability boolean
770
+ * here and one must never be added — see the header on
771
+ * `cap_audio_classification`.
772
+ */
773
+ getStats() {
774
+ const newest = this.ring.newest();
775
+ return {
776
+ opened: this.isOpen(),
777
+ mode: this.mode,
778
+ degradedReason: this.degradedReason,
779
+ running: this.proc !== null,
780
+ bufferedFrames: this.ring.getFrames(),
781
+ bufferedBytes: this.ring.getBytes(),
782
+ pendingBytes: this.splitter.getPendingBytes(),
783
+ sessionStarts: this.sessionStarts,
784
+ restarts: this.restarts,
785
+ framesDecoded: this.framesDecoded,
786
+ framesServed: this.framesServed,
787
+ framesEvicted: this.ring.getEvicted(),
788
+ framesRejected: this.ring.getRejected(),
789
+ oversizeFrames: this.splitter.getOversizeFrames(),
790
+ resyncs: this.splitter.getResyncs(),
791
+ staleReads: this.staleReads,
792
+ lastFrameAtMs: this.lastFrameAtMs,
793
+ frameAgeMs: newest ? this.now() - newest.atMs : null,
794
+ lastErrorMessage: this.lastErrorMessage,
795
+ };
796
+ }
797
+ // ── internals ────────────────────────────────────────────────────────────
798
+ async degradeTo(reason) {
799
+ this.mode = 'per_grab';
800
+ this.degradedReason = reason;
801
+ if (reason !== 'disabled') {
802
+ this.log('warn', `RTSP persistent session unavailable (${reason}); falling back to per-grab capture` +
803
+ (this.lastErrorMessage ? `: ${this.lastErrorMessage}` : ''));
804
+ }
805
+ const fallback = this.buildFallback();
806
+ // Assign BEFORE open() so a rejection still leaves the provider describing
807
+ // the path it is actually on. A throw here is the per-grab path failing,
808
+ // which is exactly what a connector sees today.
809
+ this.fallback = fallback;
810
+ await fallback.open();
811
+ }
812
+ releaseSlot() {
813
+ if (this.releaseAdmission) {
814
+ this.releaseAdmission();
815
+ this.releaseAdmission = null;
816
+ }
817
+ }
818
+ /** The newest frame if it has not been served yet, else null. */
819
+ takeFreshFrame() {
820
+ const newest = this.ring.newest();
821
+ if (!newest || newest.seq <= this.lastServedSeq)
822
+ return null;
823
+ this.lastServedSeq = newest.seq;
824
+ this.framesServed += 1;
825
+ return newest.bytes;
826
+ }
827
+ waitForFrame(timeoutMs) {
828
+ return new Promise((resolve) => {
829
+ let settled = false;
830
+ const done = (ok) => {
831
+ if (settled)
832
+ return;
833
+ settled = true;
834
+ this.frameWaiters = this.frameWaiters.filter((w) => w !== wake);
835
+ clearTimeout(timer);
836
+ resolve(ok);
837
+ };
838
+ const wake = () => done(true);
839
+ const timer = setTimeout(() => done(false), timeoutMs);
840
+ if (typeof timer.unref === 'function')
841
+ timer.unref();
842
+ this.frameWaiters.push(wake);
843
+ });
844
+ }
845
+ wakeWaiters() {
846
+ const waiters = this.frameWaiters;
847
+ this.frameWaiters = [];
848
+ for (const w of waiters) {
849
+ try {
850
+ w();
851
+ }
852
+ catch {
853
+ /* a waiter cannot break the session */
854
+ }
855
+ }
856
+ }
857
+ admitFrame(bytes) {
858
+ const at = this.now();
859
+ const seq = this.ring.push(bytes, at);
860
+ if (seq === null)
861
+ return; // counted as rejected inside the ring
862
+ this.framesDecoded += 1;
863
+ this.lastFrameAtMs = at;
864
+ this.wakeWaiters();
865
+ }
866
+ /**
867
+ * ffmpeg args for a CONTINUOUS MJPEG pull. The URL goes into a 0600 ffconcat
868
+ * file exactly as the other two providers do, so it never reaches argv.
869
+ */
870
+ buildInputArgs() {
871
+ const isRtsp = /^rtsps?:\/\//i.test(this.rtspUrl);
872
+ if (!isRtsp) {
873
+ return { args: ['-i', this.rtspUrl], cleanup: () => undefined };
874
+ }
875
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'trillboards-rtsp-stream-'));
876
+ const file = path.join(dir, 'input.ffconcat');
877
+ const timeoutOpt = this.ffmpegMajorVersion >= 5 ? 'timeout' : 'stimeout';
878
+ fs.writeFileSync(file, [
879
+ 'ffconcat version 1.0',
880
+ `file '${(0, RTSPCameraProvider_1.escapeFfconcatValue)(this.rtspUrl)}'`,
881
+ `option rtsp_transport ${this.transport}`,
882
+ `option ${timeoutOpt} ${this.timeoutUs}`,
883
+ '',
884
+ ].join('\n'), { mode: 0o600 });
885
+ try {
886
+ fs.chmodSync(file, 0o600);
887
+ }
888
+ catch {
889
+ /* best-effort on platforms with ACL semantics */
890
+ }
891
+ return {
892
+ args: [
893
+ '-protocol_whitelist',
894
+ 'file,crypto,tcp,tls,rtp,rtsp,udp,http,https',
895
+ '-safe',
896
+ '0',
897
+ '-f',
898
+ 'concat',
899
+ '-i',
900
+ file,
901
+ ],
902
+ cleanup: () => {
903
+ try {
904
+ fs.unlinkSync(file);
905
+ }
906
+ catch {
907
+ /* already gone */
908
+ }
909
+ try {
910
+ fs.rmdirSync(dir);
911
+ }
912
+ catch {
913
+ /* best-effort */
914
+ }
915
+ },
916
+ };
917
+ }
918
+ buildArgs() {
919
+ const input = this.buildInputArgs();
920
+ return {
921
+ args: [
922
+ '-nostdin',
923
+ // Before the input, so it binds to the DECODER. See
924
+ // DEFAULT_DECODER_THREADS: one thread is both smaller and faster here.
925
+ '-threads',
926
+ String(this.decoderThreads),
927
+ ...input.args,
928
+ '-an',
929
+ // crop (mosaic tile) FIRST, then the aspect-preserving scale+pad — the
930
+ // SAME carve math as the one-shot path, imported rather than restated,
931
+ // so a persistent feed and a per-grab feed can never disagree about
932
+ // what a frame of this camera looks like.
933
+ //
934
+ // `fps` LAST and deliberately not an output `-r`: the filter is driven
935
+ // by arriving input frames, so a frozen source emits nothing instead of
936
+ // duplicating the last frame into a lie about freshness.
937
+ '-vf',
938
+ `${(0, RTSPCameraProvider_1.buildVideoFilter)(this.width, this.height, this.crop)},fps=${this.streamFps}`,
939
+ '-f',
940
+ 'mjpeg',
941
+ '-q:v',
942
+ String((0, RTSPCameraProvider_1.mjpegQv)(this.jpegQuality)),
943
+ // …and again after the output codec, so it binds to the ENCODER too.
944
+ '-threads',
945
+ String(this.decoderThreads),
946
+ 'pipe:1',
947
+ ],
948
+ cleanup: input.cleanup,
949
+ };
950
+ }
951
+ /**
952
+ * Start one ffmpeg session. Resolves on the FIRST decoded frame — which is
953
+ * the only evidence that matters, because a spawned process that never
954
+ * produces an image is precisely the failure this provider exists to make
955
+ * loud. Rejects when the session ends before that.
956
+ */
957
+ startSession() {
958
+ return new Promise((resolve, reject) => {
959
+ const { args, cleanup } = this.buildArgs();
960
+ this.cleanupInput = cleanup;
961
+ this.sessionStarts += 1;
962
+ this.splitter.reset();
963
+ let proc;
964
+ try {
965
+ proc = this.spawnFn(this.ffmpegPath, args, { stdio: ['ignore', 'pipe', 'pipe'] });
966
+ }
967
+ catch (err) {
968
+ cleanup();
969
+ this.cleanupInput = null;
970
+ reject(err instanceof Error ? err : new Error(String(err)));
971
+ return;
972
+ }
973
+ this.proc = proc;
974
+ const stderrBuffer = new ffmpegStderr_1.BoundedSessionStderr();
975
+ let settled = false;
976
+ const settle = (fn) => {
977
+ if (settled)
978
+ return;
979
+ settled = true;
980
+ fn();
981
+ };
982
+ proc.stdout?.on('data', (chunk) => {
983
+ for (const frame of this.splitter.push(chunk)) {
984
+ this.admitFrame(frame);
985
+ // A decoded frame proves the session is healthy — reset the backoff.
986
+ this.currentRestartDelay = this.restartDelayMs;
987
+ settle(resolve);
988
+ }
989
+ });
990
+ proc.stderr?.on('data', (chunk) => {
991
+ stderrBuffer.append(chunk.toString());
992
+ });
993
+ proc.on('error', (err) => {
994
+ this.lastErrorMessage = (0, RTSPCameraProvider_1.sanitizeStreamUrlForLog)(err.message);
995
+ settle(() => reject(err));
996
+ this.handleSessionEnd(stderrBuffer.text());
997
+ });
998
+ proc.on('close', (code) => {
999
+ // A CLEAN EXIT IS A FAULT HERE. `code === 0` means success on the
1000
+ // one-shot path; on a session we asked to run forever it means the
1001
+ // stream ended. Measured against the rig: killing the publisher exits 0
1002
+ // in 26 ms and freezing it exits 0 after ~10 s with "Failed reading
1003
+ // RTSP data: End of file". Both are restarts, never successes.
1004
+ const stderr = stderrBuffer.text();
1005
+ const summary = (0, RTSPCameraProvider_1.summarizeFfmpegStderr)(stderr);
1006
+ this.lastErrorMessage = summary || `ffmpeg stream session exited with code ${code}`;
1007
+ settle(() => reject(new Error(`RTSP stream session ended during startup: ${this.lastErrorMessage}`)));
1008
+ this.handleSessionEnd(stderr);
1009
+ });
1010
+ });
1011
+ }
1012
+ stopProcess() {
1013
+ const proc = this.proc;
1014
+ this.proc = null;
1015
+ if (proc) {
1016
+ try {
1017
+ proc.kill('SIGTERM');
1018
+ }
1019
+ catch {
1020
+ /* already gone */
1021
+ }
1022
+ // Bounded escalation: an ffmpeg wedged on a half-open RTSP socket ignores
1023
+ // SIGTERM, and a connector that leaks one child per restart is the
1024
+ // 28-children incident wearing a different hat.
1025
+ const timer = setTimeout(() => {
1026
+ try {
1027
+ proc.kill('SIGKILL');
1028
+ }
1029
+ catch {
1030
+ /* already gone */
1031
+ }
1032
+ }, 2000);
1033
+ if (typeof timer.unref === 'function')
1034
+ timer.unref();
1035
+ }
1036
+ if (this.cleanupInput) {
1037
+ this.cleanupInput();
1038
+ this.cleanupInput = null;
1039
+ }
1040
+ }
1041
+ /**
1042
+ * A session ended. While the provider is open this ALWAYS schedules a restart
1043
+ * with capped exponential backoff, and it is never allowed to give up. On the
1044
+ * Ember fleet `shouldGiveUp` retired a camera permanently after a fixed 411 s
1045
+ * and NOTHING re-armed it — `onCameraStartFailed` was telemetry-only, no
1046
+ * config push restarted the analyzer, and `setMaxRetries` had zero call sites
1047
+ * — so 7,359 escalations became permanent silence
1048
+ * (docs/runbooks/ember-camera-health-taxonomy.md). The cap is what keeps a
1049
+ * never-give-up retry from being a hammer.
1050
+ *
1051
+ * Waiters are woken on the way out so a `getFrame()` blocked on a session
1052
+ * that just died reaches its stale error rather than sitting out the full
1053
+ * deadline for a stream that is provably not coming back.
1054
+ */
1055
+ handleSessionEnd(stderr) {
1056
+ if (this.cleanupInput) {
1057
+ this.cleanupInput();
1058
+ this.cleanupInput = null;
1059
+ }
1060
+ this.proc = null;
1061
+ // Wake anyone blocked in getFrame(): the session that would have fed them
1062
+ // is gone, so they should reach their stale error now rather than sit out a
1063
+ // full deadline waiting for a stream that is provably not coming back.
1064
+ this.wakeWaiters();
1065
+ if (!this.opened)
1066
+ return;
1067
+ if (this.startingUp)
1068
+ return; // open() owns the retry loop during startup
1069
+ if (this.restartTimer)
1070
+ return;
1071
+ const delay = this.currentRestartDelay;
1072
+ this.currentRestartDelay = Math.min(this.maxRestartDelayMs, Math.max(1, this.currentRestartDelay * 2));
1073
+ this.restarts += 1;
1074
+ this.log('warn', `RTSP stream session ended, restarting in ${delay}ms (restart #${this.restarts}): ` +
1075
+ (0, RTSPCameraProvider_1.summarizeFfmpegStderr)(stderr, 200));
1076
+ this.restartTimer = setTimeout(() => {
1077
+ this.restartTimer = null;
1078
+ if (!this.opened)
1079
+ return;
1080
+ this.startSession().catch((err) => {
1081
+ this.lastErrorMessage = (0, RTSPCameraProvider_1.sanitizeStreamUrlForLog)(err?.message ?? String(err));
1082
+ });
1083
+ }, delay);
1084
+ if (typeof this.restartTimer.unref === 'function')
1085
+ this.restartTimer.unref();
1086
+ }
1087
+ log(level, message) {
1088
+ this.onLog?.(level, (0, RTSPCameraProvider_1.sanitizeStreamUrlForLog)(message));
1089
+ }
1090
+ }
1091
+ exports.RTSPStreamCameraProvider = RTSPStreamCameraProvider;
1092
+ //# sourceMappingURL=RTSPStreamCameraProvider.js.map