every.channel/evolution/proposals/ECP-0063-cloudflare-moq-webtransport.md

ECP-0063: Cloudflare MoQ Relay + WebTransport-Only Web Watch

Status: Implemented

Decision

Adopt Cloudflare's MoQ relay preview as the default "global" distribution layer and make the web watcher path WebTransport-only.

Concrete changes:

1. ec-node gains a WebTransport MoQ publisher path that can publish a live CMAF (fMP4) stream to a relay URL (default: https://cdn.moq.dev/anon).
2. every.channel (the deployed static site) becomes a real web watcher by embedding a WebTransport-capable MoQ player component (<moq-watch> from @moq/watch).
3. The existing WebRTC/WS bootstrap directory/relay remains temporarily for compatibility, but is treated as deprecated once MoQ/WebTransport is stable.

Motivation

The project goal is one-to-many live streaming at global scale without rebuilding a bespoke stateful SFU stack.

MoQ over WebTransport moves the core system boundary to:

• publisher produces timed objects (CMAF fragments),
• relays cache/fanout,
• subscribers fetch via a single WebTransport session.

This aligns the "global watcher" story with an infrastructure-native model rather than point-to-point rendezvous.

Scope

In scope for this ECP:

• "Watch from the web" using WebTransport to a MoQ relay.
• "Publish from a node" to the relay, using ffmpeg to create fMP4 fragments.
• A shareable link format for every.channel to open a specific relay + broadcast name.

Out of scope (explicitly deferred):

• Global discovery/index of broadcasts.
• Manifest signing / Merkle availability / anti-junk (separate ECPs already exist).
• Safari support guarantees (implement anyway; provide guidance/flag notes).
• Multi-variant ladders and ABR (follow-on ECP once single-variant publish/watch works end-to-end).

Technical Notes

Relay default

Default relay endpoint is:

• https://cdn.moq.dev/anon

Nodes may override via CLI flags for self-hosted relays or future Cloudflare relay endpoints. As of February 21, 2026, browser sessions against https://interop-relay.cloudflare.mediaoverquic.com/ are observed to stall/fail during MoQ session establishment with current web clients, while https://cdn.moq.dev/anon establishes browser sessions in Chrome.

Web player

Use the @moq/watch web component:

• <moq-watch url="..." path="...">

This is WebTransport + WebCodecs based, and is expected to interoperate with Cloudflare's current relay preview.

CMAF passthrough default

ec-node wt-publish defaults --passthrough=false (and Nix module default passthrough = false).

Reason:

• Browser @moq/watch playback against live OTA ingest currently hits repeated Invalid sample duration 0 in trun decode failures when fed raw passthrough fMP4 fragments.
• Non-passthrough mode avoids this incompatibility and restores end-to-end playback reliability.

Transport compatibility

Cloudflare's public relay currently implements a subset of the IETF MoQ Transport draft-07 and may not interoperate with newer draft implementations.

Implementation choice:

• Cloudflare's relay preview currently does not support ANNOUNCE (namespace-style publishing). ec-node wt-publish uses the moq-lite publish model via quinn + web-transport-quinn + moq-lite and moq-mux (fMP4 ingestion) for Cloudflare relay compatibility.
• ec-node wt-publish is QUIC/WebTransport-only (no WebSocket fallback). NixOS deployments also set MOQ_CLIENT_WEBSOCKET_ENABLED=false as a belt-and-suspenders default for any other binaries that use moq-native.
• For Cloudflare relay interop, we patch web-transport-proto to send and accept the standard WebTransport subprotocol negotiation header (sec-webtransport-protocol) in addition to the legacy wt-available-protocols/wt-protocol headers. Without subprotocol negotiation, the relay may not select a moqt-* protocol and can close the session immediately after MoQ SETUP.
• If the relay does not select a WebTransport subprotocol, ec-node wt-publish attempts MoQ SETUP with protocol overrides (moqt-16, moqt-15, moq-00) before falling back to "no protocol".

Share link

Web share link:

• https://every.channel/watch?url=<relay-url>&name=<broadcast-name>

Alternatives considered

• Keep the legacy WebRTC/WS path as primary. Rejected because it does not align with relay-native MoQ fanout goals.
• Wait for full draft parity across all relays before shipping. Rejected because live interop was already sufficient on the chosen relay path.

Rollout / Reversibility

• Keep existing /api/* bootstrap endpoints during migration.
• Make the web site prefer MoQ/WebTransport; keep legacy paths hidden behind "advanced" until removed.
• Reversible by switching the deployed assets back to the previous UI build, and/or pointing users at the legacy paths.