streamvision 0.1.0rc1__tar.gz

streamvision-0.1.0rc1/LICENSE

@@ -0,0 +1,7 @@
+LICENSE.core (Apache 2.0) applies to all files in this repository
+except for files in or under any directory that contains a superseding
+license file (such as the models located in `inference/models/`
+which are governed by their own individual licenses and
+the files and folders in the `inference/enterprise/` and `inference_cli/lib/enterprise/` directories which are
+governed by the Roboflow Enterprise License located at
+`inference/enterprise/LICENSE.txt`).

streamvision-0.1.0rc1/PKG-INFO

@@ -0,0 +1,42 @@
+Metadata-Version: 2.4
+Name: streamvision
+Version: 0.1.0rc1
+Summary: Video sources, InferencePipeline and the stream manager for Roboflow Inference
+License: LICENSE.core (Apache 2.0) applies to all files in this repository
+        except for files in or under any directory that contains a superseding
+        license file (such as the models located in `inference/models/`
+        which are governed by their own individual licenses and
+        the files and folders in the `inference/enterprise/` and `inference_cli/lib/enterprise/` directories which are
+        governed by the Roboflow Enterprise License located at
+        `inference/enterprise/LICENSE.txt`).
+Requires-Python: <3.14,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy<2.4.0,>=2.0.0
+Requires-Dist: opencv-python<4.13.0,>=4.8.1.78
+Requires-Dist: supervision<0.30.0,>=0.29.0
+Requires-Dist: pydantic<2.12.0,>=2.8.0
+Requires-Dist: psutil>=7.0.0
+Requires-Dist: roboflow-workflows>=0.2.4rc1
+Provides-Extra: webrtc
+Requires-Dist: aiortc>=1.9.0; extra == "webrtc"
+Requires-Dist: av==14.2.0; extra == "webrtc"
+Provides-Extra: test
+Requires-Dist: pytest<10.0.0,>=9.0.3; extra == "test"
+Requires-Dist: requests-mock~=1.12.1; extra == "test"
+Requires-Dist: tomli>=2.0.0; python_version < "3.11" and extra == "test"
+Dynamic: license-file
+
+# streamvision
+
+`streamvision` holds the host-neutral pieces of Roboflow Inference's video
+stack: camera acquisition (`VideoSource` and its producers), the host-neutral
+`InferencePipeline`, the stream-manager TCP client and its wire entities, and
+the stream-manager runtime that hosts pipelines as subprocesses. It is a
+sibling distribution to `roboflow-workflows`, installable on its own or
+embedded in the full Inference server.
+
+The historical `inference.core.interfaces.{camera,stream,stream_manager}`
+import paths resolve to the same modules here when `inference` is installed.
+No `gpu`/`jetson` extra is declared: GStreamer/NVDEC support is provisioned by
+the Docker images, not pinned as a PyPI dependency in `requirements/`.

streamvision-0.1.0rc1/README.md

@@ -0,0 +1,13 @@
+# streamvision
+
+`streamvision` holds the host-neutral pieces of Roboflow Inference's video
+stack: camera acquisition (`VideoSource` and its producers), the host-neutral
+`InferencePipeline`, the stream-manager TCP client and its wire entities, and
+the stream-manager runtime that hosts pipelines as subprocesses. It is a
+sibling distribution to `roboflow-workflows`, installable on its own or
+embedded in the full Inference server.
+
+The historical `inference.core.interfaces.{camera,stream,stream_manager}`
+import paths resolve to the same modules here when `inference` is installed.
+No `gpu`/`jetson` extra is declared: GStreamer/NVDEC support is provisioned by
+the Docker images, not pinned as a PyPI dependency in `requirements/`.

streamvision-0.1.0rc1/pyproject.toml

