rushaudio 1.1.0__py3-none-any.whl

rushaudio/__init__.py

@@ -0,0 +1,94 @@
+"""RushAudio — low-latency audio over IP live streaming protocol.
+
+Pure-Python, zero-dependency port of the Rust reference implementation
+(https://github.com/OseMine/rushaudio). Follows the canonical wire spec in
+``docs/protocol.md`` of the rushaudio repository.
+
+Public API mirrors the Rust crate:
+
+    import rushaudio
+    server = rushaudio.create_server("0.0.0.0:4210")
+    client = rushaudio.create_client()
+
+    pkt = Packet.new(PacketType.AUDIO_DATA, seq=1, ts=0,
+                     payload=b"...")
+    wire = pkt.encode()
+    parsed = Packet.decode(wire)
+"""
+
+from . import constants as _c
+from .connection import Connection, ConnectionPool
+from .fec import FecEncoder
+from .handshake import Handshake, HandshakeRole, HandshakeState
+from .jitter import JitterBuffer, JitterStats
+from .levels import AudioLevels
+from .metadata import Metadata, MetadataBuilder, MetadataEntry, MetadataMap
+from .packet import (
+    BadMagicError,
+    InvalidPayloadError,
+    Packet,
+    PacketError,
+    PacketHeader,
+    PacketTooShortError,
+    TruncatedPayloadError,
+    UnknownTypeError,
+)
+from .session import Session, SessionManager
+from .transport import UdpTransport
+from .types import (
+    AudioCodec,
+    ConnectionState,
+    PacketType,
+    StreamConfig,
+    StreamStats,
+)
+
+VERSION = "1.1.0"
+DEFAULT_PORT: int = 4210
+
+
+def create_server(bind_addr: str) -> UdpTransport:
+    """Bind a non-blocking UDP server, e.g. ``create_server("0.0.0.0:4210")``."""
+    return UdpTransport.bind(bind_addr)
+
+
+def create_client() -> UdpTransport:
+    """Bind a non-blocking UDP socket on an ephemeral port."""
+    return UdpTransport.bind("0.0.0.0:0")
+
+
+__all__ = [
+    "AudioCodec",
+    "AudioLevels",
+    "BadMagicError",
+    "Connection",
+    "ConnectionPool",
+    "ConnectionState",
+    "FecEncoder",
+    "Handshake",
+    "HandshakeRole",
+    "HandshakeState",
+    "InvalidPayloadError",
+    "JitterBuffer",
+    "JitterStats",
+    "Metadata",
+    "MetadataBuilder",
+    "MetadataEntry",
+    "MetadataMap",
+    "Packet",
+    "PacketError",
+    "PacketHeader",
+    "PacketTooShortError",
+    "PacketType",
+    "Session",
+    "SessionManager",
+    "StreamConfig",
+    "StreamStats",
+    "TruncatedPayloadError",
+    "UdpTransport",
+    "UnknownTypeError",
+    "VERSION",
+    "DEFAULT_PORT",
+    "create_server",
+    "create_client",
+]

rushaudio/connection.py

