Media over QUIC Transport

Real-time audio over Media over QUIC with MOQTransport and MOQParams: serve mode, relay client mode with reconnect, and TLS.

Overview

MOQTransport carries a session over Media over QUIC, moving audio and RTVI messages over QUIC instead of a WebRTC stack. It runs in two modes:

• Serve mode (the default) — the bot binds its own UDP socket and the browser dials it. No relay process to run, and a self-signed certificate is minted for local development.
• Client mode — the bot and the browser both dial a relay and rendezvous there. Neither side needs a reachable address, so this works when the bot is behind NAT. A dropped relay session is redialed rather than treated as the end of the call (see Reconnect and errors).

Example Implementation

Runnable bot covering both modes

Media over QUIC

The protocol and its reference relay

Installation

uv add "pipecat-ai[moq]"

Serve mode vs client mode

Serve mode is the shorter path for local development: nothing to run besides the bot.

python bot.py -t moq

The bot listens on [::]:4080, mints a self-signed certificate for localhost, and publishes its SHA-256 fingerprint so the browser can pin it.

Client mode is selected by naming a relay:

python bot.py -t moq --moq-connect https://cdn.moq.dev/anon

Both peers dial the relay, so neither needs to be reachable from the other.

Each client-mode session gets its own random namespace, and on an anonymous relay that namespace is the session’s only access control — anyone who knows it can subscribe. Pass --moq-namespace to pin a well-known room only when the relay itself restricts who may join.

Broadcast paths

Each side publishes on one path and subscribes to the other’s. By default they’re composed from the namespace and the two participant ids, which are named by direction:

bot publishes   <namespace>/<participant_id>   default: pipecat/response
bot subscribes  <namespace>/<peer_id>          default: pipecat/request

Set response_path and request_path to bypass the namespace entirely and give the paths directly. That suits a deployment where the paths are assigned externally — a host running one bot per caller, naming both paths after an id the caller minted, with no namespace for the two sides to agree on beforehand. Either can be set alone; the other still derives from the namespace.

Configuration

MOQTransport

params · MOQParams · required

Transport configuration. See MOQParams below.

host · str · default: "localhost"

Host used to compose the relay URL when params.relay_url is unset.

port · int · default: "4080"

Port used to compose the relay URL, and the serve-mode listen port when params.bind is unset.

path · str · default: "/moq"

Path used to compose the relay URL.

input_name · str | None · default: "None"

Optional name for the input transport processor.

output_name · str | None · default: "None"

Optional name for the output transport processor.

MOQParams

Extends TransportParams, so the standard audio, VAD, and turn-analyzer options apply too.

Connection

Parameter	Type	Default	Description
relay_url	str | None	None	Full relay URL, dialed as given, query string included, so a relay token such as ?jwt=… rides along. When unset, composed from the constructor’s host/port/path. Ignored in serve mode
serve	bool	False	Bind a local UDP socket and accept sessions instead of dialing a relay
bind	str | None	None	Serve mode: the listen address, defaulting to [::]:<port>. Client mode: the source address to dial from
connection_timeout	float	60.0	How long the peer may be missing: the wait for it to join, and in client mode an outage, counted from the session dropping until the peer’s data flows again, across every redial

Paths

Parameter	Type	Default	Description
namespace	str	"pipecat"	Top-level namespace shared by both participants
participant_id	str	"response"	The bot’s id; it publishes under <namespace>/<participant_id>
peer_id	str	"request"	The peer’s id; the bot subscribes to <namespace>/<peer_id>
response_path	str | None	None	Full path the bot publishes on, bypassing the namespace
request_path	str | None	None	Full path the bot subscribes to, bypassing the namespace
audio_out_track	str	"bot-audio"	Name of the bot’s outgoing audio track
transcript_track	str	"transcript.json.z"	Name of the JSON stream track carrying RTVI messages

Client-side TLS (client mode only)

