supervision 0.1.7 → 0.2.0-next.0

package/dist/web-video-engine/frame-timeline-GINI8Gum.js

@@ -0,0 +1,560 @@
+/**
+ * READ_AHEAD_CANVAS is the playback decode-ahead depth: how many decoded frames
+ * the controller keeps queued ahead of the playhead so a decode that overruns a
+ * frame interval does not starve the next tick (the cause of stutter even on
+ * small, well-encoded clips, where playback otherwise pulls one frame per paint
+ * with no cushion). Applies to canvas blits, which are independent and cheap to
+ * hold; sample (zero-copy) frames pin a decoder slot each, so the controller
+ * keeps those at a depth of one to spare the WebCodecs pool.
+ *
+ * REANCHOR_STALL_MS is the wall time past which a picture standing still stops
+ * being a hitch to work through and becomes a stretch to re-anchor across. Two
+ * gaps are measured against it, and they settle in opposite directions.
+ *
+ * A gap between playing render ticks is a loop nothing was driving, which a
+ * hidden tab produces. Nobody was watching, so the clock is the truth and the
+ * walk seeks forward onto the playhead.
+ *
+ * A gap between the walk's deliveries is a pipeline with nothing to show while
+ * the loop ran, which a seek onto unbuffered ground produces. The viewer sat
+ * through it waiting on a position they asked for, so the frame is the truth
+ * and the clock is pulled back onto it. Left to catch up instead, the walk
+ * replays the whole wait at decode speed on its way to the playhead: measured
+ * against the deployed demo over six seeks, a mean 2.4x for a second, peaking
+ * at 24x, with 44 source frames flashed past.
+ *
+ * Wall time is the reading in both, so a high rate legitimately moving the
+ * media clock several frames per gap is not read as an absence.
+ *
+ * Half a second is where the tick-gap costs cross at 1x. A backlog costs one
+ * decode per source frame in it, measured at 240 frames a second on the 30fps
+ * demo clip (4.2ms each), against a keyframe-anchored seek at p95 47ms on the
+ * same clip: half a second of 30fps backlog is 15 frames, so 63ms of decode
+ * against that 47ms, and every higher rate puts more frames in the same gap. It
+ * clears the worst legitimate gap of either kind by the same order: a foreground
+ * loop leaves a long task or a GC pause to the frame-by-frame path, and forty
+ * seconds of network-fed playback of the demo clip held its picture still for at
+ * most 51ms.
+ *
+ * The present cadence is how often playback puts a frame on screen: the rate's
+ * whole demand cut to the share of it the machine has been paying for, and never
+ * under the source's own frame rate. At a full share the pump declines nothing,
+ * which is where a machine with headroom stays at every rate.
+ * A step moves the share by PRESENT_CADENCE_STEP, taking a quarter off it when
+ * the pipeline has fallen behind the playhead and putting that same quarter back
+ * when it has room to spare. The share bottoms out at one over
+ * PLAYBACK_RATE.MAX, which is the deepest cut that means anything: below it even
+ * the fastest rate asks for less than the source rate the cadence floors at.
+ *
+ * What takes the share down is a running bill, in frames, between what the clock
+ * asked the pipeline for and what the play walk delivered. The bill accumulates
+ * rather than being read per tick, which is what tells a shortfall from noise:
+ * counting whole frames against a fractional demand leaves every tick out by up
+ * to one either way and those cancel, while a machine that cannot sustain the
+ * rate falls short every tick and adds up. Measured over 100ms windows on an M3
+ * Max at rates 2x to 8x, a pipeline with headroom stayed inside 1.5 frames of
+ * its demand either way, so a bill of PRESENT_CADENCE_EVIDENCE_FRAMES frames is
+ * one it cannot run up.
+ *
+ * What puts the share back is the walk holding a frame the clock has not run
+ * past, unbroken for the wall time the source takes to produce that many frames.
+ * That is the only evidence a pipeline can offer that it has room to spare: a
+ * machine at equilibrium delivers exactly what the clock asks for however much
+ * headroom it has, so waiting for a surplus in the bill would leave every
+ * machine at whatever its worst stretch measured. It is a live reading and the
+ * bill is a cumulative one, which is why each takes one direction: ground lost
+ * still reads lost once the walk is keeping up again, and catch-up pulls are
+ * what carry the walk back onto the playhead.
+ *
+ * Neither reading is the depth of the decode-ahead queue, which belongs to the
+ * decode path and not to the machine: on the zero-copy path, which pins a
+ * decoder slot per queued frame and so buffers one, a single frame in hand is
+ * full depth and one tick from empty alike.
+ *
+ * How far behind the machine is therefore sets the pace rather than the size of
+ * the step: the bigger the shortfall the sooner the bill reaches that figure and
+ * the sooner the next step lands. Zeroing on each step makes the next one gather
+ * its own evidence, which is what stops a share sitting at the machine's limit
+ * from pulsing.
+ *
+ * Frames the clock passed, frames the walk delivered and wall time on the
+ * playhead: nothing either reading is made of knows what the panel refreshes at,
+ * so one machine lands on one cadence on any panel. A faster panel offers more
+ * slots and a machine with the headroom fills them; what it cannot do is hold
+ * the pump above what the machine pays for, because the share comes down until
+ * the pipeline is back on the playhead.
+ *
+ * PRESENT_CADENCE_SLACK is how far under the interval still counts as a full
+ * one. Presents land on display ticks, so a panel refreshing at the ceiling
+ * measures each gap as one interval give or take rAF jitter, and an exact
+ * comparison would decline every second frame there. A quarter leaves 4.2ms of
+ * jitter room at 60Hz.
+ *
+ * PRESENT_CADENCE_HZ is the demand above which frames the pump culled or
+ * declined dominate the dropped-frame ledger, so the discarded-frames rule in
+ * evaluateWarnings stands down rather than reading a count it cannot attribute.
+ */
+const PLAYBACK = {
+    READ_AHEAD_CANVAS: 3};
+/**
+ * Forward playback-rate range the engine accepts. Reverse playback needs a
+ * backwards decode strategy the runtime does not have, so zero and negative
+ * rates are refused rather than approximated.
+ *
+ * MAX is an API bound, not a promise that every source plays smoothly there.
+ * Sustaining rate r means decoding r x nativeFps frames a second, and the
+ * decode-ahead cushion is fixed at PLAYBACK.READ_AHEAD_CANVAS frames (raising it
+ * would outrun the CanvasSink pool and tear), so how high a given source really
+ * goes is a property of that source's frame size and encode. The engine measures
+ * it instead of guessing: DiagnosticsSnapshot carries the commanded rate beside
+ * the presented one, and PLAYBACK_RATE_NOT_SUSTAINED fires when they diverge.
+ * SUSTAINED_SHORTFALL is the share of the commanded rate the presented one has
+ * to hold to count as sustained.
+ */
+const PLAYBACK_RATE = {
+    MIN: 0.25,
+    MAX: 8,
+    SUSTAINED_SHORTFALL: 0.8,
+};
+/**
+ * CanvasSink frame-pool size: how many decoded canvases the sink recycles
+ * round-robin. The pool has no backpressure (a new decode overwrites the oldest
+ * slot rather than blocking), and the playback queue hands the raw pool canvas
+ * straight to the painter, so the pool must outnumber every canvas outstanding at
+ * once: the full play read-ahead, the one in flight, and the one being painted.
+ * Sized below that, a fresh decode stomps the pixels of a still-queued frame
+ * before it paints (silent tearing). The cache is unaffected; it copies into its
+ * own OffscreenCanvas. Derived from the read-ahead so the two cannot drift.
+ */
+const SCRUB = {
+    DEFAULT_POOL_SIZE: PLAYBACK.READ_AHEAD_CANVAS + 2,
+};
+/**
+ * Bounds on building a track's frame timeline, the presentation-order table of
+ * every frame's timestamp in the container's own integer grain.
+ *
+ * MAX_FRAMES caps the metadata walk that builds it. A 70-second 30fps source
+ * walks 2113 packets in a measured 5.7ms; the cap is four hundred times that,
+ * which no ordinary file reaches and a fragmented or endless source does. Past
+ * it the load fails, so nothing silently runs without frame identity.
+ *
+ * FALLBACK_TICK_RATE is for a track backing that cannot state its grain. A
+ * microsecond is the finest timestamp WebCodecs carries, so no real timestamp is
+ * lost at that rate; what is lost is the guarantee that every timestamp is a
+ * whole tick.
+ */
+const FRAME_TIMELINE = {
+    MAX_FRAMES: 1_000_000,
+    FALLBACK_TICK_RATE: 1e6,
+};
+/**
+ * Diagnostics instrument tunables. Inert unless a consumer opts in: the worker
+ * broadcasts a snapshot at BROADCAST_HZ only while subscribed, the trace rings
+ * allocate only while armed, and SCRUB_LATENCY_RING bounds the percentile sample.
+ */
+const DIAGNOSTICS = {
+    BROADCAST_HZ: 10,
+    TRACE_EVENT_CAP: 2000,
+    TRACE_SNAPSHOT_CAP: 600,
+    SCRUB_LATENCY_RING: 64,
+};
+/**
+ * What an armed capture actually keeps. The snapshot ring is fed at the fixed
+ * broadcast rate, so its capacity converts to a wall-clock window; the event
+ * ring is fed by paints and gestures at no fixed rate, so its bound is a count
+ * and nothing more. A readout that states one number for "the capture" is
+ * describing neither ring.
+ */
+const TRACE_RING_BOUNDS = {
+    snapshotWindowMs: (DIAGNOSTICS.TRACE_SNAPSHOT_CAP / DIAGNOSTICS.BROADCAST_HZ) * 1000,
+    snapshotCap: DIAGNOSTICS.TRACE_SNAPSHOT_CAP,
+    eventCap: DIAGNOSTICS.TRACE_EVENT_CAP,
+};
+/**
+ * Hang-recovery bounds for the worker video runtime. mediabunny's getCanvas/
+ * getSample take no AbortSignal, so a decode that never settles cannot be
+ * cancelled. These two timeouts bound the damage: a decode that outruns its
+ * ceiling is abandoned and its provider rebuilt, and a main-thread caller
+ * blocked on a wedged worker surfaces an error.
+ *
+ * DECODE_HANG_TIMEOUT_MS bounds a random-access decode operation, not a single
+ * frame. A seek or a play-start lands mid-GOP and decodes the whole
+ * keyframe-to-target prefix, so an 8-second GOP of 8MP frames legitimately runs
+ * tens of seconds. A ceiling sized for one frame fires on healthy progress and
+ * kills the decode it exists to protect.
+ *
+ * SEED_HANG_TIMEOUT_MS bounds the first-frame seed alone, which is why it is a
+ * fraction of the figure above: the seed anchors on the track's own first
+ * sample, so it walks no GOP prefix, and the one cost it carries that a later
+ * decode does not is the decoder's cold hardware configuration. A re-anchored
+ * decode of a 2840x2840 source measured 49ms mean / 80ms worst, so this leaves
+ * two orders of magnitude of headroom over the decode plus its cold start, and
+ * SEED_DECODE_ATTEMPTS of it still finish inside WORKER_COMMAND_TIMEOUT_MS with
+ * the rebuilds between them. That is what lets a decoder which never starts
+ * reach the caller as an error rather than as the facade giving up.
+ *
+ * That budget is the mediabunny sink paths', which carry no ceiling of their
+ * own. The long-lived decode session bounds its own wait for output more
+ * tightly and can tell a decoder that never started from one that went quiet
+ * after working, so on that path the seed ends on the session's word and these
+ * attempts go unspent.
+ *
+ * WORKER_COMMAND_TIMEOUT_MS is the main-thread backstop for an awaitable command
+ * (load, commit, step). It derives from the decode ceiling so the two cannot
+ * drift: the worker has to be able to reach its own hang path, recover, and
+ * reply before the facade gives up on it.
+ */
+const DECODE_HANG_TIMEOUT_MS = 30_000;
+const HANG_RECOVERY = {
+    WORKER_COMMAND_TIMEOUT_MS: DECODE_HANG_TIMEOUT_MS + 15_000,
+};
+
+const asSec = (n) => n;
+const asFps = (n) => n;
+const asPaintSeq = (n) => n;
+var SourceKind;
+(function (SourceKind) {
+    SourceKind["Url"] = "url";
+    SourceKind["Blob"] = "blob";
+    SourceKind["Stream"] = "stream";
+})(SourceKind || (SourceKind = {}));
+/**
+ * Coarse-grained engine status. Updates rarely (load, play, pause, end,
+ * error). Sits on its own emit channel so subscribers do not wake up on
+ * 60Hz time ticks.
+ */
+var PlaybackStatus;
+(function (PlaybackStatus) {
+    PlaybackStatus["Idle"] = "IDLE";
+    PlaybackStatus["Loading"] = "LOADING";
+    PlaybackStatus["Ready"] = "READY";
+    PlaybackStatus["Playing"] = "PLAYING";
+    PlaybackStatus["Paused"] = "PAUSED";
+    PlaybackStatus["Seeking"] = "SEEKING";
+    PlaybackStatus["Ended"] = "ENDED";
+    PlaybackStatus["Errored"] = "ERRORED";
+})(PlaybackStatus || (PlaybackStatus = {}));
+var VideoEngineErrorCode;
+(function (VideoEngineErrorCode) {
+    VideoEngineErrorCode["DecodeUnsupported"] = "DECODE_UNSUPPORTED";
+    VideoEngineErrorCode["SourceUnreadable"] = "SOURCE_UNREADABLE";
+    /**
+     * The demuxer refused the file outright: its container is not one this build
+     * reads, so no track was ever listed and no decoder was ever asked.
+     */
+    VideoEngineErrorCode["ContainerUnreadable"] = "CONTAINER_UNREADABLE";
+    /**
+     * The container opened and the demuxer parsed no track at all out of it. The
+     * file's streams are in formats it does not carry, so their video cannot be
+     * reached even though it is there.
+     */
+    VideoEngineErrorCode["VideoTrackUnreadable"] = "VIDEO_TRACK_UNREADABLE";
+    /**
+     * The container opened, its tracks listed, and none of them is video. This
+     * is the only case where the file itself is what lacks video.
+     */
+    VideoEngineErrorCode["NoVideoTrack"] = "NO_VIDEO_TRACK";
+    VideoEngineErrorCode["BackendCrashed"] = "BACKEND_CRASHED";
+    VideoEngineErrorCode["Aborted"] = "ABORTED";
+    /** A canvas was offered to an engine loaded in "frames" presentation mode,
+     *  where the host owns the only canvas. */
+    VideoEngineErrorCode["PresentationMismatch"] = "PRESENTATION_MISMATCH";
+    /**
+     * The decoder cannot decode this source at all: it refused to configure, it
+     * errored, or it acknowledged decode requests and never produced a frame.
+     * Distinct from BackendCrashed, which a rebuild can recover; this one
+     * survives every rebuild, so the runtime stops rebuilding and says so. The
+     * usual cause is outside the page: another tab holding every hardware
+     * decoder session the machine has.
+     */
+    VideoEngineErrorCode["DecoderStalled"] = "DECODER_STALLED";
+    /** A playback rate outside the forward range the engine supports. */
+    VideoEngineErrorCode["RateUnsupported"] = "RATE_UNSUPPORTED";
+})(VideoEngineErrorCode || (VideoEngineErrorCode = {}));
+/**
+ * Thrown by createScrubCursor / VideoEngine.load when decode is unsupported
+ * or the source is unreadable. Branch on `error.code` (VideoEngineErrorCode)
+ * to differentiate decode failures from network failures.
+ */
+class VideoEngineError extends Error {
+    code;
+    cause;
+    constructor(code, message, cause) {
+        super(message);
+        this.code = code;
+        this.cause = cause;
+    }
+}
+/** Shared by the facade and the core so a host gets the same refusal wherever
+ *  its canvas is caught. */
+function canvasBindingRefused() {
+    return new VideoEngineError(VideoEngineErrorCode.PresentationMismatch, 'presentation "frames" leaves the canvas to the host: this engine paints nothing and hands out VideoFrames instead');
+}
+/**
+ * Validates a requested playback rate and returns it. The facade and the core
+ * both call it, so a rate is refused at whichever boundary it arrives at and
+ * with the same message: the facade posts fire-and-forget, so a refusal raised
+ * only in the worker would reach nobody.
+ *
+ * Reverse is rejected, not clamped: backwards playback is a different decode
+ * problem, and a -1 quietly serviced as +0.25 plays the wrong direction while
+ * reporting success.
+ */
+function resolvePlaybackRate(rate) {
+    if (!Number.isFinite(rate) ||
+        rate < PLAYBACK_RATE.MIN ||
+        rate > PLAYBACK_RATE.MAX) {
+        throw new VideoEngineError(VideoEngineErrorCode.RateUnsupported, `playback rate ${rate} is outside the supported forward range ${PLAYBACK_RATE.MIN}-${PLAYBACK_RATE.MAX}; reverse playback is not supported`);
+    }
+    return rate;
+}
+
+/**
+ * Decode-resolution strategies. A strategy decides the pixel width each video
+ * frame is decoded to, independent of the source's native resolution. Height
+ * follows from native aspect, so a strategy only ever returns a width.
+ *
+ * Decoding below native trades preview sharpness for paint cost and frame-cache
+ * memory. It does NOT cut decode cost: the codec decodes the full coded frame
+ * regardless of target width, and CanvasSink resizes the result afterward. The
+ * win scales with the gap between source resolution and the on-screen box: a 4K
+ * source shown in a 640px surface still pays full 4K decode, but the smaller
+ * surface cuts the per-frame paint work and the cached blit size.
+ *
+ * A strategy applies wherever frames decode through this seam: the live scrub
+ * surface and the analysis / extraction path alike. AnalysisSession decodes at
+ * whatever strategy it is given (native when omitted), so a thumbnail pass can
+ * cache a small blit instead of a native-size one.
+ */
+/** Decode at native resolution. The conservative default. */
+function nativeResolution() {
+    return { kind: "native" };
+}
+/**
+ * Decode at the on-screen size: canvas CSS width times devicePixelRatio. Best
+ * for fixed-size surfaces fed by a much larger source (frame sampler, inline
+ * players). Falls back to native while the box is unmeasured.
+ *
+ * The box it reads is the one bindCanvas measures, so this strategy resolves to
+ * native under presentation "frames", where the engine holds no canvas and
+ * nothing ever measures one. A frames-mode consumer passes displayBoxResolution
+ * instead.
+ */
+function viewportResolution(options = {}) {
+    return {
+        kind: "viewport",
+        maxDevicePixelRatio: options.maxDevicePixelRatio ?? 2,
+    };
+}
+/**
+ * Decode at no more than maxWidth regardless of display size. For consumers
+ * with a hard throughput or memory ceiling (batch surfaces, thumbnail farms).
+ */
+function cappedResolution(maxWidth) {
+    return { kind: "capped", maxWidth };
+}
+/**
+ * Decode at the size the frame will actually occupy inside a box the consumer
+ * describes: native aspect fitted into boxWidth x boxHeight, times the clamped
+ * device pixel ratio. Letterboxing is why the box is two numbers and not one,
+ * since a portrait source in a landscape box paints far narrower than the box.
+ *
+ * This is the strategy for presentation "frames". There the consumer owns the
+ * compositor, so it is the only side that knows the box, and viewportResolution
+ * has nothing to read.
+ */
+function displayBoxResolution(options) {
+    return {
+        kind: "displayBox",
+        boxWidth: options.boxWidth,
+        boxHeight: options.boxHeight,
+        devicePixelRatio: options.devicePixelRatio,
+        maxDevicePixelRatio: options.maxDevicePixelRatio ?? 2,
+    };
+}
+/** Runs the descriptor against a context to produce a target decode width. */
+function strategyWidth(strategy, ctx) {
+    switch (strategy.kind) {
+        case "native":
+            return ctx.nativeWidth;
+        case "viewport": {
+            if (ctx.displayWidth === null || ctx.displayWidth <= 0)
+                return ctx.nativeWidth;
+            const dpr = clampDpr(ctx.devicePixelRatio, strategy.maxDevicePixelRatio);
+            return Math.ceil(ctx.displayWidth * dpr);
+        }
+        case "capped":
+            return Math.min(strategy.maxWidth, ctx.nativeWidth);
+        case "displayBox": {
+            const { boxWidth, boxHeight } = strategy;
+            if (!(boxWidth > 0) || !(boxHeight > 0))
+                return ctx.nativeWidth;
+            const fit = Math.min(boxWidth / ctx.nativeWidth, boxHeight / ctx.nativeHeight);
+            const dpr = clampDpr(strategy.devicePixelRatio, strategy.maxDevicePixelRatio);
+            return Math.ceil(ctx.nativeWidth * fit * dpr);
+        }
+    }
+}
+/**
+ * Runs a strategy and returns native-bounded, aspect-preserving integer
+ * dimensions safe to hand to CanvasSink and to size a canvas backing store.
+ * A strategy that returns garbage (non-finite, non-positive) falls back to
+ * native rather than producing a broken surface.
+ */
+function resolveDecodeDimensions(strategy, ctx) {
+    const nativeWidth = Math.max(1, Math.round(ctx.nativeWidth));
+    const nativeHeight = Math.max(1, Math.round(ctx.nativeHeight));
+    const raw = strategyWidth(strategy, ctx);
+    const width = Number.isFinite(raw) && raw > 0
+        ? Math.min(Math.round(raw), nativeWidth)
+        : nativeWidth;
+    const height = Math.max(1, Math.round((width * nativeHeight) / nativeWidth));
+    return { width, height };
+}
+function clampDpr(dpr, maxDpr) {
+    if (!Number.isFinite(dpr) || dpr <= 0)
+        return 1;
+    return Math.min(dpr, maxDpr);
+}
+
+/**
+ * One entry per presentation instant.
+ *
+ * A container may carry several coded pictures on one timestamp, and they
+ * occupy no time between them: a decode for that instant answers with a single
+ * picture, so the rest are frames no reader can reach or name. Counting them
+ * would leave a step across the group moving the picture nowhere, and a search
+ * for a time inside it answering with the group's last entry whatever it was
+ * asked.
+ */
+function oneEntryPerInstant(data) {
+    const { ticks } = data;
+    let at = 1;
+    while (at < ticks.length && ticks[at] !== ticks[at - 1])
+        at += 1;
+    if (at === ticks.length)
+        return data;
+    const distinct = new Float64Array(ticks.length);
+    distinct.set(ticks.subarray(0, at));
+    let size = at;
+    for (let i = at + 1; i < ticks.length; i += 1) {
+        if (ticks[i] === distinct[size - 1])
+            continue;
+        distinct[size] = ticks[i];
+        size += 1;
+    }
+    return { ...data, ticks: distinct.slice(0, size) };
+}
+/**
+ * Every real frame of one track, in presentation order, by its container tick
+ * timestamp.
+ *
+ * A container states its timestamps as integer multiples of 1/tickRate, so a
+ * frame's tick count is exact and comparisons between two readers of the same
+ * container are integer comparisons. `timeAt` is the same division of the same
+ * two integers the demuxer itself performs, which is what lets a consumer
+ * holding only seconds match a producer's frame with `===`.
+ */
+class FrameTimeline {
+    data;
+    ticksArray;
+    constructor(data) {
+        this.data = data;
+        this.ticksArray = data.ticks;
+    }
+    static from(data) {
+        if (data.ticks.length === 0) {
+            throw new RangeError("FrameTimeline: a track with no frames has no timeline");
+        }
+        if (!(data.tickRate > 0)) {
+            throw new RangeError(`FrameTimeline: tick rate ${data.tickRate} is not positive`);
+        }
+        return new FrameTimeline(oneEntryPerInstant(data));
+    }
+    /** A synthetic constant-rate table. Tests and fakes only. The default tick
+     *  rate is a whole multiple of `fps`, so no test table needs rounding. */
+    static uniform(fps, frameCount, tickRate = fps * 1000) {
+        const step = tickRate / fps;
+        const ticks = Float64Array.from({ length: frameCount }, (_, index) => index * step);
+        return FrameTimeline.from({ lastDurationTicks: step, tickRate, ticks });
+    }
+    get tickRate() {
+        return this.data.tickRate;
+    }
+    get frameCount() {
+        return this.ticksArray.length;
+    }
+    toData() {
+        return this.data;
+    }
+    ticksAt(index) {
+        return this.ticksArray[this.clampIndex(index)];
+    }
+    timeAt(index) {
+        return asSec(this.ticksAt(index) / this.data.tickRate);
+    }
+    idAt(index) {
+        const at = this.clampIndex(index);
+        return { index: at, ticks: this.ticksArray[at] };
+    }
+    landingAt(index) {
+        const at = this.clampIndex(index);
+        return { frame: this.idAt(at), mediaTimeS: this.timeAt(at) };
+    }
+    /** Ticks the frame at `index` ends at, which is where the next one starts. */
+    endTicksAt(index) {
+        const at = this.clampIndex(index);
+        return at + 1 < this.ticksArray.length
+            ? this.ticksArray[at + 1]
+            : this.ticksArray[at] + this.data.lastDurationTicks;
+    }
+    /**
+     * The frame covering `timeS`, which is what a decode for it returns.
+     *
+     * The comparison divides, as `timeAt` does, so a frame's own published
+     * second answers with that frame.
+     */
+    indexAtOrBefore(timeS) {
+        let low = 0;
+        let high = this.ticksArray.length - 1;
+        let found = 0;
+        while (low <= high) {
+            const mid = (low + high) >> 1;
+            if (this.ticksArray[mid] / this.data.tickRate <= timeS) {
+                found = mid;
+                low = mid + 1;
+            }
+            else {
+                high = mid - 1;
+            }
+        }
+        return found;
+    }
+    /**
+     * The frame a decoded sample is.
+     *
+     * A decoded timestamp has been through the WebCodecs microsecond plane, so
+     * it can miss its own tick by up to half a microsecond. Snapping to the
+     * nearer neighbour absorbs that by four orders of magnitude, since the
+     * narrowest real frame gap measured across the fixtures is 31667 us.
+     */
+    indexOfDecoded(timeS) {
+        const wanted = Math.round(timeS * this.data.tickRate);
+        const at = this.indexAtOrBefore(wanted / this.data.tickRate);
+        const next = at + 1;
+        if (next >= this.ticksArray.length)
+            return at;
+        return wanted - this.ticksArray[at] <= this.ticksArray[next] - wanted
+            ? at
+            : next;
+    }
+    clampIndex(index) {
+        if (index < 0)
+            return 0;
+        const last = this.ticksArray.length - 1;
+        return index > last ? last : index;
+    }
+}
+
+export { DIAGNOSTICS as D, FRAME_TIMELINE as F, HANG_RECOVERY as H, PlaybackStatus as P, SCRUB as S, TRACE_RING_BOUNDS as T, VideoEngineError as V, VideoEngineErrorCode as a, asSec as b, SourceKind as c, FrameTimeline as d, asPaintSeq as e, canvasBindingRefused as f, resolvePlaybackRate as g, PLAYBACK_RATE as h, asFps as i, cappedResolution as j, displayBoxResolution as k, nativeResolution as n, resolveDecodeDimensions as r, viewportResolution as v };
+//# sourceMappingURL=frame-timeline-GINI8Gum.js.map

