feat(engine): wire options.hdr through chunkEncoder + dynamic SDR→HDR transfer

[vanceingalls]

Summary

Three independent fixes that share a common thread: HDR config flowing correctly from EngineConfig down through every encoder. The headline fix: disk-based HDR encodes via chunkEncoder were silently producing BT.709-tagged output despite options.hdr being set.

Why

Chunk 3 of plans/hdr-followups.md. The streaming encoder was correct but chunkEncoder.buildEncoderArgs hard-coded BT.709 color tags and the bt709 VUI block in -x265-params, even when callers passed an HDR EncoderOptions. Today this is harmless because renderOrchestrator routes native-HDR content to streamingEncoder and only feeds chunkEncoder sRGB Chrome screenshots — but the contract was a lie, and any future caller that wired HDR through chunkEncoder would silently get SDR output.

What changed

3A — chunkEncoder respects options.hdr (BT.2020 + mastering metadata). When options.hdr is set, the libx265 software path emits bt2020nc plus the matching transfer (smpte2084 for PQ, arib-std-b67 for HLG) at the codec level and embeds master-display + max-cll SEI in -x265-params via getHdrEncoderColorParams. libx264 still tags BT.709 inside -x264-params (libx264 has no HDR support) but the codec-level color flags flip so the container describes pixels truthfully. GPU H.265 (nvenc/videotoolbox/qsv/vaapi) gets the BT.2020 tags but no -x265-params block, so static mastering metadata is omitted — acceptable for previews, not HDR-aware delivery.

3B — convertSdrToHdr accepts a target transfer. videoFrameExtractor.convertSdrToHdr was hard-coded to transfer=arib-std-b67 (HLG) regardless of the surrounding composition's dominant transfer. extractAllVideoFrames now calls analyzeCompositionHdr first, then passes the dominant transfer ("pq" or "hlg") into convertSdrToHdr so an SDR clip mixed into a PQ timeline gets converted with smpte2084, not arib-std-b67.

3C — EngineConfig.hdr type matches its declared shape. The IIFE for the hdr field returned undefined when PRODUCER_HDR_TRANSFER wasn't "hlg" or "pq", but the field is typed as { transfer: HdrTransfer } | false. Returning false matches the type and avoids a downstream undefined check.

Test plan

• chunkEncoder.test.ts: replaced the previous "HDR options ignored" assertions with 8 new specs covering BT.2020 + transfer tagging, master-display/max-cll embedding, libx264 fallback behavior, GPU H.265 + HDR (tags but no x265-params), and range conversion for both SDR and HDR CPU paths.
• All 313 engine unit tests pass (5 new HDR specs).
• ffprobe an HDR composition rendered through the chunk encoder path: shows bt2020nc color matrix, smpte2084 transfer, and mastering display metadata.

Stack

Chunk 3 of plans/hdr-followups.md. Independent of Chunks 1/4 (touches separate code paths).

[vanceingalls]

• docs(engine): document __name polyfill and add regression test #385
• perf(producer): cache transfer-converted hdr image buffers per render job #384
• perf(producer): gate per-frame debug meta via optional isLevelEnabled #383
• perf(producer): hdr benchmark harness — --tags filter, peak heap/RSS tracking, bench:hdr script #382
• test(producer): extract frameDirMaxIndexCache to its own module and pin cross-job isolation #381
• test(engine): cover spawnStreamingEncoder lifecycle and cleanup paths #380
• test(engine): add ffprobe-unavailable fallback regression tests #379
• test(shader-transitions): add midpoint (p=0.5) regression invariants for all shaders #378
• test(engine): lock down sRGB→BT.2020 LUT with byte-exact reference values #377
• build(lfs): track tests/*/src/*.png via Git LFS #376
• test(hdr-regression): tighten Window F maxFrameFailures budget after Chunk 4 fix #375
• fix(engine,shader): handle matrix3d transforms and hide non-first scenes #374
• refactor(producer): extract HDR compositing helpers and rename media metadata #373
• fix(producer): wire --crf and --video-bitrate CLI overrides into encoders #372
• fix(producer): tighten resource lifecycle and harden file server #371
• feat(engine): wire options.hdr through chunkEncoder + dynamic SDR→HDR transfer #370 👈 (View in Graphite)
• test(hdr-regression): tighten Window C maxFrameFailures budget after Chunk 1 fix #369
• fix(engine): stop clobbering native <video> opacity in HDR pipeline #368
• refactor(shader-transitions): extract DEFAULT_DURATION and DEFAULT_EASE constants #367
• refactor(types): tighten type safety, dedupe HfTransitionMeta, prune dead LUT export #366
• test(producer): add hdr-regression and hdr-hlg-regression test suites #365
• main

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

[jrusso1020]

This is the correctness fix I'm happiest to see in this stack. The prior chunkEncoder was actively lying about color space — hardcoding colorprim=bt709:transfer=bt709:colormatrix=bt709 in -x265-params even when the caller passed an HDR EncoderOptions. Any HDR-aware player would interpret the stream via BT.709 tone-mapping and render it as SDR; HDR TVs would show a washed-out, mis-gamma'd signal. The fact that this didn't fire in production is purely because renderOrchestrator kept HDR content on the streamingEncoder path today, but calling that "defended by routing" is fragile — the contract was wrong.

Three things to call out:

3A — SW vs GPU H.265 split is documented honestly. SW libx265 gets BT.2020 color tags + HDR static mastering metadata (master-display, max-cll SEI). GPU paths (nvenc, videotoolbox, qsv, vaapi) get the color tags but no mastering metadata because ffmpeg doesn't let you push -x265-params through hardware encoders. The PR body calls this out explicitly as "acceptable for previews, not HDR-aware delivery" — that's the right framing. For a production HDR pipeline this is worth a doc note somewhere (README? HDR guide?) so downstream callers don't assume useGpu=true + hdr={transfer: "pq"} produces a fully spec-compliant HDR10 stream.

3B — mixed-transfer composition edge case. convertSdrToHdr now takes dominant transfer from analyzeCompositionHdr. If a composition contains both PQ and HLG HDR sources (rare but legal), "dominant" wins and the non-dominant set gets converted with the wrong transfer. Worth a brief comment at the call site noting that mixed-transfer compositions are caller-error territory, or explicitly validating that analyzeCompositionHdr returns a non-null transfer only when all sources agree.

3C — type safety. Flipping hdr: undefined → hdr: false to match the declared { transfer } | false shape is the right kind of small hygiene fix. Worth verifying there are no if (config.hdr) call sites that were relying on undefined vs false coercion (both falsy, same branch behavior, so should be fine — but it's the kind of thing a static analyzer would flag). Tests pass, so this is confirmed.

libx264 + HDR is a landmine to document. With this PR, calling buildEncoderArgs with codec: "h264" + hdr: { transfer: "pq" } produces a file with BT.2020 codec-level tags but bt709 in the x264-params VUI block. Technically honest (libx264 truly can't encode HDR), but some players get confused by the VUI/container mismatch. Consider making chunkEncoder.ts explicitly warn-and-strip HDR when codec=h264, or throwing upstream so no one accidentally gets a half-HDR artifact.

Test coverage is exactly right — 8 specs across the matrix (HLG/PQ × SW/GPU × h264/h265). Approved.

— Rames Jusso

[vanceingalls]

Merge activity

• Apr 23, 3:36 AM UTC: @vanceingalls merged this pull request with Graphite.