choose the replay stream with the vod coverage resolver

Stream selection counted a main row that only touched the range, while the pinned playlist served nothing for it, so replay failed instead of using the sub footage. Selection now uses resolve_coverage, the same resolver the pinned vod and export use.

docs/docs/configuration/record.md

@@ -413,17 +413,18 @@ Avoid removing audio from only one of the two streams (for example with `-an`).
 
 As a general rule, features that read recordings prefer the main stream and fall back to the sub stream for time ranges where the main recordings have expired. Analytics features use only the main stream.
 
-| Feature                                                                                  | Stream used                                                                                                   |
-| ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
-| Recording playback (History and Review)                                                  | Both (main preferred with sub fallback by default), or exactly one stream when a quality is selected manually |
-| Tracking details and Explore clip playback                                               | Main, falling back to sub where the main recordings have expired                                              |
+| Feature                                                                                  | Stream used                                                                                                               |
+| ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| Recording playback (History and Review)                                                  | Both (main preferred with sub fallback by default), or exactly one stream when a quality is selected manually             |
+| Tracking details and Explore clip playback                                               | Main, falling back to sub where the main recordings have expired                                                          |
 | Exports                                                                                  | Both (main preferred with sub fallback by default), or exactly one stream when a quality is selected in the export dialog |
-| Clip downloads                                                                           | Main; sub is used when no main recordings remain in the range (streams are never mixed in one file)           |
-| Frames grabbed from a recording in History (download snapshot, submit frame to Frigate+) | Main preferred, sub fallback                                                                                  |
-| Audio extraction (e.g., transcription)                                                   | Main preferred, sub fallback                                                                                  |
-| Motion search                                                                            | Main only                                                                                                     |
-| Review timeline motion data                                                              | Main only                                                                                                     |
-| Storage usage statistics                                                                 | Both streams counted, and listed separately per camera                                                        |
+| Clip downloads                                                                           | Main; sub is used when no main recordings remain in the range (streams are never mixed in one file)                       |
+| Debug replay                                                                             | Main; sub is used when no main recordings remain in the range (streams are never mixed in one file)                       |
+| Frames grabbed from a recording in History (download snapshot, submit frame to Frigate+) | Main preferred, sub fallback                                                                                              |
+| Audio extraction (e.g., transcription)                                                   | Main preferred, sub fallback                                                                                              |
+| Motion search                                                                            | Main only                                                                                                                 |
+| Review timeline motion data                                                              | Main only                                                                                                                 |
+| Storage usage statistics                                                                 | Both streams counted, and listed separately per camera                                                                    |
 
 This table covers only features that read recordings from disk. Tracked object snapshots and thumbnails (the images shown in Explore and sent with notifications, and the images submitted to Frigate+ from a tracked object) are captured live from the `detect` stream as the object is tracked, never from recordings, so sub stream recording does not affect them.
 

frigate/jobs/debug_replay.py

@@ -16,18 +16,21 @@ from abc import ABC, abstractmethod
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any, Optional, cast
 
-from peewee import ModelSelect
-
 from frigate.config import FrigateConfig
 from frigate.config.camera.updater import CameraConfigUpdatePublisher
-from frigate.const import REPLAY_CAMERA_PREFIX, REPLAY_DIR
+from frigate.const import (
+    REPLAY_CAMERA_PREFIX,
+    REPLAY_DIR,
+    STREAM_TYPE_MAIN,
+    STREAM_TYPE_SUB,
+)
 from frigate.jobs.export import JobStatePublisher
 from frigate.jobs.job import Job
 from frigate.jobs.manager import job_is_running, set_current_job
-from frigate.models import Export, Recordings
+from frigate.models import Export
 from frigate.types import JobStatusTypesEnum
 from frigate.util.ffmpeg import run_ffmpeg_with_progress
-from frigate.util.recording_coverage import recording_overlap
+from frigate.util.recording_coverage import resolve_coverage
 
 if TYPE_CHECKING:
     from frigate.debug_replay import DebugReplayManager
@@ -94,24 +97,6 @@ class DebugReplayJob(Job):
         }
 
 
-def query_recordings(source_camera: str, start_ts: float, end_ts: float) -> ModelSelect:
-    """Return the Recordings query for the time range.
-
-    Module-level so tests can patch it without instantiating a runner.
-    """
-    query = (
-        Recordings.select(
-            Recordings.path,
-            Recordings.start_time,
-            Recordings.end_time,
-        )
-        .where(recording_overlap(start_ts, end_ts))
-        .where(Recordings.camera == source_camera)
-        .order_by(Recordings.start_time.asc())
-    )
-    return cast(ModelSelect, query)
-
-
 class NoRecordingsError(ValueError):
     """Raised when no recordings exist in the requested time range."""
 
