@trillboards/edge-platform-rtsp 0.2.20 → 0.2.21

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.
@@ -23,12 +23,13 @@ var __importStar = (this && this.__importStar) || function (mod) {
23
23
  return result;
24
24
  };
25
25
  Object.defineProperty(exports, "__esModule", { value: true });
26
- exports.segmentPatternFor = exports.RTSPStreamCameraProvider = exports.volumeFreeBytes = exports.buildSegmentOutputArgs = exports.readVideoStartSec = exports.videoStartSecFromMoov = exports.audioPlanFor = exports.describeAudioSource = exports.aacBitrateFor = exports.InputStreamProbe = exports.parseInputAudioStreamLine = exports.parseInputVideoStreamLine = exports.parseSegmentListCsv = exports.AUDIO_SUSPEND_MAX_MS = exports.AUDIO_SUSPEND_BASE_MS = exports.AUDIO_START_DEADLINE_MS = exports.RETAKE_BACKOFF_MAX_MS = exports.RETAKE_BACKOFF_BASE_MS = exports.RING_RESYNC_MS = exports.RING_FREE_FRACTION = exports.SEGMENT_SUSPEND_MAX_MS = exports.SEGMENT_SUSPEND_BASE_MS = exports.CLOSED_SEGMENTS_DIRNAME = exports.RECORDABLE_CODECS = exports.streamSessionStatsFor = exports.acquirePersistentSessionSlot = exports.__resetStreamAdmissionForTests = exports.reserveLiveViewStreamSession = exports.FrameRing = exports.MjpegFrameSplitter = exports.jpegFrameEnd = exports.JPEG_MALFORMED = exports.JPEG_NEED_MORE = exports.DEFAULT_MAX_STREAM_SESSIONS_PER_SOURCE = exports.RtspStreamStaleError = exports.RtspStreamAdmissionError = void 0;
26
+ exports.segmentPatternFor = exports.RTSPStreamCameraProvider = exports.sortOffLoop = exports.ringIoInFlightForTests = exports.HW_PROBE_REPORT_DELAY_MS = exports.KEYFRAME_JITTER_MS = exports.KEYFRAME_MAX_INTERVAL_MS = exports.volumeFreeBytes = exports.buildSegmentOutputArgs = exports.readVideoStartSec = exports.videoStartSecFromMoov = exports.audioPlanFor = exports.describeAudioSource = exports.aacBitrateFor = exports.InputStreamProbe = exports.parseInputAudioStreamLine = exports.parseInputVideoStreamLine = exports.parseSegmentListCsv = exports.AUDIO_SUSPEND_MAX_MS = exports.AUDIO_SUSPEND_BASE_MS = exports.AUDIO_START_DEADLINE_MS = exports.RETAKE_BACKOFF_MAX_MS = exports.RETAKE_BACKOFF_BASE_MS = exports.RING_IO_IN_FLIGHT_MAX = exports.RING_SLICE_MS = exports.RING_SYNC_ENTRIES_MAX = exports.RING_RESYNC_JITTER = exports.RING_RESYNC_MS = exports.RING_FREE_FRACTION = exports.SEGMENT_SUSPEND_MAX_MS = exports.SEGMENT_SUSPEND_BASE_MS = exports.CLOSED_SEGMENTS_DIRNAME = exports.RECORDABLE_CODECS = exports.streamSessionStatsFor = exports.acquirePersistentSessionSlot = exports.__resetStreamAdmissionForTests = exports.reserveLiveViewStreamSession = exports.FrameRing = exports.MjpegFrameSplitter = exports.jpegFrameEnd = exports.JPEG_MALFORMED = exports.JPEG_NEED_MORE = exports.DEFAULT_MAX_STREAM_SESSIONS_PER_SOURCE = exports.RtspStreamStaleError = exports.RtspStreamAdmissionError = void 0;
27
27
  const child_process_1 = require("child_process");
28
28
  const events_1 = require("events");
29
29
  const fs = __importStar(require("fs"));
30
30
  const os = __importStar(require("os"));
31
31
  const path = __importStar(require("path"));
32
+ const perf_hooks_1 = require("perf_hooks");
32
33
  const RTSPCameraProvider_1 = require("./RTSPCameraProvider");
33
34
  const ffmpegStderr_1 = require("./ffmpegStderr");
34
35
  /**
@@ -1002,11 +1003,42 @@ const SEGMENT_OUTPUT_FAILURE_RE = /(Failed to open segment[^\n]*|No space left o
1002
1003
  /** The ring may hold at most this fraction of the volume's free bytes (unless the caller sets `maxBytes`). */
1003
1004
  exports.RING_FREE_FRACTION = 0.1;
1004
1005
  /**
1005
- * How often the ring's in-memory index is rebuilt from disk. Between rebuilds
1006
+ * How often the ring's in-memory index is checked against disk. Between checks
1006
1007
  * every close updates it, so a ring of thousands of short segments costs one
1007
1008
  * statfs and no directory listing per close.
1008
1009
  */
1009
1010
  exports.RING_RESYNC_MS = 10 * 60000;
1011
+ /**
1012
+ * Each ring checks itself at RING_RESYNC_MS x [1 - this, 1 + this), drawn
1013
+ * afresh every time, so rings opened together drift apart instead of walking
1014
+ * their disks in the same second.
1015
+ */
1016
+ exports.RING_RESYNC_JITTER = 0.25;
1017
+ /**
1018
+ * A ring directory of at most this many entries (segments and their sidecars)
1019
+ * is listed, read and stat'ed in one synchronous pass. A bigger one is walked
1020
+ * off the event loop: an alert camera's week of 10-s segments is 60,480
1021
+ * segments plus their sidecars, and on Texas's store PC one synchronous pass
1022
+ * over such a ring held every camera's looks (plan v7 W8: the looks froze at
1023
+ * every ring check, and at every start).
1024
+ */
1025
+ exports.RING_SYNC_ENTRIES_MAX = 512;
1026
+ /**
1027
+ * The longest one ring step (an eviction pass, a slice of a walk) holds the
1028
+ * event loop before it yields. Small, because the steps of every ring queued
1029
+ * for the same turn of the loop run back to back: three alert rings starting
1030
+ * together hold it for about three slices.
1031
+ */
1032
+ exports.RING_SLICE_MS = 8;
1033
+ /**
1034
+ * At most this many file-system operations of ring reads (a listing, a stat,
1035
+ * a sidecar read, a delete) in flight at once across every ring in the
1036
+ * process. Each ring's read has one in flight at a time; this caps rings read
1037
+ * together (every ring starts its read when the connector starts). libuv's pool
1038
+ * is 4 threads, shared with segment uploads, sidecar writes and every API
1039
+ * call's address lookup, so the reads never take more than half of it.
1040
+ */
1041
+ exports.RING_IO_IN_FLIGHT_MAX = 2;
1010
1042
  /** First wait before a feed the recorder refused retakes a session; doubles to the max. */
1011
1043
  exports.RETAKE_BACKOFF_BASE_MS = 60000;
1012
1044
  exports.RETAKE_BACKOFF_MAX_MS = 3600000;
@@ -1498,6 +1530,30 @@ function normalizeSegmentRecording(cfg) {
1498
1530
  label,
1499
1531
  };
1500
1532
  }
