Skip to content

Write HTML. Render video. Built for agents.

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.py
index 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 Iterable
HLG_A = 0.17883277
HLG_B = 1 - 4 * HLG_A
HLG_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.ts
PQ_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_C
def pq_oetf(linear: float) -> float:
diff --git a/packages/engine/src/utils/alphaBlit.test.ts b/packages/engine/src/utils/alphaBlit.test.ts
index 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 opaque
blitRgba8OverRgb48le(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 black
const 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) unchanged
expect(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 alone
for (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.ts
index 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 constants
const 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 signal
const Lp = Math.max(0, (linear * sdrNits) / pqMaxNits);