Add timestamp metadata coverage across tests

Expands test coverage for frame timestamp metadata end-to-end: Basler backend reads now validate hardware timestamp extraction, controller/recording manager tests assert metadata forwarding, and video recorder tests verify schema_version 2 sidecar output for both software-only and hardware-backed timestamps. Also adds focused unit tests for `FrameTimestampMetadata` source/frame field splitting and default-reported value behavior.

Author: C-Achard

tests/cameras/backends/conftest.py

@@ -526,6 +526,9 @@ def GrabSucceeded(self):
         def Release(self):
             self.released = True
 
+        def GetTimeStamp(self):
+            return 123456789
+
     class InstantCamera:
         def __init__(self, device):
             self._device = device
@@ -550,6 +553,7 @@ def __init__(self, device):
 
             self.AcquisitionFrameRateEnable = FakePylon._Feature(False)
             self.AcquisitionFrameRate = FakePylon._Feature(30.0)
+            self.GevTimestampTickFrequency = FakePylon._Feature(1_000_000_000.0)
 
             self.MaxNumBuffer = FakePylon._Feature(10)
 

tests/cameras/backends/test_basler_backend.py

@@ -3,6 +3,9 @@
 import numpy as np
 import pytest
 
+from dlclivegui.cameras.base import CapturedFrame
+from dlclivegui.utils.timestamps import FrameTimestampMetadata
+
 # ---------------------------------------------------------------------
 # Core lifecycle
 # ---------------------------------------------------------------------
@@ -507,3 +510,43 @@ def raise_timeout(*_args, **_kwargs):
 
     finally:
         backend.close()
+class TestBaslerFrameTimestamps:
+    @pytest.mark.unit
+    def test_read_returns_captured_frame_with_hardware_timestamp_metadata(
+        self,
+        patch_basler_sdk,
+        basler_settings_factory,
+    ):
+        import dlclivegui.cameras.backends.basler_backend as bb
+
+        settings = basler_settings_factory()
+        be = bb.BaslerCameraBackend(settings)
+        be.open()
+
+        captured = be.read()
+
+        assert isinstance(captured, CapturedFrame)
+        assert captured.frame is not None
+        assert isinstance(captured.software_timestamp, float)
+
+        meta = captured.timestamp_metadata
+        assert isinstance(meta, FrameTimestampMetadata)
+
+        assert meta.backend == "basler"
+        assert meta.source == "grab_result.GetTimeStamp"
+        assert meta.kind == "camera_clock"
+        assert meta.raw_unit == "ticks"
+        assert meta.raw_value == 123456789
+        assert meta.tick_frequency_hz == pytest.approx(1_000_000_000.0)
+        assert meta.seconds == pytest.approx(0.123456789)
+        assert meta.default_reported == "seconds"
+
+        source_dict = meta.to_source_dict()
+        assert source_dict["backend"] == "basler"
+        assert source_dict["source"] == "grab_result.GetTimeStamp"
+
+        frame_dict = meta.to_frame_dict()
+        assert frame_dict["seconds"] == pytest.approx(0.123456789)
+        assert frame_dict["raw_value"] == 123456789
+
+        be.close()

tests/gui/test_rec_manager.py

@@ -7,6 +7,7 @@
 from dlclivegui.gui.recording_manager import RecordingManager
 from dlclivegui.services.multi_camera_controller import get_camera_id, get_display_id
 from dlclivegui.utils.stats import RecorderStats
+from dlclivegui.utils.timestamps import FrameTimestampMetadata
 
 
 @pytest.fixture
@@ -422,3 +423,41 @@ def test_start_all_passes_writegear_options(
         assert rec.writer_options["-crf"] == "23"
         assert rec.writer_options["-preset"] == "ultrafast"
         assert rec.writer_options["-tune"] == "zerolatency"
+
+
+class TestRecordingManagerTimestampMetadata:
+    @pytest.mark.unit
+    def test_write_frame_passes_timestamp_metadata(
+        self,
+        recording_settings,
+        _active_cams_two,
+        current_frames,
+        patch_video_recorder,
+        patch_build_run_dir,
+    ):
+        mgr = RecordingManager()
+        mgr.start_all(recording_settings, _active_cams_two, current_frames, session_name="Sess")
+
+        cam0_id = get_camera_id(_active_cams_two[0])
+        frame = current_frames[cam0_id]
+
+        meta = FrameTimestampMetadata(
+            source="grab_result.GetTimeStamp",
+            backend="basler",
+            default_reported="seconds",
+            seconds=0.001,
+            raw_value=1_000_000,
+            raw_unit="ticks",
+            tick_frequency_hz=1_000_000_000.0,
+            kind="camera_clock",
+        )
+
+        mgr.write_frame(cam0_id, frame, timestamp=123.0, timestamp_metadata=meta)
+
+        rec = mgr.recorders[cam0_id]
+        assert len(rec.write_calls) == 1
+
+        written_frame, written_timestamp, written_metadata = rec.write_calls[0]
+        assert written_frame is frame
+        assert written_timestamp == 123.0
+        assert written_metadata is meta

tests/services/test_multicam_controller.py

@@ -1,4 +1,5 @@
 # tests/services/test_multicam_controller.py
+import numpy as np
 import pytest
 
 from dlclivegui.cameras.factory import CameraFactory
@@ -12,6 +13,7 @@
     get_camera_id,
     get_display_id,
 )
