Skip to content

feat(media-sync): transport-neutral media clock and generation-safe delivery queue - #5423

Closed
kkroo wants to merge 1 commit into
moq-dev:mainfrom
Blockcast:feat/media-sync-core
Closed

kkroo wants to merge 1 commit into
moq-dev:mainfrom
Blockcast:feat/media-sync-core

Conversation

@kkroo

@kkroo kkroo commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

Problem

A receiver that does not use @moq/watch (a different container, decoder, or renderer) has no way to reuse the playback clock or the per-track delivery fencing. Sync in js/watch/src/sync.ts depends on @moq/signals, @moq/net probes and branded Time.Milli, and its generation fence is the epoch that video/decoder.ts checks inline after each wait, so every other receiver re-implements both. We maintain two receivers (a hang fork and a moqtail-based one) that currently share one copy of this logic out of tree.

Approach

Add js/media-sync (@moq/media-sync), dependency-free, ~220 lines:

  • Clock: received(ts) seeds and lowers the reference; now(kind) and wait(ts, kind, signal) apply a per-kind buffer. timestampScale keeps the caller's units (1 for ms, 1000 for µs). wait throws on an unseeded clock, so callers seed before waiting.
  • Queue: enqueue(ts, kind, stage) paces and serializes per kind. A stage returns a commit (or {commit, discard}); the commit runs only if its generation is still current after every await.
  • Generations: cancel(kind) / reset() abort the generation's AbortSignal, drop queued work, and allow timestamp reuse. reset() also clears the clock and wakes parked waits.
  • @moq/media-sync/vectors exports the clock, pacing and retirement vectors, so wrappers that change units or callbacks run the same cases as the core.

@moq/watch is not changed in this PR. This is an additive core, not a drop-in replacement for its current Sync: watch still uses close() for teardown and epoch around video waits; this core has neither API.

Impact

  • New package @moq/media-sync (exports MediaSync, MediaKind, MediaDelivery, MediaDeliveryStage, MediaSyncOptions) and subpath ./vectors. No change to any existing API or wire format.

Alternatives

  • Extend @moq/watch Sync. That keeps the queue behind a player package that pulls in signals, net and the UI. A receiver that only wants the fence would depend on a player.
  • Export only a delivery queue that takes an injected wait. That is smaller, but it adds a callback interface and still leaves every receiver to re-implement the clock.
  • Semantic difference from Sync today: after fix(watch): hold parked video waits across a shared clock reset #5272, a Sync.wait parked across reset() holds until the next frame re-anchors. Here a reset wakes the wait and the generation fence discards its commit. Migrating watch onto this core would need that choice made explicitly, so this PR leaves it for later.

Follow-ups

  • Optionally re-base watch's Sync queue and epoch fence on this core, if wanted, with explicit teardown (close()), epoch fencing, and reset/wait integration.
  • Docs page under doc/lib/js/ if the package is accepted.

Validation

  • Exact submitted head: a4f8a552f952c683b72cf1a6365bf5a476910e60. Independently rerun vector suite: 15 tests pass, 29 expectations.
  • Author checks recorded for this head: TypeScript, Biome, build/publint, and isolated packed-consumer import pass. Those checks were not independently rerun during submission.
  • Additive package; no runtime dependencies or imports from other @moq/* packages.

View with [code]smith Autofix with [code]smith
Need help on this PR? Tag @codesmith-bot with what you need.

…elivery queue

Adds @moq/media-sync, a dependency-free core for anchoring media timestamps
to a local clock, pacing deliveries, and serializing them per media kind with
generation-scoped cancellation: a delivery stages its effects and returns a
commit, and cancel()/reset() discard anything staged before the retirement.
Shared vectors let wrappers that adapt units or callbacks test against the
same cases as the core.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Signed-off-by: HangPlayerEngineer <hangplayerengineer@paperclip.blockcast.net>
@kixelated

kixelated commented Oct 13, 2026 •

Copy link
Copy Markdown
Collaborator

@moq/watch should be tree-shaken? The JS API is meant to be modular so you can pick and choose to use Sync, Source, Decoder, Renderer, etc and only what you need makes the final build. Like sure we could make Signals more tree-shakable but really I need some solid numbers.

At the very least a before/after comparison of your final bundle size... and why it even matters.

@kixelated

Copy link
Copy Markdown
Collaborator

Thanks for putting this together, @kkroo. We're going to close it: we don't want to take on and maintain a separate @moq/media-sync package. The receiver pieces in @moq/watch (Sync, Source, Decoder, Renderer) are meant to be modular and tree-shaken, so a receiver should be able to import just what it needs. If something there blocks reuse in your receivers, please open an issue with the concrete gap (and bundle numbers if size is the concern), and we can fix it in place.

(Written by Claude Opus 5.5)

@kixelated kixelated closed this Oct 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants