@norskvideo/moq-hang 0.1.0

package/container/consumer.js

@@ -0,0 +1,424 @@
+/* @ts-self-types="./consumer.d.ts" */
+import * as Moq from "@norskvideo/moq-net";
+import { Effect, Signal } from "@norskvideo/moq-signals";
+/**
+ * A recorded rewind boundary.
+ *
+ * After a backwards timestamp jump, groups can still arrive out of order, so a single
+ * sequence floor is not enough: a late new-epoch group can have a lower sequence than the
+ * group that triggered detection. This keeps just enough state to classify any group by
+ * its (sequence, timestamp).
+ */
+class Reset {
+    /** Highest-sequence old-epoch group seen at detection. At or below this is old: drop. */
+    prevMax;
+    /** The group whose backwards timestamp triggered detection. At or above this is new: keep. */
+    group;
+    /** That group's timestamp; in the ambiguous span, old stragglers sit at or above it. */
+    timestamp;
+    constructor(prevMax, group, timestamp) {
+        this.prevMax = prevMax;
+        this.group = group;
+        this.timestamp = timestamp;
+    }
+    /** Classify by sequence alone: true=old, false=new, undefined=ambiguous (resolve by timestamp). */
+    bySequence(sequence) {
+        if (sequence <= this.prevMax)
+            return true;
+        if (sequence >= this.group)
+            return false;
+        return undefined;
+    }
+    /** Whether a group belongs to the reneged old epoch and should be dropped. */
+    isStale(sequence, timestamp) {
+        return this.bySequence(sequence) ?? timestamp >= this.timestamp;
+    }
+}
+/**
+ * Live state for detecting timeline rewinds and classifying out-of-order groups.
+ *
+ * A publisher reneges its buffered tail by rewinding timestamps while group sequence keeps
+ * climbing (e.g. a voice agent interrupted mid-utterance). We track the live edge to spot the
+ * jump, a {@link Reset} boundary to classify out-of-order groups across it, and a counter that
+ * downstream consumers watch to flush their own queues.
+ */
+class Rewind {
+    /** The live edge of playback: max delivered timestamp and the group that carried it. */
+    liveEdge;
+    /** The active rewind boundary, if any. */
+    boundary;
+    /** Increments on every rewind; downstream consumers flush their queues when it changes. */
+    discontinuity = 0;
+}
+/** Reads frames from a MoQ track in order, buffering groups and skipping slow ones to meet the latency target. */
+export class Consumer {
+    #track;
+    #format;
+    #latency;
+    #groups = [];
+    #active; // the active group sequence number
+    #rewind = new Rewind(); // live edge + active boundary + discontinuity count
+    // Wake up the consumer when a new frame is available.
+    #notify;
+    #buffered = new Signal([]);
+    /** The time ranges currently buffered and ready to play. */
+    buffered = this.#buffered;
+    #signals = new Effect();
+    /** Start consuming the given track, decoding frames with `props.format`. */
+    constructor(track, props) {
+        this.#track = track;
+        this.#format = props.format;
+        this.#latency = Signal.from(props.latency ?? Moq.Time.Milli.zero);
+        this.#signals.spawn(this.#run.bind(this));
+        this.#signals.cleanup(() => {
+            this.#track.close();
+            for (const group of this.#groups) {
+                group.consumer.close();
+            }
+            this.#groups.length = 0;
+        });
+    }
+    async #run() {
+        // Start fetching groups in the background
+        for (;;) {
+            const consumer = await this.#track.recvGroup();
+            if (!consumer)
+                break;
+            // To improve TTV, we always start with the first group.
+            // For higher latencies we might need to figure something else out, as its racey.
+            if (this.#active === undefined) {
+                this.#active = consumer.sequence;
+            }
+            // Normally we drop anything behind the cursor. With an active reset the cursor isn't
+            // a valid floor (a late new-epoch group can sit below it); defer to the boundary and
+            // admit ambiguous groups so #runGroup can rule on them once their timestamps arrive.
+            let drop;
+            if (this.#rewind.boundary) {
+                const verdict = this.#rewind.boundary.bySequence(consumer.sequence);
+                if (verdict === undefined)
+                    drop = false;
+                else if (verdict)
+                    drop = true;
+                else
+                    drop = consumer.sequence < this.#active;
+            }
+            else {
+                drop = consumer.sequence < this.#active;
+            }
+            if (drop) {
+                console.warn(`skipping old group: track=${this.#track.name} ${consumer.sequence}`);
+                consumer.close();
+                continue;
+            }
+            const group = {
+                consumer,
+                frames: [],
+            };
+            // Insert into #groups based on the group sequence number (ascending).
+            // This is used to cancel old groups.
+            this.#groups.push(group);
+            this.#groups.sort((a, b) => a.consumer.sequence - b.consumer.sequence);
+            // If #active parked in a gap below the (new) oldest group, snap it
+            // forward so this group plays rather than stalling until a skip.
+            this.#syncActive();
+            // Start buffering frames from this group
+            this.#signals.spawn(this.#runGroup.bind(this, group));
+        }
+    }
+    async #runGroup(group) {
+        try {
+            let index = 0;
+            for (;;) {
+                const next = await group.consumer.readFrameSequence();
+                if (!next)
+                    break;
+                const decoded = this.#format.decode(next.data, next.extensions);
+                for (const sample of decoded) {
+                    const frame = {
+                        data: sample.data,
+                        timestamp: sample.timestamp,
+                        // Protocol invariant: groups always start at a keyframe.
+                        // For index 0, we enforce this regardless of what the format reports.
+                        // For index > 0, we trust the format's keyframe detection.
+                        keyframe: index === 0 ? true : sample.keyframe,
+                    };
+                    index++;
+                    group.frames.push(frame);
+                    if (group.latest === undefined || frame.timestamp > group.latest) {
+                        group.latest = frame.timestamp;
+                    }
+                    this.#updateBuffered();
+                    if (group.consumer.sequence === this.#active) {
+                        this.#notify?.();
+                        this.#notify = undefined;
+                    }
+                    else {
+                        // Newer group: resolve it against an active reset (dropping a reneged
+                        // straggler), else detect a new rewind, then check latency.
+                        if (this.#classifyStale(group))
+                            return;
+                        this.#checkReset(group);
+                        this.#checkLatency();
+                    }
+                }
+            }
+        }
+        catch (_err) {
+            // Stop reading the group but keep already-decoded frames.
+            // A decode error or stream RESET truncates the tail of the GoP;
+            // frames decoded before the error are still valid and playable.
+        }
+        finally {
+            group.done = true;
+            // #active advances when a group is *removed* (fully played) in next(),
+            // via #syncActive — a group finishing reading doesn't mean it's played.
+            // (Group ids are not consecutive, so we never `+= 1`; see #syncActive.)
+            // Recompute buffered ranges now that this group is done,
+            // so consecutive done groups can merge into a single range.
+            this.#updateBuffered();
+            // Always notify - the consumer may need to advance past this group
+            // even if it wasn't active when this task finished.
+            this.#notify?.();
+            this.#notify = undefined;
+            group.consumer.close();
+        }
+    }
+    // Snap #active forward to the oldest buffered group when it has fallen into a
+    // gap below it. MoQ group ids track the media clock and are NOT necessarily
+    // consecutive (spec §2.3.1; gaps are explicit via §12.8 Prior Group ID Gap),
+    // so advancing by `+ 1` lands in a gap and the next real group never becomes
+    // active — it buffers until #checkLatency skips it. Snapping to the oldest
+    // actual sequence lets next() play each group. Only ever moves forward to the
+    // oldest available group (never past it), so it can't skip content.
+    #syncActive() {
+        const oldest = this.#groups[0]?.consumer.sequence;
+        if (oldest !== undefined && (this.#active === undefined || this.#active < oldest)) {
+            this.#active = oldest;
+        }
+    }
+    #checkLatency() {
+        if (this.#active === undefined)
+            return;
+        let skipped = false;
+        // Keep skipping the oldest group while the buffered span exceeds the latency target.
+        // This also handles gaps in group sequence numbers: if #active points to a missing
+        // group, the latency span proves the missing content is too old to wait for.
+        while (this.#groups.length >= 2) {
+            const threshold = Moq.Time.Micro.fromMilli(this.#latency.peek());
+            // Check the difference between the earliest and latest known frames.
+            let min;
+            let max;
+            for (const group of this.#groups) {
+                if (group.latest === undefined)
+                    continue;
+                const frame = group.frames.at(0)?.timestamp ?? group.latest;
+                if (min === undefined || frame < min)
+                    min = frame;
+                if (max === undefined || group.latest > max)
+                    max = group.latest;
+            }
+            if (min === undefined || max === undefined)
+                break;
+            const latency = max - min;
+            if (latency <= threshold)
+                break;
+            const first = this.#groups.shift();
+            if (!first)
+                break;
+            this.#active = this.#groups[0]?.consumer.sequence;
+            console.warn(`skipping slow group: track=${this.#track.name} ${first.consumer.sequence} -> ${this.#active}`);
+            first.consumer.close();
+            first.frames.length = 0;
+            skipped = true;
+        }
+        if (skipped) {
+            this.#updateBuffered();
+            // Wake up any consumers waiting for a new frame.
+            this.#notify?.();
+            this.#notify = undefined;
+        }
+    }
+    // Detect a publisher "rewind" and record the reneged boundary. A newer group (sequence
+    // climbs) whose earliest frame lands before the live edge (timestamp goes backwards) can
+    // only be an explicit reneg of the buffered tail; record the boundary, bump the
+    // discontinuity counter, drop the groups it proves stale, and resume from the earliest
+    // survivor. Groups still ambiguous (a late new-epoch group vs. an old straggler) are kept
+    // and resolved by #classifyStale once their timestamps arrive.
+    #checkReset(group) {
+        if (this.#active === undefined)
+            return;
+        const live = this.#rewind.liveEdge;
+        if (live === undefined)
+            return;
+        // Only a group newer than the active one can rewind the timeline.
+        if (group.consumer.sequence <= this.#active)
+            return;
+        const start = group.frames.at(0)?.timestamp;
+        if (start === undefined)
+            return;
+        // A rewind is the timestamp going strictly backwards past the live edge. Anything at
+        // or ahead of it is normal forward motion.
+        if (start >= live.timestamp)
+            return;
+        const reset = new Reset(live.group, group.consumer.sequence, start);
+        this.#rewind.boundary = reset;
+        this.#rewind.discontinuity++;
+        // Drop buffered groups the boundary can already prove stale; keep ambiguous ones.
+        this.#groups = this.#groups.filter((g) => {
+            const verdict = reset.bySequence(g.consumer.sequence);
+            const first = g.frames.at(0);
+            const stale = verdict ?? (first !== undefined && reset.isStale(g.consumer.sequence, first.timestamp));
+            if (stale) {
+                g.consumer.close();
+                g.frames.length = 0;
+            }
+            return !stale;
+        });
+        console.warn(`buffer reset: track=${this.#track.name} group timestamps rewound (prevMax ${reset.prevMax}, group ${reset.group})`);
+        // Resume from the earliest survivor; if none, from the rewound group. Anchor the live
+        // edge at the rewind point (delivered), not group.latest (buffered ahead of playback).
+        this.#active = this.#groups[0]?.consumer.sequence ?? reset.group;
+        this.#rewind.liveEdge = { group: reset.group, timestamp: start };
+        this.#updateBuffered();
+        // Wake up any consumer waiting for a new frame.
+        this.#notify?.();
+        this.#notify = undefined;
+    }
+    // Drop a group that an active reset resolves as a reneged old straggler (its timestamp
+    // landed at or above the reset point). Returns true if the group was dropped.
+    #classifyStale(group) {
+        const reset = this.#rewind.boundary;
+        if (!reset)
+            return false;
+        const first = group.frames.at(0);
+        if (first === undefined)
+            return false;
+        if (!reset.isStale(group.consumer.sequence, first.timestamp))
+            return false;
+        this.#groups = this.#groups.filter((g) => g !== group);
+        group.consumer.close();
+        group.frames.length = 0;
+        this.#updateBuffered();
+        return true;
+    }
+    // Re-check buffered newer groups against the current live edge. #checkReset otherwise only
+    // runs when a group receives a frame, so a group that buffered while the live edge was lower
+    // (or undefined) is never reconsidered once delivery advances the edge past it, and the
+    // rewind would be missed. Highest sequence first, mirroring the Rust scan: the first rewound
+    // group becomes the boundary, and #checkReset's own guards make the rest no-ops.
+    #checkBufferedReset() {
+        if (this.#active === undefined || this.#rewind.liveEdge === undefined)
+            return;
+        for (const group of [...this.#groups].reverse()) {
+            if (group.consumer.sequence <= this.#active)
+                break;
+            this.#checkReset(group);
+        }
+    }
+    /**
+     * Returns the next frame in order along with its group number and the current
+     * {@link discontinuity} count, awaiting one if needed. A `frame` of undefined signals the
+     * end of that group; the overall result is undefined once closed. When `discontinuity`
+     * jumps relative to the previous call, the publisher rewound the timeline: flush any
+     * downstream decoder or render buffers before playing this frame.
+     */
+    async next() {
+        for (;;) {
+            // A group may have buffered a rewind while the live edge was still behind it; catch it
+            // now that delivery has advanced the edge.
+            this.#checkBufferedReset();
+            // Keep #active tracking the oldest buffered group across non-consecutive
+            // group ids (see #syncActive).
+            this.#syncActive();
+            if (this.#groups.length > 0 &&
+                this.#active !== undefined &&
+                this.#groups[0].consumer.sequence <= this.#active) {
+                const frame = this.#groups[0].frames.shift();
+                if (frame) {
+                    const seq = this.#groups[0].consumer.sequence;
+                    // Track the live edge (max timestamp + its group) so a later backwards jump
+                    // is detectable and the old epoch's tail is anchored.
+                    const live = this.#rewind.liveEdge;
+                    if (live === undefined || frame.timestamp > live.timestamp) {
+                        this.#rewind.liveEdge = { group: seq, timestamp: frame.timestamp };
+                    }
+                    this.#updateBuffered();
+                    return { frame, group: seq, discontinuity: this.#rewind.discontinuity };
+                }
+                // Check if the group is done and then remove it.
+                // A group is removable when #active has advanced past it, OR when
+                // its #runGroup task has finished (done) and all frames are consumed.
+                // The latter handles the case where #runGroup finished before
+                // #active reached this group (e.g. after a latency skip).
+                if (this.#active > this.#groups[0].consumer.sequence || this.#groups[0].done) {
+                    const group = this.#groups.shift();
+                    if (group) {
+                        // Advance to the next buffered group (ids are not consecutive).
+                        this.#syncActive();
+                        this.#updateBuffered();
+                        return {
+                            frame: undefined,
+                            group: group.consumer.sequence,
+                            discontinuity: this.#rewind.discontinuity,
+                        };
+                    }
+                }
+            }
+            if (this.#notify) {
+                throw new Error("multiple calls to next not supported");
+            }
+            const abort = this.#signals.abort;
+            if (abort.aborted)
+                return undefined;
+            const aborted = await new Promise((resolve) => {
+                const onAbort = () => resolve(true);
+                abort.addEventListener("abort", onAbort, { once: true });
+                this.#notify = () => {
+                    abort.removeEventListener("abort", onAbort);
+                    resolve(false);
+                };
+            });
+            this.#notify = undefined;
+            if (aborted)
+                return undefined;
+        }
+    }
+    #updateBuffered() {
+        const ranges = [];
+        let prev;
+        for (const group of this.#groups) {
+            const first = group.frames.at(0);
+            if (!first || group.latest === undefined)
+                continue;
+            const start = Moq.Time.Milli.fromMicro(first.timestamp);
+            const end = Moq.Time.Milli.fromMicro(group.latest);
+            const last = ranges.at(-1);
+            // `prev` is the immediately-preceding buffered group (this loop walks
+            // #groups in ascending order), so a done `prev` means these two groups
+            // are buffer-adjacent. We can't test `prev.sequence + 1 === sequence`
+            // because group ids are not consecutive (spec §2.3.1).
+            const contiguous = prev?.done === true;
+            if (last && (last.end >= start || contiguous)) {
+                last.end = Moq.Time.Milli.max(last.end, end);
+            }
+            else {
+                ranges.push({ start, end });
+            }
+            prev = group;
+        }
+        this.#buffered.set(ranges);
+    }
+    /**
+     * A counter that increments each time the consumer detects a timeline rewind and drops the
+     * reneged buffer. Also surfaced per-read via {@link next}; downstream consumers flush their
+     * decoder and render buffers when it changes.
+     */
+    get discontinuity() {
+        return this.#rewind.discontinuity;
+    }
+    /** Stop consuming and release the track and all buffered groups. */
+    close() {
+        this.#signals.close();
+    }
+}
+//# sourceMappingURL=consumer.js.map

