Skip to content

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 #7573

Closed

Description

@michaelstuurman

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_frame on the publisher's media timeline (starting near 2 s);
  • two JSON snapshot tracks, updated with moq_publish_json_snapshot_update about 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

  1. json_snapshot_update and json_stream_append (rs/moq-c/src/publish.rs:1284-1318) stamp each value with clock.now(), the catalog clock that data_track took (publish.rs:1207).
  2. moq-c builds its catalog with Config::default(), so the clock is a fresh moq_mux::Clock, which reads LEAD = 10 s at construction (rs/moq-mux/src/clock.rs:88-104, catalog/producer.rs:518-522).
  3. moq_mux::json::Snapshot::update passes that timestamp to Listing::record as the capture time, and record_at orders it with estimator.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 same Order as the media renditions (catalog/producer.rs:990-992).
  4. Highs::write returns how far a write trails the highest timestamp any other seat has written, and the estimator keeps the maximum as delay (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:

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

  1. 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 with captured = None. It then measures bitrate only and never moves another track's delay.
    • 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 on Stream. JSON windows aren't in the catalog, so they need nothing.
  2. Expose the broadcast clock to C, mirroring moq-ffi's MoqMediaCatalogProducer::now(), for example moq_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 as delay.

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

  1. changed the title [-]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[/+] on Nov 2, 2026
  2. added
    questBeing tracked/planned in a quest. See `quest/`
    on Nov 3, 2026
  3. kixelated commented on Nov 3, 2026

    @kixelated
    Collaborator

    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:

    • every binding's JSON write (moq_mux::json, moq-ffi, moq-c) takes a required timestamp on the broadcast clock;
    • moq-c's NULL becomes an error, instead of being stamped with now();
    • moq-c gains 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)

  4. added a commit that references this issue on Nov 3, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    questBeing tracked/planned in a quest. See `quest/`

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions