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
2 changes: 1 addition & 1 deletion dart/moq/lib/src/durations.dart
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ extension BackoffDuration on MoqBackoff {
/// Duration views over the subscription knobs.
extension SubscriptionDuration on MoqSubscription {
/// Upper bound on buffering before a stalled group is skipped.
Duration get maxAge => Duration(microseconds: maxAgeUs);
Duration get maxDelay => Duration(microseconds: maxDelayUs);
}

/// Duration views over the publisher-side track settings.
Expand Down
20 changes: 10 additions & 10 deletions dart/moq_ffi/lib/src/moq.dart
Original file line number Diff line number Diff line change
Expand Up @@ -60,12 +60,12 @@ class FfiConverterMoqFetchGroupOptions {

class MoqSubscription {
final int priority;
final int maxAgeUs;
final int maxDelayUs;
final int? groupStart;
final int? groupEnd;
MoqSubscription({
this.priority = 0,
this.maxAgeUs = 0,
this.maxDelayUs = 0,
this.groupStart = null,
this.groupEnd = null,
});
Expand All @@ -83,11 +83,11 @@ class FfiConverterMoqSubscription {
);
final priority = priority_lifted.value;
new_offset += priority_lifted.bytesRead;
final maxAgeUs_lifted = FfiConverterUInt64.read(
final maxDelayUs_lifted = FfiConverterUInt64.read(
Uint8List.view(buf.buffer, new_offset),
);
final maxAgeUs = maxAgeUs_lifted.value;
new_offset += maxAgeUs_lifted.bytesRead;
final maxDelayUs = maxDelayUs_lifted.value;
new_offset += maxDelayUs_lifted.bytesRead;
final groupStart_lifted = FfiConverterOptionalUInt64.read(
Uint8List.view(buf.buffer, new_offset),
);
Expand All @@ -101,7 +101,7 @@ class FfiConverterMoqSubscription {
return LiftRetVal(
MoqSubscription(
priority: priority,
maxAgeUs: maxAgeUs,
maxDelayUs: maxDelayUs,
groupStart: groupStart,
groupEnd: groupEnd,
),
Expand All @@ -112,7 +112,7 @@ class FfiConverterMoqSubscription {
static RustBuffer lower(MoqSubscription value) {
final total_length =
FfiConverterUInt8.allocationSize(value.priority) +
FfiConverterUInt64.allocationSize(value.maxAgeUs) +
FfiConverterUInt64.allocationSize(value.maxDelayUs) +
FfiConverterOptionalUInt64.allocationSize(value.groupStart) +
FfiConverterOptionalUInt64.allocationSize(value.groupEnd) +
0;
Expand All @@ -128,7 +128,7 @@ class FfiConverterMoqSubscription {
Uint8List.view(buf.buffer, new_offset),
);
new_offset += FfiConverterUInt64.write(
value.maxAgeUs,
value.maxDelayUs,
Uint8List.view(buf.buffer, new_offset),
);
new_offset += FfiConverterOptionalUInt64.write(
Expand All @@ -144,7 +144,7 @@ class FfiConverterMoqSubscription {

static int allocationSize(MoqSubscription value) {
return FfiConverterUInt8.allocationSize(value.priority) +
FfiConverterUInt64.allocationSize(value.maxAgeUs) +
FfiConverterUInt64.allocationSize(value.maxDelayUs) +
FfiConverterOptionalUInt64.allocationSize(value.groupStart) +
FfiConverterOptionalUInt64.allocationSize(value.groupEnd) +
0;
Expand Down Expand Up @@ -12554,7 +12554,7 @@ void _checkApiChecksums() {
throw UniffiInternalError.panicked("UniFFI API checksum mismatch");
}
if (uniffi_moq_ffi_checksum_method_moqbroadcastconsumer_subscribe_media() !=
29917) {
8119) {
throw UniffiInternalError.panicked("UniFFI API checksum mismatch");
}
if (uniffi_moq_ffi_checksum_method_moqbroadcastconsumer_subscribe_track() !=
Expand Down
5 changes: 3 additions & 2 deletions doc/bin/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -467,8 +467,9 @@ See [Authentication](/bin/relay/auth).
## Retention and latency

`import --max-age` (default 30 s) tells relays how long to keep old
groups fetchable, which the [HLS gateway](/bin/hls) depends on. `export --max-age` (default 500 ms) is how long *this* consumer waits for a
stalled group before skipping. Raising the first never delays playback.
groups fetchable, which the [HLS gateway](/bin/hls) depends on. `export --max-delay` (default 500 ms) is how far a stalled group may fall
behind the live edge before *this* consumer skips it. Raising the first never delays playback.
`export ts` still spells its budget `--max-age`.

For `export ts`, `--max-age` also bounds how long the muxer holds a leading
track for a lagging one. Frames go out in media-time order across all tracks,
Expand Down
2 changes: 1 addition & 1 deletion doc/bin/relay/cluster.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ a cheaper route with that epoch, each subscription continues on the new route
from the first frame its readers lack, so they see
every frame once, mid-group included. A route that is still up finishes the
groups it has open, overlapping the new one. A group neither route delivers is
dropped once the readers' max age has passed it. A route through the subscribing peer
dropped once the readers' max delay has passed it. A route through the subscribing peer
itself is never used. A publisher whose groups restart, such as an encoder
restarting from group 0, publishes under a new epoch, which replaces the old
broadcast instead of resuming it. A route without an epoch, including every
Expand Down
4 changes: 2 additions & 2 deletions doc/concept/audio-jitter.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ as packets come and lets the playback buffer hold the target, rather than
pacing reads to the speaker.

A frame dropped by the relay is never observed, which is correct only while the
drop is not the receiver's own doing. The subscription's max age drops groups
drop is not the receiver's own doing. The subscription's max delay drops groups
before any container sees them, at the relay and in the receiver's own transport
subscriber, so a subscription cut to the target hides every frame later than
the target: the estimate creeps up one bucket at a time while the frames it
Expand Down Expand Up @@ -404,7 +404,7 @@ Supported or refused, not warned about and continued.

In the browser this is the numeric `delay` setting; natively it is
`decode::Options::delay`, where `None` selects the estimator. The two spell the
same thing the same way on purpose. It is distinct from `max_age`, which is the
same thing the same way on purpose. It is distinct from `max_delay`, which is the
live-edge skip budget and not a buffer.

## Constants
Expand Down
12 changes: 6 additions & 6 deletions doc/concept/moq-lite.md
Original file line number Diff line number Diff line change
Expand Up @@ -315,15 +315,15 @@ Each subscription carries the knobs that decide behavior under congestion:
| --- | --- |
| **Priority** (0..255) | Higher-priority tracks get bandwidth first. Audio above video, base layer above enhancement. |
| **Order** | Which group to send first when several are pending. Newest first for live, oldest first for catch-up. |
| **Max age** | How old a non-latest group may get before it is skipped. Zero means "live edge only", and raising it is also what asks for history. |
| **Max delay** | How far a non-latest group may fall behind the live edge before it is skipped. Zero means "live edge only", and raising it is also what asks for history. |

Max age is measured on the media timeline, not the wall clock, so a backlog
delivered as a burst is still old while a congestion stall never expires
Max delay is measured on the media timeline, not the wall clock, so a backlog
delivered as a burst is still late while a congestion stall never expires
anything on its own. Both ends apply it: the publisher skips a group rather
than sending it, and the subscriber skips it again as it reads, since the
publisher only ever sees the most tolerant budget across its subscribers.

A route failover is invisible to max age: a group open across the change carries
A route failover is invisible to max delay: a group open across the change carries
on from the new route at the frame where the old one stopped, and a group only a
replaced route that went quiet still holds is given up once it falls a full
budget behind the new route's live edge. A successor group with no timestamp
Expand All @@ -349,7 +349,7 @@ IETF carries this value as MAX\_CACHE\_DURATION, received on every supported dra
and sent from draft 17 onward. A relay reads it from FETCH\_OK as well as SUBSCRIBE\_OK, so a track it
only fetches still learns its window. Drafts 14–16 remain receive-only for compatibility
with older implementations. This is an approximate mapping: IETF measures wall
time, while max age uses media timestamps and always keeps the newest group.
time, while the publisher's retention window uses media timestamps and always keeps the newest group.
EXPIRES describes subscription lifetime and does not set retention.

Lite-07 encodes a finite limit as milliseconds plus one, with zero meaning no limit.
Expand All @@ -360,7 +360,7 @@ timer cap schedules periodic age checks and does not shorten that window.

Put together, a conference might use:

| Track | Priority | Order | Max age |
| Track | Priority | Order | Max delay |
| --- | --- | --- | --- |
| audio | 100 | ascending | 500 ms |
| video | 50 | descending | 2 s |
Expand Down
2 changes: 1 addition & 1 deletion doc/lib/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ how it looks in that language:
- **Discover** broadcasts by prefix, wait for a specific one, or request one by path, including a path a prefix claim serves on demand. Advertise an exact path with `create_broadcast` then `announce` / `unannounce` (a broadcast is invisible to local consumers and peers alike until announced), or claim a path prefix with `dynamic(prefix, route)`.
- **Publish and subscribe to media** with the hang catalog filled in from the bitstream, plus raw pixels or PCM in and out with the codec running inside the binding (VideoToolbox, Media Foundation, NVENC, openh264, Opus). A publisher follows the connection's send estimate through `session.bandwidth()`: reserve a share for an app-owned encoder, or pass the handle when encoding so the built-in video encoder follows the grant.
- **Connection health.** `stats()` snapshots RTT, send/receive estimates, and byte/packet counters. `bandwidth()` divides that send estimate among tracks sharing the connection.
- **Raw tracks** of arbitrary bytes with timestamps, sparse or replayed groups, per-subscriber priority and max age, and best-effort datagrams.
- **Raw tracks** of arbitrary bytes with timestamps, sparse or replayed groups, per-subscriber priority and max delay, and best-effort datagrams.
- **JSON tracks** in snapshot mode (latest value, merge-patch deltas, optional compression) or stream mode (append log).
- **Fetch** a single group by sequence from the cache, decoded through the container or raw.
- **Serve on demand**: accept track and broadcast requests as they arrive instead of publishing up front.
Expand Down
6 changes: 3 additions & 3 deletions doc/lib/js/net.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,9 +52,9 @@ for (;;) {
- **Connections** race WebTransport against WebSocket. `new Connection({ url })` pools one connection per relay URL and reconnects with backoff, which the elements use. Supplying WebTransport/WebSocket options, discovery, delay, `goaway`, or a caller-owned origin selects a private loop; explicit `share: true` refuses those options. On a relay's GOAWAY the connection dials the replacement at once while the old session keeps serving its groups until it closes or the `goaway.handover` cap (default 10s, lowered to the relay's deadline) passes; the handle and its origin stay the same. An empty GOAWAY redials the same URL through a fresh DNS resolve. A redirect is followed onto the same host by default (`goaway.redirect: "follow"` lets the relay pick the host, `"ignore"` never moves), and moves the pooled entry to the new URL; a malformed or refused one, including a host change under a pinned certificate, ends the connection with `Error.RefusedRedirect` instead of reconnecting. `closed` settles when the handle is released (`null` on a clean close); the failure that stopped retrying the current URL is `error`, and a new URL recovers the same handle. A connection owns one send-rate sampler and one `Bandwidth.Allocator`; publishers reserve against it so their encoder targets sum to the estimate instead of each matching it.
- **Bandwidth** (`Bandwidth.Allocator`) divides the connection's send-rate estimate by track priority, max-min fair within a tier. An idle track claims nothing. The receive side is untouched.
- **Discovery** by any pattern scope (`origin.announced(scope)`, such as `room/*/chat`; default everything). A route event's `kind` says whether the route started, updated, or ended; its `prefix` is the covered prefix relative to the origin, and `captures` reports what the scope's wildcards matched when the prefix pins them. The consumer is an async iterable. `origin.broadcasts(scope)` is a live `Getter<ReadonlyMap<Path.Valid, Route>>` of the same covered prefixes for UIs that need the current set. A borrowed `Connection.origin` also exposes `dynamic(prefix, route)` for serving paths on demand.
- **Publisher retention** is optional `Track.Info.maxAge`, measured against media timestamps: omission sets no limit, while zero serves only the live edge. It clamps every subscriber's max age, and stalled media does not age out merely because wall time passes. Separately, cached groups nobody writes for 30 seconds are reclaimed, except a live track's newest group, which stays replayable until the track closes.
- **Subscriptions** carry a priority, a `Time.Milli` max age measured against media timestamps, and optional `groups` bounds. Groups arrive out of order and are read frame by frame, with `Error.TooFarBehind` when a reader asks for a frame the group never held and `Error.GroupTooLarge` when a write exceeds the cache budget and aborts the group.
- **Track ends**: `close()` ends a track at its live edge, while `finishAt(n)` declares the exclusive end ahead of it and still accepts the groups below. A subscriber reads the end with `final()` or awaits `finished()`. Group and datagram readers end once the live edge reaches the declared boundary, even while missing lower groups wait out the grace. The `closed` signal settles separately once every group below the end has arrived or was dropped; one reset before its header arrived is skipped after the subscription's max age on moq-lite (one second without one), or after one second on IETF.
- **Publisher retention** is optional `Track.Info.maxAge`, measured against media timestamps: omission sets no limit, while zero serves only the live edge. It clamps every subscriber's max delay, and stalled media does not age out merely because wall time passes. Separately, cached groups nobody writes for 30 seconds are reclaimed, except a live track's newest group, which stays replayable until the track closes.
- **Subscriptions** carry a priority, a `Time.Milli` max delay measured against media timestamps, and optional `groups` bounds. Subscription options use `maxDelay`; supplying the obsolete subscriber `maxAge` key throws a `TypeError` naming its replacement, including on `update()`. Groups arrive out of order and are read frame by frame, with `Error.TooFarBehind` when a reader asks for a frame the group never held and `Error.GroupTooLarge` when a write exceeds the cache budget and aborts the group.
- **Track ends**: `close()` ends a track at its live edge, while `finishAt(n)` declares the exclusive end ahead of it and still accepts the groups below. A subscriber reads the end with `final()` or awaits `finished()`. Group and datagram readers end once the live edge reaches the declared boundary, even while missing lower groups wait out the grace. The `closed` signal settles separately once every group below the end has arrived or was dropped; one reset before its header arrived is skipped after the subscription's max delay on moq-lite (one second without one), or after one second on IETF.
- **Datagrams** on moq-lite 05+ and fetch-by-sequence for history. `track.fetchGroup(sequence)` on moq-lite resolves when the publisher sends the first response byte or finishes an empty group. A missing group rejects the fetch with `StreamCode.NotFound`, including every concurrent caller sharing that fetch. `fetchGroup(sequence, { signal })` abandons a pending fetch with the signal's reason; the shared stream is cancelled only once every caller has left. Once resolved, close the group instead.
- **Errors**: deliberately closing a connection ends its received tracks cleanly. A peer close ends received tracks and open group readers with the session error and its close code. Errors live under one namespace: a stream reset throws `Error.Stream` with a `StreamCode`, while a session close gives `Error.Session` with a `SessionCode`. The registries are disjoint, so the same number means different things in each, and 64+ is yours. Named conditions such as `Error.TooFarBehind`, `Error.FrameTooLarge`, and `Error.GroupTooLarge` subclass `Error.Stream`, so one `code` check handles a condition raised here or reported by the peer. IETF streams use their own mapping: cancellation sends CANCELLED, other local failures send INTERNAL\_ERROR, and received codes remain opaque.
- **Paths** with `Path.relative` for the cross-broadcast catalog references hang uses. A `Broadcast.Consumer` names its broadcast by `path`: the path it was requested at relative to the origin handle's root, or empty for a standalone broadcast. Those references resolve against it. Path patterns (`Path.Pattern`, `Path.Patterns`) are re-exported from [`@moq/pattern`](https://www.npmjs.com/package/@moq/pattern). Literal `Path` stays a coordinate.
Expand Down
3 changes: 2 additions & 1 deletion doc/lib/js/watch.md
Original file line number Diff line number Diff line change
Expand Up @@ -130,7 +130,8 @@ const dispose = el.signals.run((effect) => {

Call `dispose()` from your framework's unmount cleanup when this subscription
is no longer needed. Removing the element disables playback but keeps its
effects open so the same node can reconnect.
effects open so the same node can reconnect. Its audio graph is released and
rebuilt on return; pausing or muting keeps the graph warm.

The effect re-runs whenever the catalog or the active broadcast changes, so a
reconnect resubscribes on its own. A publisher that rewrites its catalog often
Expand Down
2 changes: 1 addition & 1 deletion doc/lib/rs/hang.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ that carry a timestamp with every frame.

- **Catalog producer and consumer.** Typed `VideoConfig`, `AudioConfig` and text renditions, the `json` and `binary` data track sections, shared video properties (display size, rotation, flip), stalled hints, cross-broadcast rendition references, and the `archive` entry (each track's timeline track, optional replay path, store URL, and format version). Extend it with your own sections through a lock or `#[serde(flatten)]`, or read unknown sections as raw JSON.
- **Containers.** `legacy`, `cmaf`, and `loc`, decoded for you; unknown kinds pass through untouched.
- **`Ordered`** reads a media track as timestamped frames, reorders groups, and skips ones that fall past your max age.
- **`Ordered`** reads a media track as timestamped frames, reorders groups, and skips ones that fall past your max delay.
- **Codecs described**: H.264, H.265, VP8, VP9, AV1, AAC, Opus, PCM.

```bash
Expand Down
2 changes: 1 addition & 1 deletion doc/lib/rs/moq-mux.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ Turns existing container formats into hang broadcasts and back. This is what

Importers parse the bitstream to fill the catalog (resolution, codec string,
`description`), split groups at keyframes, and stamp timestamps. Exporters do
the inverse and skip stalled groups past a max age. Per-codec
the inverse and skip stalled groups past a max delay. Per-codec
producers (`import::Opus`, H.264, and so on) are available for feeding frames
you already have.

Expand Down
Loading
Loading