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

package/dist/core/isobmff/index.js

@@ -1,392 +1,19 @@
-import { emptyAnalysis, emptyTrack } from "../result.js";
+import { emptyAnalysis } from "../result.js";
 import { analyzeTimeline, rateProfileOf } from "../stats.js";
-import { toFfprobeString } from "../rational.js";
-import { IsoBmffError, readBoxHeader } from "./boxes.js";
-import { codecNameFor, isVideoFourcc } from "./codecs.js";
+import { buildVideoTrack, containerOf, emulateFfprobeExtent, formatDuration, isAbort, isVideoTrack, layoutOf, pickPrimary, reportedIds, walk } from "./build.js";
+import { whichErrorCode } from "../reader.js";
 import { newMovie } from "./model.js";
-import { parseMoof, parseSidx } from "./moof.js";
-import { parseMoov } from "./moov.js";
-import { mfraMoofOffsets, newPrefetch, prefetchNext, prefetched } from "./prefetch.js";
-import { averageRates, displayRotation, editInfo, ffprobeStage1Rate, missingMandatoryAtoms, moovSamplesInFile, presentationWindow, rescaleRound, sampleTotals, timelineSegments, trackTiming, } from "./track.js";
 export { IsoBmffError } from "./boxes.js";
-export const MOOV_SUSPECT_CAP = 16 * 1024 * 1024;
-export const MOOV_HARD_CAP = 256 * 1024 * 1024;
-export const MOOF_HARD_CAP = 64 * 1024 * 1024;
-const MAX_TOP_LEVEL_BOXES = 4_000_000;
-const SMALL_MDAT = 64 * 1024;
-const HEADER_PEEK = 16;
-function isAbort(e, reader) {
-    return reader.signal?.aborted === true || e?.name === 'AbortError';
-}
-function containerOf(movie) {
-    return movie.brand === 'qt  ' || (!movie.hasFtyp && movie.topLevel.length > 0) ? 'mov' : 'mp4';
-}
-async function readMoov(reader, h, movie) {
-    const size = reader.size;
-    const beyond = h.start + h.size > size;
-    if (!beyond && h.size > MOOV_HARD_CAP)
-        throw new IsoBmffError('unsupported: moov larger than 256 MiB');
-    const len = beyond ? Math.min(size - h.start, MOOV_SUSPECT_CAP) : h.size;
-    const dv = await reader.view(h.start, len, 0);
-    const mh = readBoxHeader(dv, 0, dv.byteLength);
-    if (!mh)
-        throw new IsoBmffError('incomplete file: moov is truncated');
-    parseMoov(dv, mh, movie, beyond, h.start);
-    if (beyond)
-        movie.warnings.push('moov size exceeds the file; parsed what is there');
-}
-async function walk(reader, opts, movie) {
-    const size = reader.size;
-    let pos = 0;
-    let ahead = opts.readAhead.head;
-    let sawMoov = false;
-    let boxes = 0;
-    let afterMdat = false;
-    const pf = newPrefetch();
-    const look = async (at, need, readAhead) => prefetched(pf, at, need) ?? reader.view(at, need, readAhead);
-    while (pos + 8 <= size) {
-        reader.checkAbort();
-        if (++boxes > MAX_TOP_LEVEL_BOXES) {
-            movie.warnings.push('too many top-level boxes');
-            break;
-        }
-        const tailRead = afterMdat && !sawMoov && size - pos <= MOOV_SUSPECT_CAP ? size - pos : ahead;
-        const hv = await look(pos, Math.min(HEADER_PEEK, size - pos), tailRead);
-        let rel;
-        try {
-            rel = readBoxHeader(hv, 0, size - pos, pos);
-        }
-        catch (e) {
-            if (!sawMoov)
-                throw e;
-            movie.warnings.push(`ignored trailing data at ${pos}: ${e.message}`);
-            break;
-        }
-        if (!rel)
-            break;
-        const h = { ...rel, start: pos, end: Math.min(pos + rel.size, size) };
-        const boxEnd = pos + rel.size;
-        const trailer = rel.truncated && sawMoov && h.type !== 'mdat' && h.type !== 'moof';
-        if (rel.truncated) {
-            movie.truncated = true;
-            movie.warnings.push(trailer ? `ignored trailing data at ${pos}: not a box` : `'${h.type}' at ${pos} is truncated`);
-        }
-        const top = { type: h.type, start: pos, end: h.end, sidx: null };
-        movie.topLevel.push(top);
-        if (trailer)
-            break;
-        if (h.type === 'ftyp') {
-            const fv = await reader.view(pos, Math.min(h.size, 1024));
-            const p = h.headerSize;
-            if (p + 4 <= fv.byteLength) {
-                movie.hasFtyp = true;
-                movie.brand = String.fromCharCode(fv.getUint8(p), fv.getUint8(p + 1), fv.getUint8(p + 2), fv.getUint8(p + 3));
-                for (let q = p + 8; q + 4 <= fv.byteLength; q += 4) {
-                    movie.compatibleBrands.push(String.fromCharCode(fv.getUint8(q), fv.getUint8(q + 1), fv.getUint8(q + 2), fv.getUint8(q + 3)));
-                }
-            }
-        }
-        else if (h.type === 'moov') {
-            if (sawMoov)
-                movie.warnings.push(`ignored a second moov at ${pos}`);
-            else {
-                await readMoov(reader, h, movie);
-                sawMoov = true;
-            }
-        }
-        else if (h.type === 'moof') {
-            if (!sawMoov)
-                throw new IsoBmffError('corrupt file: movie fragment (moof) before moov');
-            if (h.size > MOOF_HARD_CAP)
-                throw new IsoBmffError(`corrupt file: moof larger than 64 MiB at ${pos}`);
-            const want = Math.min(h.size + HEADER_PEEK, size - pos);
-            const dv = await look(pos, want, 0);
-            const mh = readBoxHeader(dv, 0, Math.min(h.size, dv.byteLength));
-            if (mh)
-                parseMoof(dv, mh, pos, movie.moofCount, movie, opts.maxExpandedSamples);
-            movie.moofCount++;
-            let gap = 0;
-            try {
-                const next = readBoxHeader(dv, h.size, dv.byteLength);
-                if (next && next.type === 'mdat')
-                    gap = next.size;
-            }
-            catch {
-                gap = 0;
-            }
-            ahead = gap <= SMALL_MDAT ? opts.readAhead.fragment : Math.min(65536, Math.max(1024, 2 * h.size + 64));
-            if (gap > SMALL_MDAT) {
-                if (!pf.hints.length && !pf.mfraTried && (size - pos) / (h.size + gap) > 16) {
-                    pf.mfraTried = true;
-                    pf.hints = await mfraMoofOffsets(reader);
-                }
-                if (pf.next < pf.hints.length && !prefetched(pf, pos + h.size + gap, HEADER_PEEK))
-                    await prefetchNext(reader, pf, pos, ahead);
-            }
-            if (opts.onProgress && movie.moofCount % 64 === 0)
-                opts.onProgress({ phase: 'fragments', done: pos, total: size });
-        }
-        else if (h.type === 'sidx' && !rel.truncated) {
-            const dv = await look(pos, h.size, 0);
-            const sh = readBoxHeader(dv, 0, dv.byteLength);
-            if (sh)
-                top.sidx = parseSidx(dv, sh, pos);
-            if (top.sidx && top.sidx.subsegments.length > 1 && !pf.hints.length)
-                pf.hints = top.sidx.subsegments.map(([o]) => o);
-        }
-        else if (h.type === 'mfra') {
-            break;
-        }
-        afterMdat = h.type === 'mdat';
-        pos = boxEnd;
-    }
-    if (!sawMoov)
-        throw new IsoBmffError('incomplete file: no moov');
-}
-async function emulateFfprobeExtent(reader, movie) {
-    const size = reader.size;
-    const ids = new Set(movie.tracks.map((t) => t.id));
-    let foundMoov = false;
-    let foundMdat = false;
-    let complete = false;
-    let mfraSize = null;
-    let moofs = 0;
-    for (const b of movie.topLevel) {
-        if (b.type === 'moof')
-            moofs++;
-        else if (b.type === 'moov')
-            foundMoov = true;
-        else if (b.type === 'mdat' && b.end - b.start > 8)
-            foundMdat = true;
-        else if (b.type === 'sidx' && foundMoov && b.sidx && !b.sidx.hierarchical && ids.has(b.sidx.referenceId)) {
-            let whole = b.sidx.coverageEnd === size;
-            if (!whole && size >= 4) {
-                if (mfraSize === null)
-                    mfraSize = (await reader.view(size - 4, 4, 0)).getUint32(0);
-                whole = b.sidx.coverageEnd === size - mfraSize;
-            }
-            if (whole && b.sidx.firstOffset === 0)
-                complete = true;
-        }
-        if (foundMoov && foundMdat && (complete || b.end === size)) {
-            movie.ffprobeMoofLimit = moofs;
-            return;
-        }
-    }
-}
-function isVideoTrack(tr, movie) {
-    if (movie.chapterTrackIds.has(tr.id))
-        return false;
-    if (tr.handler === 'vide')
-        return true;
-    if (tr.handler === 'soun')
-        return false;
-    return isVideoFourcc(tr.originalFormat ?? tr.sampleEntry);
-}
-function buildVideoTrack(tr, movie, opts, ctx) {
-    const t = emptyTrack(ctx.reportedId);
-    const w = t.warnings;
-    if (ctx.reportedId !== tr.id)
-        w.push(`duplicate track_ID ${tr.id}: reported as ${ctx.reportedId}`);
-    w.push(...tr.warnings);
-    const auxiliary = tr.handler === 'auxv';
-    if (auxiliary)
-        w.push("auxiliary video track (handler 'auxv')");
-    const broken = missingMandatoryAtoms(tr);
-    if (broken)
-        w.push('missing mandatory sample tables: ffprobe ignores the samples and timing of this track');
-    const ts = tr.hasMdhd ? tr.timescale : movie.timescale;
-    if (!tr.hasMdhd) {
-        w.push('no mdhd: using the movie timescale');
-        tr.timescale = ts;
-    }
-    t.fourccOrCodecId = tr.sampleEntry;
-    t.codecName = codecNameFor(tr.originalFormat ?? tr.sampleEntry, tr.esdsObjectType, tr.hasHvcc);
-    if (tr.originalFormat)
-        w.push(`encrypted: ${tr.sampleEntry} of ${tr.originalFormat}`);
-    if (tr.stsdCount > 1)
-        w.push(`${tr.stsdCount} sample descriptions, first used`);
-    t.width = tr.width;
-    t.height = tr.height;
-    t.rotation = displayRotation(tr.matrix, movie.matrix);
-    t.timescale = ts;
-    const totals = sampleTotals(tr);
-    const truncated = movie.truncated;
-    let presentFragments = 0;
-    for (const f of tr.fragments)
-        presentFragments += f.present;
-    const total = totals.moovSamples + totals.fragmentSamples;
-    const frames = totals.moovSamples + presentFragments;
-    t.frames = frames;
-    t.isStill = frames <= 1;
-    if (totals.moovSamples > 0 && tr.fragments.length > 0) {
-        w.push(`hybrid fragmented file: moov holds ${totals.moovSamples} of ${total} samples`);
-    }
-    if (frames < total)
-        w.push(`truncated: ${total - frames} of ${total} samples missing`);
-    const rates = averageRates(tr, movie);
-    t.avgFps = rates.avg;
-    t.avgFpsFfprobe = ctx.ffprobeFails ? null : rates.ffprobe;
-    if (t.avgFpsFfprobe !== null && t.avgFpsFfprobe !== toFfprobeString(rates.avg)) {
-        w.push(`ffprobe reads part of the fragments: avg_frame_rate ${t.avgFpsFfprobe}`);
-    }
-    if (rates.ffprobe === null && !ctx.ffprobeFails && total > 0)
-        w.push('avg_frame_rate of ffprobe is not reproduced: its header values are incomplete or overrun a box');
-    const r = ctx.ffprobeFails || broken ? null : ffprobeStage1Rate(tr, movie, totals.moovSamples, opts.maxExpandedSamples, w);
-    t.rFpsFfprobe = r ? toFfprobeString(r) : null;
-    const edits = editInfo(tr, movie.timescale, totals);
-    if (!broken) {
-        const timing = trackTiming(tr, movie, totals, edits);
-        t.durationSec = timing.durationTs / ts;
-        t.startSec = timing.startPts === null ? null : timing.startPts / ts;
-    }
-    let moovKeep = totals.moovSamples;
-    if (tr.sampleCount !== null && tr.sampleCount < moovKeep) {
-        w.push(`stts describes ${moovKeep} samples but the sample size table holds ${tr.sampleCount}`);
-        moovKeep = tr.sampleCount;
-    }
-    if (broken) {
-        t.presentedFrames = 0;
-        finishProvenance(t);
-        return { result: t, enabled: tr.enabled, auxiliary };
-    }
-    if (truncated && moovKeep > 0) {
-        const inFile = moovSamplesInFile(tr, movie.fileSize, totals.moovSamples);
-        if (inFile && inFile.complete < moovKeep) {
-            w.push(`truncated: ${inFile.complete} of ${moovKeep} samples complete`);
-            moovKeep = inFile.complete;
-        }
-    }
-    let window = presentationWindow(tr, edits, w);
-    if (window && !tr.cttsCounts && !tr.fragments.length && window.start <= 0 && (window.end <= window.start || window.end >= totals.moovDuration))
-        window = null;
-    const stats = analyzeTimeline({
-        segments: timelineSegments(tr, moovKeep),
-        timescale: ts,
-        editWindow: window,
-        maxExpandedSamples: opts.maxExpandedSamples,
-    });
-    w.push(...stats.warnings);
-    t.presentedFrames = stats.presentedFrames;
-    t.minFps = stats.minFps;
-    t.maxFps = stats.maxFps;
-    t.isVfr = stats.isVfr;
-    t.vfrRatio = stats.vfrRatio;
-    t.distinctDeltas = stats.distinctDeltas;
-    t.duplicateTimestamps = stats.duplicateTimestamps;
-    t.nominalFps = stats.nominalFps;
-    t.dominantFps = stats.dominantFps;
-    t.timestampsQuantized = stats.timestampsQuantized;
-    if (stats.presentedAvgFps)
-        t.avgFps = stats.presentedAvgFps;
-    if (t.duplicateTimestamps > 0)
-        w.push(`${t.duplicateTimestamps} duplicate timestamps`);
-    finishProvenance(t);
-    if (stats.presentedAvgFps)
-        t.provenance.avgFps = 'exact';
-    return { result: t, enabled: tr.enabled, auxiliary, profile: stats.profile };
-}
-function finishProvenance(t) {
-    const p = t.provenance;
-    for (const k of ['codec', 'dimensions', 'rotation', 'frames', 'avgFps'])
-        p[k] = 'header';
-    if (t.durationSec !== null)
-        p.durationSec = 'header';
-    if (t.startSec !== null)
-        p.startSec = 'header';
-    if (t.presentedFrames !== null)
-        p.presentedFrames = 'exact';
-    if (t.isVfr !== null) {
-        p.minFps = 'exact';
-        p.maxFps = 'exact';
-        p.isVfr = 'exact';
-        p.duplicateTimestamps = 'exact';
-    }
-    if (t.nominalFps)
-        p.nominalFps = 'exact';
-    if (t.dominantFps)
-        p.dominantFps = 'exact';
-}
-function pickPrimary(built) {
-    let best = null;
-    const score = (b) => ((b.result.frames ?? 0) > 1 ? (b.auxiliary ? 0.5 : b.enabled ? 2 : 1) : 0);
-    for (const b of built) {
-        if (!best || score(b) > score(best) || (score(b) === score(best) && (b.result.frames ?? 0) > (best.result.frames ?? 0)))
-            best = b;
-    }
-    return best ? best.result.trackId : null;
-}
-const DEFAULT_STREAM_TIMEBASE = 90000;
-function formatDuration(movie, videoTracks) {
-    const NONE = Number.MAX_SAFE_INTEGER;
-    let start = NONE;
-    let startText = NONE;
-    let end = -NONE;
-    let endText = -NONE;
-    let dur = -NONE;
-    let durText = -NONE;
-    for (const tr of movie.tracks) {
-        if (!tr.hasMdhd)
-            continue;
-        const main = videoTracks.has(tr) || tr.handler === 'soun';
-        if (missingMandatoryAtoms(tr)) {
-            const d = rescaleRound(tr.mdhdDuration, 1e6, DEFAULT_STREAM_TIMEBASE);
-            if (main)
-                dur = Math.max(dur, d);
-            else
-                durText = Math.max(durText, d);
-            continue;
-        }
-        const totals = sampleTotals(tr);
-        const timing = trackTiming(tr, movie, totals, editInfo(tr, movie.timescale, totals));
-        const d = rescaleRound(timing.durationTs, 1e6, tr.timescale);
-        if (timing.startPts !== null) {
-            const s = rescaleRound(timing.startPts, 1e6, tr.timescale);
-            if (main) {
-                start = Math.min(start, s);
-                end = Math.max(end, s + d);
-            }
-            else {
-                startText = Math.min(startText, s);
-                endText = Math.max(endText, s + d);
-            }
-        }
-        if (main)
-            dur = Math.max(dur, d);
-        else
-            durText = Math.max(durText, d);
-    }
-    if (start === NONE || (start > startText && start - startText < 1e6))
-        start = startText;
-    if (end === -NONE || (end < endText && endText - end < 1e6))
-        end = endText;
-    if (dur === -NONE || (dur < durText && durText - dur < 1e6))
-        dur = durText;
-    if (start !== NONE && end !== -NONE && end >= start)
-        dur = Math.max(dur, end - start);
-    return dur > 0 ? dur / 1e6 : null;
-}
-function reportedIds(tracks) {
-    const out = new Map();
-    const seen = new Set();
-    let next = tracks.reduce((m, t) => Math.max(m, t.id), 0) + 1;
-    for (const t of tracks) {
-        if (seen.has(t.id))
-            out.set(t, next++);
-        else {
-            seen.add(t.id);
-            out.set(t, t.id);
-        }
-    }
-    return out;
-}
+export { MOOF_HARD_CAP, MOOV_HARD_CAP, MOOV_SUSPECT_CAP } from "./build.js";
 export async function analyzeIsoBmffDetailed(reader, opts) {
     const movie = newMovie(reader.size);
     const fail = (e) => {
         if (isAbort(e, reader))
             throw e;
         const message = e instanceof Error ? e.message : String(e);
-        const analysis = emptyAnalysis(containerOf(movie), e instanceof IsoBmffError || message.startsWith(`file read failed`) ? message : `corrupt file: ${message}`);
+        const analysis = emptyAnalysis(containerOf(movie), e?.errorCode ? message : `corrupt file: ${message}`);
+        analysis.errorCode = whichErrorCode(e);
+        analysis.layout = layoutOf(movie);
         analysis.brand = movie.brand;
         analysis.warnings = movie.warnings;
         return { analysis, movie };
@@ -406,13 +33,14 @@ export async function analyzeIsoBmffDetailed(reader, opts) {
         if ([...ids].some(([t, id]) => t.id !== id))
             movie.warnings.push('duplicate track_ID values');
         const videos = movie.tracks.filter((t) => isVideoTrack(t, movie));
-        const built = videos.map((t) => buildVideoTrack(t, movie, opts, { reportedId: ids.get(t) ?? t.id, ffprobeFails }));
+        const built = videos.map((t) => buildVideoTrack(t, movie, opts, { reportedId: ids.get(t) ?? t.id, ffprobeFails }, analyzeTimeline));
         for (const b of built)
             b.result.rateProfile = await rateProfileOf(b.profile ?? null);
         analysis.videoTracks = built.map((b) => b.result);
         analysis.audioTrackCount = movie.tracks.filter((t) => t.handler === 'soun').length;
         analysis.primaryTrackId = pickPrimary(built);
         analysis.formatDurationSec = formatDuration(movie, new Set(videos));
+        analysis.layout = layoutOf(movie);
         return { analysis, movie };
     }
     catch (e) {

package/dist/core/isobmff/moof.js

@@ -77,7 +77,7 @@ export function parseTrun(dv, p, end, tfhd, dataStartDefault, fileSize, warnings
     const overrun = record > 0 && count < declared;
     const hasDuration = (flags & TRUN_SAMPLE_DURATION) !== 0;
     if (!hasDuration && tfhd.defaultDuration === null && count > 0) {
-        throw new IsoBmffError(`corrupt file: no sample duration for track ${tfhd.trackId}`);
+        throw new IsoBmffError('corrupt', `corrupt file: no sample duration for track ${tfhd.trackId}`);
     }
     const defaultDuration = tfhd.defaultDuration ?? 0;
     const durations = hasDuration ? new Uint32Array(count) : null;
@@ -196,7 +196,7 @@ export function parseSidx(dv, box, fileStart) {
     const p = box.start + box.headerSize;
     const v1 = p < box.end && dv.getUint8(p) === 1;
     if (p + (v1 ? 32 : 24) > box.end)
-        throw new IsoBmffError(`corrupt file: box 'sidx' at ${fileStart} is truncated`);
+        throw new IsoBmffError('corrupt', `corrupt file: box 'sidx' at ${fileStart} is truncated`);
     let o = p + 12;
     const earliestPts = v1 ? boxU64(dv, o, 'sidx', fileStart) : dv.getUint32(o);
     const firstOffset = v1 ? boxU64(dv, o + 8, 'sidx', fileStart) : dv.getUint32(o + 4);

package/dist/core/isobmff/moov.js

@@ -10,7 +10,7 @@ function* guard(gen, ctx, parent) {
     for (const c of gen) {
         if (c.truncated) {
             if (ctx.strict)
-                throw new IsoBmffError('incomplete file: moov is truncated');
+                throw new IsoBmffError('truncated', 'incomplete file: moov is truncated');
             ctx.warnings.push(`'${c.type}' overruns '${parent}'`);
         }
         yield c;
@@ -207,7 +207,6 @@ function parseStsd(dv, h, tr, ctx) {
     }
 }
 function parseStbl(dv, h, tr, ctx) {
-    tr.dv = dv;
     for (const c of children(dv, h, ctx)) {
         const p = payload(c);
         switch (c.type) {
@@ -281,6 +280,7 @@ function parseMdia(dv, h, tr, ctx) {
 }
 function parseTrak(dv, h, movie, ctx) {
     const tr = newTrack();
+    tr.dv = dv;
     for (const c of children(dv, h, ctx)) {
         const p = payload(c);
         if (c.type === 'tkhd' && p + 84 <= c.end) {
@@ -340,7 +340,7 @@ export function parseMoov(dv, h, movie, strict, base = 0) {
                 }
                 break;
             case 'cmov':
-                throw new IsoBmffError('unsupported: compressed movie header (cmov)');
+                throw new IsoBmffError('unsupported', 'unsupported: compressed movie header (cmov)');
         }
     }
 }

package/dist/core/matroska/header.js

@@ -1,10 +1,12 @@
 import { childUint, children, ID_ATTACHED_FILE, ID_ATTACHMENTS, ID_CLUSTER, ID_CODEC_DELAY, ID_CODEC_ID, ID_CODEC_PRIVATE, ID_CONTENT_ENCODINGS, ID_CRC32, ID_CUE_CLUSTER_POSITION, ID_CUE_POINT, ID_CUE_TRACK_POSITIONS, ID_CUES, ID_DEFAULT_DURATION, ID_DOC_TYPE, ID_DURATION, ID_EBML, ID_FILE_MEDIA_TYPE, ID_FRAME_RATE, ID_INFO, ID_PIXEL_HEIGHT, ID_PIXEL_WIDTH, ID_SEEK, ID_SEEK_HEAD, ID_SEEK_ID, ID_SEEK_POSITION, ID_SEGMENT, ID_SIMPLE_TAG, ID_TAG, ID_TAG_NAME, ID_TAG_STRING, ID_TAG_TRACK_UID, ID_TAGS, ID_TARGETS, ID_TIMESTAMP_SCALE, ID_TRACK_ENTRY, ID_TRACK_NUMBER, ID_TRACK_TIMESTAMP_SCALE, ID_TRACK_TYPE, ID_TRACK_UID, ID_TRACKS, ID_VIDEO, ID_VOID, LEVEL1_IDS, readFloat, readString, readUintBig, UNKNOWN_SIZE, vintLength, } from "./ebml.js";
+import { withErrorCode } from "../reader.js";
 import { findLevel1Forward } from "./source.js";
 export const HEADER_MAX_READS = 5;
 export const HEADER_MAX_BYTES = 1024 * 1024;
 export const MAX_DEPTH = 16;
 const SPARSE_CHILD_MAX = 64 * 1024;
 const CODEC_PRIVATE_MAX = 4096;
+const ID_FLAG_ENABLED = 0xb9;
 const SEGMENT_SEARCH_HOPS = 16;
 const SKIPPED_NAMES = new Map([
     [ID_SEEK_HEAD, 'SeekHead'],
@@ -17,7 +19,7 @@ const CHILDREN = new Map([
     [ID_SEEK, [ID_SEEK_ID, ID_SEEK_POSITION]],
     [ID_INFO, [ID_TIMESTAMP_SCALE, ID_DURATION]],
     [ID_TRACKS, [ID_TRACK_ENTRY]],
-    [ID_TRACK_ENTRY, [ID_TRACK_NUMBER, ID_TRACK_UID, ID_TRACK_TYPE, ID_CODEC_ID, ID_CODEC_PRIVATE, ID_CONTENT_ENCODINGS, ID_DEFAULT_DURATION, ID_TRACK_TIMESTAMP_SCALE, ID_CODEC_DELAY, ID_VIDEO]],
+    [ID_TRACK_ENTRY, [ID_TRACK_NUMBER, ID_TRACK_UID, ID_TRACK_TYPE, ID_FLAG_ENABLED, ID_CODEC_ID, ID_CODEC_PRIVATE, ID_CONTENT_ENCODINGS, ID_DEFAULT_DURATION, ID_TRACK_TIMESTAMP_SCALE, ID_CODEC_DELAY, ID_VIDEO]],
     [ID_VIDEO, [ID_PIXEL_WIDTH, ID_PIXEL_HEIGHT, ID_FRAME_RATE]],
     [ID_TAGS, [ID_TAG]],
     [ID_TAG, [ID_TARGETS, ID_SIMPLE_TAG]],
@@ -74,6 +76,7 @@ export function parseMaster(h, b, start, end, parent, cues = null, entry = null)
             switch (c.id) {
                 case ID_TRACK_ENTRY:
                     t = newTrack();
+                    t.entry = b.slice(p, p + n);
                     nest();
                     finishTrack(h, t);
                     break;
@@ -111,6 +114,9 @@ export function parseMaster(h, b, start, end, parent, cues = null, entry = null)
                 case ID_TRACK_TYPE:
                     t.type = uint();
                     break;
+                case ID_FLAG_ENABLED:
+                    t.disabled = !uint();
+                    break;
                 case ID_CODEC_ID:
                     t.codecId = readString(b, p, n);
                     break;
@@ -294,7 +300,7 @@ export async function readMatroskaHeader(src) {
     };
     const ebml = await src.header(0);
     if (!ebml || ebml.id !== ID_EBML || ebml.size === UNKNOWN_SIZE || ebml.dataStart + ebml.size > src.size)
-        throw new Error('invalid EBML header');
+        throw withErrorCode('corrupt', 'invalid EBML header');
     await src.load(ebml.dataStart, Math.min(ebml.size, 4096));
     const s0 = ebml.dataStart - src.base;
     for (const c of children(src.buf, s0, s0 + ebml.size))
@@ -305,7 +311,7 @@ export async function readMatroskaHeader(src) {
     if (!seg) {
         const q = await findLevel1Forward(src, ebml.dataStart + ebml.size, src.size, src.size, { canLoad });
         if (q < 0)
-            throw new Error('no Segment element');
+            throw withErrorCode('no-header', 'no Segment element');
         h.warnings.push(`no valid Segment header: reading level-1 elements from ${q}`);
         h.segmentExtended = true;
         seg = { id: ID_SEGMENT, pos: q, size: UNKNOWN_SIZE, dataStart: q };
@@ -375,6 +381,6 @@ export async function readMatroskaHeader(src) {
     if (!seen.ids.has(ID_INFO))
         h.warnings.push('no Info element: TimestampScale 1000000 assumed');
     if (!h.tracks.length)
-        throw new Error(seen.ids.has(ID_TRACKS) ? 'no complete TrackEntry in Tracks' : 'no Tracks element found');
+        throw seen.ids.has(ID_TRACKS) ? withErrorCode('truncated', 'no complete TrackEntry in Tracks') : withErrorCode('no-header', 'no Tracks element found');
     return h;
 }

package/dist/core/matroska/index.js

@@ -44,7 +44,7 @@ export function declaredRate(defaultDuration) {
 }
 export function mergeRunStats(timescale, runs) {
     const hist = new Map();
-    const out = { minFps: null, maxFps: null, isVfr: null, vfrRatio: 0, distinctDeltas: 0, duplicateTimestamps: 0, timestampsQuantized: false, medianDelta: null };
+    const out = { minFps: null, maxFps: null, isVfr: null, vfrRatio: 0, distinctDeltas: 0, duplicateTimestamps: 0, timestampsQuantized: false, medianDelta: null, medianFrameInterval: null };
     let total = 0;
     for (const r of runs) {
         out.duplicateTimestamps += r.duplicateTimestamps;
@@ -65,6 +65,8 @@ export function mergeRunStats(timescale, runs) {
         if (Math.abs(k - median) > tol)
             off += hist.get(k) ?? 0;
     out.medianDelta = median;
+    const rate = rateFromTicks(timescale, median);
+    out.medianFrameInterval = rate && { num: rate.den, den: rate.num, value: rate.den / rate.num };
     out.minFps = rateFromTicks(timescale, keys[keys.length - 1]);
     out.maxFps = rateFromTicks(timescale, keys[0]);
     out.isVfr = total >= 2 && off > 0;
@@ -80,15 +82,19 @@ function fillRates(r, s, prov) {
     r.distinctDeltas = s.distinctDeltas;
     r.duplicateTimestamps = s.duplicateTimestamps;
     r.timestampsQuantized = s.timestampsQuantized;
-    for (const f of ['minFps', 'maxFps', 'isVfr', 'duplicateTimestamps'])
+    r.medianFrameInterval = s.medianFrameInterval;
+    for (const f of ['minFps', 'maxFps', 'isVfr', 'duplicateTimestamps', 'medianFrameInterval'])
         r.provenance[f] = prov;
 }
-function headerTrack(h, t) {
+function headerTrack(h, t, opts) {
     const r = emptyTrack(t.number);
+    if (opts.codecConfig)
+        r.codecConfig = { family: 'matroska', trackEntry: t.entry ?? null };
     r.fourccOrCodecId = t.codecId;
     r.codecName = codecNameOf(t.codecId);
     r.width = t.width;
     r.height = t.height;
+    r.enabled = !t.disabled;
     r.timescale = 1e9 / (Math.trunc(h.timestampScale * t.trackTimestampScale) || h.timestampScale);
     r.provenance.codec = r.provenance.dimensions = 'header';
     const d = declaredRate(t.defaultDuration);
@@ -260,7 +266,7 @@ function pickEvenly(list, k) {
     return [...new Set(Array.from({ length: k }, (_, i) => list[Math.round((i * (list.length - 1)) / (k - 1))]))];
 }
 async function tailScan(src, h, video, first, opts) {
-    let size = Math.max(opts.readAhead.tail, 4096);
+    let size = Math.max(opts.readAhead.tail || 0, 4096);
     let hi = h.segmentEnd;
     let maxAnyTicks = -Infinity;
     for (;;) {
@@ -393,7 +399,7 @@ export async function analyzeMatroska(reader, opts) {
         return a;
     }
     a.primaryTrackId = video[0].number;
-    a.videoTracks = video.map((t) => headerTrack(h, t));
+    a.videoTracks = video.map((t) => headerTrack(h, t, opts));
     let mode = opts.matroskaMode;
     let first = null;
     if (mode !== 'header') {

package/dist/core/options.js

@@ -24,6 +24,7 @@ function mergeDefined(base, patch) {
 }
 export function resolveOptions(opts = {}) {
     return {
+        ...opts,
         signal: opts.signal ?? null,
         matroskaMode: opts.matroskaMode ?? 'auto',
         exactBudgetMs: opts.exactBudgetMs ?? DEFAULT_EXACT_BUDGET_MS,

package/dist/core/reader.d.ts

@@ -1,3 +1,4 @@
+import type { FileErrorCode } from './types.js';
 export interface BlobSlice {
     arrayBuffer(): Promise<ArrayBuffer>;
 }
@@ -42,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,9 +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;
-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))
@@ -22,13 +22,13 @@ export class BlobReader {
     #reads = 0;
     #unique = 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;
@@ -54,12 +54,12 @@ export class BlobReader {
         }
         catch (e) {
             this.checkAbort();
-            throw e?.name === 'AbortError' ? e : Error(`file read failed: ${e}`);
+            throw e?.name === 'AbortError' ? e : withErrorCode('read-failed', `file read failed: ${e}`);
         }
         this.checkAbort();
         this.#reads++;
         if (ab.byteLength !== end - offset) {
-            throw Error(`file read failed: 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);
@@ -98,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);
@@ -198,3 +198,9 @@ export function ascii(dv, p, length) {
 export function fourcc(dv, p) {
     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);
+}