perf(engine): segment-scope SDR→HDR preflight

[jrusso1020]

What

Scopes the SDR→HDR preflight re-encode to the segment the composition actually uses, mirroring the existing VFR→CFR segment-scope fix.

Why

convertSdrToHdr was re-encoding entire source files, so a 30-minute SDR screen recording contributing a 2-second clip in a mixed HDR/SDR composition ate multi-second preflight time that produced frames no one would ever read. Validated on a mixed 30s-SDR + 2s-HDR fixture: hdrPreflightMs drops 87% (1162→148ms), videoExtractMs drops 82% (1272→231ms), tmpPeakBytes drops 45% (8.2MB→4.5MB).

Depends on #444 (phase-level instrumentation) for the measurement surface.

How

• convertSdrToHdr gains startTime and duration parameters ahead of the upstream targetTransfer arg added by feat(engine): wire options.hdr through chunkEncoder + dynamic SDR→HDR transfer #370. New signature: convertSdrToHdr(input, output, startTime, duration, targetTransfer, signal, config). -ss $start -t $duration is added to the ffmpeg args.
• Phase 2 now captures the full VideoMetadata per resolvedVideos entry (previously just colorSpace) so the caller can compute segDuration from video.end - video.start with a fallback to metadata.durationSeconds - video.mediaStart for unbounded (Infinity) clips — without firing another ffprobe.
• After a successful convert, entry.video.mediaStart is zeroed out via shallow-copy (doesn't mutate the caller's VideoElement) so downstream extraction seeks from 0 instead of the original offset. Mirrors what the VFR→CFR path already does.

Test plan

Validation on /tmp/hf-fixtures/hdr-sdr-mixed-scope:

hdrPreflightMs: >1000 → 150   (gate: <300)   ✓
videoExtractMs: 1272  → 237   (-82%)
tmpPeakBytes:   8.2MB → 4.5MB (-45%)

• Unit test: new regression test synthesizes 10s SDR + 2s HDR fixture inline and asserts the converted file's duration matches the 2s used segment (pre-fix matched the 10s source)
• Lint + format
• Typecheck
• Manual perf validation against synthesized fixture

[jrusso1020]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• feat(cli): forward perf breakdown + tmpPeakBytes to PostHog telemetry #454
• perf(engine): content-addressed extraction cache for video frames #446
• perf(engine): segment-scope SDR→HDR preflight #445 👈 (View in Graphite)
• perf(engine): extraction-phase instrumentation #444
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[miguel-heygen]

Review: perf(engine): segment-scope SDR→HDR preflight

Correct approach — mirrors the established VFR segment-scope pattern. -ss before -i (input seeking), -t after -i, smart metadata reuse avoids extra ffprobe, shallow copy prevents caller mutation. The claimed perf numbers (87% drop in hdrPreflightMs) are consistent with scoping a 30-min transcode to 2 seconds.

P1 — Important (inherited, not a regression)

mediaStart beyond source duration → silent empty output. If entry.video.mediaStart > metadata.durationSeconds, -ss seeks past EOF and FFmpeg silently produces a 0-byte file. The subsequent entry.videoPath = convertedPath then points to a broken file. Same edge case exists in the VFR path. Since this code is being touched, worth adding:

if (startTime >= metadata.durationSeconds) { errors.push(...); continue; }

P2 — Should fix

No validation that duration > 0 before passing to FFmpeg. If end === start, segDuration = 0, FFmpeg receives -t 0, and silently produces an empty output. One-line guard:

if (duration <= 0) {
  throw new Error(`SDR→HDR conversion: duration must be positive (got ${duration})`);
}

P3 — Suggestions

• Test lives inside the "on a VFR source" describe block but is about HDR preflight scoping. A separate describe block (or renaming to something broader like "extractAllVideoFrames preflight normalization") would improve readability.
• Test uses extractVideoMetadata while production code uses extractMediaMetadata. If the latter is canonical going forward, the test should match.
• Benchmark reproducibility — the PR body references /tmp/hf-fixtures/hdr-sdr-mixed-scope which isn't committed. Consider adding a script reference for anyone wanting to reproduce the numbers.

Verdict: Approve with minor suggestions

Core change is correct and well-tested. Push for the duration > 0 guard — it's a one-line fix that prevents a silent failure mode.