Skip to content
openmoqPublic

About

MOQ reference implementation of Media over QUIC Transport. Full stack from WebTransport to viewport: protocol core, LOC/CMAF decode paths, ABR, and a batteries-included player.

Resources

Stars

22 stars

Watchers

1 watching

Forks

Repository files navigation

Red5 Playa – Modular MOQ Player Framework for Scalable Real-Time Streaming

Pre-release. The API surface is under active development and may change between minor versions. Pin to exact versions in production.

Reference implementation of Media over QUIC Transport (MoQT) in TypeScript, with browser WebTransport and experimental native QUIC support for Node.js.

Full stack from transport to viewport, published under one npm scope so you pick the integration path that fits:

  • @openmoq/* — the reference-implementation building blocks: protocol core, playback, and browser adapters, composed however you need.
  • @openmoq/playa — the batteries-included, drop-in browser player built on @openmoq/*.

The previous @moqt/* names and @playa/player are retained as compatibility re-exports. Use the new names for new integrations; see package compatibility for migration details.


WebTransport scheduling

The adapter owns sendOrder: control streams use 1024, request streams use 512 (including draft-16 SUBSCRIBE_NAMESPACE), and subgroup, FETCH, Joining FETCH and draft-22 fill streams use 255 − accepted subscriber priority. Assignments happen before the first byte, only when sendOrder is present (including inherited properties), and replace any provider-assigned value. Probe or setter failures are advisory; sendGroup is untouched. onSchedulingWarning reports the first failed hint per stream. Accepted priority changes re-rank open media streams, including pending FINs, before the acknowledgement is written. Refused updates leave ranks unchanged.

A fill's FillOptions.subscriberPriority overrides inheritance for that fill only. An omitted value is frozen at SUBSCRIBE_OK for an initial fill, or at acceptance of its carrying update, including that update's priority even if its ACK is deferred. Later subscription updates never re-rank the fill or retain its override.

This implements primary subscriber priority and the control/request bands from drafts 14/16/18 §7 and draft 22 §5.1. The SHOULD tie-breaks for publisher priority, group order (including draft-22 subscription-first when fill group order differs), and subgroup/object ID (including draft-22 fill-first) remain unimplemented. Datagram ordering and ordering within the request band are also unimplemented.

Quick Start

@openmoq/playa — Drop-in Player

import { Player } from '@openmoq/playa';

const player = new Player(document.getElementById('container')!, {
  url: 'https://relay.example.com/moq',
  namespace: 'live/broadcast',
});

await player.load();
player.play();

React / Custom DOM

const canvasRef = useRef<HTMLCanvasElement>(null);
const videoRef = useRef<HTMLVideoElement>(null);

const player = new Player(null, {
  url: 'https://relay.example.com/moq',
  namespace: 'live/broadcast',
  canvas: canvasRef.current!,   // WebCodecs path
  video: videoRef.current!,     // MSE/CMAF fallback path
});

await player.load();
player.play();

When elements are supplied directly the Player never touches the DOM — no appendChild, no hidden toggling, no style mutations.

@openmoq/player — Protocol-Level API

import { MoqtPlayer } from '@openmoq/player';
import { MoqtConnection } from '@openmoq/webtransport';
import {
  createWebTransport, WebCodecsVideoDecoder, CanvasRenderer,
  WebCodecsAudioDecoder, WebAudioOutput, MseMediaSource,
} from '@openmoq/browser';

// Run from a user gesture so browser audio can start.
const audioContext = new AudioContext();
await audioContext.resume();

const player = new MoqtPlayer({
  url: 'https://relay.example.com/moq',
  namespace: 'live/broadcast',
  draftVersion: 16,
  createTransport: createWebTransport({ draftVersion: 16 }),
  createConnection: () => new MoqtConnection(16),
  createVideoDecoder: () => new WebCodecsVideoDecoder(),
  createRenderer: () => new CanvasRenderer(canvas),
  createAudioDecoder: () => new WebCodecsAudioDecoder(),
  createAudioOutput: () => new WebAudioOutput(audioContext),
  createMediaSource: () => new MseMediaSource(video),
});

player.on('catalog_received', ({ catalog }) => { /* inspect tracks */ });
player.on('first_frame', () => { /* start your UI */ });
player.on('error', ({ error }) => { /* structured error with severity + code */ });

await player.load();
player.play();

canvas and video are application-owned elements. Close the application-owned AudioContext after await player.destroy() when playback is no longer needed.


Browser & Codec Support

Browser playback requires WebTransport in a secure context. The selected media path also needs these APIs:

Path Required browser APIs
LOC or LOCMAF frame mode WebCodecs (VideoDecoder / AudioDecoder for the selected tracks), Canvas, Web Audio
CMAF or LOCMAF MSE mode Media Source Extensions and an HTML video element

