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
1 change: 1 addition & 0 deletions doc/concept/moq-lite.md
Original file line number Diff line number Diff line change
Expand Up @@ -283,6 +283,7 @@ Each subscription carries the knobs that decide behavior under congestion:
| **Priority** (-128..127, default 0) | Higher-priority tracks get bandwidth first. Audio above video, base layer above enhancement. The publisher's track priority breaks ties between subscriptions at one priority. From a native Rust publisher over QUIC or WebTransport, subscriptions at the same priority and publisher priority split bandwidth evenly by bytes, streams and datagrams alike, however many groups each has queued. A browser publisher and other transports without send groups are not covered. |
| **Order** | Which group to send first when several are pending. Newest first for live (the default), oldest first for catch-up. Needs moq-lite 07 or moq-transport; older moq-lite always sends newest first. |
| **Max delay** | How long a non-latest group stays worth delivering before it is skipped. Zero means "live edge only", and raising it is also what asks for history. Unset leaves the publisher's max age alone to bound it. |
| **Min delay** | The playout buffer the subscriber holds behind the live edge. A join from the latest group starts at the newest group beginning this far behind it, so the buffer arrives full instead of filling in real time, and no fuller. The hop answering measures from what it holds: media time on a timed track, arrival time on an untimed one, and it never fetches upstream to reach further. Zero (the default) reaches back nothing, and a range from the oldest group or a named start ignores it. Carried by moq-lite 07, where a relay asks upstream for the largest its subscribers state. |
| **Ranges** | Which groups to ask for: from the oldest group, a number of groups back from the latest, or the group containing a time, through an end that includes its group. Each group arrives whole, from its first frame. The default asks for everything max delay allows. Max delay still caps every range. |

