supervision 0.1.7 → 0.2.0-next.1

package/dist/video-engine-media-source-CUXnOJOV.js

@@ -0,0 +1,450 @@
+import { MediaErrorKind } from 'supervision-js-core';
+
+/**
+ * The kind each coded refusal already stands for. Reading the code beats
+ * re-deriving the kind from the message: the text of a container refusal says
+ * "demuxer", the text of a wedged worker says "timed out", and the patterns
+ * below would file both under the wrong kind. Written as a total record, so a
+ * code added to the vocabulary above fails the build until it has a kind.
+ */
+const PRODUCER_CODE_KINDS = {
+    ABORTED: MediaErrorKind.Unknown,
+    BACKEND_CRASHED: MediaErrorKind.Decode,
+    CONTAINER_UNREADABLE: MediaErrorKind.Unreadable,
+    DECODER_STALLED: MediaErrorKind.Decode,
+    DECODE_UNSUPPORTED: MediaErrorKind.UnsupportedFormat,
+    NO_VIDEO_TRACK: MediaErrorKind.NoVideoTrack,
+    PRESENTATION_MISMATCH: MediaErrorKind.Unknown,
+    RATE_UNSUPPORTED: MediaErrorKind.Unknown,
+    SOURCE_UNREADABLE: MediaErrorKind.Unreadable,
+    VIDEO_TRACK_UNREADABLE: MediaErrorKind.UnsupportedFormat,
+};
+const UNSUPPORTED_FORMAT_PATTERN = /unsupported|not supported|no (?:matching )?(?:decoder|codec)|codec/i;
+const DECODE_PATTERN = /decod|demux|corrupt|malformed|bitstream/i;
+const NETWORK_PATTERN = /network|fetch|http|failed to load|load failed|timed? ?out|abort/i;
+/**
+ * A media failure with a stable, documented kind.
+ *
+ * Branch on `kind` instead of matching decoder, demuxer, or container message
+ * text. `message` stays diagnostic and may name vendor internals; applications
+ * own their user-facing copy. The originating failure is preserved on `cause`.
+ */
+class MediaSourceError extends Error {
+    kind;
+    constructor(kind, message, options) {
+        super(message, options);
+        this.name = "MediaSourceError";
+        this.kind = kind;
+    }
+}
+function isMediaSourceError(value) {
+    return value instanceof MediaSourceError;
+}
+/**
+ * Classifies an arbitrary media failure into a `MediaSourceError`.
+ *
+ * Already-classified errors pass through so a kind chosen at the point of
+ * failure is never downgraded by a broader message match. Anything the
+ * heuristics cannot place stays representable as `Unknown` rather than being
+ * forced into a wrong kind.
+ */
+function toMediaSourceError(error, fallbackMessage = "Media source failed.") {
+    if (isMediaSourceError(error)) {
+        return error;
+    }
+    const message = error instanceof Error ? error.message : fallbackMessage;
+    const kind = producerCodeKind(error) ?? classifyMediaErrorMessage(message);
+    return new MediaSourceError(kind, message, { cause: error });
+}
+/**
+ * Failure kind of any caught media failure.
+ *
+ * A `MediaSourceError` reports the kind chosen where it failed. Anything else
+ * is classified from its message, and stays `Unknown` when no kind fits.
+ */
+function getMediaErrorKind(error) {
+    return toMediaSourceError(error).kind;
+}
+function producerCodeKind(error) {
+    const code = error?.code;
+    return typeof code === "string" && code in PRODUCER_CODE_KINDS
+        ? PRODUCER_CODE_KINDS[code]
+        : null;
+}
+function classifyMediaErrorMessage(message) {
+    if (NETWORK_PATTERN.test(message)) {
+        return MediaErrorKind.Network;
+    }
+    if (UNSUPPORTED_FORMAT_PATTERN.test(message)) {
+        return MediaErrorKind.UnsupportedFormat;
+    }
+    if (DECODE_PATTERN.test(message)) {
+        return MediaErrorKind.Decode;
+    }
+    return MediaErrorKind.Unknown;
+}
+
+const DEFAULT_MAX_DEVICE_PIXEL_RATIO = 2;
+/**
+ * The pixel ratio a host's display box rasterizes at, for every grid that lands
+ * in that box: the presentation surface, the mask rasters drawn onto it, and the
+ * decode under both. The ceiling is what keeps a 3x display from costing nine
+ * times the texels of a 1x one for sharpness nobody resolves on a moving
+ * picture. An id raster carries a detection per pixel and can only be sampled
+ * nearest, so a grid it does not share ragged its edges.
+ *
+ * A ceiling that is not a usable number states nothing, and takes the default.
+ */
+function resolveDisplayPixelRatio(display) {
+    const { devicePixelRatio, maxDevicePixelRatio } = display;
+    if (!Number.isFinite(devicePixelRatio) || devicePixelRatio <= 0) {
+        return 1;
+    }
+    const ceiling = maxDevicePixelRatio !== undefined &&
+        Number.isFinite(maxDevicePixelRatio) &&
+        maxDevicePixelRatio > 0
+        ? maxDevicePixelRatio
+        : DEFAULT_MAX_DEVICE_PIXEL_RATIO;
+    return Math.min(devicePixelRatio, ceiling);
+}
+
+const VIDEO_ENGINE_ENTRY = "supervision/web-video-engine";
+const VIDEO_ENGINE_ANALYSIS_ENTRY = `${VIDEO_ENGINE_ENTRY}/analysis`;
+/**
+ * A bundler renames the engine chunk after the module it was split from, and a
+ * browser reports the failing chunk's URL rather than the specifier that asked
+ * for it, so the name a failure can be recognised by is the module's, not the
+ * entry's.
+ */
+const VIDEO_ENGINE_MODULE = "web-video-engine";
+const MISSING_MODULE_ERROR_CODES = new Set([
+    "ERR_MODULE_NOT_FOUND",
+    "MODULE_NOT_FOUND",
+]);
+const MISSING_MODULE_MESSAGE = /cannot find (?:module|package)|failed to (?:resolve|fetch dynamically imported) module|could not resolve/i;
+const QUOTED_SPECIFIER = /['"]([^'"]+)['"]/;
+const MAX_WRAPPED_ERROR_DEPTH = 8;
+/**
+ * The engine is a chunk of this package that the browser fetches on demand, so
+ * the raw failure names a URL nobody wrote and reads like a bug in the caller's
+ * own code.
+ */
+function rethrowEngineImportFailure(error, entry) {
+    if (isEngineResolutionFailure(error)) {
+        throw new Error(`openWebVideoEngineMediaSource needs "${entry}", which did not load. ` +
+            "The web video engine is a lazily loaded chunk of supervision, so check " +
+            "that the deployed build still serves every chunk it emitted.", { cause: error });
+    }
+    throw error;
+}
+/**
+ * An engine that never loaded and an engine that loaded and then threw arrive
+ * at the same catch, and only the first is a deployment problem. Loaders that
+ * wrap what they caught put the load failure under the error they raise, so the
+ * whole cause chain is read, bounded because a chain can be cyclic.
+ */
+function isEngineResolutionFailure(error) {
+    let cursor = error;
+    for (let depth = 0; depth <= MAX_WRAPPED_ERROR_DEPTH; depth += 1) {
+        if (!(cursor instanceof Error))
+            return false;
+        if (namesUnloadableEngine(cursor))
+            return true;
+        cursor = cursor.cause;
+    }
+    return false;
+}
+/**
+ * Node and bundlers quote the specifier they failed to resolve, so a dependency
+ * missing from an engine that did load is told apart by whose name is quoted; a
+ * browser reports an unquoted URL, which carries the chunk name too.
+ *
+ * Each bundler words this differently and one of them stubs the import with an
+ * error of its own, so the wording is matched as well as the code. A build that
+ * names the engine first and its importer second is the engine failing to load;
+ * one that names a dependency first is that dependency's problem, and reading
+ * only the first quoted specifier keeps the two apart.
+ */
+function namesUnloadableEngine(error) {
+    const code = "code" in error ? String(error.code) : "";
+    if (!MISSING_MODULE_ERROR_CODES.has(code) &&
+        !MISSING_MODULE_MESSAGE.test(error.message)) {
+        return false;
+    }
+    const quoted = QUOTED_SPECIFIER.exec(error.message)?.[1];
+    return (quoted ?? error.message).includes(VIDEO_ENGINE_MODULE);
+}
+
+const MILLISECONDS_PER_SECOND = 1000;
+const DEFAULT_FRAME_RATE = 30;
+const TIMESTAMP_EPSILON_SECONDS = 1e-6;
+const FRAMES_PRESENTATION_PREVIEW_MAX_WIDTH_PX = 320;
+/**
+ * Adapts the web video engine to the decoded-media source seam.
+ *
+ * The pull path, `sampleSink`, serves one-off reads such as thumbnails and
+ * single frame grabs, decoding each request from scratch through the engine's
+ * batch analysis entry. The push path serves playback and scrub presentation:
+ * the engine holds no canvas, paints nothing, and announces every frame that
+ * earns the screen, so a compositor subscribes to `engine` and never pulls
+ * samples here.
+ */
+async function openWebVideoEngineMediaSource(options) {
+    if ("stream" in options.source) {
+        throw new MediaSourceError(MediaErrorKind.Unreadable, "This media source decodes playback and one-off frame grabs from two readers of the video, so it needs one that opens twice: a URL or a Blob. A ReadableStream yields its bytes once.");
+    }
+    let engine;
+    let retainedFrames;
+    try {
+        const { WebVideoEngine, displayBoxResolution } = await importEngineEntry();
+        const { display, frameDecodeStrategy, ...engineOptions } = options;
+        engine = new WebVideoEngine({
+            decodeStrategy: display ? displayBoxResolution(display) : undefined,
+            previewWidth: framesPreviewWidth(display),
+            ...engineOptions,
+            presentation: "frames",
+        });
+        const openedEngine = engine;
+        // The engine can present its seed before open() returns and before the
+        // renderer can register. Retain only the newest frame across that gap.
+        retainedFrames = retainFramesUntilSubscribed(openedEngine);
+        const snapshot = await openedEngine.load();
+        const frames = createAnalysisFrameReader({
+            decodeStrategy: frameDecodeStrategy,
+            frameDuration: resolveFrameDuration(snapshot.nativeFps),
+            source: options.source,
+        });
+        return {
+            engine: openedEngine,
+            input: {
+                dispose() {
+                    retainedFrames?.dispose();
+                    void frames.close();
+                    void openedEngine.dispose();
+                },
+            },
+            metadata: createMetadata(snapshot),
+            sampleSink: frames.sampleSink,
+        };
+    }
+    catch (error) {
+        retainedFrames?.dispose();
+        await engine?.dispose();
+        throw toWebVideoEngineMediaSourceError(error);
+    }
+}
+function retainFramesUntilSubscribed(engine) {
+    const registerUpstream = engine.onPresentedFrame.bind(engine);
+    let downstream = null;
+    let pending = null;
+    let disposed = false;
+    registerUpstream((presented) => {
+        if (disposed) {
+            presented.frame.close();
+            return;
+        }
+        if (downstream) {
+            downstream(presented);
+            return;
+        }
+        pending?.frame.close();
+        pending = presented;
+    });
+    engine.onPresentedFrame = (handler) => {
+        downstream = handler;
+        const retained = pending;
+        pending = null;
+        if (retained)
+            handler(retained);
+    };
+    return {
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            pending?.frame.close();
+            pending = null;
+            downstream = (presented) => presented.frame.close();
+        },
+    };
+}
+function toWebVideoEngineMediaSourceError(error) {
+    if (error instanceof DOMException &&
+        (error.name === "SecurityError" || error.name === "NotSupportedError")) {
+        return new MediaSourceError(MediaErrorKind.EnvironmentUnsupported, "The browser environment could not start the web video engine worker.", { cause: error });
+    }
+    return toMediaSourceError(error, "Unable to open this video source.");
+}
+function createWebVideoEngineMediaRendererSource(options) {
+    return {
+        open() {
+            return openWebVideoEngineMediaSource(options);
+        },
+    };
+}
+/**
+ * The engine ships inside this package, and arrives through a dynamic import so
+ * that it lands in its own chunk: a consumer who only annotates images never
+ * downloads the engine's embedded decode worker. A static import would fold it
+ * into the main entry.
+ */
+async function importEngineEntry() {
+    try {
+        return await import('./web-video-engine/engine.js');
+    }
+    catch (error) {
+        rethrowEngineImportFailure(error, VIDEO_ENGINE_ENTRY);
+    }
+}
+async function importAnalysisEntry() {
+    try {
+        return await import('./web-video-engine/analysis.js');
+    }
+    catch (error) {
+        rethrowEngineImportFailure(error, VIDEO_ENGINE_ANALYSIS_ENTRY);
+    }
+}
+/**
+ * A wider coarse frame means fewer of them resident, and residency is what a
+ * drag spends: a scrub position holding no coarse frame paints nothing until a
+ * full decode returns. A stated box only ever lowers the width, since a preview
+ * wider than the picture it stands in for buys no sharpness and costs resident
+ * frames.
+ */
+function framesPreviewWidth(display) {
+    if (display === undefined || !(display.boxWidth > 0)) {
+        return FRAMES_PRESENTATION_PREVIEW_MAX_WIDTH_PX;
+    }
+    return Math.min(FRAMES_PRESENTATION_PREVIEW_MAX_WIDTH_PX, Math.ceil(display.boxWidth * resolveDisplayPixelRatio(display)));
+}
+function createAnalysisFrameReader(options) {
+    let sessionPromise;
+    let closed = false;
+    const openSession = () => {
+        sessionPromise ??= (async () => {
+            try {
+                const { AnalysisSession } = await importAnalysisEntry();
+                return await AnalysisSession.open({
+                    decodeStrategy: options.decodeStrategy,
+                    source: options.source,
+                });
+            }
+            catch (error) {
+                throw toMediaSourceError(error, "Unable to open video frame analysis.");
+            }
+        })();
+        return sessionPromise;
+    };
+    const extractAt = async (timestamp) => {
+        if (closed)
+            return null;
+        try {
+            const session = await openSession();
+            const [frame] = await session.extractFrames([timestamp]);
+            return frame ?? null;
+        }
+        catch (error) {
+            throw toMediaSourceError(error, "Unable to decode this video frame.");
+        }
+    };
+    const sampleSink = {
+        async getSample(timestamp) {
+            const frame = await extractAt(timestamp);
+            return frame ? createSample(frame, options.frameDuration) : null;
+        },
+        async *samples(startTimestamp = 0, endTimestamp = Number.POSITIVE_INFINITY) {
+            let cursor = startTimestamp;
+            let lastTimestamp = Number.NEGATIVE_INFINITY;
+            while (cursor <= endTimestamp) {
+                const frame = await extractAt(cursor);
+                if (!frame)
+                    return;
+                // The analysis entry answers with the frame on screen at the requested
+                // timestamp, so a request past the last frame answers with that frame
+                // again. A timestamp that does not advance is the end of the track.
+                if (frame.timestampS <= lastTimestamp + TIMESTAMP_EPSILON_SECONDS) {
+                    return;
+                }
+                lastTimestamp = frame.timestampS;
+                cursor = Math.max(cursor, frame.timestampS) + options.frameDuration;
+                yield createSample(frame, options.frameDuration);
+            }
+        },
+        async *samplesAtTimestamps(timestamps) {
+            if (closed)
+                return;
+            try {
+                const session = await openSession();
+                for await (const frame of session.framesAtTimestamps([...timestamps])) {
+                    yield frame ? createSample(frame, options.frameDuration) : null;
+                }
+            }
+            catch (error) {
+                throw toMediaSourceError(error, "Unable to decode these video frames.");
+            }
+        },
+    };
+    const close = async () => {
+        closed = true;
+        const opening = sessionPromise;
+        sessionPromise = undefined;
+        if (!opening)
+            return;
+        try {
+            const session = await opening;
+            await session.close();
+        }
+        catch {
+            // A session that failed to open already rejected the pull that opened it.
+        }
+    };
+    return { close, sampleSink };
+}
+function createSample(frame, duration) {
+    let closed = false;
+    return {
+        close() {
+            closed = true;
+        },
+        draw(context, dx, dy, dWidth = frame.width, dHeight = frame.height) {
+            if (closed)
+                throw new Error("Cannot draw a closed web video engine frame.");
+            context.drawImage(frame.canvas, dx, dy, dWidth, dHeight);
+        },
+        duration,
+        timestamp: frame.timestampS,
+    };
+}
+function createMetadata(snapshot) {
+    const duration = Number.isFinite(snapshot.durationMs)
+        ? snapshot.durationMs / MILLISECONDS_PER_SECOND
+        : null;
+    const estimatedFrameRate = snapshot.nativeFps !== null && snapshot.nativeFps > 0
+        ? snapshot.nativeFps
+        : null;
+    return {
+        audioTrackCount: 0,
+        canRead: snapshot.canDecode,
+        duration,
+        estimatedFrameCount: duration !== null && estimatedFrameRate !== null
+            ? Math.max(1, Math.round(duration * estimatedFrameRate))
+            : null,
+        estimatedFrameRate,
+        firstTimestamp: snapshot.firstTimestampMs / MILLISECONDS_PER_SECOND,
+        formatMimeType: null,
+        formatName: "video-engine",
+        mimeType: null,
+        primaryVideoHeight: snapshot.naturalHeight,
+        primaryVideoWidth: snapshot.naturalWidth,
+        trackCount: 1,
+        videoTrackCount: 1,
+    };
+}
+function resolveFrameDuration(nativeFps) {
+    return nativeFps !== null && nativeFps > 0
+        ? 1 / nativeFps
+        : 1 / DEFAULT_FRAME_RATE;
+}
+
+export { MediaSourceError as M, createWebVideoEngineMediaRendererSource as c, getMediaErrorKind as g, isMediaSourceError as i, openWebVideoEngineMediaSource as o, resolveDisplayPixelRatio as r, toMediaSourceError as t };
+//# sourceMappingURL=video-engine-media-source-CUXnOJOV.js.map

