video-fps-probe 0.3.0 → 0.4.0-beta.2

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,14 +74,69 @@ export interface VideoTrackResult {
     timestampsQuantized: boolean;
     isStill: boolean;
     rateProfile?: RateProfile | null;
+    medianFrameInterval?: Rational | null;
+    enabled?: boolean;
+    codecConfig?: CodecConfig;
+    color?: ColorInfo | null;
+    sampleAspectRatio?: Rational | null;
+    displayAspectRatio?: Rational | null;
+    displayWidth?: number | null;
+    displayHeight?: number | null;
     provenance: Partial<Record<TrackField, Provenance>>;
     warnings: string[];
 }
+export type CodecConfig = {
+    family: 'isobmff';
+    stsd: Uint8Array | null;
+    tkhd: Uint8Array | null;
+    mvhd: Uint8Array | null;
+} | {
+    family: 'isobmff-moov';
+    moov: DataView;
+    trak: number;
+} | {
+    family: 'matroska';
+    trackEntry: Uint8Array | null;
+};
+export type ColorSource = 'sps' | 'colr' | 'vpcC' | 'Colour';
+export interface DolbyVisionConfig {
+    versionMajor: number;
+    versionMinor: number;
+    profile: number;
+    level: number;
+    rpu: boolean;
+    el: boolean;
+    bl: boolean;
+    compatibilityId: number;
+    mdCompression: number;
+}
+export interface ColorInfo {
+    range: 'tv' | 'pc' | null;
+    primaries: string | null;
+    transfer: string | null;
+    space: string | null;
+    source: ColorSource | null;
+    bitDepth: number | null;
+    profile: number | null;
+    codecString: string | null;
+    hdr: 'pq' | 'hlg' | null;
+    dolbyVision: DolbyVisionConfig | null;
+}
 export interface IoStats {
     reads: number;
     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' | 'codec-config-unavailable' | 'metadata-unavailable';
 export interface FileResult {
     name: string;
     size: number;
@@ -93,6 +148,8 @@ export interface FileResult {
     audioTrackCount: number;
     primaryTrackId: number | null;
     error: string | null;
+    errorCode?: FileErrorCode | null;
+    layout?: ContainerLayout | null;
     warnings: string[];
     io: IoStats;
     engine: EngineId;
@@ -122,6 +179,7 @@ export interface AnalyzeOptions {
     costModel?: Partial<CostModel>;
     maxExpandedSamples?: number;
     onProgress?: ((progress: AnalyzeProgress) => void) | null;
+    codecConfig?: boolean;
 }
 export interface ResolvedAnalyzeOptions {
     signal: AbortSignal | null;
@@ -131,5 +189,6 @@ export interface ResolvedAnalyzeOptions {
     costModel: CostModel;
     maxExpandedSamples: number;
     onProgress: ((progress: AnalyzeProgress) => void) | null;
+    codecConfig?: boolean;
 }
 export type ContainerAnalyzer = (reader: BlobReader, opts: ResolvedAnalyzeOptions) => Promise<ContainerAnalysis>;

package/dist/engines/common.js

@@ -108,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;
@@ -126,5 +127,6 @@ export function applyStats(track, stats, source = 'exact') {
         maxFps: source,
         isVfr: source,
         duplicateTimestamps: source,
+        medianFrameInterval: source,
     });
 }

package/dist/header/index.d.ts

@@ -0,0 +1,28 @@
+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;
+    codecConfig?: boolean;
+    color?: boolean;
+    aspect?: boolean;
+}
+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,182 @@
+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 flag(value, what) {
+    if (value !== undefined && typeof value !== 'boolean')
+        throw new TypeError(`${what} must be a boolean, got ${shown(value)}`);
+    return value === true;
+}
+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', codecConfig: flag(o.codecConfig, 'codecConfig'), color: flag(o.color, 'color'), aspect: flag(o.aspect, 'aspect') };
+}
+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, codecConfig: o.codecConfig || o.color || o.aspect });
+}
+const messageOf = (e) => (e instanceof Error ? e.message || e.name : String(e));
+let metadata;
+let metadataLoad;
+function loadMetadata() {
+    metadataLoad ??= import("./metadata.js").then((m) => (metadata = m), (e) => {
+        metadataLoad = undefined;
+        throw e;
+    });
+    return metadataLoad;
+}
+async function withMetadata(analysis, o, limited) {
+    try {
+        const { withAspect, withColor } = metadata ?? (await limited.race(loadMetadata()));
+        throwIfAborted(o.signal);
+        const last = { keepCodecConfig: o.codecConfig };
+        const colored = o.color ? withColor(analysis, o.aspect ? { keepCodecConfig: true } : last) : analysis;
+        return o.aspect ? withAspect(colored, last) : colored;
+    }
+    catch (e) {
+        throwIfAborted(o.signal);
+        const videoTracks = analysis.videoTracks.map((t) => {
+            const kept = { ...t };
+            if (!o.codecConfig)
+                delete kept.codecConfig;
+            return kept;
+        });
+        return { ...analysis, videoTracks, warnings: [...analysis.warnings, `color and aspect unavailable: ${messageOf(e)}`] };
+    }
+}
+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);
+        if ((o.color || o.aspect) && analysis.videoTracks.some((t) => t.codecConfig))
+            analysis = await withMetadata(analysis, o, limited);
+    }
+    catch (e) {
+        throwIfAborted(o.signal);
+        const limit = limited.take();
+        analysis = { ...emptyAnalysis('unknown'), scan: 'header', errorCode: null, layout: null };
+        failed(analysis, limit ? limit.message : messageOf(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,26 @@
+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;
+    race<T>(pending: Promise<T>): Promise<T>;
+    slice(start?: number, end?: number): BlobSlice;
+    dispose(): void;
+}

package/dist/header/limits.js

@@ -0,0 +1,144 @@
+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;
+    }
+    race(pending) {
+        pending.catch(noop);
+        return Promise.race([pending, this.#stopped]);
+    }
+    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/header/metadata.js

@@ -0,0 +1,2 @@
+export { withAspect } from "../aspect/index.js";
+export { withColor } from "../color/index.js";

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';

package/dist/index.js

@@ -1,5 +1,6 @@
 export { analyze } from "./analyze.js";
 export { compareResults } from "./api/agreement.js";
+export { errorClass, errorCodeOf, warningCodeOf, warningCodesOf } from "./api/codes.js";
 export { ProbeError } from "./api/errors.js";
 export { isAbortError, isTimeoutError } from "./api/guards.js";
 export { summarize } from "./api/summary.js";