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/publish.ts
Original file line number Diff line number Diff line change
Expand Up @@ -404,7 +404,7 @@ meta.run((effect) => {
if (!net) return;

// A day-long cache so a viewer joining long after the last edit still replays the value.
const track = net.createTrack(META_TRACK, { latencyMax: 86_400_000 });
const track = net.createTrack(META_TRACK, { maxAge: 86_400_000 });
effect.cleanup(() => track.close());

const producer = new Json.Snapshot.Producer<unknown>({ track });
Expand Down
6 changes: 3 additions & 3 deletions doc/concept/layer/moq-lite.md
Original file line number Diff line number Diff line change
Expand Up @@ -114,16 +114,16 @@ Each Subscription consists of a few properties:

- **Track Priority**: A value between 0 and 255. Tracks with higher priority will be delivered first.
- **Group Order**: The order in which groups are delivered. Defaults to descending; higher IDs are delivered first.
- **Subscriber Max Latency**: The maximum age of a non-latest group before it is skipped. Defaults to zero, so stale groups are skipped immediately.
- **Subscriber Max Age**: How old a non-latest group may get before it is skipped. Defaults to zero, so stale groups are skipped immediately.

That age is measured both on the media timeline (a group's first timestamp against the newest stamped one) and by wall-clock arrival time, and either limit can expire the group.
The media timeline keeps a backlog delivered as a burst old, while wall-clock time backstops stalled or empty groups that have no timestamp.
Both ends apply it: the publisher skips a group rather than sending it, and the subscriber skips it again as it reads.
The publisher only ever sees the most tolerant budget across its subscribers, which is why the subscriber applies it too.
Asking for old groups with `Group Start` does not exempt them: a start bounds what you are sent, and a subscriber that wants history has to raise its budget to match.

The publisher also keeps old groups around for a best-effort **Publisher Max Latency** cache window so relays and late subscribers can still fetch them. This defaults to 5 seconds.
The subscriber's maximum latency is bounded by this window: a group can't be waited for longer than it's actually kept around.
The publisher also keeps old groups around for a best-effort **Publisher Max Age** cache window so relays and late subscribers can still fetch them. This defaults to 5 seconds.
The subscriber's max age is bounded by this window: a group can't be waited for longer than it's actually kept around.

It is declared per track, so a publisher raises it on the tracks that are read as history rather than followed at the live edge.
hang media tracks ask for 30 seconds on that basis: a segmented egress (HLS/DASH) may only advertise segments a fetch can still reach, and a standard player starts several segments behind the live edge.
Expand Down
22 changes: 12 additions & 10 deletions doc/lib/c/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -157,8 +157,10 @@ the right shape for configuration, and it grows under two rules:

- **New fields are appended**, never inserted, so existing field offsets never move.
- **Zero always means the previous behavior.** A knob whose default is not zero gets
a `has_*` / `*_valid` companion flag rather than a sentinel, so a zeroed struct
reads as "not set" and the library keeps doing what it did before.
a `*_present` companion flag rather than a sentinel, so a zeroed struct reads as
"not set" and the library keeps doing what it did before. (`*_valid` on the
read-back structs is the mirror image: there the library sets it to say whether a
metric it reports is meaningful.)

Together those make an added field invisible to code that doesn't want it: you
recompile against the new header and nothing changes. Always zero a struct before
Expand Down Expand Up @@ -325,7 +327,7 @@ Raw tracks carry arbitrary byte payloads without catalog or codec parsing. Use
`moq_publish_track_frame` / `moq_publish_group_frame` to provide presentation
timestamps in microseconds.
libmoq creates raw tracks with a microsecond timescale by default (used when
`moq_track_info.timescale_valid` is false or no info is given), matching the C
`moq_track_info.timescale_present` is false or no info is given), matching the C
ABI's timestamp units.

Use `moq_publish_track_group_at` to create sparse or replayed groups at an
Expand All @@ -350,10 +352,10 @@ network.
struct moq_track_info info = {0};
info.priority = 3;
info.ordered = true;
info.latency_max_ms = 1000;
info.latency_max_valid = true;
info.max_age_ms = 1000;
info.max_age_present = true;
info.timescale = 1000000;
info.timescale_valid = true;
info.timescale_present = true;

int track = moq_publish_track(
broadcast,
Expand All @@ -364,15 +366,15 @@ int track = moq_publish_track(

`moq_consume_track` accepts optional subscriber delivery preferences.
`moq_consume_track_update` changes them while the callback task is running.
Fields ending in `_valid` decide whether the matching optional value is present:
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.latency_max_ms = 25;
sub.max_age_ms = 25;
sub.group_start = 10;
sub.group_start_valid = true;
sub.group_start_present = true;

int consumer = moq_consume_track(
broadcast,
Expand All @@ -383,7 +385,7 @@ int consumer = moq_consume_track(
user_data);

sub.group_end = 20;
sub.group_end_valid = true;
sub.group_end_present = true;
moq_consume_track_update(consumer, &sub);
```

Expand Down
29 changes: 15 additions & 14 deletions drafts/draft-lcurley-moq-lite.md
Original file line number Diff line number Diff line change
Expand Up @@ -132,7 +132,7 @@ 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 Latency` indicates the maximum age before a non-latest Group is dropped from live delivery; `Publisher Max Latency` indicates the maximum age before a non-latest Group is dropped from the publisher's cache.
- `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 @@ -496,20 +496,20 @@ An application SHOULD use `ordered` when it wants to provide a VOD-like experien
An application SHOULD NOT use `ordered` when it wants to provide a live experience, preferring to skip old groups rather than buffer them.

Note that [expiration](#expiration) is not affected by `ordered`.
An old group may still be cancelled/skipped if it exceeds the `Subscriber Max Latency`.
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.


## Expiration
Expiration governs when an older group is dropped.
The publisher SHOULD reset Group Streams for non-latest groups whose age relative to the latest group exceeds `Subscriber Max Latency` (see [SUBSCRIBE](#subscribe)); the subscriber MAY also locally drop such groups.
Expiration only removes the group from live delivery; the publisher MAY still retain it for FETCH or new subscriptions until its age exceeds `Publisher Max Latency` (see [TRACK_INFO](#track-info)).
The publisher SHOULD reset Group Streams for non-latest groups whose age relative to the latest group exceeds `Subscriber Max Age` (see [SUBSCRIBE](#subscribe)); the subscriber MAY also locally drop such groups.
Expiration only removes the group from live delivery; the publisher MAY still retain it for FETCH or new subscriptions until its age exceeds `Publisher Max Age` (see [TRACK_INFO](#track-info)).

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 Latency`:
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`:

- **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.
Expand Down Expand Up @@ -922,7 +922,7 @@ SUBSCRIBE Message {
Epoch (i)
Subscriber Priority (8)
Subscriber Ordered (8)
Subscriber Max Latency (i)
Subscriber Max Age (i)
Group Start (i)
Group End (i)
Frame Start (i)
Expand All @@ -948,12 +948,12 @@ A single byte representing whether groups are transmitted in ascending (0x1) or
The publisher SHOULD transmit *older* groups first during congestion if true.
See the [Prioritization](#prioritization) section for more information.

**Subscriber Max Latency**:
**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.
Applies only to non-latest groups; the latest group is never dropped on staleness grounds.
A value of `0` means the subscriber wants only the latest group in live delivery (older groups are immediately stale once a newer group arrives).
This is a delivery-time preference, not a retention rule: the publisher MAY still hold these groups for FETCH or future subscriptions (see `Publisher Max Latency` in [TRACK_INFO](#track-info)).
This is a delivery-time preference, not a retention rule: the publisher MAY still hold these groups for FETCH or future subscriptions (see `Publisher Max Age` in [TRACK_INFO](#track-info)).
See the [Expiration](#expiration) section for more information.

**Group Start**:
Expand Down Expand Up @@ -991,7 +991,7 @@ SUBSCRIBE_UPDATE Message {
Message Length (i)
Subscriber Priority (8)
Subscriber Ordered (8)
Subscriber Max Latency (i)
Subscriber Max Age (i)
Group Start (i)
Group End (i)
Frame Start (i)
Expand Down Expand Up @@ -1035,7 +1035,7 @@ TRACK_INFO Message {
Epoch (i)
Publisher Priority (8)
Publisher Ordered (8)
Publisher Max Latency (i)
Publisher Max Age (i)
Timescale (i)
}
~~~
Expand All @@ -1056,16 +1056,16 @@ See the [Prioritization](#prioritization) section for more information.
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 Latency**:
**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.
It is an upper bound on retention, the inverse of an HTTP `Cache-Control: max-age` guarantee:

- A subscriber MAY issue a SUBSCRIBE or FETCH with an older `Group Start`, but the publisher MAY have already dropped any group whose age exceeds `Publisher Max Latency`.
- The publisher MAY drop groups sooner than `Publisher Max Latency` under resource pressure; subscribers MUST NOT assume older groups within the bound are still available.
- A subscriber MAY issue a SUBSCRIBE or FETCH with an older `Group Start`, but the publisher MAY have already dropped any group whose age exceeds `Publisher Max Age`.
- The publisher MAY drop groups sooner than `Publisher Max Age` under resource pressure; subscribers MUST NOT assume older groups within the bound are still available.

A value of `0` means the publisher caches only the latest group (older groups MAY be dropped as soon as a newer group arrives).
The unit is milliseconds, matching `Subscriber Max Latency`.
The unit is milliseconds, matching `Subscriber Max Age`.
See the [Expiration](#expiration) section for more information.

**Timescale**:
Expand Down Expand Up @@ -1336,6 +1336,7 @@ The `Message Length` describes the payload size on the wire.
- Restricted the GOAWAY New Session URI to servers, specified a duplicate GOAWAY as a protocol violation, and recommended scheme continuity and sticky redirects.
- 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`.

## moq-lite-05
- Renamed ANNOUNCE_INTEREST to ANNOUNCE_REQUEST and ANNOUNCE to ANNOUNCE_BROADCAST.
Expand Down
2 changes: 1 addition & 1 deletion go/wrapper/subscribe.go
Original file line number Diff line number Diff line change
Expand Up @@ -82,7 +82,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
// the latency budget; pass nil for defaults. Raise Subscription.LatencyMaxMs to
// 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) {
inner, err := b.inner.SubscribeMedia(name, container, subscription)
Expand Down
6 changes: 3 additions & 3 deletions go/wrapper/types.go
Original file line number Diff line number Diff line change
Expand Up @@ -40,16 +40,16 @@ type (
OriginOptions = ffi.MoqOriginOptions
// Route is the hop chain a broadcast takes to reach an origin, its cost, and whether it's announced.
Route = ffi.MoqRoute
// Subscription holds subscriber-side delivery preferences: priority, ordering, latency budget, and group range.
// Subscription holds subscriber-side delivery preferences: priority, ordering, max age, and group range.
Subscription = ffi.MoqSubscription
// TrackInfo holds publisher-side track properties: priority, ordering, latency budget, and timescale.
// TrackInfo holds publisher-side track properties: priority, ordering, max age, and timescale.
TrackInfo = ffi.MoqTrackInfo
// Video describes one catalog rendition, including whether the publisher recommends temporarily avoiding it.
Video = ffi.MoqVideo
// VideoHint supplies catalog fields a video stream can't reveal itself, such as bitrate, filling only the gaps.
// VideoDecodedFrame is one decoded video frame: packed I420, its dimensions, and a timestamp in microseconds.
VideoDecodedFrame = ffi.MoqVideoDecodedFrame
// VideoDecoderOutput configures what DecodeVideo delivers: an optional resize plus a latency budget.
// VideoDecoderOutput configures what DecodeVideo delivers: an optional resize plus a max age.
VideoDecoderOutput = ffi.MoqVideoDecoderOutput
VideoHint = ffi.MoqVideoHint
// AudioFormat is a single audio codec an importer can parse.
Expand Down
10 changes: 5 additions & 5 deletions js/hang/src/container/track.ts
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,9 @@
import { Time, type Track } from "@moq/net";

// How long a media track asks its publisher (and, through TRACK_INFO, every relay) to keep a
// non-latest group fetchable. Must match `hang::container::LATENCY_MAX` in
// non-latest group fetchable. Must match `hang::container::MAX_AGE` in
// rs/hang/src/container/frame.rs.
const LATENCY_MAX_MS = 30_000;
const MAX_AGE_MS = 30_000;

/**
* Track properties for a track carrying media frames, for `Request.accept`.
Expand All @@ -24,10 +24,10 @@ const LATENCY_MAX_MS = 30_000;
* read at the live edge, which is retained unconditionally, so neither pays for history it never
* serves.
*
* Options override that retention; see {@link TrackInfoOptions.latencyMax}.
* Options override that retention; see {@link TrackInfoOptions.maxAge}.
*/
export function trackInfo(options?: TrackInfoOptions): Partial<Track.Info> {
return { timescale: Time.Timescale.MICRO, latencyMax: options?.latencyMax ?? LATENCY_MAX_MS };
return { timescale: Time.Timescale.MICRO, maxAge: options?.maxAge ?? MAX_AGE_MS };
}

/** Overrides for {@link trackInfo}. */
Expand All @@ -39,5 +39,5 @@ export type TrackInfoOptions = {
* A RETENTION budget, not a delivery one, so it never makes anyone play further behind live
* and lowering it does not reduce latency: it only shortens how far back a fetch can reach.
*/
latencyMax?: number;
maxAge?: number;
};
12 changes: 6 additions & 6 deletions js/net/src/broadcast.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -54,14 +54,14 @@ test("consumer dedupes repeat subscriptions onto one upstream request", async ()
test("a request exposes the aggregate subscription options", async () => {
const consumer = new TestConsumer();

consumer.subscribe("video", { priority: 3, ordered: true, latencyMax: 100, startGroup: 10, endGroup: 20 });
consumer.subscribe("video", { priority: 7, ordered: true, latencyMax: 250, startGroup: 0, endGroup: 30 });
consumer.subscribe("video", { priority: 3, ordered: true, maxAge: 100, startGroup: 10, endGroup: 20 });
consumer.subscribe("video", { priority: 7, ordered: true, maxAge: 250, startGroup: 0, endGroup: 30 });

const request = await pendingRequest(consumer);
expect(request?.subscription).toEqual({
priority: 7,
ordered: true,
latencyMax: 250,
maxAge: 250,
startGroup: 0,
endGroup: 30,
});
Expand Down Expand Up @@ -213,7 +213,7 @@ test("a stalled consumer does not pin evicted groups", async () => {
setSystemTime(new Date(10_000));

const broadcast = new BroadcastProducer();
const producer = broadcast.createTrack("video", { latencyMax: 1000 });
const producer = broadcast.createTrack("video", { maxAge: 1000 });

// A subscriber that never reads. Its sink must not grow without bound.
const stalled = broadcast.track("video").subscribe();
Expand Down Expand Up @@ -242,11 +242,11 @@ test("a stalled consumer does not pin evicted groups", async () => {
test("createTrack commits info up front", async () => {
const broadcast = new BroadcastProducer();

const producer = broadcast.createTrack("video", { latencyMax: 2000, priority: 3 });
const producer = broadcast.createTrack("video", { maxAge: 2000, priority: 3 });
expect(producer.name).toBe("video");

const info = await broadcast.track("video").info();
expect(info.latencyMax).toBe(2000);
expect(info.maxAge).toBe(2000);
expect(info.priority).toBe(3);
});

Expand Down
8 changes: 4 additions & 4 deletions js/net/src/integration.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -140,25 +140,25 @@ test("integration: lite subscription options and updates reach the publisher", a
const subscriber = remote.track("video").subscribe({
priority: 3,
ordered: true,
latencyMax: 250,
maxAge: 250,
startGroup: 0,
endGroup: 9,
});
const producer = await accepted;
expect(producer.subscription.peek()).toEqual({
priority: 3,
ordered: true,
latencyMax: 250,
maxAge: 250,
startGroup: 0,
endGroup: 9,
});

const updated = producer.subscription.changed();
subscriber.update({ priority: 8, ordered: false, latencyMax: 500, startGroup: 2, endGroup: 12 });
subscriber.update({ priority: 8, ordered: false, maxAge: 500, startGroup: 2, endGroup: 12 });
expect(await updated).toEqual({
priority: 8,
ordered: false,
latencyMax: 500,
maxAge: 500,
startGroup: 2,
endGroup: 12,
});
Expand Down
2 changes: 1 addition & 1 deletion js/net/src/lite/publisher.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -802,7 +802,7 @@ test("lite draft-06: scheduling updates apply while SUBSCRIBE_START is blocked",
expect(sub.track.subscription.peek()).toEqual({
priority: 9,
ordered: true,
latencyMax: 0,
maxAge: 0,
startGroup: undefined,
endGroup: 5,
});
Expand Down
Loading
Loading