moq-rs 0.3.0__py3-none-any.whl

moq/__init__.py

@@ -0,0 +1,69 @@
+"""The networking layer for Media over QUIC.
+
+Real-time pub/sub with built-in caching, fan-out, and prioritization.
+"""
+
+from moq_ffi import MoqSession as Session
+
+from .client import Client
+from .origin import Announced, AnnouncedBroadcast, Announcement, OriginConsumer, OriginProducer
+from .publish import AudioProducer, BroadcastProducer, GroupProducer, MediaProducer, TrackProducer
+from .server import Request, Server, Transport
+from .subscribe import (
+    AudioConsumer,
+    BroadcastConsumer,
+    CatalogConsumer,
+    Container,
+    GroupConsumer,
+    MediaConsumer,
+    TrackConsumer,
+)
+from .types import (
+    Audio,
+    AudioCodec,
+    AudioDecoderOutput,
+    AudioEncoderInput,
+    AudioEncoderOutput,
+    AudioFormat,
+    AudioFrame,
+    Catalog,
+    Dimensions,
+    Frame,
+    Video,
+)
+
+__all__ = [
+    "Announced",
+    "AnnouncedBroadcast",
+    "Announcement",
+    "Audio",
+    "AudioCodec",
+    "AudioConsumer",
+    "AudioDecoderOutput",
+    "AudioEncoderInput",
+    "AudioEncoderOutput",
+    "AudioFormat",
+    "AudioFrame",
+    "AudioProducer",
+    "BroadcastConsumer",
+    "BroadcastProducer",
+    "Catalog",
+    "CatalogConsumer",
+    "Client",
+    "Container",
+    "Dimensions",
+    "Frame",
+    "GroupConsumer",
+    "GroupProducer",
+    "MediaConsumer",
+    "MediaProducer",
+    "OriginConsumer",
+    "OriginProducer",
+    "Request",
+    "Server",
+    "Session",
+    "TrackConsumer",
+    "TrackProducer",
+    "Transport",
+    "Video",
+]

moq/client.py

@@ -0,0 +1,100 @@
+"""Client wrapper — simplified connection with automatic origin wiring."""
+
+from __future__ import annotations
+
+from moq_ffi import MoqClient
+
+from .origin import Announced, AnnouncedBroadcast, OriginConsumer, OriginProducer
+from .publish import BroadcastProducer
+
+
+class Client:
+    """High-level MoQ client with automatic origin wiring.
+
+    In simple mode (no origin provided), creates an internal origin automatically:
+
+        async with Client("https://relay.example.com") as client:
+            async for ann in client.announced():
+                ...
+
+    In advanced mode, provide your own origin for full control:
+
+        origin = OriginProducer()
+        client = Client("https://relay.example.com", publish=origin, subscribe=origin)
+    """
+
+    def __init__(
+        self,
+        url: str,
+        *,
+        tls_verify: bool = True,
+        bind: str | None = None,
+        publish: OriginProducer | None = None,
+        subscribe: OriginProducer | None = None,
+    ) -> None:
+        self._url = url
+        self._tls_verify = tls_verify
+        self._bind = bind
+
+        # If neither origin is provided, create a shared internal one.
+        if publish is None and subscribe is None:
+            self._origin = OriginProducer()
+            self._publish_origin = self._origin
+            self._consume_origin = self._origin
+        else:
+            self._origin = None
+            self._publish_origin = publish
+            self._consume_origin = subscribe
+
+        self._consumer: OriginConsumer | None = None
+        self._inner: MoqClient | None = None
+        self._session = None
+
+    async def __aenter__(self):
+        self._inner = MoqClient()
+
+        if not self._tls_verify:
+            self._inner.set_tls_disable_verify(True)
+        if self._bind is not None:
+            self._inner.set_bind(self._bind)
+
+        if self._publish_origin is not None:
+            self._inner.set_publish(self._publish_origin._inner)
+        if self._consume_origin is not None:
+            self._inner.set_consume(self._consume_origin._inner)
+
+        self._session = await self._inner.connect(self._url)
+
+        # Create consumer from whichever origin handles consuming.
+        origin = self._consume_origin or self._publish_origin
+        if origin is not None:
+            self._consumer = origin.consume()
+
+        return self
+
+    async def __aexit__(self, *exc) -> None:
+        self._consumer = None
+        if self._inner is not None:
+            self._inner.cancel()
+            self._inner = None
+        self._session = None
+
+    def publish(self, path: str, broadcast: BroadcastProducer) -> None:
+        origin = self._publish_origin
+        if origin is None:
+            raise RuntimeError("no publish origin configured")
+        origin.publish(path, broadcast)
+
+    def announced(self, prefix: str = "") -> Announced:
+        if self._consumer is None:
+            raise RuntimeError("no consume origin configured")
+        return self._consumer.announced(prefix)
+
+    def announced_broadcast(self, path: str) -> AnnouncedBroadcast:
+        if self._consumer is None:
+            raise RuntimeError("no consume origin configured")
+        return self._consumer.announced_broadcast(path)
+
+    @property
+    def session(self):
+        return self._session

