Repository navigation
Description
Problem
A C publisher that writes media with moq_publish_media_frame stamps it on its own timeline. moq-c passes timestamp_us through verbatim and has no call that reads the broadcast clock. Its JSON snapshot and stream writes, though, are stamped with the broadcast clock's now(), and each JSON track holds a seat in the catalog's write Order. As a result, every media track on the broadcast advertises a catalog delay of about the gap between the two timelines.
Observed on 80e29de4 (moq-c 0.7.0, unreleased), with:
- two video renditions and one Opus rendition, written with
moq_publish_media_frameon the publisher's media timeline (starting near 2 s); - two JSON snapshot tracks, updated with
moq_publish_json_snapshot_updateabout once per second.
Every media track advertises a delay of ~8.1 s:
- video 8126 ms and 8126 ms;
- Opus 8133 ms.
@moq/watch buffers 8.1 s accordingly.
On libmoq 0.6.17 the same publisher advertised 1 to 14 ms; there, C JSON writes carried no timestamp and so took no part in delay. moq-c began stamping them with the broadcast clock in #5560, and #6595 made a stamped write a seat in the write order.
Root cause
json_snapshot_updateandjson_stream_append(rs/moq-c/src/publish.rs:1284-1318) stamp each value withclock.now(), the catalog clock thatdata_tracktook (publish.rs:1207).- moq-c builds its catalog with
Config::default(), so the clock is a freshmoq_mux::Clock, which readsLEAD= 10 s at construction (rs/moq-mux/src/clock.rs:88-104,catalog/producer.rs:518-522). moq_mux::json::Snapshot::updatepasses that timestamp toListing::recordas the capture time, andrecord_atorders it withestimator.order(captured.min(now))(rs/moq-mux/src/json.rs:215-224,catalog/data.rs:84-115). The JSON estimator holds a seat in the sameOrderas the media renditions (catalog/producer.rs:990-992).Highs::writereturns how far a write trails the highest timestamp any other seat has written, and the estimator keeps the maximum asdelay(catalog/estimate.rs:155-159,460-489). Every media frame is compared with the latest JSON stamp, which is ~8 s ahead.
In Rust a publisher can keep this consistent. catalog::Producer::clock() hands out the broadcast clock, so media and data can both be stamped on it, and a data value timed on it is meant to measure delay (doc/concept/hang.md: "only from payloads stamped with their capture time on the broadcast clock"). moq-c has neither half:
- No call reads the clock. moq-ffi has
MoqMediaCatalogProducer::now()from Preserve caller-supplied producer timestamps #5560, which left the C ABI out. - Its JSON writes take no timestamp, so moq-c passes the write time on as a capture time.
Even a C publisher whose media timeline matched the clock would see a delay of its capture-to-write latency, since moq-c stamps JSON when it is written while media carries its capture time.
The catalog's clock.wall is catalog creation minus 10 s (clock.rs:96-104, producer.rs:525). A consumer computing wall time from C media timestamps as wall + pts is therefore also ~8 s off.
Related: #6946 gives moq_publish_json_snapshot_update and _stream_append a trailing const moq_timestamp *, and NULL keeps stamping the broadcast clock. Once it lands, a C publisher can pass its media timestamp and avoid this, but callers passing NULL still get ~8 s.
Options
- Keep a write without a timestamp out of the order (recommended).
- On top of feat(bindings)!: exact {value, scale} timestamps in every binding #6946, a value with a timestamp is ordered at it.
- With NULL, it is still stamped
now()for delivery, but recorded withcaptured = None. It then measures bitrate only and never moves another track'sdelay. - NULL callers are fixed with no code change.
- moq-mux needs a way to write a timed value unordered, for example
moq_mux::json::Snapshot::update_unordered, and the same onStream. JSON windows aren't in the catalog, so they need nothing.
- Expose the broadcast clock to C, mirroring moq-ffi's
MoqMediaCatalogProducer::now(), for examplemoq_publish_catalog_now(broadcast, moq_timestamp *dst). C publishers can then stamp media on it. This needs no change to the order, but writes without a timestamp still show the capture-versus-write gap asdelay.
I have option 1's NULL path prototyped for snapshots as a two-file change (rs/moq-mux/src/json.rs, rs/moq-c/src/publish.rs), with a moq-mux test. Streams need the same in Stream::append.
The prototype has been applied to the same publisher on a live stream on 80e29de4, without B-frames, for 15 minutes:
Media jitter / delay |
@moq/watch delay |
|
|---|---|---|
| Without the patch | – / ~8.1 s on every track | 8163 ms |
| With the patch | none on any track | 30 to 50 ms |
The JSON tracks were still delivered, with their timestamps.
Related: #7579, the B-frame reorder effect in the same Order.
(Written by Claude Opus 5.5)
Activity
[-]moq-c: JSON snapshot writes take a place in the catalog write order, putting every C media track ~8 s behind[/-][+]moq-c: a JSON write without a timestamp is ordered on the broadcast clock, which C media can't read, so every media track advertises ~8 s delay[/+]kixelated commentedon Nov 3, 2026
Thanks for the clear diagnosis. It's planned in #7665 as
quest/m1/json-required-timestamp.md.Decision: neither option exactly. Every track in a broadcast has to share one epoch, so:
now();moq_publish_catalog_now(), so a C publisher stamps both its media and its data from the broadcast clock.This is the first piece of a broader rule recorded in the same PR: no write anywhere is ever wall-clock stamped.
To pick it up, run
/quest-start quest/m1/json-required-timestamp. Anyone who wants to donate tokens is welcome to.(Written by Claude Opus 5.5)
quest: import moq-dev#7573, moq-dev#7579, moq-dev#7646 and settle tim…