supervision 0.1.7 → 0.2.0-next.1

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

@@ -0,0 +1,616 @@
+/**
+ * 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,
+    KEYFRAME_TIMESTAMPS_CAP: 512,
+};
+/**
+ * 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 WORKER_COMMAND_TIMEOUT_MS = DECODE_HANG_TIMEOUT_MS + 15_000;
+const HANG_RECOVERY = {
+    WORKER_COMMAND_TIMEOUT_MS,
+};
+
+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 WebVideoEngineErrorCode;
+(function (WebVideoEngineErrorCode) {
+    WebVideoEngineErrorCode["DecodeUnsupported"] = "DECODE_UNSUPPORTED";
+    WebVideoEngineErrorCode["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.
+     */
+    WebVideoEngineErrorCode["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.
+     */
+    WebVideoEngineErrorCode["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.
+     */
+    WebVideoEngineErrorCode["NoVideoTrack"] = "NO_VIDEO_TRACK";
+    WebVideoEngineErrorCode["BackendCrashed"] = "BACKEND_CRASHED";
+    WebVideoEngineErrorCode["Aborted"] = "ABORTED";
+    /** A canvas was offered to an engine loaded in "frames" presentation mode,
+     *  where the host owns the only canvas. */
+    WebVideoEngineErrorCode["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; 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.
+     */
+    WebVideoEngineErrorCode["DecoderStalled"] = "DECODER_STALLED";
+    /** A playback rate outside the forward range the engine supports. */
+    WebVideoEngineErrorCode["RateUnsupported"] = "RATE_UNSUPPORTED";
+})(WebVideoEngineErrorCode || (WebVideoEngineErrorCode = {}));
+/**
+ * Thrown by createScrubCursor / WebVideoEngine.load when decode is unsupported
+ * or the source is unreadable. Branch on `error.code` (WebVideoEngineErrorCode)
+ * to differentiate decode failures from network failures.
+ */
+class WebVideoEngineError 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 WebVideoEngineError(WebVideoEngineErrorCode.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 WebVideoEngineError(WebVideoEngineErrorCode.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);
+    const distinctSource = data.sourceTicks
+        ? new Float64Array(ticks.length)
+        : undefined;
+    distinct.set(ticks.subarray(0, at));
+    if (distinctSource)
+        distinctSource.set(data.sourceTicks.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];
+        if (distinctSource)
+            distinctSource[size] = data.sourceTicks[i];
+        size += 1;
+    }
+    return {
+        ...data,
+        ticks: distinct.slice(0, size),
+        ...(distinctSource ? { sourceTicks: distinctSource.slice(0, size) } : {}),
+    };
+}
+function normalizePresentationOrigin(data) {
+    if (data.sourceTicks !== undefined || !(data.ticks[0] < 0))
+        return data;
+    let firstVisible = 0;
+    while (firstVisible < data.ticks.length) {
+        const end = firstVisible + 1 < data.ticks.length
+            ? data.ticks[firstVisible + 1]
+            : data.ticks[firstVisible] + data.lastDurationTicks;
+        if (end > 0)
+            break;
+        firstVisible += 1;
+    }
+    if (firstVisible === data.ticks.length) {
+        throw new RangeError("FrameTimeline: a track containing only pre-roll has no presentation timeline");
+    }
+    const sourceTicks = data.ticks.slice(firstVisible);
+    const ticks = sourceTicks.slice();
+    if (ticks[0] < 0)
+        ticks[0] = 0;
+    const lastDurationTicks = ticks.length === 1 && sourceTicks[0] < 0
+        ? data.lastDurationTicks + sourceTicks[0]
+        : data.lastDurationTicks;
+    return {
+        ...data,
+        lastDurationTicks,
+        sourceTicks,
+        ticks,
+    };
+}
+/**
+ * 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(normalizePresentationOrigin(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);
+    }
+    /** Timestamp passed to the decoder for the named presentation frame. */
+    sourceTimeAt(index) {
+        const at = this.clampIndex(index);
+        return asSec((this.data.sourceTicks?.[at] ?? this.ticksArray[at]) / this.data.tickRate);
+    }
+    /** Maps a public presentation time onto the container's source clock. */
+    toSourceTime(timeS) {
+        if (this.data.sourceTicks && timeS <= this.timeAt(0)) {
+            return this.sourceTimeAt(0);
+        }
+        return asSec(timeS);
+    }
+    /** Maps a decoded/container timestamp onto the public presentation clock. */
+    fromSourceTime(timeS) {
+        return asSec(this.data.sourceTicks ? Math.max(0, timeS) : timeS);
+    }
+    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, WebVideoEngineError as W, WebVideoEngineErrorCode 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 };