Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions quest/m1/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,7 @@ lands before the cut.
- [Lazy discovery](/quest/m1/lazy-discovery/README.md) - a `consume` session requests announcements only for prefixes the origin is watching, in JS then Rust; `follow`, `broadcasts`, and the `discovery` option go away
- [A spinning loop fails a sim test](/quest/m1/spinning-loops.md) - a sim test names any loop that holds a task poll too long, and each one yields through a budget
- [Data consumer timestamps](/quest/m1/data-consumer-timestamps.md) - json and binary consumers return each value's timestamp, in Rust and every binding; snapshots add `latest()` beside an in-order `next()`
- [Exact timestamps in every binding](/quest/m1/binding-timestamps.md) - bindings carry `{value, scale}` timestamps instead of lossy microseconds
- [JSON window timestamps](/quest/m1/json-window-timestamps.md) - Rust and JS window consumers return each event's frame timestamp like the snapshot and stream consumers
- [JavaScript FETCH](/quest/m1/js-fetch.md) - browser publishers answer IETF FETCH through the JS ranges request surface
- [IETF fill timeout](/quest/m1/ietf-fill-timeout.md) - native FILL_TIMEOUT bounds upstream waiting on drafts 18-22, alongside local content-age enforcement
Expand Down
61 changes: 61 additions & 0 deletions quest/m1/binding-timestamps.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
# [L] Exact timestamps in every binding

## Goal

Every binding (moq-ffi, moq-c, cpp and cpp/obs, and the py, swift, kt, go and
dart wrappers) carries media timestamps as an exact `{value, scale}` record
mirroring `moq_net::Timestamp`, with untimed as absent. It replaces the lossy
microsecond fields on frames, datagrams, media and audio frames, producer
arguments, and the data values that
[Data consumer timestamps](/quest/m1/data-consumer-timestamps.md) adds.

The Rust core and `@moq/net` already carry exact timestamps. Wire: none.
Public API: breaking in every binding.

## Plan

Today every binding speaks microseconds: moq-ffi `timestamp_us: Option<u64>`
(about 160 sites in 9 files: `MoqFrame`, `MoqDatagram`, `MoqMediaFrame`, audio
frames, json/flate producer `update`/`append`, media `flush`), moq-c
`timestamp_us` plus `timestamp_present` pairs (about 140 sites in 6 files), and
each wrapper's native type (Python `timedelta`, Go `*time.Duration`, Swift
`UInt64`, Kotlin `Duration`, Dart `int`, C++ `std::optional<uint64_t>`, OBS
microseconds). Reads floor through `as_micros()`, so any scale that does not
divide a microsecond loses: a 90 kHz tick reads as 11 µs, and republishing it
onto a 90 kHz track floors again to tick 0.

Decided with the maintainer on 2026-10-18:

- **Scope is the bindings only.** The core and JS types stay as they are.
- **m1**, beside data consumer timestamps.
- **Lands after #5677**, which ships the data-value timestamps with the
interim microsecond fields; this quest converts every site at once,
`MoqJsonValue` included.
- **Shape mirrors the core:** one `{value, scale}` per value, `value` at most
`2^62 - 1` and `scale` non-zero and at most `2^62 - 1`, matching
`Timestamp::new` and `Timescale::new`. The FFI boundary refuses anything else with
an error. Rejected: raw ticks at the track scale beside
`MoqTrackInfo.timescale`, because a producer argument needs its own scale
and per-value records match the core and JS.
- **Names:** UniFFI record `MoqTimestamp`, C `moq_timestamp`, wrappers
`Timestamp`.
- **C untimed is a nullable pointer:** `const moq_timestamp *`, `NULL` for
untimed, in arguments and callback structs. No sentinel scale and no
`_present` flag; the existing `timestamp_present` pairs go.
- **Wrappers expose the record plus duration helpers** to and from the
language's duration type (`timedelta`, `Duration`, `time.Duration`, ...).
From a duration is exact at the duration's own scale. To a duration rounds
to nearest and says so in its doc; the record itself stays exact.
- **One PR across every binding**, per the cross-package sync table, so each
binding breaks once. No shim: the microsecond fields are removed, not kept
beside the record. Each package gets a `MIGRATE.md` entry, and `doc/lib/*`
and `doc/bin/obs.md` update in the same PR.

Verification: round-trip a 90 kHz tick, a present zero, and untimed through
moq-ffi, moq-c, C++ and every wrapper's tests; refuse scale 0, an
out-of-range scale, and an out-of-range value; `just test interop --all`.

## Related

- [Data consumer timestamps](/quest/m1/data-consumer-timestamps.md) - lands first with the interim microsecond fields this replaces
- [Controlled time](/quest/m1/time/README.md) - wall and monotonic time, not media timestamps; keep the types distinct