feat(spf): speak moqt-22 through @caprid/moq-core
Stacks on #72 (feat/moq-worklet-audio-default). Retarget to mmcc/moq once #72 merges.
Summary
The MoQ player takes its MOQT codec and session from @caprid/moq-core 0.1.1 instead of its own copy in packages/spf/src/network/moqt/, which is deleted. The package was extracted from that copy, and its UPSTREAM.json asks v10 to migrate rather than keep a divergent implementation. The player now offers moqt-22 first and falls back to moqt-20.
Changes
- Dependency.
@caprid/moq-core^0.1.1 is added to@videojs/spf, and@caprid/moq-mediamoves to ^0.1.1. - Imports. Every importer of
network/moqt/*now imports from@caprid/moq-core:moq-session,track-subscriber,resolve-catalog,subscribe-selected-tracksand their tests. The local modules (bytes, varint, errors, control-messages, object-stream, request-stream, session) and their tests are deleted. - Negotiation. The session actor offers
MOQT_PROTOCOL_IDS(['moqt-22', 'moqt-20']). The default factory hands the realWebTransportto the core, and the core readstransport.protocol(theWT-Protocolanswer) throughresolveMoqtProtocolto pick its LOCATION_FILTER codec, the only wire difference between -20 and -22. A browser withoutWebTransport.prototype.protocoloffersmoqt-22only, because it could not report amoqt-20pick, and the core would misread the filter. - Draft-22 behaviour. The player sends only
relative-group 0andrelative-group 1filters. Those encode to the same bytes on -20 and -22, so no player logic changed. Transport section citations in source and the sandbox loopback relay now use draft-22 numbering. - Audio regression fixed.
@caprid/moq-media0.1.1 decodes Opus with WebAssembly libopus by default. That decoder is single-stream and ignores the OpusHead channel mapping, so a multistream track (channelConfig above stereo) would decode as noise. The default player factory passeslossConcealment: false, which keeps #72's WebCodecs path. Codex found and reproduced this. - Specs.
draft-ietf-moq-transport-22.txtreplaces the -20 text ininternal/specs/moq/. The README's tables, checksum and "declared in code" sentence now point at@caprid/moq-core. - Prose.
packages/spf/docs/moq-publishing.md, the sandbox relay templates and both.agents/plans/MoQ notes are repointed. The draft-20 migration plan is marked superseded on the player.
v10-side helpers kept
packages/spf/src/network/tests/helpers/moqt-wire.ts, test-only. The in-memory fake relays need the relay side of the wire: server SETUP,decodeControlMessage,encodeSubscribeOk,encodeRequestError,StreamReaderandutf8Encode. The package's public entry doesn't export any of them. The helper re-exports them from the package's owndist/protocol/*by deep relative path instead of re-implementing them, so a release that moves those modules breaks the tests loudly. A public@caprid/moq-core/testing(or wire-codec) entry would let this go.- No runtime helpers. Everything the player used (
compareLocations,isRetryable*,utf8Decode,REQUEST_ERROR_CODE,PUBLISH_DONE_STATUSand the session types) is exported by 0.1.1.
Testing
pnpm -F @videojs/spf test: 132 files and 2305 tests pass, with no type errors.pnpm build:packages,pnpm typecheck(staletypes/and tsbuildinfo cleared first) andpnpm lintall pass.codex review --base feat/moq-worklet-audio-defaultmade one finding, the multistream Opus regression above, which is fixed in 38db34cf6 with a test that fails without the fix.- Live, relay.mux.global, 2026-10-27, headless Chromium. A scratch browser test, not committed, publishes a synthetic VP8 640Ć360 and Opus broadcast with
@caprid/moq-core's publish session underhuddle/videojs-testing/*. It then plays the broadcast throughcreateMoqEnginewith the default WebTransport factory.- Both connections offered
["moqt-22","moqt-20"]and the relay selectedmoqt-22. The player session was ready 107 ms after connect. - The relay's upstream SUBSCRIBE decoded on -22 as
next-objectplus fillrelative-group 1. The publisher served it. - The catalog resolved and both tracks were selected. The first video frame decoded and the first audio was scheduled 522 ms after the player started.
- Over 25 s: 739 video frames decoded with 0 dropped, 1212 audio frames scheduled with 0 underruns, and the audio clock advanced 19909 ms over 19990 ms of wall time (0.996Ć).
- Both connections offered
Notes for the publisher PR (mmcc/moq-publisher)
createMoqtPublishSessionreplacespublish-session.ts. The publisher has to adapt to:openUniStream(trackAlias);- no
getStreamCount, since the session counts data and fill streams itself; - explicit track properties, so declare TIMESCALE (
TRACK_PROPERTY.TIMESCALE) yourself; - an orderly
close()that waits up toCLOSE_END_ACK_TIMEOUT_MS(2 s) for the relay's FIN; - during close, only tracks pending on
end({ after })can open streams.
subgroup-writer.tsmaps tocreateSubgroupWriter, andencodeFetchHeaderandisEmptyFetchRangeare exported. The publisher's tests that usetests/helpers/raw-peer.tsandtransport-pair.tswill need the same deep-import approach asmoqt-wire.ts, or a testing entry upstream.- The publisher should also pass the negotiated protocol through: offer
MOQT_PROTOCOL_IDSand construct the session over the realWebTransport. - Verified live here: the moq-core publish session answered relay.mux.global's moqt-22 upstream SUBSCRIBEs (LARGEST_OBJECT via
getLargestObject, plus a fill) and played cleanly.
š¤ Generated with Claude Code
https://claude.ai/code/session_01DaH4ieYHRP2Agar6P9KSCB
Summary by cubic
The MoQ player now speaks the transport through @caprid/moq-core 0.1.1 instead of its own vendored copy in packages/spf/src/network/moqt/, which is deleted. The session offers moqt-22 first with moqt-20 as fallback, and the core reads the negotiated WebTransport protocol to pick its LOCATION_FILTER codec ā the only wire difference between the two ā while browsers without WebTransport.prototype.protocol offer moqt-22 only.
Behavior changes
@caprid/moq-mediamoves to ^0.1.1, and its default WebAssembly libopus decoder is disabled (lossConcealment: false) since it decodes multistream Opus as noise; WebCodecs stays the audio path.- Test-only
moqt-wire.tsre-exports the package's relay-side codec through a deep path into itsdist/, so a release that moves those modules fails the tests loudly. - The vendored draft-20 spec text is replaced by draft-22 and docs/relay templates are repointed; the publisher still runs the local codec until its own move.