video-fps-probe 0.0.0-stage → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,130 @@
+# 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.3.0 - 2026-10-30
+
+### Added
+
+- `byContainer` on a custom worker: `{ create, engines, byContainer: { matroska: () => new Worker(...) } }` runs own on the worker of the file's container family, and every other engine and family on `create` ([api](docs/api.md#createprobeclient-client-flavor)).
+- `video-fps-probe/standalone/own-isobmff.worker.js` and `own-matroska.worker.js`: the two own workers as classic scripts with no imports, about 21.1 and 23.7 KB gzip, for `byContainer`. The combined `own.worker.js` stays.
+- `video-fps-probe/presets/sources.json`: the source page of every preset, keyed by the name of its export, such as `sources.klingO1ReferenceVideo` ([presets](docs/api.md#presets)).
+- CommonJS is tested from the packed tarball: `require()` on Node 22.12 and 24, a TypeScript `commonjs` and `node10` project as in NestJS 11, and Jest 30 with babel-jest ([Jest](docs/api.md#jest)).
+- Issue templates for bugs and feature requests, and GitHub Discussions for questions and for showing how you use the package ([feedback](README.md#feedback)).
+
+### Changed
+
+- **Behaviour change:** own runs on one worker per container family, `own-isobmff.worker` or `own-matroska.worker`, picked by the file's first 4 bytes, so a first file loads only the parser of its family.
+- The first MP4 loads about 22.7 KB gzip (23.6 KB in 0.2.0) and the first WebM or MKV without DefaultDuration 25.5 KB (26.7 KB). With Vite's default worker format they load 24.5 and 27.1 KB instead of 38.9 KB ([size matrix](report/size-matrix.md)).
+- `workers` counts per worker kind, so `workers: 1` can run one MP4 and one WebM at once. `prewarm()` starts the worker of each container family it is given, ISO BMFF by default.
+- A missing own worker file, such as a 404 after a redeploy, rejects only the jobs of its container family with `reason: 'load'`, and the next call retries.
+- Service worker precache lists that name `own.worker` need both new worker files. A custom worker that runs `serveProbeWorker({ own: ownEngine })` from `video-fps-probe/worker-runtime` keeps the 0.2.0 layout.
+- `lazyProbeClient` and `createProbeClient` load the 0.4 KB routing by container family only with `byContainer`, so a custom worker without it loads 23.6 KB for the first MP4 (23.5 KB in 0.2.0).
+- The package is about 569 KB unpacked (442 KB in 0.2.0), mostly the two new standalone files, which a bundler takes only when imported.
+- Still 0 mismatches against ffprobe 8.1.1, now on 130 committed fixtures ([accuracy](docs/benchmarks.md#accuracy-vs-ffprobe)).
+- CI also tests Node 22.12, the lowest supported version. A weekly canary builds with the latest mp4box, mediabunny, Vite and rolldown and fails when an own result changes, an own size budget is exceeded or the build breaks, not when only mp4box or mediabunny code grows.
+
+### Deprecated
+
+- `sourceUrl` of a preset: use `video-fps-probe/presets/sources.json`. Presets keep it until the next major, which leaves the URL strings that supply-chain scanners flag in `sources.json` only.
+
+### Fixed
+
+- A version 1 `mehd` or `elst` holding 0xFFFFFFFFFFFFFFFF, an unknown duration, failed the whole file. `mehd` is now ignored, as ffprobe does, and such an edit lasts to the end of the media, with a warning.
+- A top-level header after the moov that runs past the end of the file, such as the trailer of some phone MOV files, marked the file truncated. Unless it is an `mdat` or a `moof`, it now ends the walk with a warning, and samples past the end are still cut.
+- Warnings could hold raw NUL and other control characters from the file, such as a box type. Every engine now replaces them with `?`.
+- An unreadable file, such as a picked file deleted since (`NotReadableError`), now gives `file read failed: <error>` for every container and engine, not `corrupt file: ...` or the browser's bare message.
+- A `ProbeError` from another copy of the package, such as one from an engine module or a custom probe given to `VideoFpsProvider`, became `worker-failed`. It now keeps its code everywhere ([errors](docs/api.md#errors)).
+- `check` judged the `duration` of a VFR WebM or Matroska track by its measured span, up to one frame shorter than ffprobe's. It now judges `formatDurationSec` when it is within one typical frame interval of the span ([check](docs/api.md#check)).
+
+### Known limitations
+
+- React 18 and 19 only: 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" } }`.
+- Zero-config Vite (iife workers) builds each own worker as one file, so the first MP4 loads about 1.7 KB more than with `worker: { format: 'es' }`.
+- Only Vite 8 and npm are tested in CI ([bundlers](docs/bundlers.md)). Browser floors (Chrome and Edge 94, Firefox 114, Safari 15.4) are derived, not tested.
+- A TypeScript project for Node needs `"DOM"` in `lib` or `skipLibCheck: true`, and Jest needs babel-jest to transform the package ([Jest](docs/api.md#jest)).
+- For a WebM or Matroska duration `check` takes the interval of `dominantFps`, `nominalFps` or `avgFps`, so a recording without a dominant rate uses its average interval, not its median.
+- `check` judges the stored frame size: a `pasp` box or a Matroska DisplayWidth is not applied.
+- The only real recordings in the corpus come from Chromium's MediaRecorder. More in [benchmarks](docs/benchmarks.md#limitations).
+
+### Not yet
+
+- 0.3.x: a bundler matrix in CI: webpack 5, Rspack, Next.js, Angular CLI, SvelteKit, Nuxt, Parcel, Bun and Deno, with pnpm, Yarn PnP and bun installs.
+- 0.4.0: a header-only ISO BMFF mode with byte, read and time limits, machine-readable error codes, a layout field, a Range source for object storage (a fetcher, no SDK), color, HDR and Dolby Vision basics, PAR and display size, a median frame interval for `check` and CommonJS server entries only.
+- 0.5.0: a Node entry (`fromPath`, DOM-free types, a `worker_threads` pool), NestJS validators, a CLI, bitrate, GOP and audio details, cadence detection, Vue, Svelte and Angular adapters, and later MPEG-TS and HLS.
+
+## 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,183 @@
-# 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, Yarn PnP and bun installs join the bundler matrix in 0.3.x). 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 and the own worker of the file's container family, picked by its first 4 bytes, with the parser inside; `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, the version in `.nvmrc`, and on Node 22.12, the lowest supported version: CI runs the unit, fixture and package tests on both. 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`.
+
+CommonJS works on Node 22.12 and newer, which load ES modules from `require()`: `const { analyze } = require('video-fps-probe')`, the subpaths included, and a TypeScript project with `"module": "commonjs"` and `moduleResolution` `node10`, such as a NestJS 11 app. The package test checks both from the packed tarball on Node 22.12 and 24. Jest needs babel-jest to transform the package, with plugins for `import.meta` and `import()`: the tested configuration and a stub for unit tests are in [Jest](docs/api.md#jest).
+
+## 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; the source pages are also in `video-fps-probe/presets/sources.json`, where `sources[name]` replaces the deprecated `sourceUrl` ([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.40 KB with Vite's preload helper). The rest loads lazily, on the first file:
+
+| Host Vite config | Critical path | First MP4 | First MKV | All own paths | Worker files |
+|---|---:|---:|---:|---:|---:|
+| `worker: { format: 'es' }` (recommended) | **0.67 KB** | 22.73 KB | 25.54 KB | 48.61 KB | 2 |
+| none (Vite's default, 'iife') | **0.66 KB** | 24.47 KB | 27.08 KB | 48.27 KB | 2 |
+
+Own runs on one worker per container family, picked by the first four bytes of the file, so a first file loads only the worker of its family. An iife worker cannot split, so without the option each own worker is one file with its lazy parts inlined:
+
+```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.92 KB, mediabunny 54.15 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.20 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.99 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 130 committed fixtures: 2054 field checks, 1976 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 130 committed fixtures, 118 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).
+
+## Roadmap
+
+- **0.3.x**: a bundler matrix in CI: webpack 5, Rspack, Next.js, Angular CLI, SvelteKit, Nuxt, Parcel, Bun and Deno, with pnpm, Yarn PnP and bun installs.
+- **0.4.0**: a header-only ISO BMFF mode with byte, read and time limits, machine-readable error codes and a container layout field, a Range source for S3 and R2 style object storage (a fetcher function, no SDK dependency), minimal color, HDR and Dolby Vision metadata, the pixel aspect ratio and display size, a median frame interval that `check` uses, and a CommonJS build of the server entries only, while the browser entries stay ESM.
+- **0.5.0**: a Node entry (`fromPath`, DOM-free types, a `worker_threads` pool), NestJS validators, a CLI, bitrate, GOP and audio details, cadence detection, framework adapters for Vue, Svelte and Angular, and later MPEG-TS and HLS.
+
+## Feedback
+
+Questions, and how you use the package, go to [GitHub Discussions](https://github.com/vbondarets/video-fps-probe/discussions). For a wrong value or a setup that does not build, open a [bug report](https://github.com/vbondarets/video-fps-probe/issues/new/choose) with the browser or Node version, the container, the Copy JSON output of the demo or the result JSON, and the ffprobe output if you have it. The package and the demo collect no telemetry.
+
+## 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 : options);
+        this.name = 'ProbeError';
+        this.code = code;
+        this.engine = options.engine ?? null;
+    }
+}

package/dist/api/guards.d.ts

@@ -0,0 +1,4 @@
+import type { ProbeError } from './errors.js';
+export declare const isProbeError: (e: unknown) => e is ProbeError;
+export declare function isAbortError(e: unknown): boolean;
+export declare function isTimeoutError(e: unknown): boolean;

package/dist/api/guards.js

@@ -0,0 +1,9 @@
+const field = (e, key) => (typeof e === 'object' && e !== null && key in e ? e[key] : undefined);
+export const isProbeError = (e) => field(e, 'name') === 'ProbeError' && typeof field(e, 'code') === 'string';
+const probeCode = (e, code, otherName) => (isProbeError(e) ? 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;