H.264, HEVC and AV1 decoding depends on the browser, OS, hardware and codec configuration. A browser version alone is not a codec-support guarantee. The WebCodecs adapter probes VideoDecoder.isConfigSupported(); MSE checks the selected codec's MIME type. Browser autoplay policy may require a user gesture to start audio. Player exposes audioActivation: 'gesture' and prepareAudio() / unmute() for application-controlled activation.

Decode paths:

  • LOC (Low Overhead Container) — WebCodecs direct path, lowest latency. H.264, HEVC, AV1. Parses LOC-05, LOC-04 and LOC-01 properties; preserves LOC-01 output unless locVersion: 4 or 5 is selected.
  • CMAF (fragmented MP4) — MSE + <video> path, broader compatibility.
  • LOCMAF (Low Overhead CMAF) - reconstructs CMAF chunks for MSE by default, or extracts coded samples for WebCodecs with locmafDecoding: 'frame' in MoqtPlayer config (moqtPlayerConfig on Player).

Package Structure

packages/
  transport/      @openmoq/transport     — Sans-I/O protocol core (draft-14 / -16 / -18 / -22 / -23)
  webtransport/   @openmoq/webtransport  — MoQT connection adapter and WebTransport binding
  quic/           @openmoq/quic          — Experimental native QUIC binding for Node.js (draft-18 / -22 / -23)
  loc/            @openmoq/loc           — Low Overhead Container (CaptureTimestamp, VideoFrameMarking)
  locmaf/         @openmoq/locmaf        - LOCMAF object encoding, CMAF reconstruction and coded-frame extraction
  msf/            @openmoq/msf           — MSF catalog parsing, track selection, timeline
  playback/       @openmoq/playback      — Jitter buffer, A/V sync, decoder state, gap detection
  player/         @openmoq/player        — Player orchestrator (connect, catalog, subscribe, decode, render)
  browser/        @openmoq/browser       — Browser adapters (WebCodecs, Canvas, WebAudio, MSE)
  playa/          @openmoq/playa         — Batteries-included player with simple API

Architecture

The playback core (@openmoq/playback) has no browser dependencies. It produces DecoderCommand and PlaybackEvent objects. Browser adapters (@openmoq/browser) consume these. This separation enables testing in Node.js without WebCodecs/Canvas/WebAudio.

WebTransport ──────────────────────────┐
                                       ├─► @openmoq/webtransport ──► @openmoq/transport ──► @openmoq/player ──► @openmoq/playback
Native QUIC via @openmoq/quic ────────────┘
                                                            │
                                              DecoderCommand│PlaybackEvent
                                                            ▼
                                               @openmoq/browser (browser)
                                          WebCodecs / Canvas / WebAudio / MSE

@openmoq/playa API

const player = new Player(container, options);

// Lifecycle
await player.load();        // connect, subscribe to catalog, subscribe to tracks
player.play();              // start rendering
player.pause();             // pause rendering
await player.seek(30_000);  // request a seek; see completion semantics below
await player.destroy();     // tear down connection and clean up

// State
player.state          // 'idle' | 'loading' | 'playing' | 'paused' | 'ended' | 'error'
player.currentTime    // ms; sampled on access, including hidden/no-RAF reads
player.duration       // known timeline duration in ms, otherwise undefined
player.seekable       // current timeline covers the selected media identities
player.volume         // 0–1
player.muted          // boolean
player.levels         // available video quality levels
player.videoGroups    // catalog video altGroups, each with its track metadata
player.audioTracks    // available audio tracks
player.currentAudioTrack // adopted audio index, or -1 while unknown
player.programs       // catalog render groups, with unassigned tracks kept separate
player.views          // views in the adopted program, including singleton tracks
player.currentProgram // stable id of the adopted program
player.currentView    // stable id of the adopted view
player.currentLevel   // active level index
player.activeMediaType  // 'canvas' | 'video' | null (before track selection)

// Quality (active level changes on qualitychange)
await player.setQuality(index);  // manual quality switch (disables ABR)
await player.setQuality('auto'); // re-enable ABR
player.levels;                   // available quality levels

// Audio (stable identity, resolves after adoption)
const spanish = player.audioTracks.find(track => track.language === 'es');
if (spanish?.id) await player.selectAudioTrack(spanish.id);
player.setAudioTrack(index);     // compatibility wrapper; handles rejection

// Events
player.on('ready',          ({ levels, audioTracks }) => console.log(levels, audioTracks));
player.on('timeupdate',     ({ currentTime }) => console.log(currentTime));
player.on('durationchange', ({ duration }) => console.log(duration));
player.on('seeking',        ({ targetTime }) => console.log(targetTime));
player.on('seeked',         ({ currentTime }) => console.log(currentTime));
player.on('qualitychange',  ({ level, auto }) => console.log(level, auto));
player.on('audiochange',    ({ track }) => console.log(track));
player.on('audiochangefailed', ({ trackId, message }) => console.warn(trackId, message));
player.on('programchange',  ({ program }) => console.log(program));
player.on('viewchange',     ({ view }) => console.log(view));
player.on('stall',          ({ durationMs }) => console.log(durationMs));
player.on('error',          ({ severity, code, message }) => console.error(severity, code, message));
player.on('statechange',    ({ state }) => console.log(state));

