Open source CapCut alternative.
TypeScript
fix(site): convert HLG and PQ to SDR through the BT.2100 OOTF [rebuild]
David Le11d21763f410
diff --git a/docs/guides/cut/color.md b/docs/guides/cut/color.mdindex 1eb71775..09ed0157 100644--- a/docs/guides/cut/color.md+++ b/docs/guides/cut/color.md@@ -8,9 +8,9 @@ A clip's color is one recipe: what its code values mean (the source profile), thEvery video carries a source profile, read from its header at import: Apple Log and Log 2 by Apple's metadata identifier, HLG and PQ by the transfer tag beside a BT.2020 matrix, sRGB by its transfer, Rec.709 otherwise. The Color panel shows the detection and takes a per-asset override.-Rec.709 and sRGB sources draw as they are. A Log or HDR source goes through the ACES 2.0 output transform first, so the grade and any creative LUT see a Rec.709 picture. A technical Log→Rec.709 LUT is a conversion of its own: it goes on a clip whose source is set to "Rec.709 (no conversion)".+Rec.709 and sRGB sources draw as they are. Log goes through the ACES 2.0 output transform, HLG and PQ through the BT.2100 OOTF on a 100-nit display, so the grade and any creative LUT see a Rec.709 picture. A technical Log→Rec.709 LUT is a conversion of its own: it goes on a clip whose source is set to "Rec.709 (no conversion)".-That needs the code values untouched, and a browser converts a decoded frame by its bitstream tags before anything can draw it, so the parameter set's tags are rewritten to neutral Rec.709 / sRGB before the decoder sees them. The matrix a decoder then draws with differs by browser, so each route is measured once per session on a small fixture and the clip's LUT undoes it before applying the file's own. ffmpeg and headless renders read the file's matrix and need no fix. ProRes masters and their preview proxies are in [Local Compute](local-compute.md). Start in the source color module.+That needs the code values untouched, and a browser converts a decoded frame by its bitstream tags, so the parameter set's tags are rewritten to neutral Rec.709 / sRGB before the decoder sees them. The matrix a decoder draws with differs by browser, so each route is measured once per session and the clip's LUT undoes it before applying the file's own. ffmpeg and headless renders read the file's matrix and need no fix. ProRes masters and their preview proxies are in [Local Compute](local-compute.md).## LUTsdiff --git a/site/packages/effects-kit/src/colorPipeline.test.ts b/site/packages/effects-kit/src/colorPipeline.test.tsindex fec65d8c..d7df9e94 100644--- a/site/packages/effects-kit/src/colorPipeline.test.ts+++ b/site/packages/effects-kit/src/colorPipeline.test.ts@@ -15,7 +15,7 @@ import {recipeKey,sourceTransform,} from "./colorPipeline";-import { BT2408_HLG_WHITE, appleLogEncode, bt1886Encode, pqEncode } from "./colorSpace";+import { BT2408_HLG_WHITE, appleLogEncode, bt1886Encode, pqEncode, sdrToHlg } from "./colorSpace";import { applyLutToImageData } from "./gradeLut";import type { ParsedLut } from "./lutFile";@@ -106,8 +106,19 @@ describe("source conversion", () => {neutral(hlg);neutral(pq);expect(Math.abs(hlg[0] - pq[0])).toBeLessThan(2e-3);- // The BT.2408 reference white lands where ACES puts diffuse white.- expect(Math.abs(hlg[0] - 0.722)).toBeLessThan(2e-3);+ // The BT.2408 reference white lands near 0.6, leaving the top of the+ // range to the highlights.+ expect(Math.abs(hlg[0] - 0.6056)).toBeLessThan(2e-3);+ });++ test("an HLG source keeps its hues in SDR", () => {+ // Pure Rec.709 red, as an iPhone records a red screen: the red channel+ // carries it alone after the conversion, with no drift toward orange.+ const red = sdrToHlg(0.6, 0, 0);+ const out = sourceTransform("hlg", "sdr")!(...red);+ expect(out[0]).toBeGreaterThan(0.5);+ expect(out[1]).toBeLessThan(0.01);+ expect(out[2]).toBeLessThan(0.01);});test("an HDR source delivered in its own encoding is left alone, graded in place", () => {diff --git a/site/packages/effects-kit/src/colorPipeline.ts b/site/packages/effects-kit/src/colorPipeline.tsindex 5fbdee92..ac6cc5b6 100644--- a/site/packages/effects-kit/src/colorPipeline.ts+++ b/site/packages/effects-kit/src/colorPipeline.ts@@ -8,9 +8,10 @@* encoding; Apple Log and Apple Log 2 decode to scene-linear ACES and go* through the ACES 2.0 output transform — the Rec.709 100-nit transform* for an SDR project, the Rec.2100 1000-nit HLG one when the project- * delivers HDR; HLG and PQ take the same transform into SDR, and cross- * into each other through the BT.2100 transfer at 1000 nits, so an HDR- * source keeps its range)+ * delivers HDR; HLG and PQ are display-referred, so they reach SDR+ * through the BT.2100 OOTF on a 100-nit display, and cross into each+ * other through the transfer at 1000 nits, so an HDR source keeps its+ * range)* 2 the clip's library LUT, mixed by its amount* 3 the grade (preset layer, then manual), gradeMath.ts* 4 output: SDR as is; an SDR source delivered as HDR takes the BT.2408@@ -34,8 +35,8 @@ import {AP0_PRIMARIES,APPLE_WIDE_GAMUT_PRIMARIES,BRADFORD,- HLG_SCENE_WHITE,REC2020_PRIMARIES,+ REC709_PRIMARIES,appleLogDecode,bt1886Decode,hlgOetf,@@ -49,6 +50,7 @@ import {rgbToRgbMatrix,sdrToHlg,sdrToPq,+ srgbEncode,} from "./colorSpace";import { type GradeLut, GRADE_LUT_SIZE, stableJson } from "./gradeLut";import { type GradeTransform, createGradeTransform } from "./gradeMath";@@ -191,13 +193,14 @@ const clamp01 = (v: number) => (v < 0 ? 0 : v > 1 ? 1 : v);const REC2020_TO_AP0 = rgbToRgbMatrix(REC2020_PRIMARIES, AP0_PRIMARIES, BRADFORD);const AWG_TO_AP0 = rgbToRgbMatrix(APPLE_WIDE_GAMUT_PRIMARIES, AP0_PRIMARIES, BRADFORD);-const HLG_TO_ACES_SCALE = 1 / HLG_SCENE_WHITE;+const REC2020_TO_REC709 = rgbToRgbMatrix(REC2020_PRIMARIES, REC709_PRIMARIES);+const SDR_PEAK_NITS = 100;function acesPresetFor(output: OutputSpace): AcesOutputPresetId {return output === "hlg" ? "rec2100-hlg-1000" : output === "pq" ? "rec2100-pq-1000" : "rec709-100";}-/** Code values → scene-linear AP0 for the profiles that carry a scene. */+/** Code values → scene-linear AP0 for the log profiles. */function sceneDecoder(profile: SourceProfile): ((r: number, g: number, b: number) => [number, number, number]) | null {const toAp0 = (m: Mat3, r: number, g: number, b: number): [number, number, number] => [m[0] * r + m[1] * g + m[2] * b,@@ -209,23 +212,6 @@ function sceneDecoder(profile: SourceProfile): ((r: number, g: number, b: numberreturn (r, g, b) => toAp0(REC2020_TO_AP0, appleLogDecode(r), appleLogDecode(g), appleLogDecode(b));case "apple-log-2":return (r, g, b) => toAp0(AWG_TO_AP0, appleLogDecode(r), appleLogDecode(g), appleLogDecode(b));- case "hlg":- // BT.2100 inverse OETF gives the HLG scene; BT.2408 puts its reference- // white at the 75% signal, and ACES puts diffuse white at 1.0.- return (r, g, b) =>- toAp0(- REC2020_TO_AP0,- hlgOetfInverse(r) * HLG_TO_ACES_SCALE,- hlgOetfInverse(g) * HLG_TO_ACES_SCALE,- hlgOetfInverse(b) * HLG_TO_ACES_SCALE- );- case "pq":- // PQ is display-referred: the ST 2084 EOTF gives nits, and the BT.2390- // inverse OOTF for a 1000-nit display recovers the HLG scene.- return (r, g, b) => {- const [rs, gs, bs] = hlgOotfInverse(pqDecode(r), pqDecode(g), pqDecode(b), 1000);- return toAp0(REC2020_TO_AP0, rs * HLG_TO_ACES_SCALE, gs * HLG_TO_ACES_SCALE, bs * HLG_TO_ACES_SCALE);- };default:return null;}@@ -246,6 +232,18 @@ export function pqToHlg(r: number, g: number, b: number): [number, number, numbereturn [hlgOetf(rs), hlgOetf(gs), hlgOetf(bs)];}+/** HLG signal → SDR signal: the HLG picture on a 100-nit display, the+ * BT.2100 OOTF at that peak's system gamma with HLG's peak at SDR white,+ * moved into Rec.709 primaries, clipped and sRGB-encoded. Display-referred,+ * so hue and contrast hold; the rendition a phone's own player shows on an+ * SDR screen, within a level or two. */+export function hlgToSdr(r: number, g: number, b: number): [number, number, number] {+ const k = 1 / SDR_PEAK_NITS;+ const [rd, gd, bd] = hlgOotf(hlgOetfInverse(r), hlgOetfInverse(g), hlgOetfInverse(b), SDR_PEAK_NITS);+ const [x, y, z] = mat3Apply(REC2020_TO_REC709, rd * k, gd * k, bd * k);+ return [srgbEncode(clamp01(x)), srgbEncode(clamp01(y)), srgbEncode(clamp01(z))];+}+/** The source conversion for a profile into the output's display values, or* null when the source already is display values in the grade's container.* A drawn matrix that differs from the file's is undone first. An HDR file@@ -258,8 +256,15 @@ export function sourceTransform(): GradeTransform | null {const fix = needsMatrixFix(drawn) ? matrixFixTransform(drawn) : null;if (recipeIsIdentity(profile, output)) return fix;- if (isHdrSource(profile) && output !== "sdr") {- const cross = output === "pq" ? hlgToPq : pqToHlg;+ if (isHdrSource(profile)) {+ const cross =+ output === "sdr"+ ? profile === "pq"+ ? (r: number, g: number, b: number) => hlgToSdr(...pqToHlg(r, g, b))+ : hlgToSdr+ : output === "pq"+ ? hlgToPq+ : pqToHlg;return (r, g, b) => {const [fr, fg, fb] = fix ? fix(r, g, b) : [r, g, b];return cross(clamp01(fr), clamp01(fg), clamp01(fb));diff --git a/site/packages/effects-kit/src/colorSpace.ts b/site/packages/effects-kit/src/colorSpace.tsindex 5d8f35e4..8c4f0eaa 100644--- a/site/packages/effects-kit/src/colorSpace.ts+++ b/site/packages/effects-kit/src/colorSpace.ts@@ -15,7 +15,8 @@/* ------------------------------------------------------------------ *//** What a clip's code values mean. The first two need no conversion; the- * rest go through a scene-linear decode and the ACES 2.0 output transform. */+ * log profiles go through the ACES 2.0 output transform, HLG and PQ through+ * the BT.2100 OOTF. */export type SourceProfile = "rec709" | "srgb" | "apple-log" | "apple-log-2" | "hlg" | "pq";export const SOURCE_PROFILES: { id: SourceProfile; label: string; detail: string }[] = [@@ -230,9 +231,17 @@ export function hlgOetfInverse(s: number): number {return s <= 0.5 ? (s * s) / 3 : (Math.exp((s - HLG_C) / HLG_A) + HLG_B) / 12;}-/** BT.2100 HLG system gamma for a display of the given peak (1.2 at 1000 nits). */+/** HLG system gamma for a display of the given peak (1.2 at 1000 nits):+ * BT.2100's formula across its 400–2000 nit range, BT.2390's extended one+ * outside it (0.846 on a 100-nit SDR display). */export function hlgGamma(peakNits = 1000): number {- return 1.2 + 0.42 * Math.log10(peakNits / 1000);+ if (peakNits >= 400 && peakNits <= 2000) return 1.2 + 0.42 * Math.log10(peakNits / 1000);+ return 1.2 * Math.pow(1.111, Math.log2(peakNits / 1000));+}++/** sRGB transfer: display-linear → signal. */+export function srgbEncode(l: number): number {+ return l <= 0.0031308 ? 12.92 * l : 1.055 * Math.pow(l, 1 / 2.4) - 0.055;}const REC2020_LUMA = [0.2627, 0.678, 0.0593];