package/container/consumer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consumer.js","sourceRoot":"","sources":["../../src/container/consumer.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Time } from \"@moq/net\";\nimport * as Moq from \"@moq/net\";\nimport { Effect, type Getter, Signal } from \"@moq/signals\";\n\nimport type { Format } from \"./format\";\nimport type { BufferedRanges, Frame } from \"./types\";\n\n/** Options for constructing a {@link Consumer}. */\nexport interface ConsumerProps {\n\t/** The container format used to decode each MoQ frame. */\n\tformat: Format;\n\t/** Target latency in milliseconds, controlling how aggressively slow groups are skipped (default: 0). */\n\tlatency?: Signal<Time.Milli> | Time.Milli;\n}\n\ninterface Group {\n\tconsumer: Moq.Group;\n\tframes: Frame[]; // decode order\n\tlatest?: Time.Micro; // The timestamp of the latest known frame\n\tdone?: boolean; // Set when #runGroup finishes reading all frames\n}\n\n/**\n * A recorded rewind boundary.\n *\n * After a backwards timestamp jump, groups can still arrive out of order, so a single\n * sequence floor is not enough: a late new-epoch group can have a lower sequence than the\n * group that triggered detection. This keeps just enough state to classify any group by\n * its (sequence, timestamp).\n */\nclass Reset {\n\t/** Highest-sequence old-epoch group seen at detection. At or below this is old: drop. */\n\treadonly prevMax: number;\n\t/** The group whose backwards timestamp triggered detection. At or above this is new: keep. */\n\treadonly group: number;\n\t/** That group's timestamp; in the ambiguous span, old stragglers sit at or above it. */\n\treadonly timestamp: Time.Micro;\n\n\tconstructor(prevMax: number, group: number, timestamp: Time.Micro) {\n\t\tthis.prevMax = prevMax;\n\t\tthis.group = group;\n\t\tthis.timestamp = timestamp;\n\t}\n\n\t/** Classify by sequence alone: true=old, false=new, undefined=ambiguous (resolve by timestamp). */\n\tbySequence(sequence: number): boolean | undefined {\n\t\tif (sequence <= this.prevMax) return true;\n\t\tif (sequence >= this.group) return false;\n\t\treturn undefined;\n\t}\n\n\t/** Whether a group belongs to the reneged old epoch and should be dropped. */\n\tisStale(sequence: number, timestamp: Time.Micro): boolean {\n\t\treturn this.bySequence(sequence) ?? timestamp >= this.timestamp;\n\t}\n}\n\n/**\n * Live state for detecting timeline rewinds and classifying out-of-order groups.\n *\n * A publisher reneges its buffered tail by rewinding timestamps while group sequence keeps\n * climbing (e.g. a voice agent interrupted mid-utterance). We track the live edge to spot the\n * jump, a {@link Reset} boundary to classify out-of-order groups across it, and a counter that\n * downstream consumers watch to flush their own queues.\n */\nclass Rewind {\n\t/** The live edge of playback: max delivered timestamp and the group that carried it. */\n\tliveEdge?: { group: number; timestamp: Time.Micro };\n\t/** The active rewind boundary, if any. */\n\tboundary?: Reset;\n\t/** Increments on every rewind; downstream consumers flush their queues when it changes. */\n\tdiscontinuity = 0;\n}\n\n/** Reads frames from a MoQ track in order, buffering groups and skipping slow ones to meet the latency target. */\nexport class Consumer {\n\t#track: Moq.Track;\n\t#format: Format;\n\t#latency: Signal<Time.Milli>;\n\t#groups: Group[] = [];\n\t#active?: number; // the active group sequence number\n\t#rewind = new Rewind(); // live edge + active boundary + discontinuity count\n\n\t// Wake up the consumer when a new frame is available.\n\t#notify?: () => void;\n\n\t#buffered = new Signal<BufferedRanges>([]);\n\t/** The time ranges currently buffered and ready to play. */\n\treadonly buffered: Getter<BufferedRanges> = this.#buffered;\n\n\t#signals = new Effect();\n\n\t/** Start consuming the given track, decoding frames with `props.format`. */\n\tconstructor(track: Moq.Track, props: ConsumerProps) {\n\t\tthis.#track = track;\n\t\tthis.#format = props.format;\n\t\tthis.#latency = Signal.from(props.latency ?? Moq.Time.Milli.zero);\n\n\t\tthis.#signals.spawn(this.#run.bind(this));\n\t\tthis.#signals.cleanup(() => {\n\t\t\tthis.#track.close();\n\t\t\tfor (const group of this.#groups) {\n\t\t\t\tgroup.consumer.close();\n\t\t\t}\n\t\t\tthis.#groups.length = 0;\n\t\t});\n\t}\n\n\tasync #run() {\n\t\t// Start fetching groups in the background\n\t\tfor (;;) {\n\t\t\tconst consumer = await this.#track.recvGroup();\n\t\t\tif (!consumer) break;\n\n\t\t\t// To improve TTV, we always start with the first group.\n\t\t\t// For higher latencies we might need to figure something else out, as its racey.\n\t\t\tif (this.#active === undefined) {\n\t\t\t\tthis.#active = consumer.sequence;\n\t\t\t}\n\n\t\t\t// Normally we drop anything behind the cursor. With an active reset the cursor isn't\n\t\t\t// a valid floor (a late new-epoch group can sit below it); defer to the boundary and\n\t\t\t// admit ambiguous groups so #runGroup can rule on them once their timestamps arrive.\n\t\t\tlet drop: boolean;\n\t\t\tif (this.#rewind.boundary) {\n\t\t\t\tconst verdict = this.#rewind.boundary.bySequence(consumer.sequence);\n\t\t\t\tif (verdict === undefined) drop = false;\n\t\t\t\telse if (verdict) drop = true;\n\t\t\t\telse drop = consumer.sequence < this.#active;\n\t\t\t} else {\n\t\t\t\tdrop = consumer.sequence < this.#active;\n\t\t\t}\n\n\t\t\tif (drop) {\n\t\t\t\tconsole.warn(`skipping old group: track=${this.#track.name} ${consumer.sequence}`);\n\t\t\t\tconsumer.close();\n\t\t\t\tcontinue;\n\t\t\t}\n\n\t\t\tconst group: Group = {\n\t\t\t\tconsumer,\n\t\t\t\tframes: [],\n\t\t\t};\n\n\t\t\t// Insert into #groups based on the group sequence number (ascending).\n\t\t\t// This is used to cancel old groups.\n\t\t\tthis.#groups.push(group);\n\t\t\tthis.#groups.sort((a, b) => a.consumer.sequence - b.consumer.sequence);\n\n\t\t\t// If #active parked in a gap below the (new) oldest group, snap it\n\t\t\t// forward so this group plays rather than stalling until a skip.\n\t\t\tthis.#syncActive();\n\n\t\t\t// Start buffering frames from this group\n\t\t\tthis.#signals.spawn(this.#runGroup.bind(this, group));\n\t\t}\n\t}\n\n\tasync #runGroup(group: Group) {\n\t\ttry {\n\t\t\tlet index = 0;\n\n\t\t\tfor (;;) {\n\t\t\t\tconst next = await group.consumer.readFrameSequence();\n\t\t\t\tif (!next) break;\n\n\t\t\t\tconst decoded = this.#format.decode(next.data, next.extensions);\n\n\t\t\t\tfor (const sample of decoded) {\n\t\t\t\t\tconst frame: Frame = {\n\t\t\t\t\t\tdata: sample.data,\n\t\t\t\t\t\ttimestamp: sample.timestamp,\n\t\t\t\t\t\t// Protocol invariant: groups always start at a keyframe.\n\t\t\t\t\t\t// For index 0, we enforce this regardless of what the format reports.\n\t\t\t\t\t\t// For index > 0, we trust the format's keyframe detection.\n\t\t\t\t\t\tkeyframe: index === 0 ? true : sample.keyframe,\n\t\t\t\t\t};\n\n\t\t\t\t\tindex++;\n\n\t\t\t\t\tgroup.frames.push(frame);\n\n\t\t\t\t\tif (group.latest === undefined || frame.timestamp > group.latest) {\n\t\t\t\t\t\tgroup.latest = frame.timestamp;\n\t\t\t\t\t}\n\n\t\t\t\t\tthis.#updateBuffered();\n\n\t\t\t\t\tif (group.consumer.sequence === this.#active) {\n\t\t\t\t\t\tthis.#notify?.();\n\t\t\t\t\t\tthis.#notify = undefined;\n\t\t\t\t\t} else {\n\t\t\t\t\t\t// Newer group: resolve it against an active reset (dropping a reneged\n\t\t\t\t\t\t// straggler), else detect a new rewind, then check latency.\n\t\t\t\t\t\tif (this.#classifyStale(group)) return;\n\t\t\t\t\t\tthis.#checkReset(group);\n\t\t\t\t\t\tthis.#checkLatency();\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t} catch (_err) {\n\t\t\t// Stop reading the group but keep already-decoded frames.\n\t\t\t// A decode error or stream RESET truncates the tail of the GoP;\n\t\t\t// frames decoded before the error are still valid and playable.\n\t\t} finally {\n\t\t\tgroup.done = true;\n\n\t\t\t// #active advances when a group is *removed* (fully played) in next(),\n\t\t\t// via #syncActive — a group finishing reading doesn't mean it's played.\n\t\t\t// (Group ids are not consecutive, so we never `+= 1`; see #syncActive.)\n\n\t\t\t// Recompute buffered ranges now that this group is done,\n\t\t\t// so consecutive done groups can merge into a single range.\n\t\t\tthis.#updateBuffered();\n\n\t\t\t// Always notify - the consumer may need to advance past this group\n\t\t\t// even if it wasn't active when this task finished.\n\t\t\tthis.#notify?.();\n\t\t\tthis.#notify = undefined;\n\n\t\t\tgroup.consumer.close();\n\t\t}\n\t}\n\n\t// Snap #active forward to the oldest buffered group when it has fallen into a\n\t// gap below it. MoQ group ids track the media clock and are NOT necessarily\n\t// consecutive (spec §2.3.1; gaps are explicit via §12.8 Prior Group ID Gap),\n\t// so advancing by `+ 1` lands in a gap and the next real group never becomes\n\t// active — it buffers until #checkLatency skips it. Snapping to the oldest\n\t// actual sequence lets next() play each group. Only ever moves forward to the\n\t// oldest available group (never past it), so it can't skip content.\n\t#syncActive(): void {\n\t\tconst oldest = this.#groups[0]?.consumer.sequence;\n\t\tif (oldest !== undefined && (this.#active === undefined || this.#active < oldest)) {\n\t\t\tthis.#active = oldest;\n\t\t}\n\t}\n\n\t#checkLatency() {\n\t\tif (this.#active === undefined) return;\n\n\t\tlet skipped = false;\n\n\t\t// Keep skipping the oldest group while the buffered span exceeds the latency target.\n\t\t// This also handles gaps in group sequence numbers: if #active points to a missing\n\t\t// group, the latency span proves the missing content is too old to wait for.\n\t\twhile (this.#groups.length >= 2) {\n\t\t\tconst threshold = Moq.Time.Micro.fromMilli(this.#latency.peek());\n\n\t\t\t// Check the difference between the earliest and latest known frames.\n\t\t\tlet min: number | undefined;\n\t\t\tlet max: number | undefined;\n\n\t\t\tfor (const group of this.#groups) {\n\t\t\t\tif (group.latest === undefined) continue;\n\n\t\t\t\tconst frame = group.frames.at(0)?.timestamp ?? group.latest;\n\t\t\t\tif (min === undefined || frame < min) min = frame;\n\t\t\t\tif (max === undefined || group.latest > max) max = group.latest;\n\t\t\t}\n\n\t\t\tif (min === undefined || max === undefined) break;\n\n\t\t\tconst latency = max - min;\n\t\t\tif (latency <= threshold) break;\n\n\t\t\tconst first = this.#groups.shift();\n\t\t\tif (!first) break;\n\t\t\tthis.#active = this.#groups[0]?.consumer.sequence;\n\t\t\tconsole.warn(\n\t\t\t\t`skipping slow group: track=${this.#track.name} ${first.consumer.sequence} -> ${this.#active}`,\n\t\t\t);\n\n\t\t\tfirst.consumer.close();\n\t\t\tfirst.frames.length = 0;\n\t\t\tskipped = true;\n\t\t}\n\n\t\tif (skipped) {\n\t\t\tthis.#updateBuffered();\n\n\t\t\t// Wake up any consumers waiting for a new frame.\n\t\t\tthis.#notify?.();\n\t\t\tthis.#notify = undefined;\n\t\t}\n\t}\n\n\t// Detect a publisher \"rewind\" and record the reneged boundary. A newer group (sequence\n\t// climbs) whose earliest frame lands before the live edge (timestamp goes backwards) can\n\t// only be an explicit reneg of the buffered tail; record the boundary, bump the\n\t// discontinuity counter, drop the groups it proves stale, and resume from the earliest\n\t// survivor. Groups still ambiguous (a late new-epoch group vs. an old straggler) are kept\n\t// and resolved by #classifyStale once their timestamps arrive.\n\t#checkReset(group: Group) {\n\t\tif (this.#active === undefined) return;\n\n\t\tconst live = this.#rewind.liveEdge;\n\t\tif (live === undefined) return;\n\n\t\t// Only a group newer than the active one can rewind the timeline.\n\t\tif (group.consumer.sequence <= this.#active) return;\n\n\t\tconst start = group.frames.at(0)?.timestamp;\n\t\tif (start === undefined) return;\n\n\t\t// A rewind is the timestamp going strictly backwards past the live edge. Anything at\n\t\t// or ahead of it is normal forward motion.\n\t\tif (start >= live.timestamp) return;\n\n\t\tconst reset = new Reset(live.group, group.consumer.sequence, start);\n\t\tthis.#rewind.boundary = reset;\n\t\tthis.#rewind.discontinuity++;\n\n\t\t// Drop buffered groups the boundary can already prove stale; keep ambiguous ones.\n\t\tthis.#groups = this.#groups.filter((g) => {\n\t\t\tconst verdict = reset.bySequence(g.consumer.sequence);\n\t\t\tconst first = g.frames.at(0);\n\t\t\tconst stale = verdict ?? (first !== undefined && reset.isStale(g.consumer.sequence, first.timestamp));\n\t\t\tif (stale) {\n\t\t\t\tg.consumer.close();\n\t\t\t\tg.frames.length = 0;\n\t\t\t}\n\t\t\treturn !stale;\n\t\t});\n\n\t\tconsole.warn(\n\t\t\t`buffer reset: track=${this.#track.name} group timestamps rewound (prevMax ${reset.prevMax}, group ${reset.group})`,\n\t\t);\n\n\t\t// Resume from the earliest survivor; if none, from the rewound group. Anchor the live\n\t\t// edge at the rewind point (delivered), not group.latest (buffered ahead of playback).\n\t\tthis.#active = this.#groups[0]?.consumer.sequence ?? reset.group;\n\t\tthis.#rewind.liveEdge = { group: reset.group, timestamp: start };\n\t\tthis.#updateBuffered();\n\n\t\t// Wake up any consumer waiting for a new frame.\n\t\tthis.#notify?.();\n\t\tthis.#notify = undefined;\n\t}\n\n\t// Drop a group that an active reset resolves as a reneged old straggler (its timestamp\n\t// landed at or above the reset point). Returns true if the group was dropped.\n\t#classifyStale(group: Group): boolean {\n\t\tconst reset = this.#rewind.boundary;\n\t\tif (!reset) return false;\n\n\t\tconst first = group.frames.at(0);\n\t\tif (first === undefined) return false;\n\t\tif (!reset.isStale(group.consumer.sequence, first.timestamp)) return false;\n\n\t\tthis.#groups = this.#groups.filter((g) => g !== group);\n\t\tgroup.consumer.close();\n\t\tgroup.frames.length = 0;\n\t\tthis.#updateBuffered();\n\t\treturn true;\n\t}\n\n\t// Re-check buffered newer groups against the current live edge. #checkReset otherwise only\n\t// runs when a group receives a frame, so a group that buffered while the live edge was lower\n\t// (or undefined) is never reconsidered once delivery advances the edge past it, and the\n\t// rewind would be missed. Highest sequence first, mirroring the Rust scan: the first rewound\n\t// group becomes the boundary, and #checkReset's own guards make the rest no-ops.\n\t#checkBufferedReset(): void {\n\t\tif (this.#active === undefined || this.#rewind.liveEdge === undefined) return;\n\t\tfor (const group of [...this.#groups].reverse()) {\n\t\t\tif (group.consumer.sequence <= this.#active) break;\n\t\t\tthis.#checkReset(group);\n\t\t}\n\t}\n\n\t/**\n\t * Returns the next frame in order along with its group number and the current\n\t * {@link discontinuity} count, awaiting one if needed. A `frame` of undefined signals the\n\t * end of that group; the overall result is undefined once closed. When `discontinuity`\n\t * jumps relative to the previous call, the publisher rewound the timeline: flush any\n\t * downstream decoder or render buffers before playing this frame.\n\t */\n\tasync next(): Promise<{ frame: Frame | undefined; group: number; discontinuity: number } | undefined> {\n\t\tfor (;;) {\n\t\t\t// A group may have buffered a rewind while the live edge was still behind it; catch it\n\t\t\t// now that delivery has advanced the edge.\n\t\t\tthis.#checkBufferedReset();\n\n\t\t\t// Keep #active tracking the oldest buffered group across non-consecutive\n\t\t\t// group ids (see #syncActive).\n\t\t\tthis.#syncActive();\n\n\t\t\tif (\n\t\t\t\tthis.#groups.length > 0 &&\n\t\t\t\tthis.#active !== undefined &&\n\t\t\t\tthis.#groups[0].consumer.sequence <= this.#active\n\t\t\t) {\n\t\t\t\tconst frame = this.#groups[0].frames.shift();\n\t\t\t\tif (frame) {\n\t\t\t\t\tconst seq = this.#groups[0].consumer.sequence;\n\t\t\t\t\t// Track the live edge (max timestamp + its group) so a later backwards jump\n\t\t\t\t\t// is detectable and the old epoch's tail is anchored.\n\t\t\t\t\tconst live = this.#rewind.liveEdge;\n\t\t\t\t\tif (live === undefined || frame.timestamp > live.timestamp) {\n\t\t\t\t\t\tthis.#rewind.liveEdge = { group: seq, timestamp: frame.timestamp };\n\t\t\t\t\t}\n\t\t\t\t\tthis.#updateBuffered();\n\t\t\t\t\treturn { frame, group: seq, discontinuity: this.#rewind.discontinuity };\n\t\t\t\t}\n\n\t\t\t\t// Check if the group is done and then remove it.\n\t\t\t\t// A group is removable when #active has advanced past it, OR when\n\t\t\t\t// its #runGroup task has finished (done) and all frames are consumed.\n\t\t\t\t// The latter handles the case where #runGroup finished before\n\t\t\t\t// #active reached this group (e.g. after a latency skip).\n\t\t\t\tif (this.#active > this.#groups[0].consumer.sequence || this.#groups[0].done) {\n\t\t\t\t\tconst group = this.#groups.shift();\n\t\t\t\t\tif (group) {\n\t\t\t\t\t\t// Advance to the next buffered group (ids are not consecutive).\n\t\t\t\t\t\tthis.#syncActive();\n\t\t\t\t\t\tthis.#updateBuffered();\n\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\tframe: undefined,\n\t\t\t\t\t\t\tgroup: group.consumer.sequence,\n\t\t\t\t\t\t\tdiscontinuity: this.#rewind.discontinuity,\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\n\t\t\tif (this.#notify) {\n\t\t\t\tthrow new Error(\"multiple calls to next not supported\");\n\t\t\t}\n\n\t\t\tconst abort = this.#signals.abort;\n\t\t\tif (abort.aborted) return undefined;\n\n\t\t\tconst aborted = await new Promise<boolean>((resolve) => {\n\t\t\t\tconst onAbort = () => resolve(true);\n\t\t\t\tabort.addEventListener(\"abort\", onAbort, { once: true });\n\t\t\t\tthis.#notify = () => {\n\t\t\t\t\tabort.removeEventListener(\"abort\", onAbort);\n\t\t\t\t\tresolve(false);\n\t\t\t\t};\n\t\t\t});\n\n\t\t\tthis.#notify = undefined;\n\t\t\tif (aborted) return undefined;\n\t\t}\n\t}\n\n\t#updateBuffered(): void {\n\t\tconst ranges: BufferedRanges = [];\n\n\t\tlet prev: Group | undefined;\n\n\t\tfor (const group of this.#groups) {\n\t\t\tconst first = group.frames.at(0);\n\t\t\tif (!first || group.latest === undefined) continue;\n\n\t\t\tconst start = Moq.Time.Milli.fromMicro(first.timestamp);\n\t\t\tconst end = Moq.Time.Milli.fromMicro(group.latest);\n\n\t\t\tconst last = ranges.at(-1);\n\t\t\t// `prev` is the immediately-preceding buffered group (this loop walks\n\t\t\t// #groups in ascending order), so a done `prev` means these two groups\n\t\t\t// are buffer-adjacent. We can't test `prev.sequence + 1 === sequence`\n\t\t\t// because group ids are not consecutive (spec §2.3.1).\n\t\t\tconst contiguous = prev?.done === true;\n\t\t\tif (last && (last.end >= start || contiguous)) {\n\t\t\t\tlast.end = Moq.Time.Milli.max(last.end, end);\n\t\t\t} else {\n\t\t\t\tranges.push({ start, end });\n\t\t\t}\n\n\t\t\tprev = group;\n\t\t}\n\n\t\tthis.#buffered.set(ranges);\n\t}\n\n\t/**\n\t * A counter that increments each time the consumer detects a timeline rewind and drops the\n\t * reneged buffer. Also surfaced per-read via {@link next}; downstream consumers flush their\n\t * decoder and render buffers when it changes.\n\t */\n\tget discontinuity(): number {\n\t\treturn this.#rewind.discontinuity;\n\t}\n\n\t/** Stop consuming and release the track and all buffered groups. */\n\tclose(): void {\n\t\tthis.#signals.close();\n\t}\n}\n"]}

package/container/consumer.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=consumer.test.d.ts.map

package/container/consumer.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consumer.test.d.ts","sourceRoot":"","sources":["../../src/container/consumer.test.ts"],"names":[],"mappings":""}