feat(engine): add HDR video output pipeline

[vanceingalls]

Summary

Adds the ability to render HDR video output (H.265 10-bit, BT.2020) from HyperFrames compositions. When the renderer detects HDR source video, it automatically switches to the HDR output pipeline — no flags needed.

What it does

• Auto-detection — Probes each video source with ffprobe. If any has bt2020/PQ/HLG color metadata, the output switches to H.265 10-bit with correct color tags. SDR-only compositions are unaffected (H.264, bt709).
• HLG pass-through — Native HLG pixels from FFmpeg extraction are piped directly to the encoder without conversion. This avoids brightness loss from HLG→linear→PQ conversion (which requires an OOTF system gamma we can't reliably apply).
• Encoder HDR support — Both chunk and streaming encoders accept HDR presets: libx265, yuv420p10le, BT.2020 color primaries, hvc1 codec tag (required for Apple playback).
• WebGPU HDR capture (gated) — A complete WebGPU float16 readback pipeline is implemented and tested but gated behind headed Chrome (headless doesn't expose WebGPU). Ready for future use with WebGPU canvas content.
• HDR utilities — detectTransfer() (PQ vs HLG), getHdrEncoderColorParams(), analyzeCompositionHdr(). 15 unit tests.

Key design decisions

Decision	Why
No --hdr flag	SDR content encoded as HDR causes orange shift in browsers. Auto-detect eliminates this.
HLG pass-through (not HLG→PQ)	Conversion loses brightness without OOTF. Pass-through matches source exactly.
hvc1 codec tag	Apple QuickTime requires hvc1 (not hev1) for HEVC playback.
1-hour streaming timeout	HDR capture at ~6fps needs more time than the default 10-minute FFmpeg timeout.

Files changed

File	What changed
packages/engine/src/utils/hdr.ts	NEW — HDR detection, transfer types, encoder params (15 tests)
packages/engine/src/services/hdrCapture.ts	NEW — WebGPU readback, HLG conversion, PQ encode
packages/engine/src/services/streamingEncoder.ts	HDR presets, raw rgb48le input, color tags
packages/engine/src/services/chunkEncoder.ts	HDR presets, conditional color tags
packages/producer/src/services/renderOrchestrator.ts	Auto-detection loop, HDR pass-through capture path

How to test

Render a composition with an HDR video source. The output should be H.265 10-bit with HDR metadata visible in ffprobe (bt2020, arib-std-b67 or smpte2084). Plays correctly in QuickTime and on HDR displays.

Stack position

2 of 6 — Stacked on #258 (SDR/HDR normalization). Provides the encoder infrastructure that phases 1-5 build on.

🤖 Generated with Claude Code

[vanceingalls]

• feat(hdr): HDR image support, HDR10 metadata, and regression test harness #314
• feat(hdr): layered HDR compositing, shader transitions, and HDR image support #268
• feat(hdr): GSAP transforms and border-radius masks on HDR video #290
• feat(hdr): z-ordered multi-layer compositing with PQ support #289
• feat(engine): add HDR two-pass compositing — DOM layer + native HLG video #288
• feat(engine): add HDR video output pipeline #265 👈 (View in Graphite)
• main

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

[miguel-heygen]

Automated review (Claude Code)

Reviewed against CLAUDE.md. Three sibling reviews on the stack cover #288/#289/#290/#268/#314. Stack-level meta on #268.

Critical

• Shell injection — packages/producer/src/services/renderOrchestrator.ts:~1831. srcPath and localTime are interpolated directly into execSync("ffmpeg -ss ${localTime} -i \"${srcPath}\" …"). A filename containing ", $, or backtick breaks quoting and runs arbitrary commands. Use execFileSync("ffmpeg", [...]) / runFfmpeg with an argv array. #268 migrates to runFfmpeg — but #265 lands first.
• Silent failure swallows errors — same region, try { execSync(...) } catch { rawFrame = Buffer.alloc(width*height*8); }. Every ffmpeg error (missing file, codec error, abort) substitutes a black frame without log. Users get a silent black video. At minimum log.warn with frame index + path.
• Synchronous per-frame execSync blocks the event loop — one spawn per frame sequentially; a 30fps/1min clip = 1800 blocking ffmpeg spawns. This likely motivates the 1-hour streaming timeout — the timeout is masking an architectural problem. Use async streaming / single long-running ffmpeg.
• hdrCapture.ts:~756 — await import("puppeteer" as string) + silent catch {} fallback to puppeteer-core. The as string cast defeats TS resolution; the catch hides real import failures (e.g. broken puppeteer install). Distinguish ERR_MODULE_NOT_FOUND from other errors.

Important

• detectTransfer(null) → "hlg" (utils/hdr.ts:~1509) — returning HDR for SDR inputs is a lie. Callers who pass SDR get plausible HDR params back. Foot-gun; return null and let the type force a null-check.
• linearToPQ / float16ToPqRgb (hdrCapture.ts:~488-501) exported but untested. Opinionated constants (SDR_NITS=203) without reference values. Add tests.
• Orchestrator re-implements analyzeCompositionHdr inline (renderOrchestrator.ts:~1650-1661) instead of calling the helper it imports.
• videoFrameExtractor.ts:1117 — isHdrColorSpace "re-exported for backward compatibility" but there is no prior public export. Drop and import from utils/hdr.js at call sites.
• chunkEncoder.test.ts:267-281 — test name "uses bt709 color tags for HDR output" contradicts user expectation. Rename to reflect the real decision (Chrome-pixel path → bt709 even for HDR).

Suggestions

• WebGPU path (hdrCapture.ts:~709-796) is exported-but-unused by the ffmpeg pass-through path in this PR → rot risk. Move to the consuming PR or add an integration test.
• streamingEncoder.ts:~969 — Buffer.from(buffer) copy should be conditional on rawInputFormat; SDR path pays a memcpy it doesn't need.
• .gitignore churn (removing docs/images/, .agents/, .claude/skills/, captures/, *-capture/) is unrelated to HDR and could cause accidental commits. Split out.
• 1-hour streaming timeout is hiding the synchronous execSync above — should revert once async.
• Repo uses bun; the pnpm-lock.yaml / pnpm-workspace.yaml in git-status must not land.

Strengths

• utils/hdr.ts is clean and well-tested (SDR, HLG, PQ, mixed).
• ffprobe.ts color-space extension uses null (not fabricated defaults) — correct.
• Streaming encoder buffer-copy fix with clear explanatory comment is a real bug caught.
• Encoder preset test coverage covers mp4/webm/mov preset bleed-over.
• -tag:v hvc1 for QuickTime compatibility correctly noted.

🤖 Automated review. See stack meta-comment on #268 for cross-cutting findings.

[vanceingalls]

Thanks for the thorough review. Fixes landed.

Addressed:

• Shell injection / sync execSync / silent black-frame fallback — superseded by feat(hdr): layered HDR compositing, shader transitions, and HDR image support #268's migration to runFfmpeg (argv-based, signal-aware, no stdout limit). The log level for failures is log.warn now, not info/debug.
• puppeteer dynamic import — now distinguishes ERR_MODULE_NOT_FOUND from other errors before falling back to puppeteer-core. Broken installs surface instead of silently swapping.
• detectTransfer(null) → "hlg" — docstring now explicitly calls out the isHdrColorSpace precondition. Changing the return type to nullable would ripple through call sites and they all gate on isHdrColorSpace first in practice, so keeping the current shape is intentional.
• Orchestrator re-implementing analyzeCompositionHdr inline — refactored to call the helper. Also fixes the dominant-transfer correctness for mixed PQ+HLG (now picks PQ as dominant per the helper, not whichever came first).
• isHdrColorSpace re-export in videoFrameExtractor — removed. The index already exports it from utils/hdr directly. Test imports updated.
• chunkEncoder.test.ts name — renamed to reflect the actual assertion.
• linearToPQ / float16ToPqRgb tests — added packages/engine/src/services/hdrCapture.test.ts covering the buffer-size contract, black input, overbright clamp at the 1.0 PQ ceiling, channel ordering (alpha discarded), monotonicity, determinism, the 256-byte WebGPU bytesPerRow padding case, and trailing-padding garbage isolation. The clamp test uses a +1024.0 linear input rather than +2.0 because PQ encodes up to 10000 nits and SDR_NITS=203, so values below ~58× SDR white land mid-curve rather than at the ceiling.
• .gitignore churn — reverted in 95183c01 fix(hdr): restore .gitignore and revert package.json changes. The branch no longer touches .gitignore or package.json outside of intentional HDR work.

No-op:

• WebGPU path "rot risk" — re-exports now carry a docstring flagging them as experimental-path stubs with a clear remove-when condition.