Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
fix(engine): SDR content in HLG exports sits at reference white, not peak (#5749)
Miguel Ángeld796846d83fe
diff --git a/packages/engine/scripts/generate-lut-reference.py b/packages/engine/scripts/generate-lut-reference.pyindex 1c3ec19cf6..ea2dc900c2 100755--- a/packages/engine/scripts/generate-lut-reference.py+++ b/packages/engine/scripts/generate-lut-reference.py@@ -1,51 +1,15 @@#!/usr/bin/env python3"""-Regenerate the sRGB → BT.2020 (HLG/PQ) LUT reference values pinned by-packages/engine/src/utils/alphaBlit.test.ts.--This is a paste-helper for the *very rare* case the LUT genuinely needs to-shift — e.g. a spec update changes one of the OETF constants, or we change-the SDR-white reference level in the PQ branch. The reference values in-alphaBlit.test.ts are byte-exact integers, and updating ~12 hand-edited-literals (or all 256 of them, if the test grows) is exactly the kind of-mechanical churn we want to keep out of the diff.+Regenerate the byte-exact sRGB -> BT.2020 (HLG/PQ) probe table pinned in+packages/engine/src/utils/alphaBlit.test.ts (SRGB_TO_HDR_REFERENCE).Usage:- # Regenerate the probe table that lives in alphaBlit.test.ts (paste over- # the SRGB_TO_HDR_REFERENCE literal):- python3 packages/engine/scripts/generate-lut-reference.py --probes-- # Dump the full 256-entry LUTs as JSON (for ad-hoc analysis or new tests):- python3 packages/engine/scripts/generate-lut-reference.py-- # Override the probe set:- python3 packages/engine/scripts/generate-lut-reference.py --probes \- --probe-indices 0,32,64,128,192,255--## How to use this when the LUT changes--1. Edit buildSrgbToHdrLut() in packages/engine/src/utils/alphaBlit.ts.-2. Mirror the same edit here (constants, branch logic — keep them in sync).-3. Run with --probes and paste the output over SRGB_TO_HDR_REFERENCE in- alphaBlit.test.ts. Update the asymmetric-R/G/B and BT.2408-invariant- tests by hand if those probe values shifted.-4. Re-run `bun test src/utils/alphaBlit.test.ts` to confirm the engine LUT- and the test-pinned values still agree.--## Why Python (not TS)?--A standalone script avoids dragging the engine's bun/Node/build environment-into a one-off codegen flow, and matches the existing fixture-generation-pattern at packages/producer/tests/hdr-regression/scripts/generate-hdr-photo-pq.py.-Python's math.log / math.pow are libm-backed and produce IEEE-754-equivalent-results to JS's Math.log / Math.pow for these inputs — see js_round_nonneg-below for the one rounding quirk we have to match by hand.--## Drift contract+ python3 packages/engine/scripts/generate-lut-reference.py --probes # paste over the table+ python3 packages/engine/scripts/generate-lut-reference.py # full 256-entry LUTs as JSON-This file MIRRORS buildSrgbToHdrLut() in alphaBlit.ts. If the two diverge,-this script silently emits wrong values. Any change to one MUST be reflected-in the other; run the script and the test suite together to catch drift.+This file MIRRORS buildSrgbToSignalLut() in alphaBlit.ts: change both together,+then run alphaBlit.test.ts. js_round_nonneg matches JS Math.round, the one+rounding difference from Python."""import argparse@@ -58,6 +22,8 @@ from collections.abc import IterableHLG_A = 0.17883277HLG_B = 1 - 4 * HLG_AHLG_C = 0.5 - HLG_A * math.log(4 * HLG_A)+# BT.2408 SDR-reference white in HLG: the scene light (relative to peak) at 75% signal+HLG_SDR_WHITE = (math.exp((0.75 - HLG_C) / HLG_A) + HLG_B) / 12# PQ (SMPTE 2084) OETF constants — keep in sync with alphaBlit.tsPQ_M1 = 0.1593017578125@@ -90,9 +56,11 @@ def srgb_eotf(i: int) -> float:def hlg_oetf(linear: float) -> float:- if linear <= 1 / 12:- return math.sqrt(3 * linear)- return HLG_A * math.log(12 * linear - HLG_B) + HLG_C+ # Place SDR-reference white at 75% HLG signal (BT.2408), like PQ's 203 nits.+ scene = linear * HLG_SDR_WHITE+ if scene <= 1 / 12:+ return math.sqrt(3 * scene)+ return HLG_A * math.log(12 * scene - HLG_B) + HLG_Cdef pq_oetf(linear: float) -> float:diff --git a/packages/engine/src/utils/alphaBlit.test.ts b/packages/engine/src/utils/alphaBlit.test.tsindex 0890afb4a6..4dd84d3499 100644--- a/packages/engine/src/utils/alphaBlit.test.ts+++ b/packages/engine/src/utils/alphaBlit.test.ts@@ -88,6 +88,9 @@ function makePng(width: number, height: number, pixels: number[]): Buffer {// ── decodePng tests ──────────────────────────────────────────────────────────+/** sRGB 255 in an HLG frame: 75% signal, the BT.2408 SDR reference white. */+const HLG_SDR_WHITE = 49151;+describe("decodePng", () => {it("decodes a 1x1 RGBA PNG correctly", () => {// RGBA: red pixel, full opacity@@ -502,12 +505,9 @@ describe("blitRgba8OverRgb48le", () => {const dom = makeDomRgba(1, 1, 255, 128, 0, 255); // R=255, G=128, B=0, full opaqueblitRgba8OverRgb48le(dom, canvas, 1, 1);- // sRGB 255 → HLG 65535 (white maps to white)- // sRGB 128 → HLG ~46484 (mid-gray maps higher due to HLG OETF)- // sRGB 0 → HLG 0- expect(canvas.readUInt16LE(0)).toBe(65535);- expect(canvas.readUInt16LE(2)).toBeGreaterThan(40000); // HLG mid-gray > sRGB mid-gray- expect(canvas.readUInt16LE(2)).toBeLessThan(50000);+ // sRGB 255 → HLG reference white, 128 → 27146, 0 → 0+ expect(canvas.readUInt16LE(0)).toBe(HLG_SDR_WHITE);+ expect(canvas.readUInt16LE(2)).toBe(27146);expect(canvas.readUInt16LE(4)).toBe(0);});@@ -521,7 +521,7 @@ describe("blitRgba8OverRgb48le", () => {expect(canvas.readUInt16LE(4)).toBe(257);});- it("sRGB→HLG: black stays black, white stays white", () => {+ it("sRGB→HLG: black stays black, white lands on HLG reference white", () => {const canvasBlack = makeHdrFrame(1, 1, 0, 0, 0);const domBlack = makeDomRgba(1, 1, 0, 0, 0, 255);blitRgba8OverRgb48le(domBlack, canvasBlack, 1, 1);@@ -530,7 +530,7 @@ describe("blitRgba8OverRgb48le", () => {const canvasWhite = makeHdrFrame(1, 1, 0, 0, 0);const domWhite = makeDomRgba(1, 1, 255, 255, 255, 255);blitRgba8OverRgb48le(domWhite, canvasWhite, 1, 1);- expect(canvasWhite.readUInt16LE(0)).toBe(65535);+ expect(canvasWhite.readUInt16LE(0)).toBe(HLG_SDR_WHITE);});it("50% alpha: HLG-converted DOM blended with canvas", () => {@@ -540,9 +540,9 @@ describe("blitRgba8OverRgb48le", () => {const dom = makeDomRgba(1, 1, 255, 255, 255, 128);blitRgba8OverRgb48le(dom, canvas, 1, 1);- // sRGB 255 → HLG 65535, blended 50/50 with black+ // sRGB 255 → HLG reference white, blended 50/50 with blackconst alpha = 128 / 255;- const expectedR = Math.round(65535 * alpha);+ const expectedR = Math.round(HLG_SDR_WHITE * alpha);expect(canvas.readUInt16LE(0)).toBeCloseTo(expectedR, -1);});@@ -572,12 +572,12 @@ describe("blitRgba8OverRgb48le", () => {const nearR = canvasNear.readUInt16LE(0);// α=255 over black gave us the pure HLG-of-white value- expect(opaqueR).toBe(65535);+ expect(opaqueR).toBe(HLG_SDR_WHITE);// α=254 over (1000, 1000, 1000) must be *strictly less* than α=255 over black —- // if the implementation short-circuits at α >= 254 it would also return 65535.+ // if the implementation short-circuits at α >= 254 it would return the same value.expect(nearR).toBeLessThan(opaqueR);- // …but it should still be very close (within ~1% of full white)- expect(nearR).toBeGreaterThan(64000);+ // …but it should still be very close (within ~1% of white)+ expect(nearR).toBeGreaterThan(HLG_SDR_WHITE * 0.99);});it("handles a 2x2 frame correctly pixel-by-pixel", () => {@@ -592,10 +592,10 @@ describe("blitRgba8OverRgb48le", () => {blitRgba8OverRgb48le(dom, canvas, 2, 2);- // Pixel 0: sRGB white → HLG white (65535)- expect(canvas.readUInt16LE(0)).toBe(65535);- expect(canvas.readUInt16LE(2)).toBe(65535);- expect(canvas.readUInt16LE(4)).toBe(65535);+ // Pixel 0: sRGB white → HLG reference white+ expect(canvas.readUInt16LE(0)).toBe(HLG_SDR_WHITE);+ expect(canvas.readUInt16LE(2)).toBe(HLG_SDR_WHITE);+ expect(canvas.readUInt16LE(4)).toBe(HLG_SDR_WHITE);// Pixel 1: transparent DOM → canvas black (0, 0, 0) unchangedexpect(canvas.readUInt16LE(6)).toBe(0);@@ -649,12 +649,13 @@ describe("blitRgba8OverRgb48le with PQ transfer", () => {//// Two key invariants the table enforces://-// 1. HLG: sRGB 255 → 65535 (white maps to white in HLG signal space).+// 1. HLG: sRGB 255 → 49151 (75% signal, BT.2408 SDR reference white).+//+// 2. PQ: sRGB 255 → 38055 (≪ 65535). SDR white is placed at 203 nits per+// BT.2408, normalized against PQ's 10000-nit peak.//-// 2. PQ: sRGB 255 → 38055 (≪ 65535). NOT a bug — SDR white is placed at-// 203 nits per BT.2408, normalized against PQ's 10000-nit peak. This is-// what lets HDR highlights live above SDR-reference-white in a PQ frame.-// Never "fix" PQ to map sRGB 255 → 65535.+// Neither maps SDR white to peak: that is what lets HDR highlights live above+// SDR reference white. Never "fix" either to map sRGB 255 → 65535.//// To regenerate after an *intentional* LUT change (transfer-function constant,// BT.709→BT.2020 matrix tuning, SDR-white nit reference, OOTF), run:@@ -673,17 +674,17 @@ interface SrgbHdrProbe {const SRGB_TO_HDR_REFERENCE: readonly SrgbHdrProbe[] = [{ srgb: 0, hlg: 0, pq: 0 },- { srgb: 1, hlg: 1978, pq: 3315 },- { srgb: 10, hlg: 6254, pq: 8300 },- { srgb: 32, hlg: 13642, pq: 13884 },- { srgb: 64, hlg: 25702, pq: 19848 },- { srgb: 96, hlg: 38011, pq: 24379 },- { srgb: 128, hlg: 46484, pq: 28037 },- { srgb: 160, hlg: 52745, pq: 31104 },- { srgb: 192, hlg: 57772, pq: 33743 },- { srgb: 224, hlg: 61994, pq: 36057 },- { srgb: 254, hlg: 65428, pq: 37994 },- { srgb: 255, hlg: 65535, pq: 38055 },+ { srgb: 1, hlg: 1018, pq: 3315 },+ { srgb: 10, hlg: 3219, pq: 8300 },+ { srgb: 32, hlg: 7022, pq: 13884 },+ { srgb: 64, hlg: 13230, pq: 19848 },+ { srgb: 96, hlg: 19983, pq: 24379 },+ { srgb: 128, hlg: 27146, pq: 28037 },+ { srgb: 160, hlg: 34553, pq: 31104 },+ { srgb: 192, hlg: 40564, pq: 33743 },+ { srgb: 224, hlg: 45307, pq: 36057 },+ { srgb: 254, hlg: 49036, pq: 37994 },+ { srgb: 255, hlg: 49151, pq: 38055 },];describe("blitRgba8OverRgb48le: sRGB → BT.2020 reference values", () => {@@ -712,9 +713,9 @@ describe("blitRgba8OverRgb48le: sRGB → BT.2020 reference values", () => {const canvas = makeHdrFrame(1, 1, 0, 0, 0);const dom = makeDomRgba(1, 1, 64, 128, 192, 255);blitRgba8OverRgb48le(dom, canvas, 1, 1, "hlg");- expect(canvas.readUInt16LE(0)).toBe(25702);- expect(canvas.readUInt16LE(2)).toBe(46484);- expect(canvas.readUInt16LE(4)).toBe(57772);+ expect(canvas.readUInt16LE(0)).toBe(13230);+ expect(canvas.readUInt16LE(2)).toBe(27146);+ expect(canvas.readUInt16LE(4)).toBe(40564);});it("PQ: asymmetric R/G/B maps each channel independently through the LUT", () => {@@ -726,12 +727,11 @@ describe("blitRgba8OverRgb48le: sRGB → BT.2020 reference values", () => {expect(canvas.readUInt16LE(4)).toBe(33743);});- it("PQ caps SDR-reference-white well below HLG signal peak (BT.2408 invariant)", () => {- // sRGB 255 (SDR white) → HLG 65535 (top of HLG signal range)+ it("both transfers place SDR white at BT.2408 reference white, below peak", () => {+ // sRGB 255 (SDR white) → HLG 49151 (75% of HLG signal)// → PQ 38055 (~58% of PQ signal, ~203 nits)- // The gap is what lets PQ carry HDR highlights above SDR reference level.- // Locking the exact PQ value here prevents a future "fix" that would- // re-scale PQ to peak-at-SDR-white (which would clip every real HDR pixel).+ // The headroom is what carries HDR highlights above SDR reference level;+ // at peak, a grade or white text on HLG footage blows out.const canvasHlg = makeHdrFrame(1, 1, 0, 0, 0);const canvasPq = makeHdrFrame(1, 1, 0, 0, 0);const dom = makeDomRgba(1, 1, 255, 255, 255, 255);@@ -739,9 +739,8 @@ describe("blitRgba8OverRgb48le: sRGB → BT.2020 reference values", () => {blitRgba8OverRgb48le(dom, canvasHlg, 1, 1, "hlg");blitRgba8OverRgb48le(dom, canvasPq, 1, 1, "pq");- expect(canvasHlg.readUInt16LE(0)).toBe(65535);+ expect(canvasHlg.readUInt16LE(0)).toBe(49151);expect(canvasPq.readUInt16LE(0)).toBe(38055);- expect(canvasPq.readUInt16LE(0)).toBeLessThan(canvasHlg.readUInt16LE(0));});});@@ -1049,11 +1048,11 @@ describe("decodePng + blitRgba8OverRgb48le integration", () => {const canvas = makeHdrFrame(width, height, 50000, 40000, 30000);blitRgba8OverRgb48le(domRgba, canvas, width, height);- // sRGB blue (0,0,255) → HLG (0, 0, 65535) — black/white map identically+ // sRGB blue (0,0,255) → HLG (0, 0, reference white): each channel maps alonefor (let i = 0; i < width * height; i++) {expect(canvas.readUInt16LE(i * 6 + 0)).toBe(0);expect(canvas.readUInt16LE(i * 6 + 2)).toBe(0);- expect(canvas.readUInt16LE(i * 6 + 4)).toBe(65535);+ expect(canvas.readUInt16LE(i * 6 + 4)).toBe(HLG_SDR_WHITE);}});});diff --git a/packages/engine/src/utils/alphaBlit.ts b/packages/engine/src/utils/alphaBlit.tsindex 99abcf51fa..313be57dc2 100644--- a/packages/engine/src/utils/alphaBlit.ts+++ b/packages/engine/src/utils/alphaBlit.ts@@ -284,17 +284,9 @@ export function decodePngToRgb48le(buf: Buffer): { width: number; height: number* ## Convention** "Linear" here means **scene light in [0, 1] relative to SDR reference white**- * (not absolute nits). The HLG branch applies the OETF directly — no OOTF (no- * gamma 1.2 scene→display conversion). This is the right choice for DOM- * overlays that will be composited ON TOP of HLG video pixels (which are- * already in HLG signal space); we need the overlay to sit in the same space- * as what it’s blending onto. Applying the OOTF here would double-apply it- * when the HDR video already carries scene-light semantics.- *- * For PQ, SDR white is placed at 203 nits per ITU-R BT.2408 ("SDR white"- * reference level) and normalized against 10,000-nit peak. This lets SDR- * content (text, UI) sit at the conventional SDR-white brightness within a- * PQ frame rather than at peak brightness.+ * (not absolute nits). Both branches put SDR white at BT.2408 reference white,+ * below peak: HLG at 75% signal (the OETF takes peak-relative light, so it is+ * scaled first; no OOTF), PQ at 203 nits of the 10,000-nit peak.** Note: converts the transfer function but not the color primaries (bt709 →* bt2020). For neutral/near-neutral content (text, UI) the gamut difference@@ -313,6 +305,7 @@ function buildSrgbToSignalLut(transfer: "hlg" | "pq" | "srgb"): Uint16Array {const hlgA = 0.17883277;const hlgB = 1 - 4 * hlgA;const hlgC = 0.5 - hlgA * Math.log(4 * hlgA);+ const hlgSdrWhite = (Math.exp((0.75 - hlgC) / hlgA) + hlgB) / 12;// PQ (SMPTE 2084) OETF constantsconst pqM1 = 0.1593017578125;@@ -333,8 +326,8 @@ function buildSrgbToSignalLut(transfer: "hlg" | "pq" | "srgb"): Uint16Array {let signal: number;if (transfer === "hlg") {- signal =- linear <= 1 / 12 ? Math.sqrt(3 * linear) : hlgA * Math.log(12 * linear - hlgB) + hlgC;+ const scene = linear * hlgSdrWhite;+ signal = scene <= 1 / 12 ? Math.sqrt(3 * scene) : hlgA * Math.log(12 * scene - hlgB) + hlgC;} else {// PQ OETF: linear light (in SDR nits) → PQ signalconst Lp = Math.max(0, (linear * sdrNits) / pqMaxNits);