reactor-runtime 2.3.2__tar.gz → 2.4.0__tar.gz

{reactor_runtime-2.3.2 → reactor_runtime-2.4.0}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: reactor_runtime
-Version: 2.3.2
+Version: 2.4.0
 Summary: Reactor runtime with public model API
 Author-email: Reactor <team@reactor.inc>
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
-Requires-Dist: numpy<2.0
+Requires-Dist: numpy>=1.24.0
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: omegaconf>=2.3.0
 Requires-Dist: av>=14.0.0

{reactor_runtime-2.3.2 → reactor_runtime-2.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "reactor_runtime"
-version = "2.3.2"
+version = "2.4.0"
 description = "Reactor runtime with public model API"
 authors = [
 	{ name = "Reactor", email = "team@reactor.inc" }
@@ -13,7 +13,7 @@ readme = "README.md"
 requires-python = ">=3.9"
 
 dependencies = [
-	"numpy<2.0",
+	"numpy>=1.24.0",
 	"pydantic>=2.0.0",
 	"omegaconf>=2.3.0",
     "av>=14.0.0",

{reactor_runtime-2.3.2 → reactor_runtime-2.4.0}/src/reactor_runtime/__init__.py

@@ -14,6 +14,7 @@ from reactor_runtime.interface import (
     MESSAGE_REGISTRY,
     FieldInfo,
     InputField,
+    InputFrame,
     Output,
     Input,
     Video,
@@ -45,6 +46,7 @@ __all__ = [
     "MESSAGE_REGISTRY",
     "FieldInfo",
     "InputField",
+    "InputFrame",
     "Output",
     "Input",
     "Video",

{reactor_runtime-2.3.2 → reactor_runtime-2.4.0}/src/reactor_runtime/interface/__init__.py

@@ -54,6 +54,10 @@ from reactor_runtime.interface.internal.input_buffer import (
     ReadMode,
 )
 
+# Inbound frame with timing metadata (re-exported from transports so model
+# authors can ``from reactor_runtime.interface import InputFrame``).
+from reactor_runtime.transports.media import InputFrame
+
 __all__ = [
     # Tracks
     "Output",
@@ -95,4 +99,6 @@ __all__ = [
     "InputBuffer",
     "BufferClosed",
     "ReadMode",
+    # Inbound frame
+    "InputFrame",
 ]

{reactor_runtime-2.3.2 → reactor_runtime-2.4.0}/src/reactor_runtime/interface/driver/pipeline_executor.py

@@ -6,7 +6,9 @@ from __future__ import annotations
 import asyncio
 import dataclasses
 import inspect
-from typing import Any, Dict, Iterator, List, Optional, Type
+from typing import Any, Dict, Iterator, List, Optional, Type, Union
+
+import numpy as np
 
 from reactor_runtime.interface.driver.step_result import StepResult
 from reactor_runtime.interface.events.messages import ModelMessage
@@ -17,6 +19,7 @@ from reactor_runtime.interface.pipeline.reactor_pipeline import (
     GeneratorEnded,
     ReactorPipeline,
 )
+from reactor_runtime.transports.media import InputFrame
 
 
 class PipelineExecutor(Iterator[StepResult]):
@@ -166,14 +169,29 @@ class PipelineExecutor(Iterator[StepResult]):
         }
         return self._run(self._send_event(entry, **handler_kwargs))
 
-    def push_media(self, track_name: str, data: Any) -> None:
+    def push_media(self, track_name: str, data: Union[np.ndarray, InputFrame]) -> None:
         """Push a media frame into an input buffer.
 
-        The frame becomes available to the model on the next
-        iteration when ``inference()`` calls ``try_read()`` or
-        ``read()``.
+        Accepts either a raw ``np.ndarray`` (auto-wrapped into an
+        :class:`~reactor_runtime.transports.media.InputFrame` with
+        ``pts=None``) or a prebuilt :class:`InputFrame` for callers
+        that want to stamp the frame with an explicit presentation
+        timestamp.
+
+        The frame becomes available to the model on the next iteration
+        when ``inference()`` calls ``try_read()`` / ``read()`` — both
+        of which now return ``List[InputFrame]``.
         """
-        self._model._push_media(track_name, data)
+        if isinstance(data, InputFrame):
+            frame = data
+        elif isinstance(data, np.ndarray):
+            frame = InputFrame(data=data)
+        else:
+            raise TypeError(
+                "push_media expects an np.ndarray or InputFrame, got "
+                f"{type(data).__name__}"
+            )
+        self._model._push_media(track_name, frame)
 
     def disconnect(self) -> List[ModelMessage]:
         """End the current session.

{reactor_runtime-2.3.2 → reactor_runtime-2.4.0}/src/reactor_runtime/interface/internal/input_buffer.py

@@ -26,7 +26,7 @@ from collections import deque
 from enum import Enum, auto
 from typing import List, Optional
 
-import numpy as np
+from reactor_runtime.transports.media import InputFrame
 
 
 class ReadMode(Enum):
@@ -64,12 +64,16 @@ class InputBuffer:
     Accessed via :class:`Input` track handles — model authors never
     instantiate this class directly.
 
-    Read API:
+    Read API (returns :class:`~reactor_runtime.transports.media.InputFrame`):
 
     - :meth:`read` — async, blocks until *n* frames are available.
     - :meth:`try_read` — sync, returns immediately (latest frame or
       ``None``).
 
+    Both return ``List[InputFrame]``.  Callers unwrap the ``.data``
+    ``np.ndarray`` for numpy operations and ``.pts`` when they need
+    the presentation timestamp for cross-track alignment.
+
     Lifecycle:
 
     - :meth:`close` — signal end-of-input (raises :class:`BufferClosed`
@@ -93,7 +97,7 @@ class InputBuffer:
         self._lock = threading.Lock()
         self._condition = threading.Condition(self._lock)
 
-        self._buffer: deque[np.ndarray] = deque(maxlen=maxlen)
+        self._buffer: deque[InputFrame] = deque(maxlen=maxlen)
         self._total_received: int = 0
         self._closed: bool = False
 
@@ -106,8 +110,8 @@ class InputBuffer:
         n: int = 1,
         timeout: Optional[float] = None,
         mode: ReadMode = ReadMode.LATEST,
-    ) -> List[np.ndarray]:
-        """Return *n* frames, waiting if necessary.
+    ) -> List[InputFrame]:
+        """Return *n* :class:`InputFrame` objects, waiting if necessary.
 
         Blocks the calling coroutine (via ``asyncio.to_thread``) until
         at least *n* frames are present in the buffer, then returns
@@ -118,7 +122,8 @@ class InputBuffer:
         Typical usage::
 
             frames = await self.input.camera.read(4)               # newest 4
-            frames = await self.input.camera.read(4, mode=ReadMode.FIFO)  # oldest 4
+            latest = frames[-1].data                               # np.ndarray
+            pts    = frames[-1].pts                                # seconds or None
 
         Args:
             n: Number of frames to return.
@@ -130,7 +135,11 @@ class InputBuffer:
                 leaving newer frames in the buffer.
 
         Returns:
-            A list of *n* ``np.ndarray`` frames (HWC, uint8).
+            A list of *n* :class:`InputFrame` objects.  Each carries
+            ``data`` (the numpy payload — HWC uint8 RGB for video,
+            ``(1, M)`` int16 for audio) and ``pts`` (presentation
+            timestamp in seconds, or ``None`` when the transport did
+            not provide one).
 
         Raises:
             BufferClosed: The client disconnected while waiting.
@@ -144,7 +153,7 @@ class InputBuffer:
         n: int,
         timeout: Optional[float],
         mode: ReadMode = ReadMode.LATEST,
-    ) -> List[np.ndarray]:
+    ) -> List[InputFrame]:
         if self._buffer.maxlen is not None and n > self._buffer.maxlen:
             raise ValueError(
                 f"Requested {n} frames but buffer capacity is {self._buffer.maxlen}. "
@@ -165,24 +174,27 @@ class InputBuffer:
                 return self._read_latest(n)
             return self._read_fifo(n)
 
-    def _read_latest(self, n: int) -> List[np.ndarray]:
-        """Return the *n* newest frames and discard the rest.  Caller holds the lock."""
+    def _read_latest(self, n: int) -> List[InputFrame]:
+        """Return the *n* newest :class:`InputFrame` objects and discard the rest.
+
+        Caller holds the lock.
+        """
         buf_len = len(self._buffer)
         start = buf_len - n
         result = [self._buffer[start + i] for i in range(n)]
         self._buffer.clear()
         return result
 
-    def _read_fifo(self, n: int) -> List[np.ndarray]:
-        """Pop the *n* oldest frames.  Caller holds the lock."""
+    def _read_fifo(self, n: int) -> List[InputFrame]:
+        """Pop the *n* oldest :class:`InputFrame` objects.  Caller holds the lock."""
         return [self._buffer.popleft() for _ in range(n)]
 
     def try_read(
         self,
         n: int = 1,
         mode: ReadMode = ReadMode.LATEST,
-    ) -> Optional[List[np.ndarray]]:
-        """Try to read *n* frames without blocking.
+    ) -> Optional[List[InputFrame]]:
+        """Try to read *n* :class:`InputFrame` objects without blocking.
 
         Returns ``None`` when fewer than *n* frames are available —
         the buffer is left untouched so nothing is lost.
@@ -195,7 +207,7 @@ class InputBuffer:
                 leaving newer frames in the buffer.
 
         Returns:
-            A list of *n* ``np.ndarray`` frames, or ``None`` if
+            A list of *n* :class:`InputFrame` objects, or ``None`` if
             fewer than *n* are available.
 
         Raises:
@@ -274,14 +286,15 @@ class InputBuffer:
     #
     # Call chain:
     #   WebRTC transport (on_track / on_frame callback)
-    #     → ReactorCore._push_media(track_name, data)
-    #       → InputBuffer._push(data)
+    #     → VideoFrameEvent(frame=InputFrame(data, pts), track_name=...)
+    #       → ReactorCore._push_media(track_name, frame)
+    #         → InputBuffer._push(frame)
     #
     # Thread-safe: the model thread may be blocked in read()
     # concurrently — notify_all wakes it.
 
-    def _push(self, data: np.ndarray) -> None:
-        """Append a media frame (called by the runtime, not model code).
+    def _push(self, frame: InputFrame) -> None:
+        """Append an :class:`InputFrame` (called by the runtime, not model code).
 
         Silently drops the frame if the buffer has been closed.
         When full, the oldest frame is evicted (bounded deque).
@@ -289,7 +302,7 @@ class InputBuffer:
         with self._condition:
             if self._closed:
                 return
-            self._buffer.append(data)
+            self._buffer.append(frame)
             self._total_received += 1
             # Wake _read() if it's sleeping in wait_for() — it will
             # re-acquire the lock and re-check len(buffer) >= n.

{reactor_runtime-2.3.2 → reactor_runtime-2.4.0}/src/reactor_runtime/interface/internal/reactor_core.py

@@ -28,6 +28,7 @@ from reactor_runtime.interface.internal.input_buffer import InputBuffer
 from reactor_runtime.interface.tracks.descriptors import TRACK_MARKERS
 from reactor_runtime.interface.tracks.input import INPUT_REGISTRY, Input
 from reactor_runtime.interface.tracks.output import Output
+from reactor_runtime.transports.media import InputFrame
 from reactor_runtime.utils.log import get_logger
 
 logger = get_logger(__name__)
@@ -198,13 +199,20 @@ class ReactorCore:
         except RuntimeError:
             pass
 
-    def _push_media(self, track_name: str, data: Any) -> None:
-        """Thread-safe: push media into the corresponding InputBuffer."""
+    def _push_media(self, track_name: str, frame: InputFrame) -> None:
+        """Thread-safe: push an :class:`InputFrame` into the matching InputBuffer.
+
+        Strict typing: callers must build an :class:`InputFrame` (transports
+        do so at the ingress boundary).  Permissive auto-wrapping of a bare
+        ``np.ndarray`` happens at the outer public surface
+        (``PipelineExecutor.push_media``) — not here — so this stays a
+        simple threadsafe dispatch.
+        """
         if self._loop.is_closed():
             return
         buf = self._input_buffers.get(track_name)
         if buf is not None:
-            buf._push(data)
+            buf._push(frame)
         else:
             logger.debug(
                 "Received media for unknown input track",

{reactor_runtime-2.3.2 → reactor_runtime-2.4.0}/src/reactor_runtime/runtimes/headless/input_feeder.py

@@ -17,7 +17,7 @@ from typing import Optional
 import cv2
 
 from reactor_runtime.interface.internal.reactor_core import ReactorCore
-from reactor_runtime.transports.media import MediaBundle
+from reactor_runtime.transports.media import InputFrame, MediaBundle
 from reactor_runtime.utils.log import get_logger
 
 logger = get_logger(__name__)
@@ -222,9 +222,18 @@ class InputFrameFeeder:
                     continue
 
                 frame_rgb = cv2.cvtColor(frame_bgr, cv2.COLOR_BGR2RGB)
+                # Synthesise a presentation timestamp from the frame index
+                # when running at a fixed input fps, so downstream model
+                # code reading via ``read()`` / ``try_read()`` sees
+                # monotonically increasing ``pts``.  Without an fps target
+                # we leave ``pts`` unset (``None``).
+                pts = (i / self._input_fps) if self._input_fps else None
                 bundle = MediaBundle.from_video_frame(frame_rgb)
                 for track_name, track_data in bundle.tracks.items():
-                    self._model._push_media(track_name, track_data.data)
+                    self._model._push_media(
+                        track_name,
+                        InputFrame(data=track_data.data, pts=pts),
+                    )
                 fed += 1
                 self.frames_fed = fed
 

{reactor_runtime-2.3.2 → reactor_runtime-2.4.0}/src/reactor_runtime/runtimes/http/http_runtime.py

@@ -25,7 +25,7 @@ import asyncio
 import os
 import uuid
 from typing import Any, Dict, Optional
-import numpy as np
+
 from fastapi import FastAPI, HTTPException, Request
 from importlib.metadata import version as _pkg_version, PackageNotFoundError
 
@@ -38,6 +38,7 @@ import uvicorn
 
 from reactor_runtime.runtime_api import Runtime
 from reactor_runtime.transports.media import (
+    InputFrame,
     MediaBundle,
     TrackMapping,
 )
@@ -48,6 +49,7 @@ from reactor_runtime.transports import (
     EventType,
     MessageEvent,
     DisconnectedEvent,
+    AudioFrameEvent,
     VideoFrameEvent,
     PingTimeoutEvent,
 )
@@ -471,6 +473,9 @@ class HttpRuntime(Runtime):
         def on_video_frame(event: VideoFrameEvent):
             self._on_incoming_video_frame(event.frame, event.track_name)
 
+        def on_audio_frame(event: AudioFrameEvent):
+            self._on_incoming_audio_frame(event.frame, event.track_name)
+
         def on_ping_timeout(event: PingTimeoutEvent):
             if not self.loop.is_closed():
                 self.loop.call_soon_threadsafe(
@@ -480,6 +485,7 @@ class HttpRuntime(Runtime):
         client.on(EventType.MESSAGE, on_message)
         client.on(EventType.DISCONNECTED, on_disconnect)
         client.on(EventType.VIDEO_FRAME, on_video_frame)
+        client.on(EventType.AUDIO_FRAME, on_audio_frame)
         client.on(EventType.PING_TIMEOUT, on_ping_timeout)
 
     async def _stop_webrtc_client(self) -> None:
@@ -512,16 +518,25 @@ class HttpRuntime(Runtime):
             self._webrtc_client.notify_ping()
 
     def _on_incoming_video_frame(
-        self, frame: np.ndarray, track_name: str = "video"
+        self, frame: InputFrame, track_name: str = "video"
     ) -> None:
-        """Handle incoming video frame from WebRTC.
+        """Handle an incoming video :class:`InputFrame` from the WebRTC transport.
+
+        Routes the frame into the model's per-track :class:`InputBuffer`,
+        preserving ``pts`` so model code can read it via
+        ``(await self.input.<track>.read(n))[i].pts``.
+        """
+        if self.model is not None:
+            self.model._push_media(track_name, frame)
 
-        Pushes the raw frame directly into the model's InputBuffer
-        for the named track.
+    def _on_incoming_audio_frame(
+        self, frame: InputFrame, track_name: str = "audio"
+    ) -> None:
+        """Handle an incoming audio :class:`InputFrame` from the WebRTC transport.
 
-        Args:
-            frame: NumPy array in RGB format with shape (H, W, 3).
-            track_name: The MID-derived track name.
+        Routes the frame into the model's per-track :class:`InputBuffer`,
+        preserving ``pts`` so model code can align audio chunks with
+        video frames by timestamp.
         """
         if self.model is not None:
             self.model._push_media(track_name, frame)

{reactor_runtime-2.3.2 → reactor_runtime-2.4.0}/src/reactor_runtime/transports/__init__.py

@@ -23,6 +23,7 @@ Public API re-exported here for convenience::
         TrackInfo,
         TrackData,
         MediaBundle,
+        InputFrame,
         # Events
         EventType,
         WebRTCNoVideoError,
@@ -32,6 +33,7 @@ Public API re-exported here for convenience::
         DisconnectedEvent,
         MessageEvent,
         VideoFrameEvent,
+        AudioFrameEvent,
         MediaBundleEvent,
         PingTimeoutEvent,
         EventHandler,
@@ -47,6 +49,7 @@ from reactor_runtime.transports.events import (
     MessageEvent,
     PingTimeoutEvent,
     StatsMeasuredEvent,
+    AudioFrameEvent,
     VideoFrameEvent,
     WebRTCEvent,
     WebRTCNoVideoError,
@@ -55,6 +58,7 @@ from reactor_runtime.transports.events import (
 )
 from reactor_runtime.transports.interface import WebRTCTransport
 from reactor_runtime.transports.media import (
+    InputFrame,
     MediaBundle,
     TrackData,
     TrackDirection,
@@ -100,6 +104,7 @@ __all__ = [
     "TrackMapping",
     "TrackData",
     "MediaBundle",
+    "InputFrame",
     # Events
     "EventType",
     "WebRTCNoVideoError",
@@ -110,6 +115,7 @@ __all__ = [
     "DisconnectedEvent",
     "MessageEvent",
     "VideoFrameEvent",
+    "AudioFrameEvent",
     "MediaBundleEvent",
     "PingTimeoutEvent",
     "StatsMeasuredEvent",

{reactor_runtime-2.3.2 → reactor_runtime-2.4.0}/src/reactor_runtime/transports/aiortc/audio_track.py

@@ -36,7 +36,7 @@ from fractions import Fraction
 from typing import Optional
 
 import numpy as np
-from aiortc import MediaStreamTrack
+from aiortc import AudioStreamTrack
 from av import AudioFrame
 
 from reactor_runtime.utils.log import get_logger
@@ -70,8 +70,154 @@ _FADE_SAMPLES = 64
 # to cap latency.  1 second at 48 kHz = 48 000.
 MAX_BUFFER_SAMPLES = 48000
 
+# =============================================================================
+# NumPy <-> AudioFrame helpers
+# =============================================================================
+
+
+def _audio_plane_to_bytes(plane) -> bytes:
+    """Raw bytes for a PyAV ``AudioPlane``/``VideoPlane`` (``to_bytes()`` or buffer)."""
+    to_b = getattr(plane, "to_bytes", None)
+    if callable(to_b):
+        return to_b()
+    return bytes(plane)
+
+
+def _float_to_s16_samples(arr: np.ndarray) -> np.ndarray:
+    """FFmpeg/ libav ``fltp`` samples in approximately ``[-1.0, 1.0]`` → ``int16``."""
+    a = np.asarray(arr, dtype=np.float64)
+    a = np.clip(a, -1.0, 1.0)
+    return np.rint(a * 32767.0).astype(np.int16)
+
+
+def _frame_channel_count(frame: AudioFrame) -> int:
+    """Best-effort channel count from the frame (layout, else plane count)."""
+    layout = getattr(frame, "layout", None)
+    if layout is not None:
+        nb = getattr(layout, "nb_channels", None)
+        if isinstance(nb, int) and nb > 0:
+            return nb
+        chs = getattr(layout, "channels", None)
+        if chs is not None and len(chs) > 0:
+            return len(chs)
+    n_planes = len(frame.planes)
+    return max(1, n_planes) if n_planes else 1
+
+
+def _s16_to_mono_1d(arr: np.ndarray, frame: AudioFrame) -> np.ndarray:
+    """Collapse any supported layout to one **int16** vector (first channel only)."""
+    arr = np.asarray(arr, dtype=np.int16, order="C")
+    nch = _frame_channel_count(frame)
+    samples = int(getattr(frame, "samples", 0) or 0)
+
+    if arr.size == 0:
+        return arr
+
+    if arr.ndim == 1:
+        if nch <= 1:
+            return arr.copy()
+        if samples > 0 and arr.size == samples * nch:
+            return arr.reshape(-1, nch)[:, 0].copy()
+        if samples > 0 and arr.size == samples:
+            return arr.copy()
+        return arr.copy()
+
+    if arr.ndim == 2:
+        # Planar: (nch, samples) — e.g. s16p, fltp with separate planes per channel.
+        if nch > 1 and samples > 0 and arr.shape[0] == nch and arr.shape[1] == samples:
+            return arr[0].copy()
+        # Transposed planar: (samples, nch).
+        if nch > 1 and samples > 0 and arr.shape[1] == nch and arr.shape[0] == samples:
+            return arr[:, 0].copy()
+        # Packed interleaved: (1, samples * nch) — PyAV's default return shape for
+        # s16 / fltp interleaved (one plane holding [L, R, L, R, ...]).  Without
+        # this case the (1, 1920) mono-ish array for 960-sample stereo falls into
+        # the `shape[0] <= shape[1]` heuristic below and is returned as-is, which
+        # feeds interleaved stereo into the model as if it were mono — effectively
+        # doubling the sample rate and producing unintelligible high-frequency
+        # noise on playback.
+        if (
+            nch > 1
+            and samples > 0
+            and arr.shape[0] == 1
+            and arr.shape[1] == samples * nch
+        ):
+            return arr[0].reshape(-1, nch)[:, 0].copy()
+        # Mono packed: (1, samples).
+        if nch <= 1 and arr.shape[0] == 1:
+            return arr[0].copy()
+        # Heuristic fallback for unusual layouts.
+        if arr.shape[0] <= arr.shape[1]:
+            return arr[0].copy()
+        return arr[:, 0].copy()
+
+    flat = arr.ravel()
+    if samples > 0 and nch > 1 and flat.size == samples * nch:
+        return flat.reshape(-1, nch)[:, 0].copy()
+    return flat.copy()
+
+
+def audio_frame_to_numpy(frame: AudioFrame) -> np.ndarray:
+    """Convert an :class:`AudioFrame` to a ``(1, N)`` NumPy **int16 (s16, mono)** array.
+
+    Uses :meth:`~av.audio.frame.AudioFrame.to_ndarray` when available
+    (handles ``s16`` / ``s16p`` / ``fltp``, planar vs interleaved), then
+    normalizes to ``int16`` and **keeps the first channel only** (stereo
+    and multi-plane sources are down-selected, not down-mixed).
+
+    If ``to_ndarray`` is missing, decodes 16-bit PCM from ``frame.planes``
+    (single interleaved buffer or one plane per channel for ``s16p``).
+
+    The result matches the documented transport audio contract in
+    :mod:`reactor_runtime.transports.media` — ``(1, N)`` ``int16`` mono
+    — so the GStreamer and aiortc transports produce identically-shaped
+    buffers on the model's ``InputBuffer`` (before the runtime, only
+    aiortc produced a 1-D ``(N,)`` array, which broke any consumer that
+    indexed ``chunk[0]`` or read ``chunk.shape[1]``).
 
-class OutputAudioTrack(MediaStreamTrack):
+    Args:
+        frame: The :class:`AudioFrame` to convert.
+
+    Returns:
+        ``np.ndarray`` of dtype ``int16``, shape ``(1, N)`` — *N* samples
+        in one channel.
+    """
+    flat = _audio_frame_to_mono_1d(frame)
+    return flat.reshape(1, -1)
+
+
+def _audio_frame_to_mono_1d(frame: AudioFrame) -> np.ndarray:
+    """Internal: flat int16 mono extractor (1-D), used by :func:`audio_frame_to_numpy`."""
+    to_nd = getattr(frame, "to_ndarray", None)
+    if callable(to_nd):
+        arr = np.asarray(to_nd())
+        if arr.dtype in (np.float32, np.float64):
+            return _s16_to_mono_1d(_float_to_s16_samples(arr), frame)
+        if arr.dtype == np.int16:
+            return _s16_to_mono_1d(arr, frame)
+        if arr.dtype in (np.int32, np.int64, np.uint16):
+            return _s16_to_mono_1d(np.clip(arr, -32768, 32767).astype(np.int16), frame)
+
+    # Fallback: 16-bit PCM in one or more planes (or ``to_ndarray`` missing)
+    n_planes = len(frame.planes)
+    if n_planes == 0:
+        return np.empty(0, dtype=np.int16)
+    if n_planes == 1:
+        raw = np.frombuffer(
+            _audio_plane_to_bytes(frame.planes[0]),
+            dtype=np.int16,
+        )
+        return _s16_to_mono_1d(raw, frame)
+    chans = [
+        np.frombuffer(_audio_plane_to_bytes(p), dtype=np.int16) for p in frame.planes
+    ]
+    n = min(c.size for c in chans)
+    if n == 0:
+        return np.empty(0, dtype=np.int16)
+    return chans[0][:n].copy()
+
+
+class OutputAudioTrack(AudioStreamTrack):
     """Audio track that outputs samples provided via :meth:`push_samples`.
 
     Designed to be fed audio data from the model's output.  Thread-safe