@@ -0,0 +1,99 @@
+"""Per-peer connection tracking and a bounded connection pool.
+
+Mirrors ``src/transport/connection.rs`` in the Rust reference implementation.
+"""
+
+import time
+from dataclasses import dataclass, field
+from typing import Hashable, Iterator, List, Optional
+
+from .types import ConnectionState, StreamConfig, StreamStats
+
+
+@dataclass
+class Connection:
+    """State and statistics for one remote peer."""
+
+    remote_addr: Hashable
+    state: ConnectionState = ConnectionState.DISCONNECTED
+    config: StreamConfig = field(default_factory=StreamConfig)
+    stats: StreamStats = field(default_factory=StreamStats)
+    sequence_number: int = 0
+    connected_at: Optional[float] = None
+    last_activity: float = field(default_factory=time.monotonic)
+    ssrc: int = 0
+
+    def next_seq(self) -> int:
+        """Return the current sequence number and advance it (mod 2^32)."""
+        value = self.sequence_number
+        self.sequence_number = (self.sequence_number + 1) & 0xFFFFFFFF
+        return value
+
+    def current_seq(self) -> int:
+        return self.sequence_number
+
+    def mark_activity(self) -> None:
+        self.last_activity = time.monotonic()
+
+    def elapsed_since_activity(self) -> float:
+        return time.monotonic() - self.last_activity
+
+    def set_state(self, state: ConnectionState) -> None:
+        self.state = state
+        if state == ConnectionState.CONNECTED:
+            self.connected_at = time.monotonic()
+
+    def record_sent(self, size: int) -> None:
+        self.stats.packets_sent += 1
+        self.stats.bytes_sent += size
+
+    def record_received(self, size: int) -> None:
+        self.stats.packets_received += 1
+        self.stats.bytes_received += size
+
+    def record_loss(self, count: int) -> None:
+        self.stats.packets_lost += count
+
+
+class ConnectionPool:
+    """A bounded collection of connections keyed by remote address."""
+
+    def __init__(self, max_connections: int) -> None:
+        self._connections: List[Connection] = []
+        self._max_connections = max_connections
+
+    def get(self, addr: Hashable) -> Optional[Connection]:
+        for conn in self._connections:
+            if conn.remote_addr == addr:
+                return conn
+        return None
+
+    def get_mut(self, addr: Hashable) -> Optional[Connection]:
+        return self.get(addr)
+
+    def add(self, conn: Connection) -> bool:
+        if len(self._connections) >= self._max_connections:
+            return False
+        self._connections.append(conn)
+        return True
+
+    def remove(self, addr: Hashable) -> None:
+        self._connections = [c for c in self._connections if c.remote_addr != addr]
+
+    def len(self) -> int:
+        return len(self._connections)
+
+    def __len__(self) -> int:
+        return len(self._connections)
+
+    def is_empty(self) -> bool:
+        return not self._connections
+
+    def iter(self) -> Iterator[Connection]:
+        return iter(self._connections)
+
+    def __iter__(self) -> Iterator[Connection]:
+        return iter(self._connections)
+
+    def contains(self, addr: Hashable) -> bool:
+        return any(c.remote_addr == addr for c in self._connections)

rushaudio/constants.py

@@ -0,0 +1,62 @@
+"""Protocol constants for the RushAudio Python port.
+
+Mirrors ``src/protocol/constants.rs`` in the Rust reference implementation.
+"""
+
+PROTOCOL_MAGIC = bytes((0x52, 0x41))  # ASCII "RA"
+PROTOCOL_VERSION = 1
+
+HEADER_SIZE = 14  # 2(magic) + 1(ver) + 1(type) + 4(seq) + 4(ts) + 2(len)
+MAX_PAYLOAD_SIZE = 4096
+MAX_PACKET_SIZE = HEADER_SIZE + MAX_PAYLOAD_SIZE
+
+# Default timing
+DEFAULT_SAMPLE_RATE = 48000
+DEFAULT_FRAME_DURATION_MS = 20
+DEFAULT_JITTER_BUFFER_MS = 80
+DEFAULT_KEEPALIVE_INTERVAL_MS = 5000
+DEFAULT_HANDSHAKE_TIMEOUT_MS = 3000
+
+# Opus defaults
+OPUS_FRAME_SIZE_20MS = 960  # 48000 * 0.020
+OPUS_CHANNELS = 2
+
+# FEC
+FEC_REDUNDANCY_COUNT = 1
+FEC_GROUP_SIZE = 4
+
+# Control codes
+CONTROL_STREAM_START = 0x01
+CONTROL_STREAM_STOP = 0x02
+CONTROL_STREAM_PAUSE = 0x03
+CONTROL_STREAM_RESUME = 0x04
+
+# Metadata entry header: 1(key) + 2(length) = 3 bytes
+METADATA_ENTRY_HEADER_SIZE = 3
+
+# Built-in metadata keys (0x00 reserved, 0x01-0x7F reserved by protocol)
+META_SSRC = 0x01
+META_TRACK_TITLE = 0x02
+META_ARTIST = 0x03
+META_ALBUM = 0x04
+META_GENRE = 0x05
+META_SAMPLE_RATE = 0x06
+META_CHANNELS = 0x07
+META_CODEC_INFO = 0x08
+META_BITRATE = 0x09
+META_DURATION_MS = 0x0A
+META_STREAM_TITLE = 0x0B
+META_STREAM_URL = 0x0C
+
+# Custom metadata keys start at 0x80
+META_CUSTOM_BASE = 0x80
+
+# Audio level / VU meter
+# Payload: 4(audio_sequence) + 4(audio_timestamp) + 1(peak) + 1(rms)
+AUDIO_LEVELS_PAYLOAD_SIZE = 10
+# Levels are encoded in dBFS with 1 dB per unit. 0 = full scale (0 dBFS),
+# -127 = quietest non-silent level. LEVEL_SILENCE (-128) means -infinity dBFS
+# (digital silence).
+LEVEL_DBFS_MAX = 0
+LEVEL_DBFS_MIN = -127
+LEVEL_SILENCE = -128