@@ -0,0 +1,34 @@
+[project]
+name = "streamvision"
+version = "0.1.0rc1"
+description = "Video sources, InferencePipeline and the stream manager for Roboflow Inference"
+readme = "README.md"
+license = {file = "LICENSE"}
+requires-python = ">=3.10,<3.14"
+dependencies = [
+  "numpy>=2.0.0,<2.4.0",
+  "opencv-python>=4.8.1.78,<4.13.0",
+  "supervision>=0.29.0,<0.30.0",
+  "pydantic>=2.8.0,<2.12.0",
+  "psutil>=7.0.0",
+  "roboflow-workflows>=0.2.4rc1",
+]
+
+[project.optional-dependencies]
+webrtc = [
+  "aiortc>=1.9.0",
+  "av==14.2.0",
+]
+test = [
+  "pytest>=9.0.3,<10.0.0",
+  "requests-mock~=1.12.1",
+  "tomli>=2.0.0; python_version < '3.11'",
+]
+
+[build-system]
+requires = ["setuptools>=83.0.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["streamvision*"]
+exclude = ["tests*", "build_scripts*", "scripts*"]

streamvision-0.1.0rc1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

streamvision-0.1.0rc1/streamvision/__init__.py

@@ -0,0 +1 @@
+"""Camera acquisition, InferencePipeline, and the stream-manager client and runtime."""

streamvision-0.1.0rc1/streamvision/camera/buffer_strategies.py

@@ -0,0 +1,28 @@
+"""Buffer strategies of a video source, importable without the decoder.
+
+Request entities validate these values without needing cv2 or the video
+source itself. `video_source` re-exports both enums, and each class keeps the
+`__module__` it was historically defined in, so signatures, annotations and
+pickles still name `video_source` exactly as before the extraction.
+"""
+
+from enum import Enum
+
+_HISTORICAL_MODULE = f"{__name__.rsplit('.', 1)[0]}.video_source"
+
+
+class BufferFillingStrategy(str, Enum):
+    WAIT = "WAIT"
+    DROP_OLDEST = "DROP_OLDEST"
+    ADAPTIVE_DROP_OLDEST = "ADAPTIVE_DROP_OLDEST"
+    DROP_LATEST = "DROP_LATEST"
+    ADAPTIVE_DROP_LATEST = "ADAPTIVE_DROP_LATEST"
+
+
+class BufferConsumptionStrategy(str, Enum):
+    LAZY = "LAZY"
+    EAGER = "EAGER"
+
+
+BufferFillingStrategy.__module__ = _HISTORICAL_MODULE
+BufferConsumptionStrategy.__module__ = _HISTORICAL_MODULE

streamvision-0.1.0rc1/streamvision/camera/camera.py

@@ -0,0 +1,138 @@
+import logging
+import os
+import time
+from threading import Thread
+
+import cv2
+from PIL import Image
+
+logger = logging.getLogger(__name__)
+
+
+class WebcamStream:
+    """Class to handle webcam streaming using a separate thread.
+
+    Attributes:
+        stream_id (int): The ID of the webcam stream.
+        frame_id (int): A counter for the current frame.
+        vcap (VideoCapture): OpenCV video capture object.
+        width (int): The width of the video frame.
+        height (int): The height of the video frame.
+        fps_input_stream (int): Frames per second of the input stream.
+        grabbed (bool): A flag indicating if a frame was successfully grabbed.
+        frame (array): The current frame as a NumPy array.
+        pil_image (Image): The current frame as a PIL image.
+        stopped (bool): A flag indicating if the stream is stopped.
+        t (Thread): The thread used to update the stream.
+    """
+
+    def __init__(self, stream_id=0, enforce_fps=False):
+        """Initialize the webcam stream.
+
+        Args:
+            stream_id (int, optional): The ID of the webcam stream. Defaults to 0.
+        """
+        self.stream_id = stream_id
+        self.enforce_fps = enforce_fps
+        self.frame_id = 0
+        self.vcap = cv2.VideoCapture(self.stream_id)
+
+        for key in os.environ:
+            if key.startswith("CV2_CAP_PROP"):
+                opencv_prop = key[4:]
+                opencv_constant = getattr(cv2, opencv_prop, None)
+                if opencv_constant is not None:
+                    value = int(os.getenv(key))
+                    self.vcap.set(opencv_constant, value)
+                    logger.info(f"set {opencv_prop} to {value}")
+                else:
+                    logger.warning(f"Property {opencv_prop} not found in cv2")
+
+        self.width = int(self.vcap.get(cv2.CAP_PROP_FRAME_WIDTH))
+        self.height = int(self.vcap.get(cv2.CAP_PROP_FRAME_HEIGHT))
+        self.file_mode = self.vcap.get(cv2.CAP_PROP_FRAME_COUNT) > 0
+        if self.enforce_fps and not self.file_mode:
+            logger.warning(
+                "Ignoring enforce_fps flag for this stream. It is not compatible with streams and will cause the process to crash"
+            )
+            self.enforce_fps = False
+        self.max_fps = None
+        if self.vcap.isOpened() is False:
+            logger.debug("[Exiting]: Error accessing webcam stream.")
+            exit(0)
+        self.fps_input_stream = int(self.vcap.get(cv2.CAP_PROP_FPS))
+        logger.debug(
+            "FPS of webcam hardware/input stream: {}".format(self.fps_input_stream)
+        )
+        self.grabbed, self.frame = self.vcap.read()
+        self.pil_image = Image.fromarray(cv2.cvtColor(self.frame, cv2.COLOR_BGR2RGB))
+        if self.grabbed is False:
+            logger.debug("[Exiting] No more frames to read")
+            exit(0)
+        self.stopped = True
+        self.t = Thread(target=self.update, args=())
+        self.t.daemon = True
+
+    def start(self):
+        """Start the thread for reading frames."""
+        self.stopped = False
+        self.t.start()
+
+    def update(self):
+        """Update the frame by reading from the webcam."""
+        frame_id = 0
+        next_frame_time = 0
+        t0 = time.perf_counter()
+        while True:
+            t1 = time.perf_counter()
+            if self.stopped is True:
+                break
+
+            self.grabbed = self.vcap.grab()
+            if self.grabbed is False:
+                logger.debug("[Exiting] No more frames to read")
+                self.stopped = True
+                break
+            frame_id += 1
+            # We can't retrieve each frame on nano and other lower powered devices quickly enough to keep up with the stream.
+            # By default, we will only retrieve frames when we'll be ready process them (determined by self.max_fps).
+            if t1 > next_frame_time:
+                ret, frame = self.vcap.retrieve()
+                if frame is None:
+                    logger.debug("[Exiting] Frame not available for read")
+                    self.stopped = True
+                    break
+                logger.debug(
+                    f"retrieved frame {frame_id}, effective FPS: {frame_id / (t1 - t0):.2f}"
+                )
+                self.frame_id = frame_id
+                self.frame = frame
+                while self.file_mode and self.enforce_fps and self.max_fps is None:
+                    # sleep until we have processed the first frame and we know what our FPS should be
+                    time.sleep(0.01)
+                if self.max_fps is None:
+                    self.max_fps = 30
+                next_frame_time = t1 + (1 / self.max_fps) + 0.02
+            if self.file_mode:
+                t2 = time.perf_counter()
+                if self.enforce_fps:
+                    # when enforce_fps is true, grab video frames 1:1 with inference speed
+                    time_to_sleep = next_frame_time - t2
+                else:
+                    # otherwise, grab at native FPS of the video file
+                    time_to_sleep = (1 / self.fps_input_stream) - (t2 - t1)
+                if time_to_sleep > 0:
+                    time.sleep(time_to_sleep)
+        self.vcap.release()
+
+    def read_opencv(self):
+        """Read the current frame using OpenCV.
+
+        Returns:
+            array, int: The current frame as a NumPy array, and the frame ID.
+        """
+        return self.frame, self.frame_id
+
+    def stop(self):
+        """Stop the webcam stream."""
+        self.stopped = True

streamvision-0.1.0rc1/streamvision/camera/collection_policy.py

@@ -0,0 +1,377 @@
+"""Collection policies for multi-source video consumption in InferencePipeline.
+
+Motivation (measured on Jetson AGX Orin, 8x 2K@15 RTSP): consumer cameras emit
+frames in bursts separated by encoder pauses of 400-500 ms around every
+I-frame. The legacy blocking batch collection waits for a fresh frame from
+EVERY source per cycle, so with several staggered cameras almost every batch
+stalls on whichever source is inside its pause - throughput collapses to a
+fraction of the aggregate frame rate while decoded frames are silently
+discarded. The policies in this module remove that coupling:
+
+* the batch-collection window self-tunes from the pipeline's own rhythms
+  instead of a hand-picked ``batch_collection_timeout``: once per-source
+  arrival rates are measured, the round period is matched to the fastest
+  live source's frame period (full batches whenever the model has headroom,
+  floor-window under saturation); before estimates exist it falls back to a
+  fraction of the measured execution time,
+* consumption is FIFO with a bounded staleness budget - every frame is served
+  while the consumer keeps up, and under overload served frames are never
+  older than ``max_staleness`` (drops are counted and reported, not silent).
+
+File sources are exempt from the staleness budget by design: file decoding is
+demand-paced (a "stale" frame only means the consumer was busy) and dropping
+frames from a file would silently corrupt every-frame processing guarantees.
+"""
+
+import logging
+from collections import deque
+from datetime import datetime
+from enum import Enum
+from time import monotonic
+from typing import TYPE_CHECKING, Callable, Deque, Dict, Optional, Union
+
+from streamvision.camera.entities import VideoFrame
+from streamvision.stream import environment as streams_environment
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from streamvision.camera.video_source import VideoSource
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_MAX_STALENESS_SECONDS = 0.5
+MIN_COLLECTION_WINDOW_SECONDS = 0.002
+MAX_COLLECTION_WINDOW_SECONDS = 0.030
+COLLECTION_WINDOW_EXECUTION_FRACTION = 0.2
+EXECUTION_GAP_EMA_ALPHA = 0.2
+FRESHEST_MODE_BATCH_COLLECTION_TIMEOUT = 0.02
+STALENESS_DROP_CAUSE = "STALENESS_BUDGET_EXCEEDED"
+LEGACY_MODE_ALIASES = frozenset({"legacy", "none"})
+# Rate-matched window: cap and the arrival-period estimator's shape. The
+# estimator is count-over-span (never an EMA of gaps - bursty encoders like
+# consumer RTSP cameras emit 2-frame clusters around GOP pauses, and gap
+# EMAs oscillate at the burst frequency while a span over several burst
+# cycles converges on the true rate).
+RATE_MATCHED_WINDOW_CAP_SECONDS = 0.1
+# Give the first model invocation a bounded chance to receive the full live
+# cohort. Shape-specialised runtimes such as TensorRT can otherwise spend their
+# cold start preparing a tiny partial-batch plan before arrival estimates exist.
+# After the first non-empty round, the execution/rate controller takes over.
+INITIAL_COLLECTION_WINDOW_SECONDS = RATE_MATCHED_WINDOW_CAP_SECONDS
+ARRIVAL_PERIOD_SAMPLE_WINDOW = 64
+MIN_ARRIVAL_SAMPLES_TO_TRUST = 16
+SOURCE_ACTIVITY_HORIZON_SECONDS = 2.0
+
+
+class VideoProcessingMode(str, Enum):
+    """High-level intent for live multi-source consumption.
+
+    * AUTO - FIFO consumption with a staleness budget and a self-tuning
+      collection window. Serves every frame while the consumer keeps up;
+      under overload degrades to freshest-at-capacity with bounded,
+      reported drops.
+    * EVERY_FRAME - AUTO's machinery with the staleness budget disabled:
+      strict FIFO for live sources (under sustained overload latency pins
+      at the decoding-buffer depth).
+    * FRESHEST - legacy latest-wins semantics (EAGER consumption) with a
+      small fixed collection timeout; minimal latency, silent skipping.
+    """
+
+    AUTO = "auto"
+    EVERY_FRAME = "every_frame"
+    FRESHEST = "freshest"
+
+
+def resolve_video_processing_mode(
+    explicit_mode: Optional[Union[str, VideoProcessingMode]],
+) -> Optional[VideoProcessingMode]:
+    """Resolve the effective processing mode.
+
+    Order: explicit argument > tensor-representation cohort default (AUTO
+    when ``ENABLE_TENSOR_DATA_REPRESENTATION`` is set - the same opt-in
+    boundary that already gates decoding-buffer depth) > ``None`` meaning
+    the legacy collection behavior, byte-for-byte. The explicit strings
+    ``"legacy"`` / ``"none"`` force the legacy behavior even inside the
+    tensor cohort - the escape hatch from the flag-driven AUTO default.
+    """
+    if explicit_mode is not None:
+        if (
+            isinstance(explicit_mode, str)
+            and explicit_mode.lower() in LEGACY_MODE_ALIASES
+        ):
+            return None
+        return VideoProcessingMode(explicit_mode)
+    if streams_environment.ENABLE_TENSOR_DATA_REPRESENTATION:
+        return VideoProcessingMode.AUTO
+    return None
+
+
+class _SourceArrivalEstimator:
+    """Count-over-span estimate of one live source's true frame period.
+
+    Fed with ingress capture timestamps (``VideoFrame.frame_timestamp`` is
+    stamped on the decode thread), so downstream queueing cannot distort the
+    span. A gap longer than the activity horizon (reconnect, stall) clears
+    the window - a rejoin gap is not a frame period - and the estimate stays
+    ``None`` until enough fresh samples accumulate again.
+    """
+
+    def __init__(self, sample_window: int = ARRIVAL_PERIOD_SAMPLE_WINDOW):
+        self._timestamps: Deque[datetime] = deque(maxlen=sample_window)
+        self._last_seen_at: Optional[float] = None
+
+    def observe(self, frame_timestamp: datetime, now: float) -> None:
+        if self._timestamps:
+            gap = (frame_timestamp - self._timestamps[-1]).total_seconds()
+            if gap > SOURCE_ACTIVITY_HORIZON_SECONDS or gap < 0:
+                self._timestamps.clear()
+        self._timestamps.append(frame_timestamp)
+        self._last_seen_at = now
+
+    def period(self, now: float) -> Optional[float]:
+        if (
+            self._last_seen_at is None
+            or now - self._last_seen_at > SOURCE_ACTIVITY_HORIZON_SECONDS
+        ):
+            return None
+        if len(self._timestamps) < MIN_ARRIVAL_SAMPLES_TO_TRUST:
+            return None
+        span = (self._timestamps[-1] - self._timestamps[0]).total_seconds()
+        if span <= 0:
+            return None
+        return span / (len(self._timestamps) - 1)
+
+
+class AdaptiveWindowController:
+    """Self-tunes the batch-collection window from the collection rhythm.
+
+    Two regimes, picked per round by whether a trustworthy arrival-period
+    estimate exists:
+
+    * RATE-MATCHED (estimate available): ``window = clamp(min live source
+      period - exec EMA, floor, cap)``. The round period then equals the
+      fastest source's frame period, so in the light-load regime every
+      round finds each source with exactly one fresh frame - full batches
+      by construction. Under saturation (exec >= period) the subtraction
+      goes negative and the window floors, which is the correct move: every
+      source already has frames queued when the round starts. The added
+      collection wait is offset by removed queue wait (a frame that misses
+      a round today sits in the LAZY queue for a full round period), so
+      end-to-end latency stays roughly flat while occupancy rises.
+    * FALLBACK (startup, no live estimates): a fraction of the exec-time
+      EMA, clamped - light models get a near-zero window, heavy models a
+      larger alignment window.
+
+    The gap between a non-empty collection finishing and the next collection
+    starting is, by construction, the batch execution time.
+    """
+
+    def __init__(
+        self,
+        alpha: float = EXECUTION_GAP_EMA_ALPHA,
+        execution_fraction: float = COLLECTION_WINDOW_EXECUTION_FRACTION,
+        min_window: float = MIN_COLLECTION_WINDOW_SECONDS,
+        max_window: float = MAX_COLLECTION_WINDOW_SECONDS,
+        initial_window: float = INITIAL_COLLECTION_WINDOW_SECONDS,
+        rate_matched_cap: float = RATE_MATCHED_WINDOW_CAP_SECONDS,
+        clock: Callable[[], float] = monotonic,
+    ):
+        self._alpha = alpha
+        self._execution_fraction = execution_fraction
+        self._min_window = min_window
+        self._max_window = max_window
+        self._rate_matched_cap = rate_matched_cap
+        self._window = initial_window
+        self._clock = clock
+        self._execution_gap_ema: Optional[float] = None
+        self._last_non_empty_collection_end: Optional[float] = None
+
+    def on_collection_start(
+        self, minimum_arrival_period: Optional[float] = None
+    ) -> float:
+        now = self._clock()
+        if self._last_non_empty_collection_end is not None:
+            execution_gap = now - self._last_non_empty_collection_end
+            if self._execution_gap_ema is None:
+                self._execution_gap_ema = execution_gap
+            else:
+                self._execution_gap_ema = (
+                    1 - self._alpha
+                ) * self._execution_gap_ema + self._alpha * execution_gap
+            if minimum_arrival_period is not None:
+                rate_matched = minimum_arrival_period - self._execution_gap_ema
+                self._window = min(
+                    max(rate_matched, self._min_window),
+                    self._rate_matched_cap,
+                )
+            else:
+                self._window = min(
+                    max(
+                        self._execution_fraction * self._execution_gap_ema,
+                        self._min_window,
+                    ),
+                    self._max_window,
+                )
+        return self._window
+
+    def on_collection_end(self, collected_any_frame: bool) -> None:
+        self._last_non_empty_collection_end = (
+            self._clock() if collected_any_frame else None
+        )
+
+    @property
+    def window(self) -> float:
+        return self._window
+
+    @property
+    def execution_gap_ema(self) -> Optional[float]:
+        return self._execution_gap_ema
+
+
+class CollectionPolicy:
+    """Per-round collection behavior for AUTO / EVERY_FRAME modes.
+
+    Live sources are read FIFO with frames older than ``max_staleness``
+    dropped (counted, optionally reported via ``on_frame_dropped``). File
+    sources - and sources whose properties are not yet known - are read
+    as-is and NEVER dropped; liveness is resolved lazily from
+    ``VideoSource.describe_source()`` and cached once known.
+    """
+
+    def __init__(
+        self,
+        mode: VideoProcessingMode,
+        max_staleness: Optional[float] = None,
+        on_frame_dropped: Optional[Callable[[VideoFrame], None]] = None,
+        window_controller: Optional[AdaptiveWindowController] = None,
+    ):
+        if mode is VideoProcessingMode.FRESHEST:
+            raise ValueError(
+                "FRESHEST mode is realised through EAGER buffer consumption "
+                "and does not use CollectionPolicy"
+            )
+        self._mode = mode
+        if mode is VideoProcessingMode.EVERY_FRAME:
+            self._max_staleness = None
+        else:
+            self._max_staleness = (
+                DEFAULT_MAX_STALENESS_SECONDS
+                if max_staleness is None
+                else max_staleness
+            )
+        self._on_frame_dropped = on_frame_dropped
+        self._window_controller = window_controller or AdaptiveWindowController()
+        self._source_is_file: Dict[int, bool] = {}
+        self._frames_dropped_on_staleness: Dict[int, int] = {}
+        self._arrival_estimators: Dict[int, _SourceArrivalEstimator] = {}
+
+    @property
+    def mode(self) -> VideoProcessingMode:
+        return self._mode
+
+    @property
+    def max_staleness(self) -> Optional[float]:
+        return self._max_staleness
+
+    @property
+    def frames_dropped_on_staleness(self) -> Dict[int, int]:
+        return dict(self._frames_dropped_on_staleness)
+
+    def collection_window(self) -> float:
+        return self._window_controller.on_collection_start(
+            minimum_arrival_period=self.minimum_live_arrival_period()
+        )
+
+    def minimum_live_arrival_period(self) -> Optional[float]:
+        """Smallest trustworthy frame period across ACTIVE live sources.
+
+        The fastest source is the binding constraint for the rate-matched
+        window: a round period above ANY source's frame period makes that
+        source queue unboundedly. Files never contribute (demand-paced,
+        always ready) and dormant sources drop out via the activity horizon
+        so a dying camera cannot pin the window while it flaps.
+        """
+        now = monotonic()
+        periods = [
+            period
+            for period in (
+                estimator.period(now) for estimator in self._arrival_estimators.values()
+            )
+            if period is not None
+        ]
+        if not periods:
+            return None
+        return min(periods)
+
+    def note_collection_result(self, batch_frames: list) -> None:
+        self._window_controller.on_collection_end(
+            collected_any_frame=bool(batch_frames)
+        )
+
+    def read_frame(
+        self,
+        source_ord: int,
+        source: "VideoSource",
+        timeout: Optional[float],
+    ) -> Optional[VideoFrame]:
+        treated_as_file = self._source_treated_as_file(
+            source_ord=source_ord, source=source
+        )
+        if self._max_staleness is None or treated_as_file:
+            frame = source.read_frame(timeout=timeout)
+            if frame is not None and not treated_as_file:
+                self._observe_arrival(source_ord=source_ord, frame=frame)
+            return frame
+        deadline = None if timeout is None else monotonic() + timeout
+        while True:
+            remaining = None if deadline is None else max(deadline - monotonic(), 0.0)
+            frame = source.read_frame(timeout=remaining)
+            if frame is None:
+                return None
+            # Staleness-drained frames feed the estimator too: they are real
+            # arrivals, and skipping them would bias the period estimate
+            # upward exactly when the pipeline is busiest.
+            self._observe_arrival(source_ord=source_ord, frame=frame)
+            frame_age = (datetime.now() - frame.frame_timestamp).total_seconds()
+            if frame_age <= self._max_staleness:
+                return frame
+            self._register_staleness_drop(source_ord=source_ord, frame=frame)
+
+    def _observe_arrival(self, source_ord: int, frame: VideoFrame) -> None:
+        estimator = self._arrival_estimators.get(source_ord)
+        if estimator is None:
+            estimator = _SourceArrivalEstimator()
+            self._arrival_estimators[source_ord] = estimator
+        estimator.observe(frame_timestamp=frame.frame_timestamp, now=monotonic())
+
+    def _source_treated_as_file(self, source_ord: int, source: "VideoSource") -> bool:
+        cached = self._source_is_file.get(source_ord)
+        if cached is not None:
+            return cached
+        is_file: Optional[bool] = None
+        try:
+            source_metadata = source.describe_source()
+            source_properties = source_metadata.source_properties
+            if source_properties is not None:
+                is_file = source_properties.is_file
+        except Exception:  # noqa: BLE001 - metadata probe must never break reads
+            is_file = None
+        if is_file is None:
+            # Liveness unknown (source still initialising) - never drop.
+            return True
+        self._source_is_file[source_ord] = is_file
+        return is_file
+
+    def _register_staleness_drop(self, source_ord: int, frame: VideoFrame) -> None:
+        self._frames_dropped_on_staleness[source_ord] = (
+            self._frames_dropped_on_staleness.get(source_ord, 0) + 1
+        )
+        if self._on_frame_dropped is None:
+            return
+        try:
+            self._on_frame_dropped(frame)
+        except Exception:  # noqa: BLE001 - reporting must never break collection
+            logger.warning(
+                "on_frame_dropped callback raised while reporting a staleness "
+                "drop for source %s",
+                frame.source_id,
+            )