moq/origin.py

@@ -0,0 +1,96 @@
+"""Origin wrappers — manage announcements and broadcast discovery."""
+
+from __future__ import annotations
+
+from moq_ffi import MoqAnnounced, MoqAnnouncedBroadcast, MoqAnnouncement, MoqOriginConsumer, MoqOriginProducer
+
+from .publish import BroadcastProducer
+from .subscribe import BroadcastConsumer
+
+
+class Announcement:
+    """Wraps MoqAnnouncement — a discovered broadcast."""
+
+    def __init__(self, inner: MoqAnnouncement) -> None:
+        self._inner = inner
+
+    @property
+    def path(self) -> str:
+        return self._inner.path()
+
+    @property
+    def broadcast(self) -> BroadcastConsumer:
+        return BroadcastConsumer(self._inner.broadcast())
+
+
+class Announced:
+    """Wraps MoqAnnounced as an async iterator of Announcement."""
+
+    def __init__(self, inner: MoqAnnounced) -> None:
+        self._inner = inner
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *exc) -> None:
+        self.cancel()
+
+    def __aiter__(self):
+        return self
+
+    async def __anext__(self) -> Announcement:
+        result = await self._inner.next()
+        if result is None:
+            raise StopAsyncIteration
+        return Announcement(result)
+
+    def cancel(self) -> None:
+        self._inner.cancel()
+
+
+class AnnouncedBroadcast:
+    """Wraps MoqAnnouncedBroadcast — awaitable for a specific broadcast."""
+
+    def __init__(self, inner: MoqAnnouncedBroadcast) -> None:
+        self._inner = inner
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *exc) -> None:
+        self.cancel()
+
+    async def available(self) -> BroadcastConsumer:
+        return BroadcastConsumer(await self._inner.available())
+
+    def __await__(self):
+        return self.available().__await__()
+
+    def cancel(self) -> None:
+        self._inner.cancel()
+
+
+class OriginConsumer:
+    """Wraps MoqOriginConsumer for discovering broadcasts."""
+
+    def __init__(self, inner: MoqOriginConsumer) -> None:
+        self._inner = inner
+
+    def announced(self, prefix: str = "") -> Announced:
+        return Announced(self._inner.announced(prefix))
+
+    def announced_broadcast(self, path: str) -> AnnouncedBroadcast:
+        return AnnouncedBroadcast(self._inner.announced_broadcast(path))
+
+
+class OriginProducer:
+    """Wraps MoqOriginProducer for publishing broadcasts."""
+
+    def __init__(self) -> None:
+        self._inner = MoqOriginProducer()
+
+    def consume(self) -> OriginConsumer:
+        return OriginConsumer(self._inner.consume())
+
+    def publish(self, path: str, broadcast: BroadcastProducer) -> None:
+        self._inner.publish(path, broadcast._inner)

moq/publish.py

