reactor-runtime 2.7.5__tar.gz → 2.7.7__tar.gz

{reactor_runtime-2.7.5 → reactor_runtime-2.7.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reactor_runtime
-Version: 2.7.5
+Version: 2.7.7
 Summary: Reactor runtime with public model API
 Author-email: Reactor <team@reactor.inc>
 Requires-Python: >=3.9

{reactor_runtime-2.7.5 → reactor_runtime-2.7.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "reactor_runtime"
-version = "2.7.5"
+version = "2.7.7"
 description = "Reactor runtime with public model API"
 authors = [
 	{ name = "Reactor", email = "team@reactor.inc" }

{reactor_runtime-2.7.5 → reactor_runtime-2.7.7}/src/reactor_runtime/interface/internal/output_buffer.py

@@ -102,6 +102,18 @@ def split_batch(bundle: MediaBundle) -> List[MediaBundle]:
     return result
 
 
+class _FlushMarker:
+    """Sentinel placed in :class:`OutputBuffer`'s queue by :meth:`flush`.
+
+    Consumed by the emission thread, which resets ``_last_emitted`` and
+    dispatches a fresh black bundle with ``is_fresh_black=True``.  Doing
+    the reset in-thread keeps it atomic with the per-tick state read.
+    """
+
+
+_FLUSH_MARKER: _FlushMarker = _FlushMarker()
+
+
 class OutputBuffer:
     """Rate-controlled emission buffer.
 
@@ -124,10 +136,12 @@ class OutputBuffer:
         # Ordered list of per-tick observers.  Callbacks fire in
         # registration order on every emission tick; an exception in
         # one callback is logged and does not block the others.
-        self._callbacks: List[Callable[[MediaBundle, bool], None]] = []
+        self._callbacks: List[Callable[[MediaBundle, bool, bool], None]] = []
         self._callbacks_lock: threading.Lock = threading.Lock()
 
-        self._q: queue.Queue[MediaBundle] = queue.Queue(maxsize=queue_depth)
+        # Holds MediaBundle plus the _FlushMarker sentinel; the
+        # emission loop discriminates by isinstance.
+        self._q: queue.Queue[object] = queue.Queue(maxsize=queue_depth)
 
         # FPS control — store both rate and period to avoid 1/fps on every tick
         self._fixed_fps: float = 0.0
@@ -150,29 +164,18 @@ class OutputBuffer:
     # Callbacks
     # ------------------------------------------------------------------
 
-    def add_callback(self, fn: Callable[[MediaBundle, bool], None]) -> None:
-        """Register a per-tick callback.
+    def add_callback(self, fn: Callable[[MediaBundle, bool, bool], None]) -> None:
+        """Register a per-tick callback ``(bundle, duplicate, is_fresh_black)``.
 
-        Idempotent: registering the same ``fn`` twice leaves the
-        callback list with a single entry. This mirrors
-        :meth:`remove_callback` which has always been a no-op on
-        already-unregistered functions — callers shouldn't have to
-        track registration state.
-
-        The callback receives ``(bundle, duplicate)`` on every emission
-        tick.  Callbacks fire in registration order and are isolated
-        from each other: an exception raised by one is logged and the
-        remaining callbacks still fire.
+        Idempotent — re-registering the same ``fn`` is a no-op.
+        Callbacks fire in registration order with exceptions isolated.
         """
         with self._callbacks_lock:
             if fn not in self._callbacks:
                 self._callbacks.append(fn)
 
-    def remove_callback(self, fn: Callable[[MediaBundle, bool], None]) -> None:
-        """Deregister a previously added callback.
-
-        No-op if *fn* was never registered.
-        """
+    def remove_callback(self, fn: Callable[[MediaBundle, bool, bool], None]) -> None:
+        """Deregister a previously added callback (no-op if not registered)."""
         with self._callbacks_lock:
             try:
                 self._callbacks.remove(fn)
@@ -288,27 +291,30 @@ class OutputBuffer:
     # Stage 3: Emission loop
     # ------------------------------------------------------------------
 
-    def _dispatch(self, bundle: MediaBundle, duplicate: bool) -> None:
+    def _dispatch(
+        self,
+        bundle: MediaBundle,
+        duplicate: bool,
+        *,
+        is_fresh_black: bool = False,
+    ) -> None:
         """Fire every registered callback in order with error isolation.
 
-        We snapshot the callback list under the lock so callbacks that
-        register/deregister siblings during dispatch don't perturb the
-        current tick.  Each callback is wrapped so an exception in one
-        does not block the others.
+        Callbacks receive ``(bundle, duplicate, is_fresh_black)``.
+        ``is_fresh_black`` is ``True`` only on the synthesised black
+        the sentinel path emits at session boundaries; callbacks
+        choose how to interpret that separately from ``duplicate``.
+        Exceptions in one callback are logged and don't block the
+        rest.
         """
         with self._callbacks_lock:
             callbacks = list(self._callbacks)
         for fn in callbacks:
             try:
-                fn(bundle, duplicate)
+                fn(bundle, duplicate, is_fresh_black)
             except Exception as ex:
-                # ``logger.exception`` already attaches sys.exc_info()'s
-                # traceback; we also surface the type + message as
-                # structured fields so log queries on ``exc_type`` /
-                # ``exc_msg`` / ``callback`` work without traceback
-                # parsing. Without these explicit fields a silent
-                # malfunction in a downstream callback looks like
-                # "feature X didn't fire" with no obvious cause.
+                # Structured fields so log queries on exc_type /
+                # exc_msg / callback work without traceback parsing.
                 logger.exception(
                     "OutputBuffer callback raised; continuing with remaining callbacks",
                     callback=repr(fn),
@@ -322,13 +328,31 @@ class OutputBuffer:
             while not self._emission_stop.is_set():
                 interval = self._interval
 
-                bundle: Optional[MediaBundle] = None
+                item: object
                 try:
-                    bundle = self._q.get_nowait()
+                    item = self._q.get_nowait()
                 except queue.Empty:
-                    pass
+                    item = None
 
-                if bundle is not None:
+                bundle: Optional[MediaBundle] = None
+                sentinel_consumed = False
+                if isinstance(item, _FlushMarker):
+                    self._last_emitted = None
+                    sentinel_consumed = True
+                elif isinstance(item, MediaBundle):
+                    bundle = item
+
+                if sentinel_consumed:
+                    # Session-boundary black: tagged so the wire
+                    # forwards it (otherwise the client would stay
+                    # frozen on the previous frame), the recorder
+                    # ignores it.
+                    self._dispatch(
+                        self._create_black_bundle(),
+                        True,
+                        is_fresh_black=True,
+                    )
+                elif bundle is not None:
                     vtracks = bundle.get_tracks_by_kind(TrackKind.VIDEO)
                     if vtracks:
                         vd = vtracks[0].data
@@ -464,11 +488,19 @@ class OutputBuffer:
         self._drain_queue()
 
     def flush(self) -> None:
-        """Empty the queue and insert a black frame."""
+        """Drop pending bundles and request a session-boundary reset.
+
+        The emission thread performs the actual reset of
+        ``_last_emitted`` when it dequeues the sentinel.  Then the
+        next tick emits a fresh black bundle tagged ``is_fresh_black``
+        — forwarded by the wire, ignored by the recorder.
+        """
         self._drain_queue()
-        self._last_emitted = None
-        black = self._create_black_bundle()
         try:
-            self._q.put_nowait(black)
+            self._q.put_nowait(_FLUSH_MARKER)
         except queue.Full:
-            pass
+            # Same thread as submit(), so unreachable in practice.
+            logger.warning(
+                "OutputBuffer.flush: queue full immediately after drain; "
+                "reset sentinel dropped"
+            )

{reactor_runtime-2.7.5 → reactor_runtime-2.7.7}/src/reactor_runtime/recording/chunk_encoder.py

@@ -61,6 +61,31 @@ def _build_argv(
     is fed at exactly ``sample_rate * dt`` samples per video frame
     (see ``SessionRecorder._next_audio_chunk``) so its byte-derived
     DTS still tracks wall-clock 1:1 with video's PTS.
+
+    Social-media compatibility (REA-2482):
+
+    * ``-pix_fmt yuv420p`` + ``-profile:v main`` on the *output*.  With
+      rgb24 input and no output pix_fmt, libx264 auto-selects yuv444p
+      (Hi444PP profile), which macOS VideoToolbox cannot decode and
+      every major social uploader rejects.  Forcing yuv420p+Main is
+      the universally-compatible H.264 sub-profile.
+    * ``-vf setpts=PTS-STARTPTS`` re-anchors the wallclock-stamped
+      video PTS to session-relative.  Without it every segment's
+      ``tfdt baseMediaDecodeTime`` carries the Unix-epoch-derived
+      value (~1.78e9), which some players treat as the playback
+      start time and some uploaders refuse outright.  Subtracting
+      ``STARTPTS`` preserves *relative* frame spacing (so the
+      dynamic-FPS comment above still holds) while shifting chunk 0
+      to PTS=0.  Note: mid-session clips still carry a non-zero
+      ``tfdt`` (e.g. 32 s in for a clip starting at session t=32) —
+      that's the SDK's concern (REA-2558), not ours.
+    * Silent AAC stub for video-only models: ``-f lavfi -i anullsrc``
+      synthesises an infinite silent mono 48 kHz stream inside
+      libavfilter — no extra subprocess, no Python audio thread, no
+      pipe.  Paired with ``-shortest`` so the encoder terminates on
+      the video pipe's EOF.  Required by Instagram and broadens
+      compatibility on every other platform; encoding silence costs
+      <1% of a core and ~16 kbps × duration on disk.
     """
     # ``-probesize 32 -analyzeduration 0`` on every input: rawvideo /
     # s16le are fully described by ``-f`` + format flags, so ffmpeg's
@@ -117,16 +142,61 @@ def _build_argv(
             "1024",
             "-i",
             f"pipe:{audio_read_fd}",
-            "-map",
-            "0:v",
-            "-map",
-            "1:a",
         ]
+    else:
+        # Synthetic silent audio (REA-2482).  ``lavfi anullsrc`` is a
+        # virtual generator inside libavfilter — no extra subprocess
+        # spawned, no audio pipe opened on our side.
+        #
+        # ``-re`` paces the lavfi input at native rate (one
+        # wallclock-second of silence per real second).  Without it,
+        # lavfi is an unpaced infinite generator: the input thread
+        # produces silent samples as fast as ffmpeg's filter graph
+        # asks, racing ahead of the wallclock-stamped video on idle
+        # sessions and risking thread-queue exhaustion / stalled
+        # teardown.  With ``-re``, the silent stream tracks wallclock
+        # the same way the real pipe-fed audio path does (which
+        # writes exactly ``sample_rate * dt`` samples per video frame
+        # in ``SessionRecorder._feed_loop``).
+        #
+        # We pair this with ``-shortest`` below so the encoder
+        # terminates with the video pipe's EOF (anullsrc is infinite
+        # by itself).
+        argv += [
+            "-re",
+            "-f",
+            "lavfi",
+            "-i",
+            "anullsrc=cl=mono:r=48000",
+        ]
+    # Explicit stream mappings: now that there is always a second
+    # input (either the real audio pipe or the lavfi silent stub),
+    # both branches funnel through the same -map pair.
+    argv += [
+        "-map",
+        "0:v",
+        "-map",
+        "1:a",
+    ]
     # video encoder
     vcodec = "libx264" if config.video.codec == "h264" else "libx265"
     argv += [
         "-c:v",
         vcodec,
+        # Social-media-compat output format (see docstring).  The first
+        # -pix_fmt earlier in argv is the *input* (rgb24); this second
+        # -pix_fmt applies to the encoder output because it sits after
+        # all -i flags.
+        "-pix_fmt",
+        "yuv420p",
+        "-profile:v",
+        "main",
+        # Re-anchor wallclock-stamped PTS to session-relative; see
+        # docstring.  Single arithmetic op per frame inside the
+        # existing filter graph — no extra encode, no decode (input
+        # is rawvideo).
+        "-vf",
+        "setpts=PTS-STARTPTS",
         "-preset",
         config.video.preset,
         "-crf",
@@ -141,13 +211,20 @@ def _build_argv(
         "-force_key_frames",
         f"expr:gte(t,n_forced*{config.chunk_seconds})",
     ]
-    if has_audio:
-        argv += [
-            "-c:a",
-            config.audio.codec,
-            "-b:a",
-            f"{config.audio.bitrate_kbps}k",
-        ]
+    # Audio encoder runs unconditionally now: real audio (when
+    # has_audio=True) or the lavfi silent stub (when False) — either
+    # way we want an AAC track in every output segment.
+    argv += [
+        "-c:a",
+        config.audio.codec,
+        "-b:a",
+        f"{config.audio.bitrate_kbps}k",
+    ]
+    if not has_audio:
+        # ``lavfi anullsrc`` produces samples forever; without
+        # -shortest the encoder would keep writing silent audio
+        # frames after the video pipe EOFs, never terminating.
+        argv += ["-shortest"]
     # HLS+fMP4 muxer (was ``-f dash``: dash's segment-rename trips
     # ENOENT on macOS, killing the encoder ~10s in).  Same byte-level
     # output, more robust segment-close, 0-indexed by default — which

{reactor_runtime-2.7.5 → reactor_runtime-2.7.7}/src/reactor_runtime/recording/config.py

@@ -96,6 +96,24 @@ class RecordingConfig:
     # that frame.  Clip requests before any real frame fail with
     # ``no media generated yet``.  Set to ``False`` to record from
     # session arm time and include the leading pre-roll in clips.
+    #
+    # **Timeline note (REA-2482).** The encoder applies
+    # ``setpts=PTS-STARTPTS`` on the video output to keep segment PTS
+    # session-relative rather than Unix-epoch-relative.  That filter
+    # zeroes media time at the *first packet fed* to ffmpeg.  In the
+    # default ``skip_leading_black=True`` mode, that is also where
+    # :class:`~reactor_runtime.recording.markers.MarkerBookkeeper`
+    # anchors its timeline (via ``mark_first_real_frame``), so markers
+    # and media bytes share the same origin and clip ranges resolve
+    # exactly.  In the legacy ``skip_leading_black=False`` mode the
+    # marker bookkeeper keeps its origin at recorder arm time
+    # (``session_start``), so the two timelines diverge by however
+    # long the recorder waited for the first emission tick — usually
+    # one frame interval (<33 ms) but worst-case longer if the
+    # OutputBuffer hasn't started emitting yet at recorder arm.  Clips
+    # served from that early window cover slightly *later* content
+    # than their marker range advertises; the clip length itself is
+    # unchanged.
     skip_leading_black: bool = True
     video_track: Optional[str] = None
     audio_track: Optional[str] = None

{reactor_runtime-2.7.5 → reactor_runtime-2.7.7}/src/reactor_runtime/recording/markers.py

@@ -5,6 +5,16 @@ Markers are wall-clock seconds aligned with ffmpeg's
 ``-use_wallclock_as_timestamps`` input.  When ``anchor_at_first_frame``
 is set (``RecordingConfig.skip_leading_black``), ``t=0`` is the first
 real frame fed to the encoder, not recorder arm time.
+
+The encoder additionally applies ``setpts=PTS-STARTPTS`` on the video
+output (REA-2482), which zeroes media PTS at the *first packet fed* to
+ffmpeg.  With ``anchor_at_first_frame=True`` that's the same instant
+the bookkeeper anchors on, so markers and media share an origin.  With
+``anchor_at_first_frame=False`` the bookkeeper's origin stays at
+recorder arm time while the media origin slips to the first emission
+tick; the gap is typically a single frame interval but can be longer
+if the OutputBuffer hadn't started emitting yet at arm time.  See
+``RecordingConfig.skip_leading_black`` for the user-facing contract.
 """
 
 from __future__ import annotations

{reactor_runtime-2.7.5 → reactor_runtime-2.7.7}/src/reactor_runtime/recording/session_recorder.py

@@ -250,10 +250,22 @@ class SessionRecorder:
     # OutputBuffer integration
     # ------------------------------------------------------------------
 
-    def _on_bundle_sync(self, bundle: MediaBundle, duplicate: bool) -> None:
-        """Enqueue a bundle for the feed worker; non-blocking."""
+    def _on_bundle_sync(
+        self,
+        bundle: MediaBundle,
+        duplicate: bool,
+        is_fresh_black: bool = False,
+    ) -> None:
+        """Enqueue a bundle for the feed worker; non-blocking.
+
+        Session-boundary synthesised black (``is_fresh_black``) is not
+        real model output and is invisible to the recording timeline:
+        no feed-queue write, no ``mark_first_real_frame`` consideration.
+        """
         if self._disabled or not self._started:
             return
+        if is_fresh_black:
+            return
         now = time.monotonic()
         if duplicate:
             if self._config.skip_leading_black and not self._markers.recording_started:

{reactor_runtime-2.7.5 → reactor_runtime-2.7.7}/src/reactor_runtime/runtime_api.py

@@ -350,22 +350,19 @@ class Runtime(ModelStateMachine, ABC):
             logger.warning("Failed to send app message", error=e)
 
     def _send_out_app_bundle_sync(
-        self, media_bundle: MediaBundle, duplicate: bool
+        self,
+        media_bundle: MediaBundle,
+        duplicate: bool,
+        is_fresh_black: bool = False,
     ) -> None:
-        """Callback from the :class:`FrameBuffer` emission loop.
-
-        Silently fails if the event loop is closed (expected during shutdown).
-
-        When *duplicate* is ``True`` the bundle is a re-emission of the
-        last frame (queue was empty, video-only).  We skip forwarding
-        entirely: the video track already serves the last pushed frame,
-        and pushing the same frame again only wastes event-loop time.
+        """OutputBuffer callback — forward real frames + session-boundary black.
 
-        Args:
-            media_bundle: The :class:`MediaBundle` to send.
-            duplicate: True if this is a re-emission of the last frame.
+        Drops keepalive duplicates (the wire track already shows that
+        frame) but forwards ``is_fresh_black`` bundles so the client
+        transitions off the previous session's last frame on flush.
+        Silently fails if the event loop is closed (shutdown).
         """
-        if duplicate:
+        if duplicate and not is_fresh_black:
             return
         if self.loop.is_closed():
             return

{reactor_runtime-2.7.5 → reactor_runtime-2.7.7}/src/reactor_runtime/runtimes/headless/headless_runtime.py

@@ -70,19 +70,26 @@ class HeadlessRuntime(Runtime):
     # Runtime API implementation - MODEL -> CLIENT (stdout)
     # ===============================
 
-    def _send_out_app_bundle_sync(self, media_bundle, duplicate: bool) -> None:
-        """Override base-class sync wrapper to forward duplicates.
-
-        The base :class:`Runtime` drops duplicates because re-sending
-        the same frame over WebRTC is wasteful.  The headless runtime
-        needs to see them so that ``send_out_app_bundle`` can count
-        skipped duplicates for the ``ignore_duplicates`` feature.
+    def _send_out_app_bundle_sync(
+        self,
+        media_bundle,
+        duplicate: bool,
+        is_fresh_black: bool = False,
+    ) -> None:
+        """Forward every bundle to :meth:`send_out_app_bundle`.
+
+        Unlike the base class, headless does not drop duplicates here
+        — the async path counts them for the ``ignore_duplicates``
+        feature.  Silently fails if the event loop is closed.
         """
         if self.loop.is_closed():
             return
         try:
             asyncio.run_coroutine_threadsafe(
-                self.send_out_app_bundle(media_bundle, duplicate), self.loop
+                self.send_out_app_bundle(
+                    media_bundle, duplicate, is_fresh_black=is_fresh_black
+                ),
+                self.loop,
             )
         except RuntimeError:
             pass
@@ -105,19 +112,30 @@ class HeadlessRuntime(Runtime):
         output = json.dumps(data, indent=2)
         print(f"\n[RUNTIME] {output}", flush=True)
 
-    async def send_out_app_bundle(self, media_bundle, duplicate: bool) -> None:
-        """
-        Handle an output media bundle from the model.
-        Extracts the video frame and writes it as a PNG file.
-
-        Args:
-            media_bundle: A :class:`MediaBundle` (video track extracted).
-            duplicate: True if this is a re-emission of the last frame.
+    async def send_out_app_bundle(
+        self,
+        media_bundle,
+        duplicate: bool,
+        *,
+        is_fresh_black: bool = False,
+    ) -> None:
+        """Extract the video frame from ``media_bundle`` and write as PNG.
+
+        Skips ``is_fresh_black`` bundles (synthesised session-boundary
+        black, not model output) and — when ``ignore_duplicates`` is
+        set — ``duplicate`` keepalives.
         """
         if self.file_path is None:
             return
 
-        # Skip duplicate frames (re-emissions from the frame buffer when it's empty)
+        if is_fresh_black:
+            self._duplicates_skipped += 1
+            logger.debug(
+                "Skipped fresh-black session-boundary frame",
+                total_skipped=self._duplicates_skipped,
+            )
+            return
+
         if self.config.ignore_duplicates and duplicate:
             self._duplicates_skipped += 1
             logger.debug(

{reactor_runtime-2.7.5 → reactor_runtime-2.7.7}/src/reactor_runtime.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reactor_runtime
-Version: 2.7.5
+Version: 2.7.7
 Summary: Reactor runtime with public model API
 Author-email: Reactor <team@reactor.inc>
 Requires-Python: >=3.9