Register event listeners before load() to observe startup events. The lifecycle, state and event lines above illustrate separate API calls, not a playback script.

On the built-in MSE and frame paths, seek() resolves after admission of bounded historical retrieval, not after output lands. currentTime holds the admitted target until the owned output establishes its position, then samples that output without requiring a visible tab or animation tick. seeked reports that position: MSE uses actual native positioning and buffered coverage; frame playback uses producing video/audio timing. Neither proves a painted MSE frame or literal speaker output. LOC mapping is relative to the indexed sample; the MSF timestamp rounding limits nominal content precision to approximately 1 ms, not universal browser landing accuracy or capture-clock synchronization.

seekable describes timeline coverage; custom outputs must also supply owned seek capabilities (beginSeek for MSE, createFrameOutput for frame playback). Unsupported capabilities or unproven mappings refuse the request. The legacy fallback for other output configurations updates subscription filters in place and emits seeked optimistically, before output is proven. Historical frame quality selection is limited to paused, video-only draft-18/22 playback in the same declared alternate set, configuration, shape and common index; historical MSE quality requires matching codec and initialization. These limits do not expand ordinary live selection.

Options

Option Type Default Description
url string — WebTransport relay URL
namespace string — Track namespace (e.g. live/broadcast)
draftVersion 14 | 16 | 18 | 22 | 23 16 MOQT draft version
certHash ArrayBuffer — SHA-256 hash for self-signed certs
authorization credential provider — Opt-in CAT4MOQ token acquisition; see authorization
autoplay boolean false Start playback after load
volume number 1 Initial volume 0–1
muted boolean false Start muted
audioActivation 'auto' | 'gesture' 'auto' Defer Web Audio activation until a user gesture when set to 'gesture'
targetLatencyMs number — Live edge target latency
autoQuality boolean true Enable ABR
startLevel number | 'auto' | 'lowest' 'auto' Initial quality level
videoAltGroup number first video group Initial video view; quality and ABR stay within it
selection catalog selectors — Initial render group, alternate sets or exact namespace/name identities
audioLanguages readonly string[] catalog order Ordered language preferences within the selected program
maxResolution {width, height} — Cap video quality
canvas HTMLCanvasElement — Caller-owned canvas (framework mode)
video HTMLVideoElement — Caller-owned video element (framework mode)
moqtPlayerConfig Partial<MoqtPlayerConfig> — Advanced overrides, including locmafDecoding and catalogBootstrap

Video Views

A catalog can carry separate video views, such as landscape and portrait, in different altGroups. Set videoAltGroup on Player or MoqtPlayer to choose one at tune-in. Group 0 is valid; an unknown group fails rather than falling back to different content. Omission retains first-group selection.

const portrait = new Player(container, {
  url: relayUrl,
  namespace: 'live/stream',
  videoAltGroup: 0,
});
await portrait.load();
portrait.play();

levels and automatic quality selection only contain alternatives from that view. videoGroups (availableVideoGroups on MoqtPlayer) lists the catalog's supported video groups. Multiple players can select different groups independently. selectView(id, options) prepares another view on the existing session; selectProgram(id, options) prepares the program's required video and audio together. Readback and change events move only after adoption. A refused or incomplete target leaves the old selection playing. setQuality/selectVideoTrack remain quality switches within a view, not cross-view timeline mappings: different sets need not share timestamps or Group IDs.

For unrelated timelines, provide a correspondence established by the application. The anchors are raw presentation timestamps in microseconds, not Group IDs or the browser playhead. Both target outputs map into the same reference's domain:

const reference = player.mediaTimelineReference;
if (!reference) throw new Error('Wait for accepted source timing');
await player.selectProgram(nextProgram.id, {
  timeline: {
    kind: 'reference-map', referenceToken: reference.token,
    video: { sourceTimeUs: 90_000_000n, referenceTimeUs: 1_000_000_000n },
    audio: { sourceTimeUs: 900_000_000n, referenceTimeUs: 1_000_000_000n },
  },
});

Reading mediaTimelineReference enables source-time collection; it can remain null until subsequent accepted media supplies evidence. Its opaque token expires when the source, configuration or timeline changes. An explicit map establishes placement, not a promise that independently published content is synchronized. LOC program/view changes require the running decoder configuration. Generic MSE changes require the running initialization and an explicit presentation map; unsupported changes fail before adoption. Logical A/V selection is joint, but native decoder and device output is not an atomic splice.