rushaudio/fec.py

@@ -0,0 +1,84 @@
+"""XOR-based forward error correction.
+
+Mirrors ``src/utils/fec.rs`` in the Rust reference implementation and
+spec section 8.
+
+- Encoding: XOR-reduce the payloads of a group of packets into one repair
+  packet that also carries the group count and the original sequence numbers.
+- Decoding: XOR the repair data with every surviving packet of the group to
+  recover a single missing packet. More than one loss per group is fatal.
+"""
+
+from typing import List, Optional, Sequence, Tuple
+
+from .packet import Packet
+from .types import PacketType
+
+
+class FecEncoder:
+    """Static helpers for FEC repair packet generation and recovery."""
+
+    @staticmethod
+    def generate_repair(group: Sequence[Packet], seq: int, ts: int) -> Optional[Packet]:
+        """Build a FECData repair packet for a group of data packets.
+
+        XORs all group payloads into ``repair_data`` (sized to the longest
+        payload in the group) and prefixes:
+        ``[group_count: u8] [sequence × group_count: u32 BE each]``.
+        """
+        if not group:
+            return None
+
+        max_len = max(len(pkt.payload) for pkt in group)
+        repair = bytearray(max_len)
+        for pkt in group:
+            for index, byte in enumerate(pkt.payload):
+                repair[index] ^= byte
+
+        fec_meta = bytearray([len(group)])
+        for pkt in group:
+            fec_meta += pkt.header.sequence.to_bytes(4, "big")
+
+        return Packet.new(
+            PacketType.FEC_DATA, seq, ts, bytes(fec_meta) + bytes(repair)
+        )
+
+    @staticmethod
+    def try_recover(
+        repair_packet: Packet, available: Sequence[Packet]
+    ) -> Optional[Tuple[int, bytes]]:
+        """Attempt to recover a lost packet.
+
+        Returns ``(lost_sequence, recovered_payload)`` when exactly one
+        packet of the FEC group is missing and recoverable; otherwise None.
+        """
+        payload = repair_packet.payload
+        if not payload:
+            return None
+
+        group_count = payload[0]
+        meta_end = 1 + group_count * 4
+        if len(payload) < meta_end:
+            return None
+
+        sequences = [
+            int.from_bytes(payload[1 + i * 4:5 + i * 4], "big")
+            for i in range(group_count)
+        ]
+        repair_data = bytearray(payload[meta_end:])
+
+        available_seqs = {pkt.header.sequence for pkt in available}
+        missing = [s for s in sequences if s not in available_seqs]
+        if len(missing) != 1:
+            return None
+        lost_seq = missing[0]
+
+        for pkt in available:
+            if pkt.header.sequence == lost_seq:
+                continue
+            if pkt.header.sequence in sequences:
+                for index, byte in enumerate(pkt.payload):
+                    if index < len(repair_data):
+                        repair_data[index] ^= byte
+
+        return lost_seq, bytes(repair_data)

rushaudio/handshake.py

