@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 +53 -0
- package/dist/RTSPStreamCameraProvider.d.ts +522 -4
- package/dist/RTSPStreamCameraProvider.d.ts.map +1 -1
- package/dist/RTSPStreamCameraProvider.js +1727 -46
- package/dist/RTSPStreamCameraProvider.js.map +1 -1
- package/dist/index.d.ts +2 -2
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +23 -1
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
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
|
-
|
|
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
|
-
|
|
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
|