The player example offers program, view and audio menus from the catalog. These choices start the selected presentation anew, using a fresh player rather than an inferred timeline mapping. Video quality changes stay within the current view. ?altGroup=0 selects the initial view; Stop cancels an in-progress retune. videoAltGroup cannot be combined with the catalog-free knownTracks fast path when video is enabled.

Audio selection

Audio menus carry stable id values and ordered namespace fields. The selected index changes after the target is accepted, initialized and has usable media. A refused target keeps the previous selection; failure to restore an output after reconfiguration is a fatal playback error. The legacy setAudioTrack(index) method returns immediately and reports failure through events; use selectAudioTrack(id) when the caller needs to await adoption or handle rejection. After the current request drains, switching also requires a current output position witness; adapters without one refuse the change and retain playback.

The default switch stays in the same declared audio alternate set. Independent sets need an explicit timeline relationship; equal Group IDs or timestamps do not establish one. Advanced callers can supply a reference-map with bigint microsecond anchors and the opaque token from audioTimelineReference. Reading that property arms source-time collection for the current load; it can remain null until subsequent accepted audio supplies evidence. Its timestamp is raw source metadata, not the output playhead. Tokens become invalid when their owner, configuration or clock changes. A custom adapter without timing evidence cannot supply a reference.

Explicit live-resync uses a current Web Audio graph position to place live replacement audio on the continuing schedule. It does not establish content alignment. Finite tracks, silent outputs and MSE adapters without an inverse source-time mapping are refused; the default setter never enables this policy.

audioLanguages tries preferences in order, preferring an exact tag and then regional variants in catalog order, with RFC 4647 singleton-aware fallback. This is the player's preference policy, rather than strict RFC 4647 Lookup. No match keeps the existing scope-local default. A successful explicit audio choice carries its language preference into later program selections, even if an intervening program lacks that language. Exact track pins stay local to the program. audioConstraints.lang is an exact startup filter and does not override a later viewer choice.


@openmoq/player MoqtPlayer API

// Hooks run synchronously: return the intent to proceed, or null to cancel.
player.hooks.beforeSubscribe.add((intent) => {
  if (shouldSkip(intent.trackName)) return null;
  return intent;
});

player.hooks.beforeQualitySwitch.add((intent) => {
  if (networkIsBad()) return null;
  return intent;
});

player.hooks.onRecovery.add((action) => {
  if (action.type === 'reduce_quality') return null;
  return action;
});

// Extension points
player.on('media_object', ({ mediaType, groupId, objectId, payload }) => console.log(mediaType, groupId, objectId, payload));
player.on('decoder_command', ({ command }) => console.log(command));
player.on('namespace_discovered', ({ namespaceSuffix }) => console.log(namespaceSuffix));
player.on('sap_event', ({ entries }) => console.log(entries));
player.on('catch_up_changed', ({ active, rate, latencyMs }) => console.log(active, rate, latencyMs));

shouldSkip and networkIsBad are application policy functions. Remove a hook with .remove(theSameFunction). MoqtPlayer errors carry a structured error object; the higher-level Player instead emits severity, code and message.

Key config options

Option Type Default Description
draftVersion 14 | 16 | 18 | 22 | 23 16 Protocol version; select the draft supported by your relay
maxRequestId number 10,000 Initial MOQT MAX_REQUEST_ID on legacy drafts (auto-replenished)
knownTracks object — Pre-known codec metadata for TTFF optimization
catalog {tracks} — Inject catalog externally, skip catalog subscription
targetLatencyMs number — Live catch-up target
liveJumpThresholdMs number 3000 Live LOC jumps toward received media after 1 s of excess above this threshold; 0 disables
maxCatchUpRate number 1.0 Max playback rate for catch-up
authority string — CLIENT_SETUP AUTHORITY for tenant-routed relays (interop override; spec prohibits it over WebTransport)
warmStartCurrentGroup boolean false Join live LOC/CMAF/LOCMAF tracks mid-group via Joining FETCH on drafts 14/16/18, or a fill on drafts 22/23; non-fatal if refused
catalogBootstrap 'auto' | 'joining-fetch' | 'strict' | 'subscribe' 'auto' Catalog bootstrap policy; drafts 22/23 use fills rather than Joining FETCH
locmafDecoding 'mse' | 'frame' 'mse' Reconstruct CMAF for MSE or decode LOCMAF samples through WebCodecs
authorization credential provider — Opt-in token acquisition for SETUP and authorized requests
objectTransform function — Per-object transform (e.g. decryption)
extensionParser function — Custom LOC extension parser
onQlogEvent function — qlog event stream
logLevel string 'none' Logging: 'none' | 'error' | 'warn' | 'info' | 'debug'