@@ -0,0 +1,187 @@
+"""Producer wrappers — publish broadcasts and media tracks."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from moq_ffi import (
+    MoqAudioProducer,
+    MoqBroadcastProducer,
+    MoqGroupProducer,
+    MoqMediaProducer,
+    MoqMediaStreamProducer,
+    MoqTrackProducer,
+)
+
+from .types import AudioEncoderInput, AudioEncoderOutput, AudioFrame
+
+if TYPE_CHECKING:
+    from .subscribe import BroadcastConsumer, GroupConsumer, TrackConsumer
+
+
+class MediaProducer:
+    """Wraps MoqMediaProducer with a cleaner interface."""
+
+    def __init__(self, inner: MoqMediaProducer) -> None:
+        self._inner = inner
+
+    @property
+    def name(self) -> str:
+        """The generated media track name."""
+        return self._inner.name()
+
+    async def used(self) -> None:
+        """Wait until this media track has at least one active subscriber."""
+        await self._inner.used()
+
+    async def unused(self) -> None:
+        """Wait until this media track has no active subscribers."""
+        await self._inner.unused()
+
+    def write_frame(self, payload: bytes, timestamp_us: int) -> None:
+        self._inner.write_frame(payload, timestamp_us)
+
+    def finish(self) -> None:
+        self._inner.finish()
+
+
+class MediaStreamProducer:
+    """Wraps MoqMediaStreamProducer — feed a raw byte stream (e.g. Annex-B
+    H.264) and let the importer infer frame boundaries.
+
+    Built via :meth:`BroadcastProducer.publish_media_stream`. Unlike
+    :class:`MediaProducer`, no per-frame timestamps are needed; just push
+    encoder bytes as they arrive.
+    """
+
+    def __init__(self, inner: MoqMediaStreamProducer) -> None:
+        self._inner = inner
+
+    def write(self, payload: bytes) -> None:
+        """Push raw stream bytes; whole frames are emitted as they complete."""
+        self._inner.write(payload)
+
+    def finish(self) -> None:
+        self._inner.finish()
+
+
+class GroupProducer:
+    """Writes frames into a single group on a track."""
+
+    def __init__(self, inner: MoqGroupProducer) -> None:
+        self._inner = inner
+
+    @property
+    def sequence(self) -> int:
+        """The sequence number of this group within the track."""
+        return self._inner.sequence()
+
+    def consume(self) -> GroupConsumer:
+        """Create a consumer that reads frames from this group."""
+        from .subscribe import GroupConsumer
+
+        return GroupConsumer(self._inner.consume())
+
+    def write_frame(self, payload: bytes) -> None:
+        self._inner.write_frame(payload)
+
+    def finish(self) -> None:
+        self._inner.finish()
+
+
+class TrackProducer:
+    """Track producer — write arbitrary byte payloads with no codec required.
+
+    Same pattern as moq-boy's status/command tracks.
+    """
+
+    def __init__(self, inner: MoqTrackProducer) -> None:
+        self._inner = inner
+
+    @property
+    def name(self) -> str:
+        """The track name."""
+        return self._inner.name()
+
+    async def used(self) -> None:
+        """Wait until this track has at least one active subscriber."""
+        await self._inner.used()
+
+    async def unused(self) -> None:
+        """Wait until this track has no active subscribers."""
+        await self._inner.unused()
+
+    def append_group(self) -> GroupProducer:
+        """Start a new group; write frames into it, then finish()."""
+        return GroupProducer(self._inner.append_group())
+
+    def write_frame(self, payload: bytes) -> None:
+        """Convenience: write a single-frame group in one call."""
+        self._inner.write_frame(payload)
+
+    def consume(self) -> TrackConsumer:
+        """Create a consumer that reads directly from this producer's track."""
+        from .subscribe import TrackConsumer
+
+        return TrackConsumer(self._inner.consume())
+
+    def finish(self) -> None:
+        self._inner.finish()
+
+
+class AudioProducer:
+    """Publish raw PCM and let libopus encode it on the way out.
+
+    Built via :meth:`BroadcastProducer.publish_audio`. PCM layout
+    (format / sample rate / channels / bitrate / frame duration) is
+    fixed at construction; each :meth:`write` call passes only bytes
+    and a presentation timestamp.
+    """
+
+    def __init__(self, inner: MoqAudioProducer) -> None:
+        self._inner = inner
+
+    def write(self, frame: AudioFrame) -> None:
+        """Push one frame of PCM in the configured input format."""
+        self._inner.write(frame)
+
+    def finish(self) -> None:
+        """Flush any pending samples and finalize the track."""
+        self._inner.finish()
+
+
+class BroadcastProducer:
+    """Wraps MoqBroadcastProducer with a cleaner interface."""
+
+    def __init__(self) -> None:
+        self._inner = MoqBroadcastProducer()
+
+    def publish_media(self, format: str, init: bytes) -> MediaProducer:
+        return MediaProducer(self._inner.publish_media(format, init))
+
+    def publish_media_stream(self, format: str) -> MediaStreamProducer:
+        """Publish a media track fed by a raw byte stream (unknown frame
+        boundaries). `format` is a stream format (avc3, hev1, av01, fmp4, mkv)."""
+        return MediaStreamProducer(self._inner.publish_media_stream(format))
+
+    def publish_audio(
+        self,
+        name: str,
+        input: AudioEncoderInput,
+        output: AudioEncoderOutput,
+    ) -> AudioProducer:
+        """Publish a raw-audio track with an in-process Opus encoder."""
+        return AudioProducer(self._inner.publish_audio(name, input, output))
+
+    def publish_track(self, name: str) -> TrackProducer:
+        """Create a track — send any bytes, no codec validation."""
+        return TrackProducer(self._inner.publish_track(name))
+
+    def consume(self) -> BroadcastConsumer:
+        """Create a consumer that reads from this broadcast's tracks."""
+        from .subscribe import BroadcastConsumer
+
+        return BroadcastConsumer(self._inner.consume())
+
+    def finish(self) -> None:
+        self._inner.finish()