1533
+ const LEGACY_CAPTURE = Object.freeze({ selectFirst: false, hwDecode: false, keyframesOnly: false });
1534
+ /**
1535
+ * The longest keyframe interval a keyframe-only camera may have. A look reads the
1536
+ * newest decoded frame, and with keyframe-only decode that frame is up to one
1537
+ * interval old, so a longer interval would age every look past the 3 s frame-age
1538
+ * bar. Measured on this camera's own keyframe-only output, never assumed.
1539
+ */
1540
+ exports.KEYFRAME_MAX_INTERVAL_MS = 2000;
1541
+ /**
1542
+ * Timestamp jitter a nominal interval may carry: Texas's 2 s-GOP cameras measure
1543
+ * 1.99-2.09 s between keyframes (recorded segments, 2026-11-17).
1544
+ */
1545
+ exports.KEYFRAME_JITTER_MS = 100;
1546
+ /** Inter-keyframe gaps measured before a camera's keyframe verdict is final. */
1547
+ const KEYFRAME_SAMPLES = 4;
1548
+ /**
1549
+ * When the GPU decode probe runs report-only, after the first open: late enough
1550
+ * to stay clear of the connector's start-up work. The probe encodes and decodes
1551
+ * two 2 s synthetic clips, once per process.
1552
+ */
1553
+ exports.HW_PROBE_REPORT_DELAY_MS = 300000;
1554
+ function sameCapturePlan(a, b) {
1555
+ return a.selectFirst === b.selectFirst && a.hwDecode === b.hwDecode && a.keyframesOnly === b.keyframesOnly;
1556
+ }
1501
1557
  function writeFileAtomic(file, body) {
1502
1558
  const tmp = `${file}.tmp`;
1503
1559
  fs.writeFileSync(tmp, body);
@@ -1505,7 +1561,186 @@ function writeFileAtomic(file, body) {
1505
1561
  }
1506
1562
  function readSidecar(file) {
1507
1563
  try {
1508
- const raw = JSON.parse(fs.readFileSync(file, 'utf8'));
1564
+ return parseSidecar(fs.readFileSync(file, 'utf8'));
1565
+ }
1566
+ catch {
1567
+ return null;
1568
+ }
1569
+ }
1570
+ /** readSidecar, with the read off the event loop. */
1571
+ async function readSidecarOffLoop(file) {
1572
+ try {
1573
+ return parseSidecar(await fs.promises.readFile(file, 'utf8'));
1574
+ }
1575
+ catch {
1576
+ return null;
1577
+ }
1578
+ }
1579
+ /** Binary search: the first position in `items` (sorted by file) whose file is >= `file`. */
1580
+ function ringItemPosition(items, file) {
1581
+ let lo = 0;
1582
+ let hi = items.length;
1583
+ while (lo < hi) {
1584
+ const mid = (lo + hi) >>> 1;
1585
+ if (items[mid].file < file)
1586
+ lo = mid + 1;
1587
+ else
1588
+ hi = mid;
1589
+ }
1590
+ return lo;
1591
+ }
1592
+ /** Insert in name (= capture time) order; a file already present is left as is. */
1593
+ function insertRingItem(items, file, bytes) {
1594
+ if (!items.length || items[items.length - 1].file < file) {
1595
+ items.push({ file, bytes });
1596
+ return;
1597
+ }
1598
+ const at = ringItemPosition(items, file);
1599
+ if (at < items.length && items[at].file === file)
1600
+ return;
1601
+ items.splice(at, 0, { file, bytes });
1602
+ }
1603
+ /** More than `max` entries in `dir` (false when it cannot be read), without listing the rest. */
1604
+ function dirExceeds(dir, max) {
1605
+ let handle = null;
1606
+ try {
1607
+ handle = fs.opendirSync(dir);
1608
+ for (let i = 0; i <= max; i += 1) {
1609
+ if (handle.readSync() === null)
1610
+ return false;
1611
+ }
1612
+ return true;
1613
+ }
1614
+ catch {
1615
+ return false;
1616
+ }
1617
+ finally {
1618
+ try {
1619
+ handle?.closeSync();
1620
+ }
1621
+ catch {
1622
+ /* already closed */
1623
+ }
1624
+ }
1625
+ }
1626
+ /**
1627
+ * Every name in `dir`, read a batch at a time off the event loop, handed to
1628
+ * `onName` as it is read; nothing when the directory cannot be read.
1629
+ */
1630
+ async function listDirOffLoop(dir, onName) {
1631
+ let handle;
1632
+ try {
1633
+ handle = await fs.promises.opendir(dir, { bufferSize: 256 });
1634
+ }
1635
+ catch {
1636
+ return;
1637
+ }
1638
+ try {
1639
+ for await (const entry of handle)
1640
+ onName(entry.name);
1641
+ }
1642
+ catch {
1643
+ /* a listing cut short keeps what it read; the next check reads the rest */
1644
+ }
1645
+ }
1646
+ /** Binary search in names sorted by code unit. */
1647
+ function sortedHas(names, name) {
1648
+ let lo = 0;
1649
+ let hi = names.length;
1650
+ while (lo < hi) {
1651
+ const mid = (lo + hi) >>> 1;
1652
+ if (names[mid] < name)
1653
+ lo = mid + 1;
1654
+ else
1655
+ hi = mid;
1656
+ }
1657
+ return lo < names.length && names[lo] === name;
1658
+ }
1659
+ function yieldToLoop() {
1660
+ return new Promise((resolve) => setImmediate(resolve));
1661
+ }
1662
+ let ringIoInFlight = 0;
1663
+ const ringIoWaiting = [];
1664
+ /**
1665
+ * Run one ring-read file-system operation once fewer than
1666
+ * RING_IO_IN_FLIGHT_MAX are in flight across every ring in the process; the
1667
+ * rings waiting take turns in the order they asked.
1668
+ */
1669
+ async function ringIo(op) {
1670
+ if (ringIoInFlight < exports.RING_IO_IN_FLIGHT_MAX) {
1671
+ ringIoInFlight += 1;
1672
+ }
1673
+ else {
1674
+ // The slot is handed over by the release below, still counted.
1675
+ await new Promise((resolve) => ringIoWaiting.push(resolve));
1676
+ }
1677
+ try {
1678
+ return await op();
1679
+ }
1680
+ finally {
1681
+ const next = ringIoWaiting.shift();
1682
+ if (next)
1683
+ next();
1684
+ else
1685
+ ringIoInFlight -= 1;
1686
+ }
1687
+ }
1688
+ /** Ring-read operations in flight now, and those waiting for a turn (tests). */
1689
+ function ringIoInFlightForTests() {
1690
+ return { now: ringIoInFlight, waiting: ringIoWaiting.length };
1691
+ }
1692
+ exports.ringIoInFlightForTests = ringIoInFlightForTests;
1693
+ /**
1694
+ * Sort names without holding the event loop for longer than a slice. NTFS
1695
+ * lists a directory in name order, so a store PC's listing costs one pass to
1696
+ * confirm; any other order (ext4 hashes it) is sorted in runs that are merged
1697
+ * a slice at a time: 60,480 names in hash order take ~140 ms in one sort().
1698
+ */
1699
+ async function sortOffLoop(names) {
1700
+ let ordered = true;
1701
+ for (let i = 1; i < names.length && ordered; i += 1)
1702
+ ordered = names[i - 1] <= names[i];
1703
+ if (ordered)
1704
+ return names;
1705
+ const RUN = 2048;
1706
+ let runs = [];
1707
+ for (let i = 0; i < names.length; i += RUN) {
1708
+ runs.push(names.slice(i, i + RUN).sort());
1709
+ await yieldToLoop();
1710
+ }
1711
+ while (runs.length > 1) {
1712
+ const merged = [];
1713
+ for (let r = 0; r < runs.length; r += 2) {
1714
+ const a = runs[r];
1715
+ const b = runs[r + 1];
1716
+ if (!b) {
1717
+ merged.push(a);
1718
+ continue;
1719
+ }
1720
+ const out = new Array(a.length + b.length);
1721
+ let i = 0;
1722
+ let j = 0;
1723
+ let k = 0;
1724
+ let sliceStartMs = perf_hooks_1.performance.now();
1725
+ while (i < a.length || j < b.length) {
1726
+ out[k] = j >= b.length || (i < a.length && a[i] <= b[j]) ? a[i++] : b[j++];
1727
+ k += 1;
1728
+ if ((k & 1023) === 0 && perf_hooks_1.performance.now() - sliceStartMs >= exports.RING_SLICE_MS) {
1729
+ await yieldToLoop();
1730
+ sliceStartMs = perf_hooks_1.performance.now();
1731
+ }
1732
+ }
1733
+ merged.push(out);
1734
+ }
1735
+ runs = merged;
1736
+ await yieldToLoop();
1737
+ }
1738
+ return runs[0] ?? [];
1739
+ }
1740
+ exports.sortOffLoop = sortOffLoop;
1741
+ function parseSidecar(text) {
1742
+ try {
1743
+ const raw = JSON.parse(text);
1509
1744
  const nums = [raw.startSec, raw.endSec, raw.captureStartMs, raw.captureEndMs, raw.bytes];
1510
1745
  if (raw.version !== 1 || nums.some((n) => typeof n !== 'number' || !Number.isFinite(n)))
1511
1746
  return null;
@@ -1543,7 +1778,9 @@ function errorText(err) {
1543
1778
  *
1544
1779
  * Events: `'segment'` (RecordedSegment) for every closed recording segment,
1545
1780
  * `'segment_evicted'` (EvictedSegment) when the ring deletes one undelivered,
1546
- * and `'opening'` at the start of every `open()`.
1781
+ * `'ring_indexed'` (RingIndexedEvent) when the ring's figures were just read
1782
+ * from disk (before anything is evicted against them), and `'opening'` at the
1783
+ * start of every `open()`.
1547
1784
  */
1548
1785
  class RTSPStreamCameraProvider extends events_1.EventEmitter {
1549
1786
  constructor(config) {
@@ -1585,13 +1822,25 @@ class RTSPStreamCameraProvider extends events_1.EventEmitter {
1585
1822
  // ── segment recording ────────────────────────────────────────────────────
1586
1823
  this.segmentConfig = null;
1587
1824
  /**
1588
- * The ring's closed segments, oldest first: rebuilt from disk at most every
1825
+ * The ring's closed segments, oldest first: checked against disk about every
1589
1826
  * `RING_RESYNC_MS` and kept current by every move in between, so a ring of
1590
1827
  * thousands of 10-s segments is not re-listed and re-stat'ed at every close.
1591
- * Files a consumer deleted since the last rebuild are dropped when the
1592
- * eviction walk reaches them (ENOENT) and by the next rebuild.
1828
+ * Files a consumer deleted since the last check are dropped when the
1829
+ * eviction walk reaches them (ENOENT) and by the next check.
1593
1830
  */
1594
1831
  this.ringIndex = null;
1832
+ /**
1833
+ * A walk of the ring off the event loop (a big ring's first index, its
1834
+ * periodic check, or its open-time recovery), with what moved in and out of
1835
+ * the ring while it ran; the current index serves until it swaps in.
1836
+ */
1837
+ this.ringWalk = null;
1838
+ /** Bumped by close(): a walk from before it never swaps in. */
1839
+ this.ringGeneration = 0;
1840
+ /** The next slice of an eviction that ran out of its RING_SLICE_MS. */
1841
+ this.ringEvictImmediate = null;
1842
+ /** The directory whose ring figures (`ringSegments`, `ringBytes`) were last read from disk. */
1843
+ this.ringIndexedDir = null;
1595
1844
  /** 0 = an ordinary feed; higher holds its persistent session ahead of lower ones. */
1596
1845
  this.sessionPriority = 0;
1597
1846
  /** No live review needs this feed (setIdle); with no recording it runs per-grab. */
@@ -1670,6 +1919,20 @@ class RTSPStreamCameraProvider extends events_1.EventEmitter {
1670
1919
  this.lastErrorMessage = null;
1671
1920
  /** Resolvers waiting for the next frame. Woken by `admitFrame`. */
1672
1921
  this.frameWaiters = [];
1922
+ // ── capture pipeline (plan v7 W8) ────────────────────────────────────────
1923
+ this.captureMode = 'legacy';
1924
+ /** The host's GPU decode probe, once it has answered. */
1925
+ this.hwProbe = null;
1926
+ this.hwProbeStarted = false;
1927
+ /** The report-only probe's start timer (see `hardwareDecodeProbeDelayMs`). */
1928
+ this.hwProbeTimer = null;
1929
+ /** This feed's GPU decode stopped working after the probe passed: decode in software. */
1930
+ this.hwDecodeFailure = null;
1931
+ /** The keyframe-only verdict, measured on this camera's own keyframe-only output. */
1932
+ this.keyframes = { verdict: 'unmeasured', intervalMs: null, lastAtMs: null, gaps: [], timer: null };
1933
+ this.captureReconfigures = 0;
1934
+ /** When the frame `getFrame` last returned arrived: honest capture time for keyframe-only looks. */
1935
+ this.lastServedFrameAtMs = null;
1673
1936
  if (!config?.rtspUrl)
1674
1937
  throw new Error('rtspUrl is required for RTSPStreamCameraProvider');
1675
1938
  this.rtspUrl = config.rtspUrl;
@@ -1700,6 +1963,7 @@ class RTSPStreamCameraProvider extends events_1.EventEmitter {
1700
1963
  this.persistentRequested = config.persistent !== false;
1701
1964
  this.spawnFn = config.spawnFn ?? child_process_1.spawn;
1702
1965
  this.now = config.now ?? Date.now;
1966
+ this.random = config.random ?? Math.random;
1703
1967
  this.onLog = config.onLog;
1704
1968
  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)));
1705
1969
  this.splitter = new MjpegFrameSplitter(Math.max(1, Math.trunc(config.maxFrameBytes ?? DEFAULT_MAX_FRAME_BYTES)));
@@ -1722,6 +1986,11 @@ class RTSPStreamCameraProvider extends events_1.EventEmitter {
1722
1986
  // No filesystem work here: a provider that is built and never opened (a
1723
1987
  // test, a manager that is configured and then discarded) must leave no trace.
1724
1988
  this.segmentConfig = normalizeSegmentRecording(config.segmentRecording ?? null);
1989
+ this.hardwareDecodeProbe = config.hardwareDecodeProbe ?? RTSPCameraProvider_1.hardwareDecodeProbeFor;
1990
+ this.hwProbeDelayMs = Number.isFinite(config.hardwareDecodeProbeDelayMs)
1991
+ ? Math.trunc(config.hardwareDecodeProbeDelayMs) : exports.HW_PROBE_REPORT_DELAY_MS;
1992
+ if (config.capturePipeline !== undefined)
1993
+ this.setCapturePipeline(config.capturePipeline);
1725
1994
  }
1726
1995
  on(event, listener) {
1727
1996
  return super.on(event, listener);
@@ -1763,6 +2032,57 @@ class RTSPStreamCameraProvider extends events_1.EventEmitter {
1763
2032
  // retakes its session, and one that stops gives it back.
1764
2033
  this.reconcileIdle();
1765
2034
  }
2035
+ /**
2036
+ * How look frames are made (plan v7 W8, `CapturePipelineMode`). A change the
2037
+ * running session's argv does not already satisfy restarts it once, after its
2038
+ * first frame, exactly as a recording change does; the restart is counted in
2039
+ * `capture.reconfigures`, never as a fault. An unknown mode is ignored.
2040
+ */
2041
+ setCapturePipeline(mode) {
2042
+ if (!RTSPCameraProvider_1.CAPTURE_PIPELINE_MODES.includes(mode) || mode === this.captureMode)
2043
+ return;
2044
+ this.captureMode = mode;
2045
+ if (mode === 'select_first_hw' || mode === 'keyframes_hw')
2046
+ this.startHardwareDecodeProbe();
2047
+ this.reconcileCapture();
2048
+ }
2049
+ /**
2050
+ * Run this host's GPU decode probe once (memoized per ffmpeg binary, so one real
2051
+ * probe per process): started by a `_hw` mode, or report-only after open (see
2052
+ * `hardwareDecodeProbeDelayMs`). The probe decodes its own synthetic clips, never
2053
+ * a camera; `planCapture` uses the answer only under a `_hw` mode.
2054
+ */
2055
+ startHardwareDecodeProbe() {
2056
+ if (this.hwProbeTimer) {
2057
+ clearTimeout(this.hwProbeTimer);
2058
+ this.hwProbeTimer = null;
2059
+ }
2060
+ if (this.hwProbeStarted)
2061
+ return;
2062
+ this.hwProbeStarted = true;
2063
+ this.hardwareDecodeProbe(this.ffmpegPath).then((probe) => {
2064
+ this.hwProbe = probe;
2065
+ // Logged where it decides something; a report-only answer is read off capture stats.
2066
+ if (this.captureMode === 'select_first_hw' || this.captureMode === 'keyframes_hw') {
2067
+ this.log(probe.state === 'passed' ? 'info' : 'warn', `GPU decode probe: ${probe.state} (h264 ${probe.h264}, hevc ${probe.hevc}, ${probe.durationMs} ms)` +
2068
+ (probe.detail ? `: ${probe.detail}` : ''));
2069
+ }
2070
+ this.reconcileCapture();
2071
+ }, () => undefined);
2072
+ }
2073
+ getCapturePipeline() {
2074
+ return this.captureMode;
2075
+ }
2076
+ /**
2077
+ * When the frame the last `getFrame()` returned arrived from ffmpeg, for a
2078
+ * keyframe-only session only (null otherwise). A keyframe-only look reads a
2079
+ * frame up to one keyframe interval old, and stamping it with the time it was
2080
+ * read would hide that age; every other mode serves a frame at most one
2081
+ * look interval old and keeps the stamp it always had.
2082
+ */
2083
+ servedFrameCapturedAtMs() {
2084
+ return this.session?.capture.keyframesOnly ? this.lastServedFrameAtMs : null;
2085
+ }
1766
2086
  /**
1767
2087
  * Rank this feed for its recorder's persistent sessions. 0 is an ordinary
1768
2088
  * feed; the connector raises a camera with an enabled alert to 1, because
@@ -1784,6 +2104,14 @@ class RTSPStreamCameraProvider extends events_1.EventEmitter {
1784
2104
  getSessionPriority() {
1785
2105
  return this.sessionPriority;
1786
2106
  }
2107
+ /**
2108
+ * The ring's closed segments, oldest first, from its in-memory index: no
2109
+ * listing, no stat. Null until the ring's first read lands.
2110
+ */
2111
+ ringFiles() {
2112
+ const index = this.currentRingIndex();
2113
+ return index ? index.items.map((item) => item.file) : null;
2114
+ }
1787
2115
  /**
1788
2116
  * Take a segment another recorder of this camera closed into THIS feed's ring
1789
2117
  * — the camera's main-stream recorder (`MainStreamSession`), which records
@@ -1899,6 +2227,14 @@ class RTSPStreamCameraProvider extends events_1.EventEmitter {
1899
2227
  if (this.opened)
1900
2228
  return;
1901
2229
  const generation = ++this.openGeneration;
2230
+ if (!this.hwProbeStarted && this.hwProbeTimer === null && this.hwProbeDelayMs >= 0) {
2231
+ this.hwProbeTimer = setTimeout(() => {
2232
+ this.hwProbeTimer = null;
2233
+ this.startHardwareDecodeProbe();
2234
+ }, this.hwProbeDelayMs);
2235
+ if (typeof this.hwProbeTimer.unref === 'function')
2236
+ this.hwProbeTimer.unref();
2237
+ }
1902
2238
  // A controller attached at construction starts here, so a provider that is
1903
2239
  // built and never opened costs nothing. Its listener may set the recording
1904
2240
  // config synchronously, which the first session below then carries.
@@ -2100,7 +2436,7 @@ class RTSPStreamCameraProvider extends events_1.EventEmitter {
2100
2436
  const fresh = this.takeFreshFrame();
2101
2437
  if (fresh)
2102
2438
  return fresh;
2103
- const arrived = await this.waitForFrame(this.frameWaitMs);
2439
+ const arrived = await this.waitForFrame(this.frameWaitForCapture());
2104
2440
  // The session was handed back (the feed went idle) while this call waited.
2105
2441
  if (this.fallback)
2106
2442
  return this.fallbackFrame();
@@ -2155,9 +2491,24 @@ class RTSPStreamCameraProvider extends events_1.EventEmitter {
2155
2491
  this.openGeneration += 1;
2156
2492
  this.startingUp = false;
2157
2493
  this.opened = false;
2494
+ if (this.hwProbeTimer) {
2495
+ clearTimeout(this.hwProbeTimer);
2496
+ this.hwProbeTimer = null;
2497
+ }
2158
2498
  this.leaveSessionQueue();
2159
- // A re-open rebuilds the ring index from disk once.
2160
- this.ringIndex = null;
2499
+ // A re-open checks the ring against disk once, at its next eviction pass;
2500
+ // the index serves until then. A walk under way is dropped, and a recovery
2501
+ // it had not finished runs again at the next open.
2502
+ this.ringGeneration += 1;
2503
+ if (this.ringWalk?.recover)
2504
+ this.segmentsRecoveredFor = null;
2505
+ this.ringWalk = null;
2506
+ if (this.ringEvictImmediate) {
2507
+ clearImmediate(this.ringEvictImmediate);
2508
+ this.ringEvictImmediate = null;
2509
+ }
2510
+ if (this.ringIndex)
2511
+ this.ringIndex.resyncAtMs = this.now();
2161
2512
  if (this.restartTimer) {
2162
2513
  clearTimeout(this.restartTimer);
2163
2514
  this.restartTimer = null;
@@ -2213,6 +2564,14 @@ class RTSPStreamCameraProvider extends events_1.EventEmitter {
2213
2564
  frameAgeMs: newest ? this.now() - newest.atMs : null,
2214
2565
  lastErrorMessage: this.lastErrorMessage,
2215
2566
  segments: this.segmentStats(),
2567
+ capture: {
2568
+ mode: this.captureMode,
2569
+ session: this.session ? { ...this.session.capture } : null,
2570
+ hardwareDecode: this.hwProbe ? { ...this.hwProbe } : null,
2571
+ hardwareDecodeFailure: this.hwDecodeFailure,
2572
+ keyframes: { verdict: this.keyframes.verdict, intervalMs: this.keyframes.intervalMs },
2573
+ reconfigures: this.captureReconfigures,
2574
+ },
2216
2575
  };
2217
2576
  }
2218
2577
  // ── internals ────────────────────────────────────────────────────────────
@@ -2420,6 +2779,7 @@ class RTSPStreamCameraProvider extends events_1.EventEmitter {
2420
2779
  return null;
2421
2780
  this.lastServedSeq = newest.seq;
2422
2781
  this.framesServed += 1;
2782
+ this.lastServedFrameAtMs = newest.atMs;
2423
2783
  return newest.bytes;
2424
2784
  }
2425
2785
  waitForFrame(timeoutMs) {
@@ -2459,6 +2819,8 @@ class RTSPStreamCameraProvider extends events_1.EventEmitter {
2459
2819
  return; // counted as rejected inside the ring
2460
2820
  this.framesDecoded += 1;
2461
2821
  this.lastFrameAtMs = at;
2822
+ if (this.session)
2823
+ this.noteKeyframe(this.session, at);
2462
2824
  this.wakeWaiters();
2463
2825
  }
2464
2826
  /**
@@ -2514,11 +2876,12 @@ class RTSPStreamCameraProvider extends events_1.EventEmitter {
2514
2876
  };
2515
2877
  }
2516
2878
  /**
2517
- * The session's argv. With no `segmentOutput` it is byte-identical to the
2518
- * look-only session this provider has always run; with one, the second
2519
- * output (`buildSegmentOutputArgs`) follows `pipe:1`.
2879
+ * The session's argv. With no `segmentOutput` and the `legacy` capture plan
2880
+ * it is byte-identical to the look-only session this provider has always run;
2881
+ * with a segment output, the second output (`buildSegmentOutputArgs`) follows
2882
+ * `pipe:1`. `capture` defaults to what the current mode plans.
2520
2883
  */
2521
- buildArgs(segmentOutput) {
2884
+ buildArgs(segmentOutput, capture = this.planCapture()) {
2522
2885
  const input = this.buildInputArgs();
2523
2886
  return {
2524
2887
  args: [
@@ -2527,18 +2890,26 @@ class RTSPStreamCameraProvider extends events_1.EventEmitter {
2527
2890
  // DEFAULT_DECODER_THREADS: one thread is both smaller and faster here.
2528
2891
  '-threads',
2529
2892
  String(this.decoderThreads),
2893
+ // Plan v7 W8 (`CapturePipelineMode`). Decoder options, before the input,
2894
+ // so they bind to the decoder only: the segment output copies the
2895
+ // input's packets and never decodes, so its bytes do not move.
2896
+ ...(capture.hwDecode ? ['-hwaccel', 'd3d11va'] : []),
2897
+ ...(capture.keyframesOnly ? ['-skip_frame', 'nokey'] : []),
2530
2898
  ...input.args,
2531
2899
  '-an',
2532
- // crop (mosaic tile) FIRST, then the aspect-preserving scale+pad — the
2533
- // SAME carve math as the one-shot path, imported rather than restated,
2534
- // so a persistent feed and a per-grab feed can never disagree about
2535
- // what a frame of this camera looks like.
2900
+ // crop (mosaic tile), then the aspect-preserving scale+pad — the SAME
2901
+ // carve math as the one-shot path, imported rather than restated, so a
2902
+ // persistent feed and a per-grab feed can never disagree about what a
2903
+ // frame of this camera looks like.
2536
2904
  //
2537
- // `fps` LAST and deliberately not an output `-r`: the filter is driven
2538
- // by arriving input frames, so a frozen source emits nothing instead of
2539
- // duplicating the last frame into a lie about freshness.
2905
+ // The look rate is a `select`, deliberately not an output `-r`: the
2906
+ // filter is driven by arriving input frames, so a frozen source emits
2907
+ // nothing instead of duplicating the last frame into a lie about
2908
+ // freshness. Legacy runs it LAST; select_first runs it FIRST, so only
2909
+ // the frames a look can read are carved (same frames: `select` reads
2910
+ // only timestamps, which crop/scale/pad pass through).
2540
2911
  '-vf',
2541
- `${(0, RTSPCameraProvider_1.buildVideoFilter)(this.width, this.height, this.crop)},select='isnan(prev_selected_t)+gte(t-prev_selected_t,${1 / this.streamFps}-0.000001)'`,
2912
+ (0, RTSPCameraProvider_1.buildLookFilter)(this.width, this.height, this.crop, 1 / this.streamFps, capture.selectFirst),
2542
2913
  ...(this.ffmpegMajorVersion >= 5 ? ['-fps_mode', 'passthrough'] : ['-vsync', '0']),
2543
2914
  '-f',
2544
2915
  'mjpeg',
@@ -2564,6 +2935,7 @@ class RTSPStreamCameraProvider extends events_1.EventEmitter {
2564
2935
  startSession() {
2565
2936
  return new Promise((resolve, reject) => {
2566
2937
  const recording = this.prepareSessionRecording();
2938
+ const capture = this.planCapture();
2567
2939
  const { args, cleanup } = this.buildArgs(recording
2568
2940
  ? {
2569
2941
  csvPath: recording.csvPath,
@@ -2573,9 +2945,14 @@ class RTSPStreamCameraProvider extends events_1.EventEmitter {
2573
2945
  minSegDuration: recording.plan.minSegDuration,
2574
2946
  audio: recording.plan.audio,
2575
2947
  }
2576
- : null);
2948
+ : null, capture);
2577
2949
  this.sessionStarts += 1;
2578
2950
  this.splitter.reset();
2951
+ // A keyframe gap is measured within one session, never across a restart.
2952
+ this.keyframes.lastAtMs = null;
2953
+ if (this.keyframes.timer)
2954
+ clearTimeout(this.keyframes.timer);
2955
+ this.keyframes.timer = null;
2579
2956
  let proc;
2580
2957
  try {
2581
2958
  proc = this.spawnFn(this.ffmpegPath, args, { stdio: ['ignore', 'pipe', 'pipe'] });
@@ -2595,6 +2972,7 @@ class RTSPStreamCameraProvider extends events_1.EventEmitter {
2595
2972
  probe: new InputStreamProbe(),
2596
2973
  streamInfo: null,
2597
2974
  recording,
2975
+ capture,
2598
2976
  superseded: false,
2599
2977
  detached: false,
2600
2978
  ended: false,
@@ -2639,6 +3017,7 @@ class RTSPStreamCameraProvider extends events_1.EventEmitter {
2639
3017
  proc.stderr?.on('data', (chunk) => {
2640
3018
  const text = chunk.toString();
2641
3019
  stderrBuffer.append(text);
3020
+ this.noteCaptureStderr(session, text);
2642
3021
  if (!session.probe.done) {
2643
3022
  const info = session.probe.push(text);
2644
3023
  if (info)
@@ -2861,8 +3240,11 @@ class RTSPStreamCameraProvider extends events_1.EventEmitter {
2861
3240
  return;
2862
3241
  const want = this.planRecording();
2863
3242
  const have = session.recording ? session.recording.plan : null;
2864
- if (this.sessionSatisfies(have, want))
3243
+ if (this.sessionSatisfies(have, want)) {
3244
+ // Recording is in line; the look output may still need a change (plan v7 W8).
3245
+ this.reconcileCapture();
2865
3246
  return;
3247
+ }
2866
3248
  this.segCounters.reconfigures += 1;
2867
3249
  this.log('info', want
2868
3250
  ? `RTSP stream session restarting to record ${want.segmentSeconds}s segments` +
@@ -2873,6 +3255,129 @@ class RTSPStreamCameraProvider extends events_1.EventEmitter {
2873
3255
  this.session = null;
2874
3256
  this.killSession(session);
2875
3257
  }
3258
+ /** What the next session's look output should be (`CapturePipelineMode`). */
3259
+ planCapture() {
3260
+ const mode = this.captureMode;
3261
+ if (mode === 'legacy')
3262
+ return LEGACY_CAPTURE;
3263
+ const codec = this.streamInfo?.codec ?? null;
3264
+ const probe = this.hwProbe;
3265
+ // The GPU decodes only a codec this host's probe decoded there, and only once
3266
+ // ffmpeg has named this camera's codec: a first session decodes in software.
3267
+ const hwDecode = (mode === 'select_first_hw' || mode === 'keyframes_hw') && this.hwDecodeFailure === null
3268
+ && probe?.state === 'passed' && (codec === 'h264' ? probe.h264 : codec === 'hevc' ? probe.hevc : false);
3269
+ const keyframesOnly = (mode === 'keyframes' || mode === 'keyframes_hw') && this.keyframes.verdict !== 'too_long';
3270
+ return { selectFirst: true, hwDecode, keyframesOnly };
3271
+ }
3272
+ /**
3273
+ * Bring the live session's look output in line with `planCapture` — by
3274
+ * restarting it once, after its first frame, never with another reconfigure
3275
+ * in flight: the same rules as a recording change, counted apart.
3276
+ */
3277
+ reconcileCapture() {
3278
+ const session = this.session;
3279
+ if (!session || !this.opened || this.fallback || this.startingUp)
3280
+ return;
3281
+ if (session.firstFrameAtMs === null || this.reconfigurePendingFor)
3282
+ return;
3283
+ const want = this.planCapture();
3284
+ if (sameCapturePlan(session.capture, want))
3285
+ return;
3286
+ this.captureReconfigures += 1;
3287
+ this.log('info', `RTSP stream session restarting to capture with ${want.selectFirst ? 'select first' : 'legacy filters'}`
3288
+ + `${want.keyframesOnly ? ', keyframes only' : ''}${want.hwDecode ? ', GPU decode (d3d11va)' : ''}`);
3289
+ session.superseded = true;
3290
+ this.reconfigurePendingFor = session;
3291
+ this.session = null;
3292
+ this.killSession(session);
3293
+ }
3294
+ /** How long `getFrame` waits for a new frame: one keyframe interval more on a keyframe-only session. */
3295
+ frameWaitForCapture() {
3296
+ return this.session?.capture.keyframesOnly
3297
+ ? Math.max(this.frameWaitMs, exports.KEYFRAME_MAX_INTERVAL_MS + this.frameWaitMs)
3298
+ : this.frameWaitMs;
3299
+ }
3300
+ /**
3301
+ * Measure this camera's keyframe interval on its own keyframe-only output: every
3302
+ * one of KEYFRAME_SAMPLES gaps at or under KEYFRAME_MAX_INTERVAL_MS (plus
3303
+ * KEYFRAME_JITTER_MS) keeps it. A gap past 1.5x the bar at any time, or three
3304
+ * gaps in a row past the bar once kept, puts the camera back on full decode
3305
+ * (select first) for the rest of this provider's life: a "smart" encoder that
3306
+ * stretches its GOP in a still scene (Texas cams 3/5/7/8/10/11: 12-28 s gaps
3307
+ * between 2-4 s ones) would otherwise age every look past the 3 s bar while it
3308
+ * waits. Called for every frame of the live session.
3309
+ */
3310
+ noteKeyframe(session, atMs) {
3311
+ if (!session.capture.keyframesOnly)
3312
+ return;
3313
+ const k = this.keyframes;
3314
+ if (k.verdict === 'unmeasured')
3315
+ k.verdict = 'measuring';
3316
+ if (k.lastAtMs !== null && atMs >= k.lastAtMs) {
3317
+ const gap = atMs - k.lastAtMs;
3318
+ if (k.verdict === 'measuring') {
3319
+ k.gaps.push(gap);
3320
+ if (k.gaps.length >= KEYFRAME_SAMPLES) {
3321
+ k.intervalMs = Math.max(...k.gaps);
3322
+ this.keyframeVerdict(k.intervalMs <= exports.KEYFRAME_MAX_INTERVAL_MS + exports.KEYFRAME_JITTER_MS ? 'kept' : 'too_long');
3323
+ }
3324
+ }
3325
+ else if (k.verdict === 'kept') {
3326
+ if (gap > exports.KEYFRAME_MAX_INTERVAL_MS * 1.5) {
3327
+ k.intervalMs = gap;
3328
+ this.keyframeVerdict('too_long');
3329
+ }
3330
+ else {
3331
+ k.gaps = gap > exports.KEYFRAME_MAX_INTERVAL_MS + exports.KEYFRAME_JITTER_MS ? [...k.gaps, gap].slice(-3) : [];
3332
+ if (k.gaps.length >= 3)
3333
+ this.keyframeVerdict('too_long');
3334
+ }
3335
+ }
3336
+ }
3337
+ k.lastAtMs = atMs;
3338
+ if (k.timer)
3339
+ clearTimeout(k.timer);
3340
+ k.timer = null;
3341
+ if (k.verdict === 'measuring') {
3342
+ k.timer = setTimeout(() => {
3343
+ k.timer = null;
3344
+ if (k.verdict === 'measuring' && this.session === session)
3345
+ this.keyframeVerdict('too_long');
3346
+ }, Math.round(exports.KEYFRAME_MAX_INTERVAL_MS * 1.5));
3347
+ if (typeof k.timer.unref === 'function')
3348
+ k.timer.unref();
3349
+ }
3350
+ }
3351
+ keyframeVerdict(verdict) {
3352
+ const k = this.keyframes;
3353
+ if (k.timer)
3354
+ clearTimeout(k.timer);
3355
+ k.timer = null;
3356
+ k.verdict = verdict;
3357
+ k.gaps = [];
3358
+ this.log(verdict === 'kept' ? 'info' : 'warn', verdict === 'kept'
3359
+ ? `keyframe-only decode kept: keyframes every ${k.intervalMs} ms`
3360
+ : `keyframe-only decode off for this camera: keyframes further apart than ${exports.KEYFRAME_MAX_INTERVAL_MS} ms`
3361
+ + (k.intervalMs !== null ? ` (${k.intervalMs} ms)` : ''));
3362
+ if (verdict === 'too_long')
3363
+ this.reconcileCapture();
3364
+ }
3365
+ /**
3366
+ * A GPU decode that stopped working on this feed after the probe passed —
3367
+ * ffmpeg says so on stderr and falls back to software, or errors. The feed
3368
+ * decodes in software for the rest of this provider's life.
3369
+ */
3370
+ noteCaptureStderr(session, text) {
3371
+ if (!session.capture.hwDecode || this.hwDecodeFailure !== null)
3372
+ return;
3373
+ const m = /(Failed setup for format d3d11[^\n]*|hwaccel initialisation returned error[^\n]*|Failed to (?:create|get) (?:D3D11|decoder)[^\n]*)/i.exec(text);
3374
+ if (!m)
3375
+ return;
3376
+ this.hwDecodeFailure = (0, RTSPCameraProvider_1.summarizeFfmpegStderr)(m[1], 200);
3377
+ this.log('warn', `GPU decode failed on this feed; decoding in software: ${this.hwDecodeFailure}`);
3378
+ if (this.session === session)
3379
+ this.reconcileCapture();
3380
+ }
2876
3381
  onSessionFirstFrame(session) {
2877
3382
  session.firstFrameAtMs = this.now();
2878
3383
  this.reconcileRecording();
@@ -3391,8 +3896,20 @@ class RTSPStreamCameraProvider extends events_1.EventEmitter {
3391
3896
  catch {
3392
3897
  return; // nothing recorded here yet
3393
3898
  }
3394
- // closed/ FIRST: recovering a work directory below moves files INTO it.
3395
3899
  const closedDir = path.join(cfg.dir, exports.CLOSED_SEGMENTS_DIRNAME);
3900
+ const running = this.ringWalk && this.ringWalk.dir === cfg.dir ? this.ringWalk : null;
3901
+ if (running || this.ringIsBig(cfg.dir)) {
3902
+ // A big ring (an alert camera's week of 10-s segments): its closed
3903
+ // segments are handed out by a walk off the event loop. The walk is
3904
+ // registered first, so what the work directories move in below is
3905
+ // already handed out and the walk skips it; they are recovered now,
3906
+ // before this process's first session writes a work directory of its own.
3907
+ const walk = running ?? this.startRingWalk(cfg.dir, true);
3908
+ walk.recover = true;
3909
+ this.recoverWorkDirs(cfg.dir, names);
3910
+ return;
3911
+ }
3912
+ // closed/ FIRST: recovering a work directory below moves files INTO it.
3396
3913
  let closed = [];
3397
3914
  try {
3398
3915
  closed = fs.readdirSync(closedDir).sort();
@@ -3465,21 +3982,25 @@ class RTSPStreamCameraProvider extends events_1.EventEmitter {
3465
3982
  this.countSegment(segment);
3466
3983
  this.emitSegment(segment);
3467
3984
  }
3985
+ this.recoverWorkDirs(cfg.dir, names);
3986
+ this.enforceRing();
3987
+ }
3988
+ /** Every session work directory an earlier process left under `dir` (never the live one's). */
3989
+ recoverWorkDirs(dir, names) {
3468
3990
  const live = this.session?.recording?.workDir ?? null;
3469
- for (const name of names.sort()) {
3991
+ for (const name of [...names].sort()) {
3470
3992
  if (!name.startsWith(SESSION_WORKDIR_PREFIX))
3471
3993
  continue;
3472
- const workDir = path.join(cfg.dir, name);
3994
+ const workDir = path.join(dir, name);
3473
3995
  if (workDir === live)
3474
3996
  continue;
3475
3997
  try {
3476
- this.recoverWorkDir(cfg.dir, workDir);
3998
+ this.recoverWorkDir(dir, workDir);
3477
3999
  }
3478
4000
  catch (err) {
3479
4001
  this.segCounters.lastError = `segment recovery: ${errorText(err)}`;
3480
4002
  }
3481
4003
  }
3482
- this.enforceRing();
3483
4004
  }
3484
4005
  recoverWorkDir(dir, workDir) {
3485
4006
  let text = '';
@@ -3539,7 +4060,21 @@ class RTSPStreamCameraProvider extends events_1.EventEmitter {
3539
4060
  if (!leftBehind)
3540
4061
  this.removeWorkDir(workDir, true);
3541
4062
  }
3542
- /** List and stat the ring once; every close until the next rebuild updates the result in memory. */
4063
+ /** The ring index of the configured directory, when one is in. */
4064
+ currentRingIndex() {
4065
+ const cfg = this.segmentConfig;
4066
+ const index = this.ringIndex;
4067
+ return cfg && index && index.dir === cfg.dir ? index : null;
4068
+ }
4069
+ /** A ring too big to list and stat in one synchronous pass (RING_SYNC_ENTRIES_MAX). */
4070
+ ringIsBig(dir) {
4071
+ return dirExceeds(path.join(dir, exports.CLOSED_SEGMENTS_DIRNAME), exports.RING_SYNC_ENTRIES_MAX);
4072
+ }
4073
+ /**
4074
+ * List and stat a small ring in one synchronous pass and swap it in; every
4075
+ * close until the next check updates it in memory. A big ring is read by
4076
+ * `startRingWalk` instead.
4077
+ */
3543
4078
  rebuildRingIndex(dir) {
3544
4079
  const closedDir = path.join(dir, exports.CLOSED_SEGMENTS_DIRNAME);
3545
4080
  let names;
@@ -3559,23 +4094,274 @@ class RTSPStreamCameraProvider extends events_1.EventEmitter {
3559
4094
  /* delivered and deleted under us */
3560
4095
  }
3561
4096
  }
3562
- this.ringIndex = { dir, items, rebuiltAtMs: this.now() };
4097
+ this.installRingIndex(dir, items);
3563
4098
  return items;
3564
4099
  }
4100
+ /**
4101
+ * Swap in a ring index read from disk, due its next check RING_RESYNC_MS
4102
+ * (jittered by RING_RESYNC_JITTER) from now, and announce the ring's figures.
4103
+ * `'ring_indexed'` fires BEFORE anything is evicted against them, so a caller
4104
+ * that sizes the ring from the bytes it holds (the box buffer's share)
4105
+ * re-sizes it first.
4106
+ */
4107
+ installRingIndex(dir, items) {
4108
+ const nowMs = this.now();
4109
+ const raw = this.random();
4110
+ const draw = Number.isFinite(raw) ? Math.min(1, Math.max(0, raw)) : 0.5;
4111
+ const spread = 1 - exports.RING_RESYNC_JITTER + 2 * exports.RING_RESYNC_JITTER * draw;
4112
+ this.ringIndex = { dir, items, rebuiltAtMs: nowMs, resyncAtMs: nowMs + Math.floor(exports.RING_RESYNC_MS * spread) };
4113
+ this.ringIndexedDir = dir;
4114
+ let bytes = 0;
4115
+ for (const item of items)
4116
+ bytes += item.bytes;
4117
+ this.segCounters.ringSegments = items.length;
4118
+ this.segCounters.ringBytes = bytes;
4119
+ try {
4120
+ this.emit('ring_indexed', { dir, segments: items.length, bytes });
4121
+ }
4122
+ catch (err) {
4123
+ this.log('warn', `segment recording: a 'ring_indexed' listener threw: ${errorText(err)}`);
4124
+ }
4125
+ }
4126
+ /**
4127
+ * Read a big ring off the event loop: list it a batch at a time, stat only
4128
+ * the files the current index does not know, keep serving that index
4129
+ * meanwhile, and swap at the end, with whatever closed or was evicted while
4130
+ * it ran reconciled in. With `recover`, then hand out what an earlier
4131
+ * process left, its sidecars read off the loop too. One walk at a time.
4132
+ */
4133
+ startRingWalk(dir, recover) {
4134
+ const walk = {
4135
+ dir,
4136
+ generation: this.ringGeneration,
4137
+ recover,
4138
+ added: new Map(),
4139
+ removed: new Set(),
4140
+ done: Promise.resolve(),
4141
+ };
4142
+ this.ringWalk = walk;
4143
+ walk.done = this.runRingWalk(walk).catch((err) => {
4144
+ if (this.ringWalk === walk)
4145
+ this.ringWalk = null;
4146
+ this.segCounters.lastError = `ring read: ${errorText(err)}`;
4147
+ });
4148
+ return walk;
4149
+ }
4150
+ async runRingWalk(walk) {
4151
+ const current = () => this.ringWalk === walk && walk.generation === this.ringGeneration;
4152
+ const closedDir = path.join(walk.dir, exports.CLOSED_SEGMENTS_DIRNAME);
4153
+ const segments = [];
4154
+ const sidecars = [];
4155
+ const partials = [];
4156
+ // One turn for the whole listing: its batch reads run one at a time.
4157
+ await ringIo(() => listDirOffLoop(closedDir, (name) => {
4158
+ const lower = name.toLowerCase();
4159
+ if (lower.endsWith('.mp4'))
4160
+ segments.push(name);
4161
+ else if (lower.endsWith('.json'))
4162
+ sidecars.push(name);
4163
+ else if (lower.endsWith('.tmp'))
4164
+ partials.push(name);
4165
+ }));
4166
+ if (!current())
4167
+ return;
4168
+ const ordered = await sortOffLoop(segments);
4169
+ if (!current())
4170
+ return;
4171
+ // What the index already knows keeps its bytes: only files new to it are stat'ed.
4172
+ const known = this.ringIndex && this.ringIndex.dir === walk.dir ? this.ringIndex.items.slice() : [];
4173
+ const items = [];
4174
+ let k = 0;
4175
+ let sliceStartMs = perf_hooks_1.performance.now();
4176
+ for (const name of ordered) {
4177
+ const file = path.join(closedDir, name);
4178
+ while (k < known.length && known[k].file < file)
4179
+ k += 1;
4180
+ if (k < known.length && known[k].file === file) {
4181
+ items.push(known[k]);
4182
+ }
4183
+ else {
4184
+ try {
4185
+ items.push({ file, bytes: (await ringIo(() => fs.promises.stat(file))).size });
4186
+ }
4187
+ catch {
4188
+ /* delivered and deleted under us */
4189
+ }
4190
+ if (!current())
4191
+ return;
4192
+ }
4193
+ if (perf_hooks_1.performance.now() - sliceStartMs >= exports.RING_SLICE_MS) {
4194
+ await yieldToLoop();
4195
+ if (!current())
4196
+ return;
4197
+ sliceStartMs = perf_hooks_1.performance.now();
4198
+ }
4199
+ }
4200
+ if (this.segmentConfig?.dir !== walk.dir) {
4201
+ this.ringWalk = null; // the ring moved while it was read
4202
+ return;
4203
+ }
4204
+ // What moved while the walk ran wins over what it read.
4205
+ const merged = walk.removed.size ? items.filter((item) => !walk.removed.has(item.file)) : items;
4206
+ for (const [file, bytes] of walk.added) {
4207
+ if (!walk.removed.has(file))
4208
+ insertRingItem(merged, file, bytes);
4209
+ }
4210
+ const recover = walk.recover;
4211
+ if (!recover)
4212
+ this.ringWalk = null;
4213
+ this.installRingIndex(walk.dir, merged);
4214
+ if (this.segmentsRecoveredFor === walk.dir)
4215
+ this.enforceRing();
4216
+ if (!recover || !current())
4217
+ return;
4218
+ await this.recoverRingOffLoop(walk, closedDir, ordered, sidecars, partials, current);
4219
+ }
4220
+ /**
4221
+ * `recoverSegments` for a big ring, after its index is in: hand out every
4222
+ * closed segment an earlier process left, oldest first, its sidecar read off
4223
+ * the loop; delete what can never be indexed (no sidecar), leftover `.tmp`
4224
+ * files and sidecars whose segment is gone. A segment this process moved in
4225
+ * while the walk ran was handed out as it moved, and is skipped.
4226
+ */
4227
+ async recoverRingOffLoop(walk, closedDir, segments, sidecars, partials, current) {
4228
+ let sliceStartMs = perf_hooks_1.performance.now();
4229
+ const yieldIfDue = async () => {
4230
+ if (perf_hooks_1.performance.now() - sliceStartMs < exports.RING_SLICE_MS)
4231
+ return current();
4232
+ await yieldToLoop();
4233
+ sliceStartMs = perf_hooks_1.performance.now();
4234
+ return current();
4235
+ };
4236
+ for (const name of segments) {
4237
+ const file = path.join(closedDir, name);
4238
+ const index = this.ringIndex && this.ringIndex.dir === walk.dir ? this.ringIndex.items : [];
4239
+ const at = ringItemPosition(index, file);
4240
+ // Not in the index: gone before the walk could stat it, or already evicted.
4241
+ if (at >= index.length || index[at].file !== file || walk.added.has(file)) {
4242
+ if (!(await yieldIfDue()))
4243
+ return;
4244
+ continue;
4245
+ }
4246
+ const bytes = index[at].bytes;
4247
+ const metaFile = file.replace(/\.mp4$/i, '.json');
4248
+ const sidecar = await ringIo(() => readSidecarOffLoop(metaFile));
4249
+ if (!current())
4250
+ return;
4251
+ if (!sidecar) {
4252
+ // No capture time, so it can never be indexed.
4253
+ try {
4254
+ await ringIo(() => fs.promises.unlink(file));
4255
+ this.segCounters.partialsDeleted += 1;
4256
+ this.dropRingFile(walk.dir, file);
4257
+ try {
4258
+ await ringIo(() => fs.promises.unlink(metaFile));
4259
+ }
4260
+ catch {
4261
+ /* absent or inaccessible */
4262
+ }
4263
+ }
4264
+ catch {
4265
+ /* evicted meanwhile, or busy: best-effort */
4266
+ }
4267
+ if (!current())
4268
+ return;
4269
+ continue;
4270
+ }
4271
+ const segment = {
4272
+ file,
4273
+ metaFile,
4274
+ startSec: sidecar.startSec,
4275
+ endSec: sidecar.endSec,
4276
+ captureStartMs: sidecar.captureStartMs,
4277
+ captureEndMs: sidecar.captureEndMs,
4278
+ bytes,
4279
+ stream: sidecar.stream,
4280
+ recovered: true,
4281
+ label: sidecar.label ?? null,
4282
+ };
4283
+ this.countSegment(segment);
4284
+ this.emitSegment(segment);
4285
+ if (!(await yieldIfDue()))
4286
+ return;
4287
+ }
4288
+ for (const name of partials) {
4289
+ try {
4290
+ await ringIo(() => fs.promises.unlink(path.join(closedDir, name)));
4291
+ }
4292
+ catch {
4293
+ /* best-effort */
4294
+ }
4295
+ if (!current())
4296
+ return;
4297
+ }
4298
+ for (const name of sidecars) {
4299
+ if (sortedHas(segments, name.replace(/\.json$/i, '.mp4'))) {
4300
+ if (!(await yieldIfDue()))
4301
+ return;
4302
+ continue;
4303
+ }
4304
+ const metaFile = path.join(closedDir, name);
4305
+ const file = metaFile.replace(/\.json$/i, '.mp4');
4306
+ // Listed mid-move: its segment landed after the listing.
4307
+ if (walk.added.has(file))
4308
+ continue;
4309
+ try {
4310
+ await ringIo(() => fs.promises.access(file));
4311
+ continue;
4312
+ }
4313
+ catch {
4314
+ /* its segment is gone: the sidecar is an orphan */
4315
+ }
4316
+ try {
4317
+ await ringIo(() => fs.promises.unlink(metaFile));
4318
+ }
4319
+ catch {
4320
+ /* best-effort */
4321
+ }
4322
+ if (!current())
4323
+ return;
4324
+ }
4325
+ this.ringWalk = null;
4326
+ if (this.segmentsRecoveredFor === walk.dir)
4327
+ this.enforceRing();
4328
+ }
3565
4329
  /** A file just moved into `closed/`: keep the index in name (= capture time) order. */
3566
4330
  noteRingFile(dir, file, bytes) {
4331
+ const walk = this.ringWalk;
4332
+ if (walk && walk.dir === dir)
4333
+ walk.added.set(file, bytes);
3567
4334
  const index = this.ringIndex;
3568
4335
  if (!index || index.dir !== dir)
3569
4336
  return;
3570
- const items = index.items;
3571
- if (!items.length || items[items.length - 1].file < file) {
3572
- items.push({ file, bytes });
4337
+ insertRingItem(index.items, file, bytes);
4338
+ }
4339
+ /** A file left `closed/` (evicted, or found gone): a walk under way must not swap it back in. */
4340
+ noteRingRemoval(dir, file) {
4341
+ const walk = this.ringWalk;
4342
+ if (walk && walk.dir === dir)
4343
+ walk.removed.add(file);
4344
+ }
4345
+ /** A file deleted outside an eviction pass: out of the index and of any walk under way. */
4346
+ dropRingFile(dir, file) {
4347
+ this.noteRingRemoval(dir, file);
4348
+ const index = this.ringIndex;
4349
+ if (!index || index.dir !== dir)
3573
4350
  return;
3574
- }
3575
- if (items.some((item) => item.file === file))
4351
+ const at = ringItemPosition(index.items, file);
4352
+ if (at < index.items.length && index.items[at].file === file)
4353
+ index.items.splice(at, 1);
4354
+ }
4355
+ /** The rest of an eviction pass that ran out of its RING_SLICE_MS, from where it stopped. */
4356
+ scheduleRingEviction(from) {
4357
+ if (this.ringEvictImmediate)
3576
4358
  return;
3577
- const at = items.findIndex((item) => item.file > file);
3578
- items.splice(at < 0 ? items.length : at, 0, { file, bytes });
4359
+ const generation = this.ringGeneration;
4360
+ this.ringEvictImmediate = setImmediate(() => {
4361
+ this.ringEvictImmediate = null;
4362
+ if (generation === this.ringGeneration)
4363
+ this.enforceRing(from);
4364
+ });
3579
4365
  }
3580
4366
  /**
3581
4367
  * Hold the closed segments to min(ringSeconds x measured bytes/s, the cap),
@@ -3584,16 +4370,39 @@ class RTSPStreamCameraProvider extends events_1.EventEmitter {
3584
4370
  * the volume's free bytes. A file the OS will not let us delete (Windows,
3585
4371
  * mid-upload) is skipped, never waited on; a file already gone (its consumer
3586
4372
  * delivered and deleted it) leaves the index without counting as evicted.
4373
+ *
4374
+ * Never holds the event loop for a big ring: until its first read lands
4375
+ * nothing is evicted (the figures would leave its own files out), its check
4376
+ * against disk runs in the background, and a pass longer than RING_SLICE_MS
4377
+ * finishes in later slices, resuming past the files it could not delete.
3587
4378
  */
3588
- enforceRing() {
4379
+ enforceRing(from = 0) {
3589
4380
  const cfg = this.segmentConfig;
3590
4381
  if (!cfg)
3591
4382
  return;
3592
- const index = this.ringIndex;
3593
- const items = !index || index.dir !== cfg.dir || this.now() - index.rebuiltAtMs >= exports.RING_RESYNC_MS
3594
- ? this.rebuildRingIndex(cfg.dir)
3595
- : index.items;
3596
- let total = items.reduce((n, item) => n + item.bytes, 0);
4383
+ const index = this.currentRingIndex();
4384
+ const walking = this.ringWalk !== null && this.ringWalk.dir === cfg.dir;
4385
+ if (!index || (this.now() >= index.resyncAtMs && !walking)) {
4386
+ if (walking)
4387
+ return; // the walk enforces when it lands
4388
+ if (this.ringIsBig(cfg.dir)) {
4389
+ this.startRingWalk(cfg.dir, false);
4390
+ if (!index)
4391
+ return;
4392
+ }
4393
+ else {
4394
+ // A small ring: read in one pass. Its listeners have seen the figures
4395
+ // (and may have re-sized the ring) before anything below runs.
4396
+ this.rebuildRingIndex(cfg.dir);
4397
+ if (this.currentRingIndex())
4398
+ this.enforceRing();
4399
+ return;
4400
+ }
4401
+ }
4402
+ const items = this.currentRingIndex().items;
4403
+ let total = 0;
4404
+ for (const item of items)
4405
+ total += item.bytes;
3597
4406
  const freeBytes = this.freeBytesFn(cfg.dir);
3598
4407
  const bytesPerSec = this.measuredBytesPerSec();
3599
4408
  const byRing = bytesPerSec === null ? null : Math.floor(cfg.ringSeconds * bytesPerSec);
@@ -3602,43 +4411,54 @@ class RTSPStreamCameraProvider extends events_1.EventEmitter {
3602
4411
  : freeBytes === null ? null : Math.floor(exports.RING_FREE_FRACTION * freeBytes);
3603
4412
  const limit = byRing === null ? byFree : byFree === null ? byRing : Math.min(byRing, byFree);
3604
4413
  if (limit !== null) {
3605
- let i = 0;
4414
+ const sliceStartMs = perf_hooks_1.performance.now();
4415
+ let i = Math.min(Math.max(0, from), items.length);
3606
4416
  while (total > limit && i < items.length) {
3607
4417
  const item = items[i];
3608
4418
  const metaFile = item.file.replace(/\.mp4$/i, '.json');
4419
+ let evicted = false;
3609
4420
  try {
3610
4421
  fs.unlinkSync(item.file);
4422
+ evicted = true;
3611
4423
  }
3612
4424
  catch (err) {
3613
4425
  if (err?.code === 'ENOENT') {
3614
4426
  total -= item.bytes;
3615
4427
  items.splice(i, 1);
4428
+ this.noteRingRemoval(cfg.dir, item.file);
3616
4429
  try {
3617
4430
  fs.unlinkSync(metaFile);
3618
4431
  }
3619
4432
  catch {
3620
4433
  /* its consumer took both */
3621
4434
  }
3622
- continue;
3623
4435
  }
3624
- i += 1;
3625
- continue;
3626
- }
3627
- try {
3628
- fs.unlinkSync(metaFile);
3629
- }
3630
- catch {
3631
- /* best-effort */
4436
+ else {
4437
+ i += 1;
4438
+ }
3632
4439
  }
3633
- items.splice(i, 1);
3634
- total -= item.bytes;
3635
- this.segCounters.evicted += 1;
3636
- this.segCounters.evictedBytes += item.bytes;
3637
- try {
3638
- this.emit('segment_evicted', { file: item.file, metaFile, bytes: item.bytes });
4440
+ if (evicted) {
4441
+ try {
4442
+ fs.unlinkSync(metaFile);
4443
+ }
4444
+ catch {
4445
+ /* best-effort */
4446
+ }
4447
+ items.splice(i, 1);
4448
+ total -= item.bytes;
4449
+ this.noteRingRemoval(cfg.dir, item.file);
4450
+ this.segCounters.evicted += 1;
4451
+ this.segCounters.evictedBytes += item.bytes;
4452
+ try {
4453
+ this.emit('segment_evicted', { file: item.file, metaFile, bytes: item.bytes });
4454
+ }
4455
+ catch (err) {
4456
+ this.log('warn', `segment recording: a 'segment_evicted' listener threw: ${errorText(err)}`);
4457
+ }
3639
4458
  }
3640
- catch (err) {
3641
- this.log('warn', `segment recording: a 'segment_evicted' listener threw: ${errorText(err)}`);
4459
+ if (total > limit && i < items.length && perf_hooks_1.performance.now() - sliceStartMs >= exports.RING_SLICE_MS) {
4460
+ this.scheduleRingEviction(i);
4461
+ break;
3642
4462
  }
3643
4463
  }
3644
4464
  }
@@ -3668,6 +4488,7 @@ class RTSPStreamCameraProvider extends events_1.EventEmitter {
3668
4488
  partialsDeleted: c.partialsDeleted,
3669
4489
  ringSegments: c.ringSegments,
3670
4490
  ringBytes: c.ringBytes,
4491
+ ringIndexed: cfg !== null && this.ringIndexedDir === cfg.dir,
3671
4492
  ringLimitBytes: c.ringLimitBytes,
3672
4493
  measuredBytesPerSec: bytesPerSec === null ? null : Math.round(bytesPerSec),
3673
4494
  freeBytes: c.freeBytes,