video-fps-probe 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,79 @@
+# Changelog
+
+Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versions follow semver with the [0.x policy](docs/api.md#versioning).
+
+## Unreleased
+
+## 0.2.0 - 2026-10-25
+
+### Added
+
+- First release on npm: `npm install video-fps-probe`; Yarn, pnpm and bun install the same publish ([Publishing](docs/publishing.md)).
+- `video-fps-probe/react`: `VideoFpsProvider`, `useVideoFps(file)`, `useVideoFpsProbe()` and `usePrewarmVideoFps()` for React 18 and 19. The hook caches results per file, runs one analysis under `StrictMode` and aborts it when its last component unmounts ([React](docs/api.md#react)).
+- `video-fps-probe/check`: `check(result, rules)` judges a result against upload limits before the upload: frame rate, duration, frame size, aspect ratio, pixels, file size, container, codec, audio, VFR and uneven pacing. The rules are plain JSON ([Check](docs/api.md#check)).
+- `check` compares exact rationals, so 23.976 fps is below `min: 24`, and an NTSC decimal such as 29.97 also matches its x/1001 rate. A missing, failed or malformed result is `unknown` where it lacks a value, never an exception, so an upload can fail open; a broken rule throws a `TypeError` naming it.
+- The `check` report has a verdict, one violation per broken rule with a readable message, and a `suggestedFps` to convert to: a clean 1-in-k frame drop when the file is at least 1.5 times the nearest allowed rate (50 fps under `max: 30` gets 25), else the nearest allowed rate (31 fps gets 30).
+- `video-fps-probe/presets`: the published input limits of six video generation APIs as `check` rules, with sources, verified on 2026-10-25: Kling O1 and Motion Control 3.0, Runway Aleph 2.0, Veo 3.1, and Wan 2.6 on fal and Seedance 2.0 on EvoLink, which only warn ([Presets](docs/api.md#presets)).
+- `ProbeError.reason`: `'load'` when code did not load, such as a chunk that is gone after a redeploy ([deploy skew](docs/bundlers.md#deploy-skew)), `'crash'` when it failed after loading. The code stays `worker-failed`.
+- `avgFpsFfprobe` and `rFpsFfprobe` for a WebM or Matroska track without DefaultDuration, such as a MediaRecorder recording: ffprobe's estimate for VP8, VP9, AV1 and Baseline H.264 in the [listed cases](docs/implementation-notes.md#ffprobe-frame-rates-without-defaultduration-020), else null with a warning.
+
+### Changed
+
+- **Behaviour change:** a lazy stub whose probe client fails to load rejects with `ProbeError('worker-failed')`, `reason: 'load'` and the import error as `cause`, instead of the browser's import error. Code that caught that error should test `e.reason === 'load'`.
+- `isAbortError` and `isTimeoutError` check the error's name and code instead of `instanceof`, so they also recognize a `ProbeError` from another copy of the package.
+- A file smaller than 465,536 bytes is read whole in one read, so a small MP4 with its moov at the end takes 1 read instead of 2; that read is at most 1 MiB whatever the cost model.
+- In `auto` mode the exact scan of a Matroska track without DefaultDuration also feeds the ffprobe estimate, so the first Clusters are read once; the track's warning says whether the estimate was reproduced.
+- The mediabunny engine is verified with mediabunny 1.62.1; the peer range stays `^1.62.0`.
+- Sizes (gzip): the first MP4 of the default configuration loads about 23.6 KB (23.3 KB in 0.1.0) and the critical path stays under 0.7 KB. The React entry adds about 1.2 KB, `check` about 3.9 KB and one preset about 0.5 KB, each only when imported ([size matrix](report/size-matrix.md)).
+- Still 0 mismatches against ffprobe 8.1.1, now on 126 committed fixtures: 114 made with ffmpeg and 12 real MediaRecorder recordings from Chromium ([benchmarks](docs/benchmarks.md#accuracy-vs-ffprobe)).
+
+### Fixed
+
+- A worker script that failed to load, such as a 404 after a redeploy, was reported as a crash. It now rejects with `reason: 'load'` and says the app may have been redeployed; when the last worker fails to load, the queued jobs reject once instead of each loading the script again.
+- The mp4box engine ended a fragmented track at the sum of its sample durations. It now follows the tfdt timeline like ffprobe, so a Chrome MediaRecorder fMP4 gets ffprobe's duration (4.524533 s instead of 4.557667 s on `rec_chromium_h264.mp4`).
+
+### Known limitations
+
+- React 18 and 19 only. React is an optional peer, `^18.0.0 || ^19.0.0`: next to another React major npm refuses the install with `ERESOLVE`, unless you pass `--legacy-peer-deps` or add `"overrides": { "video-fps-probe": { "react": "$react" } }` to your `package.json`.
+- Zero-config Vite (iife workers) loads about 39 KB for the first MP4, one worker with both parsers; `worker: { format: 'es' }` makes it about 23.6 KB.
+- Only Vite 8 and npm are tested in CI; other bundlers are documented ([bundlers](docs/bundlers.md)), and Yarn, pnpm and bun are expected to work.
+- Browser floors (Chrome and Edge 94, Firefox 114, Safari 15.4, mp4box.js Safari 16.4) are derived, not tested; CI runs Playwright's Chromium, Firefox and WebKit, and in-thread `analyze()` is tested on Node 24 only.
+- The type declarations name DOM types, so a TypeScript project for Node needs `"DOM"` in `lib` or `skipLibCheck: true`.
+- The corpus has real recordings from Chromium's MediaRecorder only: none from Firefox, Safari, phones, cameras or screen recorders.
+- A regular cadence such as 2:3 pulldown is VFR, but its rate profile reads as Steady.
+- `check` judges the stored frame size: the sample aspect ratio of a `pasp` box or a Matroska DisplayWidth is not applied.
+- `check` takes the duration of a VFR WebM or Matroska track on 1 ms ticks from its measured span, up to one frame shorter than ffprobe's: `vfr_screenrec_ts1000.webm` lasts 5.999 s against 6.000000, so `duration: { min: 6 }` fails it.
+- rVFC needs playback: a visible foreground tab, a playable codec and seconds per file.
+- Files above 2^53 bytes, `cmov` headers and a moov above 256 MiB are rejected as error results.
+- In `auto` mode a large Matroska file gets a sampled probe unless the exact scan is predicted to take at most 150 ms.
+
+### Not yet
+
+- Bundler matrix and peers job (0.3.0): Vite 6, webpack 5, Rspack, Next.js 16 on Turbopack and webpack, a pnpm install and a Yarn PnP install.
+- Demo: no prewarm before the first file.
+
+## 0.1.0 - 2026-10-24
+
+First release; not on npm yet (`"private": true`).
+
+### Added
+
+- Frame rate (an exact rational and ffprobe's `avg_frame_rate`), nominal, minimum and maximum FPS, frame counts, duration, codec, size and rotation per video track, a VFR flag and a rate profile, read from MP4, MOV (fragmented included), WebM and Matroska headers in a module worker, without decoding. Values carry provenance tags; file problems are `result.error`.
+- Entries: `.` and `./lazy` with the own worker, `./client` and `./client/lazy` for a host worker, the `./mp4box`, `./mediabunny` and `./rvfc` engines, `./worker-runtime` and `./engines/*` for a custom worker, and `./standalone/own.worker.js` ([API](docs/api.md)).
+- `analyze` with `engine` and `fallback`, `tryAnalyze`, `compare` (experimental), `prewarm`, `dispose`, `destroy`, `summarize`, `ProbeError`, the in-thread `analyze` for Node, and worker protocol v1.
+- Chrome and Edge 94, Firefox 114, Safari 15.4 (derived floors); CI runs Chromium, Firefox and WebKit.
+- 0.67 KB gzip on the critical path of a Vite 8.3.5 host; the first MP4 loads 23.26 KB lazily with `worker: { format: 'es' }`.
+- 0 mismatches against ffprobe 8.1.1 on the 111 committed fixtures.
+
+### Known limitations
+
+- Zero-config Vite (iife workers) loads 34.77 KB for the first MP4: the probe client and one 32.11 KB worker file with both parsers.
+- A regular cadence such as 2:3 pulldown is VFR, but its rate profile reads as Steady.
+- rVFC needs playback: a visible foreground tab, a playable codec and seconds per file.
+- Files above 2^53 bytes, `cmov` headers and a moov above 256 MiB are rejected as error results.
+- In `auto` mode a large Matroska file gets a sampled probe unless the exact scan is predicted to take at most 150 ms.
+- Only Vite 8 is verified; the other bundlers are documented, not tested ([bundlers](docs/bundlers.md)).
+
+### Not yet
+
+- React entry (0.2.0), bundler matrix and peers job (0.3.0), npm publishing (1.0.0).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Volodymyr Bondarets
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,171 @@
-# Temporary Holding Version
+# video-fps-probe
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Frame rate, frame count, VFR detection and a rate profile for MP4, MOV, WebM and MKV files, read from the container headers in a Web Worker. Nothing is decoded and nothing leaves the browser, and the values match ffprobe 8.1.1 on the test corpus (0 mismatches). ESM only, no runtime dependencies, types included.
+
+**[Live demo](https://vbondarets.github.io/video-fps-probe/)** · [API](docs/api.md) · [Bundlers](docs/bundlers.md) · [Benchmarks](docs/benchmarks.md) · [Architecture](docs/architecture.md) · [Changelog](CHANGELOG.md)
+
+## Install
+
+```
+npm install video-fps-probe
+yarn add video-fps-probe   # Yarn classic and berry
+pnpm add video-fps-probe
+bun add video-fps-probe
+```
+
+The first npm release is 0.2.0; one publish serves every package manager ([publishing](docs/publishing.md)). npm is the tested package manager: CI installs the packed tarball with npm. Yarn, pnpm and bun are expected to work but are not tested in CI yet (pnpm and Yarn PnP join the matrix in 0.3.0). The package has no dependencies. Its peers are optional and no package manager installs them for you: install one yourself, only for the entry you import: `mp4box` for `video-fps-probe/mp4box`, `mediabunny` for `video-fps-probe/mediabunny`, React 18 or 19 for `video-fps-probe/react`.
+
+For a commit that is not released yet, install a packed tarball. A git dependency gets no code with npm (Yarn, pnpm and bun are not tested): `prepack` builds `dist/`, and npm does not run it for a git install.
+
+```
+git clone https://github.com/vbondarets/video-fps-probe.git && cd video-fps-probe
+npm ci && TGZ="$PWD/$(npm pack | tail -n 1)"   # builds and checks dist/, writes the tarball, keeps its path
+cd ../your-app && npm install "$TGZ"
+```
+
+In PowerShell: `$tgz = Join-Path $PWD (npm pack | Select-Object -Last 1)`, then `cd ../your-app; npm install $tgz`.
+
+## Quick start
+
+```ts
+import { lazyProbe } from 'video-fps-probe/lazy';
+
+const probe = lazyProbe(); // a small stub: loads nothing until the first call
+
+const result = await probe.analyze(file); // a broken file is result.error, not a rejection
+const track = result.videoTracks.find((t) => t.trackId === result.primaryTrackId);
+track?.avgFps; // exact rational { num, den, value }
+track?.avgFpsFfprobe; // the avg_frame_rate string of ffprobe, for example '30000/1001'
+track?.presentedFrames; // the frame count
+track?.isVfr;
+track?.rateProfile?.summary; // for example 'Uneven: 5 fps for 4 s, 200 fps for 4 s'
+```
+
+The first call loads the probe client, the worker and the parser of the sniffed container; `probe.prewarm()` loads them ahead, for example when an upload dialog opens. `createProbe()` from `video-fps-probe` is the probe without the stub; `summarize(result)` flattens the primary track.
+
+## React
+
+```tsx
+import { useState } from 'react';
+import { lazyProbe } from 'video-fps-probe/lazy';
+import { VideoFpsProvider, useVideoFps } from 'video-fps-probe/react';
+
+const probe = lazyProbe(); // once, at module scope
+
+export const App = () => (
+  <VideoFpsProvider probe={probe}>
+    <Upload />
+  </VideoFpsProvider>
+);
+
+function Upload() {
+  const [file, setFile] = useState<File | null>(null);
+  const { status, summary } = useVideoFps(file); // 'idle', 'pending', 'success' or 'error'; also result, error, progress, cancel(), retry()
+  return (
+    <>
+      <input type="file" onChange={(e) => setFile(e.currentTarget.files?.[0] ?? null)} />
+      {status === 'success' && <p>{summary?.ok ? `${summary.fps?.toFixed(3)} fps` : summary?.error}</p>}
+    </>
+  );
+}
+```
+
+React 18 and 19. `useVideoFps` caches each result by the file and the options, runs one analysis through the double effects of `StrictMode`, and aborts a pending one when the last component using it unmounts; `usePrewarmVideoFps()` returns a function that prewarms the probe ([details](docs/api.md#react)).
+
+## Engines
+
+Own, the default, needs nothing else. mp4box.js and mediabunny are optional peers for a second opinion or a fallback, and rVFC estimates by playing the file:
+
+```ts
+import { lazyProbe } from 'video-fps-probe/lazy';
+import { mediabunny } from 'video-fps-probe/mediabunny'; // npm install mediabunny
+import { mp4box } from 'video-fps-probe/mp4box'; // npm install mp4box
+
+const probe = lazyProbe({ engines: [mp4box(), mediabunny()] });
+await probe.analyze(file, { engine: 'mediabunny' });
+await probe.analyze(file, { fallback: ['mediabunny'] }); // on an error, no frame rate, a timeout or a crash
+const { outcomes, agreement } = await probe.compare(file); // experimental
+```
+
+`agreement.agree` is `true`, `false`, or `null` when nothing could be compared ([rules](docs/api.md#compare-and-agreement)). rVFC (`video-fps-probe/rvfc`) is never used implicitly and needs a visible host element ([engines](docs/api.md#engines)).
+
+## Node
+
+```ts
+import { openAsBlob } from 'node:fs';
+import { analyze } from 'video-fps-probe';
+
+const result = await analyze(await openAsBlob(path), { name: path }); // in the calling thread, no worker
+```
+
+In-thread `analyze()` is tested on Node 24 only, the version in `.nvmrc` that every CI job uses. The example needs `fs.openAsBlob`, available since Node 19.8 and stable in Node 24. Files above 4 GiB need a `BlobLike` in Node 24 ([in-thread analyze](docs/api.md#in-thread-analyze)). The type declarations name DOM types such as `Worker` and `HTMLElement`, so a TypeScript project for Node needs `"DOM"` in `lib` or `skipLibCheck: true`.
+
+## Cancellation, timeouts and failing open
+
+```ts
+probe.prewarm(); // when the upload dialog opens
+const deadline = new AbortController();
+const late = new Promise<null>((resolve) => setTimeout(() => (deadline.abort(), resolve(null)), 5000));
+const checks = Promise.all(files.map((f) => probe.tryAnalyze(f, { timeoutMs: 3000, signal: deadline.signal })));
+const results = await Promise.race([checks, late]); // null, or null entries: upload without the check
+```
+
+`tryAnalyze` resolves `null` where `analyze` rejects. `timeoutMs` counts per job once a worker takes it and the signal cancels queued and running jobs, but neither covers main-thread chunk downloads: hence `prewarm()` and the race. A probe and a lazy stub reject only with a `ProbeError`; code that did not load, such as a chunk that is gone after a redeploy, has `reason: 'load'`. [Details](docs/api.md#cancellation-and-failing-open).
+
+## Check before upload
+
+```ts
+import { check } from 'video-fps-probe/check';
+import { klingO1ReferenceVideo } from 'video-fps-probe/presets';
+
+const report = check(await probe.tryAnalyze(file, { timeoutMs: 3000 }), klingO1ReferenceVideo.rules);
+if (report.verdict === 'fail') showErrors(report.violations, report.suggestedFps?.reason); // for example 'convert to 24 fps'
+else upload(file); // 'pass', 'warn', or 'unknown': no result, an error or a missing field fails open
+```
+
+Rules are JSON, such as `{ fps: { min: 24, max: 60 }, duration: { max: 10 }, vfr: 'warn' }`, and frame rates compare as exact rationals: 23.976 fps (`24000/1001`) is below a minimum of 24, 59.94 meets a maximum of 60. The presets hold the published input limits of Kling O1 and Motion Control, Runway Aleph 2.0, Veo 3.1, and Wan 2.6 on fal and Seedance 2.0 on EvoLink (gateways, so they only warn), each with its source and the day it was verified ([check](docs/api.md#check), [presets](docs/api.md#presets)).
+
+## Size
+
+<!-- tables:size:start -->
+
+**0.67 KB gzip on the critical path**: the package code in the entry chunk of a Vite 8.3.5 app that imports `video-fps-probe/lazy` (1.39 KB with Vite's preload helper). The rest loads lazily, on the first file:
+
+| Host Vite config | Critical path | First MP4 | All own paths | Worker files |
+|---|---:|---:|---:|---:|
+| `worker: { format: 'es' }` (recommended) | **0.67 KB** | 23.59 KB | 40.76 KB | 1 |
+| none (Vite's default, 'iife') | **0.66 KB** | 38.92 KB | 38.92 KB | 1 |
+
+An iife worker cannot split, so without the option the own worker is one file with both parsers:
+
+```js
+import { defineConfig } from 'vite';
+
+export default defineConfig({ worker: { format: 'es' } });
+```
+
+Engines cost nothing until imported. Importing a descriptor grows the critical path a little, from 0.67 KB to 0.89 KB with mp4box or mediabunny, 0.77 KB with rVFC and 1.01 KB with all three, and the engine itself loads lazily: mp4box 44.86 KB, mediabunny 53.97 KB, rVFC 2.19 KB. Gzip -9 of production builds from the packed tarball, budgeted in CI; every configuration is in [docs/benchmarks.md](docs/benchmarks.md#package-size).
+
+`video-fps-probe/react` adds 1.18 KB to the critical path for the provider, `useVideoFps` and its store (React itself not counted); its first analysis also fetches a 0.43 KB summary module, in parallel with the probe client. `video-fps-probe/check` adds 3.89 KB when imported statically, and nothing lazily; one preset from `video-fps-probe/presets` adds 0.46 KB.
+
+<!-- tables:size:end -->
+
+## Accuracy
+
+<!-- tables:accuracy-summary:start -->
+
+**0 mismatches against ffprobe 8.1.1** on the 126 committed fixtures: 2002 field checks, 1924 exact, 13 within tolerance (9 of them a definition difference by design: the measured average of a Matroska file that stores no duration for its last frame, which avgFps gives the median interval and ffprobe its own estimate), 0 known deviations with a recorded reason, 65 not applicable. The same comparison runs mp4box.js 2.4.1 and mediabunny 1.62.1 in 5 arms (their idiomatic recipes, mediabunny with a full scan, and this package's tuned adapters) and sorts each difference into wrong, definition differs, unverified, not provided or unsupported container; the [accuracy section](docs/benchmarks.md#accuracy-vs-ffprobe) has the outcomes and where the libraries win.
+
+Of the 126 committed fixtures, 114 are synthetic files made with ffmpeg and 12 are real MediaRecorder recordings from headless Chromium, committed as recorded; per-engine tables, speed and method: [docs/benchmarks.md](docs/benchmarks.md).
+
+<!-- tables:accuracy-summary:end -->
+
+## Browser support
+
+Chrome and Edge 94, Firefox 114, Safari and iOS 15.4: floors derived from the features used, not tested on those versions; CI runs Chromium, Firefox and WebKit. mp4box.js needs Safari 16.4; rVFC needs `requestVideoFrameCallback` (Chrome 83, Firefox 132, Safari 15.4), a visible foreground tab and a playable codec. [Details](docs/benchmarks.md#browser-support).
+
+Known limitations: [changelog](CHANGELOG.md#known-limitations), [benchmarks](docs/benchmarks.md#limitations). Development: [demo/README.md](demo/README.md), [scripts](docs/benchmarks.md#reproducing-the-numbers).
+
+## License
+
+[MIT](LICENSE). The optional peers have their own licenses: mediabunny is MPL-2.0, mp4box is BSD-3-Clause.

package/dist/analyze.d.ts

@@ -0,0 +1,9 @@
+import type { ProbeResult } from './client/types.js';
+import type { BlobLike } from './core/reader.js';
+import type { AnalyzeOptions } from './core/types.js';
+import type { EngineDescriptor } from './plugins/types.js';
+export interface InThreadOptions extends AnalyzeOptions {
+    name?: string;
+    engine?: EngineDescriptor;
+}
+export declare function analyze(input: Blob | BlobLike, options?: InThreadOptions): Promise<ProbeResult>;

package/dist/analyze.js

@@ -0,0 +1,5 @@
+export async function analyze(input, options = {}) {
+    const { name = typeof File !== 'undefined' && input instanceof File ? input.name : '', engine, ...opts } = options;
+    const module = engine ? await engine.load() : (await import("./worker/runtime.js")).ownEngine;
+    return module.run(input, name, opts);
+}

package/dist/api/agreement.d.ts

@@ -0,0 +1,18 @@
+import type { EngineId, FileResult, Rational } from '../core/types.js';
+export type ComparedFieldName = 'avgFps' | 'nominalFps' | 'minFps' | 'maxFps' | 'frames' | 'durationSec';
+export type ComparedValue = Rational | number | null;
+export interface ComparedField<K extends EngineId> {
+    field: ComparedFieldName;
+    values: Partial<Record<K, ComparedValue>>;
+    agree: boolean | null;
+    differ: K[];
+}
+export interface Agreement<K extends EngineId> {
+    reference: K | null;
+    engines: K[];
+    fields: ComparedField<K>[];
+    agree: boolean | null;
+}
+export declare const RELATIVE_TOLERANCE = 0.003;
+export declare const DURATION_TOLERANCE_SEC = 0.000001;
+export declare function compareResults<K extends EngineId>(results: Partial<Record<K, FileResult>>, reference?: NoInfer<K>): Agreement<K>;

package/dist/api/agreement.js

@@ -0,0 +1,55 @@
+import { primaryTrack } from "../core/result.js";
+export const RELATIVE_TOLERANCE = 0.003;
+export const DURATION_TOLERANCE_SEC = 1e-6;
+const RATIONALS = ['avgFps', 'nominalFps', 'minFps', 'maxFps'];
+const APPROXIMATE = new Set(['estimated', 'sampled']);
+const sameRational = (a, b) => [a.num, a.den, b.num, b.den].every(Number.isSafeInteger) ? BigInt(a.num) * BigInt(b.den) === BigInt(b.num) * BigInt(a.den) : a.num / a.den === b.num / b.den;
+function valueOf(t, field) {
+    if (field === 'frames')
+        return t.presentedFrames ?? t.frames;
+    if (field === 'durationSec')
+        return t.durationSec;
+    return t[field];
+}
+function equal(field, a, b) {
+    const x = valueOf(a, field);
+    const y = valueOf(b, field);
+    if (typeof x === 'number' && typeof y === 'number')
+        return field === 'durationSec' ? Math.abs(x - y) <= DURATION_TOLERANCE_SEC : x === y;
+    const p = x;
+    const q = y;
+    if (sameRational(p, q))
+        return true;
+    const approximate = APPROXIMATE.has(a.provenance[field]) || APPROXIMATE.has(b.provenance[field]);
+    return approximate && Math.abs(p.value / q.value - 1) <= RELATIVE_TOLERANCE;
+}
+export function compareResults(results, reference) {
+    const tracks = new Map();
+    for (const [engine, result] of Object.entries(results)) {
+        const t = result && !result.error ? primaryTrack(result) : null;
+        if (t)
+            tracks.set(engine, t);
+    }
+    const engines = [...tracks.keys()];
+    const ref = reference !== undefined ? (tracks.has(reference) ? reference : null) : tracks.has('own') ? 'own' : (engines[0] ?? null);
+    const fields = [...RATIONALS, 'frames', 'durationSec'].map((field) => {
+        const values = {};
+        for (const [engine, t] of tracks)
+            values[engine] = valueOf(t, field);
+        const base = ref === null ? null : tracks.get(ref);
+        const differ = [];
+        let compared = 0;
+        if (base && valueOf(base, field) !== null) {
+            for (const [engine, t] of tracks) {
+                if (engine === ref || valueOf(t, field) === null)
+                    continue;
+                compared++;
+                if (!equal(field, base, t))
+                    differ.push(engine);
+            }
+        }
+        return { field, values, agree: compared === 0 ? null : differ.length === 0, differ };
+    });
+    const decided = fields.filter((f) => f.agree !== null);
+    return { reference: ref, engines, fields, agree: decided.length === 0 ? null : decided.every((f) => f.agree) };
+}

package/dist/api/errors.d.ts

@@ -0,0 +1,12 @@
+import type { EngineId } from '../core/types.js';
+export type ProbeErrorCode = 'aborted' | 'timeout' | 'worker-failed' | 'engine-not-registered' | 'unknown-engine' | 'unsupported-environment' | 'protocol';
+export interface ProbeErrorOptions {
+    engine?: EngineId | null;
+    cause?: unknown;
+}
+export declare class ProbeError extends Error {
+    readonly code: ProbeErrorCode;
+    readonly engine: EngineId | null;
+    readonly reason?: 'load' | 'crash';
+    constructor(code: ProbeErrorCode, message: string, options?: ProbeErrorOptions);
+}

package/dist/api/errors.js

@@ -0,0 +1,10 @@
+export class ProbeError extends Error {
+    code;
+    engine;
+    constructor(code, message, options = {}) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = 'ProbeError';
+        this.code = code;
+        this.engine = options.engine ?? null;
+    }
+}

package/dist/api/guards.d.ts

@@ -0,0 +1,2 @@
+export declare function isAbortError(e: unknown): boolean;
+export declare function isTimeoutError(e: unknown): boolean;

package/dist/api/guards.js

@@ -0,0 +1,8 @@
+const field = (e, key) => (typeof e === 'object' && e !== null && key in e ? e[key] : undefined);
+const probeCode = (e, code, otherName) => (field(e, 'name') === 'ProbeError' ? field(e, 'code') === code : field(e, 'name') === otherName);
+export function isAbortError(e) {
+    return probeCode(e, 'aborted', 'AbortError');
+}
+export function isTimeoutError(e) {
+    return probeCode(e, 'timeout', 'TimeoutError');
+}

package/dist/api/summary.d.ts

@@ -0,0 +1,22 @@
+import type { ContainerKind, EngineId, FileResult } from '../core/types.js';
+export interface VideoFpsSummary {
+    ok: boolean;
+    name: string;
+    container: ContainerKind;
+    engine: EngineId;
+    fps: number | null;
+    fpsRational: string | null;
+    nominalFps: number | null;
+    frames: number | null;
+    durationSec: number | null;
+    width: number | null;
+    height: number | null;
+    rotation: number | null;
+    isVfr: boolean | null;
+    minFps: number | null;
+    maxFps: number | null;
+    approximate: boolean;
+    error: string | null;
+    warnings: string[];
+}
+export declare function summarize(r: FileResult): VideoFpsSummary;

package/dist/api/summary.js

@@ -0,0 +1,25 @@
+const APPROXIMATE = new Set(['estimated', 'sampled']);
+export function summarize(r) {
+    const t = r.primaryTrackId === null ? null : (r.videoTracks.find((x) => x.trackId === r.primaryTrackId) ?? null);
+    const error = r.error ?? (!t ? 'no video track' : t.avgFps ? null : 'no frame rate');
+    return {
+        ok: error === null,
+        name: r.name,
+        container: r.container,
+        engine: r.engine,
+        fps: t?.avgFps?.value ?? null,
+        fpsRational: t?.avgFps ? `${t.avgFps.num}/${t.avgFps.den}` : null,
+        nominalFps: t?.nominalFps?.value ?? null,
+        frames: t ? (t.presentedFrames ?? t.frames) : null,
+        durationSec: t?.durationSec ?? r.formatDurationSec,
+        width: t?.width ?? null,
+        height: t?.height ?? null,
+        rotation: t?.rotation ?? null,
+        isVfr: t?.isVfr ?? null,
+        minFps: t?.minFps?.value ?? null,
+        maxFps: t?.maxFps?.value ?? null,
+        approximate: !!t && ['avgFps', 'nominalFps', 'frames'].some((k) => APPROXIMATE.has(t.provenance[k])),
+        error,
+        warnings: [...r.warnings, ...(t?.warnings ?? [])],
+    };
+}

package/dist/check/index.d.ts

@@ -0,0 +1,60 @@
+import type { ContainerKind, FileResult } from '../core/types.js';
+export type RatioValue = number | `${number}/${number}` | `${number}:${number}`;
+export type RatePolicy = 'allow' | 'warn' | 'reject';
+export type FpsSource = 'avg' | 'ffprobe' | 'nominal' | 'dominant';
+export type CheckVerdict = 'pass' | 'warn' | 'fail' | 'unknown';
+export type CheckSeverity = 'fail' | 'warn' | 'unknown';
+export interface RangeRule<T = number> {
+    min?: T;
+    max?: T;
+}
+export interface FpsRule extends RangeRule<RatioValue> {
+    exact?: RatioValue;
+    oneOf?: readonly RatioValue[];
+    source?: FpsSource;
+}
+export interface AspectRatioRule extends RangeRule<RatioValue> {
+    oneOf?: readonly RatioValue[];
+}
+export interface FrameSizeRule {
+    minWidth?: number;
+    maxWidth?: number;
+    minHeight?: number;
+    maxHeight?: number;
+    minShortSide?: number;
+    maxShortSide?: number;
+    minLongSide?: number;
+    maxLongSide?: number;
+}
+export interface CheckRules {
+    fps?: FpsRule;
+    duration?: RangeRule;
+    frameSize?: FrameSizeRule;
+    aspectRatio?: AspectRatioRule;
+    pixels?: RangeRule;
+    fileSize?: RangeRule;
+    containers?: readonly ContainerKind[];
+    codecs?: readonly string[];
+    audio?: 'required' | 'forbidden';
+    vfr?: RatePolicy;
+    uneven?: RatePolicy;
+    severity?: 'fail' | 'warn';
+}
+export type CheckExpected = number | string | readonly (number | string)[] | null;
+export interface CheckViolation {
+    rule: string;
+    severity: CheckSeverity;
+    expected: CheckExpected;
+    actual: number | string | boolean | null;
+    message: string;
+}
+export interface SuggestedFps {
+    value: number | null;
+    reason: string;
+}
+export interface CheckReport {
+    verdict: CheckVerdict;
+    violations: CheckViolation[];
+    suggestedFps?: SuggestedFps;
+}
+export declare function check(result: FileResult | null | undefined, rules: CheckRules): CheckReport;