moq/server.py

@@ -0,0 +1,228 @@
+"""Server wrapper — accept incoming sessions with automatic origin wiring."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable, Sequence
+from typing import Literal
+
+from moq_ffi import MoqRequest, MoqServer, MoqSession
+
+from .origin import OriginProducer
+from .publish import BroadcastProducer
+
+Transport = Literal["quic", "iroh", "websocket"]
+
+
+class Request:
+    """Wraps MoqRequest — an incoming session that can be accepted or rejected.
+
+    Use `await request.ok()` to complete the handshake, or
+    `await request.close(code)` to reject with an HTTP status code.
+
+    Dropping a Request without responding closes the underlying connection
+    silently; call `close(code)` to send an explicit HTTP status.
+    """
+
+    def __init__(self, inner: MoqRequest) -> None:
+        self._inner = inner
+
+    @property
+    def url(self) -> str | None:
+        return self._inner.url()
+
+    @property
+    def transport(self) -> Transport:
+        return self._inner.transport()  # type: ignore[return-value]
+
+    def set_publish(self, origin: OriginProducer | None) -> None:
+        """Override the publish origin for this session. Falls back to the
+        server's configured publish origin if unset."""
+        self._inner.set_publish(origin._inner if origin is not None else None)
+
+    def set_consume(self, origin: OriginProducer | None) -> None:
+        """Override the consume origin for this session. Falls back to the
+        server's configured consume origin if unset."""
+        self._inner.set_consume(origin._inner if origin is not None else None)
+
+    async def ok(self) -> MoqSession:
+        """Complete the MoQ handshake and return the established session.
+
+        The caller must hold the returned session to keep the connection
+        alive; dropping it closes the session. Raises `MoqError.AlreadyResponded`
+        if `ok()` or `close()` has already been called.
+        """
+        return await self._inner.ok()
+
+    async def close(self, code: int = 404) -> None:
+        """Reject the session with the given HTTP status code.
+
+        Raises `MoqError.AlreadyResponded` if `ok()` or `close()` has already
+        been called.
+        """
+        await self._inner.close(code)
+
+    def cancel(self) -> None:
+        """Cancel an in-flight `ok()` or `close()` call."""
+        self._inner.cancel()
+
+
+class Server:
+    """High-level MoQ server with automatic origin wiring.
+
+    In simple mode (no origin provided), creates an internal origin automatically:
+
+        async with Server("127.0.0.1:4443", tls_generate=["localhost"]) as server:
+            server.publish("live", broadcast)
+            await server.serve()
+
+    Or hand-roll the accept loop if you need per-request control:
+
+        async with Server("127.0.0.1:4443", tls_generate=["localhost"]) as server:
+            async for request in server:
+                if request.url and "/admin" in request.url:
+                    await request.close(403)
+                    continue
+                session = await request.ok()  # hold to keep the connection alive
+
+    Exiting the context manager stops accepting new sessions but does not
+    close in-flight sessions; those stay alive until their handles are
+    dropped or `Session.cancel()` is called.
+
+    In advanced mode, provide your own origins for full control:
+
+        origin = OriginProducer()
+        server = Server(
+            "127.0.0.1:4443",
+            tls_generate=["localhost"],
+            publish=origin,
+            subscribe=origin,
+        )
+    """
+
+    def __init__(
+        self,
+        bind: str = "[::]:443",
+        *,
+        tls_cert: Sequence[str] = (),
+        tls_key: Sequence[str] = (),
+        tls_generate: Sequence[str] = (),
+        publish: OriginProducer | None = None,
+        subscribe: OriginProducer | None = None,
+    ) -> None:
+        self._bind = bind
+        self._tls_cert = list(tls_cert)
+        self._tls_key = list(tls_key)
+        self._tls_generate = list(tls_generate)
+
+        # If neither origin is provided, create a shared internal one.
+        if publish is None and subscribe is None:
+            self._origin: OriginProducer | None = OriginProducer()
+            self._publish_origin: OriginProducer | None = self._origin
+            self._consume_origin: OriginProducer | None = self._origin
+        else:
+            self._origin = None
+            self._publish_origin = publish
+            self._consume_origin = subscribe
+
+        self._inner: MoqServer | None = None
+        self._local_addr: str | None = None
+
+    async def __aenter__(self):
+        self._inner = MoqServer()
+        self._inner.set_bind(self._bind)
+        if self._tls_cert:
+            self._inner.set_tls_cert(self._tls_cert)
+        if self._tls_key:
+            self._inner.set_tls_key(self._tls_key)
+        if self._tls_generate:
+            self._inner.set_tls_generate(self._tls_generate)
+        if self._publish_origin is not None:
+            self._inner.set_publish(self._publish_origin._inner)
+        if self._consume_origin is not None:
+            self._inner.set_consume(self._consume_origin._inner)
+
+        self._local_addr = await self._inner.listen()
+        return self
+
+    async def __aexit__(self, *exc) -> None:
+        if self._inner is not None:
+            self._inner.cancel()
+            self._inner = None
+        self._local_addr = None
+
+    @property
+    def local_addr(self) -> str:
+        """The bound local address, available after entering the context manager."""
+        if self._local_addr is None:
+            raise RuntimeError("server not listening; use 'async with'")
+        return self._local_addr
+
+    def cert_fingerprints(self) -> list[str]:
+        """SHA-256 fingerprints of the configured TLS certificates, hex-encoded.
+
+        Useful for pinning a generated self-signed certificate in a browser
+        via WebTransport's `serverCertificateHashes`.
+        """
+        if self._inner is None:
+            raise RuntimeError("server not listening; use 'async with'")
+        return self._inner.cert_fingerprints()
+
+    def __aiter__(self):
+        return self
+
+    async def __anext__(self) -> Request:
+        if self._inner is None:
+            raise RuntimeError("server not listening; use 'async with'")
+        request = await self._inner.accept()
+        if request is None:
+            raise StopAsyncIteration
+        return Request(request)
+
+    def publish(self, path: str, broadcast: BroadcastProducer) -> None:
+        """Publish a broadcast under the given path, served to incoming sessions."""
+        origin = self._publish_origin
+        if origin is None:
+            raise RuntimeError("no publish origin configured")
+        origin.publish(path, broadcast)
+
+    async def serve(
+        self,
+        on_request: Callable[[Request], Awaitable[bool | None]] | None = None,
+    ) -> None:
+        """Accept sessions in a loop, holding each one alive until it closes.
+
+        Each session is handled by its own task that awaits `session.closed()`,
+        so memory does not grow with the number of past connections.
+
+        Pass `on_request` to inspect a `Request` before accepting it; return
+        `False` (or raise) to reject the request with HTTP 403, `True` (or
+        `None`) to accept. For richer routing, hand-roll the accept loop
+        instead.
+        """
+        session_tasks: set[asyncio.Task] = set()
+
+        async def serve_session(request: Request) -> None:
+            session = await request.ok()
+            await session.closed()
+
+        try:
+            async for request in self:
+                if on_request is not None:
+                    try:
+                        decision = await on_request(request)
+                    except Exception:
+                        await request.close(500)
+                        raise
+                    if decision is False:
+                        await request.close(403)
+                        continue
+                task = asyncio.create_task(serve_session(request))
+                session_tasks.add(task)
+                task.add_done_callback(session_tasks.discard)
+        finally:
+            # Cancel any session tasks still pending a handshake, but let
+            # established sessions wind down on their own.
+            for task in list(session_tasks):
+                if not task.done():
+                    task.cancel()