@@ -156,7 +141,8 @@ class RecordingDebugReplaySource(DebugReplaySource):
 
     Feeds ffmpeg the internal VOD endpoint so segments with mismatched
     SPS/PPS (e.g. across day/night transitions) stitch cleanly via HLS
-    discontinuities.
+    discontinuities. The playlist is pinned to one stream because the
+    stream-copied clip cannot change codec or resolution mid-file.
     """
 
     def __init__(
@@ -170,6 +156,7 @@ class RecordingDebugReplaySource(DebugReplaySource):
         self._start_ts = start_ts
         self._end_ts = end_ts
         self._internal_port = internal_port
+        self._stream_type = STREAM_TYPE_MAIN
 
     @property
     def source_camera(self) -> str:
@@ -187,15 +174,28 @@ class RecordingDebugReplaySource(DebugReplaySource):
         if self._end_ts <= self._start_ts:
             raise ValueError("End time must be after start time")
 
-        if not query_recordings(self._camera, self._start_ts, self._end_ts).count():
-            raise NoRecordingsError(
-                f"No recordings found for camera '{self._camera}' in the specified time range"
-            )
+        # the VOD resolver decides what the pinned playlist serves, so it
+        # also decides the stream; a row merely touching the range has no
+        # interval and must not win
+        intervals = resolve_coverage(self._camera, self._start_ts, self._end_ts)
+
+        if any(interval.main for interval in intervals):
+            self._stream_type = STREAM_TYPE_MAIN
+            return
+
+        if any(interval.sub for interval in intervals):
+            self._stream_type = STREAM_TYPE_SUB
+            return
+
+        raise NoRecordingsError(
+            f"No recordings found for camera '{self._camera}' in the specified time range"
+        )
 
     def ffmpeg_input_args(self, working_dir: str) -> list[str]:
         playlist_url = (
             f"http://127.0.0.1:{self._internal_port}/vod/{self._camera}"
-            f"/start/{self._start_ts}/end/{self._end_ts}/index.m3u8"
+            f"/{self._stream_type}/start/{self._start_ts}/end/{self._end_ts}"
+            "/index.m3u8"
         )
         return [
             "-protocol_whitelist",

frigate/test/test_debug_replay_job.py

@@ -18,6 +18,7 @@ from frigate.jobs.debug_replay import (
 from frigate.jobs.export import JobStatePublisher
 from frigate.jobs.manager import _completed_jobs, _current_jobs
 from frigate.types import JobStatusTypesEnum
+from frigate.util.recording_coverage import CoverageInterval
 
 
 def _reset_job_manager() -> None:
@@ -77,6 +78,31 @@ class TestDebugReplayJob(unittest.TestCase):
         self.assertEqual(results["end_ts"], 200.0)
 
 
+class TestRecordingDebugReplaySource(unittest.TestCase):
+    def _source_url(self, intervals: list[CoverageInterval]) -> str:
+        source = RecordingDebugReplaySource(
+            source_camera="front", start_ts=100.0, end_ts=200.0, internal_port=5000
+        )
+        with patch(
+            "frigate.jobs.debug_replay.resolve_coverage", return_value=intervals
+        ):
+            source.validate()
+        return source.ffmpeg_input_args("/tmp")[-1]
+
+    def test_pins_main_when_main_has_recordings(self) -> None:
+        url = self._source_url(
+            [
+                CoverageInterval(100.0, 150.0, None, MagicMock()),
+                CoverageInterval(150.0, 200.0, MagicMock(), MagicMock()),
+            ]
+        )
+        self.assertIn("/vod/front/main/start/100.0/end/200.0/", url)
+
+    def test_falls_back_to_sub_without_main_recordings(self) -> None:
+        url = self._source_url([CoverageInterval(100.0, 200.0, None, MagicMock())])
+        self.assertIn("/vod/front/sub/start/100.0/end/200.0/", url)
+
+
 class TestStartDebugReplayJob(unittest.TestCase):
     def setUp(self) -> None:
         _reset_job_manager()
@@ -87,9 +113,7 @@ class TestStartDebugReplayJob(unittest.TestCase):
         self.frigate_config.ffmpeg.ffmpeg_path = "/bin/true"
         self.publisher = MagicMock()
 
-        self.recordings_qs = MagicMock()
-        self.recordings_qs.count.return_value = 1
-        self.recordings_qs.__iter__.return_value = iter([MagicMock(path="/tmp/r1.mp4")])
+        self.coverage = [CoverageInterval(100.0, 200.0, MagicMock(), None)]
 
     def tearDown(self) -> None:
         runner = get_active_runner()
@@ -127,9 +151,7 @@ class TestStartDebugReplayJob(unittest.TestCase):
             )
 
     def test_rejects_when_no_recordings(self) -> None:
-        empty_qs = MagicMock()
-        empty_qs.count.return_value = 0
-        with patch("frigate.jobs.debug_replay.query_recordings", return_value=empty_qs):
+        with patch("frigate.jobs.debug_replay.resolve_coverage", return_value=[]):
             with self.assertRaises(NoRecordingsError):
                 start_debug_replay_job(
                     source=RecordingDebugReplaySource(
@@ -152,8 +174,8 @@ class TestStartDebugReplayJob(unittest.TestCase):
 
         with (
             patch(
-                "frigate.jobs.debug_replay.query_recordings",
-                return_value=self.recordings_qs,
+                "frigate.jobs.debug_replay.resolve_coverage",
+                return_value=self.coverage,
             ),
             patch(
                 "frigate.jobs.debug_replay.run_ffmpeg_with_progress",
@@ -192,8 +214,8 @@ class TestStartDebugReplayJob(unittest.TestCase):
 
         with (
             patch(
-                "frigate.jobs.debug_replay.query_recordings",
-                return_value=self.recordings_qs,
+                "frigate.jobs.debug_replay.resolve_coverage",
+                return_value=self.coverage,
             ),
             patch(
                 "frigate.jobs.debug_replay.run_ffmpeg_with_progress",
@@ -242,9 +264,7 @@ class TestRunnerHappyPath(unittest.TestCase):
         self.frigate_config.ffmpeg.ffmpeg_path = "/bin/true"
         self.publisher = MagicMock()
 
-        self.recordings_qs = MagicMock()
-        self.recordings_qs.count.return_value = 1
-        self.recordings_qs.__iter__.return_value = iter([MagicMock(path="/tmp/r1.mp4")])
+        self.coverage = [CoverageInterval(100.0, 200.0, MagicMock(), None)]
 
     def tearDown(self) -> None:
         runner = get_active_runner()
@@ -272,8 +292,8 @@ class TestRunnerHappyPath(unittest.TestCase):
 
         with (
             patch(
-                "frigate.jobs.debug_replay.query_recordings",
-                return_value=self.recordings_qs,
+                "frigate.jobs.debug_replay.resolve_coverage",
+                return_value=self.coverage,
             ),
             patch(
                 "frigate.jobs.debug_replay.run_ffmpeg_with_progress",
@@ -325,9 +345,7 @@ class TestRunnerFailurePath(unittest.TestCase):
         self.frigate_config.cameras = {"front": MagicMock()}
         self.frigate_config.ffmpeg.ffmpeg_path = "/bin/true"
         self.publisher = MagicMock()
-        self.recordings_qs = MagicMock()
-        self.recordings_qs.count.return_value = 1
-        self.recordings_qs.__iter__.return_value = iter([MagicMock(path="/tmp/r1.mp4")])
+        self.coverage = [CoverageInterval(100.0, 200.0, MagicMock(), None)]
 
     def tearDown(self) -> None:
         runner = get_active_runner()
@@ -350,8 +368,8 @@ class TestRunnerFailurePath(unittest.TestCase):
 
         with (
             patch(
-                "frigate.jobs.debug_replay.query_recordings",
-                return_value=self.recordings_qs,
+                "frigate.jobs.debug_replay.resolve_coverage",
+                return_value=self.coverage,
             ),
             patch(
                 "frigate.jobs.debug_replay.run_ffmpeg_with_progress",
@@ -399,9 +417,7 @@ class TestRunnerCancellation(unittest.TestCase):
         self.frigate_config.cameras = {"front": MagicMock()}
         self.frigate_config.ffmpeg.ffmpeg_path = "/bin/true"
         self.publisher = MagicMock()
-        self.recordings_qs = MagicMock()
-        self.recordings_qs.count.return_value = 1
-        self.recordings_qs.__iter__.return_value = iter([MagicMock(path="/tmp/r1.mp4")])
+        self.coverage = [CoverageInterval(100.0, 200.0, MagicMock(), None)]
 
     def tearDown(self) -> None:
         runner = get_active_runner()
@@ -431,8 +447,8 @@ class TestRunnerCancellation(unittest.TestCase):
 
         with (
             patch(
-                "frigate.jobs.debug_replay.query_recordings",
-                return_value=self.recordings_qs,
+                "frigate.jobs.debug_replay.resolve_coverage",
+                return_value=self.coverage,
             ),
             patch(
                 "frigate.jobs.debug_replay.run_ffmpeg_with_progress",