Parameter	Type	Default	Description
verify_ssl	bool	True	Verify the relay’s certificate
client_tls_cert	str | None	None	PEM client certificate chain to present, for a relay using mTLS
client_tls_key	str | None	None	PEM private key matching client_tls_cert. Both must be set
client_tls_roots	list[str] | None	None	Extra PEM CA certificates to trust, for a relay behind a private CA
client_tls_fingerprints	list[str] | None	None	SHA-256 fingerprints to accept, pinning one specific certificate

client_tls_roots and client_tls_fingerprints are alternatives to turning verify_ssl off, not companions to it. Reach for them when a relay uses a private CA or a self-signed certificate, and leave verification on.

Serve-side TLS (serve mode only)

Parameter	Type	Default	Description
serve_tls_host	str	"localhost"	Hostname in the generated self-signed certificate
serve_tls_cert	str | None	None	PEM certificate chain. Unset alongside the key, one is generated
serve_tls_key	str | None	None	PEM private key matching serve_tls_cert

Audio

Parameter	Type	Default	Description
audio_out_sample_rate	int	24000	Rate the bot publishes at; audio is resampled to the nearest Opus rate
audio_in_sample_rate	int	16000	Rate decoded audio is resampled to before going downstream
audio_in_max_latency_ms	int	500	How long to wait for a late frame before skipping ahead
audio_out_frame_ms	int	20	Outgoing frame duration. One of 2, 5, 10, 20, 40, 60
audio_out_max_buffer_ms	int	25000	Maximum outgoing buffer

serve_bind is deprecated since v1.8.0 and will be removed in 2.0.0. Use bind, which sets the listen address in serve mode and the source address in client mode.

Reconnect and errors

In client mode a dropped relay session is redialed rather than reported as the peer leaving. Each dial announces the bot’s broadcast afresh on the same path, with the transcript so far replayed into it, so the peer sees the same session return, and the transport retries with a delay that doubles from 0.5 s up to 2 s. connection_timeout bounds the whole outage: it counts from the session dropping until the peer’s data flows again, and a redial that succeeds does not restart it, because a relay keeps announcing a path whose route has died, so an announcement alone is not the peer being back. A relay that vanishes without closing the session is noticed by a traffic-stall watchdog, well before QUIC’s idle timeout would report it. Only when the time is up does the transport fire on_client_disconnected for a peer it had seen, so the usual handler ends the call.

Each relay session is a connect and a disconnect of its own: on_connected fires for the first session and every redialed one, and on_disconnected when a session ends. A redial therefore shows up as a disconnect followed by a connect, so a bot ends the call from on_client_disconnected, which fires only once the peer is gone. Set connection_timeout longer than a load balancer in front of the relays takes to fail a dead one out, since until then redials can be pinned to the dead target.

Each side appends a session-ending marker to its transcript stream before it leaves. The peer’s tracks ending after that marker is a hangup, and the transport reports the client gone at once. Ending without it is also what a failed relay between the peers looks like, so the transport redials and gives the peer connection_timeout to appear on the new session, reporting it gone only if it does not. A client that closes without sending the marker, a tab killed outright for instance, is reported gone within connection_timeout of its broadcast disappearing.

A relay that refuses the token is not retried. The relay accepts the QUIC connection first and then closes the session as unauthorized, so a forged token fails on the first session and an expired one ends the call at its expiry, both without redials.

Failures reach the pipeline as an ErrorFrame from the input transport, in addition to the on_error event: a refused token carries an authentication or authorization category, and a relay that could not be reached within connection_timeout carries a connectivity category marked permanent. Either leaves the transport unable to do its job, and the pipeline worker’s processor_unusable_policy decides whether the pipeline ends. The default, CONTINUE, only logs, so a bot that should exit on a dead relay sets the policy to END or CANCEL, or acts on on_error itself.

Transcript records

