Skip to main content

caprid-relay

The Relay Python SDK. connect_relay_subscriber subscribes to track objects and connect_relay_publisher publishes them, through Relay, Mux's Media over QUIC (MoQ) relay service. Payloads are bytes the SDK does not interpret. You need no browser, player, or media catalog.

Requirements

  • Python 3.11 or later, and asyncio.
  • Network access to the relay over QUIC on UDP. The default transport is native QUIC (MOQT directly on QUIC) through aioquic, which installs as a dependency. To use another transport, pass create_transport.
  • A Relay endpoint and a short-lived Relay JWT authorized for the namespace you use. The SDK uses tokens but does not issue them.

Install

uv add caprid-relay

pip install caprid-relay works too. It installs caprid-moq-core as a dependency. For media publishing and reading, add caprid-moq-media.

Publish and subscribe

import asyncio

from caprid_relay import (
    MoqtObject,
    RelaySubscriptionHandlers,
    connect_relay_publisher,
    connect_relay_subscriber,
    read_text,
    room_endpoint,
)


async def main(token: str) -> None:
    url = room_endpoint(["team"])  # your token's root as the path
    namespace = ["quickstart", "unique-run"]  # relative to that root
    arrived: asyncio.Future[str] = asyncio.get_running_loop().create_future()

    def on_object(obj: MoqtObject) -> None:
        if obj.status == "normal" and not arrived.done():
            arrived.set_result(read_text(obj))

    async with (
        await connect_relay_publisher(url, namespace=namespace, get_token=lambda: token) as publisher,
        await connect_relay_subscriber(url, get_token=lambda: token) as subscriber,
    ):
        ticker = publisher.register_track("ticker")
        await publisher.announced
        subscription = subscriber.subscribe(namespace, "ticker", RelaySubscriptionHandlers(on_object=on_object))
        await subscription.subscribed  # a fresh namespace can briefly reject this with error 16; retry it
        await ticker.write_text("hello from caprid-relay")  # waits for the subscriber's demand
        print(await arrived)

The guide's full demo runs the complete version of this, with credential handling, the subscribe retry, a deadline, and cleanup on failure.

Stability

Before 1.0, a minor version can break the API, and CHANGELOG.md says what changed. caprid-relay, caprid-moq-core, and caprid-moq-media always release together at the same version, and caprid-relay pins caprid-moq-core exactly. A release supports Python 3.11 or later, and MOQT draft 22 (moqt-22) with draft 20 (moqt-20) as an offered fallback, against moq-relay 0.15.4 or later.

Documentation

  • Python guide: the quickstart, subscription and publishing lifecycles, async consumption, supervised connections, the aioquic transport, and the media examples.
  • API reference: in a checkout of the repository, run mise run python:docs to build it from the source.
  • Errors and recovery: stable RelayError.code and phase values, the exception subclasses, preserved transport causes, and how to recover without assuming delivery or a safe replay.
  • Shared specification: the protocol pins, behavior contract, and test vectors every Relay SDK implements.

Metadata

Release files for caprid-relay 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for caprid-relay 0.2.0
File Size Uploaded Provenance Actions
caprid_relay-0.2.0.tar.gz 127.1 kB With provenance Details for caprid_relay-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for caprid-relay 0.2.0
File Interpreter ABI Platform Actions
caprid_relay-0.2.0-py3-none-any.whl Python 3 none any Details for caprid_relay-0.2.0-py3-none-any.whl

Total release size: 275.8 kB

Release files / caprid_relay-0.2.0.tar.gz

Download URL caprid_relay-0.2.0.tar.gz
Size 127.1 kB
Tags Source
SHA-256 checksum
How to use checksums
a01b8b68a1673d8e4f927ff4d57c72fcf3e792c47a923d9e30d76c452aa67c2a
BLAKE2b-256 checksum
How to use checksums
213fac6a66a17f253ca1fcbcc3d769d4b3a733f1696a81f13418aad4ff67f9a1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 28, 2026.

Transparency log

Release files / caprid_relay-0.2.0-py3-none-any.whl

Download URL caprid_relay-0.2.0-py3-none-any.whl
Size 148.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e7897db8c3a8af54f44f71d48f7a792c0007b2199ef80c80615973b211cfbba8
BLAKE2b-256 checksum
How to use checksums
cf8a6f5793ceef4092f27af4f994a036bef18efc9770c4ece4d4e7c791f93e07
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 28, 2026.

Transparency log

Security for caprid-relay 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for caprid_relay-0.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 28, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page