+from dlclivegui.utils.timestamps import FrameTimestampMetadata
 
 
 @pytest.mark.unit
@@ -547,3 +549,50 @@ def on_recording_frame(camera_id, frame, timestamp, timestamp_metadata=None):
     finally:
         with qtbot.waitSignal(mc.all_stopped, timeout=2000):
             mc.stop(wait=True)
+
+
+class TestRecordingFrameTimestamps:
+    @pytest.mark.unit
+    def test_recording_frame_ready_forwards_timestamp_metadata(self, qtbot):
+        mc = MultiCameraController()
+        mc._running = True
+        mc._recording_frame_emission_enabled = True
+
+        cam_id = "basler:0815-0000"
+        mc._settings[cam_id] = CameraSettings(
+            name="C",
+            backend="basler",
+            index=0,
+            enabled=True,
+        ).apply_defaults()
+        mc._camera_display_order = [cam_id]
+        mc._display_ids[cam_id] = "C"
+
+        frame = np.zeros((10, 10), dtype=np.uint8)
+        meta = FrameTimestampMetadata(
+            source="grab_result.GetTimeStamp",
+            backend="basler",
+            default_reported="seconds",
+            seconds=0.001,
+            raw_value=1_000_000,
+            raw_unit="ticks",
+            tick_frequency_hz=1_000_000_000.0,
+            kind="camera_clock",
+        )
+
+        seen = []
+
+        def on_recording_frame(camera_id, emitted_frame, timestamp, timestamp_metadata):
+            seen.append((camera_id, emitted_frame, timestamp, timestamp_metadata))
+
+        mc.recording_frame_ready.connect(on_recording_frame)
+
+        mc._on_frame_captured(cam_id, frame, 123.0, meta)
+
+        assert len(seen) == 1
+
+        camera_id, emitted_frame, timestamp, timestamp_metadata = seen[0]
+        assert camera_id == cam_id
+        assert emitted_frame is frame
+        assert timestamp == 123.0
+        assert timestamp_metadata is meta

tests/services/test_video_recorder.py

@@ -9,6 +9,7 @@
 import pytest
 
 import dlclivegui.services.video_recorder as vr_mod
+from dlclivegui.utils.timestamps import FrameTimestampMetadata
 
 # ----------------------------
 # Helpers
@@ -228,10 +229,14 @@ def test_stop_writes_timestamps_sidecar_json(patch_writegear, output_path, rgb_f
     data = json.loads(ts_path.read_text())
     assert data["video_file"] == output_path.name
     assert data["num_frames"] == 2
-    assert data["timestamps"] == [10.0, 12.0]
     assert data["start_time"] == 10.0
     assert data["end_time"] == 12.0
     assert data["duration_seconds"] == 2.0
+    assert data["schema_version"] == 2
+    assert data["timestamps"] == [10.0, 12.0]
+    assert data["timestamp_sources"]["hardware_timestamp"] is None
+    assert data["frame_timestamps"][0]["software_timestamp"] == 10.0
+    assert data["frame_timestamps"][1]["software_timestamp"] == 12.0
 
 
 def test_encoder_write_error_sets_encode_error_and_future_writes_raise(patch_writegear, output_path, rgb_frame):
@@ -418,3 +423,113 @@ def close(self):
     rec.stop()
 
     assert written[0].shape == (10, 20, 3)
+
+
+class TestVideoRecorderTimestampSidecar:
+    def test_stop_writes_software_only_timestamp_sidecar_json(
+        self,
+        patch_writegear,
+        output_path,
+        rgb_frame,
+    ):
+        rec = vr_mod.VideoRecorder(output_path, buffer_size=10)
+        rec.start()
+
+        rec.write(rgb_frame, timestamp=10.0)
+        rec.write(rgb_frame, timestamp=12.0)
+
+        wait_until(lambda: len(FakeWriteGear.instances[0].frames) >= 2)
+        rec.stop()
+
+        ts_path = output_path.with_suffix("").with_suffix(output_path.suffix + "_timestamps.json")
+        assert ts_path.exists()
+
+        data = json.loads(ts_path.read_text())
+
+        assert data["schema_version"] == 2
+        assert data["video_file"] == output_path.name
+        assert data["num_frames"] == 2
+
+        # Backward-compatible list.
+        assert data["timestamps"] == [10.0, 12.0]
+
+        assert data["timestamp_sources"]["software_timestamp"]["kind"] == "software_wall_clock"
+        assert data["timestamp_sources"]["hardware_timestamp"] is None
+
+        assert data["frame_timestamps"] == [
+            {
+                "frame_index": 0,
+                "software_timestamp": 10.0,
+            },
+            {
+                "frame_index": 1,
+                "software_timestamp": 12.0,
+            },
+        ]
+
+    def test_stop_writes_hardware_timestamp_metadata_sidecar_json(
+        self,
+        patch_writegear,
+        output_path,
+        rgb_frame,
+    ):
+        rec = vr_mod.VideoRecorder(output_path, buffer_size=10)
+        rec.start()
+
+        meta = FrameTimestampMetadata(
+            source="grab_result.GetTimeStamp",
+            backend="basler",
+            default_reported="seconds",
+            seconds=0.001,
+            raw_value=1_000_000,
+            raw_unit="ticks",
+            tick_frequency_hz=1_000_000_000.0,
+            timebase="Basler camera timestamp counter",
+            kind="camera_clock",
+        )
+
+        rec.write(rgb_frame, timestamp=10.0, timestamp_metadata=meta)
+
+        wait_until(lambda: len(FakeWriteGear.instances[0].frames) >= 1)
+        rec.stop()
+
+        ts_path = output_path.with_suffix("").with_suffix(output_path.suffix + "_timestamps.json")
+        assert ts_path.exists()
+
+        data = json.loads(ts_path.read_text())
+
+        assert data["schema_version"] == 2
+        assert data["video_file"] == output_path.name
+        assert data["num_frames"] == 1
+
+        # Backward-compatible software timestamp list.
+        assert data["timestamps"] == [10.0]
+        assert data["start_time"] == 10.0
+        assert data["end_time"] == 10.0
+        assert data["duration_seconds"] == 0.0
+
+        # Static hardware source metadata is written once.
+        hw_source = data["timestamp_sources"]["hardware_timestamp"]
+        assert hw_source == {
+            "source": "grab_result.GetTimeStamp",
+            "backend": "basler",
+            "default_reported": "seconds",
+            "raw_unit": "ticks",
+            "tick_frequency_hz": 1_000_000_000.0,
+            "timebase": "Basler camera timestamp counter",
+            "kind": "camera_clock",
+            "extra": {},
+        }
+
+        # Per-frame records contain only per-frame values.
+        frame_ts = data["frame_timestamps"]
+        assert len(frame_ts) == 1
+
+        rec0 = frame_ts[0]
+        assert rec0["frame_index"] == 0
+        assert rec0["software_timestamp"] == 10.0
+        assert rec0["hardware_timestamp"] == {
+            "seconds": 0.001,
+            "raw_value": 1_000_000,
+        }
+        assert rec0["hardware_timestamp_default"] == 0.001

tests/utils/test_timestamps.py

@@ -0,0 +1,63 @@
+import pytest
+
+from dlclivegui.utils.timestamps import FrameTimestampMetadata
+
+
+class TestFrameTimestampMetadata:
+    def test_splits_source_and_frame_values(self):
+        meta = FrameTimestampMetadata(
+            source="grab_result.GetTimeStamp",
+            backend="basler",
+            default_reported="seconds",
+            seconds=0.123456789,
+            wall_clock_time=None,
+            raw_value=123456789,
+            raw_unit="ticks",
+            tick_frequency_hz=1_000_000_000.0,
+            timebase="Basler camera timestamp counter",
+            kind="camera_clock",
+        )
+
+        assert meta.to_source_dict() == {
+            "source": "grab_result.GetTimeStamp",
+            "backend": "basler",
+            "default_reported": "seconds",
+            "raw_unit": "ticks",
+            "tick_frequency_hz": 1_000_000_000.0,
+            "timebase": "Basler camera timestamp counter",
+            "kind": "camera_clock",
+            "extra": {},
+        }
+
+        frame_dict = meta.to_frame_dict()
+        assert frame_dict["seconds"] == pytest.approx(0.123456789)
+        assert frame_dict["raw_value"] == 123456789
+        assert "wall_clock_time" not in frame_dict
+
+        assert meta.get_default_reported() == pytest.approx(0.123456789)
+
+    def test_default_reported_raw_value(self):
+        meta = FrameTimestampMetadata(
+            source="device_counter",
+            backend="some_backend",
+            default_reported="raw_value",
+            raw_value=42,
+            raw_unit="frames",
+            kind="frame_counter",
+        )
+
+        assert meta.to_frame_dict() == {"raw_value": 42}
+        assert meta.get_default_reported() == 42
+
+    def test_unknown_default_field_returns_none(self):
+        meta = FrameTimestampMetadata(
+            source="device_counter",
+            backend="some_backend",
+            default_reported="seconds",
+            raw_value=42,
+            raw_unit="frames",
+            kind="frame_counter",
+        )
+
+        assert meta.to_frame_dict() == {"raw_value": 42}
+        assert meta.get_default_reported() is None