Each transcript track is a single group that a subscriber reads from its first record, so a reconnect on either side replays the whole log. Every record the transport writes is the RTVI message plus two fields: seq, the record’s position in the log, counting across reconnects, and epoch, an opaque string identifying this transport instance. On subscribe the transport drops records at or below the last seq it accepted for the current epoch, treats a different epoch as a new peer whose count starts over, and strips both fields before the message enters the pipeline. A record without seq is delivered unchanged, so a client that predates the fields keeps working.

@pipecat-ai/moq-transport implements the same format. Another client on this stream should too; otherwise a reconnect redelivers client-ready and the bot greets again.

Properties

cert_fingerprints

transport.cert_fingerprints -> list[str]

SHA-256 fingerprints of the certificate the bot serves, as hex. In serve mode the browser pins one of these to accept a self-signed certificate.

Usage

from pipecat.transports.moq.transport import MOQTransport, MOQParams

transport = MOQTransport(
    params=MOQParams(
        audio_in_enabled=True,
        audio_out_enabled=True,
        namespace="my-room",
    ),
    host="localhost",
    port=4080,
)

@transport.event_handler("on_client_connected")
async def on_client_connected(transport):
    await worker.queue_frames([context_aggregator.user().get_context_frame()])

@transport.event_handler("on_client_disconnected")
async def on_client_disconnected(transport):
    # In client mode the transport redials, so end the call here
    await runner.cancel()

With the development runner, create_transport builds this for you:

transport_params = {
    "moq": lambda: MOQParams(audio_in_enabled=True, audio_out_enabled=True),
}

MOQRunnerArguments takes either a host and port to compose the relay URL from, or a full relay_url, query string included, which create_transport passes through unchanged. A host that hands the bot a relay URL with a token in it uses the second form:

from pipecat.runner.types import MOQRunnerArguments

args = MOQRunnerArguments(
    relay_url="https://relay.example.com/?jwt=…",
    namespace="pcc/session-id",
)

Runner options

Flag	Default	Description
--moq-connect URL	unset	Full relay URL to dial, query string included. Passing it selects client mode
--moq-bind ADDR:PORT	[::]:4080 in serve mode	Serve: listen address. Client: source address to dial from
--moq-serve	on when --moq-connect is absent	Force serve mode
--moq-namespace NAME	pipecat serving, random dialing	Pin a well-known room instead of a per-session namespace
--moq-bot-id ID	response	The bot publishes under <namespace>/<id>
--moq-client-id ID	request	The bot subscribes to <namespace>/<id>
--moq-tls-cert PEM	unset	Serve: certificate, with --moq-tls-key
--moq-tls-key PEM	unset	Key for --moq-tls-cert
--moq-tls-generate HOST	localhost when no TLS given	Generate a self-signed development certificate. Serve mode only
--moq-tls-insecure	False	Skip relay certificate verification. Development only

The /start response carries a moq block — relayUrl, certHash, serve, namespace, clientId, botId, and transcriptTrack — which is what the browser needs to join. The prebuilt client UI shipped with the runner extra speaks MoQ, so http://localhost:7860 can connect without any client code of your own.

Event Handlers

Event	Description
on_connected	A session with the relay is established, the first and every redialed one, or the serve-mode bind is up
on_disconnected	A session ended, or the transport stopped without ever having one. Client mode redials after it, so end the call from on_client_disconnected instead
on_client_connected	The peer’s broadcast was announced
on_client_disconnected	The peer is gone: it said goodbye, or it stayed missing for connection_timeout
on_track_subscribed	A remote track subscription succeeded
on_error	An error in the underlying transport. Receives the message and the exception; the pipeline also gets an ErrorFrame

Notes

• RTVI over MoQ: the transcript_track is a lossless, ordered JSON stream carrying RTVI messages in both directions, so MoQ is a full RTVI transport on par with Daily or WebSocket rather than an audio-only path.
• Audio: a single Opus track each way. The library resamples to the nearest Opus-supported rate before encoding, so audio_out_sample_rate doesn’t have to be one of them.
• Latency: audio_in_max_latency_ms trades interactivity against resilience — lower waits less for a late frame, at the cost of more drops on a poor network.