moq/subscribe.py

@@ -0,0 +1,195 @@
+"""Consumer wrappers — subscribe to broadcasts, catalogs, and media tracks."""
+
+from __future__ import annotations
+
+from moq_ffi import (
+    Container,
+    MoqAudioConsumer,
+    MoqBroadcastConsumer,
+    MoqCatalogConsumer,
+    MoqGroupConsumer,
+    MoqMediaConsumer,
+    MoqTrackConsumer,
+)
+
+from .types import Audio, AudioDecoderOutput, AudioFrame, Catalog, Frame
+
+
+class MediaConsumer:
+    """Wraps MoqMediaConsumer as an async iterator of Frame."""
+
+    def __init__(self, inner: MoqMediaConsumer) -> None:
+        self._inner = inner
+
+    def __aiter__(self):
+        return self
+
+    async def __anext__(self) -> Frame:
+        frame = await self._inner.next()
+        if frame is None:
+            raise StopAsyncIteration
+        return frame
+
+    def cancel(self) -> None:
+        self._inner.cancel()
+
+
+class GroupConsumer:
+    """Async iterator of byte payloads within a single group."""
+
+    def __init__(self, inner: MoqGroupConsumer) -> None:
+        self._inner = inner
+
+    @property
+    def sequence(self) -> int:
+        """The sequence number of this group within the track."""
+        return self._inner.sequence()
+
+    def __aiter__(self):
+        return self
+
+    async def __anext__(self) -> bytes:
+        frame = await self._inner.read_frame()
+        if frame is None:
+            raise StopAsyncIteration
+        return frame
+
+    def cancel(self) -> None:
+        self._inner.cancel()
+
+
+class TrackConsumer:
+    """Async iterator of groups from a track.
+
+    Each group is itself an async iterator of byte payloads. Same pattern as
+    moq-boy's status/command tracks (one frame per group), but multi-frame
+    groups are also supported.
+    """
+
+    def __init__(self, inner: MoqTrackConsumer) -> None:
+        self._inner = inner
+
+    def __aiter__(self):
+        return self
+
+    async def __anext__(self) -> GroupConsumer:
+        group = await self.recv_group()
+        if group is None:
+            raise StopAsyncIteration
+        return group
+
+    async def recv_group(self) -> GroupConsumer | None:
+        """Return the next group in arrival order. Returns `None` when the track ends.
+
+        Groups are returned as they arrive on the wire, which may be out of sequence
+        order. Use this for live consumption where latency matters more than order.
+        """
+        group = await self._inner.recv_group()
+        if group is None:
+            return None
+        return GroupConsumer(group)
+
+    async def next_group(self) -> GroupConsumer | None:
+        """Return the next group in sequence order, skipping forward if behind.
+
+        Returns `None` when the track ends. Use this when order matters more than
+        latency; `recv_group` is preferred for live consumption.
+        """
+        group = await self._inner.next_group()
+        if group is None:
+            return None
+        return GroupConsumer(group)
+
+    async def read_frame(self) -> bytes | None:
+        """Read the first frame of the next group.
+
+        Convenience for tracks using one-frame-per-group (like moq-boy's
+        status/command tracks). Returns `None` when the track ends.
+        """
+        return await self._inner.read_frame()
+
+    def cancel(self) -> None:
+        self._inner.cancel()
+
+
+class AudioConsumer:
+    """Async iterator of decoded audio frames.
+
+    Built via :meth:`BroadcastConsumer.subscribe_audio`. The PCM layout
+    is fixed by the :class:`AudioDecoderOutput` passed at subscribe
+    time; each frame's ``data`` is raw bytes in that format.
+    """
+
+    def __init__(self, inner: MoqAudioConsumer) -> None:
+        self._inner = inner
+
+    def __aiter__(self):
+        return self
+
+    async def __anext__(self) -> AudioFrame:
+        frame = await self._inner.next()
+        if frame is None:
+            raise StopAsyncIteration
+        return frame
+
+    def cancel(self) -> None:
+        self._inner.cancel()
+
+
+class CatalogConsumer:
+    """Wraps MoqCatalogConsumer as an async iterator of Catalog."""
+
+    def __init__(self, inner: MoqCatalogConsumer) -> None:
+        self._inner = inner
+
+    def __aiter__(self):
+        return self
+
+    async def __anext__(self) -> Catalog:
+        catalog = await self._inner.next()
+        if catalog is None:
+            raise StopAsyncIteration
+        return catalog
+
+    def cancel(self) -> None:
+        self._inner.cancel()
+
+
+class BroadcastConsumer:
+    """Wraps MoqBroadcastConsumer with convenience methods."""
+
+    def __init__(self, inner: MoqBroadcastConsumer) -> None:
+        self._inner = inner
+
+    def subscribe_catalog(self) -> CatalogConsumer:
+        return CatalogConsumer(self._inner.subscribe_catalog())
+
+    def subscribe_track(self, name: str) -> TrackConsumer:
+        """Subscribe to a track — receive arbitrary byte payloads."""
+        return TrackConsumer(self._inner.subscribe_track(name))
+
+    def subscribe_media(self, name: str, container: Container, max_latency_ms: int) -> MediaConsumer:
+        return MediaConsumer(self._inner.subscribe_media(name, container, max_latency_ms))
+
+    def subscribe_audio(
+        self,
+        name: str,
+        catalog_audio: Audio,
+        output: AudioDecoderOutput,
+    ) -> AudioConsumer:
+        """Subscribe to a raw-audio track; samples come back in the format
+        declared by ``output``.
+
+        ``catalog_audio`` comes from the catalog (e.g.
+        ``await broadcast.catalog()`` followed by
+        ``catalog.audio[name]``). Use ``output.latency_max_ms`` to
+        control how aggressively stalled groups get skipped — that's
+        the congestion-control knob. (Named ``_max`` to leave room for
+        a future ``latency_min_ms`` jitter-buffer floor.)
+        """
+        return AudioConsumer(self._inner.subscribe_audio(name, catalog_audio, output))
+
+    async def catalog(self) -> Catalog:
+        """Convenience: subscribe and return the first catalog."""
+        consumer = self.subscribe_catalog()
+        return await anext(consumer)

