feat(spf): speak moqt-22 through @caprid/moq-core

Merged
MM
25d ago
+5206-10132

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-media moves to ^0.1.1.
  • Imports. Every importer of network/moqt/* now imports from @caprid/moq-core: moq-session, track-subscriber, resolve-catalog, subscribe-selected-tracks and 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 real WebTransport to the core, and the core reads transport.protocol (the WT-Protocol answer) through resolveMoqtProtocol to pick its LOCATION_FILTER codec, the only wire difference between -20 and -22. A browser without WebTransport.prototype.protocol offers moqt-22 only, because it could not report a moqt-20 pick, and the core would misread the filter.
  • Draft-22 behaviour. The player sends only relative-group 0 and relative-group 1 filters. 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-media 0.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 passes lossConcealment: false, which keeps #72's WebCodecs path. Codex found and reproduced this.
  • Specs. draft-ietf-moq-transport-22.txt replaces the -20 text in internal/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, StreamReader and utf8Encode. The package's public entry doesn't export any of them. The helper re-exports them from the package's own dist/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_STATUS and 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 (stale types/ and tsbuildinfo cleared first) and pnpm lint all pass.
  • codex review --base feat/moq-worklet-audio-default made 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 under huddle/videojs-testing/*. It then plays the broadcast through createMoqEngine with the default WebTransport factory.
    • Both connections offered ["moqt-22","moqt-20"] and the relay selected moqt-22. The player session was ready 107 ms after connect.
    • The relay's upstream SUBSCRIBE decoded on -22 as next-object plus fill relative-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Ɨ).

Notes for the publisher PR (mmcc/moq-publisher)

  • createMoqtPublishSession replaces publish-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 to CLOSE_END_ACK_TIMEOUT_MS (2 s) for the relay's FIN;
    • during close, only tracks pending on end({ after }) can open streams.
  • subgroup-writer.ts maps to createSubgroupWriter, and encodeFetchHeader and isEmptyFetchRange are exported. The publisher's tests that use tests/helpers/raw-peer.ts and transport-pair.ts will need the same deep-import approach as moqt-wire.ts, or a testing entry upstream.
  • The publisher should also pass the negotiated protocol through: offer MOQT_PROTOCOL_IDS and construct the session over the real WebTransport.
  • 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-media moves 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.ts re-exports the package's relay-side codec through a deep path into its dist/, 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.