On moq-lite 05 and later, a publisher explicitly reports groups that will not arrive.
Expand Down
12 changes: 8 additions & 4 deletions drafts/draft-lcurley-moq-lite.md
Original file line number Diff line number Diff line change
Expand Up @@ -1718,8 +1718,8 @@ See the [Expiration](#expiration) section for more information.
**Subscriber Min Age**:
The subscriber's target latency behind the live edge, in milliseconds plus one: the playout or jitter-buffer delay it holds.
A value of `0` means the subscriber did not state one, which is distinct from a stated zero (`1`).
It is a hint that asks for nothing: a publisher MAY use it, for example to start a cold join that far back, and MAY ignore it.
A relay forwarding an aggregate of several subscriptions SHOULD carry the smallest stated value, and not stated when none is, so a subscription that did not state one never pulls the aggregate to zero.
It decides where a Range joining at the live edge starts (see below).
A relay forwarding an aggregate of several subscriptions SHOULD carry the largest stated value, and not stated when none is, so its own copy starts far enough back for the subscription that buffers most.

**Range Count**:
The number of Ranges that follow.
Expand All @@ -1746,13 +1746,17 @@ A Range resolves once: an update that leaves it live does not resolve it again.
The number of the subscription's terms this message sets: 0 on SUBSCRIBE, and on each SUBSCRIBE_UPDATE a larger value than the one before it.
A [SUBSCRIBE_DROP](#subscribe-drop) echoes the number in effect when its groups were given up, so the subscriber can tell a stale verdict on its current terms from one an update has since replaced.

A `Start` is a floor, not a request; `Subscriber Max Age` is the only thing that asks for data.
A `Start` is a floor, not a request; `Subscriber Max Age` and `Subscriber Min Age` are the only things that ask for data.
The publisher SHOULD start at the oldest group at or above the floor that [Expiration](#expiration) has not expired, and MUST NOT deliver an older one.
A `Subscriber Max Age` of 0 therefore starts at the latest group, since every older group is already stale.
A subscriber that buffers is then handed the head of what it can still play instead of only the live edge, and is never sent history it would discard on arrival: the same bound decides what to start at and what to expire, so the two cannot disagree.
A floor above the latest group simply waits there: that is a resumed subscription naming where it left off.
Reaching back is best-effort, not a guarantee that the groups still exist; see `Publisher Max Age` in [TRACK_INFO](#track-info).

A Range joining at the live edge, with a `Start` of Relative 0 and an `End` of None, starts by a nonzero `Subscriber Min Age` instead: the publisher SHOULD start it at the newest group it holds that starts at or before the live edge minus the Min Age, at the oldest group it holds when none does, and never at a group Expiration has expired.
The live edge is the newest frame timestamp the publisher holds; on a Track without a timescale, the Min Age is measured by when each group arrived at the publisher instead.
The publisher starts from what it holds and never fetches to reach further back, so a subscriber is handed the buffer it will play, and no more, without waiting for it to fill.

A Range covers whole Groups; a subscriber reads a slice of a Group with FETCH (see [Positions](#positions)).

## SUBSCRIBE_UPDATE {#subscribe-update}
Expand Down Expand Up @@ -2518,7 +2522,7 @@ An application-specific payload.

- Replaced `Group Start`, `Group End`, `Frame Start`, and `Frame End` in SUBSCRIBE and SUBSCRIBE_UPDATE with a non-empty list of Ranges of whole Groups. Each end is an Anchor: none, an absolute Group (exclusive as an end), a count of Groups back from the latest, or a presentation time.
- Added `Group Order` to SUBSCRIBE and SUBSCRIBE_UPDATE: descending (0x0, the previous fixed order) or ascending (0x1).
- Added an optional `Subscriber Min Age` to SUBSCRIBE and SUBSCRIBE_UPDATE, the subscriber's target latency, encoded as milliseconds plus one with zero meaning not stated. A relay forwards the smallest stated value.
- Added an optional `Subscriber Min Age` to SUBSCRIBE and SUBSCRIBE_UPDATE, the subscriber's target latency, encoded as milliseconds plus one with zero meaning not stated. A Range joining at the latest group starts that far behind the live edge, from the groups the publisher holds. A relay forwards the largest stated value.
- FETCH reads one Group or a slice of one, and SUBSCRIBE reads whole Groups: a read starting partway through a Group FETCHes it. A publisher holding only part of a Group a subscription covers drops it.
- A SUBSCRIBE_UPDATE that lowers a `Start` covers the groups below the old start that the publisher still holds, not only those that arrive later. A group already sent is not sent again.
- Replaced SUBSCRIBE_OK `Group` with a `Range Start` per Range: the Group where that Range's delivery starts, including at a Relative or Time Anchor, from which its Groups are owed.
Expand Down
4 changes: 2 additions & 2 deletions js/hang/src/container/consumer.ts
Original file line number Diff line number Diff line change
Expand Up @@ -60,8 +60,8 @@ export interface ConsumerProps {
* decoder that needs that much media before its output is clean starts early enough, such as an
* Opus decoder. Pass the catalog audio rendition's `warmup`. Mirrors Rust's `container::Playout`.
*
* Put the max delay plus the warmup on the subscription, since the publisher skips what falls
* outside that budget. The start is no later than the group covering the live edge less
* Put the min and max delay plus the warmup on the subscription, since the publisher starts a
* live join at the min and skips what falls outside the max. The start is no later than the group covering the live edge less
* `delay.min` and the warmup: one that starts at or before that point. Both default to zero,
* which the newest group covers, so the start waits for nothing. Otherwise groups can arrive
* newest first, so when none that arrived covers that point the start waits for an earlier one,
Expand Down
138 changes: 135 additions & 3 deletions js/net/src/track.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -610,17 +610,18 @@ test("multiple subscriber options aggregate like Rust", async () => {
delay: { min: Duration.millis(50), max: Duration.millis(250) },
ranges: [{ start: { absolute: 5n } }],
});
// A minimum that went unstated, as a legacy peer's does, never pulls the smallest to zero.
// A minimum that went unstated, as a legacy peer's does, counts for nothing.
const legacy = producer.subscribe({
delay: { min: null, max: Duration.millis(0) },
ranges: [{ start: { absolute: 5n } }],
});

// One descending subscriber makes the aggregate descending, so a live reader is never held
// behind another's backlog.
// behind another's backlog. The largest minimum wins, so an upstream reaches back far enough
// for the reader that buffers most.
expect(producer.subscription.peek()).toEqual({
priority: 7,
delay: { min: Duration.millis(50), max: Duration.millis(250) },
delay: { min: Duration.millis(400), max: Duration.millis(250) },
order: "descending",
ranges: [{ start: { absolute: 5n } }],
});
Expand Down Expand Up @@ -860,6 +861,137 @@ test("a time range reads the groups containing its times, settling its end as gr
expect(hooks.servingEnd(reader)).toBe(4n);
});

// Every group `reader` can take now, in delivery order.
function readable(reader: ReturnType<TrackProducer["subscribe"]>): bigint[] {
const got: bigint[] = [];
for (let group = reader.tryRecvGroup(); group; group = reader.tryRecvGroup()) got.push(group.sequence);
return got;
}

// A timed track of 500 ms groups 0 through 10, each presenting at its start.
function halfSecondGroups(): TrackProducer {
const producer = new TrackProducer("test");
producer.accept({ timescale: Timescale.MILLI, maxAge: null });
for (let sequence = 0n; sequence <= 10n; sequence++) appendHalfSecond(producer, sequence);
return producer;
}

function appendHalfSecond(producer: TrackProducer, sequence: bigint): void {
const group = producer.createGroup(sequence);
group.writeFrame(textFrame(`${sequence}`, Timestamp.fromMillis(Number(sequence) * 500)));
group.finish();
}

test("a live join reaches back by its min age", () => {
const producer = halfSecondGroups();
const reader = producer.subscribe({ delay: { min: Duration.secs(2), max: Duration.secs(30) }, ranges: [LIVE] });
// The newest frame presents at 5 s, so the join starts at the group containing 3 s.
expect(readable(reader)).toEqual([6n, 7n, 8n, 9n, 10n]);
appendHalfSecond(producer, 11n);
expect(readable(reader)).toEqual([11n]);
});

test("a min age update reaches a live join not yet started", () => {
const producer = new TrackProducer("test");
producer.accept({ timescale: Timescale.MILLI, maxAge: null });
const reader = producer.subscribe({ delay: { min: Duration.secs(1), max: Duration.secs(30) }, ranges: [LIVE] });
expect(readable(reader)).toEqual([]);
reader.update({ delay: { min: Duration.secs(2), max: Duration.secs(30) }, ranges: [LIVE] });
for (let sequence = 0n; sequence <= 10n; sequence++) appendHalfSecond(producer, sequence);
expect(readable(reader)).toEqual([6n, 7n, 8n, 9n, 10n]);
});

test("a live join without a min age starts at the latest group, and the oldest start ignores it", () => {
const producer = halfSecondGroups();
const all = Array.from({ length: 11 }, (_, sequence) => BigInt(sequence));
for (const min of [null, Duration.ZERO]) {
const live = producer.subscribe({ delay: { min, max: Duration.secs(30) }, ranges: [LIVE] });
expect(readable(live)).toEqual([10n]);
}
for (const min of [null, Duration.ZERO, Duration.secs(2)]) {
const oldest = producer.subscribe({ delay: { min, max: Duration.secs(30) } });
expect(readable(oldest)).toEqual(all);
}
// Past everything held, it starts at the oldest group; a named start ignores it.
const far = producer.subscribe({ delay: { min: Duration.secs(60), max: Duration.secs(30) }, ranges: [LIVE] });
expect(readable(far)).toEqual(all);
const named = producer.subscribe({
delay: { min: Duration.secs(2), max: Duration.secs(30) },
ranges: [{ start: { relative: 1n } }],
});
expect(readable(named)).toEqual([9n, 10n]);
});

test("a live join reads nothing until the groups held measure the live edge", () => {
const producer = new TrackProducer("test");
// Groups written before accept say nothing yet of whether the track is timed.
const groups = Array.from({ length: 11 }, (_, sequence) => producer.createGroup(BigInt(sequence)));
const reader = producer.subscribe({ delay: { min: Duration.secs(2), max: Duration.secs(30) }, ranges: [LIVE] });
expect(readable(reader)).toEqual([]);
producer.accept({ timescale: Timescale.MILLI, maxAge: null });
// Accepted, but still only headers: nothing to measure by.
expect(readable(reader)).toEqual([]);
for (const [sequence, group] of groups.entries()) {
group.writeFrame(textFrame(`${sequence}`, Timestamp.fromMillis(sequence * 500)));
group.finish();
}
expect(readable(reader)).toEqual([6n, 7n, 8n, 9n, 10n]);
});

test("a live join reaches back by ticks rounded up, at any timestamp the track accepts", () => {
const producer = new TrackProducer("test");
producer.accept({ timescale: Timescale.MILLI, maxAge: null });
// Past what microseconds can hold as a safe number.
const base = 10_000_000_000_000;
for (let sequence = 0; sequence <= 2; sequence++) {
const group = producer.createGroup(BigInt(sequence));
group.writeFrame(textFrame(`${sequence}`, Timestamp.fromMillis(base + sequence)));
group.finish();
}
// 1.5 ms back from 2 ms past the base is 0.5 ms past it, which only group 0 starts by.
const reader = producer.subscribe({
delay: { min: Duration.micros(1500), max: Duration.secs(30) },
ranges: [LIVE],
});
expect(readable(reader)).toEqual([0n, 1n, 2n]);
});

test("a live join measures timestamps between ticks, floored", () => {
const producer = new TrackProducer("test");
producer.accept({ timescale: Timescale.MILLI, maxAge: null });
for (const [sequence, ms] of [0.5, 1.5, 2.5].entries()) {
const group = producer.createGroup(BigInt(sequence));
group.writeFrame(textFrame(`${sequence}`, Timestamp.fromMillis(ms)));
group.finish();
}
// The edge floors to 2 ms, so 1 ms back is the group starting by 1 ms.
const reader = producer.subscribe({ delay: { min: Duration.millis(1), max: Duration.secs(30) }, ranges: [LIVE] });
expect(readable(reader)).toEqual([1n, 2n]);
});

test("a scale-less join reaches back by arrival", () => {
const clock = manualTime(0);
try {
const producer = new TrackProducer("test");
producer.accept({ maxAge: null });
// Group N arrives N seconds in, and the join comes at 5 s.
for (let sequence = 0n; sequence < 5n; sequence++) {
const group = producer.createGroup(sequence);
group.writeFrame(textFrame(`${sequence}`, Timestamp.unscaled(sequence)));
group.finish();
clock.set(Number(sequence + 1n) * 1000);
}
const reader = producer.subscribe({
delay: { min: Duration.millis(2500), max: Duration.secs(30) },
ranges: [LIVE],
});
expect(readable(reader)).toEqual([2n, 3n, 4n]);
producer.close();
} finally {
clock.installed.close();
}
});

// A reached end leaves a held group that may still start, so a time start still waits on it.
test("a time start waits on groups below a reached end that have yet to start", () => {
for (const order of ["ascending", "descending"] as const) {
Expand Down
Loading