moq/types.py

@@ -0,0 +1,49 @@
+"""Re-export moq-ffi record types without the Moq prefix."""
+
+from moq_ffi import (
+    MoqAudio as Audio,
+)
+from moq_ffi import (
+    MoqAudioCodec as AudioCodec,
+)
+from moq_ffi import (
+    MoqAudioDecoderOutput as AudioDecoderOutput,
+)
+from moq_ffi import (
+    MoqAudioEncoderInput as AudioEncoderInput,
+)
+from moq_ffi import (
+    MoqAudioEncoderOutput as AudioEncoderOutput,
+)
+from moq_ffi import (
+    MoqAudioFormat as AudioFormat,
+)
+from moq_ffi import (
+    MoqAudioFrame as AudioFrame,
+)
+from moq_ffi import (
+    MoqCatalog as Catalog,
+)
+from moq_ffi import (
+    MoqDimensions as Dimensions,
+)
+from moq_ffi import (
+    MoqFrame as Frame,
+)
+from moq_ffi import (
+    MoqVideo as Video,
+)
+
+__all__ = [
+    "Audio",
+    "AudioCodec",
+    "AudioDecoderOutput",
+    "AudioEncoderInput",
+    "AudioEncoderOutput",
+    "AudioFormat",
+    "AudioFrame",
+    "Catalog",
+    "Dimensions",
+    "Frame",
+    "Video",
+]