package/dist/web-video-engine/frame-timeline-GINI8Gum.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame-timeline-GINI8Gum.js","sources":["../src/constants.ts","../src/types.ts","../src/decode-resolution.ts","../src/frame-timeline.ts"],"sourcesContent":[null,null,null,null],"names":[],"mappings":"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"}

package/dist/web-video-engine/frame-timeline.d.ts

@@ -0,0 +1,71 @@
+import { type Sec } from "./types";
+/** Ticks per second, from the container's own timing grain. */
+export type TickRate = number;
+/**
+ * A frame of the source, named twice: by its position in presentation order and
+ * by its presentation timestamp in the track's own integer grain.
+ */
+export interface FrameId {
+    readonly index: number;
+    readonly ticks: number;
+}
+/**
+ * Where the transport has settled: the frame, and the one seconds value anyone
+ * publishes for it. Nothing else on the wire carries a media position.
+ */
+export interface FrameLanding {
+    readonly frame: FrameId;
+    readonly mediaTimeS: number;
+}
+/** The clone-safe shape the timeline crosses a worker boundary as. */
+export interface FrameTimelineData {
+    readonly tickRate: TickRate;
+    readonly ticks: Float64Array;
+    readonly lastDurationTicks: number;
+}
+/**
+ * Every real frame of one track, in presentation order, by its container tick
+ * timestamp.
+ *
+ * A container states its timestamps as integer multiples of 1/tickRate, so a
+ * frame's tick count is exact and comparisons between two readers of the same
+ * container are integer comparisons. `timeAt` is the same division of the same
+ * two integers the demuxer itself performs, which is what lets a consumer
+ * holding only seconds match a producer's frame with `===`.
+ */
+export declare class FrameTimeline {
+    private readonly data;
+    private readonly ticksArray;
+    private constructor();
+    static from(data: FrameTimelineData): FrameTimeline;
+    /** A synthetic constant-rate table. Tests and fakes only. The default tick
+     *  rate is a whole multiple of `fps`, so no test table needs rounding. */
+    static uniform(fps: number, frameCount: number, tickRate?: TickRate): FrameTimeline;
+    get tickRate(): TickRate;
+    get frameCount(): number;
+    toData(): FrameTimelineData;
+    ticksAt(index: number): number;
+    timeAt(index: number): Sec;
+    idAt(index: number): FrameId;
+    landingAt(index: number): FrameLanding;
+    /** Ticks the frame at `index` ends at, which is where the next one starts. */
+    endTicksAt(index: number): number;
+    /**
+     * The frame covering `timeS`, which is what a decode for it returns.
+     *
+     * The comparison divides, as `timeAt` does, so a frame's own published
+     * second answers with that frame.
+     */
+    indexAtOrBefore(timeS: number): number;
+    /**
+     * The frame a decoded sample is.
+     *
+     * A decoded timestamp has been through the WebCodecs microsecond plane, so
+     * it can miss its own tick by up to half a microsecond. Snapping to the
+     * nearer neighbour absorbs that by four orders of magnitude, since the
+     * narrowest real frame gap measured across the fixtures is 31667 us.
+     */
+    indexOfDecoded(timeS: number): number;
+    private clampIndex;
+}
+//# sourceMappingURL=frame-timeline.d.ts.map

package/dist/web-video-engine/frame-timeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame-timeline.d.ts","sourceRoot":"","sources":["../src/frame-timeline.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,KAAK,GAAG,EAAE,MAAM,SAAS,CAAC;AAE1C,+DAA+D;AAC/D,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC;AAE9B;;;GAGG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,sEAAsE;AACtE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;CACpC;AA4BD;;;;;;;;;GASG;AACH,qBAAa,aAAa;IAGJ,OAAO,CAAC,QAAQ,CAAC,IAAI;IAFzC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAe;IAE1C,OAAO;IAIP,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,iBAAiB,GAAG,aAAa;IAcnD;8EAC0E;IAC1E,MAAM,CAAC,OAAO,CACZ,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,MAAM,EAClB,QAAQ,GAAE,QAAqB,GAC9B,aAAa;IAShB,IAAI,QAAQ,IAAI,QAAQ,CAEvB;IAED,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,MAAM,IAAI,iBAAiB;IAI3B,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAI9B,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG;IAI1B,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAK5B,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY;IAKtC,8EAA8E;IAC9E,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAOjC;;;;;OAKG;IACH,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAgBtC;;;;;;;OAOG;IACH,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAUrC,OAAO,CAAC,UAAU;CAKnB"}