Defer recording until preview frames are ready

Adds a pending-recording flow in the main window so "Start recording" while preview is stopped first starts preview, then begins recording only after all active cameras have produced frames. The pending state is cleared on stop/error/init failure to avoid stale triggers and duplicate starts. Adds GUI tests covering deferred start, waiting for all camera frames, frame-ready trigger behavior, and no double-starts.

Author: C-Achard

dlclivegui/gui/main_window.py

@@ -137,6 +137,7 @@ def __init__(self, config: ApplicationSettings | None = None):
         self._raw_frame: np.ndarray | None = None
         self._last_pose: PoseResult | None = None
         self._dlc_active: bool = False
+        self._pending_recording_after_preview = False
         self._active_camera_settings: CameraSettings | None = None
         self._last_drop_warning = 0.0
         self._last_recorder_summary = "Recorder idle"
@@ -1422,6 +1423,7 @@ def _on_multi_frame_processing_ready(self, frame_data: MultiFrameData) -> None:
         """
         self._multi_camera_frames = frame_data.frames
         self._multi_camera_display_ids = frame_data.display_ids or {}
+        self._try_start_pending_recording()
         src_id = frame_data.source_camera_id
         if src_id:
             self._fps_tracker.note_frame(src_id)  # Track FPS
@@ -1487,6 +1489,7 @@ def _on_multi_camera_stopped(self) -> None:
         """Handle all cameras stopped event."""
         # Stop all multi-camera recorders
         self._stop_multi_camera_recording()
+        self._pending_recording_after_preview = False
 
         self.preview_button.setEnabled(True)
         self.stop_preview_button.setEnabled(False)
@@ -1501,6 +1504,7 @@ def _on_multi_camera_stopped(self) -> None:
 
     def _on_multi_camera_error(self, camera_id: str, message: str) -> None:
         """Handle error from a camera in multi-camera mode."""
+        self._pending_recording_after_preview = False
         self._show_warning(f"Camera {camera_id} error: {message}\nRecording stopped.")
         self._refresh_dlc_camera_list_running()
         if self.dlc_camera_combo.count() <= 1:
@@ -1509,6 +1513,7 @@ def _on_multi_camera_error(self, camera_id: str, message: str) -> None:
 
     def _on_multi_camera_initialization_failed(self, failures: list) -> None:
         """Handle complete failure to initialize cameras."""
+        self._pending_recording_after_preview = False
         # Build error message with details for each failed camera
         error_lines = ["Failed to initialize camera(s):"]
         for camera_id, error_msg in failures:
@@ -1669,6 +1674,7 @@ def _stop_preview(self) -> None:
         self._stop_multi_camera_recording()
 
         self.multi_camera_controller.stop()
+        self._pending_recording_after_preview = False
         self._stop_inference(show_message=False)
         self._fps_tracker.clear()
         self._last_display_time = 0.0
@@ -1952,6 +1958,7 @@ def _start_recording(self) -> None:
         """Start recording from all active cameras."""
         # Auto-start preview if not running
         if not self.multi_camera_controller.is_running():
+            self._pending_recording_after_preview = True
             self._start_preview()
             # Wait a moment for cameras to initialize before recording
             # The recording will start after preview is confirmed running
@@ -1963,6 +1970,32 @@ def _start_recording(self) -> None:
         # Preview already running, start recording immediately
         self._start_multi_camera_recording()
 
+    def _try_start_pending_recording(self) -> None:
+        if not self._pending_recording_after_preview:
+            return
+
+        if self._rec_manager.is_active:
+            self._pending_recording_after_preview = False
+            return
+
+        if not self.multi_camera_controller.is_running():
+            return
+
+        active_cams = self._config.multi_camera.get_active_cameras()
+        expected_ids = {get_camera_id(cam) for cam in active_cams}
+
+        if not expected_ids:
+            self._pending_recording_after_preview = False
+            return
+
+        available_ids = set(self._multi_camera_frames.keys())
+
+        if not expected_ids.issubset(available_ids):
+            return
+
+        self._pending_recording_after_preview = False
+        self._start_multi_camera_recording()
+
     def _stop_recording(self) -> None:
         """Stop recording from all cameras."""
         self._stop_multi_camera_recording()

tests/gui/test_recording_gui.py

@@ -0,0 +1,173 @@
+import numpy as np
+import pytest
+
+from dlclivegui.services.multi_camera_controller import MultiFrameData, get_camera_id
+
+
+@pytest.mark.gui
+class TestPendingRecordingAfterPreview:
+    def test_start_recording_when_preview_stopped_defers_until_preview_frames(
+        self,
+        window,
+        monkeypatch,
+    ):
+        calls = {
+            "start_preview": 0,
+            "start_recording": 0,
+        }
+
+        monkeypatch.setattr(
+            window.multi_camera_controller,
+            "is_running",
+            lambda: False,
+        )
+
+        def fake_start_preview():
+            calls["start_preview"] += 1
+
+        def fake_start_multi_camera_recording():
+            calls["start_recording"] += 1
+
+        monkeypatch.setattr(window, "_start_preview", fake_start_preview)
+        monkeypatch.setattr(window, "_start_multi_camera_recording", fake_start_multi_camera_recording)
+
+        window._pending_recording_after_preview = False
+
+        window._start_recording()
+
+        assert calls["start_preview"] == 1
+        assert calls["start_recording"] == 0
+        assert window._pending_recording_after_preview is True
+
+    def test_pending_recording_waits_until_all_active_cameras_have_frames(
+        self,
+        window,
+        monkeypatch,
+    ):
+        active_cams = window._config.multi_camera.get_active_cameras()
+        assert len(active_cams) >= 2
+
+        cam0_id = get_camera_id(active_cams[0])
+        cam1_id = get_camera_id(active_cams[1])
+
+        calls = {
+            "start_recording": 0,
+        }
+
+        monkeypatch.setattr(
+            window.multi_camera_controller,
+            "is_running",
+            lambda: True,
+        )
+
+        def fake_start_multi_camera_recording():
+            calls["start_recording"] += 1
+
+        monkeypatch.setattr(window, "_start_multi_camera_recording", fake_start_multi_camera_recording)
+
+        window._pending_recording_after_preview = True
+        window._multi_camera_frames = {
+            cam0_id: np.zeros((10, 10, 3), dtype=np.uint8),
+        }
+
+        window._try_start_pending_recording()
+
+        assert calls["start_recording"] == 0
+        assert window._pending_recording_after_preview is True
+
+        window._multi_camera_frames[cam1_id] = np.zeros((10, 10, 3), dtype=np.uint8)
+
+        window._try_start_pending_recording()
+
+        assert calls["start_recording"] == 1
+        assert window._pending_recording_after_preview is False
+
+    def test_pending_recording_is_triggered_from_multi_frame_processing_ready(
+        self,
+        window,
+        monkeypatch,
+    ):
+        active_cams = window._config.multi_camera.get_active_cameras()
+        assert len(active_cams) >= 2
+
+        cam0_id = get_camera_id(active_cams[0])
+        cam1_id = get_camera_id(active_cams[1])
+
+        calls = {
+            "start_recording": 0,
+        }
+
+        monkeypatch.setattr(
+            window.multi_camera_controller,
+            "is_running",
+            lambda: True,
+        )
+
+        def fake_start_multi_camera_recording():
+            calls["start_recording"] += 1
+
+        monkeypatch.setattr(window, "_start_multi_camera_recording", fake_start_multi_camera_recording)
+
+        window._pending_recording_after_preview = True
+
+        frame0 = np.zeros((10, 10, 3), dtype=np.uint8)
+        frame1 = np.zeros((10, 10, 3), dtype=np.uint8)
+
+        frame_data = MultiFrameData(
+            frames={
+                cam0_id: frame0,
+                cam1_id: frame1,
+            },
+            timestamps={
+                cam0_id: 1.0,
+                cam1_id: 1.0,
+            },
+            source_camera_id=cam0_id,
+            display_ids={
+                cam0_id: "Cam0",
+                cam1_id: "Cam1",
+            },
+        )
+
+        window._on_multi_frame_processing_ready(frame_data)
+
+        assert calls["start_recording"] == 1
+        assert window._pending_recording_after_preview is False
+
+    def test_pending_recording_does_not_start_twice(
+        self,
+        window,
+        monkeypatch,
+    ):
+        active_cams = window._config.multi_camera.get_active_cameras()
+        assert len(active_cams) >= 2
+
+        cam0_id = get_camera_id(active_cams[0])
+        cam1_id = get_camera_id(active_cams[1])
+
+        calls = {
+            "start_recording": 0,
+        }
+
+        monkeypatch.setattr(
+            window.multi_camera_controller,
+            "is_running",
+            lambda: True,
+        )
+
+        def fake_start_multi_camera_recording():
+            calls["start_recording"] += 1
+
+        monkeypatch.setattr(window, "_start_multi_camera_recording", fake_start_multi_camera_recording)
+
+        window._pending_recording_after_preview = True
+        window._multi_camera_frames = {
+            cam0_id: np.zeros((10, 10, 3), dtype=np.uint8),
+            cam1_id: np.zeros((10, 10, 3), dtype=np.uint8),
+        }
+
+        window._try_start_pending_recording()
+        window._try_start_pending_recording()
+
+        assert calls["start_recording"] == 1
+        assert window._pending_recording_after_preview is False