> ## Documentation Index
> Fetch the complete documentation index at: https://daily-ms-ws-body-url-encode.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://quic.video), 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](#reconnect-and-errors)).

<CardGroup cols={2}>
  <Card title="Example Implementation" icon="play" href="https://github.com/pipecat-ai/pipecat/blob/main/examples/transports/transports-moq.py">
    Runnable bot covering both modes
  </Card>

  <Card title="Media over QUIC" icon="book" href="https://quic.video">
    The protocol and its reference relay
  </Card>
</CardGroup>

## Installation

```bash theme={null}
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.

```bash theme={null}
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:

```bash theme={null}
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.

<Warning>
  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.
</Warning>

## 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

<ParamField path="params" type="MOQParams" required>
  Transport configuration. See [MOQParams](#moqparams) below.
</ParamField>

<ParamField path="host" type="str" default="localhost">
  Host used to compose the relay URL when `params.relay_url` is unset.
</ParamField>

<ParamField path="port" type="int" default="4080">
  Port used to compose the relay URL, and the serve-mode listen port when
  `params.bind` is unset.
</ParamField>

<ParamField path="path" type="str" default="/moq">
  Path used to compose the relay URL.
</ParamField>

<ParamField path="input_name" type="str | None" default="None">
  Optional name for the input transport processor.
</ParamField>

<ParamField path="output_name" type="str | None" default="None">
  Optional name for the output transport processor.
</ParamField>

### MOQParams

Extends [`TransportParams`](/api-reference/server/services/transport/transport-params), 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 |

<Note>
  `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.
</Note>

**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 |

<Warning>
  `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.
</Warning>

## 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`](/pipecat/fundamentals/error-handling#deciding-what-the-pipeline-does) 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`](/api-reference/client/js/transports/moq) 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

```python theme={null}
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

```python theme={null}
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](/api-reference/server/utilities/runner/guide), `create_transport` builds this for you:

```python theme={null}
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:

```python theme={null}
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.