streamdouble 0.1.0__py3-none-any.whl

streamdouble/__init__.py

@@ -0,0 +1,14 @@
+"""streamdouble -- a framework-agnostic Twilio Media Streams simulator.
+
+Test a voice agent's WebSocket endpoint locally, at full protocol fidelity,
+without placing a real call.
+
+Not affiliated with Twilio. This package simulates the publicly documented
+Twilio Media Streams protocol.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

streamdouble/audio.py

@@ -0,0 +1,232 @@
+"""WAV <-> mu-law conversion and 20 ms frame chunking.
+
+Twilio Media Streams carries ``audio/x-mulaw`` at 8000 Hz, mono. One mu-law byte
+is one sample, so a 20 ms frame is exactly 160 bytes. Twilio does not document a
+mandatory frame size, but 20 ms is what it sends and what every implementation
+expects; sending a different size is one of the ways a simulator stops being a
+faithful one.
+
+Pure functions and file I/O only -- nothing here touches the network. If a bug
+in this module needs a WebSocket to reproduce, the layering is wrong.
+"""
+
+from __future__ import annotations
+
+import wave
+from pathlib import Path
+
+import numpy as np
+
+from . import g711
+
+__all__ = [
+    "FRAME_BYTES",
+    "FRAME_MS",
+    "SAMPLES_PER_FRAME",
+    "SAMPLE_RATE",
+    "AudioError",
+    "frame_ulaw",
+    "load_wav",
+    "resample",
+    "silence_frame",
+    "to_mono",
+    "ulaw_to_wav",
+    "wav_to_ulaw_frames",
+]
+
+#: Twilio Media Streams sample rate, in Hz. Not configurable at the protocol level.
+SAMPLE_RATE = 8000
+
+#: Duration of one media frame, in milliseconds.
+FRAME_MS = 20
+
+#: Samples in one 20 ms frame at 8 kHz.
+SAMPLES_PER_FRAME = SAMPLE_RATE * FRAME_MS // 1000  # 160
+
+#: Bytes in one 20 ms mu-law frame. One byte per sample.
+FRAME_BYTES = SAMPLES_PER_FRAME  # 160
+
+
+class AudioError(Exception):
+    """Raised for unusable audio input: bad WAV, unsupported encoding, etc."""
+
+
+def load_wav(path: str | Path) -> tuple[np.ndarray, int]:
+    """Read a PCM WAV file into int16 samples.
+
+    Args:
+        path: Path to a PCM (uncompressed) WAV file.
+
+    Returns:
+        ``(samples, sample_rate)`` where ``samples`` is 2-D with shape
+        ``(n_frames, n_channels)`` and dtype int16.
+
+    Raises:
+        AudioError: The file is not readable as PCM WAV, or uses a sample width
+            this module does not handle.
+    """
+    path = Path(path)
+    try:
+        with wave.open(str(path), "rb") as wav:
+            channels = wav.getnchannels()
+            width = wav.getsampwidth()
+            rate = wav.getframerate()
+            n_frames = wav.getnframes()
+            raw = wav.readframes(n_frames)
+    except wave.Error as exc:
+        raise AudioError(f"{path}: not a readable PCM WAV file ({exc})") from exc
+    except FileNotFoundError as exc:
+        raise AudioError(f"{path}: no such file") from exc
+
+    if channels < 1:
+        raise AudioError(f"{path}: reports {channels} channels")
+    if rate < 1:
+        raise AudioError(f"{path}: reports a sample rate of {rate} Hz")
+
+    # Check we actually got the audio the header promised, before handing the
+    # bytes to numpy. A truncated file otherwise fails in one of two bad ways:
+    # an odd byte count raises a bare ValueError out of np.frombuffer, breaking
+    # this module's promise that bad input arrives as AudioError; and an even
+    # truncation is worse still, decoding silently to less audio than the caller
+    # asked for, which looks downstream like the agent stopped talking.
+    # Interrupted downloads and killed recordings both produce exactly this.
+    expected_bytes = n_frames * channels * width
+    if len(raw) != expected_bytes:
+        raise AudioError(
+            f"{path}: truncated. Header declares {n_frames} frames "
+            f"({expected_bytes} bytes) but the data chunk holds {len(raw)}"
+        )
+
+    samples = _decode_pcm(raw, width, path)
+
+    if samples.size % channels:
+        raise AudioError(
+            f"{path}: sample count {samples.size} is not divisible by {channels} channels"
+        )
+    return samples.reshape(-1, channels), rate
+
+
+def _decode_pcm(raw: bytes, width: int, path: Path) -> np.ndarray:
+    """Convert raw WAV frame bytes of the given sample width to int16."""
+    if width == 1:
+        # 8-bit WAV is unsigned, offset by 128. Everything else is signed.
+        u8 = np.frombuffer(raw, dtype=np.uint8).astype(np.int16)
+        return ((u8 - 128) << 8).astype(np.int16)
+    if width == 2:
+        return np.frombuffer(raw, dtype="<i2").copy()
+    if width == 3:
+        # 24-bit little-endian packed. Widen to int32 by placing the three bytes
+        # in the *high* 24 bits, which sign-extends for free, then shift down.
+        b = np.frombuffer(raw, dtype=np.uint8)
+        if b.size % 3:
+            raise AudioError(f"{path}: 24-bit data length {b.size} is not a multiple of 3")
+        b = b.reshape(-1, 3).astype(np.int32)
+        i32 = (b[:, 0] << 8) | (b[:, 1] << 16) | (b[:, 2] << 24)
+        return (i32 >> 16).astype(np.int16)
+    if width == 4:
+        return (np.frombuffer(raw, dtype="<i4") >> 16).astype(np.int16)
+    raise AudioError(f"{path}: unsupported sample width of {width} bytes")
+
+
+def to_mono(samples: np.ndarray) -> np.ndarray:
+    """Downmix ``(n, channels)`` int16 samples to a 1-D mono int16 array.
+
+    Averages in int32 so that summing channels cannot overflow.
+    """
+    if samples.ndim == 1:
+        return samples.astype(np.int16, copy=False)
+    if samples.shape[1] == 1:
+        return samples[:, 0].astype(np.int16, copy=False)
+    return samples.astype(np.int32).mean(axis=1).round().astype(np.int16)
+
+
+def resample(samples: np.ndarray, src_rate: int, dst_rate: int = SAMPLE_RATE) -> np.ndarray:
+    """Resample 1-D int16 audio.
+
+    Uses ``soxr`` for a proper band-limited resample. There is no acceptable
+    stdlib resampler: naive decimation aliases badly, and aliasing at 8 kHz
+    lands squarely in the speech band, so it would degrade exactly the audio the
+    tool exists to test.
+
+    Raises:
+        AudioError: The input is not usable 1-D audio, a rate is not positive,
+            or a rate change is needed but ``soxr`` is not installed.
+    """
+    # Validate at the boundary rather than letting the failure surface later.
+    # Multi-channel input reaching here means the caller skipped to_mono; soxr
+    # would happily resample it per-channel and hand back a 2-D array, and the
+    # eventual complaint would come from g711.encode and appear to blame the
+    # codec rather than the missing downmix.
+    if samples.ndim != 1:
+        raise AudioError(
+            f"resample expects 1-D mono audio, got shape {samples.shape}. "
+            "Pass it through to_mono() first."
+        )
+    if src_rate < 1 or dst_rate < 1:
+        raise AudioError(
+            f"sample rates must be positive, got src_rate={src_rate}, dst_rate={dst_rate}"
+        )
+
+    if src_rate == dst_rate:
+        return samples
+    try:
+        import soxr
+    except ImportError as exc:
+        raise AudioError(
+            f"input is {src_rate} Hz and must be resampled to {dst_rate} Hz, but the "
+            "'soxr' package is not installed. Install it with "
+            "'pip install streamdouble[resample]', or supply audio that is already "
+            f"{dst_rate} Hz mono."
+        ) from exc
+
+    resampled = soxr.resample(samples.astype(np.float32), src_rate, dst_rate, quality="VHQ")
+    # Clip before casting: a band-limited resampler can overshoot past full scale
+    # on transients, and a bare astype would wrap that around to the opposite sign.
+    return np.clip(np.round(resampled), -32768, 32767).astype(np.int16)
+
+
+def frame_ulaw(payload: bytes, pad: bool = True) -> list[bytes]:
+    """Split mu-law bytes into 160-byte frames.
+
+    Args:
+        payload: mu-law encoded audio.
+        pad: If true, pad a short final frame to 160 bytes with mu-law silence.
+            If false, drop it.
+
+    Returns:
+        A list of frames, each exactly ``FRAME_BYTES`` long.
+    """
+    frames = [payload[i : i + FRAME_BYTES] for i in range(0, len(payload), FRAME_BYTES)]
+    if frames and len(frames[-1]) < FRAME_BYTES:
+        if pad:
+            short = frames[-1]
+            frames[-1] = short + bytes([g711.SILENCE_BYTE]) * (FRAME_BYTES - len(short))
+        else:
+            frames.pop()
+    return frames
+
+
+def silence_frame() -> bytes:
+    """One 20 ms frame of mu-law digital silence."""
+    return bytes([g711.SILENCE_BYTE]) * FRAME_BYTES
+
+
+def wav_to_ulaw_frames(path: str | Path, pad: bool = True) -> list[bytes]:
+    """Load a WAV file and convert it to a list of 160-byte mu-law frames.
+
+    Handles downmixing to mono and resampling to 8 kHz along the way.
+    """
+    samples, rate = load_wav(path)
+    mono = to_mono(samples)
+    resampled = resample(mono, rate, SAMPLE_RATE)
+    return frame_ulaw(g711.encode(resampled), pad=pad)
+
+
+def ulaw_to_wav(payload: bytes, path: str | Path) -> None:
+    """Decode mu-law bytes and write them to an 8 kHz mono 16-bit WAV file."""
+    samples = g711.decode(payload)
+    with wave.open(str(path), "wb") as wav:
+        wav.setnchannels(1)
+        wav.setsampwidth(2)
+        wav.setframerate(SAMPLE_RATE)
+        wav.writeframes(samples.tobytes())

streamdouble/chaos.py

@@ -0,0 +1,162 @@
+"""Network impairment: what a bad mobile connection does to a call.
+
+The happy path is not where voice agents break. They break when the caller is on
+a train, and the tool is only worth having if it can reproduce that.
+
+Pure and deterministic: this module decides *whether* to drop a frame and *how
+long* to delay one, and nothing else. It performs no I/O, reads no clock, and
+given the same seed makes the same decisions every run. A chaos feature that
+cannot be replayed is not a test tool, it is a random number generator that
+occasionally fails your build -- when a bad seed finds a real bug, you need to
+be able to hand someone the seed.
+
+A note on what impairment can and cannot mean here, because it shapes every
+decision below and the Twilio documentation does not address it.
+
+**The Twilio-to-app leg is a WebSocket, which is TCP.** TCP retransmits, so a
+frame cannot simply vanish in transit and cannot arrive out of order. Whatever
+"packet loss" means for a voice call, it does not mean a missing WebSocket
+frame. The loss happens *upstream* of Twilio -- on the carrier's RTP leg, which
+is UDP over a mobile network -- and by the time Twilio comes to build a frame,
+that audio was never received.
+
+So the model here is: a dropped frame is one Twilio never sends, because it
+never had the audio. The app sees no gap in ``sequenceNumber`` (Twilio numbers
+what it sends), but it does see ``media.timestamp`` jump by more than one frame
+interval, because presentation time keeps running while the audio does not.
+
+**This is an inference, not documentation.** Twilio does not say whether it
+skips the frame or substitutes silence; both are plausible implementations. The
+skip model was chosen because it is the one an agent can actually detect -- a
+timestamp discontinuity is a signal, silence substitution is invisible -- and a
+test tool should surface the harder case. If Twilio turns out to substitute
+silence, this is the knob to change, and the docstring is here so that whoever
+finds out knows where to look.
+"""
+
+from __future__ import annotations
+
+import random
+from dataclasses import dataclass
+
+__all__ = ["Impairments", "Network"]
+
+
+@dataclass(frozen=True)
+class Impairments:
+    """How badly to treat the caller's audio.
+
+    Defaults are a perfect connection, so an unconfigured session behaves
+    exactly as it did before this module existed.
+    """
+
+    #: Probability in [0, 1] that any given frame is never sent.
+    loss: float = 0.0
+
+    #: Maximum timing deviation, in milliseconds, applied per frame. Drawn
+    #: uniformly from [0, jitter_ms] -- never negative, because a frame cannot
+    #: be delivered before the audio in it was spoken.
+    jitter_ms: float = 0.0
+
+    #: Constant delay added to every frame, in milliseconds. Models distance
+    #: rather than instability: a caller on the other side of the world.
+    latency_ms: float = 0.0
+
+    def __post_init__(self) -> None:
+        if not 0.0 <= self.loss <= 1.0:
+            raise ValueError(f"loss must be a probability in [0, 1], got {self.loss}")
+        if self.jitter_ms < 0:
+            raise ValueError(f"jitter_ms cannot be negative, got {self.jitter_ms}")
+        if self.latency_ms < 0:
+            raise ValueError(f"latency_ms cannot be negative, got {self.latency_ms}")
+
+    @property
+    def active(self) -> bool:
+        """Whether anything at all is being impaired."""
+        return bool(self.loss or self.jitter_ms or self.latency_ms)
+
+    def describe(self) -> str:
+        if not self.active:
+            return "none"
+        parts = []
+        if self.loss:
+            parts.append(f"{self.loss:.1%} loss")
+        if self.jitter_ms:
+            parts.append(f"{self.jitter_ms:g}ms jitter")
+        if self.latency_ms:
+            parts.append(f"{self.latency_ms:g}ms latency")
+        return ", ".join(parts)
+
+
+class Network:
+    """Decides, per frame, whether it is lost and how late it is.
+
+    Seeded explicitly rather than left to global randomness. When a chaos run
+    finds a bug, the seed is the reproduction: without it the failure is a story
+    about something that happened once.
+
+    ``random.Random`` is used rather than ``numpy.random.Generator`` for the same
+    reason the fixtures avoid it -- CPython documents the Mersenne Twister
+    stream as stable across versions, while NumPy explicitly reserves the right
+    to change ``Generator`` on a feature release.
+    """
+
+    def __init__(self, impairments: Impairments | None = None, *, seed: int = 0) -> None:
+        self.impairments = impairments or Impairments()
+        self.seed = seed
+        self._random = random.Random(seed)
+
+        self.frames_considered = 0
+        self.frames_dropped = 0
+        self.total_delay_s = 0.0
+
+    @property
+    def active(self) -> bool:
+        return self.impairments.active
+
+    def should_drop(self) -> bool:
+        """Whether this frame is lost before Twilio ever sees it."""
+        self.frames_considered += 1
+        if not self.impairments.loss:
+            return False
+        dropped = self._random.random() < self.impairments.loss
+        if dropped:
+            self.frames_dropped += 1
+        return dropped
+
+    def delay_s(self) -> float:
+        """Extra delay for this frame, in seconds, on top of its schedule.
+
+        Constant latency plus a per-frame jitter draw. Always non-negative:
+        pulling a frame *earlier* than its deadline would mean delivering audio
+        before it was spoken, which no network does.
+
+        Jitter is applied to a frame's release without moving any other frame's
+        deadline, so it perturbs spacing without accumulating -- the pacer's
+        absolute-deadline scheduling absorbs it, which is exactly the behaviour a
+        real jitter buffer has.
+        """
+        delay = self.impairments.latency_ms / 1000
+        if self.impairments.jitter_ms:
+            delay += self._random.uniform(0, self.impairments.jitter_ms / 1000)
+        self.total_delay_s += delay
+        return delay
+
+    def summary(self) -> str:
+        if not self.active:
+            return "no impairment"
+        loss_pct = (
+            self.frames_dropped / self.frames_considered * 100
+            if self.frames_considered
+            else 0.0
+        )
+        mean_delay_ms = (
+            self.total_delay_s / self.frames_considered * 1000
+            if self.frames_considered
+            else 0.0
+        )
+        return (
+            f"{self.impairments.describe()} (seed {self.seed}): "
+            f"dropped {self.frames_dropped}/{self.frames_considered} "
+            f"({loss_pct:.1f}%), mean added delay {mean_delay_ms:.1f}ms"
+        )