video-fps-probe 0.2.0 → 0.4.0-beta.1

package/dist/core/reader.d.ts

@@ -1,3 +1,4 @@
+import type { FileErrorCode } from './types.js';
 export interface BlobSlice {
     arrayBuffer(): Promise<ArrayBuffer>;
 }
@@ -10,17 +11,9 @@ export interface BlobReaderOptions {
     maxWindows?: number;
     signal?: AbortSignal | null;
 }
-export interface ReaderStats {
-    reads: number;
-    bytesFetched: number;
-    bytesTransferred: number;
-}
 export declare const DEFAULT_HEAD_WINDOW: number;
 export declare const DEFAULT_MAX_WINDOWS = 4;
 export declare const MAX_SAFE_OFFSET: number;
-export declare class EndOfFileError extends Error {
-    constructor(message: string);
-}
 export declare function toSafeNumber(value: bigint, what?: string): number;
 export declare class BlobReader {
     #private;
@@ -31,16 +24,12 @@ export declare class BlobReader {
     constructor(source: BlobLike, options?: BlobReaderOptions);
     get reads(): number;
     get bytesFetched(): number;
-    get bytesTransferred(): number;
-    stats(): ReaderStats;
     checkAbort(): void;
     read(offset: number, length: number): Promise<Uint8Array>;
     readMany(ranges: ReadonlyArray<readonly [offset: number, length: number]>, concurrency?: number): Promise<Uint8Array[]>;
     peek(offset: number, length: number): DataView | null;
     view(offset: number, length: number, readAhead?: number): Promise<DataView>;
-    viewExact(offset: number, length: number, readAhead?: number): Promise<DataView>;
     bytes(offset: number, length: number, readAhead?: number): Promise<Uint8Array>;
-    clearCache(): void;
 }
 export declare function u8(dv: DataView, p: number): number;
 export declare function u16(dv: DataView, p: number): number;
@@ -54,3 +43,5 @@ export declare function u64Big(dv: DataView, p: number): bigint;
 export declare function fixed16_16(dv: DataView, p: number): number;
 export declare function ascii(dv: DataView, p: number, length: number): string;
 export declare function fourcc(dv: DataView, p: number): string;
+export declare function withErrorCode(code: FileErrorCode, message: string): Error;
+export declare function whichErrorCode(e: unknown, fallback?: FileErrorCode): FileErrorCode;

package/dist/core/reader.js

@@ -2,15 +2,9 @@ import { throwIfAborted } from "./abort.js";
 export const DEFAULT_HEAD_WINDOW = 64 * 1024;
 export const DEFAULT_MAX_WINDOWS = 4;
 export const MAX_SAFE_OFFSET = Number.MAX_SAFE_INTEGER;
-export class EndOfFileError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = 'EndOfFileError';
-    }
-}
-function assertSafeCount(value, what) {
+function assertSafeCount(value, what, kind = RangeError) {
     if (!Number.isSafeInteger(value) || value < 0)
-        throw new RangeError(`${what} must be a non-negative safe integer, got ${value}`);
+        throw new kind(`${what} must be a non-negative safe integer, got ${value}`);
 }
 export function toSafeNumber(value, what = 'value') {
     if (value > BigInt(MAX_SAFE_OFFSET) || value < -BigInt(MAX_SAFE_OFFSET))
@@ -27,15 +21,14 @@ export class BlobReader {
     #covered = [];
     #reads = 0;
     #unique = 0;
-    #transferred = 0;
     constructor(source, options = {}) {
-        assertSafeCount(source.size, 'blob size');
+        assertSafeCount(source.size, 'blob size', TypeError);
         this.#source = source;
         this.size = source.size;
         this.headWindow = options.headWindow ?? DEFAULT_HEAD_WINDOW;
         this.maxWindows = Math.max(1, options.maxWindows ?? DEFAULT_MAX_WINDOWS);
         this.signal = options.signal ?? null;
-        assertSafeCount(this.headWindow, 'headWindow');
+        assertSafeCount(this.headWindow, 'headWindow', TypeError);
     }
     get reads() {
         return this.#reads;
@@ -43,12 +36,6 @@ export class BlobReader {
     get bytesFetched() {
         return this.#unique;
     }
-    get bytesTransferred() {
-        return this.#transferred;
-    }
-    stats() {
-        return { reads: this.#reads, bytesFetched: this.#unique, bytesTransferred: this.#transferred };
-    }
     checkAbort() {
         throwIfAborted(this.signal);
     }
@@ -61,12 +48,18 @@ export class BlobReader {
         if (end === offset)
             return new Uint8Array(0);
         this.checkAbort();
-        const ab = await this.#source.slice(offset, end).arrayBuffer();
+        let ab;
+        try {
+            ab = await this.#source.slice(offset, end).arrayBuffer();
+        }
+        catch (e) {
+            this.checkAbort();
+            throw e?.name === 'AbortError' ? e : withErrorCode('read-failed', `file read failed: ${e}`);
+        }
         this.checkAbort();
         this.#reads++;
-        this.#transferred += ab.byteLength;
         if (ab.byteLength !== end - offset) {
-            throw new EndOfFileError(`short read at ${offset}: expected ${end - offset} bytes, got ${ab.byteLength}`);
+            throw withErrorCode('read-failed', `file read failed: short read at ${offset}: expected ${end - offset} bytes, got ${ab.byteLength}`);
         }
         this.#cover(offset, end);
         return new Uint8Array(ab);
@@ -105,7 +98,7 @@ export class BlobReader {
     async view(offset, length, readAhead = this.headWindow) {
         assertSafeCount(offset, 'offset');
         assertSafeCount(length, 'length');
-        assertSafeCount(readAhead, 'readAhead');
+        assertSafeCount(readAhead, 'readAhead', TypeError);
         if (offset > this.size)
             throw new RangeError(`offset ${offset} is beyond the end of the file (${this.size})`);
         const end = Math.min(this.size, offset + length);
@@ -132,20 +125,10 @@ export class BlobReader {
             this.#windows.length = this.maxWindows;
         return new DataView(buf.buffer, buf.byteOffset, end - offset);
     }
-    async viewExact(offset, length, readAhead = this.headWindow) {
-        const dv = await this.view(offset, length, readAhead);
-        if (dv.byteLength < length) {
-            throw new EndOfFileError(`unexpected end of file: wanted ${length} bytes at ${offset}, file size ${this.size}`);
-        }
-        return dv;
-    }
     async bytes(offset, length, readAhead = this.headWindow) {
         const dv = await this.view(offset, length, readAhead);
         return new Uint8Array(dv.buffer, dv.byteOffset, dv.byteLength);
     }
-    clearCache() {
-        this.#windows = [];
-    }
     #cover(start, end) {
         const list = this.#covered;
         let lo = 0;
@@ -213,5 +196,11 @@ export function ascii(dv, p, length) {
     return s;
 }
 export function fourcc(dv, p) {
-    return ascii(dv, p, 4);
+    return ascii(dv, p, 4).replace(/[^ -~]/g, '?');
+}
+export function withErrorCode(code, message) {
+    return Object.assign(Error(message), { errorCode: code });
+}
+export function whichErrorCode(e, fallback = 'internal') {
+    return e?.errorCode ?? (e instanceof RangeError ? 'corrupt' : fallback);
 }

package/dist/core/result.js

@@ -38,6 +38,7 @@ export function emptyTrack(trackId) {
         timestampsQuantized: false,
         isStill: false,
         rateProfile: null,
+        medianFrameInterval: null,
         provenance: {},
         warnings: [],
     };

package/dist/core/stats.js

@@ -134,6 +134,7 @@ function emptyStats(timescale, warnings) {
         minDelta: null,
         maxDelta: null,
         medianDelta: null,
+        medianFrameInterval: null,
         meanDelta: null,
         tolerance: null,
         minFps: null,
@@ -235,6 +236,8 @@ function applyHistogram(base, hist, tickQuantized) {
     base.minDelta = minD;
     base.maxDelta = maxD;
     base.medianDelta = median;
+    const interval = rateFromTicks(ts, median);
+    base.medianFrameInterval = interval && makeRational(interval.den, interval.num);
     base.meanDelta = sum / total;
     base.tolerance = tol;
     base.minFps = rateFromTicks(ts, maxD);

package/dist/core/types.d.ts

@@ -17,7 +17,7 @@ export type ContainerKind = 'mp4' | 'mov' | 'webm' | 'matroska' | 'unknown';
 export type EngineId = 'own' | 'mediabunny' | 'mp4box' | 'rvfc';
 export type MatroskaMode = 'header' | 'probe' | 'exact' | 'auto';
 export type ScanDepth = 'header' | 'probe' | 'exact';
-export type TrackField = 'codec' | 'dimensions' | 'rotation' | 'frames' | 'presentedFrames' | 'durationSec' | 'startSec' | 'avgFps' | 'nominalFps' | 'dominantFps' | 'minFps' | 'maxFps' | 'isVfr' | 'duplicateTimestamps';
+export type TrackField = 'codec' | 'dimensions' | 'rotation' | 'frames' | 'presentedFrames' | 'durationSec' | 'startSec' | 'avgFps' | 'nominalFps' | 'dominantFps' | 'minFps' | 'maxFps' | 'isVfr' | 'duplicateTimestamps' | 'medianFrameInterval';
 export type RateSegmentKind = 'steady' | 'variable';
 export interface RateSegment {
     startSec: number;
@@ -74,6 +74,8 @@ export interface VideoTrackResult {
     timestampsQuantized: boolean;
     isStill: boolean;
     rateProfile?: RateProfile | null;
+    medianFrameInterval?: Rational | null;
+    enabled?: boolean;
     provenance: Partial<Record<TrackField, Provenance>>;
     warnings: string[];
 }
@@ -82,6 +84,16 @@ export interface IoStats {
     bytesRead: number;
     ms: number;
 }
+export type FileErrorCode = 'empty-file' | 'unrecognised' | 'unsupported-container' | 'unsupported' | 'too-large' | 'no-header' | 'truncated' | 'corrupt' | 'no-duration' | 'byte-limit' | 'read-limit' | 'time-limit' | 'structure-limit' | 'read-failed' | 'load-failed' | 'engine-failed' | 'internal';
+export type LayoutKind = 'faststart' | 'moov-at-end' | 'fragmented';
+export interface ContainerLayout {
+    kind: LayoutKind;
+    moovOffset: number | null;
+    moovSize: number | null;
+    sidx: boolean;
+    emptyMoov: boolean;
+}
+export type WarningCode = 'invalid-timescale' | 'truncated-mdat' | 'truncated-box' | 'trailing-data' | 'fragment-index-unread' | 'duration-unresolved' | 'fragments-ignored' | 'structure-limit';
 export interface FileResult {
     name: string;
     size: number;
@@ -93,6 +105,8 @@ export interface FileResult {
     audioTrackCount: number;
     primaryTrackId: number | null;
     error: string | null;
+    errorCode?: FileErrorCode | null;
+    layout?: ContainerLayout | null;
     warnings: string[];
     io: IoStats;
     engine: EngineId;

package/dist/engines/common.js

@@ -53,6 +53,12 @@ export function isAbort(e, signal) {
 export function newResult(name, size, engine) {
     return { name, size, ...emptyAnalysis('unknown'), io: { reads: 0, bytesRead: 0, ms: 0 }, engine };
 }
+const printable = (warnings) => warnings.map((w) => w.replace(/[^\x20-\x7e\xa0-\uffff]/g, '?'));
+export function printableWarnings(result) {
+    result.warnings = printable(result.warnings);
+    for (const t of result.videoTracks)
+        t.warnings = printable(t.warnings);
+}
 export function ffprobeRotation(matrix) {
     const a = matrix[0] / 65536;
     const b = matrix[1] / 65536;
@@ -102,6 +108,7 @@ export function applyStats(track, stats, source = 'exact') {
     track.dominantFps = stats.dominantFps;
     track.minFps = stats.minFps;
     track.maxFps = stats.maxFps;
+    track.medianFrameInterval = stats.medianFrameInterval;
     track.isVfr = stats.isVfr;
     track.vfrRatio = stats.vfrRatio;
     track.distinctDeltas = stats.distinctDeltas;
@@ -120,5 +127,6 @@ export function applyStats(track, stats, source = 'exact') {
         maxFps: source,
         isVfr: source,
         duplicateTimestamps: source,
+        medianFrameInterval: source,
     });
 }

package/dist/engines/mediabunny.js

@@ -3,7 +3,7 @@ import { throwIfAborted } from "../core/abort.js";
 import { resolveOptions } from "../core/options.js";
 import { emptyTrack } from "../core/result.js";
 import { analyzeTimeline } from "../core/stats.js";
-import { applyStats, approxRational, codecNameFromFourcc, errorMessage, isAbort, newResult } from "./common.js";
+import { applyStats, approxRational, codecNameFromFourcc, errorMessage, isAbort, newResult, printableWarnings } from "./common.js";
 import { CountingBlob, elapsed, now } from "./counting.js";
 export const MEDIABUNNY_VERSION = '1.62.1';
 const CODEC_NAMES = {
@@ -145,7 +145,18 @@ async function probe(counted, result, opts, t0) {
     ];
     const source = new CustomSource({
         getSize: () => counted.size,
-        read: async (start, end) => new Uint8Array(await counted.slice(start, end).arrayBuffer()),
+        read: async (start, end) => {
+            let ab;
+            try {
+                ab = await counted.slice(start, end).arrayBuffer();
+            }
+            catch (e) {
+                throw isAbort(e, signal) ? e : Error(`file read failed: ${e}`);
+            }
+            if (ab.byteLength !== end - start)
+                throw Error(`file read failed: short read at ${start}: expected ${end - start} bytes, got ${ab.byteLength}`);
+            return new Uint8Array(ab);
+        },
         prefetchProfile: 'fileSystem',
         handleUnhandledError: (e) => {
             unhandled.push(errorMessage(e));
@@ -160,7 +171,8 @@ async function probe(counted, result, opts, t0) {
         catch (e) {
             if (isAbort(e, signal))
                 throw e;
-            result.error = `not a recognised container: ${errorMessage(e)}`;
+            const message = errorMessage(e);
+            result.error = message.startsWith('file read failed') ? message : `not a recognised container: ${message}`;
             return;
         }
         result.container = containerOf(format);
@@ -176,7 +188,7 @@ async function probe(counted, result, opts, t0) {
                 works.push(await collectTrack(track, quantized, signal, maxPackets));
             }
             catch (e) {
-                if (isAbort(e, signal))
+                if (isAbort(e, signal) || errorMessage(e).startsWith('file read failed'))
                     throw e;
                 result.warnings.push(`track ${track.id}: ${errorMessage(e)}`);
             }
@@ -235,6 +247,7 @@ export async function analyzeWithMediabunny(blob, name, opts = {}) {
     }
     if (result.mediabunny === undefined)
         result.io = counted.io(t0);
+    printableWarnings(result);
     return result;
 }
 export const containers = 'any';

package/dist/engines/mp4box.js

@@ -5,7 +5,7 @@ import { BlobReader, fourcc, u32, u64 } from "../core/reader.js";
 import { emptyTrack } from "../core/result.js";
 import { sniff } from "../core/sniff.js";
 import { analyzeTimeline } from "../core/stats.js";
-import { applyStats, codecNameFromFourcc, errorMessage, ffprobeRotation, isAbort, newResult } from "./common.js";
+import { applyStats, codecNameFromFourcc, errorMessage, ffprobeRotation, isAbort, newResult, printableWarnings } from "./common.js";
 import { CountingBlob, now } from "./counting.js";
 export const MP4BOX_VERSION = '2.4.1';
 const MAX_TOP_LEVEL_BOXES = 5_000_000;
@@ -423,6 +423,7 @@ export async function analyzeWithMp4box(blob, name, opts = {}) {
         result.error = errorMessage(e);
     }
     result.io = counted.io(t0);
+    printableWarnings(result);
     return result;
 }
 export const containers = ['isobmff'];

package/dist/header/index.d.ts

@@ -0,0 +1,25 @@
+import { type BlobLike } from '../core/reader.js';
+import type { FileResult, IoStats } from '../core/types.js';
+import { type HeaderLimits } from './limits.js';
+export { errorClass, errorCodeOf, warningCodeOf, warningCodesOf, type ErrorClass } from '../api/codes.js';
+export { isAbortError, isTimeoutError } from '../api/guards.js';
+export { HEADER_DEFAULT_LIMITS, type HeaderLimits } from './limits.js';
+export type { BlobLike, BlobSlice } from '../core/reader.js';
+export type * from '../core/types.js';
+export type FragmentedDuration = 'header' | 'index';
+export interface HeaderOptions {
+    name?: string;
+    signal?: AbortSignal | null;
+    limits?: HeaderLimits;
+    readAhead?: {
+        head?: number;
+        tail?: number;
+    };
+    fragmentedDuration?: FragmentedDuration;
+}
+export type HeaderResult = FileResult & {
+    io: IoStats & {
+        bytesRequested: number;
+    };
+};
+export declare function analyzeHeader(source: Blob | BlobLike, options?: HeaderOptions): Promise<HeaderResult>;

package/dist/header/index.js

@@ -0,0 +1,146 @@
+import { throwIfAborted } from "../core/abort.js";
+import { analyzeIsoBmffHeader } from "../core/isobmff/header.js";
+import { DEFAULT_READ_AHEAD } from "../core/options.js";
+import { BlobReader, whichErrorCode } from "../core/reader.js";
+import { emptyAnalysis } from "../core/result.js";
+import { sniff } from "../core/sniff.js";
+import { HEADER_DEFAULT_LIMITS, LimitedSource } from "./limits.js";
+export { errorClass, errorCodeOf, warningCodeOf, warningCodesOf } from "../api/codes.js";
+export { isAbortError, isTimeoutError } from "../api/guards.js";
+export { HEADER_DEFAULT_LIMITS } from "./limits.js";
+const SNIFF_BYTES = 1024;
+const MIN_HEAD = SNIFF_BYTES;
+const MIN_TAIL = 16;
+function shown(value) {
+    if (typeof value === 'string')
+        return JSON.stringify(value);
+    if (typeof value === 'object' && value !== null)
+        return Array.isArray(value) ? 'an array' : 'an object';
+    return String(value);
+}
+function count(value, what, min = 0, infinite = false) {
+    if (infinite && value === Number.POSITIVE_INFINITY)
+        return value;
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < min) {
+        throw new TypeError(`${what} must be a non-negative safe integer${min > 0 ? ` of at least ${min}` : ''}${infinite ? ' or Infinity' : ''}, got ${shown(value)}`);
+    }
+    return value;
+}
+function record(value, what) {
+    if (value === undefined)
+        return {};
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        throw new TypeError(`${what} must be an object, got ${shown(value)}`);
+    return value;
+}
+function resolveHeaderOptions(source, options) {
+    const src = source;
+    if (typeof src !== 'object' || src === null || typeof src.slice !== 'function')
+        throw new TypeError(`source must be a Blob or a BlobLike with a size and a slice method, got ${shown(source)}`);
+    const size = count(src.size, 'source.size');
+    const o = record(options, 'options');
+    if (o.name !== undefined && typeof o.name !== 'string')
+        throw new TypeError(`name must be a string, got ${shown(o.name)}`);
+    const signal = o.signal ?? null;
+    if (signal !== null) {
+        const s = signal;
+        if (typeof s !== 'object' || typeof s.aborted !== 'boolean' || typeof s.addEventListener !== 'function' || typeof s.removeEventListener !== 'function')
+            throw new TypeError(`signal must be an AbortSignal, got ${shown(signal)}`);
+    }
+    const l = record(o.limits, 'limits');
+    const limits = { ...HEADER_DEFAULT_LIMITS };
+    for (const key of Object.keys(HEADER_DEFAULT_LIMITS))
+        if (l[key] !== undefined)
+            limits[key] = count(l[key], `limits.${key}`, 0, true);
+    const r = record(o.readAhead, 'readAhead');
+    for (const key of Object.keys(r))
+        if (key !== 'head' && key !== 'tail' && r[key] !== undefined)
+            throw new TypeError(`readAhead takes only head and tail, got ${key}`);
+    const head = r.head === undefined ? DEFAULT_READ_AHEAD.head : count(r.head, 'readAhead.head', MIN_HEAD);
+    const tail = r.tail === undefined ? DEFAULT_READ_AHEAD.tail : count(r.tail, 'readAhead.tail', MIN_TAIL);
+    const mode = o.fragmentedDuration ?? 'index';
+    if (mode !== 'index' && mode !== 'header')
+        throw new TypeError(`fragmentedDuration must be 'header' or 'index', got ${shown(mode)}`);
+    const name = o.name ?? (typeof File !== 'undefined' && source instanceof File ? source.name : '');
+    return { name, size, signal: signal, limits, head, tail, index: mode === 'index' };
+}
+function docTypeOf(head) {
+    let p = 4;
+    const vint = (marker) => {
+        if (p >= head.length)
+            return null;
+        const first = head[p];
+        let len = 1;
+        while (len <= 8 && !(first & (0x80 >> (len - 1))))
+            len++;
+        if (len > 8 || p + len > head.length)
+            return null;
+        let v = marker ? first : first & (0xff >> len);
+        for (let i = 1; i < len; i++)
+            v = v * 256 + head[p + i];
+        p += len;
+        return v;
+    };
+    const size = vint(false);
+    if (size === null)
+        return null;
+    const end = Math.min(head.length, p + size);
+    while (p < end) {
+        const id = vint(true);
+        const n = vint(false);
+        if (id === null || n === null || p + n > end)
+            return null;
+        if (id === 0x4282)
+            return String.fromCharCode(...head.subarray(p, p + n)).replace(/\0+$/, '');
+        p += n;
+    }
+    return null;
+}
+function failed(analysis, message, code) {
+    analysis.error = message;
+    analysis.errorCode = code;
+    return analysis;
+}
+async function analyzeSource(reader, limited, o) {
+    const analysis = { ...emptyAnalysis('unknown'), scan: 'header', errorCode: null, layout: null };
+    const size = reader.size;
+    if (size === 0)
+        return failed(analysis, 'not a recognised container: empty file', 'empty-file');
+    const head = await reader.bytes(0, Math.min(SNIFF_BYTES, size), Math.min(size, o.head, limited.bytesLeft));
+    const sniffed = sniff(head);
+    if (sniffed.kind === 'unknown')
+        return failed(analysis, `not a recognised container: ${sniffed.reason}`, 'unrecognised');
+    if (sniffed.kind === 'matroska') {
+        analysis.container = docTypeOf(head) === 'webm' ? 'webm' : 'matroska';
+        return failed(analysis, `container not read by the header entry: ${analysis.container}`, 'unsupported-container');
+    }
+    const { maxTracks, maxTopLevelBoxes } = o.limits;
+    return analyzeIsoBmffHeader(reader, limited, { head: o.head, tail: o.tail, maxTracks, maxTopLevelBoxes, index: o.index });
+}
+export async function analyzeHeader(source, options = {}) {
+    const t0 = performance.now();
+    const o = resolveHeaderOptions(source, options);
+    throwIfAborted(o.signal);
+    const limited = new LimitedSource(source, o.size, o.limits, o.signal);
+    const reader = new BlobReader(limited, { headWindow: o.head, signal: o.signal });
+    let analysis;
+    try {
+        analysis = await analyzeSource(reader, limited, o);
+    }
+    catch (e) {
+        throwIfAborted(o.signal);
+        const limit = limited.take();
+        analysis = { ...emptyAnalysis('unknown'), scan: 'header', errorCode: null, layout: null };
+        failed(analysis, limit ? limit.message : e instanceof Error ? e.message || e.name : String(e), whichErrorCode(limit ?? e));
+    }
+    finally {
+        limited.dispose();
+    }
+    return {
+        name: o.name,
+        size: o.size,
+        ...analysis,
+        io: { reads: reader.reads, bytesRead: reader.bytesFetched, ms: performance.now() - t0, bytesRequested: limited.bytesRequested },
+        engine: 'own',
+    };
+}

package/dist/header/limits.d.ts

@@ -0,0 +1,25 @@
+import type { BlobLike, BlobSlice } from '../core/reader.js';
+export interface HeaderLimits {
+    maxBytes?: number;
+    maxReads?: number;
+    maxMs?: number;
+    maxTracks?: number;
+    maxTopLevelBoxes?: number;
+}
+export declare const HEADER_DEFAULT_LIMITS: Readonly<Required<HeaderLimits>>;
+export type LimitCode = 'byte-limit' | 'read-limit' | 'time-limit' | 'structure-limit';
+export declare class LimitError extends Error {
+    readonly errorCode: LimitCode;
+    constructor(code: LimitCode, message: string);
+}
+export declare class LimitedSource implements BlobLike {
+    #private;
+    readonly size: number;
+    constructor(inner: BlobLike, size: number, limits: Required<Pick<HeaderLimits, 'maxBytes' | 'maxReads' | 'maxMs'>>, caller: AbortSignal | null);
+    get bytesLeft(): number;
+    get bytesRequested(): number;
+    checkTime(): void;
+    take(): LimitError | null;
+    slice(start?: number, end?: number): BlobSlice;
+    dispose(): void;
+}

package/dist/header/limits.js

@@ -0,0 +1,140 @@
+export const HEADER_DEFAULT_LIMITS = Object.freeze({
+    maxBytes: 16 * 1024 * 1024,
+    maxReads: 8,
+    maxMs: 10_000,
+    maxTracks: 64,
+    maxTopLevelBoxes: 1024,
+});
+export class LimitError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.name = 'LimitError';
+        this.errorCode = code;
+    }
+}
+const noop = () => { };
+const MAX_TIMER_MS = 0x7fffffff;
+function sourceError(message) {
+    return Object.assign(new Error(message), { name: '' });
+}
+function bufferOf(value) {
+    if (ArrayBuffer.isView(value)) {
+        const bytes = new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+        return bytes.byteOffset === 0 && bytes.byteLength === bytes.buffer.byteLength && bytes.buffer instanceof ArrayBuffer ? bytes.buffer : bytes.slice().buffer;
+    }
+    if (typeof value?.byteLength !== 'number')
+        throw sourceError(`the source returned ${value === null ? 'null' : typeof value} instead of bytes`);
+    return value;
+}
+export class LimitedSource {
+    size;
+    #inner;
+    #maxBytes;
+    #maxReads;
+    #maxMs;
+    #deadline;
+    #controller = new AbortController();
+    #stopped;
+    #caller;
+    #forward = () => this.#controller.abort(this.#caller?.reason);
+    #timer = null;
+    #timedOut = false;
+    #reads = 0;
+    #bytes = 0;
+    #tripped = null;
+    constructor(inner, size, limits, caller) {
+        this.size = size;
+        this.#inner = inner;
+        this.#maxBytes = limits.maxBytes;
+        this.#maxReads = limits.maxReads;
+        this.#maxMs = limits.maxMs;
+        this.#deadline = performance.now() + limits.maxMs;
+        this.#caller = caller;
+        const internal = this.#controller.signal;
+        this.#stopped = new Promise((_, reject) => internal.addEventListener('abort', () => reject(internal.reason), { once: true }));
+        this.#stopped.catch(noop);
+        if (caller) {
+            if (caller.aborted)
+                this.#forward();
+            else
+                caller.addEventListener('abort', this.#forward, { once: true });
+        }
+        if (Number.isFinite(limits.maxMs) && !internal.aborted)
+            this.#arm(limits.maxMs);
+    }
+    #arm(left) {
+        const step = Math.min(left, MAX_TIMER_MS);
+        this.#timer = setTimeout(() => {
+            if (left > step)
+                return this.#arm(left - step);
+            this.#timer = null;
+            this.#timedOut = true;
+            this.#controller.abort(new LimitError('time-limit', `limit reached: maxMs ${this.#maxMs}`));
+        }, step);
+    }
+    get bytesLeft() {
+        return this.#maxBytes - this.#bytes;
+    }
+    get bytesRequested() {
+        return this.#bytes;
+    }
+    checkTime() {
+        if (this.#timedOut || performance.now() >= this.#deadline)
+            throw this.#trip('time-limit', `limit reached: maxMs ${this.#maxMs}`);
+    }
+    take() {
+        const t = this.#tripped;
+        this.#tripped = null;
+        return t;
+    }
+    slice(start = 0, end = this.size) {
+        return { arrayBuffer: () => this.#fetch(start, end) };
+    }
+    dispose() {
+        if (this.#timer !== null)
+            clearTimeout(this.#timer);
+        this.#timer = null;
+        this.#caller?.removeEventListener('abort', this.#forward);
+    }
+    #trip(code, message) {
+        this.#tripped = new LimitError(code, message);
+        return this.#tripped;
+    }
+    #admission(bytes, offset) {
+        if (this.#reads + 1 > this.#maxReads)
+            return this.#trip('read-limit', `limit reached: maxReads ${this.#maxReads}`);
+        if (this.#bytes + bytes > this.#maxBytes)
+            return this.#trip('byte-limit', `limit reached: maxBytes ${this.#maxBytes} (${this.#bytes + bytes - this.#maxBytes} more bytes needed at offset ${offset})`);
+        try {
+            this.checkTime();
+        }
+        catch (e) {
+            return e;
+        }
+        return null;
+    }
+    #fetch(start, end) {
+        const length = Math.max(0, end - start);
+        const trip = this.#admission(length, start);
+        if (trip)
+            return Promise.reject(trip);
+        this.#reads++;
+        this.#bytes += length;
+        let pending;
+        try {
+            const inner = this.#inner;
+            pending = Promise.resolve(typeof inner.read === 'function' ? inner.read(start, end, this.#controller.signal) : inner.slice(start, end).arrayBuffer()).then(bufferOf);
+        }
+        catch (e) {
+            pending = Promise.reject(e);
+        }
+        pending.catch(noop);
+        return Promise.race([pending, this.#stopped]).catch((e) => {
+            if (e instanceof LimitError)
+                this.#tripped = e;
+            else if (!this.#controller.signal.aborted && e?.name === 'AbortError')
+                throw sourceError(String(e));
+            throw e;
+        });
+    }
+}

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { analyze, type InThreadOptions } from './analyze.js';
 export { compareResults, type Agreement, type ComparedField, type ComparedFieldName, type ComparedValue } from './api/agreement.js';
+export { errorClass, errorCodeOf, warningCodeOf, warningCodesOf, type ErrorClass } from './api/codes.js';
 export { ProbeError, type ProbeErrorCode } from './api/errors.js';
 export { isAbortError, isTimeoutError } from './api/guards.js';
 export { summarize, type VideoFpsSummary } from './api/summary.js';