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 demo/web/src/stats.ts
Original file line number Diff line number Diff line change
Expand Up @@ -145,7 +145,7 @@ function subscribeNode(effect: Signals.Effect, origin: Net.Origin.Table, path: N
if (!consumer) return;

const sub = <K extends keyof NodeStats>(trackName: string, key: K) => {
const track = consumer.subscribe(trackName);
const track = consumer.subscribe(trackName).ordered();
effect.cleanup(() => track.close());
effect.spawn(async () => {
for (;;) {
Expand Down
5 changes: 0 additions & 5 deletions doc/lib/c/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -344,14 +344,10 @@ codec metadata.
## Raw Track Options

`moq_publish_track` accepts optional publisher-side track properties:
`ordered` controls prioritization only. When true, groups are prioritized in
sequence order. Groups may always arrive out-of-order (or not at all) over the
network.

```c
struct moq_track_info info = {0};
info.priority = 3;
info.ordered = true;
info.max_age_ms = 1000;
info.max_age_present = true;
info.timescale = 1000000;
Expand All @@ -371,7 +367,6 @@ Fields ending in `_present` decide whether the matching optional value is set:
```c
struct moq_subscription sub = {0};
sub.priority = 5;
sub.ordered = true;
sub.max_age_ms = 25;
sub.group_start = 10;
sub.group_start_present = true;
Expand Down
4 changes: 1 addition & 3 deletions doc/lib/kt/moq.md
Original file line number Diff line number Diff line change
Expand Up @@ -110,11 +110,9 @@ val track = announcement.broadcast().subscribeTrack(
Subscription(priority = 10u.toUByte()),
)
val info = track.info()
track.update(Subscription(priority = 20u.toUByte(), ordered = false))
track.update(Subscription(priority = 20u.toUByte()))
```

`ordered` controls prioritization only. When true, groups are prioritized in sequence order. Groups may always arrive out-of-order (or not at all) over the network.

A catalog rendition may name a *different* broadcast: `MoqVideo.broadcast` / `MoqAudio.broadcast` is a path relative to the broadcast the catalog came from, so a transcode output at `live/hd` can describe a track that actually lives in `live/source`. `decodeAudio` and `decodeVideo` follow it for you. `subscribeMedia`, `subscribeTrack`, `fetchGroup`, and `fetchMediaGroup` take a track name rather than a rendition, so resolve first:

```kotlin
Expand Down
5 changes: 2 additions & 3 deletions doc/lib/py/moq-rs.md
Original file line number Diff line number Diff line change
Expand Up @@ -240,16 +240,15 @@ track = await broadcast_consumer.subscribe_track(
subscription=moq.Subscription(priority=10),
)
info = track.info()
track.update(moq.Subscription(priority=20, ordered=False))
track.update(moq.Subscription(priority=20))
async for group in track:
async for frame in group:
print(frame.timestamp_us, frame.payload)
```

`write_frame` on a track creates a one-frame group by default, using a microsecond raw-track timescale. Consumers receive a `Frame` from `read_frame()` or group iteration, carrying `payload` and `timestamp_us`. (Media tracks yield a `MediaFrame`, which adds the codec-derived `keyframe` flag.) Use `append_group()` for multi-frame groups (e.g., a video GOP).
Use `create_group(sequence)` for sparse or replayed groups. `finish_at(final_sequence)` declares the exclusive end while still permitting lower groups to arrive, and `abort(error_code)` terminates a track or group with an application error.
`TrackConsumer.info()` returns the publisher's track properties (timescale, cache, priority, ordering priority), and `update()` changes this subscriber's delivery preferences without resubscribing.
`ordered` controls prioritization only. When true, groups are prioritized in sequence order. Groups may always arrive out-of-order (or not at all) over the network.
`TrackConsumer.info()` returns the publisher's track properties (timescale, cache, priority), and `update()` changes this subscriber's delivery preferences without resubscribing.

### Fetching raw groups

Expand Down
4 changes: 1 addition & 3 deletions doc/lib/swift/moq.md
Original file line number Diff line number Diff line change
Expand Up @@ -123,11 +123,9 @@ let track = try await announcement.broadcast.subscribeTrack(
name: "events",
subscription: Subscription(priority: 10))
let info = try track.info()
track.update(subscription: Subscription(priority: 20, ordered: false))
track.update(subscription: Subscription(priority: 20))
```

`ordered` controls prioritization only. When true, groups are prioritized in sequence order. Groups may always arrive out-of-order (or not at all) over the network.

A catalog rendition may name a *different* broadcast: `Video.broadcast` / `Audio.broadcast` is a path
relative to the broadcast the catalog came from, so a transcode output at `live/hd` can describe a
track that actually lives in `live/source`. `decodeAudio` and `decodeVideo` follow it for you.
Expand Down
3 changes: 1 addition & 2 deletions drafts/draft-lcurley-moq-hang.md
Original file line number Diff line number Diff line change
Expand Up @@ -654,7 +654,6 @@ For the same reason a publisher SHOULD NOT combine tracks into a single object,
~~~
Track Object {
Publisher Priority (8)
Publisher Ordered (8)
Timescale (i)
}
~~~
Expand Down Expand Up @@ -780,7 +779,7 @@ TODO Security

A consumer parsing a recording ({{recording}}) is parsing data at rest that it did not necessarily write.
It MUST bounds-check a segment object's group `Length` and each frame's `Message Length` against the bytes actually retrieved, rather than trusting either to describe the object, and it MUST treat a malformed object as a missing segment rather than letting it invalidate the recording.
It MUST reject a track object with an invalid `Publisher Ordered` value or a zero `Timescale`.
It MUST reject a track object with a zero `Timescale`.
Varint fields are subject to the same limits as moq-lite {{moql}}.
A recording inherits the confidentiality and integrity properties of the storage holding it; encryption at rest is transparent to the format and out of scope.

Expand Down
62 changes: 31 additions & 31 deletions drafts/draft-lcurley-moq-lite.md
Original file line number Diff line number Diff line change
Expand Up @@ -131,7 +131,6 @@ Both bounds may be refined to a Frame within their Group, so a subscription can

The subscriber and publisher both indicate their delivery preference:
- `Priority` indicates if Track A should be transmitted instead of Track B.
- `Ordered` indicates if the Groups within a Track should be transmitted in order.
- `Subscriber Max Age` indicates the maximum age before a non-latest Group is dropped from live delivery; `Publisher Max Age` indicates the maximum age before a non-latest Group is dropped from the publisher's cache.

The combination of these preferences enables the most important content to arrive during network degradation while still respecting encoding dependencies.
Expand Down Expand Up @@ -451,11 +450,10 @@ moq-lite consists of multiple groups being transmitted in parallel across separa
How these streams get transmitted over the network is very important, and yet has been distilled down into a few simple properties:

## Prioritization
The Publisher and Subscriber both exchange `Priority` and `Ordered` values:
- `Priority` determines which Track should be transmitted next.
- `Ordered` determines which Group within the Track should be transmitted next.
The Publisher and Subscriber both exchange a `Priority` value, which determines which Track should be transmitted next.
Group order within a Track is fixed: newest first.

A publisher SHOULD attempt to transmit streams based on these fields.
A publisher SHOULD attempt to transmit streams based on these rules.
This depends on the QUIC implementation and it may not be possible to get fine-grained control.

### Priority
Expand Down Expand Up @@ -490,16 +488,15 @@ ali/video: subscriber_priority=1 publisher_priority=1

The subscriber priority takes precedence, so the subscriber can likewise full-screen Ali's window by raising the subscriber priority of Ali's tracks above Bob's.

### Ordered
The `Subscriber Ordered` field signals if older (0x1) or newer (0x0) groups should be transmitted first within a Track.
The `Publisher Ordered` field MAY likewise be used to resolve conflicts.
### Group Order
Within a Track, a publisher SHOULD transmit the newest Group first.
Under congestion this sheds the backlog rather than the live edge, which is what a Group boundary exists to make possible.

An application SHOULD use `ordered` when it wants to provide a VOD-like experience, preferring to buffer old groups rather than skip them.
An application SHOULD NOT use `ordered` when it wants to provide a live experience, preferring to skip old groups rather than buffer them.
There is no field to invert it.
A subscriber that wants Groups in sequence order gets them by reading in sequence order: reordering is a local decision, it costs the network nothing, and encoding it on the wire only lets one subscriber's preference reach a Track that a relay is fanning out to many.
Such a subscriber SHOULD raise its `Subscriber Max Age` so the Groups it intends to read in order are still being delivered when it reaches them.

Note that [expiration](#expiration) is not affected by `ordered`.
An old group may still be cancelled/skipped if it exceeds the `Subscriber Max Age`.
An application MUST support gaps and out-of-order delivery even when `ordered` is true.
A subscriber MUST support gaps and out-of-order delivery regardless.


## Expiration
Expand All @@ -510,14 +507,26 @@ Expiration only removes the group from live delivery; the publisher MAY still re
It is not crucial to aggressively expire groups thanks to [prioritization](#prioritization), but a lower priority group still consumes RAM, bandwidth, and potentially flow control.
It is RECOMMENDED that an application set conservative limits and only resort to expiration when data is absolutely no longer needed.

A group is never expired until at least the next group (by sequence number) has been received or queued.
Once a newer group exists, the group's age is measured two ways, and it is expired once **either** measure exceeds the relevant `Max Age`:
A group is never expired until a later group (by sequence number) has presented a frame.
Once one has, the group's **timestamp age** is the difference between the *newest* frame timestamp of the latest group that has at least one frame, and this group's **reach**, defined below; the group is expired once that age meets the relevant `Max Age`.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Use reach consistently when resolving subscription starts

This changes expiration to measure age from a group's successor-defined reach and expire when the age meets the budget, but the same draft still says at line 504 that expiration requires the age to exceed the budget and, more importantly, tells publishers at line 996 to resolve Group Start using the group's first frame. Implementations following the SUBSCRIBE section can therefore select and deliver a different oldest group than implementations following this section and the Rust/JS code, defeating the promise at line 998 that start selection and expiration cannot disagree. (Written by GPT-5.6 Sol)

AGENTS.md reference: AGENTS.md:L211-L211

Useful? React with 👍 / 👎.

Timestamps are the only measure: they are consistent across relays and unaffected by buffering or jitter.
Wall-clock reclamation of idle content is the retention cache's own policy (`Publisher Max Age`, or any implementation-defined bound), not part of this rule.

- **Timestamp age**: the difference between this group's first frame timestamp and the first frame timestamp of the latest group that has at least one frame. This measure is consistent across relays and unaffected by buffering or jitter.
- **Wall-clock age**: the difference between when this group's first byte arrived (subscriber) or was queued (publisher) and the same instant for the latest group.
A group is expired only once it **provably cannot overlap the Max Age window**: every frame it could still present is older than the budget allows.
Being behind is not itself a reason to expire anything.
[Prioritization](#prioritization) already transmits newer groups first, so an older group consumes only whatever capacity is left over; it therefore closes the gap faster than the live edge advances, and a receiver that is behind can converge without losing content.
What cannot be recovered is a group with nothing left worth delivering, and that is what expiration removes.

The two backstop each other: a publisher cannot keep stale groups alive with fresh-looking timestamps, and a burst of groups arriving together does not reset their age.
A group that contains zero frames has no timestamp, so only the wall-clock age applies; this avoids stalling expiration on empty groups sent as keep-alives or gap markers.
A group's **reach** is the first frame timestamp of the next group by sequence number, or unbounded when no later group has presented a frame.
A group cannot present past where its successor begins, so this is the furthest it could still reach.
Its own frames do not bound it: frame durations are not carried on the wire, so a group's last frame timestamp is where that frame *starts* presenting, not where the group ends.
A group whose successor has not presented a frame is therefore never expired, because nothing yet proves where it stops.
The group itself needs no timestamp: a zero-frame group (a keep-alive or gap marker) is bounded by its successor's first frame the same way.

Reach is an exclusive bound, so a timestamp age **equal** to Max Age already expires the group: the freshest frame it could still hold sits strictly below its reach, and is therefore strictly older than the budget.
A Max Age of zero follows from the same rule without a special case.

Measuring in timestamps rather than arrival means a burst of groups delivered together still reads as its true age, so catching up never resets the clock.

An expired group SHOULD be reset at the QUIC level to avoid consuming flow control.

Expand Down Expand Up @@ -951,7 +960,6 @@ SUBSCRIBE Message {
Track Name (s)
Epoch (i)
Subscriber Priority (8)
Subscriber Ordered (8)
Subscriber Max Age (i)
Group Start (i)
Group End (i)
Expand All @@ -973,11 +981,6 @@ The priority of the subscription within the session, represented as a u8.
The publisher SHOULD transmit *higher* values first during congestion.
See the [Prioritization](#prioritization) section for more information.

**Subscriber Ordered**:
A single byte representing whether groups are transmitted in ascending (0x1) or descending (0x0) order.
The publisher SHOULD transmit *older* groups first during congestion if true.
See the [Prioritization](#prioritization) section for more information.

**Subscriber Max Age**:
The subscriber's preference, in milliseconds, for how long a non-latest group may remain in flight before being considered stale and dropped from live delivery.
The publisher SHOULD reset (at the QUIC level) Group Streams for groups whose age relative to the latest group exceeds this duration.
Expand Down Expand Up @@ -1024,7 +1027,6 @@ The start and end group can be changed in either direction (growing or shrinking
SUBSCRIBE_UPDATE Message {
Message Length (i)
Subscriber Priority (8)
Subscriber Ordered (8)
Subscriber Max Age (i)
Group Start (i)
Group End (i)
Expand Down Expand Up @@ -1068,7 +1070,6 @@ TRACK_INFO Message {
Message Length (i)
Epoch (i)
Publisher Priority (8)
Publisher Ordered (8)
Publisher Max Age (i)
Timescale (i)
}
Expand All @@ -1086,10 +1087,6 @@ Subscribers key their TRACK_INFO cache by it, and a SUBSCRIBE or FETCH that will
The publisher's priority for this Track, represented as a u8, used only to resolve ties between subscriptions of equal subscriber priority.
See the [Prioritization](#prioritization) section for more information.

**Publisher Ordered**:
The publisher's group ordering preference (ascending `0x1` or descending `0x0`), used only to resolve ties.
See the [Prioritization](#prioritization) section for more information.

**Publisher Max Age**:
The maximum age, in milliseconds, that the publisher caches a non-latest group past the arrival of a newer group.
Applies only to non-latest groups; the latest group is always retained.
Expand Down Expand Up @@ -1373,6 +1370,9 @@ The `Message Length` describes the payload size on the wire.
- Exempted a ceiling-cost serving path from the actively-carrying cost discount: a relay whose serving path costs the saturation ceiling (primarily a session that received a GOAWAY) advertises the ceiling instead of 0, so the drain propagates downstream instead of being re-masked by each carrying hop. Keyed on the value, not the reason, which does not travel on the wire.
- Added the Error Codes section, defining separate session and stream code spaces and listing the codes moq-lite uses, reused unchanged from moq-transport. Codes 64+ are the application's; 32-63 are reserved and MUST NOT be interpreted, pending a future revision. Previously the codes were unspecified, so an endpoint could neither send one a peer would understand nor safely interpret one it received. Note this renumbers every code an existing implementation sent, and that a stream reset of 0x0 is now INTERNAL_ERROR rather than a cancellation (CANCELLED is 0x1).
- Renamed `Subscriber Max Latency` to `Subscriber Max Age` and `Publisher Max Latency` to `Publisher Max Age`.
- Redefined timestamp age so a group is expired only once it provably cannot overlap the Max Age window. Age is now measured from a group's *reach* (the first frame timestamp of its successor, which is the furthest it could still present) to the newest frame of the latest group, and an age equal to Max Age expires it, since reach is an exclusive bound. Previously age ran from the group's own first frame, which expired a group whose later frames were still well inside the budget. A group whose successor has not yet presented a frame is never expired, because frame durations are not on the wire and nothing else proves where it ends.
- Removed the wall-clock age measure from expiration: timestamps are the only input, and wall-clock reclamation of idle content is the retention cache's own policy (`Publisher Max Age`) rather than part of the subscription rule. A zero-frame group needs no measure of its own, since its reach is bounded by its successor's first frame like any other group.
- Removed `Subscriber Ordered` from SUBSCRIBE and SUBSCRIBE_UPDATE, and `Publisher Ordered` from TRACK_INFO and SUBSCRIBE_OK. Group order within a Track is now normatively newest-first, with no field to invert it: a subscriber that wants sequence order reads in sequence order, which costs the network nothing and does not let one subscriber's preference reach a Track a relay is fanning out to many. Note this removes a byte from the middle of each message, so a lite-06 peer cannot parse a lite-05 one's SUBSCRIBE (the earlier drafts keep the byte, and an implementation serving them SHOULD write 0 and ignore what it reads).
- Made `Group Start` an absolute floor (the raw minimum group sequence, default 0) rather than the sequence + 1 with 0 meaning the latest group. The start resolves from `Subscriber Max Age` instead: the oldest group at or above the floor within the budget, so a subscriber that buffers is handed the head of what it can still play. A zero budget still resolves to the latest group, which was the only start the old encoding could ask for by default.

## moq-lite-05
Expand Down
2 changes: 1 addition & 1 deletion go/wrapper/publish.go
Original file line number Diff line number Diff line change
Expand Up @@ -477,7 +477,7 @@ func (t *TrackProducer) Abort(errorCode uint16) error {
}

// Consume reads directly from this producer's track. subscription tunes delivery
// (delivery priority, group ordering priority, group range); pass nil for defaults.
// (delivery priority, group range); pass nil for defaults.
func (t *TrackProducer) Consume(subscription *Subscription) (*TrackConsumer, error) {
inner, err := t.inner.Consume(subscription)
if err != nil {
Expand Down
4 changes: 2 additions & 2 deletions go/wrapper/subscribe.go
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ func (b *BroadcastConsumer) SubscribeCatalog() (*CatalogConsumer, error) {
}

// SubscribeTrack subscribes to a track, receiving arbitrary byte payloads.
// subscription tunes delivery priority, group ordering priority, and group range; pass nil for defaults.
// subscription tunes delivery priority, group range, and staleness; pass nil for defaults.
func (b *BroadcastConsumer) SubscribeTrack(name string, subscription *Subscription) (*TrackConsumer, error) {
inner, err := b.inner.SubscribeTrack(name, subscription)
if err != nil {
Expand Down Expand Up @@ -81,7 +81,7 @@ func (b *BroadcastConsumer) FetchMediaGroup(name string, sequence uint64, contai
}

// SubscribeMedia subscribes to a media track, decoded with the given container.
// subscription tunes delivery priority, group ordering priority, group range, and
// subscription tunes delivery priority, group range, and
// the max age; pass nil for defaults. Raise Subscription.MaxAgeMs to
// buffer instead of skipping a stalled group.
func (b *BroadcastConsumer) SubscribeMedia(name string, container Container, subscription *Subscription) (*MediaConsumer, error) {
Expand Down
Loading
Loading