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

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

Status: Draft

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://relay.cloudflare.mediaoverquic.com/).
2. every.channel (the deployed static site) becomes a real web watcher by embedding a WebTransport-capable MoQ player component (<hang-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://relay.cloudflare.mediaoverquic.com/

Nodes may override via CLI flags for self-hosted relays or future Cloudflare relay endpoints.

Web player

Use the @kixelated/hang web component:

• <hang-watch url="..." name="..." controls>

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

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 moq-native and moq-mux (fMP4 ingestion) for Cloudflare relay compatibility.
• On NixOS deployments, we disable moq-native's WebSocket fallback (MOQ_CLIENT_WEBSOCKET_ENABLED=false) to ensure WebTransport (QUIC) is used. This avoids the WebSocket path occasionally "winning" the race and then failing MoQ negotiation against the Cloudflare relay, causing rapid reconnect loops.
• 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.

Share link

Web share link:

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

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.