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: 4 additions & 0 deletions c/moq/MIGRATE.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,10 @@ How to update your code for each breaking change, newest first.

The hand-written crate never published as moq-c: a libmoq 0.6 user applies these entries before moving to the generated API.

### JSON writes refuse a NULL timestamp ([#7691](https://github.com/moq-dev/moq/pull/7691))

`moq_publish_json_snapshot_update`, `moq_publish_json_stream_append`, `moq_publish_json_window_push`, and `moq_publish_json_window_pop` fail with `MOQ_ERROR_INVALID_POINTER` on a NULL `timestamp` instead of stamping the broadcast clock. Stamp media and JSON from `moq_publish_catalog_now()`; in the generated API, JSON `update`, `append`, `push`, and `pop` take a required `moq_timestamp` from the media catalog producer's `now`, and the JSON producers refuse a track without a timescale.

### Announcement captures are required ([#7484](https://github.com/moq-dev/moq/pull/7484))

`moq_announce_event.has_captures` is removed, changing the C ABI. Read `captures_len` directly: zero means the filter has no wildcards. Rebuild consumers against the regenerated header and matching native library.
Expand Down
4 changes: 4 additions & 0 deletions cpp/moq/MIGRATE.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,10 @@

## Unreleased

### JSON writes take a broadcast-clock timestamp ([#7691](https://github.com/moq-dev/moq/pull/7691))

`moq::JsonSnapshotProducer::update`, `moq::JsonStreamProducer::append`, and `moq::JsonWindowProducer::push` and `pop` take a required `moq::Timestamp` instead of an optional one. Stamp it from `moq::MediaCatalogProducer::now()`, the broadcast clock every track shares. Their constructors refuse a track created without a `timescale`. Regenerate bindings and rebuild with the matching native library.

### Subscriptions take a `moq::Delay` ([#7697](https://github.com/moq-dev/moq/pull/7697))

`moq::Subscription::max_delay` is `moq::Delay delay`: set `delay.max` to the old `max_delay`, or start from `moq::subscription_defaults()`.
Expand Down
4 changes: 4 additions & 0 deletions dart/moq/MIGRATE.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,10 @@ How to update your code for each breaking change, newest first.

## Unreleased

### JSON writes take a broadcast-clock timestamp ([#7691](https://github.com/moq-dev/moq/pull/7691))

`json.SnapshotProducer.update`, `json.StreamProducer.append`, and `json.WindowProducer.push` / `pop` take a `required MoqTimestamp timestamp` on the broadcast clock instead of an optional one. Read it with `MoqMediaCatalogProducer(broadcast: broadcast).now()`. Their track needs a timescale, such as `MoqTrackInfo(timescale: 1000)`; one without is refused.

### Subscriptions take a `Delay` ([#7697](https://github.com/moq-dev/moq/pull/7697))

`Subscription.maxDelay` is `delay`, a `Delay`, and a bare `Subscription()` is moq-net's defaults again: pass `delay: Delay(max: maxDelay)`, and `Delay(max: null)` for no subscriber limit.
Expand Down
13 changes: 10 additions & 3 deletions dart/moq/lib/json.dart
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,11 @@
/// which has no window mode), and a consumer takes over a `TrackConsumer` that
/// has not read a group yet. Values cross as JSON strings. Compression is the
/// track's: publish JSON with `MoqTrackInfo(compress: true)`, and a consumer
/// reads it with no option of its own. Import it with a prefix, since
/// `dart:convert` has a `json` too:
/// reads it with no option of its own. Every write (a snapshot update, a stream
/// append, a window push or pop) takes a timestamp on the broadcast clock, the
/// epoch every track in the broadcast shares, so the track needs a timescale;
/// one without is refused.
/// Import it with a prefix, since `dart:convert` has a `json` too:
///
/// ```dart
/// import 'package:moq/json.dart' as moq_json;
Expand All @@ -15,10 +18,14 @@
/// broadcast: broadcast,
/// track: broadcast.publishTrack(
/// name: 'status',
/// info: MoqTrackInfo(compress: true),
/// info: MoqTrackInfo(timescale: 1000, compress: true),
/// ),
/// config: moq_json.SnapshotConfig(),
/// );
/// status.update(
/// value: '{"state":"live"}',
/// timestamp: MoqMediaCatalogProducer(broadcast: broadcast).now(),
/// );
/// ```
library;