Protocol Support

  • draft-ietf-moq-transport-23 - opt-in (draftVersion: 23 / moqt-23)
  • draft-ietf-moq-transport-22 - opt-in (draftVersion: 22 / moqt-22)
  • draft-ietf-moq-transport-18 — uni control-stream pair + per-request bidi streams (draftVersion: 18 / moqt-18)
  • draft-ietf-moq-transport-16 — default supported transport draft
  • draft-ietf-moq-transport-14 — Red5/moq-rs interop (draftVersion: 14)
  • draft-ietf-moq-msf-00 — Catalog, track selection, ABR (altGroup), timeline
  • draft-ietf-moq-msf-01 - Independent catalogs, op-array deltas and referenced initialization data; catalog bootstrap uses Joining FETCH on drafts 14/16/18 and fills on drafts 22/23
  • draft-ietf-moq-loc-05 — Low Overhead Container, LOC-04 plus the Codec String property (0x11); locVersion: 5 to emit
  • draft-ietf-moq-loc-04 — Low Overhead Container (Timestamp + Timescale, Video Frame Marking, Audio Config); locVersion: 4 to emit
  • draft-ietf-moq-loc-01 — Low Overhead Container (CaptureTimestamp, VideoFrameMarking); auto-detected on parse, default on encode
  • draft-ietf-moq-cmsf-00 — CMAF Streaming Format (moof+mdat, MSE path)
  • draft-ietf-moq-cmsf-01 - CMAF catalogs with MSF-01 initialization references and SAP event timelines
  • draft-einarsson-moq-locmaf-01 - LOCMAF object reconstruction, MSE and coded-frame interfaces, including event-only tracks

CAT4MOQ bearer-token carriage is opt-in, not required for anonymous playback or broadcast. The application obtains credentials; the relay enforces permissions. DPoP signing is not built in. See authorization for the supported profiles and security boundaries.

Draft version selection

LOC and transport versions are independent. The broadcast example explicitly selects LOC-04; ?loc=1 selects LOC-01 and ?loc=5 selects LOC-05, which repeats the catalog's codec string on every object. Library encoding remains LOC-01 by default. A LOC-04 Timescale makes timestamps media-relative; conversion to LOC-01 requires an application-provided wall-clock anchor, not just unit scaling. LOC support here covers public properties and clear payloads. Secure Objects, encrypted/private properties, and automatic transport track-property delivery are not implemented. Callers with track-scoped defaults can pass track to parseLocHeaders().

Browser WebTransport may expose transport.protocol, enabling automatic draft detection from the negotiated WT-Available-Protocols:

  • moqt-23 → draft 23
  • moqt-22 → draft 22
  • moqt-18 → draft 18
  • moqt-16 → draft 16
  • moq-00 → draft 14

Without an explicit draft, a recognized transport.protocol selects the wire codec; otherwise the adapter defaults to draft 16. An explicit new MoqtConnection(18) selects draft 18. Keep that choice and the transport factory's draftVersion aligned. The browser factory offers ["moqt-16"] by default, not every supported draft. Opt into 18, 22 or 23 explicitly (or use ?v=18 / ?v=22 / ?v=23 in the examples). Drafts 22 and 23 require a readable negotiated moqt-22 / moqt-23 protocol and do not retry without the protocol offer.

draft-18 is an architectural change, not just a wire bump: the control stream becomes a unidirectional pair, each request rides its own bidirectional stream (responses correlate by stream, not Request ID), and integers use the full-uint64 vi64 encoding.

For draft-14 relays (moq-rs, Red5, moqtail), you must explicitly specify the version:

const conn = new MoqtConnection(14); // required — CLIENT_SETUP is draft-specific

MoqtConnection auto-detects the draft from any WebTransportLike whose protocol exposes a supported token (moqt-23, moqt-22, moqt-18, moqt-16, or moq-00) — there's nothing factory-specific about detection. The browser transport factory is just the convenience that sets the WebTransport protocols offer for you. If you construct your own WebTransport, pass the appropriate protocols option yourself and make sure transport.protocol is readable; Playa reads it the same way. Some Node/polyfill transports may not support protocols yet.

Node applications can use the experimental native QUIC binding for drafts 18, 22 and 23. Draft 18 is the default:

import { connectQuic } from '@openmoq/quic';
import { MoqtConnection } from '@openmoq/webtransport';

const transport = await connectQuic('moqt://relay.example.com:443/moq');
const connection = new MoqtConnection(18);
await connection.connect(transport);

@openmoq/quic requires Node >=26.8.1 built with QUIC support and launched with --experimental-quic. It offers moqt-18 by default, or moqt-22 / moqt-23 with { draft: 22 } / { draft: 23 }, requires QUIC DATAGRAM negotiation, disables 0-RTT, and does not fall back to WebTransport.

draft 23

