fix(core): media-treatment --analyze finishes on long HDR clips - #5792

What changes for users

hyperframes media-treatment --analyze now finishes on several-minute HDR clips instead of failing with spawnSync ffmpeg ETIMEDOUT, and its grade reflects the whole clip rather than only the first 40 seconds.

Root cause

analyzeMediaGrade (packages/core/src/mediaGradeAnalyzer.ts, and its vendored copy packages/cli/src/media-use/lib/grade-analyzer.mjs) ran one ffmpeg pass from the start of the file with an fps filter set to 5 / duration, floored at 0.1 fps. For any clip longer than 50 s the floor wins, so ffmpeg decoded every frame of the first ~40 s, at full resolution and frame rate, to emit its five samples. The cost grows with resolution × frame rate, and a 4K60 10-bit HEVC phone clip goes past the fixed 15 s timeout. The same floor meant the five samples all came from the first 40 s.

Fix

Each of the five samples seeks (-noaccurate_seek -ss) to the middle of one fifth of the clip and decodes a single frame from the keyframe there. Decode work no longer depends on clip length, resolution only scales the five decodes. The 15 s timeout (still overridable with HYPERFRAMES_ANALYZE_TIMEOUT_MS) now applies per sample, and on expiry the error names the sample time and the variable. Images and media with no probed duration keep the old single pass. trim=end_frame=N heads the filter chain: on ffmpeg 8, -frames:v N still lets one extra frame through the filter, so each sample counted twice (main's image path had the same leak: an animated GIF reported 6 frames).

-noaccurate_seek over an accurate seek: an accurate seek decodes from the keyframe up to the target, which on a long-GOP file (a screen recording with one keyframe) brings back a decode that scales with clip length. The sample lands on the keyframe at or before the target instead, within a GOP of it on camera footage.

Before / after

Same machine (8-core Linux, shared and under load), same generated clips, wall time of analyzeMediaGrade:

The measured stats agree to the decimal (yAvg 126.4 vs 126.4 on the 4K clip). The table times the media-use copy; the core module behind the command measured the same way: 4K60 clip main ETIMEDOUT at 17.5 s vs 2.4 s, 240 s 1080x1920 clip 5.7 s vs 0.8 s. Generated clips decode faster than camera footage; an independent rerun on a 60 s 4K60 synthetic clip measured 8.4 s on main vs 2.1 s here.

Known limits, deliberate: the per-sample timeout means a stuck run fails after up to 5 x 15 s instead of 15 s, with the sample named. On a file with one keyframe (some screen recordings) every sample lands on that keyframe, so the grade comes from fewer distinct frames; it still finishes.

Tests

• packages/core/src/mediaGradeAnalyzer.test.ts (new, real ffmpeg, runs in the runtime test job): a two-minute 128x128 10-bit HLG HEVC clip, black then white. On main it fails with expected 16 to be greater than 200 (all samples from the black first 40 s); on this branch the samples cover both halves. A second test sets the timeout to 1 ms and checks the error message.
• The media-use copy measures the same clip identically (runs in CI with ffmpeg; replacing its seek with a single pass turns it red), and the parity test checks both copies seek to the same times.
• 20/20 pass 3 runs in a row on ffmpeg 8.0.1 (the build CI pins) and once on 7.0.2; media-treatment.test.ts (34) and grade-analyzer.test.mjs (10) pass.

Pre-review pass (independent reviewer)