@@ -0,0 +1,99 @@
+"""Session handshake state machine and payload builders/parsers.
+
+Mirrors ``src/session/handshake.rs`` in the Rust reference implementation and
+spec section 5.
+"""
+
+import enum
+import time
+from dataclasses import dataclass, field
+from typing import Optional, Tuple
+
+from . import constants as _c
+from .packet import Packet
+from .types import AudioCodec, PacketType, StreamConfig
+
+
+class HandshakeRole(enum.Enum):
+    INITIATOR = "Initiator"
+    RESPONDER = "Responder"
+
+
+class HandshakeState(enum.Enum):
+    IDLE = "Idle"
+    WAITING_FOR_RESPONSE = "WaitingForResponse"
+    WAITING_FOR_REQUEST = "WaitingForRequest"
+    COMPLETED = "Completed"
+    FAILED = "Failed"
+
+
+@dataclass
+class Handshake:
+    """Tracks one side of a handshake and builds/parses its packets."""
+
+    role: HandshakeRole
+    ssrc: int
+    config: StreamConfig
+    state: HandshakeState = HandshakeState.IDLE
+    remote_addr: Optional[str] = None
+    started_at: Optional[float] = None
+    timeout: float = _c.DEFAULT_HANDSHAKE_TIMEOUT_MS / 1000.0
+
+    def build_request(self, seq: int, ts: int) -> Packet:
+        """Build a HandshakeRequest packet (14-byte payload, spec 4.3)."""
+        payload = (
+            self.ssrc.to_bytes(4, "big")
+            + self.config.sample_rate.to_bytes(4, "big")
+            + self.config.bitrate.to_bytes(4, "big")
+            + bytes((self.config.codec.to_u8(), self.config.channels))
+        )
+        return Packet.new(PacketType.HANDSHAKE_REQUEST, seq, ts, payload)
+
+    def build_response(self, seq: int, ts: int, accepted: bool) -> Packet:
+        """Build a HandshakeResponse packet (5-byte payload, spec 4.4)."""
+        payload = bytes((0x01 if accepted else 0x00,)) + self.ssrc.to_bytes(4, "big")
+        return Packet.new(PacketType.HANDSHAKE_RESPONSE, seq, ts, payload)
+
+    @staticmethod
+    def parse_request(packet: Packet) -> Optional[Tuple[int, StreamConfig]]:
+        """Parse a HandshakeRequest -> (remote_ssrc, StreamConfig)."""
+        payload = packet.payload
+        if len(payload) < 12:
+            return None
+
+        remote_ssrc = int.from_bytes(payload[0:4], "big")
+        sample_rate = int.from_bytes(payload[4:8], "big")
+        bitrate = int.from_bytes(payload[8:12], "big")
+        codec = AudioCodec.from_u8(payload[12]) if len(payload) > 12 else None
+        if codec is None:
+            codec = AudioCodec.OPUS
+        channels = payload[13] if len(payload) > 13 else 2
+
+        config = StreamConfig(
+            sample_rate=sample_rate,
+            channels=channels,
+            bitrate=bitrate,
+            codec=codec,
+            ssrc=0,
+        )
+        return remote_ssrc, config
+
+    @staticmethod
+    def parse_response(packet: Packet) -> Optional[Tuple[bool, int]]:
+        """Parse a HandshakeResponse -> (accepted, responder_ssrc)."""
+        payload = packet.payload
+        if len(payload) < 5:
+            return None
+        accepted = payload[0] == 0x01
+        ssrc = int.from_bytes(payload[1:5], "big")
+        return accepted, ssrc
+
+    def start(self, remote: str) -> None:
+        self.state = HandshakeState.WAITING_FOR_RESPONSE
+        self.remote_addr = remote
+        self.started_at = time.monotonic()
+
+    def timed_out(self) -> bool:
+        if self.started_at is None:
+            return True
+        return (time.monotonic() - self.started_at) > self.timeout

rushaudio/jitter.py

