Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
102 commits
Select commit Hold shift + click to select a range
7b9c311
chore(quest): claim quest/m2/time-addressing/model.md
kixelated Nov 13, 2026
a0bd3c8
refactor(moq-net): name a group by its key, not a sequence
kixelated Nov 13, 2026
e01a1ef
wip: key-addressed groups (does not compile yet)
kixelated Nov 13, 2026
15958d1
wip: moq-net lib compiles with key-addressed anchors
kixelated Nov 13, 2026
f177d6e
wip: reach from a group's own end, scale-less max age in bare units
kixelated Nov 13, 2026
e7c4c4f
wip: strict start ties, no send-time stamping on lite-05/06
kixelated Nov 13, 2026
416c71d
wip: IETF relative filters count groups, priority wraps wide keys, dr…
kixelated Nov 13, 2026
641dbab
wip: moq-net unit tests compile for key-addressed groups
kixelated Nov 13, 2026
1751406
wip: tests stamp groups at their keys, since starts strictly increase
kixelated Nov 13, 2026
30c1b9a
wip: moq-net lib tests pass for key-addressed groups
kixelated Nov 13, 2026
d9b1338
doc: groups are addressed by their start
kixelated Nov 13, 2026
be96ce7
quest: collapse a window's layered runs once time ends stop walking
kixelated Nov 13, 2026
c50750b
fix(moq-net): Range::span only where a wire uses it
kixelated Nov 13, 2026
29847ef
test(moq-net): compile the integration tests against key-addressed gr…
kixelated Nov 13, 2026
961e5ac
bench(moq-net): key groups by their start in benches and the charge test
kixelated Nov 13, 2026
3c061a5
test(moq-net-tests): address groups by start
kixelated Nov 13, 2026
9e66956
test(moq-net): stamp each test frame at its group's start
kixelated Nov 13, 2026
474e98f
test(moq-net): meet the key model's range and timestamp semantics
kixelated Nov 13, 2026
8dac640
style(moq-net): format the migrated tests and benches
kixelated Nov 13, 2026
9be354d
bench(moq-net): name a group's start by its field shorthand
kixelated Nov 13, 2026
d2ed1af
fix(moq-net): legacy copies resolve time starts as their upstream does
kixelated Nov 13, 2026
8e9940e
fix(moq-net): a recovery subscription records the publisher's skips
kixelated Nov 13, 2026
0d761e3
fix(moq-net): a lite-07 copy places a time start only once it knows
kixelated Nov 13, 2026
b9ac2e2
chore(moq-net): fix a stale comment and the runtime-free model test
kixelated Nov 13, 2026
cf1f259
moq-json: key groups by their first frame's timestamp
kixelated Nov 13, 2026
e32df10
moq-crypto: address signed and encrypted groups by start
kixelated Nov 13, 2026
7895f62
moq-stats: start snapshot groups at their drain's timestamp
kixelated Nov 13, 2026
c1aa141
moq-archive: address groups by start
kixelated Nov 13, 2026
8c0b8e4
moq-mux: key groups by their first frame's timestamp
kixelated Nov 13, 2026
027179e
moq-bench: start groups at their keyframe's millisecond
kixelated Nov 13, 2026
b7961be
moq-tokio: stamp groups at their start
kixelated Nov 13, 2026
d59353e
moq-relay: fetch groups by start
kixelated Nov 13, 2026
bb33f8e
moq-uring: key test and bench groups by start
kixelated Nov 13, 2026
714080a
hang: start the example's catalog group at zero
kixelated Nov 13, 2026
1ebad61
moq-boy, moq-gst: address groups by start
kixelated Nov 13, 2026
3e571f5
moq-archive: record in start order through moq-net's ordered reader
kixelated Nov 13, 2026
b577d47
moq-hls: list each segment's groups by start
kixelated Nov 13, 2026
9c151a5
moq-archive, moq-hls: rustfmt
kixelated Nov 13, 2026
b1ec3c6
moq-transcode: start each output group where its source group does
kixelated Nov 13, 2026
dc5e37d
moq-video, moq-webrtc: address groups by start
kixelated Nov 13, 2026
edbd7af
moq-ffi, moq-c: address groups by start
kixelated Nov 13, 2026
cb4a3f5
moq-audio: end each packet group whole at its last packet's end
kixelated Nov 13, 2026
c178a10
moq-cli, interop clients: address groups by start
kixelated Nov 13, 2026
d96cf9a
doc: describe groups keyed by start in the Rust and CLI pages
kixelated Nov 13, 2026
4520d72
moq-ffi: tests start each group past the last
kixelated Nov 13, 2026
4e7b87e
moq-c, moq-ffi, moq-mux: key seeks and drop time lookups in the bindings
kixelated Nov 13, 2026
3b070fc
moq-c: request tests keep reading while a lookup is dropped
kixelated Nov 13, 2026
585804c
moq-json: own Timed, which moq-net never used
kixelated Nov 13, 2026
27a35ce
fix(moq-net): a whole group ages only once its own end comes
kixelated Nov 13, 2026
c3116aa
feat(moq-net): the next group in range passes over declared skips
kixelated Nov 13, 2026
058358e
feat(moq-net): Subscriber::is_skipped asks whether a run was never pr…
kixelated Nov 13, 2026
e391fc9
moq-mux, moq-audio: tell a track's first group by the skip below it
kixelated Nov 13, 2026
d20eaa7
moq-mux: a discontinuity marker never lands below the last frame
kixelated Nov 13, 2026
ee857f8
moq-mux: a run declared skipped between two groups loses nothing
kixelated Nov 13, 2026
903bb03
moq-mux: passthrough tests place the break marker by start
kixelated Nov 13, 2026
5012254
moq-mux: the consumer docs say a declared skip holds no group
kixelated Nov 13, 2026
1526b88
feat(moq-net): the next group in range passes over drops for good
kixelated Nov 13, 2026
278b2f7
moq-hls: a hole-less lite reader records once its feed budget passes
kixelated Nov 13, 2026
b60d25a
moq-audio: lose a group after an end by leaving its starts undeclared
kixelated Nov 13, 2026
2c326b4
moq-audio: never stamp a packet below where the packets before it end
kixelated Nov 13, 2026
41bcd2e
moq-video: a latest join counts back its lookback in groups
kixelated Nov 13, 2026
2c81f4c
moq-cli: a lost-group press seeks to its own start
kixelated Nov 13, 2026
cc0c007
moq-cli: a video join counts back its lookback in groups
kixelated Nov 13, 2026
4dc64e4
moq-mux, @moq/hang: Legacy audio reads each packet's duration from it…
kixelated Nov 13, 2026
b931fa8
moq-mux: a dropped run waits for the next group's first frame
kixelated Nov 13, 2026
b99563f
Restate transcode and Python tests by start; fmt and clippy
kixelated Nov 13, 2026
79880d6
Bindings: name media groups by start; regenerate Dart and the hang AP…
kixelated Nov 13, 2026
19ea717
moq-c: drop the relative update test whose open range now holds the n…
kixelated Nov 13, 2026
0dba549
moq-net: a lite-05/06 end declared before the start follows SUBSCRIBE…
kixelated Nov 13, 2026
b4d89e8
moq-net: a resumed reader reads a drained copy again once its range w…
kixelated Nov 13, 2026
f952d10
moq-mux: deliver a frame that lands mid-poll before judging a skip
kixelated Nov 13, 2026
489e1e0
Merge origin/main into quest/m2/time-addressing/model
kixelated Nov 13, 2026
290e1e8
Merge origin/main into quest/m2/time-addressing/model
kixelated Nov 13, 2026
a40cdc3
Merge remote-tracking branch 'origin/main' into HEAD
kixelated Nov 14, 2026
a55d34e
wip: unscaled Timestamp through moq-net and moq-json
kixelated Nov 14, 2026
cf84d56
feat(moq-net)!: a scale-less timestamp is an unscaled Timestamp
kixelated Nov 14, 2026
4bbf407
Merge remote-tracking branch 'origin/main' into HEAD
kixelated Nov 14, 2026
749b22d
fix: address the first local review of the start-addressed model
kixelated Nov 14, 2026
410ffc6
fix(moq-transcode): keep gap drops whole when the source can't answer…
kixelated Nov 14, 2026
dd8756c
fix(moq-transcode): a retired rung refuses the gap it can't place
kixelated Nov 14, 2026
0bf2e87
fix(moq-transcode): answer a fill's miss before looking for the rest …
kixelated Nov 14, 2026
368e86c
Merge origin/main into quest/m2/time-addressing/model
kixelated Nov 14, 2026
0c9745d
fix(moq-hls): key each group after a reanchor by its keyframe
kixelated Nov 14, 2026
7111c9a
fix(moq-ffi,moq-c): refuse a scaled time anchor rather than drop its …
kixelated Nov 14, 2026
dba4051
fix(moq-archive): resolve a time lookup by group key, as the live cac…
kixelated Nov 14, 2026
97d3730
quest(time-addressing): record the maintainer's acceptance of the /qu…
kixelated Nov 14, 2026
bd9942a
style: format the review fixes
kixelated Nov 14, 2026
41c3b98
fix(moq-video,moq-cli): join the warmup decoder with a time start eve…
kixelated Nov 14, 2026
5713c55
fix(json): keep a scale-less key exact past the safe number range
kixelated Nov 14, 2026
3512548
fix(moq-net): age a scale-less track's keys by distance over the whol…
kixelated Nov 14, 2026
66c4ffe
docs(net): record Time.keyOf in the API report
kixelated Nov 14, 2026
142e7fa
fix(moq-cli): wait for the video live edge only for a warmup lane
kixelated Nov 14, 2026
69b0140
Merge origin/main into quest/m2/time-addressing/model
kixelated Nov 14, 2026
35fa39a
Merge origin/main into quest/m2/time-addressing/model
kixelated Nov 14, 2026
64e1ae1
quest: move layered-runs to m3, since it breaks nothing and shouldn't…
kixelated Nov 14, 2026
bcd17e4
style(net): format the head-fill test
kixelated Nov 14, 2026
82ca7af
Merge origin/main into quest/m2/time-addressing/model
kixelated Nov 14, 2026
716cde5
Merge origin/main into quest/m2/time-addressing/model
kixelated Nov 15, 2026
05b252c
Merge origin/main into quest/m2/time-addressing/model
kixelated Nov 15, 2026
7b89888
Merge origin/main into quest/m2/time-addressing/model
kixelated Nov 15, 2026
e0761bb
fix(moq-hls): count a segment's groups past what any request fetches
kixelated Nov 15, 2026
a2942ba
Merge origin/main into quest/m2/time-addressing/model
kixelated Nov 15, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
2 changes: 1 addition & 1 deletion .claude/skills/verify-resume/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ Sync commit: `103052ed074a87f00269ecb0d639905482ecfb6f`. Run `git log 103052ed07
| `rs/moq-net/src/model/resume.rs` `Reader::bound_at_end`, `let_go`, `Copy::retains` | `BoundAtEnd`, `LetGo`, `Retains` |
| `rs/moq-net/src/model/resume.rs` `Reader::poll_end` | `PollEnd` |
| `rs/moq-net/src/model/resume.rs` `Producer::splice`, `serve_from`, the front's end | `Serve`, `FrontFinish`, `FrontFail` |
| `rs/moq-net/src/model/track.rs` `TrackState::is_complete`, `may_land`, `latest_sequence`, `track::Subscriber::has_unread_group` | `Seal`, `Held`, `MayLand`, `Latest`, `HasUnread` |
| `rs/moq-net/src/model/track.rs` `TrackState::is_complete`, `may_land`, `max_key`, `track::Subscriber::has_unread_group` | `Seal`, `Held`, `MayLand`, `Latest`, `HasUnread` |

## Not covered

Expand Down
6 changes: 5 additions & 1 deletion bench/browser/page/cmaf.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
/** CMAF fragment decode over fixed audio and video input, with no network in the timed phase. */
import * as CmafDecode from "@moq/hang/cmaf";
import { Time } from "@moq/net";
import { check } from "../fixture.ts";
import { longTasks, nextTask } from "./observe.ts";

Expand Down Expand Up @@ -44,6 +45,9 @@ async function prepare(next: Cmaf): Promise<void> {
decoded = undefined;
}

// A scale-less frame carries a group key and no time, so samples present at their tfdt.
const UNTIMED = Time.Timestamp.unscaled(0n);

async function decode(): Promise<Phase> {
const segment = init;
if (!config || !segment || fragments.length !== config.sizes.length) throw new Error("decode before prepare");
Expand All @@ -53,7 +57,7 @@ async function decode(): Promise<Phase> {
for (let iteration = 0; iteration < config.iterations; iteration++) {
decoded = fragments.map((fragment) => {
bytes += fragment.byteLength;
return CmafDecode.decodeDataSegment(fragment, segment, undefined);
return CmafDecode.decodeDataSegment(fragment, segment, UNTIMED);
});
}
const end = performance.now();
Expand Down
12 changes: 6 additions & 6 deletions c/moq/test/probe.c
Original file line number Diff line number Diff line change
Expand Up @@ -495,19 +495,19 @@ int main(void)
result reading = {0};
task = moq_track_consumer_read_frame(consumer, on_frame, &reading);
const uint8_t hello[] = {'h', 'e', 'l', 'l', 'o'};
moq_frame frame = moq_frame_default();
frame.payload.data = hello;
frame.payload.len = sizeof(hello);
moq_timestamp timestamp = {1000, 1000000};
frame.timestamp = &timestamp;
moq_frame frame = {
.payload = {.data = hello, .len = sizeof(hello)},
.timestamp = {.value = 1000, .scale = {.has_value = true, .value = 1000000}},
};
ok(moq_track_producer_write_frame(track, &frame), "write_frame");
moq_frame *received = await(&reading, "read_frame");
moq_task_free(task);
CHECK(received);
CHECK(received->payload.len == sizeof(hello));
CHECK(memcmp(received->payload.data, hello, sizeof(hello)) == 0);
/* Lite-07 carries both the Implementation parameter and frame timestamps, at any scale. */
CHECK(received->timestamp && received->timestamp->value * 1000000 == 1000 * received->timestamp->scale);
CHECK(received->timestamp.scale.has_value &&
received->timestamp.value * 1000000 == 1000 * received->timestamp.scale.value);
moq_frame_free(received);
CHECK(!cancelled.done);

Expand Down
3 changes: 1 addition & 2 deletions cpp/moq/bench/main.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -90,8 +90,7 @@ Reader read(Case c, std::shared_ptr<moq::TrackConsumer> consumer, const std::vec
require(group != nullptr);
for (int f = 0; f < c.frames(); ++f) {
auto frame = ok(co_await group->read_frame());
require(frame && frame->payload == payload && frame->timestamp &&
frame->timestamp->value == n * c.frames() + f);
require(frame && frame->payload == payload && frame->timestamp.value == n * c.frames() + f);
}
}

Expand Down
33 changes: 19 additions & 14 deletions cpp/moq/test/probe.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -105,11 +105,11 @@ Coroutine read_one(std::shared_ptr<moq::TrackConsumer> consumer, std::optional<m
}
#endif

// Whether two timestamps name the same instant at any scales; the probe's values are small
// enough that the cross products cannot overflow.
// Whether two scaled timestamps name the same instant at any scales; the probe's values are
// small enough that the cross products cannot overflow.
bool same_time(const moq::Timestamp &a, const moq::Timestamp &b)
{
return a.value * b.scale == b.value * a.scale;
return a.scale && b.scale && a.value * *b.scale == b.value * *a.scale;
}

// A datagram-only request reaches its own handler and demand.
Expand All @@ -127,18 +127,21 @@ void datagram_tracks()
auto producer = ok(request->accept(std::nullopt), "accept datagrams");
CHECK(ok(producer->priority(), "aggregate priority") == 12);
CHECK(!ok(stream->demand(), "stream demand")->wanted());
ok(producer->insert({7, std::nullopt, bytes("seven")}), "insert datagram");
// A scale-less datagram track has no time: its timestamp is the unscaled sequence.
ok(producer->insert({7, moq::Timestamp{7, std::nullopt}, bytes("seven")}), "insert datagram");
auto received = ok(consumer->recv().get(), "receive datagram");
CHECK(received && received->sequence == 7 && received->payload == bytes("seven"));
CHECK(received->timestamp.value == 7 && !received->timestamp.scale);
consumer->cancel();
CHECK(!ok(producer->priority_changed(12).get(), "released demand"));
ok(producer->finish(), "finish datagrams");
datagrams->cancel();
ok(broadcast->close(), "close datagram broadcast");
}

// Timestamps are exact records: a 90 kHz tick and a present zero read back as written, an
// untimed frame reads back untimed, and a record past the bounds is refused.
// Timestamps are exact records: a 90 kHz tick and a present zero read back as written, a
// scale-less track's unscaled group key reads back unscaled, and a record past the bounds is
// refused.
void timestamp_roundtrip()
{
auto broadcast = ok(moq::BroadcastProducer::init(), "timestamp broadcast");
Expand All @@ -149,8 +152,8 @@ void timestamp_roundtrip()
for (uint64_t value : {0, 1}) {
ok(track->write_frame({bytes("tick"), moq::Timestamp{value, 90000}}), "write tick");
auto frame = ok(consumer->read_frame().get(), "read tick");
CHECK(frame && frame->timestamp);
CHECK(frame->timestamp->value == value && frame->timestamp->scale == 90000);
CHECK(frame);
CHECK(frame->timestamp.value == value && frame->timestamp.scale == uint64_t(90000));
}
for (const moq::Timestamp &invalid :
{moq::Timestamp{0, 0}, moq::Timestamp{0, uint64_t(1) << 62}, moq::Timestamp{uint64_t(1) << 61, 90000}}) {
Expand All @@ -159,11 +162,13 @@ void timestamp_roundtrip()
CHECK(std::holds_alternative<moq::Error::kTimeOverflow>(refused.error().get_variant()));
}

auto untimed = ok(broadcast->publish_track("untimed", std::nullopt), "publish untimed track");
auto untimed_consumer = ok(untimed->consume(std::nullopt), "consume untimed track");
ok(untimed->write_frame({bytes("untimed"), std::nullopt}), "write untimed");
auto frame = ok(untimed_consumer->read_frame().get(), "read untimed");
CHECK(frame && !frame->timestamp);
auto untimed = ok(broadcast->publish_track("untimed", std::nullopt), "publish scale-less track");
auto untimed_consumer = ok(untimed->consume(std::nullopt), "consume scale-less track");
// An unscaled timestamp on a timed track is refused.
CHECK(!track->write_frame({bytes("tick"), moq::Timestamp{2, std::nullopt}}));
ok(untimed->write_frame({bytes("untimed"), moq::Timestamp{3, std::nullopt}}), "write unscaled");
auto frame = ok(untimed_consumer->read_frame().get(), "read unscaled");
CHECK(frame && frame->timestamp.value == 3 && !frame->timestamp.scale);
ok(broadcast->close(), "close timestamp broadcast");
}

Expand Down Expand Up @@ -430,7 +435,7 @@ int main()
CHECK(frame.has_value());
CHECK(frame->payload == bytes("hello"));
// Lite-07 carries both the Implementation parameter and frame timestamps.
CHECK(frame->timestamp && same_time(*frame->timestamp, {1000, 1000000}));
CHECK(same_time(frame->timestamp, {1000, 1000000}));

// A continuation receives the next frame on the executor.
{
Expand Down
7 changes: 5 additions & 2 deletions cpp/obs/src/moq-source.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -79,10 +79,13 @@ namespace {
struct moq_source;

// A track timestamp in the nanoseconds OBS stamps media with, floored when the scale does not
// divide a second evenly into nanoseconds.
// divide a second evenly into nanoseconds. Decoded media is always scaled; an unscaled group
// key has no time, so it maps to zero rather than dividing by a missing scale.
static uint64_t moq_source_nanoseconds(const moq::Timestamp &timestamp)
{
return util_mul_div64(timestamp.value, 1'000'000'000, timestamp.scale);
if (!timestamp.scale)
return 0;
return util_mul_div64(timestamp.value, 1'000'000'000, *timestamp.scale);
}

enum class Decoded { Pending, Ready, Failed };
Expand Down
7 changes: 5 additions & 2 deletions cpp/obs/test/moq-audio-encoder-test.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -278,12 +278,15 @@ void CheckSubscriberDecodes(const char *preset, size_t channels)
if (!variant)
break;
const auto *frame = &variant->frame;
CHECK(frame->timestamp.scale.has_value());
if (!frame->timestamp.scale)
break;
if (!first_decoded)
first_decoded = frame->timestamp;
const auto *samples = reinterpret_cast<const float *>(frame->data.data());
const size_t frames = frame->data.size() / sizeof(float) / channels;
const int64_t offset =
static_cast<int64_t>(frame->timestamp.value * RATE / frame->timestamp.scale) - (start + RATE);
static_cast<int64_t>(frame->timestamp.value * RATE / *frame->timestamp.scale) - (start + RATE);
for (size_t i = 0; i < frames; i++) {
const double expected = Tone(offset + static_cast<int64_t>(i));
for (size_t c = 0; c < channels; c++) {
Expand All @@ -298,7 +301,7 @@ void CheckSubscriberDecodes(const char *preset, size_t channels)
// OBS never drains an audio encoder, so the decoder trims the 312-sample pre-skip
// and nothing pads the tail: every input sample but that lookahead comes back.
// Compared as fractions of a second, since the track reads back at its own scale.
CHECK(first_decoded && first_decoded->value * RATE == sample(0) * first_decoded->scale);
CHECK(first_decoded && first_decoded->value * RATE == sample(0) * *first_decoded->scale);
CHECK(decoded == count * encoder.frame_size - 312);
CHECK(energy > 0 && error / energy < 0.05);
printf(" %s, %zu channels: %zu samples, error %.4f\n", preset, channels, decoded,
Expand Down
12 changes: 9 additions & 3 deletions cpp/obs/test/moq-source-test.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -1042,8 +1042,12 @@ int main()
CHECK(publisher.WriteUntil([&] { return g_output_audio >= audio + 3; }));
} else {
uint64_t timestamp_us = 2'000'000;
// The scale-less track carries the time in its payload, so each frame's timestamp
// is the unscaled key of the group it opens.
uint64_t key = 0;
CHECK(WaitFor([&] {
TestOk(pcm->write_frame(moq::Frame{PcmFrame(timestamp_us, channels), std::nullopt}),
TestOk(pcm->write_frame(moq::Frame{PcmFrame(timestamp_us, channels),
moq::Timestamp{key++, std::nullopt}}),
"write pcm");
timestamp_us += 20'000;
std::this_thread::sleep_for(std::chrono::milliseconds(10));
Expand Down Expand Up @@ -1476,10 +1480,12 @@ int main()
g_candidate = {candidate, false};
return true;
}));
// Each cut opens a group, so each retry starts later than the last.
uint64_t bad_us = 1'000'000'000;
CHECK(publisher.WriteUntil([&] {
TestOk(replacement->write_frame(moq::Frame{BAD_OPUS, Micros(1'000'000'000)}),
"replacement frame");
TestOk(replacement->write_frame(moq::Frame{BAD_OPUS, Micros(bad_us)}), "replacement frame");
TestOk(replacement->cut(), "replacement audio cut");
bad_us += 20'000;
std::lock_guard<std::mutex> lock(g_candidate_mutex);
return g_candidate.failed && candidate.expired();
}));
Expand Down
4 changes: 3 additions & 1 deletion dart/moq/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,9 @@ The package uses `Future` for asynchronous operations and `Stream` for
announcements, and `connect` / `listen` take an options struct like Rust does.
Types are spelled without the `Moq` prefix (`Session`, `BroadcastProducer`,
`Backoff`). Spans cross as a `Duration` (`stats.rtt`), and media times as an
exact `Timestamp` with `toDuration()`. The lower-level generated API
exact `Timestamp` with `toDuration()`; a track without a timescale has no
time, so its frames carry `Timestamp.unscaled(groupKey)` instead (a datagram,
its sequence). The lower-level generated API
remains available through the re-exported `moq_ffi` package.

Flutter Web is not supported. Browser applications should use the TypeScript
Expand Down
2 changes: 1 addition & 1 deletion dart/moq/bench/ffi.dart
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ Future<void> throughput(
final frame = await group.readFrame();
require(
frame != null &&
frame.timestamp?.value == n * c.frames + f &&
frame.timestamp.value == n * c.frames + f &&
frame.payload.length == payload.length &&
memcmp(frame.payload.address, payload.address, payload.length) ==
0,
Expand Down
6 changes: 3 additions & 3 deletions dart/moq/lib/json.dart
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ typedef StreamProducer = MoqJsonStreamProducer;
typedef StreamConsumer = MoqJsonStreamConsumer;

/// A JSON string read from a track, with the timestamp of the frame that
/// carried it, or null when untimed.
/// carried it, or its unscaled group key on a scale-less track.
typedef Value = MoqJsonValue;

/// Publishes a sliding window of JSON records on a track it takes over, pushed
Expand All @@ -75,6 +75,6 @@ typedef WindowEventPop = PopMoqJsonWindowEvent;
/// The records in `[start, end)` will never be delivered to this reader.
typedef WindowEventSkip = SkipMoqJsonWindowEvent;

/// A [WindowEvent] and the timestamp of the frame that carried it, or null
/// when untimed.
/// A [WindowEvent] and the timestamp of the frame that carried it, or its
/// unscaled group key on a scale-less track.
typedef WindowTimed = MoqJsonWindowTimed;
24 changes: 18 additions & 6 deletions dart/moq/lib/src/aliases.dart
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,11 @@ import 'package:moq_ffi/moq_ffi.dart';
// Re-export the UniFFI types without their `Moq` prefix, so consumers spell
// them the way the Rust API does. These are type aliases, not wrappers: the
// values are the exact same objects, so every generated method applies
// unchanged and the prefixed names stay valid. `Delay` and `Subscription` are
// extension types instead, which are the same objects too but give an omitted
// delay bound the zero moq-net defaults to, where the generated record leaves
// it null.
// unchanged and the prefixed names stay valid. `Delay`, `Subscription`, and
// `Timestamp` are extension types instead, which are the same objects too but
// add constructors: an omitted delay bound is the zero moq-net defaults to,
// where the generated record leaves it null, and a timestamp is built either
// scaled or [Timestamp.unscaled], as in Rust.
//
// Four types are deliberately not aliased, because the unprefixed name is
// already taken where this package is used:
Expand Down Expand Up @@ -144,14 +145,25 @@ typedef GroupProducer = MoqGroupProducer;
/// The read side of a single group: yields timestamped raw frames.
typedef GroupConsumer = MoqGroupConsumer;

/// A datagram payload with its own sequence and optional timestamp.
/// A datagram payload with its own sequence and timestamp.
typedef Datagram = MoqDatagram;

/// A payload plus the timestamp it should be presented at.
typedef Frame = MoqFrame;

/// An exact media time: `value` units at `scale` units per second.
typedef Timestamp = MoqTimestamp;
///
/// A scale-less track has no time, so there `scale` is null and `value` is the
/// frame's group key (a datagram's sequence), as [Timestamp.unscaled] builds.
/// Reads return the generated [MoqTimestamp], which this type implements.
extension type Timestamp._(MoqTimestamp _timestamp) implements MoqTimestamp {
/// `value` units at `scale` units per second.
Timestamp({required int value, required int scale})
: this._(MoqTimestamp(value: value, scale: scale));

/// The scale-less timestamp at group key `key`, or a datagram's sequence.
Timestamp.unscaled(int key) : this._(MoqTimestamp(value: key, scale: null));
}

/// How far behind the live edge a subscriber or decoder plays: where it starts, and how late it may fall.
extension type Delay._(MoqDelay _delay) implements MoqDelay {
Expand Down
15 changes: 11 additions & 4 deletions dart/moq/lib/src/timestamp.dart
Original file line number Diff line number Diff line change
@@ -1,15 +1,22 @@
import 'package:moq_ffi/moq_ffi.dart';

import 'aliases.dart';

final _microsPerSecond = BigInt.from(Duration.microsecondsPerSecond);

/// Converts a [MoqTimestamp] to Dart's [Duration].
extension TimestampDuration on MoqTimestamp {
/// This timestamp as a [Duration], rounded down to a whole microsecond.
///
/// The timestamp itself is exact; keep it, not the duration, to republish a
/// tick such as 90 kHz. Throws a [RangeError] when the result does not fit
/// in a [Duration].
/// tick such as 90 kHz. Throws a [StateError] when unscaled, since a
/// scale-less track's key is no time, and a [RangeError] when the result
/// does not fit in a [Duration].
Duration toDuration() {
final scale = this.scale;
if (scale == null) {
throw StateError('unscaled timestamp #$value has no time');
}
// value * 10^6 can exceed 64 bits at the allowed bounds.
final units = BigInt.from(scale);
final micros = BigInt.from(value) * _microsPerSecond ~/ units;
Expand All @@ -25,11 +32,11 @@ extension DurationTimestamp on Duration {
/// This duration as an exact timestamp at microsecond scale.
///
/// Throws an [ArgumentError] when negative.
MoqTimestamp toTimestamp() {
Timestamp toTimestamp() {
if (isNegative) {
throw ArgumentError.value(this, 'duration', 'must not be negative');
}
return MoqTimestamp(
return Timestamp(
value: inMicroseconds,
scale: Duration.microsecondsPerSecond,
);
Expand Down
Loading