Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
49c7a1e
chore(quest): claim Rust frame continuity signaling
kixelated Oct 10, 2026
f0dc21e
feat(mux): expose container and audio delivery continuity
kixelated Oct 10, 2026
279e568
chore: merge main into Rust delivery continuity
kixelated Oct 11, 2026
bf89731
fix(audio): preserve continuity across resampler tails
kixelated Oct 11, 2026
c375772
chore: merge main into Rust delivery continuity
kixelated Oct 12, 2026
4cb9ad2
chore: merge main into Rust delivery continuity
kixelated Oct 12, 2026
9f07a7a
refactor(mux): name the read wrapper container::Delivery; split video…
kixelated Oct 12, 2026
5a0e640
fix(mux): mark the delivery after an evicted current group non-contin…
kixelated Oct 12, 2026
35163c7
Merge remote-tracking branch 'origin/main' into HEAD
kixelated Oct 13, 2026
48ec8c6
feat(mux): read gaps and declared ends as items in delivery order
kixelated Oct 13, 2026
5e9c469
Merge remote-tracking branch 'origin/main' into HEAD
kixelated Oct 13, 2026
c5817e3
fix(interop): read the frame item in the JS native subscriber
kixelated Oct 13, 2026
be9337e
fix(hang): read no gap when a retired group lost nothing
kixelated Oct 13, 2026
69c098b
Merge remote-tracking branch 'origin/main' into HEAD
kixelated Oct 13, 2026
552b23b
fix(mux): read a joined marker's end, and keep gaps for unfinished re…
kixelated Oct 13, 2026
19dc728
fix(cli): a declared end lets play drain the pictures before it
kixelated Oct 13, 2026
9b87c07
Merge remote-tracking branch 'origin/main' into merge-5288
kixelated Oct 13, 2026
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 doc/lib/rs/moq-mux.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,10 @@ set at the init segment, so a new rendition or a changed configuration ends the
export. The [CLI page](/bin/cli#import) covers these and the MPEG-TS specifics:
one program per broadcast, damaged packets, and feed checks.

A container read yields frames plus two markers in delivery order: a gap where
media will never arrive (the join, a skip, a hole) and an end where the
publisher declared its media stops (a pause, a source switch, the finish).

Data tracks are catalog entries too. The [hang page](/concept/hang#data-tracks)
describes the modes. A capture time converts onto the broadcast clock; a
timestamp taken from the source is published as given and lines up with media
Expand Down
15 changes: 11 additions & 4 deletions js/hang/src/container/consumer.nonsequential.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,14 @@ import { Format as LegacyFormat } from "./legacy.ts";

// Standalone from consumer.test.ts so it only pulls the Legacy format, not the CMAF decoder.

/** The next frame, passing over gaps and ends. */
async function nextFrame(consumer: Consumer) {
for (;;) {
const next = await consumer.next();
if (!next || next.kind === "frame") return next;
}
}

function encodeLegacyFrame(timestamp: Time.Micro, payload: Uint8Array): Uint8Array {
const tsBytes = Varint.encode(timestamp);
const data = new Uint8Array(tsBytes.byteLength + payload.byteLength);
Expand Down Expand Up @@ -40,10 +48,9 @@ test("Consumer waits on a non-sequential hang group because it has no per-frame
a.close();
track.writeGroup(a);

// Drain A: its frame, then its group-done marker.
const firstFrame = await consumer.next();
expect(firstFrame?.frame?.payload).toEqual(new Uint8Array([0x01]));
await consumer.next();
// Drain A's frame.
const firstFrame = await nextFrame(consumer);
expect(firstFrame?.frame.payload).toEqual(new Uint8Array([0x01]));

// Park next() before the next group's frames arrive (the live streaming case).
const pending = consumer.next();
Expand Down
53 changes: 28 additions & 25 deletions js/hang/src/container/consumer.outoforder.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,14 @@ import { Format as LegacyFormat } from "./legacy.ts";

// Standalone from consumer.test.ts so it only pulls the Legacy format, not the CMAF decoder.

/** The next frame, passing over gaps and ends. */
async function nextFrame(consumer: Consumer) {
for (;;) {
const next = await consumer.next();
if (!next || next.kind === "frame") return next;
}
}

function encodeLegacyFrame(timestamp: Time.Micro, payload: Uint8Array): Uint8Array {
const tsBytes = Varint.encode(timestamp);
const data = new Uint8Array(tsBytes.byteLength + payload.byteLength);
Expand All @@ -29,14 +37,16 @@ function publish(track: Track.Producer, sequence: number, millis: number) {
group.close();
}

/** Every group and frame the consumer will hand over right now, as [group, payload] pairs. */
/** Every frame the consumer will hand over right now, as [group, payload] pairs. */
async function drain(consumer: Consumer): Promise<[number, number | undefined][]> {
const seen: [number, number | undefined][] = [];
for (;;) {
const next = await Promise.race([consumer.next(), new Promise((resolve) => setTimeout(resolve, 50))]);
const next = await Promise.race([
consumer.next(),
new Promise<undefined>((resolve) => setTimeout(resolve, 50)),
]);
if (!next) break;
const { group, frame } = next as { group: number; frame?: { payload: Uint8Array } };
seen.push([group, frame?.payload[0]]);
if (next.kind === "frame") seen.push([next.group, next.frame.payload[0]]);
}
return seen;
}
Expand All @@ -55,16 +65,15 @@ test("out-of-order groups are delivered rather than dropped", async () => {

// The live edge lands first, and delivery starts there rather than waiting.
publish(track, 3, 30);
expect((await consumer.next())?.frame?.payload).toEqual(new Uint8Array([3]));
expect((await nextFrame(consumer))?.frame.payload).toEqual(new Uint8Array([3]));

// The window's head follows it. Every group is still within both budgets, so all three
// are handed over even though each sits below the group already delivered.
publish(track, 0, 0);
publish(track, 1, 10);
publish(track, 2, 20);

const delivered = (await drain(consumer)).filter(([, payload]) => payload !== undefined);
expect(delivered).toEqual([
expect(await drain(consumer)).toEqual([
[0, 0],
[1, 1],
[2, 2],
Expand All @@ -87,25 +96,25 @@ test("a below-cursor group still downloading is not truncated", async () => {
const live = new Group.Producer(3);
track.writeGroup(live);
publishFrame(live, 3000, 30);
expect((await consumer.next())?.frame?.payload[0]).toBe(30);
expect((await nextFrame(consumer))?.frame.payload[0]).toBe(30);

// A backlog group lands below the cursor, one frame at a time (mid-download).
const backlog = new Group.Producer(1);
track.writeGroup(backlog);
publishFrame(backlog, 1000, 10);
const first = await consumer.next();
const first = await nextFrame(consumer);
expect(first?.group).toBe(1);
expect(first?.frame?.payload[0]).toBe(10);
expect(first?.frame.payload[0]).toBe(10);

// The consumer finds the group's buffer empty while it is still open. It must wait
// rather than shift the group out, so the second frame still arrives.
const pending = consumer.next();
const pending = nextFrame(consumer);
publishFrame(backlog, 1500, 11);
backlog.close();

const second = (await pending) as { group: number; frame?: { payload: Uint8Array } };
expect(second.group).toBe(1);
expect(second.frame?.payload[0]).toBe(11);
const second = await pending;
expect(second?.group).toBe(1);
expect(second?.frame.payload[0]).toBe(11);

live.close();
track.close();
Expand All @@ -120,30 +129,24 @@ test("delayed older groups survive a floor established by two newer groups", asy
format: new LegacyFormat("data"),
maxDelay: Time.Milli(5000),
});
async function nextFrame() {
for (;;) {
const next = await consumer.next();
if (!next || next.frame) return next;
}
}
try {
publish(track, 3, 30);
expect((await nextFrame())?.group).toBe(3);
expect((await nextFrame(consumer))?.group).toBe(3);

const latest = new Group.Producer(4);
track.writeGroup(latest);
publishFrame(latest, 40, 4);
expect((await nextFrame())?.group).toBe(4);
expect((await nextFrame(consumer))?.group).toBe(4);

// Group 1's 10ms frame is valid history, below group 4's 30ms floor.
publish(track, 1, 10);
const backlog = await nextFrame();
const backlog = await nextFrame(consumer);
expect(backlog?.group).toBe(1);
expect(backlog?.frame?.timestamp).toBe(Time.Micro(10_000));
expect(backlog?.frame.timestamp).toBe(Time.Micro(10_000));

// Delivering the backlog must not erase the floor for group 4 itself.
publishFrame(latest, 29, 5);
await expect(nextFrame()).rejects.toThrow("below the previous group start");
await expect(nextFrame(consumer)).rejects.toThrow("below the previous group start");
} finally {
consumer.close();
track.close();
Expand Down
3 changes: 1 addition & 2 deletions js/hang/src/container/consumer.rewind.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ function group(track: Track.Producer, timestamps: number[], end?: number) {
async function frame(consumer: Consumer) {
for (;;) {
const result = await consumer.next();
if (!result || result.frame) return result;
if (!result || result.kind === "frame") return result;
}
}

Expand All @@ -50,7 +50,6 @@ test("Consumer accepts a resuming keyframe before the estimated group end", asyn
group(track, [0, 33_000], 66_000);
expect((await frame(consumer))?.frame?.timestamp).toBe(Time.Micro(0));
expect((await frame(consumer))?.frame?.timestamp).toBe(Time.Micro(33_000));
expect((await consumer.next())?.end).toBe(Time.Micro(66_000));
group(track, [50_000]);
expect((await frame(consumer))?.frame?.timestamp).toBe(Time.Micro(50_000));
} finally {
Expand Down
3 changes: 2 additions & 1 deletion js/hang/src/container/consumer.skips.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,8 @@ for (const count of [1, 16, 256]) {
expect(warn).toHaveBeenLastCalledWith(`skipping slow groups: track=tone 0 -> ${count * 2} count=${count}`);
expect(consumer.buffered.peek()[0]?.start).toBe(Time.Milli(count));
// The retained group is still delivered, and another catch-up reports separately.
expect((await consumer.next())?.group).toBe(count * 2);
expect(await consumer.next()).toEqual({ kind: "gap" });
expect(await consumer.next()).toMatchObject({ kind: "frame", group: count * 2 });
newest.writeFrame({ payload: Varint.encode(count * 1000), timestamp: Time.Timestamp.now() });
write(count * 2 + 2, (count + 1) * 1000);
await buffered(count + 1);
Expand Down
66 changes: 39 additions & 27 deletions js/hang/src/container/consumer.startup.test.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
import { expect, jest, onTestFinished, spyOn, test } from "bun:test";
import { Group, Error as NetError, StreamCode, Time, Track } from "@moq/net";
import { Consumer } from "./consumer.ts";
import { Consumer, type Read } from "./consumer.ts";
import { encodeFrame, Format } from "./legacy.ts";

// Drain the in-memory readers and their continuations without advancing mocked time.
Expand All @@ -13,7 +13,7 @@ function setup(maxDelay = 100) {
format: new Format("video"),
maxDelay: Time.Milli(maxDelay),
});
const results: NonNullable<Awaited<ReturnType<Consumer["next"]>>>[] = [];
const results: Read[] = [];
const warn = spyOn(console, "warn").mockImplementation(() => {});
const reading = (async () => {
for (;;) {
Expand All @@ -35,6 +35,19 @@ function setup(maxDelay = 100) {
return { track, consumer, results, warn };
}

// Each item as "gap", "<group>@<µs>" for a frame, or "end <group>@<µs>".
function items(results: Read[]): string[] {
return results.map((read) => {
if (read.kind === "gap") return "gap";
if (read.kind === "end") return `end ${read.group}@${read.end}`;
return `${read.group}@${read.frame.timestamp}`;
});
}

function frames(results: Read[]) {
return results.flatMap((read) => (read.kind === "frame" ? [read] : []));
}

function write(group: Group.Producer, timestamp: number, marker = false) {
group.writeFrame({
payload: encodeFrame(marker ? new Uint8Array() : new Uint8Array([1]), Time.Micro(timestamp)),
Expand All @@ -46,7 +59,7 @@ for (const emptySuccessor of [false, true]) {
test.each([0, 100])(
`Consumer starts across a hole after an empty reset (empty successor: ${emptySuccessor}, maxDelay: %s)`,
async (maxDelay) => {
const { track, consumer, results, warn } = setup(maxDelay);
const { track, results, warn } = setup(maxDelay);
const stale = new Group.Producer(16);
track.writeGroup(stale);
await flush();
Expand All @@ -58,45 +71,42 @@ for (const emptySuccessor of [false, true]) {
}
stale.close(new NetError.Stream(StreamCode.Old));
await flush();
expect(results.some((result) => result.group === 16 && !result.frame)).toBe(true);
if (emptySuccessor) expect(results.some((result) => result.group === 17 && !result.frame)).toBe(true);
expect(results).toEqual([]);

const sequence = emptySuccessor ? 19 : 18;
const live = new Group.Producer(sequence);
track.writeGroup(live);
for (let i = 0; i < 5; i++) write(live, 1_000_000 + i * 33_333);
await flush();

const frames = results.filter((result) => result.frame);
expect(frames.map((result) => result.group)).toEqual(Array(5).fill(sequence));
expect(frames.map((result) => result.frame?.timestamp)).toEqual(
[1_000_000, 1_033_333, 1_066_666, 1_099_999, 1_133_332].map((timestamp) => Time.Micro(timestamp)),
);
expect(frames.map((result) => result.frame?.keyframe)).toEqual([true, false, false, false, false]);
expect(frames.map((result) => result.continuous)).toEqual([false, true, true, true, true]);
expect(consumer.discontinuity).toBe(0);
expect(items(results)).toEqual([
"gap",
...[1_000_000, 1_033_333, 1_066_666, 1_099_999, 1_133_332].map(
(timestamp) => `${sequence}@${timestamp}`,
),
]);
expect(frames(results).map((read) => read.frame.keyframe)).toEqual([true, false, false, false, false]);
expect(warn).not.toHaveBeenCalled();
},
);
}

test("Consumer preserves a declared marker before its first media across a hole", async () => {
const { track, consumer, results, warn } = setup();
const { track, results, warn } = setup();
const marker = new Group.Producer(16);
track.writeGroup(marker);
write(marker, 0, true);
marker.close();
await flush();
expect(consumer.discontinuity).toBe(1);
expect(items(results)).toEqual(["gap", "end 16@0"]);

const live = new Group.Producer(18);
track.writeGroup(live);
write(live, 50_000);
await flush();
const frames = results.filter((result) => result.frame);
expect(frames).toHaveLength(1);
expect(frames[0]).toMatchObject({ group: 18, discontinuity: 1, continuous: false });
expect(frames[0].frame?.keyframe).toBe(true);
// Group 17 never arrived, so the media after the marker is past a gap.
expect(items(results)).toEqual(["gap", "end 16@0", "gap", "18@50000"]);
expect(frames(results)[0].frame.keyframe).toBe(true);
expect(warn).not.toHaveBeenCalled();
});

Expand All @@ -107,35 +117,37 @@ test.each([false, true])("Consumer still waits for a gap after media (playhead r
write(first, 0);
first.close();
await flush();
expect(results.filter((result) => result.frame)).toHaveLength(1);
expect(items(results)).toEqual(["gap", "16@0"]);

if (reset) {
const marker = new Group.Producer(17);
track.writeGroup(marker);
write(marker, 0, true);
marker.close();
await flush();
expect(consumer.discontinuity).toBe(1);
expect(items(results)).toEqual(["gap", "16@0", "end 17@0"]);
}
const sequence = reset ? 20 : 19;
const later = new Group.Producer(sequence);
track.writeGroup(later);
write(later, 50_000);
await flush();
expect(consumer.buffered.peek().length).toBeGreaterThan(0);
expect(results.filter((result) => result.frame)).toHaveLength(1);
expect(frames(results)).toHaveLength(1);

// Supply the missing, timestamp-contiguous bridge and prove the queued frame survives.
const bridge = new Group.Producer(sequence - 1);
track.writeGroup(bridge);
write(bridge, 0);
bridge.close();
await flush();
expect(results.filter((result) => result.frame).map((result) => result.group)).toEqual([
16,
sequence - 1,
sequence,
// The bridge closes the hole, so nothing reads as a gap past the first.
expect(items(results)).toEqual([
"gap",
"16@0",
...(reset ? ["end 17@0"] : []),
`${sequence - 1}@0`,
`${sequence}@50000`,
]);
expect(consumer.discontinuity).toBe(reset ? 1 : 0);
expect(warn).not.toHaveBeenCalled();
});
Loading
Loading