reactor-runtime 3.2.1__tar.gz → 3.2.3__tar.gz

{reactor_runtime-3.2.1 → reactor_runtime-3.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reactor-runtime
-Version: 3.2.1
+Version: 3.2.3
 Summary: A Python framework for building real-time, interactive video models
 Author: Reactor
 Author-email: Reactor <team@reactor.inc>
@@ -18,7 +18,7 @@ Requires-Dist: numpy>=2.1
 Requires-Dist: prometheus-client>=0.26.0
 Requires-Dist: protobuf>=7.35.1
 Requires-Dist: pyyaml>=6.0.3
-Requires-Dist: reactor-webrtc==0.10.0
+Requires-Dist: reactor-webrtc==0.12.0
 Requires-Dist: uvicorn>=0.49.0
 Requires-Python: >=3.12
 Project-URL: Source, https://github.com/reactor-team/reactor-runtime

{reactor_runtime-3.2.1 → reactor_runtime-3.2.3}/pyproject.toml

@@ -92,7 +92,7 @@ pythonpath = ["."]
 
 [project]
 name = "reactor-runtime"
-version = "3.2.1"
+version = "3.2.3"
 description = "A Python framework for building real-time, interactive video models"
 readme = "README.md"
 license = "Apache-2.0"
@@ -115,7 +115,7 @@ dependencies = [
     "prometheus-client>=0.26.0",
     "protobuf>=7.35.1",
     "pyyaml>=6.0.3",
-    "reactor-webrtc==0.10.0",
+    "reactor-webrtc==0.12.0",
     "uvicorn>=0.49.0",
 ]
 

{reactor_runtime-3.2.1 → reactor_runtime-3.2.3}/pyproject.toml.orig

@@ -20,7 +20,7 @@ version = "1.20260814.7"
 
 [project]
 name = "reactor-runtime"
-version = "3.2.1"
+version = "3.2.3"
 description = "A Python framework for building real-time, interactive video models"
 readme = "README.md"
 license = "Apache-2.0"
@@ -41,7 +41,7 @@ dependencies = [
     "prometheus-client>=0.26.0",
     "protobuf>=7.35.1",
     "pyyaml>=6.0.3",
-    "reactor-webrtc==0.10.0",
+    "reactor-webrtc==0.12.0",
     "uvicorn>=0.49.0",
 ]
 

{reactor_runtime-3.2.1 → reactor_runtime-3.2.3}/src/reactor_runtime/core/values.py

@@ -64,15 +64,18 @@ class InputFrame:
         metadata: What the sender attached to this frame, as the bytes it sent,
             or ``None`` for a frame that carried nothing. Decoding them is the
             model's business: the transport treats them as opaque.
-        capture_time_us: The microsecond the sender stamped this frame as it went
-            to the wire — its capture instant for a source that sends as it
-            captures — or ``None`` for a frame that carried no stamp. The wire
-            value, unrounded, in the unit the sender's own SDK works in. It rides
-            with the metadata, so a sender or a transport that carries neither
-            leaves both unset. Unlike ``pts``, it is a reading of another
-            machine's clock: differences between stamps from one sender are that
-            source's own timing, while anything subtracted from a local clock is
-            mostly the offset between two clocks that drift independently.
+        capture_time_us: When the sender says this frame was captured, in
+            microseconds, or ``None`` for a frame that carried no stamp. The value
+            the sender declared, unrounded — a client that stamps several tracks
+            from one clock reading therefore delivers that one value on all of
+            them, which is what makes a multi-camera capture readable as a single
+            moment. A sender that declares nothing has its transport read a clock
+            for it, so a stamped frame is the normal case. It rides with the
+            metadata, so a sender or a transport that carries neither leaves both
+            unset. Unlike ``pts``, it is a reading of another machine's clock:
+            differences between stamps from one sender are that source's own
+            timing, while anything subtracted from a local clock is mostly the
+            offset between two clocks that drift independently.
     """
 
     data: npt.NDArray[Any]

{reactor_runtime-3.2.1 → reactor_runtime-3.2.3}/src/reactor_runtime/recording/recorder.py

@@ -15,7 +15,6 @@ director learns a clip is genuinely fetchable rather than merely requested.
 
 from __future__ import annotations
 
-import contextlib
 import math
 import queue
 import re
@@ -25,6 +24,7 @@ import threading
 import time
 from collections.abc import Callable
 from dataclasses import dataclass
+from enum import Enum
 from pathlib import Path
 from typing import Any
 from urllib.parse import urlencode
@@ -45,6 +45,21 @@ logger = get_logger(__name__)
 # model that runs slower or faster than real time still records at true duration.
 RECORDING_FPS = 30
 
+# How many grid frames may sit queued between the model thread and the encoder.
+# Never applied below one emission's worth, so a model that batches always fits
+# a whole emission: the queue absorbs a burst and drains it between emissions,
+# rather than gating the burst at its own depth.
+_FEED_DEPTH = 4
+# How long one emission may wait, in total, for the encoder to make room. Bounds
+# the producer's exposure to a wedged encoder: past the deadline the rest of the
+# emission is counted and abandoned, so a stalled recording costs the recording
+# rather than the session.
+_FEED_WAIT_SECONDS = 1.0
+# How often the feed reports dropped frames. An encoder that stays behind loses
+# frames on every emission, so the count is carried on every recording's summary
+# and only the periodic warning is rate-limited.
+_DROP_LOG_INTERVAL_SECONDS = 5.0
+
 _INIT_FILENAME = "init.mp4"
 # Written into a recording's directory once it is finished, so its final segment
 # (which has no successor to prove it closed) is recognised as fetchable.
@@ -72,6 +87,23 @@ _AudioArray = npt.NDArray[Any]
 _FeedItem = tuple[npt.NDArray[Any], _AudioArray | None]
 
 
+class _Slot(Enum):
+    """The answer to asking the feed queue for room for one grid frame.
+
+    Separates the two reasons room is refused, because only one of them is a
+    fact about the recording's health: frames abandoned because the encoder is
+    behind are the recording losing media, while frames abandoned because the
+    recording is stopping are teardown and say nothing about the encoder.
+    """
+
+    TAKEN = "taken"
+    """There is room; the frame can be queued."""
+    FULL = "full"
+    """The encoder is behind, and any wait the chunk asked for has run out."""
+    WINDING_DOWN = "winding_down"
+    """The recording is stopping, so the rest of the emission is moot."""
+
+
 class RecorderError(Exception):
     """Base for a clip request the recorder cannot serve."""
 
@@ -205,7 +237,13 @@ class Recorder:
         self._started = False
         self._disabled = False
 
-        self._feed_queue: queue.Queue[_FeedItem | None] = queue.Queue(maxsize=4)
+        # The queue is unbounded in itself; the depth is the bound, checked as
+        # each frame is queued. The effective capacity never sits below one
+        # emission, so a batching model always fits a whole emission.
+        self._feed_queue: queue.Queue[_FeedItem | None] = queue.Queue()
+        # Signalled by the feed worker after each dequeue so a producer waiting
+        # for room sleeps until the encoder takes a frame instead of polling.
+        self._feed_room = threading.Condition()
         self._feed_thread: threading.Thread | None = None
         self._feed_stop = threading.Event()
         self._watch_thread: threading.Thread | None = None
@@ -227,6 +265,9 @@ class Recorder:
         self._chunk_lock = threading.Lock()
 
         self._dropped_frames = 0
+        # When the feed last warned about dropped frames. Zero until it has, so
+        # the first loss of a session is always reported.
+        self._dropped_logged_at = 0.0
         # Fractional grid frames carried between chunks so resampling a chunk's
         # own rate onto the fixed recording grid accumulates no rounding drift.
         self._grid_debt = 0.0
@@ -311,8 +352,11 @@ class Recorder:
             return
         self._disabled = True
         self._feed_stop.set()
-        with contextlib.suppress(queue.Full):
-            self._feed_queue.put_nowait(None)
+        self._feed_queue.put_nowait(None)
+        # Release a producer parked on a full queue, so teardown cannot wait
+        # behind an encoder that has already stopped draining.
+        with self._feed_room:
+            self._feed_room.notify_all()
         feed_thread = self._feed_thread
         self._feed_thread = None
         if self._encoder is not None:
@@ -410,6 +454,7 @@ class Recorder:
         self._audio_sample_rate = 48_000
         self._has_audio = False
         self._dropped_frames = 0
+        self._dropped_logged_at = 0.0
         self._grid_debt = 0.0
         self._audio_jitter_buf = []
         self._audio_buffered_samples = 0
@@ -423,7 +468,7 @@ class Recorder:
     # -- media fan-out tap ----------------------------------------------------
 
     def on_chunk(self, chunk: MediaChunk) -> None:
-        """Feed one emitted media chunk to the recording; non-blocking.
+        """Feed one emitted media chunk to the recording.
 
         Called on the model thread by the runner's media fan-out. The chunk's
         frames are resampled from the chunk's own rate onto the fixed recording
@@ -433,8 +478,17 @@ class Recorder:
         duration. Fractional grid frames carry across chunks so the resampling
         accumulates no drift. The timeline advances by the media actually fed,
         not by wall-clock, so a pause simply stops advancing rather than
-        recording dead air. A frame that does not fit the feed queue is dropped
-        to keep the model thread unblocked.
+        recording dead air.
+
+        The feed queue holds at least a whole emission, so handing a batch over
+        costs the model thread nothing while the encoder keeps up. Once the
+        queue is full the chunk decides, exactly as it does at the wire: a chunk
+        that asks for backpressure (``chunk.wait``) makes this call wait for
+        room, bounded by :data:`_FEED_WAIT_SECONDS` across the emission, and one
+        that prefers skipping has its overflow dropped and counted. Only the
+        encoder falling behind is counted: an emission cut short because the
+        recording is stopping is teardown, and reporting it would put phantom
+        losses on the summary :meth:`stop` logs.
         """
         if self.disabled:
             return
@@ -456,24 +510,69 @@ class Recorder:
         grid_frames = int(self._grid_debt)
         self._grid_debt -= grid_frames
         audio_target = round(self._audio_sample_rate / RECORDING_FPS) if self._has_audio else 0
+        # One authoritative bound, never below the emission being queued, so the
+        # burst a batching model hands over always fits.
+        capacity = max(_FEED_DEPTH, grid_frames)
+        deadline = time.monotonic() + _FEED_WAIT_SECONDS
         fed = 0
+        outcome = _Slot.TAKEN
         for i in range(grid_frames):
+            outcome = self._claim_slot(capacity, wait=chunk.wait, deadline=deadline)
+            if outcome is not _Slot.TAKEN:
+                break
             video_data = frames[i * len(frames) // grid_frames]
             audio_data = self._take_audio(audio_target) if self._has_audio else None
-            try:
-                self._feed_queue.put_nowait((video_data, audio_data))
-            except queue.Full:
-                self._dropped_frames += 1
-                if self._dropped_frames == 1 or self._dropped_frames % 300 == 0:
-                    logger.warning(
-                        "recorder feed queue full; dropping a frame to keep the model unblocked",
-                        dropped_total=self._dropped_frames,
-                    )
-                break
+            self._feed_queue.put_nowait((video_data, audio_data))
             fed += 1
+        if outcome is _Slot.FULL:
+            self._count_dropped(grid_frames - fed, grid_frames)
         if fed:
             markers.advance(fed / RECORDING_FPS)
 
+    def _claim_slot(self, capacity: int, *, wait: bool, deadline: float) -> _Slot:
+        """Ask the feed queue for room for one more grid frame.
+
+        A chunk that asks for backpressure waits for the encoder to take a
+        frame, until *deadline* passes; one that does not reports the full queue
+        immediately so its caller can drop. A recording that is stopping answers
+        :attr:`_Slot.WINDING_DOWN` on either path, so teardown is never counted
+        against the encoder.
+        """
+        if self._feed_queue.qsize() < capacity:
+            return _Slot.TAKEN
+        if self._feed_stop.is_set() or self._disabled:
+            return _Slot.WINDING_DOWN
+        if not wait:
+            return _Slot.FULL
+        with self._feed_room:
+            while self._feed_queue.qsize() >= capacity:
+                if self._feed_stop.is_set() or self._disabled:
+                    return _Slot.WINDING_DOWN
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    return _Slot.FULL
+                self._feed_room.wait(timeout=min(remaining, 0.1))
+        return _Slot.TAKEN
+
+    def _count_dropped(self, dropped: int, offered: int) -> None:
+        """Record the frames an emission could not hand over, and say so.
+
+        Every dropped frame reaches the count, which the recording reports when
+        it stops; the warning itself is rate-limited so an encoder that stays
+        behind reports the loss periodically rather than once per emission.
+        """
+        self._dropped_frames += dropped
+        now = time.monotonic()
+        if now - self._dropped_logged_at < _DROP_LOG_INTERVAL_SECONDS:
+            return
+        self._dropped_logged_at = now
+        logger.warning(
+            "recorder feed queue full; dropping frames from an emission",
+            dropped=dropped,
+            offered=offered,
+            dropped_total=self._dropped_frames,
+        )
+
     def _video_frames(self, bundle: MediaBundle) -> list[npt.NDArray[Any]]:
         """Split the recorded video track into single ``(H, W, 3)`` frames.
 
@@ -537,6 +636,10 @@ class Recorder:
                 item = self._feed_queue.get(timeout=0.1)
             except queue.Empty:
                 continue
+            # Room opened the moment the frame left the queue, so a producer
+            # waiting on capacity is released before the encode, not after it.
+            with self._feed_room:
+                self._feed_room.notify_all()
             if item is None:
                 return
             encoder = self._encoder
@@ -598,12 +701,14 @@ class Recorder:
         return out.reshape(1, -1)
 
     def _drain_feed_queue(self) -> None:
-        """Discard every queued feed item."""
+        """Discard every queued feed item, releasing anyone waiting for room."""
         while True:
             try:
                 self._feed_queue.get_nowait()
             except queue.Empty:
-                return
+                break
+        with self._feed_room:
+            self._feed_room.notify_all()
 
     # -- clip / recording requests --------------------------------------------
 

{reactor_runtime-3.2.1 → reactor_runtime-3.2.3}/src/reactor_runtime/runner/runner.py

@@ -888,17 +888,27 @@ class Runner(ServiceComponent, ConnectionSink):
     def _emit_media(self, chunk: MediaChunk) -> None:
         """Fan one emitted media chunk out to the recorder and the connections.
 
-        Called off the model loop (emit dispatches to a worker thread). The
-        recorder is fed first and always queues without blocking, so a
-        backpressure wait in a connection's pacer (``chunk.wait``) delays the
-        producer, never the recording. A chunk emitted with ``drop=True``
-        keeps every consumer non-blocking.
+        Called off the model loop (emit dispatches to a worker thread). Both
+        consumers bound their queue the same way — never below the emission
+        being handed over — so a whole chunk fits each of them and the fan-out
+        costs the producer nothing while they keep up. A consumer that falls
+        behind honours ``chunk.wait``, and a chunk emitted with ``drop=True``
+        leaves every consumer non-blocking.
+
+        The connections are served first so the archive is never in front of
+        the session. A pacer that makes the producer wait is throttling it to
+        the playout rate it asked for, and drains on its own thread meanwhile;
+        the recorder's wait is bounded instead, because an encoder can stall
+        outright. Feeding the recorder second keeps that bounded stall off the
+        live path, and leaves its queue the whole broadcast to drain into.
         """
         for track in chunk.bundle.tracks:
             self._model_metrics.emitted(track, chunk.n_frames)
-        self._recorder.on_chunk(chunk)
         generation = self._media_generation
         self._connections.broadcast_media(chunk, abort=lambda: self._media_generation != generation)
+        # The archive takes the whole chunk even when a flush cut the broadcast
+        # short: a playout cut is not an archive boundary.
+        self._recorder.on_chunk(chunk)
 
     def _flush_media(self) -> None:
         """Drop queued media in every connection and cut playout to black.

{reactor_runtime-3.2.1 → reactor_runtime-3.2.3}/src/reactor_runtime/transport/webrtc/peer.py

@@ -583,8 +583,8 @@ class WebRTCPeer:
 
         The fourth argument is the trailer the sender attached, when it was there
         to read and the receiver transform is in place to strip it. It carries the
-        sender's own bytes and, beside them, the microsecond the sender stamped
-        the frame at, which reaches the model as that frame's capture time.
+        sender's own bytes and, beside them, the capture time the sender declared
+        for the frame, which reaches the model as that frame's capture time.
         """
 
         def sink(
@@ -593,10 +593,9 @@ class WebRTCPeer:
             if self._stop_event.is_set():
                 return
             metadata = bytes(meta.user_data) if meta is not None else b""
-            # The trailer leaves the stamp zero when the sender set none. Zero is
-            # not a clock reading, so it is the absence of a stamp rather than a
-            # frame captured at the epoch.
-            capture_us = meta.timestamp if meta is not None else 0
+            # Zero is the trailer's "unset", and it is not a clock reading: a frame
+            # captured at the epoch is not what a sender means by it.
+            capture_us = meta.capture_time_us if meta is not None else 0
             frame = InputFrame(
                 data=bgra_to_rgb(bgra, width, height),
                 # An empty trailer is a frame the sender attached nothing to.