fix(engine): auto-normalize VFR video inputs to CFR before frame extraction

[jrusso1020]

What

Auto-normalize variable-frame-rate (VFR) video inputs to constant-frame-rate (CFR) before the frame-extraction stage, eliminating the "frozen screen recording" class of bugs in rendered compositions.

Why

A user reported on X that their screen-recording scenes were freezing in hyperframes renders. Investigation:

• macOS ScreenCaptureKit, QuickTime screen recordings, and phone videos all emit VFR by default (frames written only on content change).
• The extractor at packages/engine/src/services/videoFrameExtractor.ts:142 runs ffmpeg -ss <start> -i <video> -t <dur> -vf fps=N on the input.
• On VFR inputs, the fps filter exhibits two failure modes:
  1. Frame-count shortfall: for a 4-second segment at 30fps starting mid-file, output was ~90 frames instead of 120. FrameLookupTable.getFrameAtTime (line 440) returns null for out-of-range indices, so the compositor holds the last valid frame — the user sees a freeze.
  2. Duplicate-frame runs: 32-39% of output frames were duplicates on realistic VFR fixtures, because the fps filter snaps multiple outputs to the same nearest source frame.

The engine already detects VFR via metadata.isVFR (packages/engine/src/utils/ffprobe.ts:257) but never acted on it — the compiler only logged a warning telling users to manually re-encode.

How

Mirrored the existing SDR→HDR normalization pattern in the same file. When metadata.isVFR === true, re-encode the used segment to CFR before extraction:

ffmpeg -ss <mediaStart> -i <video> -t <duration> \
       -fps_mode cfr -r <targetFps> \
       -c:v libx264 -preset fast -crf 18 \
       -c:a copy -y <normalized.mp4>

Scoping to [mediaStart, mediaStart+duration] rather than full-file means a 30-second clip cut from a 60-minute screen recording pays ~1s of transcode cost, not 18s.

Benchmarked locally on a synthesized VFR fixture (10s of testsrc2 with ~40% frames dropped, sparse keyframes every 10s):

Strategy	Dupe rate	Frame-count shortfall
Baseline (before)	32-39%	25% shortfall on mid-segments
Flag changes only (-fps_mode cfr, -r vs -vf fps=N, accurate seek)	~same	still short
CFR preflight (this PR)	1.7-6%	perfect frame count

The flag-only tweaks were tested and insufficient — the fps filter's VFR handling is the underlying issue, not the seek mode or output-rate flag. Pre-encoding is the fix experiment-framework already uses internally for the same reason (see worker/celery/movio/utils/ffmpeg_utils.py reencode_video_if_potentially_vfr).

The compiler warning that used to tell users to manually re-encode VFR videos is downgraded from console.warn to console.info since the engine now handles it; the message still mentions the pre-encode command for users who want to skip the per-render transcode cost.

Test plan

• Unit tests added: packages/engine/src/services/videoFrameExtractor.test.ts
  • Detects the fixture as VFR.
  • Regression test: mid-file segment produces expected frame count (120 @ 4s × 30fps, previously ~90).
  • Full-file case produces expected frame count (300 @ 10s × 30fps).
• All 311 existing engine tests still pass.
• Typecheck, lint, format clean.
• Manual validation against the user's actual screen recording (once Miguel gets the repro file from the reporter).

— Rames Jusso

[miguel-heygen]

I'd add a regression test just in case