Draft 23 (new MoqtConnection(23), draftVersion: 23, ALPN/WT protocol moqt-23) is opt-in. It keeps the draft-22 model, so everything in the draft-22 section below also applies, and changes the wire and behaviour as follows. Draft 22 and draft 23 are not wire-compatible.

  • Framing. A control message Length is a varint. This endpoint advertises, and never sends more than, the default MAX_CONTROL_MESSAGE_SIZE of 65535; a longer incoming message closes the session with FIELD_LENGTH_EXCEEDED before it is buffered.
  • FETCH responses. A FETCH is answered with REQUEST_OK; FETCH_OK (0x18) is reserved. The connection still surfaces a FETCH_OK to onMessage, whose End Location is LARGEST_OBJECT when the publisher sent it and the requested end otherwise. acceptFetch() sends LARGEST_OBJECT when the new largestObject option falls inside the requested range (draft 23 requires it there); endLocation is not used. endOfTrack has no draft-23 field and is refused: call sendFetchEndMarker(streamId, 'end-of-track') after the last Object instead.
  • FETCH stream. Object ID deltas within a group, delta-coded End of Range markers, End of Gone Range (0x40C), End of Group (0x80) and End of Track (0x81). sendFetchEndOfRange() takes a range kind ('non-existent', 'unknown', 'timed-out', 'gone') as well as the old boolean. End of Group and End of Track reach onObject as END_OF_GROUP and END_OF_TRACK gaps on the last Object; a Gone range is reported like an Unknown one. sendFetchEndMarker() writes nothing on earlier drafts.
  • PAUSED. FORWARD becomes PAUSED (0x11) with the value inverted. The codec translates, so the forward options and the FORWARD parameter keep their meaning on every draft.
  • Parameters. FILL_PARAMETERS is counted instead of length-prefixed. A PUBLISH answering a SUBSCRIBE_TRACKS carries SUBSCRIBE_TRACKS_ID. NAMESPACE carries an (empty) Parameters block.
  • REQUEST_ERROR. The Redirect becomes a REDIRECT Error Detail; UNSUPPORTED_PROPERTY details appear as unsupportedProperties, and every received detail as errorDetails.
  • Namespaces. Overlapping SUBSCRIBE_NAMESPACE and SUBSCRIBE_TRACKS prefixes are allowed (no PREFIX_OVERLAP), and an announced namespace reaches every matching namespace subscription.
  • Errors. Violations close with the specific draft-23 codes (MALFORMED_MESSAGE, INVALID_PARAMETER, UNEXPECTED_MESSAGE, MALFORMED_OBJECT, TRUNCATED_OBJECT, …) on draft-23 sessions only; earlier drafts still close with PROTOCOL_VIOLATION. A Track Name must be at least one byte.

Not implemented yet: the malformed-track rule for an Object that conflicts with a recorded non-existence (§12.1), Property multiplicity and scope checks, and fills requested through a PUBLISH.

draft 22

Draft 22 (new MoqtConnection(22), draftVersion: 22, ALPN/WT protocol moqt-22) keeps the draft-18 stream model and adds the features below. It replaces the experimental draft-21 implementation. LOCATION_FILTER now starts with a type (0x00-0x05) selecting its fields, rather than a length. Some encodings coincide, but the two drafts are not wire-compatible.

  • Location filters. SUBSCRIBE and FETCH carry their range in LOCATION_FILTER. SubscriptionFilter gains RelativeStart (groups: N starts at group Largest + 1 - N, so 1 is the current group) and an optional inclusive endObject on AbsoluteRange.

  • Fills instead of Joining FETCH. Draft 22 has no Joining FETCH. subscribe() / subscribeTrack() take fill: { filter?: SubscriptionFilter, groupOrder?: GroupOrder }. Omitted fields inherit the subscription policy. The fill is bounded by the Largest Location in its response; Forward=0 or an empty range opens no fill stream. Its FETCH_HEADER carries the SUBSCRIBE's or REQUEST_UPDATE's Request ID. There is no FETCH_OK: FIN completes the fill and reset fails it. cancelFill(requestId) stops a fill without cancelling live delivery; passing the subscription ID stops all of its fills. The publisher uses openFillStream(requestId) to serve it.

  • Player. The MSF-01 catalog bootstrap and warm start ask for the current group as a fill (RelativeStart with groups: 1). A SUBSCRIBE_OK without a Largest Object means an empty track, so the player waits for the first live catalog object and does not expect a fill.

  • Other changes. PUBLISH_STATE_NOTIFY on the subscription stream advances the Largest Location. GOAWAY has no Request ID. The End of Timed-Out Range fetch marker (0x20C) is accepted. PUBLISH_DONE 0x3 no longer exists.

  • REQUEST_UPDATE. requestUpdate() also takes fill; that fill stream carries the update's Request ID. SetupOptions.maxRequestUpdates advertises MAX_REQUEST_UPDATES. Updates never exceed the peer's limit, and a peer that exceeds ours closes the session with TOO_MANY_REQUEST_UPDATES.

  • Several subscriptions to one track. Draft 22 allows them, and a publisher may give them one Track Alias. Each subscription's filter controls delivery. Ending one leaves the others running. Publisher calls to openSubgroup() and sendDatagram() must supply requestId when the alias has several active owners, so cancellation and terminal stream counts remain attributable to the right request.

  • Native QUIC. connectQuic(uri, { draft: 22 }) offers moqt-22.

