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.
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.
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();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.
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 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: 4or5is 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'inMoqtPlayerconfig (moqtPlayerConfigonPlayer).
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
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
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.
| 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 |
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 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.
// 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.
| 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' |
- 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: 5to emit - draft-ietf-moq-loc-04 — Low Overhead Container (Timestamp + Timescale, Video Frame Marking, Audio Config);
locVersion: 4to 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.
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 23moqt-22→ draft 22moqt-18→ draft 18moqt-16→ draft 16moq-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-specificMoqtConnection 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 (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_OKtoonMessage, whose End Location is LARGEST_OBJECT when the publisher sent it and the requested end otherwise.acceptFetch()sends LARGEST_OBJECT when the newlargestObjectoption falls inside the requested range (draft 23 requires it there);endLocationis not used.endOfTrackhas no draft-23 field and is refused: callsendFetchEndMarker(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 reachonObjectas 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
forwardoptions 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 aserrorDetails. - 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 (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.
SubscriptionFiltergainsRelativeStart(groups: Nstarts at group Largest + 1 - N, so 1 is the current group) and an optional inclusiveendObjectonAbsoluteRange. -
Fills instead of Joining FETCH. Draft 22 has no Joining FETCH.
subscribe()/subscribeTrack()takefill: { 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 usesopenFillStream(requestId)to serve it. -
Player. The MSF-01 catalog bootstrap and warm start ask for the current group as a fill (
RelativeStartwithgroups: 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_DONE0x3no longer exists. -
REQUEST_UPDATE.
requestUpdate()also takesfill; that fill stream carries the update's Request ID.SetupOptions.maxRequestUpdatesadvertises 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()andsendDatagram()must supplyrequestIdwhen the alias has several active owners, so cancellation and terminal stream counts remain attributable to the right request. -
Native QUIC.
connectQuic(uri, { draft: 22 })offersmoqt-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 support is functional for the subscriber and publisher paths. The deliberately deferred edges are documented as intentional gaps rather than silently dropped:
- Redirect (
REQUEST_ERRORcode0x34) 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 pendingsubscribeTrack()rejects with a non-fatalMoqtConnectionError) and the GOAWAY is surfaced viaonMessage. 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 definesPUBLISH_OKas aREQUEST_OKalias and removed the standalone message, so draft-18 has no0x1Econtrol type (the value is a data-stream type) despite a stale registry table entry. Peers that emit a literal0x1Econtrol message are non-conformant; respond withREQUEST_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_OKon the PUBLISH_NAMESPACE request stream. The advertisement is persistent:publishNamespaceDone(requestId)withdraws it by closing/resetting that request stream — it does not emit aPUBLISH_NAMESPACE_DONEmessage (that message was removed in draft-18). - v16:
REQUEST_OKwith the matchingrequestId.publishNamespaceDone(requestId)emitsPUBLISH_NAMESPACE_DONEon the control stream. - v14:
PUBLISH_NAMESPACE_OKwith the matchingrequestId.publishNamespaceDone(requestId)emitsPUBLISH_NAMESPACE_DONEon the control stream.
Do not use a fixed sleep. If onClose fires before acceptance, treat the operation as failed.
- 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-fatalMoqtConnectionError(relevant to relays with WT_MAX_STREAMS limits) - Legacy REQUESTS_BLOCKED - peer notified via MAX_REQUEST_ID when blocked
# Install dependencies
pnpm install
# Build all packages
pnpm build
# Start the dev server (examples at http://localhost:5173)
cd examples && npx vite devExample 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.
# 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:browserpnpm 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.
- 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
Raymond Lucke and the Red5 Team
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.
Apache 2.0