Expand Down
40 changes: 19 additions & 21 deletions dart/moq_ffi/lib/src/moq.dart
Original file line number Diff line number Diff line change
Expand Up @@ -10685,7 +10685,7 @@ class FfiConverterMoqJsonSnapshotConsumer {
abstract class MoqJsonSnapshotProducerInterface {
MoqTrackDemand demand();
void finish();
void update({required String value, MoqTimestamp? timestamp = null});
void update({required String value, required MoqTimestamp timestamp});
}

final _MoqJsonSnapshotProducerFinalizer = Finalizer<Pointer<Void>>((ptr) {
Expand Down Expand Up @@ -10762,12 +10762,12 @@ class MoqJsonSnapshotProducer implements MoqJsonSnapshotProducerInterface {
}, moqExceptionErrorHandler);
}

void update({required String value, MoqTimestamp? timestamp = null}) {
void update({required String value, required MoqTimestamp timestamp}) {
return rustCall((status) {
uniffi_moq_ffi_fn_method_moqjsonsnapshotproducer_update(
uniffiClonePointer(),
FfiConverterString.lower(value),
FfiConverterOptionalMoqTimestamp.lower(timestamp),
FfiConverterMoqTimestamp.lower(timestamp),
status,
);
}, moqExceptionErrorHandler);
Expand Down Expand Up @@ -10905,7 +10905,7 @@ class FfiConverterMoqJsonStreamConsumer {
}

abstract class MoqJsonStreamProducerInterface {
void append({required String value, MoqTimestamp? timestamp = null});
void append({required String value, required MoqTimestamp timestamp});
MoqTrackDemand demand();
void finish();
}
Expand Down Expand Up @@ -10962,12 +10962,12 @@ class MoqJsonStreamProducer implements MoqJsonStreamProducerInterface {
}
}

void append({required String value, MoqTimestamp? timestamp = null}) {
void append({required String value, required MoqTimestamp timestamp}) {
return rustCall((status) {
uniffi_moq_ffi_fn_method_moqjsonstreamproducer_append(
uniffiClonePointer(),
FfiConverterString.lower(value),
FfiConverterOptionalMoqTimestamp.lower(timestamp),
FfiConverterMoqTimestamp.lower(timestamp),
status,
);
}, moqExceptionErrorHandler);
Expand Down Expand Up @@ -11128,8 +11128,8 @@ abstract class MoqJsonWindowProducerInterface {
void cut();
MoqTrackDemand demand();
void finish();
void pop({required int count, MoqTimestamp? timestamp = null});
void push({required String value, MoqTimestamp? timestamp = null});
void pop({required int count, required MoqTimestamp timestamp});
void push({required String value, required MoqTimestamp timestamp});
}

final _MoqJsonWindowProducerFinalizer = Finalizer<Pointer<Void>>((ptr) {
Expand Down Expand Up @@ -11213,23 +11213,23 @@ class MoqJsonWindowProducer implements MoqJsonWindowProducerInterface {
}, moqExceptionErrorHandler);
}

void pop({required int count, MoqTimestamp? timestamp = null}) {
void pop({required int count, required MoqTimestamp timestamp}) {
return rustCall((status) {
uniffi_moq_ffi_fn_method_moqjsonwindowproducer_pop(
uniffiClonePointer(),
FfiConverterUInt64.lower(count),
FfiConverterOptionalMoqTimestamp.lower(timestamp),
FfiConverterMoqTimestamp.lower(timestamp),
status,
);
}, moqExceptionErrorHandler);
}

void push({required String value, MoqTimestamp? timestamp = null}) {
void push({required String value, required MoqTimestamp timestamp}) {
return rustCall((status) {
uniffi_moq_ffi_fn_method_moqjsonwindowproducer_push(
uniffiClonePointer(),
FfiConverterString.lower(value),
FfiConverterOptionalMoqTimestamp.lower(timestamp),
FfiConverterMoqTimestamp.lower(timestamp),
status,
);
}, moqExceptionErrorHandler);
Expand Down Expand Up @@ -21951,8 +21951,7 @@ void _checkApiChecksums() {
42593) {
throw UniffiInternalError.panicked("UniFFI API checksum mismatch");
}
if (uniffi_moq_ffi_checksum_method_moqjsonsnapshotproducer_update() !=
41112) {
if (uniffi_moq_ffi_checksum_method_moqjsonsnapshotproducer_update() != 7688) {
throw UniffiInternalError.panicked("UniFFI API checksum mismatch");
}
if (uniffi_moq_ffi_checksum_method_moqjsonstreamconsumer_cancel() != 29308) {
Expand All @@ -21961,7 +21960,7 @@ void _checkApiChecksums() {
if (uniffi_moq_ffi_checksum_method_moqjsonstreamconsumer_next() != 21257) {
throw UniffiInternalError.panicked("UniFFI API checksum mismatch");
}
if (uniffi_moq_ffi_checksum_method_moqjsonstreamproducer_append() != 57310) {
if (uniffi_moq_ffi_checksum_method_moqjsonstreamproducer_append() != 60414) {
throw UniffiInternalError.panicked("UniFFI API checksum mismatch");
}
if (uniffi_moq_ffi_checksum_method_moqjsonstreamproducer_demand() != 52854) {
Expand All @@ -21985,10 +21984,10 @@ void _checkApiChecksums() {
if (uniffi_moq_ffi_checksum_method_moqjsonwindowproducer_finish() != 49018) {
throw UniffiInternalError.panicked("UniFFI API checksum mismatch");
}
if (uniffi_moq_ffi_checksum_method_moqjsonwindowproducer_pop() != 58245) {
if (uniffi_moq_ffi_checksum_method_moqjsonwindowproducer_pop() != 24069) {
throw UniffiInternalError.panicked("UniFFI API checksum mismatch");
}
if (uniffi_moq_ffi_checksum_method_moqjsonwindowproducer_push() != 47237) {
if (uniffi_moq_ffi_checksum_method_moqjsonwindowproducer_push() != 56727) {
throw UniffiInternalError.panicked("UniFFI API checksum mismatch");
}
if (uniffi_moq_ffi_checksum_method_moqmediacatalogconsumer_cancel() !=
Expand Down Expand Up @@ -22441,22 +22440,21 @@ void _checkApiChecksums() {
throw UniffiInternalError.panicked("UniFFI API checksum mismatch");
}
if (uniffi_moq_ffi_checksum_constructor_moqjsonsnapshotproducer_new() !=
14914) {
37949) {
throw UniffiInternalError.panicked("UniFFI API checksum mismatch");
}
if (uniffi_moq_ffi_checksum_constructor_moqjsonstreamconsumer_new() != 3025) {
throw UniffiInternalError.panicked("UniFFI API checksum mismatch");
}
if (uniffi_moq_ffi_checksum_constructor_moqjsonstreamproducer_new() !=
20445) {
if (uniffi_moq_ffi_checksum_constructor_moqjsonstreamproducer_new() != 2022) {
throw UniffiInternalError.panicked("UniFFI API checksum mismatch");
}
if (uniffi_moq_ffi_checksum_constructor_moqjsonwindowconsumer_new() !=
48790) {
throw UniffiInternalError.panicked("UniFFI API checksum mismatch");
}
if (uniffi_moq_ffi_checksum_constructor_moqjsonwindowproducer_new() !=
43418) {
34390) {
throw UniffiInternalError.panicked("UniFFI API checksum mismatch");
}
if (uniffi_moq_ffi_checksum_constructor_moqmediacatalogconsumer_subscribe() !=
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 @@ -110,7 +110,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()` 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, NULL on an untimed track and valid as long as the payload. Tracks moq-c creates are timed, so their raw writes need one. JSON writes, including window pushes and pops, take one too, converted to their track's milliseconds; NULL stamps the broadcast clock's current time. A zero scale 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, NULL on an untimed track and valid as long as the payload. Tracks moq-c creates are timed, so their raw writes need one. 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 JSON write (snapshot update, stream append, window push or pop) fails with `MOQ_ERROR_INVALID_POINTER` and publishes nothing. A zero scale or an out-of-range value fails with `MOQ_ERROR_TIMESTAMP_OVERFLOW`.
- **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.
- **Decoded reads.** `moq_decode_audio` and `moq_decode_video` deliver read ids in order: a frame, a gap where media was lost, or an end where the publisher stopped its encoder. Check `kind` on what `moq_decode_audio_read` or `moq_decode_video_read` writes. Free each id with `moq_decode_audio_read_free` or `moq_decode_video_read_free` promptly: a held video frame holds a decoder buffer, and the decoder stalls. A decoder reads everything the track still holds unless a live player sets `start` to `MOQ_DECODE_START_LATEST`, which joins at the newest group and skips the cached backlog.
Expand Down
3 changes: 2 additions & 1 deletion doc/lib/dart/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,8 @@ container consumers. `TrackProducer.audio` / `.video` take a broadcast, an init
and a `Named` or `Requested` target. `CatalogProducer(broadcast: ...)` owns catalog properties
and sections; it holds the broadcast weakly and fails after the broadcast closes.
Publish JSON tracks with `MoqTrackInfo(compress: true)`; a `package:moq/json.dart` consumer reads one with no option of its own.
A missing data timestamp stays untimed; the library never substitutes zero or now.
A raw frame without a timestamp stays untimed, which only an untimed track accepts; JSON writes always take one. The library never substitutes zero or now.
`SnapshotProducer.update`, `StreamProducer.append`, and `WindowProducer.push` and `pop` require a timestamp on the broadcast clock (`CatalogProducer.now()`), the epoch every track in the broadcast shares, so their track needs a timescale.
`package:moq/json.dart` consumers return `Value` (`value`, `timestamp`) from `next()`; a snapshot consumer
yields each state in order, and `latest()` skips to the newest.
Media times are exact `Timestamp` records, `value` units at `scale` units per second, so a 90 kHz tick survives a
Expand Down
4 changes: 2 additions & 2 deletions doc/lib/go/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,10 +19,10 @@ and a `Named` or `Requested` target. `NewCatalogProducer` holds its broadcast we
catalog writes fail with `ErrClosed` after the broadcast closes. Media timestamps are exact
`moq.Timestamp` records (`Value` at `Scale` units per second), so a 90 kHz tick survives a read and republish;
`TimestampFromDuration` converts exactly; `TimestampToDuration` rounds down to a whole nanosecond.
A missing data timestamp stays untimed; the library never substitutes zero or now.
A raw frame without a timestamp stays untimed, which only an untimed track accepts; JSON writes always take one. The library never substitutes zero or now.
Raw tracks with a `nil` timescale are untimed on both publish and receive.
`TrackInfo.Compress` sends each group DEFLATE-compressed to opt-in `moq-lite-07-wip` peers; other peers, and every reader here, get the original frames. Set it on JSON tracks.
The JSON producers' `Update` / `Append` take a final `*moq.Timestamp` argument (`nil` for untimed).
The JSON producers' `Update`, `Append`, `Push`, and `Pop` take a final `moq.Timestamp` on the broadcast clock, the epoch every track in the broadcast shares, so their track needs a timescale.
JSON consumers return a `*Timed` holding the value and that timestamp; `SnapshotConsumer.Latest`
skips to the newest state where `Next` yields each one. A read timestamp is at the track's timescale.
Whole-frame media writes require caller time; container imports keep their own timeline handling.
Expand Down
3 changes: 2 additions & 1 deletion doc/lib/kt/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,8 @@ x86\_64) and desktop JVM (Linux x86\_64/aarch64, macOS arm64, Windows x64).
/ `.video` take a broadcast, a `Named` or `Requested` target, and an init record.
`CatalogProducer(broadcast)` holds its broadcast weakly and fails with `Closed` after it closes.
Publish JSON tracks with `TrackInfo(compress = true)`; a `dev.moq.json` consumer reads one with no option of its own.
A missing data timestamp stays untimed; the library never substitutes zero or now.
A raw frame without a timestamp stays untimed, which only an untimed track accepts; JSON writes always take one. The library never substitutes zero or now.
`SnapshotProducer.update`, `StreamProducer.append`, and `WindowProducer.push` and `pop` require a timestamp on the broadcast clock (`CatalogProducer.now()`), the epoch every track in the broadcast shares, so their track needs a timescale.
`dev.moq.json` consumers' `values()` emits `Value` (`value`, `timestamp`) and `valuesAs<T>()` emits `Timed<T>`;
a snapshot consumer yields each state in order, and `latest()` skips to the newest.
A `Timestamp(value, scale)` is exact and reads back at the track's timescale, so a 90 kHz tick republishes unchanged.
Expand Down
8 changes: 4 additions & 4 deletions doc/lib/py/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,12 +24,12 @@ so a raw byte stream needs no other importer.
`ContainerFormat.FMP4` splits each fragment into one frame per sample.
Media timestamps are exact `moq.Timestamp(value, scale)` records, so a 90 kHz tick survives a read and republish.
`Timestamp.from_timedelta` is exact; `.to_timedelta()` rounds down to a whole microsecond.
A missing data timestamp stays untimed; the library never substitutes zero or now.
A raw frame without a timestamp stays untimed, which only an untimed track accepts; JSON writes always take one. The library never substitutes zero or now.
JSON consumers yield `moq.json.Timed(value, timestamp)`; a snapshot consumer yields each state in order,
and `await consumer.latest()` skips to the newest. A window consumer's value is a `WindowPush`, `WindowPop`, or `WindowSkip`.
Raw tracks with a `None` timescale are untimed on both publish and receive.
`TrackInfo(compress=True)` sends each group DEFLATE-compressed to opt-in `moq-lite-07-wip` peers; other peers, and every reader here, get the original frames. Set it on JSON tracks.
The JSON producers' `update` / `append` accept `timestamp=moq.Timestamp(...)` (`None` for untimed).
The JSON producers' `update`, `append`, `push`, and `pop` require a `timestamp` on the broadcast clock, the epoch every track in the broadcast shares, so their track needs a timescale.
Whole-frame media writes require caller time; container imports keep their own timeline handling.
Timed raw/data tracks require caller-supplied timestamps. Use `CatalogProducer.now()` to stamp a locally
created event on the broadcast clock; reading it fixes that clock for later media producers.
Expand Down Expand Up @@ -95,9 +95,9 @@ async def main():
# Raw bytes and JSON
events = broadcast.publish_track("events")
events.write_frame(b'{"cmd": "ready"}')
status_track = broadcast.publish_track("status", moq.TrackInfo(compress=True))
status_track = broadcast.publish_track("status", moq.TrackInfo(timescale=1_000, compress=True))
status = moq.json.SnapshotProducer(broadcast, status_track)
status.update({"state": "live", "viewers": 42})
status.update({"state": "live", "viewers": 42}, catalog_producer.now())

publication.announce() # each broadcast mints a fresh instance
audio.finish()
Expand Down
Loading
Loading