Range Filters beyond LOCATION_FILTER are not implemented. The endpoint advertises the default MAX_FILTER_RANGES=0 and rejects requests that exceed it with INVALID_FILTER rather than ignoring the filter.

Draft 22 does not change the framing of drafts 14/16/18. See draft development for compatibility policy and the unresolved FETCH End-of-Range framing question.

draft-18 known gaps (non-blocking)

draft-18 support is functional for the subscriber and publisher paths. The deliberately deferred edges are documented as intentional gaps rather than silently dropped:

  • Redirect (REQUEST_ERROR code 0x34) is decoded, context-validated, and surfaced — but automatic redirect-follow is not implemented; the application decides whether to reconnect.
  • GOAWAY (§10.4) is handled in both forms. On the control stream it transitions the session to DRAINING (no new local requests). On a request stream it is parsed and handled as a per-request migration signal — never FIFO-matched as a response and never a session close: the affected request is settled (a pending subscribeTrack() rejects with a non-fatal MoqtConnectionError) and the GOAWAY is surfaced via onMessage. Automatic re-issue/reconnect of that request is not implemented; it remains application policy.
  • PUBLISH_OK (0x1E) is intentionally rejected on draft-18: the changelog defines PUBLISH_OK as a REQUEST_OK alias and removed the standalone message, so draft-18 has no 0x1E control type (the value is a data-stream type) despite a stale registry table entry. Peers that emit a literal 0x1E control message are non-conformant; respond with REQUEST_OK.

Inbound Track Namespace / Full Track Name fields are validated per §2.4.1 (0–32 namespace fields, each non-empty; an empty namespace is permitted; Track Namespace and Full Track Name each ≤ 4096 bytes). A violation closes the session with PROTOCOL_VIOLATION, enforced both at the wire codec (decode/encode) and defensively in the session before any request/alias state is created.

Track Properties (§2.5) are fully wired in both directions: received on SUBSCRIBE_OK / FETCH_OK / TRACK_STATUS_OK / PUBLISH, and sent via the trackProperties option on acceptSubscribe(), acceptFetch(), acceptTrackStatus(), and publish(). (The send API is draft-18-only; supplying non-empty Track Properties on draft-14/16 throws.)

REQUEST_UPDATE is supported on the request streams that allow it: SUBSCRIBE and outbound PUBLISH (subscription updates), and SUBSCRIBE_NAMESPACE / SUBSCRIBE_TRACKS (§10.9.2 Track Namespace Prefix updates, with per-type prefix-overlap enforcement). It is not valid on a one-shot TRACK_STATUS stream.

After publishNamespace(ns), wait for acceptance via onMessage before calling publishNamespaceDone(requestId):

  • v18: REQUEST_OK on the PUBLISH_NAMESPACE request stream. The advertisement is persistent: publishNamespaceDone(requestId) withdraws it by closing/resetting that request stream — it does not emit a PUBLISH_NAMESPACE_DONE message (that message was removed in draft-18).
  • v16: REQUEST_OK with the matching requestId. publishNamespaceDone(requestId) emits PUBLISH_NAMESPACE_DONE on the control stream.
  • v14: PUBLISH_NAMESPACE_OK with the matching requestId. publishNamespaceDone(requestId) emits PUBLISH_NAMESPACE_DONE on the control stream.

Do not use a fixed sleep. If onClose fires before acceptance, treat the operation as failed.

Transport robustness

  • Legacy MAX_REQUEST_ID sliding window - the player advertises 10,000 initially and replenishes credit in increments of 1,000. Drafts 18/22 use QUIC request-stream limits instead.
  • Stream limit handling — createUnidirectionalStream() failures caught and surfaced as non-fatal MoqtConnectionError (relevant to relays with WT_MAX_STREAMS limits)
  • Legacy REQUESTS_BLOCKED - peer notified via MAX_REQUEST_ID when blocked