@@ -0,0 +1,144 @@
+"""Adaptive jitter buffer (spec section 7).
+
+Mirrors ``src/audio/jitter.rs`` in the Rust reference implementation.
+
+Packets are inserted in sequence order and only released once they have aged
+past the target delay. The target delay adapts to observed jitter with an
+exponential moving average.
+"""
+
+import time
+from dataclasses import dataclass
+from typing import Deque, List, Optional, Tuple
+
+from . import constants as _c
+
+
+@dataclass
+class _JitterPacket:
+    data: bytes
+    sequence: int
+    timestamp: int
+    received_at: float
+
+
+# Placeholder to keep the public surface explicit in type hints.
+JitterPacket = _JitterPacket
+
+
+@dataclass(frozen=True)
+class JitterStats:
+    depth: int
+    dropped: int
+    inserted: int
+    late: int
+    jitter_ms: float
+    target_delay_ms: float
+
+
+class JitterBuffer:
+    """Sequence-ordered buffer that absorbs network jitter."""
+
+    def __init__(self, capacity: int = 256) -> None:
+        self._packets: List[_JitterPacket] = []
+        self._capacity = capacity
+        self._target_delay = _c.DEFAULT_JITTER_BUFFER_MS / 1000.0
+        self._min_delay = 0.020
+        self._max_delay = 0.400
+        self._last_playout_ts: Optional[int] = None
+        self._dropped = 0
+        self._inserted = 0
+        self._late = 0
+        self._current_jitter = 0.0
+
+    def with_capacity(self, cap: int) -> "JitterBuffer":
+        return JitterBuffer(capacity=cap)
+
+    def push(self, sequence: int, timestamp: int, data: bytes) -> None:
+        if len(self._packets) >= self._capacity:
+            self._packets.pop(0)
+            self._dropped += 1
+
+        packet = _JitterPacket(
+            data=bytes(data),
+            sequence=sequence,
+            timestamp=timestamp,
+            received_at=time.monotonic(),
+        )
+
+        index = self._insert_index(packet.sequence)
+        if index < len(self._packets) and self._packets[index].sequence == sequence:
+            return  # duplicate, drop silently (mirrors Rust binary_search hit)
+
+        if self._last_playout_ts is not None:
+            if sequence < self._last_playout_ts and (
+                self._last_playout_ts - sequence
+            ) > 1000:
+                self._late += 1
+                return
+
+        self._packets.insert(index, packet)
+        self._inserted += 1
+
+    def _insert_index(self, sequence: int) -> int:
+        lo, hi = 0, len(self._packets)
+        while lo < hi:
+            mid = (lo + hi) // 2
+            if self._packets[mid].sequence < sequence:
+                lo = mid + 1
+            else:
+                hi = mid
+        return lo
+
+    def pop(self) -> Optional[Tuple[int, bytes]]:
+        if not self._packets:
+            return None
+
+        now = time.monotonic()
+        head = self._packets[0]
+        head_age = now - head.received_at
+        if head_age < self._target_delay:
+            return None
+
+        packet = self._packets.pop(0)
+        self._last_playout_ts = packet.timestamp
+        self._current_jitter = self._current_jitter * 0.875 + (head_age * 1000.0) * 0.125
+        return packet.timestamp, packet.data
+
+    def peek(self) -> Optional[Tuple[int, int, int]]:
+        if not self._packets:
+            return None
+        head = self._packets[0]
+        return head.sequence, head.timestamp, len(head.data)
+
+    def len(self) -> int:
+        return len(self._packets)
+
+    def __len__(self) -> int:
+        return len(self._packets)
+
+    def is_empty(self) -> bool:
+        return not self._packets
+
+    def clear(self) -> None:
+        self._packets.clear()
+
+    def stats(self) -> JitterStats:
+        return JitterStats(
+            depth=len(self._packets),
+            dropped=self._dropped,
+            inserted=self._inserted,
+            late=self._late,
+            jitter_ms=self._current_jitter,
+            target_delay_ms=self._target_delay * 1000.0,
+        )
+
+    def adapt_delay(self) -> None:
+        new_target = max(self._current_jitter * 2.0 + 10.0, 20.0) / 1000.0
+        self._target_delay = min(max(new_target, self._min_delay), self._max_delay)
+
+    def set_min_delay(self, ms: int) -> None:
+        self._min_delay = ms / 1000.0
+
+    def set_max_delay(self, ms: int) -> None:
+        self._max_delay = ms / 1000.0

rushaudio/levels.py

@@ -0,0 +1,52 @@
+"""Per-packet audio level measurement (VU meter data) packet type.
+
+Mirrors ``src/protocol/levels.rs`` in the Rust reference implementation.
+
+Levels are in dBFS with 1 dB per unit: ``0`` = full scale, ``-127`` =
+quietest non-silent level, and ``LEVEL_SILENCE`` (-128) = digital silence.
+"""
+
+import struct
+from dataclasses import dataclass
+
+from . import constants as _c
+from .packet import InvalidPayloadError, Packet
+from .types import PacketType
+
+
+@dataclass(frozen=True)
+class AudioLevels:
+    """Levels describing one ``AudioData`` packet (spec section 4.10)."""
+
+    audio_sequence: int
+    audio_timestamp: int
+    peak: int
+    rms: int
+
+    def encode(self) -> bytes:
+        return (
+            self.audio_sequence.to_bytes(4, "big")
+            + self.audio_timestamp.to_bytes(4, "big")
+            + struct.pack("b", self.peak)
+            + struct.pack("b", self.rms)
+        )
+
+    @classmethod
+    def decode(cls, data: bytes) -> "AudioLevels":
+        if len(data) < _c.AUDIO_LEVELS_PAYLOAD_SIZE:
+            raise InvalidPayloadError("audio level payload too short")
+        return cls(
+            audio_sequence=int.from_bytes(data[0:4], "big"),
+            audio_timestamp=int.from_bytes(data[4:8], "big"),
+            peak=struct.unpack("b", data[8:9])[0],
+            rms=struct.unpack("b", data[9:10])[0],
+        )
+
+    def to_packet(self, seq: int, ts: int) -> Packet:
+        return Packet.new(PacketType.AUDIO_LEVEL, seq, ts, self.encode())
+
+    @classmethod
+    def from_packet(cls, packet: Packet) -> "AudioLevels":
+        if packet.header.packet_type != PacketType.AUDIO_LEVEL:
+            raise InvalidPayloadError("not an audio level packet")
+        return cls.decode(packet.payload)