moq_rs-0.3.0.dist-info/METADATA

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: moq-rs
+Version: 0.3.0
+Summary: Media over QUIC: real-time pub/sub with built-in caching, fan-out, and prioritization, with a Pythonic API. Import as `moq`.
+Project-URL: Homepage, https://github.com/moq-dev/moq
+Project-URL: Repository, https://github.com/moq-dev/moq
+Author-email: Luke Curley <kixelated@gmail.com>
+License-Expression: MIT OR Apache-2.0
+Keywords: http3,live,media,quic,streaming,webtransport
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: Multimedia :: Video
+Requires-Python: >=3.10
+Requires-Dist: moq-ffi~=0.2.16
+Description-Content-Type: text/markdown
+
+# moq
+
+Python bindings for [Media over QUIC](https://github.com/moq-dev/moq): real-time pub/sub with built-in caching, fan-out, and prioritization, on top of QUIC.
+
+`moq` wraps the auto-generated [`moq-ffi`](https://pypi.org/project/moq-ffi/) UniFFI bindings with a Pythonic API: no `Moq` prefixes, async iterators, context managers, and simplified connection setup. At session setup it negotiates either the `moq-lite` or `moq-transport` wire protocol.
+
+## Installation
+
+```bash
+pip install moq
+```
+
+This pulls in the `moq-ffi` native bindings automatically. `moq` is pure Python and is versioned independently of `moq-ffi`; it floats to the latest compatible `moq-ffi` patch.
+
+## Quick Start
+
+### Subscribe to a stream
+
+```python
+import asyncio
+import moq
+
+async def main():
+    async with moq.Client("https://relay.quic.video") as client:
+        async for announcement in client.announced():
+            catalog = await announcement.broadcast.catalog()
+
+            for name in catalog.audio:
+                async for frame in announcement.broadcast.subscribe_media(name):
+                    print(f"Got frame: {len(frame.payload)} bytes, ts={frame.timestamp_us}")
+
+asyncio.run(main())
+```
+
+### Publish a stream
+
+```python
+import asyncio
+import moq
+
+async def main():
+    async with moq.Client("https://relay.quic.video") as client:
+        broadcast = moq.BroadcastProducer()
+
+        # Publish an Opus audio track (init bytes from your encoder)
+        audio = broadcast.publish_media("opus", opus_init_bytes)
+        client.publish("my-stream", broadcast)
+
+        # Write frames
+        audio.write_frame(payload, timestamp_us=0)
+        audio.write_frame(payload, timestamp_us=20000)
+
+        # Clean up
+        audio.finish()
+        broadcast.finish()
+
+asyncio.run(main())
+```
+
+### Host a server
+
+```python
+import asyncio
+import moq
+
+async def main():
+    async with moq.Server("127.0.0.1:4443", tls_generate=["localhost"]) as server:
+        broadcast = moq.BroadcastProducer()
+        track = broadcast.publish_track("events")
+        server.publish("hello", broadcast)
+        print(f"listening on https://{server.local_addr}")
+
+        sessions = []
+        async for request in server:
+            print(f"  + {request.transport} from {request.url}")
+            sessions.append(await request.ok())
+
+asyncio.run(main())
+```
+
+Reject a request instead of accepting it with `await request.close(403)`.
+
+### Advanced: Manual origin wiring
+
+For full control over the origin topology:
+
+```python
+import moq
+
+origin = moq.OriginProducer()
+client = moq.Client(
+    "https://relay.quic.video",
+    publish=origin,
+    subscribe=origin,
+)
+```
+
+## API
+
+### Connection
+
+- **`Client(url, *, tls_verify=True, bind=None, publish=None, subscribe=None)`**. Async context manager for connecting to a relay.
+- **`Server(bind="[::]:443", *, tls_cert=(), tls_key=(), tls_generate=(), publish=None, subscribe=None)`**. Async context manager + async iterator of incoming `Request`s.
+  - `.local_addr`. The bound address (useful when binding to port `0`).
+  - `.cert_fingerprints()`. SHA-256 fingerprints of the configured TLS certificates, for `serverCertificateHashes` browser cert pinning.
+  - `.publish(path, broadcast)`. Publish a broadcast to be served.
+- **`Request`**. An incoming session, yielded by `async for request in server`.
+  - `.url`, `.transport`. Properties.
+  - `.set_publish(origin)`, `.set_consume(origin)`. Per-request overrides.
+  - `await .ok()`. Complete the handshake, returns a session (hold it to keep the connection alive).
+  - `await .close(code)`. Reject with an HTTP status code.
+  - `.cancel()`. Cancel an in-flight `ok()`/`close()` call.
+
+### Publishing
+
+- **`BroadcastProducer()`**. Create a broadcast to publish tracks into.
+  - `.publish_media(format, init) → MediaProducer`
+  - `.finish()`
+- **`MediaProducer`**. Write frames to a track.
+  - `.write_frame(payload, timestamp_us)`
+  - `.finish()`
+
+### Subscribing
+
+- **`BroadcastConsumer`**. Subscribe to tracks within a broadcast.
+  - `.subscribe_catalog() → CatalogConsumer`
+  - `.subscribe_media(name, max_latency_ms=10000) → MediaConsumer`
+  - `await .catalog() → Catalog` (convenience)
+- **`CatalogConsumer`**. Async iterator of `Catalog`.
+- **`MediaConsumer`**. Async iterator of `Frame`.
+
+### Origin (advanced)
+
+- **`OriginProducer()`**. Manage broadcast announcements.
+  - `.consume() → OriginConsumer`
+  - `.publish(path, broadcast)`
+- **`OriginConsumer`**. Discover broadcasts.
+  - `.announced(prefix) → Announced` (async iterator)
+  - `.announced_broadcast(path) → AnnouncedBroadcast` (awaitable)
+
+### Types
+
+- **`Catalog`**. `.audio: dict[str, Audio]`, `.video: dict[str, Video]`, `.display`, `.rotation`, `.flip`.
+- **`Frame`**. `.payload: bytes`, `.timestamp_us: int`, `.keyframe: bool`.
+- **`Audio`**. `.codec`, `.sample_rate`, `.channel_count`, `.bitrate`, `.description`.
+- **`Video`**. `.codec`, `.coded: Dimensions`, `.display_ratio`, `.bitrate`, `.framerate`, `.description`.
+- **`Dimensions`**. `.width: int`, `.height: int`.
+
+## See Also
+
+- [`moq-ffi`](https://pypi.org/project/moq-ffi/). The raw UniFFI bindings this package wraps. Use it directly only if you need the unwrapped `Moq`-prefixed API.
+- [MoQ project](https://github.com/moq-dev/moq). Full monorepo with Rust server, TypeScript browser lib, and more.

moq_rs-0.3.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+moq/__init__.py,sha256=Q0tqutMcHvQZPygRi-rT5YAEdNMlCiNHxlEgbDUBQ6c,1459
+moq/client.py,sha256=QrUwQAyNs9yxGGN3MzybIm6xfDZo_LAkUV5Zs1QEooI,3291
+moq/origin.py,sha256=8jXYhw6rpHoKoTR8t7YJngBu_smPtKs3b_rH_ZzgPec,2621
+moq/publish.py,sha256=ZGCWoGoEX1J-2OmzJTlu_tGNsgm-IOitx2bMM4C9ehM,5894
+moq/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+moq/server.py,sha256=NT07HT4IQFXVorcJQL_NdTlYwPztPnt_WKILxLDLVng,8421
+moq/subscribe.py,sha256=Jl2kw9YUKi0NvBduTS82glLYz5pPrkuCFl_gFGKbcUM,5939
+moq/types.py,sha256=o1K7iNY2spINxHlWPYKFEDXjnIxoAEyCQ4QMNyZ9kzI,920
+moq_rs-0.3.0.dist-info/METADATA,sha256=D_I7yZhcQ0hLta5nQv4-4hyiOSsyrhaf2nlVRL_nVa0,6088
+moq_rs-0.3.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+moq_rs-0.3.0.dist-info/RECORD,,

moq_rs-0.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any