@trillboards/edge-platform-rtsp 0.2.6 → 0.2.9

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 CHANGED
@@ -95,6 +95,59 @@ Four things about it that are not obvious:
95
95
  plus a separate `maxFrameBytes` ceiling on the partially-received frame, with
96
96
  every eviction counted in `getStats()`.
97
97
 
98
+ #### Segment recording — the same session, a second output
99
+
100
+ `segmentRecording` makes the persistent session also write the camera's own
101
+ bitstream to MP4 segments: a **stream copy** (`-map 0:v -c:v copy … -f segment`, plus the camera's audio — see below),
102
+ so there is no decode, no re-encode and no second RTSP session against the
103
+ recorder. Only a crop-less persistent session records; with no
104
+ `segmentRecording` the session's argv is byte-identical to the look-only one.
105
+
106
+ ```ts
107
+ const camera = new RTSPStreamCameraProvider({
108
+ rtspUrl: 'rtsp://user:pass@192.168.1.100:554/Streaming/Channels/101',
109
+ segmentRecording: { dir: '/var/lib/trillboards/video-segments/cam-101', segmentSeconds: 60, ringSeconds: 3600 },
110
+ });
111
+ camera.on('segment', (s) => {
112
+ // s.file is a CLOSED .mp4 under <dir>/closed/, beside its JSON sidecar.
113
+ // s.captureStartMs / s.captureEndMs are wall clock; s.stream is ffmpeg's codec/size/fps.
114
+ });
115
+ camera.on('segment_evicted', (e) => { /* the ring deleted e.file before delivery */ });
116
+ await camera.open();
117
+ camera.setSegmentRecording(null); // stop: one session restart, counted as a reconfigure
118
+ ```
119
+
120
+ - **Closed means listed.** ffmpeg writes a line to the segment list only when it
121
+ ends a segment. Listed files move to `<dir>/closed/`; anything still in a
122
+ session's work directory when it ends was never listed and is deleted.
123
+ - **Timing.** `captureStartMs` = wall clock at the session's first decoded frame
124
+ + the segment's `startSec`. `-avoid_negative_ts make_zero` makes the copy's
125
+ timeline start at its first keyframe, which is what makes that sum true, and
126
+ each close is checked against the wall clock to correct a drifting media clock.
127
+ - **HEVC** is tagged `hvc1` (ffmpeg writes `hev1` otherwise, which QuickTime and
128
+ Safari refuse). Codecs other than H.264 and HEVC are not recorded.
129
+ - **The camera's audio rides in the same segments.** Once ffmpeg's input
130
+ description names an audio stream, the session restarts once (a reconfigure)
131
+ with `-map 0:a:0?`: AAC is copied; any other codec (G.711, G.726, Opus, PCM)
132
+ is transcoded once to AAC-LC at the camera's own rate and channels — 48 kb/s
133
+ at 8 kHz mono (AAC-LC's ceiling there), 64 kb/s per channel above 11 kHz —
134
+ and the track's handler name says what the camera sent (`camera pcm_alaw 8000
135
+ Hz 1ch`). The look output keeps `-an`; a camera with no audio stream keeps the
136
+ video-only argv. Measured: 1.14% of one core per 8 kHz G.711 camera.
137
+ - **Audio never costs the video.** With audio mapped the copy's timeline starts
138
+ at the first audio packet, so the first segment's own edit list gives the
139
+ first video frame's offset and the clock is anchored there. A camera that
140
+ announces a microphone and sends nothing stalls the output (no file at all):
141
+ 15 s after the first frame with no file, or any failure of a session with
142
+ audio, drops the audio for a doubling pause (10 min up to 24 h) and the next
143
+ session records video exactly as before. `getStats().segments.audio` says which.
144
+ - **Bounded on disk.** The closed ring holds min(`ringSeconds` x measured
145
+ bytes/s, 10% of the volume's free bytes), deleting oldest first.
146
+ - **It never takes the look path down.** A session that carried the second
147
+ output and failed runs look-only next; recording retries after a doubling
148
+ pause (60 s up to 1 h). `getStats().segments` reports the state, the ring, and
149
+ every counter.
150
+
98
151
  ## Audio
99
152
 
100
153
  ### `RTSPAudioProvider` — continuous audio off a camera / NVR channel
@@ -1,7 +1,9 @@
1
1
  /// <reference types="node" />
2
2
  /// <reference types="node" />
3
3
  /// <reference types="node" />
4
+ /// <reference types="node" />
4
5
  import { spawn } from 'child_process';
6
+ import { EventEmitter } from 'events';
5
7
  import type { CameraProvider } from '@trillboards/edge-core';
6
8
  import { type CropRegion, type RTSPCameraConfig } from './RTSPCameraProvider';
7
9
  /**
@@ -178,6 +180,54 @@ import { type CropRegion, type RTSPCameraConfig } from './RTSPCameraProvider';
178
180
  * written to a 0600 ffconcat file and only the temp path reaches argv, so a
179
181
  * password never appears in `ps` output; stderr is scrubbed through
180
182
  * `sanitizeStreamUrlForLog` before it can reach a log line.
183
+ *
184
+ * ── SEGMENT RECORDING: A SECOND OUTPUT ON THE SAME SESSION ────────────────
185
+ *
186
+ * `segmentRecording` adds a second ffmpeg OUTPUT to the session that is already
187
+ * running — `-map 0:v -c:v copy … -f segment` — so the camera's own H.264/HEVC
188
+ * bitstream is written to MP4 segments with no decode and no re-encode, and no
189
+ * second RTSP session is opened against the recorder. The look path's argv is
190
+ * byte-identical when it is absent, and only a crop-less persistent session
191
+ * records (a mosaic tile's crop applies to the look output, never to a copy).
192
+ *
193
+ * Closed segments are found by reading the segment muxer's own CSV list:
194
+ * ffmpeg prints a line only when it ENDS a segment, so a listed file is a
195
+ * closed one. Every listed file moves to `<dir>/closed/` with a JSON sidecar
196
+ * and is emitted as a `'segment'` event; every file still in the session's
197
+ * work directory when the session ends was never listed — the segment that
198
+ * was being written — and is deleted, so a partial file never leaves here.
199
+ * Measured on ffmpeg 6.1.1 against mediamtx: SIGTERM mid-segment leaves that
200
+ * segment unlisted and without a `moov` atom; a listed segment probes clean.
201
+ *
202
+ * Recording can never take the look path down. A session that carried the
203
+ * second output, opened its input and then produced nothing is read as the
204
+ * output's failure: the next session runs look-only and recording retries
205
+ * after a doubling cooldown (`SEGMENT_SUSPEND_BASE_MS`..`SEGMENT_SUSPEND_MAX_MS`).
206
+ *
207
+ * ── THE CAMERA'S AUDIO RIDES IN THE SAME SEGMENTS ─────────────────────────
208
+ *
209
+ * When ffmpeg's input description names an audio stream, the second output
210
+ * also maps the camera's first audio track (`-map 0:a:0?`): AAC is copied as
211
+ * is; every other codec (G.711, G.726, Opus, PCM, …) is transcoded ONCE to
212
+ * AAC-LC at the camera's own rate and channel count (`audioPlanFor`). The look
213
+ * output keeps `-an`, the video stays a copy, and a camera with no audio track
214
+ * gets exactly the video-only argv. Measured on the mediamtx rig (ffmpeg
215
+ * 6.1.1; the CPU cost is in `aacBitrateFor`), three facts shape the code:
216
+ *
217
+ * 1. The audio starts at the first audio PACKET and the copy at the first
218
+ * video KEYFRAME, so with audio mapped the segment list's zero moves
219
+ * earlier by that gap (0.905 s on a 6 fps HEVC camera; one GOP at most).
220
+ * `anchorFor` reads the gap back from the first segment's own edit list.
221
+ * 2. A camera that ANNOUNCES a microphone and sends no audio packets stalls
222
+ * the whole second output: the AAC encoder never starts, so the segment
223
+ * muxer never writes a file (40 s, nothing on disk, look path fine). With
224
+ * audio flowing the first file exists within 0.1 s of the first frame, so
225
+ * no file `AUDIO_START_DEADLINE_MS` after the first frame is a stall.
226
+ * 3. Audio is the junior track. Any failure of a session that mapped audio —
227
+ * a stall, a death before the first frame, a write error — suspends AUDIO
228
+ * (`AUDIO_SUSPEND_BASE_MS`..`AUDIO_SUSPEND_MAX_MS`) and the next session
229
+ * records video exactly as before. Only a video-only failure suspends
230
+ * recording.
181
231
  */
182
232
  /** The recorder's persistent-session lane is full. Degrade, never queue. */
183
233
  export declare class RtspStreamAdmissionError extends Error {
@@ -348,6 +398,293 @@ export declare function streamSessionStatsFor(streamUrl: string): {
348
398
  limit: number;
349
399
  learnedCeiling: number | null;
350
400
  } | null;
401
+ /** Where and how a feed records. One directory per feed; never shared. */
402
+ export interface SegmentRecordingConfig {
403
+ /**
404
+ * The feed's own directory. Session work directories (`rec-*`) and the ring
405
+ * of closed segments (`closed/`) live beneath it.
406
+ */
407
+ dir: string;
408
+ /** `-segment_time`: a segment closes at the first keyframe after this. */
409
+ segmentSeconds: number;
410
+ /** Ring capacity, in seconds of this feed's MEASURED bytes per second. */
411
+ ringSeconds: number;
412
+ /**
413
+ * False keeps the directory (leftover recovery, the ring) but adds no
414
+ * output. Default true.
415
+ */
416
+ enabled?: boolean;
417
+ }
418
+ /** The input's first audio stream as ffmpeg described it. */
419
+ export interface SegmentAudioStreamInfo {
420
+ /** ffmpeg's codec name, lowercased: `pcm_alaw`, `pcm_mulaw`, `aac`, `opus`, … (`none` = unidentified). */
421
+ codec: string;
422
+ sampleRate: number | null;
423
+ channels: number | null;
424
+ }
425
+ /** The input stream as ffmpeg described it when the session opened. */
426
+ export interface SegmentStreamInfo {
427
+ /** ffmpeg's codec name, lowercased: `h264`, `hevc`, `mjpeg`, … */
428
+ codec: string;
429
+ width: number | null;
430
+ height: number | null;
431
+ fps: number | null;
432
+ /** The input's first audio stream. Absent when the input carries none. */
433
+ audio?: SegmentAudioStreamInfo;
434
+ }
435
+ /**
436
+ * What the second output does with the camera's audio. `copy` for AAC, which
437
+ * MP4 holds as is; `aac` transcodes once (MP4 cannot hold G.711 or G.726).
438
+ */
439
+ export interface SegmentAudioPlan {
440
+ mode: 'copy' | 'aac';
441
+ /** `-b:a` for a transcode; null leaves the rate to ffmpeg's encoder (the camera named no rate or layout). */
442
+ bitrateBps: number | null;
443
+ /** The camera's own audio in ffmpeg's words (`pcm_alaw 8000 Hz 1ch`), written as the track's handler name. */
444
+ source: string;
445
+ }
446
+ /** A CLOSED segment, moved into `<dir>/closed/` beside its JSON sidecar. */
447
+ export interface RecordedSegment {
448
+ /** Absolute path of the closed `.mp4`. The consumer owns it from here. */
449
+ file: string;
450
+ /** Its JSON sidecar (the fields below), deleted with it. */
451
+ metaFile: string;
452
+ /** Start and end on the session's output timeline, from the segment list. */
453
+ startSec: number;
454
+ endSec: number;
455
+ /**
456
+ * Wall clock at the session's first decoded frame, plus the segment's offset
457
+ * from the session's FIRST listed segment. See `anchorFor`.
458
+ */
459
+ captureStartMs: number;
460
+ captureEndMs: number;
461
+ bytes: number;
462
+ stream: SegmentStreamInfo | null;
463
+ /** Closed by an earlier process and found on disk when this one opened. */
464
+ recovered: boolean;
465
+ }
466
+ /** A closed segment the ring deleted before anyone delivered it. */
467
+ export interface EvictedSegment {
468
+ file: string;
469
+ metaFile: string;
470
+ bytes: number;
471
+ }
472
+ export type SegmentRecordingState =
473
+ /** No recording configured, or configured off. */
474
+ 'off'
475
+ /** A session is writing segments now. */
476
+ | 'recording'
477
+ /** Configured on; the next session will record. */
478
+ | 'waiting_for_session'
479
+ /** A mosaic tile: its crop belongs to the look output, so it never records. */
480
+ | 'cropped'
481
+ /** The feed runs the per-grab path, which has no session to record from. */
482
+ | 'per_grab'
483
+ /** The camera sends a codec the index cannot hold (not H.264 or HEVC). */
484
+ | 'unsupported_codec'
485
+ /** A session with the second output failed; retrying after a cooldown. */
486
+ | 'suspended';
487
+ export interface SegmentRecordingStats {
488
+ state: SegmentRecordingState;
489
+ dir: string | null;
490
+ segmentSeconds: number | null;
491
+ ringSeconds: number | null;
492
+ /** The input codec ffmpeg reported for the newest session, or null. */
493
+ codec: string | null;
494
+ /** Segments this process closed and emitted (recovered ones excluded). */
495
+ segmentsClosed: number;
496
+ /** Segments an earlier process left on disk, emitted at open. */
497
+ segmentsRecovered: number;
498
+ secondsClosed: number;
499
+ bytesClosed: number;
500
+ /** Never-listed files deleted from session work directories. */
501
+ partialsDeleted: number;
502
+ /** Closed segments on disk at the last ring check, and their bytes. */
503
+ ringSegments: number;
504
+ ringBytes: number;
505
+ /** min(ringSeconds x measured bytes/s, 10% of the volume's free bytes). */
506
+ ringLimitBytes: number | null;
507
+ measuredBytesPerSec: number | null;
508
+ freeBytes: number | null;
509
+ evictedSegments: number;
510
+ evictedBytes: number;
511
+ /** Session restarts taken to add, drop or change the second output. */
512
+ reconfigures: number;
513
+ /**
514
+ * Sessions whose second output failed: opened the input and produced
515
+ * nothing, or named a write failure — plus every audio failure counted in
516
+ * `audio.failures` (which costs the audio, not the recording).
517
+ */
518
+ outputFailures: number;
519
+ suspendedUntilMs: number | null;
520
+ /** Times the wall-clock anchor was corrected against a segment's close. */
521
+ reanchors: number;
522
+ /** Predicted minus observed close of the newest segment, in ms. */
523
+ lastAnchorDriftMs: number | null;
524
+ lastSegmentAtMs: number | null;
525
+ lastError: string | null;
526
+ /** The camera's audio in the segments. */
527
+ audio: SegmentAudioStats;
528
+ }
529
+ export type SegmentAudioState =
530
+ /** ffmpeg has not described the input yet. */
531
+ 'unknown'
532
+ /** The input carries no audio stream: segments are video only. */
533
+ | 'no_audio_track'
534
+ /** ffmpeg could not identify the audio codec (`Audio: none`). */
535
+ | 'unsupported_codec'
536
+ /** A session that mapped audio failed; segments are video only until the pause ends. */
537
+ | 'suspended'
538
+ /** The live session copies the camera's AAC into the segments. */
539
+ | 'copy'
540
+ /** The live session transcodes the camera's audio to AAC once. */
541
+ | 'transcode'
542
+ /** The camera has audio; the next recording session maps it. */
543
+ | 'waiting_for_session';
544
+ export interface SegmentAudioStats {
545
+ state: SegmentAudioState;
546
+ /** The camera's own audio, as ffmpeg named it. */
547
+ codec: string | null;
548
+ sampleRate: number | null;
549
+ channels: number | null;
550
+ /** `-b:a` of the live transcode, or null. */
551
+ bitrateBps: number | null;
552
+ /** Sessions with audio mapped that failed, and of those the stalls (a microphone that sends nothing). */
553
+ failures: number;
554
+ stalls: number;
555
+ suspendedUntilMs: number | null;
556
+ /** How far the first video frame sat behind the first audio packet in the newest session's first segment. */
557
+ lastVideoLeadMs: number | null;
558
+ lastError: string | null;
559
+ }
560
+ /** Codecs `video_segment` holds. Anything else is not recorded. */
561
+ export declare const RECORDABLE_CODECS: readonly string[];
562
+ /** Closed segments, beside their sidecars, under the feed's directory. */
563
+ export declare const CLOSED_SEGMENTS_DIRNAME = "closed";
564
+ /** First recording pause after the second output failed a session. */
565
+ export declare const SEGMENT_SUSPEND_BASE_MS = 60000;
566
+ /** Ceiling on that pause: at most one look-path restart an hour on a failure that persists. */
567
+ export declare const SEGMENT_SUSPEND_MAX_MS = 3600000;
568
+ /** The ring may hold at most this fraction of the volume's free bytes. */
569
+ export declare const RING_FREE_FRACTION = 0.1;
570
+ /**
571
+ * A session that maps audio and has written no segment file this long after
572
+ * its first frame is stalled on a microphone that sends nothing. Measured: with
573
+ * audio flowing the first file existed within 0.1 s of the first frame on three
574
+ * rig cameras (polled every 100 ms); with an announced-but-silent track, no file
575
+ * in 40 s.
576
+ */
577
+ export declare const AUDIO_START_DEADLINE_MS = 15000;
578
+ /** First audio pause after a session with audio mapped failed. */
579
+ export declare const AUDIO_SUSPEND_BASE_MS: number;
580
+ /**
581
+ * Ceiling on that pause. Each retry of a camera whose audio keeps failing costs
582
+ * one look-path restart and, for a stall, the deadline's worth of video, so it
583
+ * settles at one retry a day rather than one an hour.
584
+ */
585
+ export declare const AUDIO_SUSPEND_MAX_MS: number;
586
+ /** A file the segment list names, with its place on the output timeline. */
587
+ export interface SegmentListEntry {
588
+ name: string;
589
+ startSec: number;
590
+ endSec: number;
591
+ }
592
+ /**
593
+ * Parse the segment muxer's CSV list (`-segment_list_type csv`): one line per
594
+ * CLOSED segment, `name,start,end`. The last line is returned as `remainder`
595
+ * when it is not yet newline-terminated, so a half-written line is never read.
596
+ */
597
+ export declare function parseSegmentListCsv(text: string): {
598
+ entries: SegmentListEntry[];
599
+ remainder: string;
600
+ };
601
+ /**
602
+ * One `Stream #0:N: Video: …` line from ffmpeg's input description, or null.
603
+ * `90k tbr`-style rates are the RTP clock, not a frame rate, so only an
604
+ * explicit `fps` is read.
605
+ */
606
+ export declare function parseInputVideoStreamLine(line: string): SegmentStreamInfo | null;
607
+ /**
608
+ * One `Stream #0:N: Audio: …` line from ffmpeg's input description, or null.
609
+ * Real lines (mediamtx rig, ffmpeg 6.1.1): `Audio: pcm_alaw, 8000 Hz, mono,
610
+ * s16, 64 kb/s`, `Audio: aac (LC), 16000 Hz, mono, fltp`, `Audio: opus, 48000
611
+ * Hz, stereo, fltp`; older builds print `1 channels`.
612
+ */
613
+ export declare function parseInputAudioStreamLine(line: string): SegmentAudioStreamInfo | null;
614
+ /**
615
+ * Reads ffmpeg's stderr as it arrives and finishes at the end of the INPUT
616
+ * description — the first line after `Input #0,` that is not indented (`Stream
617
+ * mapping:`, `Output #N`, a component's `[x @ …]` line). It answers with the
618
+ * first video stream, plus the first audio stream when the input has one; the
619
+ * audio line can come before or after the video line, which is why it does not
620
+ * stop at the video. Bounded: it holds at most one partial line.
621
+ */
622
+ export declare class InputStreamProbe {
623
+ private partial;
624
+ private inInput;
625
+ private video;
626
+ private audio;
627
+ /** The input was opened (ffmpeg described it). */
628
+ inputOpened: boolean;
629
+ done: boolean;
630
+ info: SegmentStreamInfo | null;
631
+ push(text: string): SegmentStreamInfo | null;
632
+ private finish;
633
+ }
634
+ /**
635
+ * The transcode's `-b:a`: 64 kb/s per channel, capped at AAC-LC's ceiling of
636
+ * 6,144 bits per 1,024-sample frame per channel — which at 8 kHz, where almost
637
+ * every CCTV microphone sits (G.711), is 48,000 b/s, the most AAC can spend on
638
+ * it. Null when the camera named no rate or channel count.
639
+ *
640
+ * Measured (ffmpeg 6.1.1, one core of the dev box, one hour of 8 kHz G.711
641
+ * A-law pink noise plus a tone): decode + AAC at 48 kb/s costs 40.9 s of CPU
642
+ * per hour of audio, 1.14% of one core per camera, at 33.9 dB signal-to-
643
+ * distortion against the decoded G.711 (G.711's own floor is ~38 dB). 48 kHz
644
+ * stereo Opus to 128 kb/s costs 110 s an hour, 3.1%. A copy (AAC) costs no
645
+ * codec work. ffmpeg's `-aac_coder fast` halves the cost at 30.9 dB.
646
+ */
647
+ export declare function aacBitrateFor(sampleRate: number | null, channels: number | null): number | null;
648
+ /** The camera's own audio in ffmpeg's words: `pcm_alaw 8000 Hz 1ch`. */
649
+ export declare function describeAudioSource(audio: SegmentAudioStreamInfo): string;
650
+ /**
651
+ * What the second output does with this audio stream: copy AAC (MP4-legal as
652
+ * is), transcode anything else once to AAC, and leave out a stream ffmpeg
653
+ * could not identify (it cannot be decoded, so mapping it would only fail).
654
+ */
655
+ export declare function audioPlanFor(audio: SegmentAudioStreamInfo | null | undefined): SegmentAudioPlan | null;
656
+ /**
657
+ * Where the video track starts on a segment's timeline, in seconds, from its
658
+ * `moov`: the leading empty edits (movie timescale) minus the first media
659
+ * edit's start (track timescale). ffmpeg's mov muxer writes exactly that pair
660
+ * — an empty edit of the first sample's presentation time, then a media edit
661
+ * from its composition offset — so the difference is the first video packet's
662
+ * decode time: 0 for a video-only copy (with or without B-frames), and the
663
+ * audio lead when the audio started first. 0 for anything it cannot read.
664
+ */
665
+ export declare function videoStartSecFromMoov(moov: Buffer): number;
666
+ /** `videoStartSecFromMoov` of a closed segment file; 0 when it cannot be read. */
667
+ export declare function readVideoStartSec(file: string): number;
668
+ /** The second output, exactly. Pure, so the argv can be asserted. */
669
+ export declare function buildSegmentOutputArgs(o: {
670
+ /** `-segment_list` target. */
671
+ csvPath: string;
672
+ /** The segment filename template, `%` already escaped in its directory. */
673
+ segmentPattern: string;
674
+ segmentSeconds: number;
675
+ /** `-tag:v hvc1` so an HEVC segment plays in QuickTime/Safari (ffmpeg writes hev1 otherwise). */
676
+ tagHvc1: boolean;
677
+ /**
678
+ * `-min_seg_duration`, so a cut needs at least `segmentSeconds` since the
679
+ * last one. Without it the muxer cuts at the first keyframe after each
680
+ * MULTIPLE of segment_time: a 2 s GOP at segment_time 5 gives 6 s, 4 s, 6 s…
681
+ */
682
+ minSegDuration: boolean;
683
+ /** The camera's audio, or null/absent for the video-only argv, unchanged byte for byte. */
684
+ audio?: SegmentAudioPlan | null;
685
+ }): string[];
686
+ /** The volume's free bytes, or null where the platform cannot say. */
687
+ export declare function volumeFreeBytes(dir: string): number | null;
351
688
  export interface RTSPStreamCameraConfig {
352
689
  /** RTSP stream URL. Credentials never reach argv — see the header. */
353
690
  rtspUrl: string;
@@ -411,6 +748,14 @@ export interface RTSPStreamCameraConfig {
411
748
  fallbackConfig?: Partial<RTSPCameraConfig>;
412
749
  /** DHCP recovery hook, forwarded to the per-grab fallback. */
413
750
  streamUrlResolver?: RTSPCameraConfig['streamUrlResolver'];
751
+ /**
752
+ * Record the camera's own bitstream to MP4 segments as a second output of
753
+ * the persistent session (stream copy). Applies only to a persistent session
754
+ * with no `crop`. Change it later with `setSegmentRecording`.
755
+ */
756
+ segmentRecording?: SegmentRecordingConfig;
757
+ /** Free bytes of the volume holding a directory. Injected for tests. */
758
+ freeBytesFn?: (dir: string) => number | null;
414
759
  /** Injected spawn, for tests. */
415
760
  spawnFn?: typeof spawn;
416
761
  /** Injected per-grab fallback, for tests. */
@@ -454,14 +799,23 @@ export interface RTSPStreamStats {
454
799
  /** Age of the newest frame at the moment getStats() was called, or null. */
455
800
  frameAgeMs: number | null;
456
801
  lastErrorMessage: string | null;
802
+ /**
803
+ * Segment recording on this feed. `state` is derived on every call; the ring
804
+ * figures are as of the last ring check (each segment close and session end).
805
+ */
806
+ segments: SegmentRecordingStats;
457
807
  }
458
808
  /**
459
809
  * One instance per feed. Implements the SAME `CameraProvider` interface as
460
810
  * `RTSPCameraProvider`, so every consumer is unchanged — but `getFrame()` reads
461
811
  * the newest frame out of the ring the long-lived session is filling, rather
462
812
  * than spawning a process and handshaking a stream per call.
813
+ *
814
+ * Events: `'segment'` (RecordedSegment) for every closed recording segment,
815
+ * `'segment_evicted'` (EvictedSegment) when the ring deletes one undelivered,
816
+ * and `'opening'` at the start of every `open()`.
463
817
  */
464
- export declare class RTSPStreamCameraProvider implements CameraProvider {
818
+ export declare class RTSPStreamCameraProvider extends EventEmitter implements CameraProvider {
465
819
  private readonly rtspUrl;
466
820
  private readonly width;
467
821
  private readonly height;
@@ -503,14 +857,39 @@ export declare class RTSPStreamCameraProvider implements CameraProvider {
503
857
  * one frame later.
504
858
  */
505
859
  private fallbackOpenError;
506
- private proc;
860
+ /** The live ffmpeg session, or null between sessions. */
861
+ private session;
507
862
  /** This recorder's persistent-session lane, for the learned ceiling. */
508
863
  private admission;
509
864
  private releaseAdmission;
510
865
  private restartTimer;
511
866
  private currentRestartDelay;
512
- private cleanupInput;
513
867
  private startingUp;
868
+ private segmentConfig;
869
+ private readonly freeBytesFn;
870
+ /** The newest input description ffmpeg gave; decides the tag and the codec gate. */
871
+ private streamInfo;
872
+ private segmentsRecoveredFor;
873
+ private segmentPollTimer;
874
+ private lastSegmentPollAtMs;
875
+ /** A session stopped to change the second output; its exit starts the next one. */
876
+ private reconfigurePendingFor;
877
+ /**
878
+ * Recording paused after the second output failed a session. Provider-wide,
879
+ * not per argv: the next plan differs only by the tag once ffmpeg has named
880
+ * the codec, and retrying it at once would spend open()'s last attempt.
881
+ */
882
+ private segmentSuspension;
883
+ private segmentSuspendTimer;
884
+ private consecutiveOutputFailures;
885
+ /** The camera's audio left out of the segments after a session that mapped it failed. */
886
+ private audioSuspension;
887
+ private audioSuspendTimer;
888
+ private consecutiveAudioFailures;
889
+ private readonly audioCounters;
890
+ private measuredSegmentBytes;
891
+ private measuredSegmentSeconds;
892
+ private readonly segCounters;
514
893
  private sessionStarts;
515
894
  private restarts;
516
895
  private framesDecoded;
@@ -522,6 +901,17 @@ export declare class RTSPStreamCameraProvider implements CameraProvider {
522
901
  /** Resolvers waiting for the next frame. Woken by `admitFrame`. */
523
902
  private frameWaiters;
524
903
  constructor(config: RTSPStreamCameraConfig);
904
+ on(event: 'segment', listener: (segment: RecordedSegment) => void): this;
905
+ on(event: 'segment_evicted', listener: (evicted: EvictedSegment) => void): this;
906
+ on(event: 'opening', listener: () => void): this;
907
+ on(event: string | symbol, listener: (...args: any[]) => void): this;
908
+ /**
909
+ * Change segment recording. `null` turns it off and keeps the directory (the
910
+ * ring and any leftovers stay this provider's). A change that the running
911
+ * session's argv does not already satisfy restarts the session once — after
912
+ * its first frame, never during startup.
913
+ */
914
+ setSegmentRecording(next: SegmentRecordingConfig | null): void;
525
915
  /**
526
916
  * Take a recorder session slot and start streaming. NEVER throws because the
527
917
  * persistent path was unavailable — it degrades to the per-grab provider and
@@ -583,7 +973,12 @@ export declare class RTSPStreamCameraProvider implements CameraProvider {
583
973
  * file exactly as the other two providers do, so it never reaches argv.
584
974
  */
585
975
  private buildInputArgs;
586
- buildArgs(): {
976
+ /**
977
+ * The session's argv. With no `segmentOutput` it is byte-identical to the
978
+ * look-only session this provider has always run; with one, the second
979
+ * output (`buildSegmentOutputArgs`) follows `pipe:1`.
980
+ */
981
+ buildArgs(segmentOutput?: Parameters<typeof buildSegmentOutputArgs>[0] | null): {
587
982
  args: string[];
588
983
  cleanup: () => void;
589
984
  };
@@ -594,7 +989,13 @@ export declare class RTSPStreamCameraProvider implements CameraProvider {
594
989
  * loud. Rejects when the session ends before that.
595
990
  */
596
991
  private startSession;
992
+ /**
993
+ * Detach the live session and stop its ffmpeg. Its own exit later finishes
994
+ * its recording, and is never restarted: whoever called this owns what
995
+ * happens next (close, shed, or open()'s retry loop).
996
+ */
597
997
  private stopProcess;
998
+ private killSession;
598
999
  /**
599
1000
  * A session ended. While the provider is open this ALWAYS schedules a restart
600
1001
  * with capped exponential backoff, and it is never allowed to give up. On the
@@ -608,8 +1009,125 @@ export declare class RTSPStreamCameraProvider implements CameraProvider {
608
1009
  * Waiters are woken on the way out so a `getFrame()` blocked on a session
609
1010
  * that just died reaches its stale error rather than sitting out the full
610
1011
  * deadline for a stream that is provably not coming back.
1012
+ *
1013
+ * Only the LIVE session's end does any of that. A session already detached
1014
+ * (stopProcess) or superseded (a reconfigure) finishes its recording and
1015
+ * either stops there or, for a reconfigure, starts its replacement.
611
1016
  */
612
1017
  private handleSessionEnd;
1018
+ /** What the NEXT session should record, or null for look-only. */
1019
+ private planRecording;
1020
+ /**
1021
+ * The camera's audio for the next session — decided ONLY from ffmpeg's own
1022
+ * description of this input, never speculated: a session that has not been
1023
+ * described yet records video only, exactly as before, and the description
1024
+ * of an audio track then costs one reconfigure. Speculating would put audio
1025
+ * options on every camera with no microphone (ffmpeg warns that `-b:a` was
1026
+ * never used) and risk the stall above on a camera nobody has seen yet.
1027
+ */
1028
+ private planAudio;
1029
+ /** Does a running session's second output already give what `want` asks for? */
1030
+ private sessionSatisfies;
1031
+ /**
1032
+ * Bring the live session's second output in line with the plan — by
1033
+ * restarting it once, only after its first frame, and never with a second
1034
+ * reconfigure already in flight. The restart is not a fault: it is counted
1035
+ * in `segments.reconfigures`, not `restarts`, and keeps the recorder slot.
1036
+ */
1037
+ private reconcileRecording;
1038
+ private onSessionFirstFrame;
1039
+ private onSessionStreamInfo;
1040
+ /** The work directory for a session that will record, or null for look-only. */
1041
+ private prepareSessionRecording;
1042
+ /** Pause recording, doubling from SEGMENT_SUSPEND_BASE_MS, then reconcile again. */
1043
+ private suspendRecording;
1044
+ private clearSegmentSuspension;
1045
+ /**
1046
+ * Leave the camera's audio out of the segments for a doubling pause
1047
+ * (`AUDIO_SUSPEND_BASE_MS`..`AUDIO_SUSPEND_MAX_MS`), then reconcile again.
1048
+ * Counted as a second-output failure too, so `open()` does not spend a
1049
+ * validation attempt on it; video recording is untouched.
1050
+ */
1051
+ private suspendAudio;
1052
+ /**
1053
+ * The ONE thing that brings audio back after a pause: reconcile when the
1054
+ * pause ends. Armed by `suspendAudio`, and re-armed by `open()` — `close()`
1055
+ * cancels the timer but keeps the pause, so a feed reopened mid-pause would
1056
+ * otherwise record video only until some unrelated restart.
1057
+ */
1058
+ private armAudioRetry;
1059
+ /**
1060
+ * A session that maps audio and has written no file `AUDIO_START_DEADLINE_MS`
1061
+ * after its first frame is stalled on a microphone that sends nothing: drop
1062
+ * the audio and restart the session video-only. Checked once, at the deadline.
1063
+ */
1064
+ private checkAudioStall;
1065
+ private ensureSegmentPolling;
1066
+ private stopSegmentPolling;
1067
+ /** One read of the live session's segment list: new closes move into the ring. */
1068
+ private pollSegments;
1069
+ /** Read whatever the segment list gained since the last read. */
1070
+ private readSegmentList;
1071
+ /** Move listed segments into the ring, in list order. Returns how many moved. */
1072
+ private flushPending;
1073
+ private closeSegment;
1074
+ /**
1075
+ * The wall clock of the session's FIRST listed segment.
1076
+ *
1077
+ * The first decoded frame and the first copied packet are the same keyframe
1078
+ * (a stream copy drops what precedes it), so the first listed segment starts
1079
+ * at the first frame's wall clock and every later one at its offset from it.
1080
+ * When ffmpeg starts the output timeline at 0 — measured 0.000000 for H.264
1081
+ * and HEVC through mediamtx — that is exactly first frame + startSec.
1082
+ *
1083
+ * With the camera's audio mapped the timeline starts at the first audio
1084
+ * PACKET instead, which can arrive before the first video keyframe (rig:
1085
+ * 0.905 s on a 6 fps HEVC camera, every listed time shifted by it). The first
1086
+ * frame then sits at the first segment's VIDEO start, which the file's own
1087
+ * edit list states (`readVideoStartSec`), so that is the anchor's media time.
1088
+ * Without it every segment of the session would be dated up to a GOP late.
1089
+ */
1090
+ private anchorFor;
1091
+ /**
1092
+ * Keep the anchor honest against the one wall-clock fact a close gives us:
1093
+ * a segment cannot end after we saw it closed, and on a timely poll it ended
1094
+ * at most one poll before. The camera's media clock is not the wall clock,
1095
+ * and a session runs for days.
1096
+ */
1097
+ private guardAnchorDrift;
1098
+ private persistAnchor;
1099
+ /**
1100
+ * Write the sidecar, then move the closed file beside it, then emit. Null
1101
+ * when the move must be retried (Windows refuses to rename a file ffmpeg
1102
+ * still holds; the next poll asks again).
1103
+ */
1104
+ private moveIntoRing;
1105
+ private countSegment;
1106
+ private emitSegment;
1107
+ /**
1108
+ * A session that recorded has ended: read its list one last time, move what
1109
+ * it closed, judge the second output, and delete what it never listed.
1110
+ */
1111
+ private finishSessionRecording;
1112
+ private removeWorkDir;
1113
+ /**
1114
+ * Hand out what an earlier process left: closed segments with sidecars, and
1115
+ * listed segments still in a session work directory. Unlisted files are
1116
+ * partials and are deleted. Runs once per directory, before the first session.
1117
+ */
1118
+ private recoverSegments;
1119
+ private recoverWorkDir;
1120
+ /**
1121
+ * Hold the closed segments to min(ringSeconds x measured bytes/s, 10% of the
1122
+ * volume's free bytes), deleting oldest first. A file the OS will not let us
1123
+ * delete (Windows, mid-upload) is skipped, never waited on.
1124
+ */
1125
+ private enforceRing;
1126
+ private measuredBytesPerSec;
1127
+ private segmentStats;
1128
+ /** The camera's audio in the segments. Derived on every call, like the rest. */
1129
+ private audioStats;
1130
+ private recordingState;
613
1131
  private log;
614
1132
  }
615
1133
  //# sourceMappingURL=RTSPStreamCameraProvider.d.ts.map