package/dist/video-engine-media-source-CUXnOJOV.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"video-engine-media-source-CUXnOJOV.js","sources":["../src/media/media-errors.ts","../src/media/display-pixel-ratio.ts","../src/media/engine-import-failure.ts","../src/media/video-engine-media-source.ts"],"sourcesContent":[null,null,null,null],"names":[],"mappings":"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"}

package/dist/web-video-engine/analysis-session.d.ts

@@ -0,0 +1,75 @@
+import { type DecodeSourceHandle } from "./decode-source";
+import type { DecodeResolutionStrategy } from "./decode-resolution";
+import type { VideoSource } from "./types";
+/**
+ * Playback-independent analysis over a video source: metadata, keyframe
+ * discovery, and frame extraction at arbitrary timestamps. It rides the same
+ * opened decode source as the playback cursor but spins no worker, binds no
+ * canvas, and runs no clock, so a consumer can pull thumbnails or build a
+ * contact sheet without standing up a player.
+ *
+ * Extracted frames are copied into their own canvases before the next decode,
+ * because the underlying sink recycles a small pool round-robin; the copy is
+ * what makes a returned frame safe to hold.
+ */
+export interface AnalysisOptions {
+    source: VideoSource;
+    /**
+     * Output frame resolution: it sizes the decode sink, so frames decode (and
+     * paint, and copy) at this width with height following native aspect. Native
+     * when omitted; a capped strategy makes a thumbnail pass cheaper end to end
+     * rather than decoding native and scaling down afterward.
+     */
+    decodeStrategy?: DecodeResolutionStrategy;
+    poolSize?: number;
+}
+export interface AnalysisMetadata {
+    readonly durationS: number;
+    readonly width: number;
+    readonly height: number;
+    /** Resolution extracted frames are sized to, after the decode strategy. */
+    readonly frameWidth: number;
+    readonly frameHeight: number;
+    readonly nativeFps: number | null;
+}
+export interface ExtractedFrame {
+    readonly timestampS: number;
+    readonly canvas: OffscreenCanvas;
+    readonly width: number;
+    readonly height: number;
+}
+export declare class AnalysisSession {
+    private readonly sink;
+    private readonly keyframeIndex;
+    private readonly track;
+    private readonly disposeSource;
+    private closed;
+    constructor(source: DecodeSourceHandle);
+    /** Opens a source for analysis. The returned session owns the source. */
+    static open(options: AnalysisOptions): Promise<AnalysisSession>;
+    get metadata(): AnalysisMetadata;
+    /**
+     * Keyframe timestamps (seconds) whose GOP overlaps the range, resolved
+     * lazily through the container. Useful for a contact sheet that lands on
+     * real I-frames, which decode without a GOP walk.
+     */
+    keyframeTimestamps(startS?: number, endS?: number): Promise<readonly number[]>;
+    /**
+     * Decodes a frame for each requested timestamp and returns a stable copy of
+     * each. Timestamps are sorted so the sink decodes each packet at most once;
+     * a timestamp with no frame is skipped rather than yielding a gap.
+     */
+    extractFrames(timestampsS: readonly number[]): Promise<ExtractedFrame[]>;
+    /**
+     * One frame per requested timestamp, in the order asked for, `null` where no
+     * frame covers it, so a caller pairing frames with its own indices keeps the
+     * gaps attributable. Timestamps that climb decode in a single pass over the
+     * track: one seek and GOP walk for the whole set.
+     *
+     * A consumer that finishes with each frame before pulling the next holds one
+     * frame of memory; {@link extractFrames} holds the whole set.
+     */
+    framesAtTimestamps(timestampsS: readonly number[]): AsyncGenerator<ExtractedFrame | null, void, unknown>;
+    close(): Promise<void>;
+    private copyFrame;
+}

package/dist/web-video-engine/analysis.d.ts

@@ -0,0 +1,6 @@
+export { AnalysisSession } from "./analysis-session";
+export type { AnalysisMetadata, AnalysisOptions, ExtractedFrame, } from "./analysis-session";
+export { FrameExtractor } from "./frame-extractor";
+export { FrameWalker, walkFrames } from "./frame-walker";
+export type { FrameWalkMetadata, FrameWalkRange, WalkedFrame, } from "./frame-walker";
+export type { WalkFrameSource } from "./decode-source";