video-fps-probe 0.4.0-beta.1 → 0.4.0

package/CHANGELOG.md

@@ -4,6 +4,78 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versions follo
 
 ## Unreleased
 
+## 0.4.0 - 2026-11-01
+
+### Summary of 0.4.0
+
+What 0.4.0 adds over 0.3.0, in one place. The [0.4.0-beta.1](CHANGELOG.md#040-beta1---2026-10-31) and [0.4.0-beta.2](CHANGELOG.md#040-beta2---2026-10-31) sections of the changelog give the details. Every 0.3.0 field and option stays, and the only change to an existing `check()` verdict is the duration window marked as a behaviour change under Changed.
+
+- **Header-only analysis on a server.** `video-fps-probe/header` reads only the header of an MP4 or MOV file in the calling thread, under limits on the bytes, the reads, the time, the tracks and the top-level boxes, and resolves the duration of a fragmented file from a sidx, the mfra index or mehd ([header-only analysis](docs/api.md#header-only-analysis)).
+- **A Range source.** `video-fps-probe/url` turns any function that fetches a byte range, such as `fetch` with a presigned URL or an object-storage SDK client, into a source for `analyzeHeader` and the in-thread `analyze`, and checks every reply before it reads the body ([Range source](docs/api.md#range-source)).
+- **Codes and layout.** `errorCode` on every own result, `errorCodeOf`, `errorClass`, `warningCodeOf` and `warningCodesOf` for results of any engine or version, and `layout` on ISO BMFF results: faststart, moov at the end or fragmented ([error codes](docs/api.md#error-codes)).
+- **Color, HDR and aspect ratio.** `codecConfig: true` keeps the codec configuration of each video track. `video-fps-probe/color` reads from it the color names ffprobe 8.1.1 prints, the bit depth, the profile, the RFC 6381 codec string, `hdr` and the Dolby Vision record, and `video-fps-probe/aspect` the sample and display aspect ratios and the display size ([color](docs/api.md#color), [aspect ratio and display size](docs/api.md#aspect-ratio-and-display-size)).
+- **New track fields.** `medianFrameInterval` on the tracks of own, mp4box and mediabunny, and `enabled` on own tracks.
+- **New check rules.** `sizeBasis: 'display'` judges the display size and the display aspect ratio, the `hdr` policy PQ, HLG and Dolby Vision as the stream keys of ffprobe signal them, from the container first and from the SPS when the container is silent, and the duration window of a WebM or Matroska track takes the median frame interval ([check](docs/api.md#check)).
+- **CommonJS for the server entries.** The seven server entries load with `require()` and in Jest with no configuration, and the types of all of them but the root entry name no DOM type. The browser entries stay ESM ([CommonJS](docs/api.md#commonjs)).
+- **The same accuracy and the same critical path.** 0 mismatches against ffprobe 8.1.1 on the 168 committed fixtures and 4878 checks. The package code in the entry chunk of the default configuration is byte for byte that of 0.3.0, 0.67 KB. The first MP4 loads 23.13 KB gzip (22.73 KB in 0.3.0), 24.91 KB with Vite's default worker format (24.47 KB), and the first WebM or MKV 25.76 KB (25.54 KB) ([size matrix](report/size-matrix.md)). The installed package takes 931 KB unpacked (580 KB in 0.3.0), most of the growth the CommonJS copy and the longer docs.
+- **Frozen API.** The codes, the layout, the header and Range source APIs, the color and aspect entries and the new check rule keys are frozen: later releases only add to them ([versioning](docs/api.md#versioning)).
+
+### Added
+
+- `check()` rules `sizeBasis` and `hdr`. `sizeBasis: 'display'` makes `frameSize` and `pixels` judge `displayWidth` x `displayHeight`, which `withAspect` sets with the rotation applied, and `aspectRatio` the exact `displayAspectRatio` that ffprobe prints, turned the same way, so an anamorphic 1440x1080 file stored for 16:9 display passes `aspectRatio: { oneOf: ['16:9'] }`, and so does NTSC widescreen, 720x480 with a sample aspect ratio of 32:27, whose display size rounds to 853x480. The default, `'stored'`, judges the stored size as before. `hdr` is a `RatePolicy` over the `color` that `withColor` sets: PQ, HLG, an 8-bit HLG file included, and Dolby Vision are HDR, BT.2020 primaries or 10 bits alone are not. It judges the signalling as the stream keys of ffprobe do, so a `colr` that names a transfer wins over the SPS and an alternative transfer characteristics SEI is not read (see Known limitations below). A missing display size or color is unknown, never a pass, each with a hint: `no display size (needs codecConfig: true and withAspect)`, `no color (needs codecConfig: true and withColor)`, `no color in codecConfig` for a codec configuration without a color source and `no transfer in codecConfig` when the container and the SPS are silent, as for an AV1 or VP9 file whose container carries no color, or the transfer is `reserved`. A result analyzed without `codecConfig: true` (with `analyzeHeader`, without `color: true` for `hdr` or `aspect: true` for the display basis), and one persisted by 0.3.0, are therefore unknown under these rules. A 0.3.x `check()` throws on rules that use `sizeBasis` or `hdr`, since it validates the keys strictly ([check](docs/api.md#check)).
+
+### Frozen from 0.4.0
+
+The `CheckRules` keys `hdr`, a `RatePolicy`, and `sizeBasis`, `'stored'` or `'display'` with `'stored'` the default, join the lists of 0.4.0-beta.1 and 0.4.0-beta.2.
+
+### Changed
+
+- **Behaviour change:** `check()` now takes the median frame interval, `medianFrameInterval`, as the typical frame interval of a WebM or Matroska track that has no dominant rate and is not constant, where 0.3.0 and the betas took the average interval. `duration` judges the format duration of such a track when it is within that interval of the measured span, so the window of the Chromium recordings narrows from about 27 ms to 17 ms: for a format duration more than 17 ms and at most about 27 ms off the span, the span is judged instead. Tracks with a dominant rate or a constant rate and MP4 and MOV tracks are judged as before, and so are Matroska header scans and results persisted by 0.3.0, which have no `medianFrameInterval`. Every preset verdict over the committed fixtures is unchanged.
+- `video-fps-probe/check` puts 4.22 KB gzip in the entry chunk (3.99 KB in 0.3.0), after a trim that kept every message and every verdict. The critical path of a host that imports it is 4.78 KB (4.55 KB), under its 5.00 KB budget, and with one preset 5.13 KB (4.90 KB). That is over the 5.00 KB budget of the preset configuration, so that budget moved to its measurement plus 3 percent, rounded up to 0.5 KB, 5.50 KB, as the 0.4.0 plan allowed for this opt-in entry. The default critical path does not change.
+- The installed package measures 931 KB unpacked (920 KB in 0.4.0-beta.2), under its 936 KB cap, with the longer changelog and the check rules.
+
+### Fixed
+
+- The docs and the 0.4.0-beta.2 notes said a probe posts the bytes of the moov and nothing else. That holds for every moov whose size fits in the file. For a moov whose size field runs past the end of the file, the walk reads and copies everything from the start of the moov to the end of the file, up to 16 MiB, so when such a moov is not the last box the posted copy also holds the boxes after it, an mdat included. The text now says so, and the code is unchanged.
+
+### Known limitations
+
+- The color entry does not read the AV1 sequence header, the VP9 frame header, ProRes or HDR10 static metadata (`mdcv`, `clli`, MasteringMetadata), so their values stay null where ffprobe takes them from the decoder, and `hdr` is unknown for such a file whose container carries no color.
+- `hdr` judges the signalling as the stream keys of ffprobe do. A `colr` that names a transfer wins over the SPS, and an alternative transfer characteristics SEI is not read, so a `bt709` colr over a PQ SPS, and HLG signalled only in such an SEI next to a `bt2020-10` transfer (x265 `--atc-sei 18`), pass `hdr: 'reject'` while their decoded frames are HDR.
+- The `rotation` of a Matroska or WebM track stays 0, while `withAspect` applies its ProjectionPoseRoll to the display size.
+- With `codecConfig: true` a probe posts a copy of the moov box, up to 256 MiB, and nothing else, except for a moov whose size field runs past the end of the file, whose copy runs to the end of the file, up to 16 MiB, with the boxes after it when it is not the last box. While the walk runs it can hold the moov twice.
+- The types of the root entry name DOM types such as `Worker`, so a TypeScript project for Node that imports it needs `"DOM"` in `lib` or `skipLibCheck: true`.
+- Only Vite 8 and npm are tested in CI until the bundler matrix of 0.4.1 ([bundlers](docs/bundlers.md)). The Range source and full-mode limitations of [0.4.0-beta.1](CHANGELOG.md#040-beta1---2026-10-31) and the React, zero-config Vite and corpus limitations of [0.3.0](CHANGELOG.md#030---2026-10-30) still hold.
+
+## 0.4.0-beta.2 - 2026-10-31
+
+### Added
+
+- `video-fps-probe/color`: `colorOf(track)` and `withColor(result)` read the codec configuration of a video track and give `color`: the range, primaries, transfer and matrix names that ffprobe 8.1.1 prints, where they came from (`sps`, `colr`, `vpcC` or `Colour`), the bit depth, the numeric profile, the RFC 6381 codec string, `hdr` (`'pq'` or `'hlg'`) and the Dolby Vision configuration record. The container wins over the H.264 or HEVC SPS, as in FFmpeg, and the SPS speaks when the container is silent. A value that is not null equals ffprobe on every committed fixture ([color](docs/api.md#color)).
+- `video-fps-probe/aspect`: `aspectOf(track)` and `withAspect(result)` give `sampleAspectRatio`, `displayAspectRatio`, `displayWidth` and `displayHeight`, with the pasp, tkhd matrix, tkhd size and SPS VUI precedence of ffprobe 8.1.1 for MP4 and MOV and the Display and PixelCrop elements for Matroska and WebM. The display size has the rotation applied, for Matroska and WebM the ProjectionPoseRoll that ffprobe reports as the display matrix ([aspect ratio and display size](docs/api.md#aspect-ratio-and-display-size)).
+- `codecConfig: true` keeps the raw codec configuration of each video track in `codecConfig` for both entries, with no read beyond the walk: the TrackEntry of a Matroska or WebM track, the stsd, tkhd and mvhd boxes of an MP4 or MOV track in `analyzeHeader` and the root `analyze`, and in a probe a view of the moov with the index of the trak, `{ family: 'isobmff-moov', moov, trak }`, a family of its own, from which both entries cut the same boxes. The view lies in a copy of the moov that the walk makes only with the option, so a probe posts the moov box and nothing else, except for a moov whose size field runs past the end of the file: then it posts everything from the start of the moov to the end of the file, up to 16 MiB, the boxes after a moov that is not the last box included. A configuration whose bytes are missing or no longer `Uint8Array` or `DataView` values, as after `JSON.parse`, or that has a buffer transferred to another thread in any member, the view of the moov, a box or the TrackEntry, gives `color` and the aspect fields undefined, as a track without one does.
+- `analyzeHeader` options `codecConfig`, `color` and `aspect`. `color: true` and `aspect: true` apply the two entries from a chunk loaded with `import()` and read no extra byte. Each chunk loads under the deadline and the signal of the call. A chunk never turns a result into an error: one that fails to load or has not loaded by `maxMs` leaves the result as it is with a coded warning, and one that an earlier call loaded, or started to load before it lost to its deadline, is applied even after the deadline, since it reads no byte.
+- The warning codes `codec-config-unavailable`, for the prefix `codec configuration unavailable`, and `metadata-unavailable`, for `color and aspect unavailable`, which `warningCodeOf` gives to an `analyzeHeader` result whose codec configuration or color and aspect step did not run, so an exhaustive switch over `WarningCode` needs the two cases.
+- The new optional result fields `codecConfig`, `color`, `sampleAspectRatio`, `displayAspectRatio`, `displayWidth` and `displayHeight` on `VideoTrackResult`, and the types `CodecConfig`, `ColorInfo`, `ColorSource` and `DolbyVisionConfig`.
+- CommonJS copies of `video-fps-probe/color` and `video-fps-probe/aspect`, so the seven server entries load with `require()` and in Jest with no configuration, and the types of all of them but the root entry name no DOM type.
+
+### Frozen from 0.4.0-beta.2
+
+The members of `ColorInfo` and `DolbyVisionConfig`, the `ColorSource` values, the `codecConfig`, `color` and `aspect` options of `analyzeHeader`, the warning codes `codec-config-unavailable` and `metadata-unavailable` with their prefixes and the signatures of `colorOf`, `withColor`, `aspectOf` and `withAspect` join the list of 0.4.0-beta.1. Later releases only add to them. `CodecConfig` is raw bytes for the two entries and may gain members.
+
+### Changed
+
+- The installed package may take up to 936 KB unpacked (867 KB in 0.4.0-beta.1), measured at 920 KB, for the two entries, their CommonJS copies and the longer docs.
+- The first MKV or WebM loads 25.76 KB gzip (25.73 KB in 0.4.0-beta.1) for the TrackEntry copy: the Matroska header walk copies every TrackEntry, and the analyzer attaches the copy to the video tracks only with the option. The first MP4 loads 23.13 KB (23.07 KB in 0.4.0-beta.1), 24.91 KB with Vite's default worker format, for the view of the moov that the worker attaches with the option and the copy of the moov it lies in. The 0.4.0 plan gave this step 0.05 KB on the first MP4 path, and the copy takes it to 0.08 KB, measured 0.06 to 0.08 KB over 0.4.0-beta.1, with every first MP4 row inside its budget and the 24.95 KB cap.
+- `video-fps-probe/color` puts 4.93 KB gzip in the entry chunk of an app that imports it, under a budget of 5.0 KB rather than the 4.00 KB the 0.4.0 plan set: the two SPS walkers and the FFmpeg name tables are what make the color result equal to ffprobe, and cutting the boxes out of the moov view of a probe adds 0.25 KB.
+- `video-fps-probe/header` puts 19.81 KB gzip of package code in the entry chunk (19.28 KB in 0.4.0-beta.1). It loads the codec configuration capture and the two entries with `import()`, so an app whose only dynamic import is this one gets Vite's preload helper, 0.75 KB, in its entry chunk too.
+- Still 0 mismatches against ffprobe 8.1.1 on the 168 committed fixtures, now with checks of the color names, bit depth, profile, codec string, Dolby Vision record and both aspect ratios: 4878 checks, with 5 new known deviations where ffprobe takes the color range or matrix from a bitstream the color entry does not read (the AV1 sequence header, ProRes, MPEG-4 Part 2).
+
+### Known limitations
+
+- A probe gives an MP4 or MOV track a view of the moov rather than the three boxes, because cutting them in the worker measured 0.25 KB on the first MP4 path, over the 0.08 KB this release allows there. `colorOf` and `aspectOf` read both forms. The view lies in a copy of the moov, so `postMessage` copies the moov box, up to 256 MiB, and nothing else, except for a moov whose size field runs past the end of the file, where it copies everything from the start of the moov to the end of the file, up to 16 MiB, the boxes after a moov that is not the last box included. Without the copy a probe posted the whole read the moov came from, up to 16 MiB with media data after an mdat. While the walk runs it can hold the moov twice, the read and the copy, up to 512 MiB for a moov at the 256 MiB limit.
+- The color entry does not read the AV1 sequence header, the VP9 frame header, ProRes or HDR10 static metadata (`mdcv`, `clli`, MasteringMetadata), so their values stay null where ffprobe takes them from the decoder. An HLG stream signalled only by an alternative transfer characteristics SEI keeps the `bt2020-10` transfer of its VUI, as the stream keys of ffprobe do. The `rotation` of a Matroska or WebM track stays 0, while `withAspect` applies its ProjectionPoseRoll to the display size.
+
 ## 0.4.0-beta.1 - 2026-10-31
 
 ### Added

package/README.md

@@ -98,7 +98,7 @@ 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 of the root entry name DOM types such as `Worker` and `HTMLElement`, so a TypeScript project for Node that imports it needs `"DOM"` in `lib` or `skipLibCheck: true`. The server entries `video-fps-probe/header`, `video-fps-probe/url`, `video-fps-probe/check` and `video-fps-probe/presets` need neither.
+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 of the root entry name DOM types such as `Worker` and `HTMLElement`, so a TypeScript project for Node that imports it needs `"DOM"` in `lib` or `skipLibCheck: true`. The server entries `video-fps-probe/header`, `video-fps-probe/url`, `video-fps-probe/color`, `video-fps-probe/aspect`, `video-fps-probe/check` and `video-fps-probe/presets` need neither.
 
 A server can branch on `result.errorCode`, a machine-readable code for `error` such as `unrecognised`, `no-header`, `truncated` or `read-failed`, and on `result.layout`, which tells a faststart MP4 from one with its moov at the end or a fragmented one. `errorCodeOf(result)` also codes results of other engines and stored 0.3.0 JSON from their text, and `errorClass(code)` tells a file problem, which can be cached, from a read failure worth a retry ([error codes](docs/api.md#error-codes)).
 
@@ -106,7 +106,9 @@ A server that checks uploads in object storage can read only the header: `analyz
 
 `video-fps-probe/url` reads such an object over HTTP Range requests: `analyzeHeader(await openRangeSource(httpRange(presignedUrl)), { limits })`, or `rangeSource(fetcher, { size })` over the client of any object-storage SDK. It needs no SDK and makes one request per read, with no retries, and it checks the status, `Content-Range` and `Content-Length` of every reply before the body is read and caps the body while it streams, so a server that ignores the range or an object whose size changed fails the read as `read-failed` instead of returning wrong bytes. An `If-Match` with the object's ETag, which the caller sends, also catches an overwrite at the same size ([Range source](docs/api.md#range-source)).
 
-CommonJS works on Node 22.12 and newer, the lowest supported version, 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 five server entries, `video-fps-probe`, `video-fps-probe/header`, `video-fps-probe/url`, `video-fps-probe/check` and `video-fps-probe/presets`, also ship a minified CommonJS copy with `.d.cts` types for loaders that do not run `require(esm)`, so Jest 30 runs them with no configuration and `jest` as the only dependency, and with `--experimental-vm-modules` on Node 24.9 it loads the ESM build instead. The package tests check all of this from the packed tarball on Node 22.12 and 24. The other entries still need babel-jest in Jest: the tested configuration and a stub for unit tests are in [Jest](docs/api.md#jest).
+The same call can tell an HDR upload from an SDR one and give the display size: `analyzeHeader(source, { color: true, aspect: true })` fills `color` with the range, primaries, transfer and matrix names ffprobe prints, the bit depth, the profile, the RFC 6381 codec string, `hdr` (`'pq'` or `'hlg'`) and the Dolby Vision record, and fills `sampleAspectRatio`, `displayAspectRatio`, `displayWidth` and `displayHeight`, from the boxes of the moov it reads anyway. The container wins over the H.264 or HEVC SPS as in FFmpeg 8.1.1, and the SPS speaks when the container is silent. `video-fps-probe/color` and `video-fps-probe/aspect` do the same for results of `analyzeHeader`, the root `analyze` or a probe with `codecConfig: true` ([Color](docs/api.md#color), [Aspect ratio and display size](docs/api.md#aspect-ratio-and-display-size)).
+
+CommonJS works on Node 22.12 and newer, the lowest supported version, 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 seven server entries, `video-fps-probe`, `video-fps-probe/header`, `video-fps-probe/url`, `video-fps-probe/color`, `video-fps-probe/aspect`, `video-fps-probe/check` and `video-fps-probe/presets`, also ship a minified CommonJS copy with `.d.cts` types for loaders that do not run `require(esm)`, so Jest 30 runs them with no configuration and `jest` as the only dependency, and with `--experimental-vm-modules` on Node 24.9 it loads the ESM build instead. The package tests check all of this from the packed tarball on Node 22.12 and 24. The other entries still need babel-jest in Jest: the tested configuration and a stub for unit tests are in [Jest](docs/api.md#jest).
 
 ## Cancellation, timeouts and failing open
 
@@ -131,18 +133,18 @@ 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; 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)).
+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`. On a result analyzed with `codecConfig: true`, `sizeBasis: 'display'` judges the display size and the display aspect ratio that `withAspect` sets, and `hdr: 'reject'` fails PQ, HLG and Dolby Vision as the stream keys of ffprobe signal them, the container first and the SPS when the container is silent, from the color that `withColor` sets, while a file whose color is not known stays unknown ([check](docs/api.md#check), [presets](docs/api.md#presets)).
 
 ## Size
 
 <!-- tables:size:start -->
 
-**0.66 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:
+**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.66 KB** | 23.07 KB | 25.73 KB | 49.14 KB | 2 |
-| none (Vite's default, 'iife') | **0.66 KB** | 24.85 KB | 27.19 KB | 48.75 KB | 2 |
+| `worker: { format: 'es' }` (recommended) | **0.67 KB** | 23.13 KB | 25.76 KB | 49.23 KB | 2 |
+| none (Vite's default, 'iife') | **0.66 KB** | 24.91 KB | 27.21 KB | 48.85 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:
 
@@ -152,9 +154,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.66 KB to 0.89 KB with mp4box or mediabunny, 0.76 KB with rVFC and 1.01 KB with all three, and the engine itself loads lazily: mp4box 44.94 KB, mediabunny 54.17 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.95 KB, mediabunny 54.16 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), and 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.
+`video-fps-probe/react` adds 1.20 KB to the critical path for the provider, `useVideoFps` and its store (React itself not counted), and its first analysis also fetches a 0.43 KB summary module, in parallel with the probe client. `video-fps-probe/check` adds 4.22 KB when imported statically, and nothing lazily. One preset from `video-fps-probe/presets` adds 0.46 KB.
 
 <!-- tables:size:end -->
 
@@ -162,7 +164,7 @@ 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 168 committed fixtures: 3318 field checks, 3229 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), 2 known deviations with a recorded reason, 74 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 168 committed fixtures: 4878 field checks, 4675 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), 7 known deviations with a recorded reason, 183 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 168 committed fixtures, 156 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).
 
@@ -176,8 +178,9 @@ Known limitations: [changelog](CHANGELOG.md#known-limitations), [benchmarks](doc
 
 ## Roadmap
 
-- **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.4.1**: 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.2**: a CI guarantee of a clean console: the e2e and consumer smoke tests fail on any console warning or error, page error or unhandled rejection in Chromium, Firefox and WebKit, and a Node test checks that the library writes nothing to stdout or stderr.
+- **Later in 0.4.x**: HDR10 static metadata (`mdcv`, `clli`, MasteringMetadata) and the color of the AV1 sequence header, which the color entry of 0.4.0 does not read yet.
 - **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

package/dist/analyze.js

@@ -1,5 +1,14 @@
 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);
+    const result = await module.run(input, name, opts);
+    if (!result.videoTracks.some((t) => t.codecConfig?.family === 'isobmff-moov'))
+        return result;
+    try {
+        const { isoBoxes } = await import("./core/isobmff/config.js");
+        return { ...result, videoTracks: result.videoTracks.map((t) => (t.codecConfig?.family === 'isobmff-moov' ? { ...t, codecConfig: isoBoxes(t.codecConfig.moov, t.codecConfig.trak) } : t)) };
+    }
+    catch {
+        return result;
+    }
 }

package/dist/api/codes.js

@@ -49,6 +49,8 @@ const WARNING_PREFIXES = [
     ['format duration unresolved: ', 'duration-unresolved'],
     ['fragments ignored: ', 'fragments-ignored'],
     ['too many top-level boxes', 'structure-limit'],
+    ['codec configuration unavailable', 'codec-config-unavailable'],
+    ['color and aspect unavailable', 'metadata-unavailable'],
 ];
 const TRUNCATED_BOX = /^'(.{4})' at \d+ is truncated/;
 export function errorCodeOf(result) {

package/dist/aspect/index.d.ts

@@ -0,0 +1,13 @@
+import type { FileResult, Rational, VideoTrackResult } from '../core/types.js';
+export type { CodecConfig, Rational } from '../core/types.js';
+export interface AspectInfo {
+    sampleAspectRatio: Rational | null;
+    displayAspectRatio: Rational | null;
+    displayWidth: number | null;
+    displayHeight: number | null;
+}
+export type AspectTrack = Pick<VideoTrackResult, 'codecName' | 'width' | 'height' | 'rotation' | 'codecConfig'>;
+export declare function aspectOf(track: AspectTrack): AspectInfo | undefined;
+export declare function withAspect<R extends Pick<FileResult, 'videoTracks'>>(result: R, options?: {
+    keepCodecConfig?: boolean;
+}): R;

package/dist/aspect/index.js

@@ -0,0 +1,180 @@
+import { boxPayload, elementUint, elements, firstBox, i32, ID_DISPLAY_HEIGHT, ID_DISPLAY_UNIT, ID_DISPLAY_WIDTH, ID_PIXEL_HEIGHT, ID_PIXEL_WIDTH, ID_STEREO_MODE, isoConfig, matroskaConfig, u32, } from "../color/config.js";
+import { avcConfigSps, hevcConfigSps } from "../color/sps.js";
+import { avD2q, avReduce, INT_MAX } from "./rational.js";
+const DAR_MAX = 1048576n;
+const MATRIX_SCALE_LIMIT = 1 << 24;
+const MATRIX_SCALE_TOLERANCE = 0.01;
+const DISPLAY_UNIT_UNKNOWN = 4;
+const WIDTH_TIMES_TWO = new Set([1, 8, 9, 11]);
+const HEIGHT_TIMES_TWO = new Set([2, 3, 6, 7]);
+const ID_PIXEL_CROP_BOTTOM = 0x54aa;
+const ID_PIXEL_CROP_TOP = 0x54bb;
+const ID_PIXEL_CROP_LEFT = 0x54cc;
+const ID_PIXEL_CROP_RIGHT = 0x54dd;
+const ID_PROJECTION = 0x7670;
+const ID_PROJECTION_TYPE = 0x7671;
+const ID_PROJECTION_PRIVATE = 0x7672;
+const ID_PROJECTION_POSE_YAW = 0x7673;
+const ID_PROJECTION_POSE_PITCH = 0x7674;
+const ID_PROJECTION_POSE_ROLL = 0x7675;
+function rational([num, den]) {
+    return { num: Number(num), den: Number(den), value: Number(num) / Number(den) };
+}
+const valid = (r) => r !== null && r[0] > 0n && r[1] > 0n;
+function vuiRatio(sps) {
+    const sar = sps?.vui?.sar;
+    return sar ? avReduce(BigInt(sar[0]), BigInt(sar[1]), INT_MAX) : null;
+}
+function configSps(codec, b, s) {
+    return !s ? null : codec === 'h264' ? avcConfigSps(b, s) : codec === 'hevc' ? hevcConfigSps(b, s) : null;
+}
+function matrixOf(box, offset) {
+    const p = boxPayload(box);
+    if (!box || !p)
+        return null;
+    const at = p.start + offset(box[p.start]);
+    if (at + 36 > p.end)
+        return null;
+    return Array.from({ length: 9 }, (_, i) => BigInt(i32(box, at + i * 4)));
+}
+function tkhdSizeAt(iso) {
+    const tkhd = boxPayload(iso.tkhd);
+    const at = iso.tkhd && tkhd ? tkhd.start + (iso.tkhd[tkhd.start] === 1 ? 88 : 76) : -1;
+    return tkhd && at + 8 <= tkhd.end ? at : -1;
+}
+function matrixRatio(iso, sizeAt) {
+    if (!iso.tkhd || sizeAt < 0 || !u32(iso.tkhd, sizeAt) || !u32(iso.tkhd, sizeAt + 4))
+        return null;
+    const track = matrixOf(iso.tkhd, (v) => (v === 1 ? 52 : 40));
+    if (!track)
+        return null;
+    const movie = matrixOf(iso.mvhd, (v) => (v === 1 ? 48 : 36)) ?? Array(9).fill(0n);
+    const shift = [16n, 16n, 30n];
+    const m = [];
+    for (let i = 0; i < 3; i++) {
+        for (let j = 0; j < 3; j++) {
+            let sum = 0n;
+            for (let e = 0; e < 3; e++)
+                sum += (track[i * 3 + e] * movie[e * 3 + j]) >> shift[e];
+            m.push(Number(BigInt.asIntN(32, sum)));
+        }
+    }
+    const identity = m[0] === 65536 && m[4] === 65536 && m[8] === 1 << 30 && !m[1] && !m[2] && !m[3] && !m[5] && !m[6] && !m[7];
+    if (identity)
+        return null;
+    const x = Math.hypot(m[0], m[3]);
+    const y = Math.hypot(m[1], m[4]);
+    if (!(x > 1 && y > 1 && x < MATRIX_SCALE_LIMIT && y < MATRIX_SCALE_LIMIT && Math.abs(x / y - 1) > MATRIX_SCALE_TOLERANCE))
+        return null;
+    return avD2q(x / y, INT_MAX);
+}
+function isoRatio(track, iso) {
+    const sizeAt = tkhdSizeAt(iso);
+    let pasp = null;
+    for (const entry of iso.entries) {
+        for (const c of entry.children) {
+            if (c.type === 'pasp' && c.end - c.start >= 8 && i32(iso.bytes, c.start + 4))
+                pasp = [BigInt(i32(iso.bytes, c.start)), BigInt(i32(iso.bytes, c.start + 4))];
+        }
+    }
+    let sar = pasp?.[0] ? avReduce(pasp[0], pasp[1], INT_MAX) : matrixRatio(iso, sizeAt);
+    if (!sar?.[0] && iso.tkhd && sizeAt >= 0) {
+        const w = BigInt(i32(iso.tkhd, sizeAt) >> 16);
+        const h = BigInt(i32(iso.tkhd, sizeAt + 4) >> 16);
+        const sw = BigInt(track.width);
+        const sh = BigInt(track.height);
+        if (w && h && sw && sh && (sw !== w || sh !== h))
+            sar = avReduce(sh * w, sw * h, INT_MAX);
+    }
+    if (valid(sar))
+        return sar;
+    const entry = iso.entries[0];
+    return vuiRatio(configSps(track.codecName, iso.bytes, firstBox(entry, track.codecName === 'h264' ? 'avcC' : 'hvcC')));
+}
+function matroskaCodec(mkv) {
+    return mkv.codecId === 'V_MPEG4/ISO/AVC' ? 'h264' : mkv.codecId === 'V_MPEGH/ISO/HEVC' ? 'hevc' : '';
+}
+function matroskaRatio(mkv) {
+    const b = mkv.bytes;
+    const video = (id) => elementUint(b, mkv.video.get(id));
+    const unit = video(ID_DISPLAY_UNIT) ?? 0;
+    let sar = null;
+    const croppedWidth = (video(ID_PIXEL_WIDTH) ?? 0) - (video(ID_PIXEL_CROP_LEFT) ?? 0) - (video(ID_PIXEL_CROP_RIGHT) ?? 0);
+    const croppedHeight = (video(ID_PIXEL_HEIGHT) ?? 0) - (video(ID_PIXEL_CROP_TOP) ?? 0) - (video(ID_PIXEL_CROP_BOTTOM) ?? 0);
+    if (unit < DISPLAY_UNIT_UNKNOWN && croppedWidth > 0 && croppedHeight > 0) {
+        const dw = video(ID_DISPLAY_WIDTH) ?? (unit === 0 ? croppedWidth : null);
+        const dh = video(ID_DISPLAY_HEIGHT) ?? (unit === 0 ? croppedHeight : null);
+        const stereo = video(ID_STEREO_MODE) ?? 0;
+        if (dw && dh) {
+            const wmul = WIDTH_TIMES_TWO.has(stereo) ? 2n : 1n;
+            const hmul = HEIGHT_TIMES_TWO.has(stereo) ? 2n : 1n;
+            sar = avReduce(BigInt(croppedHeight) * BigInt(dw) * wmul, BigInt(croppedWidth) * BigInt(dh) * hmul, INT_MAX);
+        }
+    }
+    return valid(sar) ? sar : vuiRatio(configSps(matroskaCodec(mkv), b, mkv.codecPrivate));
+}
+function elementFloat(b, span) {
+    const n = span ? span.end - span.start : 0;
+    if (!span || (n !== 4 && n !== 8))
+        return 0;
+    const dv = new DataView(b.buffer, b.byteOffset + span.start, n);
+    return n === 4 ? dv.getFloat32(0) : dv.getFloat64(0);
+}
+function projectionRotation(mkv) {
+    const span = mkv.video.get(ID_PROJECTION);
+    if (!span)
+        return 0;
+    const b = mkv.bytes;
+    const projection = new Map();
+    for (const e of elements(b, span.start, span.end))
+        projection.set(e.id, e);
+    const extra = projection.get(ID_PROJECTION_PRIVATE);
+    if ((elementUint(b, projection.get(ID_PROJECTION_TYPE)) ?? 0) !== 0 || (extra && extra.end > extra.start && b[extra.start] !== 0))
+        return 0;
+    const yaw = elementFloat(b, projection.get(ID_PROJECTION_POSE_YAW));
+    const roll = elementFloat(b, projection.get(ID_PROJECTION_POSE_ROLL));
+    if (elementFloat(b, projection.get(ID_PROJECTION_POSE_PITCH)) !== 0 || (yaw !== 0 && Math.abs(yaw) !== 180) || Number.isNaN(roll))
+        return 0;
+    const flip = yaw !== 0 ? -1 : 1;
+    const radians = (roll * flip * Math.PI) / 180;
+    const a = (flip * Math.trunc(Math.cos(radians) * 65536)) / 65536;
+    const c = Math.trunc(-Math.sin(radians) * 65536) / 65536;
+    const s0 = Math.hypot(a, (flip * Math.trunc(Math.sin(radians) * 65536)) / 65536);
+    const s1 = Math.hypot(c, Math.trunc(Math.cos(radians) * 65536) / 65536);
+    return s0 && s1 ? Math.trunc(-((Math.atan2(c / s1, a / s0) * 180) / Math.PI)) || 0 : 0;
+}
+export function aspectOf(track) {
+    const config = track.codecConfig;
+    const iso = config && isoConfig(config);
+    const mkv = config && !iso ? matroskaConfig(config) : null;
+    if (!iso && !mkv)
+        return undefined;
+    const sar = iso ? isoRatio(track, iso) : matroskaRatio(mkv);
+    const usable = valid(sar) ? sar : null;
+    const { width, height } = track;
+    if (width <= 0 || height <= 0)
+        return { sampleAspectRatio: usable && rational(usable), displayAspectRatio: null, displayWidth: null, displayHeight: null };
+    const [num, den] = usable ?? [1n, 1n];
+    const storedWidth = Number((2n * BigInt(width) * num + den) / (2n * den));
+    const rotation = track.rotation || (mkv ? projectionRotation(mkv) : 0);
+    const swap = Math.abs(rotation) % 180 === 90;
+    return {
+        sampleAspectRatio: usable && rational(usable),
+        displayAspectRatio: usable && rational(avReduce(BigInt(width) * num, BigInt(height) * den, DAR_MAX)),
+        displayWidth: swap ? height : storedWidth,
+        displayHeight: swap ? storedWidth : height,
+    };
+}
+export function withAspect(result, options = {}) {
+    return {
+        ...result,
+        videoTracks: result.videoTracks.map((t) => {
+            if (!t.codecConfig)
+                return t;
+            const out = { ...t, ...aspectOf(t) };
+            if (!options.keepCodecConfig)
+                delete out.codecConfig;
+            return out;
+        }),
+    };
+}

package/dist/aspect/rational.js

@@ -0,0 +1,61 @@
+export const INT_MAX = 2147483647n;
+const abs = (v) => (v < 0n ? -v : v);
+function gcd(a, b) {
+    while (b)
+        [a, b] = [b, a % b];
+    return a;
+}
+export function avReduce(num, den, max) {
+    let a0 = [0n, 1n];
+    let a1 = [1n, 0n];
+    const negative = num < 0n !== den < 0n;
+    const g = gcd(abs(num), abs(den));
+    if (g) {
+        num = abs(num) / g;
+        den = abs(den) / g;
+    }
+    if (num <= max && den <= max) {
+        a1 = [num, den];
+        den = 0n;
+    }
+    while (den) {
+        let x = num / den;
+        const nextDen = num - den * x;
+        const a2n = x * a1[0] + a0[0];
+        const a2d = x * a1[1] + a0[1];
+        if (a2n > max || a2d > max) {
+            if (a1[0])
+                x = (max - a0[0]) / a1[0];
+            if (a1[1])
+                x = x < (max - a0[1]) / a1[1] ? x : (max - a0[1]) / a1[1];
+            if (den * (2n * x * a1[1] + a0[1]) > num * a1[1])
+                a1 = [x * a1[0] + a0[0], x * a1[1] + a0[1]];
+            break;
+        }
+        a0 = a1;
+        a1 = [a2n, a2d];
+        num = den;
+        den = nextDen;
+    }
+    return [negative ? -a1[0] : a1[0], a1[1]];
+}
+function binaryExponent(v) {
+    if (v === 0)
+        return 0;
+    let e = Math.floor(Math.log2(v));
+    while (2 ** e > v)
+        e--;
+    while (2 ** (e + 1) <= v)
+        e++;
+    return e;
+}
+export function avD2q(d, max) {
+    if (Number.isNaN(d))
+        return [0n, 0n];
+    if (Math.abs(d) > Number(INT_MAX) + 3)
+        return [d < 0 ? -1n : 1n, 0n];
+    const exponent = Math.max(binaryExponent(Math.abs(d)), 0);
+    const den = 1n << BigInt(61 - exponent);
+    const num = BigInt(Math.floor(d * Number(den) + 0.5));
+    return avReduce(num, den, max);
+}

package/dist/check/index.d.ts

@@ -38,6 +38,8 @@ export interface CheckRules {
     audio?: 'required' | 'forbidden';
     vfr?: RatePolicy;
     uneven?: RatePolicy;
+    hdr?: RatePolicy;
+    sizeBasis?: 'stored' | 'display';
     severity?: 'fail' | 'warn';
 }
 export type CheckExpected = number | string | readonly (number | string)[] | null;