Running the Examples

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Start the dev server (examples at http://localhost:5173)
cd examples && npx vite dev

Example pages:

Path Description
/player/ Player with stats, video-view and quality selectors, and settings
/simple/ Minimal player — connect, play, done
/connect/ Protocol explorer — raw message log
/catalog/ Catalog browser
/broadcast/ Camera/screen publisher example with opt-in CAT4MOQ
/video/ Video-only player

The /player/ page takes URL parameters: ?url= (relay), ?ns= / ?nsField= (namespace), ?hash= (cert hash), ?v=14|16|18|22|23 (draft), ?authority= (tenant-routed relays), ?warmStart=1 (join live LOC/CMAF/LOCMAF tracks mid-group via Joining FETCH or draft-22 fills; needs isLive: true in the catalog and relay support; degrades to a normal live join otherwise), ?log=info|debug (player logs on the console), ?catalog=<base64 JSON> (inject a catalog), ?fetchCatalog=1 (FETCH the catalog before injecting it into the player), ?catalogBootstrap=auto|joining-fetch|strict|subscribe (bootstrap policy), ?altGroup=0 (initial video view), and ?locmaf=mse|frame (LOCMAF decode path).

?url= is the complete WebTransport endpoint, including its deployment-specific path. For example, use ?url=https%3A%2F%2Frelay.example.com%3A4433%2Fmoq-relay when a relay is mounted at /moq-relay. When omitted, the browser examples discover the endpoint by probing https://<page-host>:4433 at /moq, /moq-relay, then / and selecting the first successful path in that order. /moq and /moq-relay are deployment conventions, not MOQT-standard paths (a relay that accepts any path simply matches on /moq). Discovery is a convenience for these examples: a deployed application knows its relay endpoint and should configure the complete URL.


Testing

# Discover and run standard and native UDP correctness projects
pnpm test

# Reproduce CI: standard tests, then serialized native UDP correctness
pnpm test:ci

# Run only the serialized native UDP correctness project
pnpm test --project native-correctness --maxWorkers=1 --no-file-parallelism --retry=0

# Explicit host-performance cases (single worker, retry0)
pnpm test:shaper:performance

# Watch mode
pnpm test:watch

# Typecheck test sources
pnpm typecheck:tests

# Check published exports and legacy compatibility wrappers (build first)
pnpm build
pnpm smoke:exports

# Browser playback acceptance (requires ffmpeg and installed Google Chrome)
pnpm test:player:browser

pnpm test [paths] retains filename filtering across both correctness projects. Native UDP correctness requires local bind permission and runs without parallel test workers in CI. Use pnpm test:ci for the required scheduling; plain pnpm test discovers both projects but does not enforce isolated native worker limits. Host timing is separate: pnpm test:shaper:performance retains the strict p99 <2ms bound and runs with one worker and zero retries.

Browser acceptance runs against a private local WebTransport relay with generated media. It checks moving video, browser audio-output samples, quality/view selection, LOC timing domains, mixed packaging, and both LOCMAF paths. Frozen picture and missing-audio controls must be detected as failures. JSON evidence, screenshots and logs are written under reports/player-acceptance/; this does not claim physical-speaker output or interoperability with every remote relay. Set PLAYER_TEST_BROWSER=chromium to use an installed Playwright Chromium build instead of Google Chrome.


Docs

  • Simulation — Deterministic protocol-confidence harness (golden vectors, codec property tests, seeded scenario runner) for MoQT drafts 14/16/18
  • Catalog Testing — Integration harness for validating catalog subscription against a live relay
  • Authorization — CAT4MOQ credential providers for players and connections
  • Package Compatibility - Legacy package re-exports and release ordering
  • Draft Development - Draft-22 and draft-23 support and compatibility policy
  • Playout Trace - Bounded qlog recorder, event design and instrumentation status
  • Optional Player Diagnostics - Explicit development or production exposure, bounded capture, and recording
  • Diagnostic Probe - Owner-local WebTransport probes, protocol policy, and lifecycle
  • DevTools Extension - Build and load the workspace Chrome panel; inspect an opted-in player or start a separate Probe

Related Content

Author

Raymond Lucke and the Red5 Team

Publication heads and confirmed updates

Publishers serving REQUEST_UPDATE on drafts 16, 18 and 22 must install setLargestLocationProvider for subscription requests and setFetchLargestLocationProvider for FETCH requests. Return the current track head as { group, object }, or null only for a known-empty track. Bind each lookup to its exact live request; throw for unknown or retired sources. Advance the head before sending each Object. Prepare outgoing publication heads before writing PUBLISH so immediate peer updates can resolve the live request. A FETCH's finite end is not its track head. Missing, throwing or invalid providers refuse the update and terminate its subscription (UPDATE_FAILED) or FETCH. This also applies to draft-16/18 publishers that previously accepted updates without a provider.

requestUpdateConfirmed(id, { timeoutMs, ...options }) resolves after the matching REQUEST_OK has been applied and returns a private copy of its parameters. RequestUpdateError preserves a peer refusal. Other RequestUpdateFailures say not-sent or possibly-sent; a timeout or abort after dispatch does not undo an update, and a late acknowledgement can still apply. Draft 14 has no confirmation. IncomingPublish.largestLocation reports a frozen receive-head snapshot; closed resolves with the final snapshot when the publication ends.

License

Apache 2.0

About

MOQ reference implementation of Media over QUIC Transport. Full stack from WebTransport to viewport: protocol core, LOC/CMAF decode paths, ABR, and a batteries-included player.

Resources

Stars

22 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages