chore: update demo runtime, tests, and agent docs

opengait/demo/input.py

@@ -18,6 +18,7 @@ logger = logging.getLogger(__name__)
 # Type alias for frame stream: (frame_array, metadata_dict)
 FrameStream = Iterable[tuple[np.ndarray, dict[str, object]]]
 
+
 # Protocol for cv-mmap metadata (needed at runtime for nested function annotation)
 class _FrameMetadata(Protocol):
     frame_count: int
@@ -58,6 +59,13 @@ def opencv_source(
     if not cap.isOpened():
         raise RuntimeError(f"Failed to open video source: {path}")
 
+    is_file_source = isinstance(path, str)
+    source_fps = float(cap.get(cv2.CAP_PROP_FPS)) if is_file_source else 0.0
+    fps_valid = source_fps > 0.0 and np.isfinite(source_fps)
+    fallback_fps = source_fps if fps_valid else 30.0
+    fallback_interval_ns = int(1_000_000_000 / fallback_fps)
+    start_ns = time.monotonic_ns()
+
     frame_idx = 0
     try:
         while max_frames is None or frame_idx < max_frames:
@@ -66,14 +74,22 @@ def opencv_source(
                 # End of stream
                 break
 
-            # Get timestamp if available (some backends support this)
-            timestamp_ns = time.monotonic_ns()
+            if is_file_source:
+                pos_msec = float(cap.get(cv2.CAP_PROP_POS_MSEC))
+                if np.isfinite(pos_msec) and pos_msec > 0.0:
+                    timestamp_ns = start_ns + int(pos_msec * 1_000_000)
+                else:
+                    timestamp_ns = start_ns + frame_idx * fallback_interval_ns
+            else:
+                timestamp_ns = time.monotonic_ns()
 
             metadata: dict[str, object] = {
                 "frame_count": frame_idx,
                 "timestamp_ns": timestamp_ns,
                 "source": path,
             }
+            if fps_valid:
+                metadata["source_fps"] = source_fps
 
             yield frame, metadata
             frame_idx += 1
@@ -118,7 +134,6 @@ def cvmmap_source(
     # Import cvmmap only when function is called
     # Use try/except for runtime import check
     try:
-
         from cvmmap import CvMmapClient as _CvMmapClientReal  # pyright: ignore[reportMissingTypeStubs]
     except ImportError as e:
         raise ImportError(