video-fps-probe 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -4,6 +4,57 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versions follo
 
 ## 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

package/README.md

@@ -13,7 +13,7 @@ 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`.
+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.
 
@@ -41,7 +41,7 @@ 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.
+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
 
@@ -98,7 +98,9 @@ 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`.
+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
 
@@ -123,20 +125,20 @@ if (report.verdict === 'fail') showErrors(report.violations, report.suggestedFps
 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)).
+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.39 KB with Vite's preload helper). The rest loads lazily, on the first file:
+**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 | 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 |
+| 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 |
 
-An iife worker cannot split, so without the option the own worker is one file with both parsers:
+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';
@@ -144,9 +146,9 @@ 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).
+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.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.
+`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 -->
 
@@ -154,9 +156,9 @@ Engines cost nothing until imported. Importing a descriptor grows the critical p
 
 <!-- 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.
+**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 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).
+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 -->
 
@@ -166,6 +168,16 @@ Chrome and Edge 94, Firefox 114, Safari and iOS 15.4: floors derived from the fe
 
 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/api/errors.js

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

package/dist/api/guards.d.ts

@@ -1,2 +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

@@ -1,5 +1,6 @@
 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 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');
 }

package/dist/check/index.js

@@ -70,6 +70,7 @@ const fromRational = (r) => (r && whole(r.num) && whole(r.den) ? [BigInt(r.num),
 const gcd = (a, b) => (b === 0n ? a : gcd(b, a % b));
 const value = (q) => Number(q[0]) / Number(q[1]);
 const round = (x) => +x.toFixed(3);
+const micros = (q) => (q[0] * 2000000n + q[1]) / (2n * q[1]);
 function digits(q, against) {
     let d = 3;
     while (d < 12 && against.some((b) => value(b).toFixed(d) === value(q).toFixed(d)))
@@ -97,6 +98,15 @@ function resolution(t, cfr) {
         return undefined;
     return cfr ? (x) => close(1n, cfr[0], x, 1n, NOMINAL_SLACK_PER_S) : (x) => close(BigInt(frames), avg, x, SPAN_SLACK_MS, 1000n);
 }
+function printedDuration(t, result) {
+    const span = t.durationSec;
+    const format = result.formatDurationSec;
+    const typical = fromRational(t.dominantFps?.rate ?? (t.isVfr === false ? t.nominalFps : null) ?? t.avgFps);
+    const matroska = result.container === 'webm' || result.container === 'matroska';
+    const [a, b] = [span, format].map((x) => (typeof x === 'number' ? decimal(String(x)) : null));
+    const gap = a && b && abs(micros(a) - micros(b));
+    return matroska && typical && gap != null && gap * typical[0] <= 1000000n * typical[1] ? format : (span ?? format);
+}
 function judgedFps(t, source, cfr) {
     const m = /^(\d+)\/(\d+)$/.exec(t.avgFpsFfprobe ?? '');
     if (source === 'ffprobe')
@@ -218,8 +228,8 @@ export function check(result, rules) {
     const fps = t && judgedFps(t, rules.fps?.source, cfr);
     const near = t && (rules.fps?.source ?? 'avg') === 'avg' ? resolution(t, cfr) : undefined;
     limits('fps', rules.fps, fps, fps ? fraction(fps) : '', (against) => fpsText(fps, against), ' fps', `${rules.fps?.source ?? 'avg'} frame rate`, '', near);
-    const exact = cfr?.[1] ?? quantity(t && (t.durationSec ?? result.formatDurationSec));
-    const span = exact && [(exact[0] * 2000000n + exact[1]) / (2n * exact[1]), 1000000n];
+    const exact = cfr?.[1] ?? quantity(t && printedDuration(t, result));
+    const span = exact && [micros(exact), 1000000n];
     const seconds = span ? value(span) : 0;
     limits('duration', rules.duration, span, seconds, (against) => `${digits(span, against)}`, ' s', 'duration');
     const size = t ? (Math.abs(t.rotation) % 180 === 90 ? [t.height, t.width] : [t.width, t.height]) : [0, 0];

package/dist/client/compare.js

@@ -1,6 +1,6 @@
 import { compareResults } from "../api/agreement.js";
 import { ProbeError } from "../api/errors.js";
-import { isAbortError } from "../api/guards.js";
+import { isAbortError, isProbeError } from "../api/guards.js";
 import { failureOf } from "./fallback.js";
 import { nameOf } from "./probe.js";
 export async function compare(ctx, file, o = {}) {
@@ -25,7 +25,7 @@ export async function compare(ctx, file, o = {}) {
         catch (e) {
             if (isAbortError(e))
                 throw e;
-            const error = e instanceof ProbeError ? e : Object.assign(new ProbeError('worker-failed', String(e), { engine: id, cause: e }), { reason: 'crash' });
+            const error = isProbeError(e) ? e : Object.assign(new ProbeError('worker-failed', String(e), { engine: id, cause: e }), { reason: 'crash' });
             if (error.code === 'unsupported-environment')
                 return { status: 'skipped', reason: 'unsupported-environment' };
             return { status: error.code === 'timeout' ? 'timeout' : 'crashed', error };

package/dist/client/create.d.ts

@@ -0,0 +1,3 @@
+import type { EngineDescriptor, WorkerEngineId } from '../plugins/types.js';
+import type { ClientOptions, IdOf, Probe } from './types.js';
+export declare function createProbeClient<const E extends readonly EngineDescriptor[] = [], const W extends WorkerEngineId = never>(options: ClientOptions<E, W>): Probe<W | IdOf<E[number]> | 'own'>;

package/dist/client/create.js

@@ -0,0 +1,8 @@
+import { createProbeCore } from "./probe.js";
+import { splitBy } from "./split.js";
+const splitOnFirstRun = splitBy((pool, lazy, life) => ({
+    run: (request, options) => lazy(import("./route.js"), request.engine).then((m) => m.runByHead(pool, lazy, life).run(request, options)),
+}));
+export function createProbeClient(options) {
+    return createProbeCore({ ...options, split: splitOnFirstRun });
+}

package/dist/client/fallback.js

@@ -1,5 +1,5 @@
 import { ProbeError } from "../api/errors.js";
-import { isAbortError } from "../api/guards.js";
+import { isAbortError, isProbeError } from "../api/guards.js";
 import { emptyAnalysis, primaryTrack } from "../core/result.js";
 export const failureOf = (r) => {
     const t = primaryTrack(r);
@@ -25,7 +25,7 @@ export async function runChain(run, chain, file, name, wire, call, first) {
         catch (e) {
             if (isAbortError(e))
                 throw e;
-            last = e instanceof ProbeError ? e : Object.assign(new ProbeError('worker-failed', String(e), { engine: id, cause: e }), { reason: 'crash' });
+            last = isProbeError(e) ? e : Object.assign(new ProbeError('worker-failed', String(e), { engine: id, cause: e }), { reason: 'crash' });
             failures.push({ engine: id, error: last.message });
             continue;
         }

package/dist/client/index.d.ts

@@ -7,5 +7,5 @@ export type * from '../core/types.js';
 export type { MediabunnyNative, MediabunnyTrackNative, Mp4boxNative, Mp4boxTrackNative, RvfcConfidence, RvfcDetails, RvfcPass } from '../engines/types.js';
 export type { ContainerFamily, EngineDescriptor, EngineModule, WorkerEngineId } from '../plugins/types.js';
 export type { WireOptions } from '../worker/protocol.js';
-export { createProbeClient } from './probe.js';
+export { createProbeClient } from './create.js';
 export type * from './types.js';

package/dist/client/index.js

@@ -2,4 +2,4 @@ export { compareResults } from "../api/agreement.js";
 export { ProbeError } from "../api/errors.js";
 export { isAbortError, isTimeoutError } from "../api/guards.js";
 export { summarize } from "../api/summary.js";
-export { createProbeClient } from "./probe.js";
+export { createProbeClient } from "./create.js";

package/dist/client/inline.js

@@ -38,6 +38,6 @@ export function runInline(load, file, name, options, run) {
             }
             const opts = { ...options, signal: controller.signal, onProgress, host };
             return { type: 'result', result: await module.run(file, name, opts) };
-        })().then((reply) => finish(() => resolve(reply)), (e) => (e instanceof ProbeError ? finish(() => reject(e)) : fail(Object.assign(new ProbeError('worker-failed', e instanceof Error ? e.message || e.name : String(e), { engine, cause: e }), { reason: loading ? 'load' : 'crash' }))));
+        })().then((reply) => finish(() => resolve(reply)), (e) => (e?.name === 'ProbeError' && typeof e.code === 'string' ? finish(() => reject(e)) : fail(Object.assign(new ProbeError('worker-failed', e instanceof Error ? e.message || e.name : String(e), { engine, cause: e }), { reason: loading ? 'load' : 'crash' }))));
     });
 }

package/dist/client/lazy.js

@@ -3,5 +3,5 @@ export function lazyProbeFrom(factory) {
     return lazyStub(factory, []);
 }
 export function lazyProbeClient(options) {
-    return lazyStub(() => import("./probe.js").then((m) => m.createProbeClient(options)), knownEngines(options.worker, options.engines));
+    return lazyStub(() => import("./probe-client.js").then((m) => m.loadProbeClient(options)), knownEngines(options.worker, options.engines));
 }

package/dist/client/probe-client.js

@@ -0,0 +1,4 @@
+import { createProbeCore } from "./probe.js";
+export const loadProbeClient = (options) => options.worker?.byContainer
+    ? import("./route.js").then((m) => createProbeCore({ ...options, split: m.splitRoute }))
+    : createProbeCore(options);

package/dist/client/probe.js

@@ -2,10 +2,11 @@ import { ProbeError } from "../api/errors.js";
 import { WorkerPool, workerFailed } from "./pool.js";
 const notRegistered = (id, message = `engine ${id} is not registered`) => new ProbeError('engine-not-registered', message, { engine: id });
 export const nameOf = (file) => (typeof File !== 'undefined' && file instanceof File ? file.name : '');
-const loadOwnInThread = async () => (await import("../worker/runtime.js")).ownEngine;
+const loadOwnInThread = () => import("../worker/runtime.js").then((m) => m.ownEngine);
 export function createProbeCore(options) {
-    const { worker, engines: descriptors = [], engine: defaultEngine = 'own', fallback: defaultFallback = [], workers, idleTimeoutMs, timeoutMs: defaultTimeout, defaults } = options;
+    const { worker, engines: descriptors = [], engine: defaultEngine = 'own', fallback: defaultFallback = [], workers, idleTimeoutMs, timeoutMs: defaultTimeout, defaults, split } = options;
     const custom = typeof worker === 'object' ? worker : null;
+    const byContainer = custom?.byContainer;
     const inline = worker === 'inline' || typeof Worker === 'undefined';
     const pools = new Map();
     const byId = new Map();
@@ -21,27 +22,29 @@ export function createProbeCore(options) {
             stop();
         chunk.then(resolve, (e) => reject(workerFailed(String(e), 'load', engine, e))).finally(() => life.signal.removeEventListener('abort', stop));
     });
-    const poolOf = (kind, create) => ({
-        kind,
-        pool: () => {
-            let pool = pools.get(kind);
-            if (!pool)
-                pools.set(kind, (pool = new WorkerPool({ create, size: workers, idleTimeoutMs })));
-            return pool;
-        },
-    });
+    const poolFor = (key, create) => {
+        let pool = pools.get(key);
+        if (!pool)
+            pools.set(key, (pool = new WorkerPool({ create, size: workers, idleTimeoutMs })));
+        return pool;
+    };
+    const poolOf = (kind, create) => ({ kind, pool: () => poolFor(kind, create) });
     const servedBy = (d, key) => {
         const load = d?.[key];
         if (!d || !load)
             return null;
-        return !inline && d.thread === 'worker' && d.createWorker ? poolOf(d.id, d.createWorker) : { load };
+        if (inline || d.thread !== 'worker')
+            return { load };
+        if (d.createWorker)
+            return poolOf(d.id, d.createWorker);
+        return (d.createWorkers && split?.(d.id, d.createWorkers, poolFor, lazy, life.signal)) || { load };
     };
     const routeOf = (id) => {
         const listed = !custom?.engines.includes(id)
             ? null
             : inline
                 ? { error: new ProbeError('unsupported-environment', `engine ${id} runs in a worker and Worker is not available`, { engine: id }) }
-                : poolOf('custom', custom.create);
+                : (id === 'own' && byContainer && split?.('custom', byContainer, poolFor, lazy, life.signal, custom.create)) || poolOf('custom', custom.create);
         if (listed && 'pool' in listed)
             return listed;
         const route = id === 'own'
@@ -106,13 +109,14 @@ export function createProbeCore(options) {
                     continue;
                 if ('load' in route)
                     jobs.push(lazy(route.load(), id).then((m) => m.warm?.(containers)));
-                else {
-                    const pool = route.pool();
-                    warm.set(pool, [...(warm.get(pool) ?? []), id]);
-                }
+                else
+                    for (const [pool, families] of route.warmPools ? route.warmPools(containers) : [[route.pool(), containers]]) {
+                        const [engines, union] = warm.get(pool) ?? [[], []];
+                        warm.set(pool, [[...engines, id], [...new Set([...union, ...families])]]);
+                    }
             }
-            for (const [pool, engines] of warm)
-                jobs.push(pool.run({ type: 'warm', engines, containers }, { timeoutMs: defaultTimeout }));
+            for (const [pool, [engines, union]] of warm)
+                jobs.push(pool.run({ type: 'warm', engines, containers: union }, { timeoutMs: defaultTimeout }));
             await Promise.allSettled(jobs);
         },
         dispose() {
@@ -126,6 +130,3 @@ export function createProbeCore(options) {
         },
     };
 }
-export function createProbeClient(options) {
-    return createProbeCore(options);
-}

package/dist/client/route.js

@@ -0,0 +1,20 @@
+import { splitBy } from "./split.js";
+export const EBML = [0x1a, 0x45, 0xdf, 0xa3];
+export const familyOf = (file, signal) => new Promise((resolve) => {
+    const iso = () => resolve('isobmff');
+    if (signal?.aborted)
+        return iso();
+    signal?.addEventListener('abort', iso);
+    Promise.resolve()
+        .then(() => file.slice(0, 4).arrayBuffer())
+        .then((b) => {
+        const head = new Uint8Array(b);
+        return EBML.every((x, i) => head[i] === x) ? 'matroska' : 'isobmff';
+    })
+        .then(resolve, iso)
+        .finally(() => signal?.removeEventListener('abort', iso));
+});
+export const runByHead = (pool, lazy, life) => ({
+    run: (request, options) => lazy(familyOf(request.file, options.signal), request.engine).then((family) => (life.aborted ? lazy(Promise.reject(), request.engine) : pool(family).run(request, options))),
+});
+export const splitRoute = splitBy(runByHead);

package/dist/client/split.js

@@ -0,0 +1,9 @@
+const FAMILIES = ['isobmff', 'matroska'];
+export const splitBy = (runner) => (kind, byFamily, pools, lazy, life, create) => {
+    const pool = (family) => {
+        const own = byFamily[family];
+        return own ? pools(`${kind}-${family}`, own) : pools(kind, create);
+    };
+    const run = runner(pool, lazy, life);
+    return { kind, pool: () => run, warmPools: (containers) => FAMILIES.filter((f) => containers.includes(f)).map((f) => [pool(f), [f]]) };
+};

package/dist/client/stub.js

@@ -1,5 +1,5 @@
 import { ProbeError } from "../api/errors.js";
-export const knownEngines = (worker, descriptors = []) => [...new Set(['own', ...(typeof worker === 'object' ? worker.engines : []), ...descriptors.map((d) => d.id)])];
+export const knownEngines = (worker, descriptors = []) => [...new Set(['own', ...(worker?.engines ?? []), ...descriptors.map((d) => d.id)])];
 export function lazyStub(factory, known) {
     let probe = null;
     let loading = null;
@@ -11,7 +11,7 @@ export function lazyStub(factory, known) {
         return (probe = p);
     }, (e) => {
         loading = null;
-        throw e instanceof ProbeError ? e : Object.assign(new ProbeError('worker-failed', String(e), { cause: e }), { reason: 'load' });
+        throw e?.name === 'ProbeError' && typeof e.code === 'string' ? e : Object.assign(new ProbeError('worker-failed', String(e), { cause: e }), { reason: 'load' });
     }));
     const loadUnlessDestroyed = () => new Promise((resolve, reject) => {
         const stop = () => reject(aborted());

package/dist/client/types.d.ts

@@ -20,6 +20,7 @@ export interface ProbeOptions<E extends readonly EngineDescriptor[] = []> extend
 export interface CustomWorker<W extends WorkerEngineId> {
     create: () => Worker;
     engines: readonly W[];
+    byContainer?: Readonly<Partial<Record<ContainerFamily, () => Worker>>>;
 }
 export interface ClientOptions<E extends readonly EngineDescriptor[] = [], W extends WorkerEngineId = never> extends BaseOptions<NoInfer<W | IdOf<E[number]> | 'own'>> {
     worker: CustomWorker<W> | 'inline';

package/dist/core/analyze.js

@@ -1,8 +1,5 @@
-import { throwIfAborted } from "./abort.js";
-import { resolveOptions } from "./options.js";
-import { BlobReader } from "./reader.js";
-import { emptyAnalysis } from "./result.js";
-import { sniff } from "./sniff.js";
+import { analyzeWith } from "./dispatch.js";
+export { errorMessage, firstReadAhead, isAbortError, SINGLE_READ_MAX_BYTES } from "./dispatch.js";
 export const DEFAULT_LOADERS = {
     isobmff: async () => (await Promise.all([import("./isobmff/index.js"), import("./stats.js")]))[0].analyzeIsoBmff,
     matroska: async () => (await Promise.all([import("./matroska/index.js"), import("./stats.js")]))[0].analyzeMatroska,
@@ -11,77 +8,6 @@ export const DEFAULT_ANALYZERS = {
     isobmff: async (reader, opts) => (await DEFAULT_LOADERS.isobmff())(reader, opts),
     matroska: async (reader, opts) => (await DEFAULT_LOADERS.matroska())(reader, opts),
 };
-const SNIFF_BYTES = 1024;
-export const SINGLE_READ_MAX_BYTES = 1024 * 1024;
-export function firstReadAhead(size, opts) {
-    const { perReadMs, bytesPerMs } = opts.costModel;
-    const head = opts.readAhead.head;
-    return size < Math.max(head, Math.min(head + perReadMs * bytesPerMs, SINGLE_READ_MAX_BYTES)) ? size : head;
-}
-export function isAbortError(e) {
-    return typeof e === 'object' && e !== null && 'name' in e && e.name === 'AbortError';
-}
-export function errorMessage(e) {
-    if (e instanceof Error)
-        return e.message || e.name;
-    return String(e);
-}
-function applyAnalysis(target, a) {
-    target.container = a.container;
-    target.brand = a.brand;
-    target.formatDurationSec = a.formatDurationSec;
-    target.scan = a.scan;
-    target.videoTracks = a.videoTracks;
-    target.audioTrackCount = a.audioTrackCount;
-    target.primaryTrackId = a.primaryTrackId;
-    target.error = a.error;
-    target.warnings = a.warnings;
-}
-export async function analyze(blob, name, opts = {}, analyzers = DEFAULT_ANALYZERS, loaders = analyzers === DEFAULT_ANALYZERS ? DEFAULT_LOADERS : null) {
-    const t0 = performance.now();
-    const resolved = resolveOptions(opts);
-    throwIfAborted(resolved.signal);
-    const result = {
-        name,
-        size: blob.size,
-        ...emptyAnalysis('unknown'),
-        io: { reads: 0, bytesRead: 0, ms: 0 },
-        engine: 'own',
-    };
-    let reader = null;
-    let loadMs = 0;
-    try {
-        reader = new BlobReader(blob, { headWindow: resolved.readAhead.head, signal: resolved.signal });
-        if (reader.size === 0) {
-            result.error = 'not a recognised container: empty file';
-        }
-        else {
-            const head = await reader.bytes(0, Math.min(SNIFF_BYTES, reader.size), firstReadAhead(reader.size, resolved));
-            const sniffed = sniff(head);
-            if (sniffed.kind === 'unknown') {
-                result.error = `not a recognised container: ${sniffed.reason}`;
-            }
-            else {
-                result.container = sniffed.kind === 'isobmff' ? 'mp4' : 'matroska';
-                let analyzer = analyzers[sniffed.kind];
-                if (loaders) {
-                    const l0 = performance.now();
-                    analyzer = await loaders[sniffed.kind]();
-                    loadMs = performance.now() - l0;
-                }
-                applyAnalysis(result, await analyzer(reader, resolved));
-            }
-        }
-    }
-    catch (e) {
-        if (resolved.signal?.aborted || isAbortError(e))
-            throw e;
-        result.error = errorMessage(e);
-    }
-    if (reader) {
-        result.io.reads = reader.reads;
-        result.io.bytesRead = reader.bytesFetched;
-    }
-    result.io.ms = performance.now() - t0 - loadMs;
-    return result;
+export function analyze(blob, name, opts = {}, analyzers = DEFAULT_ANALYZERS, loaders = analyzers === DEFAULT_ANALYZERS ? DEFAULT_LOADERS : null) {
+    return analyzeWith(blob, name, opts, loaders ? (kind) => loaders[kind]() : (kind) => analyzers[kind]);
 }

package/dist/core/dispatch.js

@@ -0,0 +1,76 @@
+import { throwIfAborted } from "./abort.js";
+import { resolveOptions } from "./options.js";
+import { BlobReader } from "./reader.js";
+import { emptyAnalysis } from "./result.js";
+import { sniff } from "./sniff.js";
+const SNIFF_BYTES = 1024;
+export const SINGLE_READ_MAX_BYTES = 1024 * 1024;
+export function firstReadAhead(size, opts) {
+    const { perReadMs, bytesPerMs } = opts.costModel;
+    const head = opts.readAhead.head;
+    return size < Math.max(head, Math.min(head + perReadMs * bytesPerMs, SINGLE_READ_MAX_BYTES)) ? size : head;
+}
+export function isAbortError(e) {
+    return e?.name === 'AbortError';
+}
+export function errorMessage(e) {
+    if (e instanceof Error)
+        return e.message || e.name;
+    return String(e);
+}
+function applyAnalysis(target, a) {
+    target.container = a.container;
+    target.brand = a.brand;
+    target.formatDurationSec = a.formatDurationSec;
+    target.scan = a.scan;
+    target.videoTracks = a.videoTracks;
+    target.audioTrackCount = a.audioTrackCount;
+    target.primaryTrackId = a.primaryTrackId;
+    target.error = a.error;
+    target.warnings = a.warnings;
+}
+export async function analyzeWith(blob, name, opts, analyzerOf) {
+    const t0 = performance.now();
+    const resolved = resolveOptions(opts);
+    throwIfAborted(resolved.signal);
+    const result = {
+        name,
+        size: blob.size,
+        ...emptyAnalysis('unknown'),
+        io: { reads: 0, bytesRead: 0, ms: 0 },
+        engine: 'own',
+    };
+    let reader = null;
+    let loadMs = 0;
+    try {
+        reader = new BlobReader(blob, { headWindow: resolved.readAhead.head, signal: resolved.signal });
+        if (reader.size === 0) {
+            result.error = 'not a recognised container: empty file';
+        }
+        else {
+            const head = await reader.bytes(0, Math.min(SNIFF_BYTES, reader.size), firstReadAhead(reader.size, resolved));
+            const sniffed = sniff(head);
+            if (sniffed.kind === 'unknown') {
+                result.error = `not a recognised container: ${sniffed.reason}`;
+            }
+            else {
+                result.container = sniffed.kind === 'isobmff' ? 'mp4' : 'matroska';
+                const l0 = performance.now();
+                const analyzer = await analyzerOf(sniffed.kind);
+                loadMs = performance.now() - l0;
+                applyAnalysis(result, await analyzer(reader, resolved));
+            }
+        }
+    }
+    catch (e) {
+        if (resolved.signal?.aborted || isAbortError(e))
+            throw e;
+        result.error = errorMessage(e);
+    }
+    if (reader) {
+        result.io.reads = reader.reads;
+        result.io.bytesRead = reader.bytesFetched;
+    }
+    result.io.ms = performance.now() - t0 - loadMs;
+    return result;
+}