Repository navigation
docs(quest): a broadcast's wall times track UTC for any session length #9077
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,60 @@ | ||
| # [L] A broadcast's wall times track UTC for any session length | ||
|
|
||
| ## Goal | ||
|
|
||
| A broadcast's wall times (`sync.clock.wall + pts`, as HLS | ||
| `EXT-X-PROGRAM-DATE-TIME`, DASH `availabilityStartTime`, and app | ||
| `wallClockTime` read them) stay within about 1 s of the publishing host's | ||
| UTC for any session length, on Linux, macOS, Windows, and in browsers, | ||
| including after a suspend. Media timing never jumps on an NTP step. | ||
|
|
||
| Non-goals: drift of an audio device's crystal against the host clock | ||
| (moq-dev/moq#9059 and its `browser-audio-drift` follow-up), skew between | ||
| hosts (JWT and grant leeway, DASH `UTCTiming`, derivatives on another host), | ||
| an MPEG-TS stream's own clock steps, and WHIP senders' RTCP clocks. | ||
|
|
||
| ## Plan | ||
|
|
||
| Today the anchor is sampled once (`moq_mux::Clock::new`, | ||
| `rs/moq-mux/src/clock.rs`; `CatalogProducer` from `performance.timeOrigin` in | ||
| `js/publish/src/catalog.ts`) and PTS advances by monotonic elapsed time. The | ||
| mapping is right on Linux, whose CLOCK_MONOTONIC takes NTP's rate | ||
| correction. It drifts on macOS, Windows, and in browsers by the crystal's | ||
| error, about 1 to 4 s a day and up to 43 s at 500 ppm. A suspend adds its | ||
| full length, because the monotonic clock stops while the host sleeps. | ||
|
|
||
| Decided 2026-11-18 (maintainer, /quest-plan): | ||
|
|
||
| - ✅ Slew the PTS clock (rejected: republish the catalog clock, re-anchor per | ||
| publisher run). The media clock runs at UTC's rate, nudged toward the wall | ||
| clock by at most about 500 ppm (NTP's own slew cap), the way Linux slews | ||
| CLOCK_MONOTONIC. The catalog mapping stays fixed for the broadcast, so the | ||
| hang draft does not change. Republishing would make wall time jump between | ||
| frames and need a draft change; re-anchoring per run leaves a single long | ||
| session drifting. Do it where media is stamped (`moq_mux::Clock` and | ||
| js/publish's clock), not kio-wide, so timers and group aging keep the | ||
| plain monotonic clock. | ||
| - ✅ A suspend is a gap in the timeline (rejected: slew it out, out of | ||
| scope). Natively, read a clock that counts suspend (CLOCK_BOOTTIME on | ||
| Linux, `mach_continuous_time` on macOS, the interrupt-time equivalent on | ||
| Windows), so PTS jumps forward by the sleep. No media exists for that | ||
| time, and #9059 handles a large audio jump the same way. Slewing a 1 h | ||
| sleep at 500 ppm would take about 80 days. | ||
| - ✅ In browsers, a forward jump of `Date.now()` against `performance.now()` | ||
| of more than about 2 s is a suspend gap, and anything smaller is slewed | ||
| (rejected: always slew). Browsers have no boot-time clock to tell a | ||
| suspend from a forward NTP step; a step that big in a browser is rare, and | ||
| a gap only moves forward, so media never runs backward. | ||
| - An NTP step natively, or a backward jump anywhere, is slewed out at the cap | ||
| and never jumps media, as the Goal requires. | ||
|
Comment on lines
+48
to
+49
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Reconcile the accuracy goal with capped step correction. If native wall time steps forward by 2 s, the 500 ppm cap leaves the broadcast more than 1 s behind for about 2,000 s. Larger or backward steps have the same conflict. The proposed step test cannot satisfy the Goal as written. Define an attainable error bound during step recovery, or revise the timing requirements.
|
||
|
|
||
| Recommendations, not decided: | ||
|
|
||
| - Rust and JS land in one PR, per the cross-package sync rule. | ||
| - Prove it with kio's sim, which models `step_wall` but not slew or suspend: | ||
| add both, and show the mapping's error stays within 1 s across a simulated | ||
| day at ±500 ppm, a step each way, and a suspend. | ||
| - gst `moqsink` stamps from the pipeline's running time and places its anchor | ||
| itself (`rs/moq-gst/src/sink/wall.rs`); GStreamer users pick an NTP or | ||
| realtime pipeline clock there, so leave it unless it maps through | ||
| `moq_mux::Clock`. | ||
|
Comment on lines
+57
to
+60
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Bring the GStreamer running-time anchor into the Goal's scope. The Goal covers broadcasts on macOS and Windows. The plan leaves Decide the GStreamer case in the plan. Either apply the same slew to the
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Qualify the Goal's NTP-step guarantee to include the browser gap rule.
The Goal says media timing never jumps on an NTP step. The browser rule in Plan accepts a PTS gap when a forward
Date.now()step exceeds about 2 s. These statements conflict as written. Update the Goal to name this browser exception so the contract matches the decision.Suggested fix