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
4 changes: 2 additions & 2 deletions cpp/moq/bench/main.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -121,7 +121,7 @@ void throughput(Case c, double budget, std::vector<Result> &results)
readers.push_back(read(c, consumer, payload, n).completion);
}
for (auto &track : tracks) {
auto group = ok(track->append_group());
auto group = ok(track->append_group(moq::Timestamp{n * c.frames(), 1000000}));
for (int f = 0; f < c.frames(); ++f)
ok(group->write_frame({payload, moq::Timestamp{n * c.frames() + f, 1000000}}));
ok(group->finish());
Expand Down Expand Up @@ -183,7 +183,7 @@ int main()

auto broadcast = ok(moq::BroadcastProducer::init());
auto track = ok(broadcast->publish_track("calls", {}));
auto producer = ok(track->append_group());
auto producer = ok(track->append_group(moq::Timestamp{0, std::nullopt}));
auto group = ok(producer->consume());
auto consumer = ok(track->consume({}));
auto call = [&](const char *name, auto fn) {
Expand Down
6 changes: 4 additions & 2 deletions dart/moq/bench/ffi.dart
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,9 @@ Future<void> throughput(
Future<void> step(int n) async {
final readers = [for (final consumer in consumers) read(consumer, n)];
for (final track in tracks) {
final group = track.appendGroup();
final group = track.appendGroup(
start: Timestamp(value: n * c.frames, scale: 1000000),
);
try {
for (var f = 0; f < c.frames; f++) {
group.writeFrame(
Expand Down Expand Up @@ -156,7 +158,7 @@ Future<void> main() async {
}
final broadcast = BroadcastProducer();
final track = broadcast.publishTrack(name: 'calls', info: null);
final producer = track.appendGroup();
final producer = track.appendGroup(start: Timestamp.unscaled(0));
final group = producer.consume();
final consumer = track.consume(subscription: null);
void call(String name, Object? Function() fn) {
Expand Down
8 changes: 5 additions & 3 deletions dart/moq/test/moq_test.dart
Original file line number Diff line number Diff line change
Expand Up @@ -247,7 +247,9 @@ void main() {
info: TrackInfo(maxAge: null, timescale: 1000000),
);
for (var ms = 0; ms < 3; ms++) {
final group = track.appendGroup();
final group = track.appendGroup(
start: Duration(milliseconds: ms).toTimestamp(),
);
group.writeFrame(
frame: Frame(
payload: utf8.encode('x'),
Expand All @@ -269,7 +271,7 @@ void main() {
final group = await consumer.recvGroup().timeout(timeout);
starts.add(group!.start());
}
expect(starts, [0, 1, 2]);
expect(starts, [0, 1000, 2000]);
broadcast.close();
},
);
Expand Down Expand Up @@ -538,7 +540,7 @@ void main() {
final demand = track.demand();
while (await demand.wantedChanged().timeout(timeout) == null) {}

final producer = track.appendGroup();
final producer = track.appendGroup(start: Duration.zero.toTimestamp());
producer.writeFrame(
frame: MoqFrame(
payload: utf8.encode('dart round trip'),
Expand Down
4 changes: 3 additions & 1 deletion dart/moq_ffi/test/leak_test.dart
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,9 @@ void main() {
info: MoqTrackInfo(timescale: 1000000),
);
final consumer = track.consume(subscription: null);
final producer = track.appendGroup();
final producer = track.appendGroup(
start: MoqTimestamp(value: 0, scale: 1000000),
);
producer.writeFrame(
frame: MoqFrame(
payload: payload,
Expand Down
8 changes: 6 additions & 2 deletions dart/moq_ffi/test/smoke_test.dart
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,9 @@ void main() {
info: null,
);
final consumer = track.consume(subscription: null);
final producer = track.appendGroup();
final producer = track.appendGroup(
start: MoqTimestamp(value: 0, scale: null),
);
final group = await consumer.nextGroup();
producer.abort(errorCode: 404);
await expectLater(
Expand Down Expand Up @@ -52,7 +54,9 @@ void main() {
final consumer = track.consume(subscription: null);
final nextGroup = consumer.nextGroup();

final producer = track.appendGroup();
final producer = track.appendGroup(
start: MoqTimestamp(value: 0, scale: 1000000),
);
producer.writeFrame(
frame: MoqFrame(
payload: utf8.encode('dart'),
Expand Down
2 changes: 1 addition & 1 deletion doc/lib/c/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -128,7 +128,7 @@ inside. The header is the reference: each function carries a doc comment.
- **Discovery.** Announcement captures are always a list of wildcard matches, empty when the filter has no wildcards.
- **Ending cleanly.** When the input ends, finish every track, then call `moq_publish_catalog_finish()` to finish the catalog, which ends the content. The broadcast stays announced and keeps serving the finished tracks, so a subscriber still catching up can drain them, until `moq_publish_close()` or `moq_route_free()` takes it offline. How long to keep it up is yours to decide. A track still open at the close ends with `UNROUTABLE` (an internal error over moq-transport, which has no such code), and its handle is released. Readers follow a publisher's runs by announcement, not by that error: see [identity and recovery](/concept/identity).
- **Timeline breaks.** On a seek or pause, call `moq_publish_media_discontinuity`, then keep timestamps moving forward and resume video on a keyframe.
- **Timestamps.** A `moq_timestamp` is exact: `value` units at `scale` units per second, so a 90 kHz tick survives a read and republish. Frames, datagrams, and JSON values point `timestamp` at theirs, valid as long as the payload. An untimed track has no scale, so there `has_scale` is false and `value` is the frame's group key (a datagram's sequence); every write takes one, with `moq_publish_group_start` naming a group's key. Stream tracks moq-c creates are timed, so their raw writes need one. Datagram tracks are separate and default to untimed; set their timescale when creating them to require timestamps. Stamp media frames and JSON writes from `moq_publish_catalog_now()`, the broadcast clock every track in the broadcast shares; media on a timeline of its own advertises the gap to the JSON tracks as catalog `delay`. JSON writes are converted to their track's milliseconds. A NULL timestamp on any write fails with `MOQ_ERROR_INVALID_POINTER`. A zero scale with `has_scale` set, or an out-of-range value, fails with `MOQ_ERROR_TIMESTAMP_OVERFLOW`.
- **Timestamps.** A `moq_timestamp` is exact: `value` units at `scale` units per second, so a 90 kHz tick survives a read and republish. Frames, datagrams, and JSON values point `timestamp` at theirs, valid as long as the payload. An untimed track has no scale, so there `has_scale` is false and `value` is the frame's group key (a datagram's sequence); every write and `moq_publish_track_group` takes one, with `moq_publish_group_start` naming a group's key. Stream tracks moq-c creates are timed, so their raw writes need one. Datagram tracks are separate and default to untimed; set their timescale when creating them to require timestamps. Stamp media frames and JSON writes from `moq_publish_catalog_now()`, the broadcast clock every track in the broadcast shares; media on a timeline of its own advertises the gap to the JSON tracks as catalog `delay`. JSON writes are converted to their track's milliseconds. A NULL timestamp on any write fails with `MOQ_ERROR_INVALID_POINTER`. A zero scale with `has_scale` set, or an out-of-range value, fails with `MOQ_ERROR_TIMESTAMP_OVERFLOW`.
- **Catalog timing.** Each catalog snapshot from `moq_consume_catalog` takes effect at the media timestamp `moq_consume_catalog_timestamp` fills. A zero `delay_us` delivers only the newest catalog; a player that holds each update until its media reaches that time passes its playout delay instead, and receives in order every update it may still need.
- **JSON values.** `moq_consume_json_value` fills `moq_json_value` with the document and its frame's timestamp. A snapshot consumer's callback fires for each state in order, but a group superseded before it is read is skipped.
- **JSON windows.** `moq_publish_json_window` publishes a sliding run of records: `moq_publish_json_window_push` appends at the back, `moq_publish_json_window_pop` drops from the front, and `moq_publish_json_window_cut` closes the open group at a natural boundary. The catalog has no window mode, so a reader names the track. `moq_consume_json_window_event` fills `moq_json_window_event` with a push (the record at `start`, in `json`), a pop of `[start, end)`, or a skip of `[start, end)` that this reader joined too late to receive. Set `checkpoint_records` to bound what each new group restates for a window you never pop.
Expand Down
2 changes: 1 addition & 1 deletion doc/lib/dart/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -135,7 +135,7 @@ final route = moq.route('live/camera'); // visible at once, under a fresh instan
print(route.instance());
final mine = route.broadcast();
final track = mine.publishTrack(name: 'video', info: null);
final group = track.appendGroup();
final group = track.appendGroup(start: Timestamp.unscaled(0));
group.writeFrame(frame: Frame(payload: bytes, timestamp: Timestamp.unscaled(group.start())));
group.finish();
track.finish();
Expand Down
2 changes: 1 addition & 1 deletion go/wrapper/errors_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ func TestStreamAbortProtocolDetails(t *testing.T) {
if err != nil {
t.Fatal(err)
}
producer, err := track.AppendGroup()
producer, err := track.AppendGroup(moq.Unscaled(0))
if err != nil {
t.Fatal(err)
}
Expand Down
14 changes: 7 additions & 7 deletions go/wrapper/moq_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -717,7 +717,7 @@ func TestFetchGroupAndServeDynamicMiss(t *testing.T) {
t.Fatal(err)
}

cached, err := track.AppendGroup()
cached, err := track.AppendGroup(ts(0))
if err != nil {
t.Fatal(err)
}
Expand Down Expand Up @@ -933,7 +933,7 @@ func TestTrackPublishConsume(t *testing.T) {
t.Fatalf("frame = %+v, want payload=hello ts=12345", frame)
}

group, err := track.AppendGroup()
group, err := track.AppendGroup(ts(23_456))
if err != nil {
t.Fatal(err)
}
Expand Down Expand Up @@ -976,7 +976,7 @@ func TestAscendingSubscriptionReadsCachedBacklogOldestFirst(t *testing.T) {
t.Fatal(err)
}
for i := range 3 {
group, err := track.AppendGroup()
group, err := track.AppendGroup(ts(uint64(i) * 1000))
if err != nil {
t.Fatal(err)
}
Expand Down Expand Up @@ -1010,8 +1010,8 @@ func TestAscendingSubscriptionReadsCachedBacklogOldestFirst(t *testing.T) {
}
starts = append(starts, group.Start())
}
if !slices.Equal(starts, []uint64{0, 1, 2}) {
t.Fatalf("starts = %v, want [0 1 2]", starts)
if !slices.Equal(starts, []uint64{0, 1_000, 2_000}) {
t.Fatalf("starts = %v, want [0 1000 2000]", starts)
}
}

Expand All @@ -1033,7 +1033,7 @@ func TestReadFrameSkipsEmptyThenPopulatedGroups(t *testing.T) {
}
defer consumer.Cancel()

empty, err := track.AppendGroup()
empty, err := track.AppendGroup(ts(0))
if err != nil {
t.Fatal(err)
}
Expand Down Expand Up @@ -1333,7 +1333,7 @@ func TestRecvGroupCancelKeepsConsumer(t *testing.T) {
t.Fatalf("cancelled RecvGroup = %v, want context.Canceled", err)
}

group, err := track.AppendGroup()
group, err := track.AppendGroup(moq.Unscaled(0))
if err != nil {
t.Fatal(err)
}
Expand Down
8 changes: 5 additions & 3 deletions go/wrapper/publish.go
Original file line number Diff line number Diff line change
Expand Up @@ -189,9 +189,11 @@ func (t *TrackProducer) Requests() (*TrackRequests, error) {
return &TrackRequests{inner: inner}, nil
}

// AppendGroup starts a new group; write frames into it, then Finish.
func (t *TrackProducer) AppendGroup() (*GroupProducer, error) {
inner, err := t.inner.AppendGroup()
// AppendGroup starts the next group at start, converted to the track's timescale
// (on a scale-less track, Unscaled at the group's key); write frames into it, then
// Finish. A start at or before a group the track holds is refused.
func (t *TrackProducer) AppendGroup(start Timestamp) (*GroupProducer, error) {
inner, err := t.inner.AppendGroup(start)
if err != nil {
return nil, err
}
Expand Down
4 changes: 2 additions & 2 deletions go/wrapper/runtime_bench_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -97,7 +97,7 @@ func BenchmarkFFI(b *testing.B) {
}
b.Run("call/start", func(b *testing.B) {
track := benchTrack(b, "calls")
producer, err := track.AppendGroup()
producer, err := track.AppendGroup(moq.Unscaled(0))
if err != nil {
b.Fatal(err)
}
Expand Down Expand Up @@ -210,7 +210,7 @@ func benchThroughput(b *testing.B, c benchCase) {
}()
}
for _, track := range tracks {
group, err := track.AppendGroup()
group, err := track.AppendGroup(moq.TimestampFromScale(uint64(n*frames), 1_000_000))
if err != nil {
return err
}
Expand Down
14 changes: 7 additions & 7 deletions kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt
Original file line number Diff line number Diff line change
Expand Up @@ -136,7 +136,7 @@ class SmokeTest {
fun `stream abort preserves protocol details`() = runTest {
BroadcastProducer().use { broadcast ->
val track = broadcast.publishTrack("errors", null)
val producer = track.appendGroup()
val producer = track.appendGroup(Timestamp.unscaled(0uL))
val group = broadcast.consume().fetchGroup("errors", 0uL, FetchGroupOptions())
producer.abort(404u)
val error = assertFailsWith<MoqException.Protocol> { group.readFrame() }
Expand Down Expand Up @@ -322,7 +322,7 @@ class SmokeTest {
"events",
TrackInfo(maxAge = java.time.Duration.ZERO, timescale = 1_000_000uL),
)
val group = track.appendGroup()
val group = track.appendGroup(Timestamp(0uL, 1_000_000uL))
group.writeFrame(
Frame(
payload = "cached".encodeToByteArray(),
Expand Down Expand Up @@ -360,7 +360,7 @@ class SmokeTest {
TrackInfo(maxAge = null, timescale = 1_000_000uL),
)
for (ms in 0uL until 3uL) {
val group = track.appendGroup()
val group = track.appendGroup(Timestamp(ms, 1_000uL))
group.writeFrame(
Frame(payload = "x".encodeToByteArray(), timestamp = Timestamp(ms, 1_000uL))
)
Expand All @@ -379,7 +379,7 @@ class SmokeTest {
)
)
val starts = List(3) { checkNotNull(consumer.recvGroup()).start() }
assertEquals(listOf(0uL, 1uL, 2uL), starts)
assertEquals(listOf(0uL, 1_000uL, 2_000uL), starts)
}
}

Expand Down Expand Up @@ -417,8 +417,8 @@ class SmokeTest {
TrackInfo(maxAge = java.time.Duration.ZERO, timescale = 1_000_000uL),
)
val consumer = track.consume(null)
track.appendGroup().finish()
track.appendGroup().finish()
track.appendGroup(Timestamp(0uL, 1_000_000uL)).finish()
track.appendGroup(Timestamp(1_000uL, 1_000_000uL)).finish()
track.writeFrame(
Frame(
payload = "populated".encodeToByteArray(),
Expand Down Expand Up @@ -831,7 +831,7 @@ class SmokeTest {
fun `a flow releases its handle however collection ends`() = runTest {
BroadcastProducer().use { broadcast ->
val track = broadcast.publishTrack("thrown", null)
track.appendGroup().finish()
track.appendGroup(Timestamp.unscaled(0uL)).finish()
// Finished, so a handle left open would read the end instead of failing.
track.finish()
val consumer = broadcast.consume().subscribeTrack("thrown", null)
Expand Down
5 changes: 3 additions & 2 deletions kt/moq/src/jvmTest/kotlin/dev/moq/FfiBench.kt
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ class FfiBench {

val broadcast = BroadcastProducer()
val track = broadcast.publishTrack("calls", null)
val producer = track.appendGroup()
val producer = track.appendGroup(Timestamp.unscaled(0uL))
val group = producer.consume()
call("start", results) { group.start() }
val consumer = track.consume(null)
Expand Down Expand Up @@ -118,7 +118,8 @@ class FfiBench {
}
}
tracks.forEach { track ->
track.appendGroup().use { group ->
track.appendGroup(Timestamp((n * case.frames).toULong(), 1_000_000uL)).use {
group ->
repeat(case.frames) { f ->
group.writeFrame(
Frame(
Expand Down
4 changes: 2 additions & 2 deletions py/moq-rs/benches/ffi.py
Original file line number Diff line number Diff line change
Expand Up @@ -81,7 +81,7 @@ async def step(n: int) -> None:
# Each consumer reads on its own task while this one writes each group in turn.
readers = [asyncio.create_task(read(case, consumer, payload, n)) for consumer in consumers]
for track in tracks:
group = track.append_group()
group = track.append_group(moq.Timestamp(n * case.frames, 1_000_000))
for f in range(case.frames):
group.write_frame(payload, moq.Timestamp(n * case.frames + f, 1_000_000))
group.finish()
Expand Down Expand Up @@ -170,7 +170,7 @@ async def main() -> None:
await throughput(case, results)

track = moq.BroadcastProducer().publish_track("calls")
group = track.append_group().consume()
group = track.append_group(moq.Timestamp.unscaled(0)).consume()
call("start", lambda: group.start, results)
consumer = track.consume()
call("info", consumer.info, results)
Expand Down
2 changes: 1 addition & 1 deletion py/moq-rs/examples/clock.py
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ async def publish(url: str, broadcast_name: str, track_name: str, insecure: bool
while True:
now = datetime.now(timezone.utc).replace(microsecond=0)
timestamp = moq.Timestamp(int(now.timestamp()), 1)
group = track.append_group()
group = track.append_group(timestamp)
group.write_frame(now.strftime("%Y-%m-%d %H:%M:").encode(), timestamp)

current_minute = now.minute
Expand Down
2 changes: 1 addition & 1 deletion py/moq-rs/examples/serve_clock.py
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ async def run(bind: str, broadcast_name: str, track_name: str, host: str) -> Non
while True:
now = datetime.now(timezone.utc).replace(microsecond=0)
timestamp = moq.Timestamp(int(now.timestamp()), 1)
group = track.append_group()
group = track.append_group(timestamp)
group.write_frame(now.strftime("%Y-%m-%d %H:%M:").encode(), timestamp)

current_minute = now.minute
Expand Down
11 changes: 8 additions & 3 deletions py/moq-rs/moq/publish.py
Original file line number Diff line number Diff line change
Expand Up @@ -134,9 +134,14 @@ def requests(self) -> TrackRequests:
"""Serve fetches for groups that are not currently cached."""
return TrackRequests(self._inner.requests())

def append_group(self) -> GroupProducer:
"""Start a new group; write frames into it, then finish()."""
return GroupProducer(self._inner.append_group())
def append_group(self, start: Timestamp) -> GroupProducer:
"""Start the next group at ``start``; write frames into it, then finish().

``start`` is converted to the track's timescale; on a scale-less track it is
:meth:`Timestamp.unscaled` at the group's key. A start at or before a group the
track holds is refused.
"""
return GroupProducer(self._inner.append_group(start._ffi()))

def create_group(self, start: int) -> GroupProducer:
"""Create a group with an explicit start."""
Expand Down
Loading