@hyperframes/engine 0.4.6 → 0.4.8

package/src/utils/hdr.test.ts

@@ -0,0 +1,191 @@
+import { describe, expect, it } from "vitest";
+import {
+  isHdrColorSpace,
+  detectTransfer,
+  getHdrEncoderColorParams,
+  analyzeCompositionHdr,
+  DEFAULT_HDR10_MASTERING,
+} from "./hdr.js";
+import type { VideoColorSpace } from "./ffprobe.js";
+
+describe("isHdrColorSpace", () => {
+  it("returns false for null", () => {
+    expect(isHdrColorSpace(null)).toBe(false);
+  });
+
+  it("returns false for bt709 SDR", () => {
+    expect(
+      isHdrColorSpace({ colorTransfer: "bt709", colorPrimaries: "bt709", colorSpace: "bt709" }),
+    ).toBe(false);
+  });
+
+  it("detects bt2020 primaries", () => {
+    expect(
+      isHdrColorSpace({ colorTransfer: "bt709", colorPrimaries: "bt2020", colorSpace: "bt709" }),
+    ).toBe(true);
+  });
+
+  it("detects smpte2084 (PQ)", () => {
+    expect(
+      isHdrColorSpace({
+        colorTransfer: "smpte2084",
+        colorPrimaries: "bt2020",
+        colorSpace: "bt2020nc",
+      }),
+    ).toBe(true);
+  });
+
+  it("detects arib-std-b67 (HLG)", () => {
+    expect(
+      isHdrColorSpace({
+        colorTransfer: "arib-std-b67",
+        colorPrimaries: "bt2020",
+        colorSpace: "bt2020nc",
+      }),
+    ).toBe(true);
+  });
+});
+
+describe("detectTransfer", () => {
+  it("returns hlg for null", () => {
+    expect(detectTransfer(null)).toBe("hlg");
+  });
+
+  it("returns pq for smpte2084", () => {
+    expect(
+      detectTransfer({
+        colorTransfer: "smpte2084",
+        colorPrimaries: "bt2020",
+        colorSpace: "bt2020nc",
+      }),
+    ).toBe("pq");
+  });
+
+  it("returns hlg for arib-std-b67", () => {
+    expect(
+      detectTransfer({
+        colorTransfer: "arib-std-b67",
+        colorPrimaries: "bt2020",
+        colorSpace: "bt2020nc",
+      }),
+    ).toBe("hlg");
+  });
+
+  it("returns hlg for bt709 (fallback)", () => {
+    expect(
+      detectTransfer({ colorTransfer: "bt709", colorPrimaries: "bt709", colorSpace: "bt709" }),
+    ).toBe("hlg");
+  });
+});
+
+describe("getHdrEncoderColorParams", () => {
+  it("returns PQ params with mastering metadata", () => {
+    const params = getHdrEncoderColorParams("pq");
+    expect(params.colorTrc).toBe("smpte2084");
+    expect(params.colorPrimaries).toBe("bt2020");
+    expect(params.colorspace).toBe("bt2020nc");
+    expect(params.pixelFormat).toBe("yuv420p10le");
+    expect(params.x265ColorParams).toContain("colorprim=bt2020");
+    expect(params.x265ColorParams).toContain("transfer=smpte2084");
+    expect(params.x265ColorParams).toContain("colormatrix=bt2020nc");
+    expect(params.mastering).toEqual(DEFAULT_HDR10_MASTERING);
+  });
+
+  it("returns HLG params with mastering metadata", () => {
+    const params = getHdrEncoderColorParams("hlg");
+    expect(params.colorTrc).toBe("arib-std-b67");
+    expect(params.colorPrimaries).toBe("bt2020");
+    expect(params.pixelFormat).toBe("yuv420p10le");
+    expect(params.x265ColorParams).toContain("transfer=arib-std-b67");
+    expect(params.mastering).toEqual(DEFAULT_HDR10_MASTERING);
+  });
+
+  // Regression guard for the side_data=[none] bug. See
+  // packages/producer/scripts/hdr-smoke.ts and the bug-1 entry in
+  // hdr-deferred-followups.md. Without master-display + max-cll in the
+  // x265-params, downstream players (Apple QuickTime, YouTube, HDR TVs) treat
+  // the file as SDR BT.2020 and tone-map incorrectly.
+  it("emits master-display and max-cll for PQ", () => {
+    const params = getHdrEncoderColorParams("pq");
+    expect(params.x265ColorParams).toContain(
+      `master-display=${DEFAULT_HDR10_MASTERING.masterDisplay}`,
+    );
+    expect(params.x265ColorParams).toContain(`max-cll=${DEFAULT_HDR10_MASTERING.maxCll}`);
+  });
+
+  it("emits master-display and max-cll for HLG", () => {
+    const params = getHdrEncoderColorParams("hlg");
+    expect(params.x265ColorParams).toContain(
+      `master-display=${DEFAULT_HDR10_MASTERING.masterDisplay}`,
+    );
+    expect(params.x265ColorParams).toContain(`max-cll=${DEFAULT_HDR10_MASTERING.maxCll}`);
+  });
+
+  it("respects an explicit mastering override", () => {
+    const custom = {
+      masterDisplay: "G(1,2)B(3,4)R(5,6)WP(7,8)L(9,10)",
+      maxCll: "500,200",
+    };
+    const params = getHdrEncoderColorParams("pq", custom);
+    expect(params.mastering).toBe(custom);
+    expect(params.x265ColorParams).toContain("master-display=G(1,2)B(3,4)R(5,6)WP(7,8)L(9,10)");
+    expect(params.x265ColorParams).toContain("max-cll=500,200");
+  });
+
+  // The DEFAULT_HDR10_MASTERING values are tagged as "P3-D65 inside BT.2020,
+  // 0.0001-1000 nits, MaxCLL 1000 / MaxFALL 400". If anyone tweaks these
+  // numbers without updating the docstring or the deferred-followups doc,
+  // this test will fail and force a deliberate review.
+  it("DEFAULT_HDR10_MASTERING matches the documented HDR10 reference", () => {
+    expect(DEFAULT_HDR10_MASTERING.masterDisplay).toBe(
+      "G(13250,34500)B(7500,3000)R(34000,16000)WP(15635,16450)L(10000000,1)",
+    );
+    expect(DEFAULT_HDR10_MASTERING.maxCll).toBe("1000,400");
+  });
+});
+
+describe("analyzeCompositionHdr", () => {
+  const sdr: VideoColorSpace = {
+    colorTransfer: "bt709",
+    colorPrimaries: "bt709",
+    colorSpace: "bt709",
+  };
+  const hlg: VideoColorSpace = {
+    colorTransfer: "arib-std-b67",
+    colorPrimaries: "bt2020",
+    colorSpace: "bt2020nc",
+  };
+  const pq: VideoColorSpace = {
+    colorTransfer: "smpte2084",
+    colorPrimaries: "bt2020",
+    colorSpace: "bt2020nc",
+  };
+
+  it("returns no HDR for all SDR", () => {
+    expect(analyzeCompositionHdr([sdr, sdr, null])).toEqual({
+      hasHdr: false,
+      dominantTransfer: null,
+    });
+  });
+
+  it("detects HLG", () => {
+    expect(analyzeCompositionHdr([sdr, hlg])).toEqual({
+      hasHdr: true,
+      dominantTransfer: "hlg",
+    });
+  });
+
+  it("detects PQ", () => {
+    expect(analyzeCompositionHdr([sdr, pq])).toEqual({
+      hasHdr: true,
+      dominantTransfer: "pq",
+    });
+  });
+
+  it("PQ takes priority over HLG in mixed HDR", () => {
+    expect(analyzeCompositionHdr([hlg, pq])).toEqual({
+      hasHdr: true,
+      dominantTransfer: "pq",
+    });
+  });
+});

package/src/utils/hdr.ts

@@ -0,0 +1,137 @@
+/**
+ * HDR Color Space Utilities
+ *
+ * Centralized HDR detection, transfer type handling, and FFmpeg color
+ * parameter generation for the HDR rendering pipeline.
+ */
+
+import type { VideoColorSpace } from "./ffprobe.js";
+
+export type HdrTransfer = "hlg" | "pq";
+
+/**
+ * Check if a video's color space indicates HDR content.
+ * Re-exported from videoFrameExtractor for backward compatibility.
+ */
+export function isHdrColorSpace(cs: VideoColorSpace | null): boolean {
+  if (!cs) return false;
+  return (
+    cs.colorPrimaries.includes("bt2020") ||
+    cs.colorSpace.includes("bt2020") ||
+    cs.colorTransfer === "smpte2084" ||
+    cs.colorTransfer === "arib-std-b67"
+  );
+}
+
+/**
+ * Determine the HDR transfer function from a video's color space metadata.
+ *
+ * IMPORTANT: Callers must gate on `isHdrColorSpace(cs)` first. This function
+ * assumes the input has already been classified as HDR and defaults ambiguous
+ * inputs to "hlg" — calling it with an SDR color space silently returns "hlg",
+ * which is wrong for SDR.
+ *
+ * Returns "pq" for SMPTE 2084, "hlg" for ARIB STD-B67, defaults to "hlg".
+ */
+export function detectTransfer(cs: VideoColorSpace | null): HdrTransfer {
+  if (cs?.colorTransfer === "smpte2084") return "pq";
+  return "hlg";
+}
+
+/**
+ * HDR static metadata for the encoded stream.
+ *
+ * `masterDisplay` is the SMPTE ST 2086 mastering-display color volume string
+ * accepted by x265 (`G(Gx,Gy)B(Bx,By)R(Rx,Ry)WP(WPx,WPy)L(Lmax,Lmin)`).
+ * Chromaticity values are scaled by 50000 (0.00002 cd/m² per unit) and
+ * luminance values by 10000 (0.0001 cd/m² per unit).
+ *
+ * `maxCll` is the CTA-861.3 Content Light Level pair `MaxCLL,MaxFALL` in
+ * cd/m². Without these SEI messages, downstream players (Apple QuickTime,
+ * YouTube, HDR TVs) treat the stream as SDR BT.2020 and tone-map incorrectly
+ * — see packages/producer/scripts/hdr-smoke.ts for the regression assertion.
+ */
+export interface HdrMasteringMetadata {
+  masterDisplay: string;
+  maxCll: string;
+}
+
+/**
+ * Default HDR10 mastering metadata: P3-D65 primaries inside a BT.2020
+ * container, mastered for 0.0001–1000 cd/m² with MaxCLL=1000, MaxFALL=400.
+ *
+ * These are conservative defaults that match how most HDR10 grading suites
+ * (Premiere, DaVinci Resolve) tag content when per-frame measured values
+ * aren't available. A future PR can plumb measured MaxCLL through `--hdr-opt`.
+ */
+export const DEFAULT_HDR10_MASTERING: HdrMasteringMetadata = {
+  masterDisplay: "G(13250,34500)B(7500,3000)R(34000,16000)WP(15635,16450)L(10000000,1)",
+  maxCll: "1000,400",
+};
+
+export interface HdrEncoderColorParams {
+  colorPrimaries: string;
+  colorTrc: string;
+  colorspace: string;
+  pixelFormat: string;
+  /**
+   * Full x265-params string including color tagging and HDR static metadata.
+   * Pass directly to `-x265-params` (concatenate with other options via `:`).
+   */
+  x265ColorParams: string;
+  /** The mastering metadata that was baked into `x265ColorParams`. */
+  mastering: HdrMasteringMetadata;
+}
+
+/**
+ * Get FFmpeg encoder color parameters for a given HDR transfer function.
+ *
+ * The returned `x265ColorParams` includes both color tagging
+ * (`colorprim`/`transfer`/`colormatrix`) and HDR static metadata
+ * (`master-display`/`max-cll`). Without the static metadata the encoded
+ * stream is rejected as SDR by most HDR-aware players and CDNs.
+ */
+export function getHdrEncoderColorParams(
+  transfer: HdrTransfer,
+  mastering: HdrMasteringMetadata = DEFAULT_HDR10_MASTERING,
+): HdrEncoderColorParams {
+  const colorTrc = transfer === "pq" ? "smpte2084" : "arib-std-b67";
+  const tagging = `colorprim=bt2020:transfer=${colorTrc}:colormatrix=bt2020nc`;
+  const metadata = `master-display=${mastering.masterDisplay}:max-cll=${mastering.maxCll}`;
+  return {
+    colorPrimaries: "bt2020",
+    colorTrc,
+    colorspace: "bt2020nc",
+    pixelFormat: "yuv420p10le",
+    x265ColorParams: `${tagging}:${metadata}`,
+    mastering,
+  };
+}
+
+export interface CompositionHdrInfo {
+  hasHdr: boolean;
+  dominantTransfer: HdrTransfer | null;
+}
+
+/**
+ * Analyze a set of video color spaces to determine if the composition
+ * contains HDR content and what the dominant transfer function is.
+ */
+export function analyzeCompositionHdr(
+  colorSpaces: Array<VideoColorSpace | null>,
+): CompositionHdrInfo {
+  let hasPq = false;
+  let hasHdr = false;
+
+  for (const cs of colorSpaces) {
+    if (!isHdrColorSpace(cs)) continue;
+    hasHdr = true;
+    if (cs?.colorTransfer === "smpte2084") hasPq = true;
+  }
+
+  if (!hasHdr) return { hasHdr: false, dominantTransfer: null };
+
+  // PQ takes priority — it's the more common HDR10 format
+  const dominantTransfer: HdrTransfer = hasPq ? "pq" : "hlg";
+  return { hasHdr: true, dominantTransfer };
+}

package/src/utils/layerCompositor.test.ts

@@ -0,0 +1,141 @@
+import { describe, expect, it } from "vitest";
+import { groupIntoLayers } from "./layerCompositor.js";
+import type { ElementStackingInfo } from "../services/videoFrameInjector.js";
+
+function makeEl(id: string, zIndex: number, isHdr: boolean): ElementStackingInfo {
+  return {
+    id,
+    zIndex,
+    x: 0,
+    y: 0,
+    width: 1920,
+    height: 1080,
+    layoutWidth: 1920,
+    layoutHeight: 1080,
+    opacity: 1,
+    visible: true,
+    isHdr,
+    transform: "none",
+    borderRadius: [0, 0, 0, 0],
+  };
+}
+
+describe("groupIntoLayers", () => {
+  it("single DOM element → 1 DOM layer", () => {
+    const layers = groupIntoLayers([makeEl("text", 0, false)]);
+    expect(layers).toHaveLength(1);
+    expect(layers[0]!.type).toBe("dom");
+  });
+
+  it("single HDR element → 1 HDR layer", () => {
+    const layers = groupIntoLayers([makeEl("v-hdr", 0, true)]);
+    expect(layers).toHaveLength(1);
+    expect(layers[0]!.type).toBe("hdr");
+  });
+
+  it("merges adjacent DOM elements into one layer", () => {
+    const elements = [makeEl("bg", 0, false), makeEl("text", 1, false), makeEl("logo", 2, false)];
+    const layers = groupIntoLayers(elements);
+    expect(layers).toHaveLength(1);
+    expect(layers[0]!.type).toBe("dom");
+    if (layers[0]!.type === "dom") {
+      expect(layers[0]!.elementIds).toEqual(["bg", "text", "logo"]);
+    }
+  });
+
+  it("splits on HDR/DOM boundary: DOM → HDR → DOM = 3 layers", () => {
+    const elements = [makeEl("bg", 0, false), makeEl("v-hdr", 1, true), makeEl("title", 2, false)];
+    const layers = groupIntoLayers(elements);
+    expect(layers).toHaveLength(3);
+    expect(layers[0]!.type).toBe("dom");
+    expect(layers[1]!.type).toBe("hdr");
+    expect(layers[2]!.type).toBe("dom");
+  });
+
+  it("merges adjacent DOM around multiple HDR: DOM → HDR → HDR → DOM = 4 layers", () => {
+    const elements = [
+      makeEl("bg", 0, false),
+      makeEl("v-hdr1", 1, true),
+      makeEl("v-hdr2", 2, true),
+      makeEl("title", 3, false),
+    ];
+    const layers = groupIntoLayers(elements);
+    expect(layers).toHaveLength(4);
+    expect(layers[0]!.type).toBe("dom");
+    expect(layers[1]!.type).toBe("hdr");
+    expect(layers[2]!.type).toBe("hdr");
+    expect(layers[3]!.type).toBe("dom");
+  });
+
+  it("complex case: DOM DOM HDR DOM HDR DOM = 5 layers (2 DOM merges)", () => {
+    const elements = [
+      makeEl("bg", 0, false),
+      makeEl("caption", 1, false),
+      makeEl("v-hdr1", 2, true),
+      makeEl("text", 3, false),
+      makeEl("v-hdr2", 4, true),
+      makeEl("logo", 5, false),
+    ];
+    const layers = groupIntoLayers(elements);
+    expect(layers).toHaveLength(5);
+    expect(layers.map((l) => l.type)).toEqual(["dom", "hdr", "dom", "hdr", "dom"]);
+    if (layers[0]!.type === "dom") {
+      expect(layers[0]!.elementIds).toEqual(["bg", "caption"]);
+    }
+  });
+
+  it("sorts by zIndex before grouping", () => {
+    const elements = [makeEl("title", 5, false), makeEl("v-hdr", 2, true), makeEl("bg", 0, false)];
+    const layers = groupIntoLayers(elements);
+    expect(layers).toHaveLength(3);
+    expect(layers[0]!.type).toBe("dom"); // bg (z=0)
+    expect(layers[1]!.type).toBe("hdr"); // v-hdr (z=2)
+    expect(layers[2]!.type).toBe("dom"); // title (z=5)
+  });
+
+  it("includes invisible elements in correct z-position", () => {
+    const elements = [
+      makeEl("bg", 0, false),
+      { ...makeEl("hidden-sdr", 1, false), visible: false },
+      { ...makeEl("hidden-hdr", 2, true), visible: false },
+      makeEl("title", 3, false),
+    ];
+    const layers = groupIntoLayers(elements);
+    // All elements included — invisible SDR videos need their injected
+    // <img> replacements hidden from other layers' screenshots
+    expect(layers).toHaveLength(3);
+    expect(layers[0]!.type).toBe("dom"); // bg + hidden-sdr (merged)
+    expect(layers[1]!.type).toBe("hdr"); // hidden-hdr
+    expect(layers[2]!.type).toBe("dom"); // title
+    if (layers[0]!.type === "dom") {
+      expect(layers[0]!.elementIds).toEqual(["bg", "hidden-sdr"]);
+    }
+  });
+
+  it("returns an empty array for empty input", () => {
+    expect(groupIntoLayers([])).toEqual([]);
+  });
+
+  it("handles negative z-index (valid CSS back layers)", () => {
+    const elements = [makeEl("fg", 1, false), makeEl("bg", -5, false)];
+    const layers = groupIntoLayers(elements);
+    expect(layers).toHaveLength(1);
+    expect(layers[0]!.type).toBe("dom");
+    if (layers[0]!.type === "dom") {
+      expect(layers[0]!.elementIds).toEqual(["bg", "fg"]);
+    }
+  });
+
+  it("preserves input order for equal z-index (stable tie-break)", () => {
+    const elements = [
+      makeEl("first", 0, false),
+      makeEl("second", 0, false),
+      makeEl("third", 0, false),
+    ];
+    const layers = groupIntoLayers(elements);
+    expect(layers).toHaveLength(1);
+    if (layers[0]!.type === "dom") {
+      expect(layers[0]!.elementIds).toEqual(["first", "second", "third"]);
+    }
+  });
+});

package/src/utils/layerCompositor.ts

@@ -0,0 +1,58 @@
+/**
+ * Layer Compositor — z-order analysis for multi-layer HDR compositing.
+ *
+ * Groups timed elements into z-ordered layers (DOM or HDR) for the
+ * per-frame compositing loop. Adjacent DOM elements merge into a single
+ * layer to minimize Chrome screenshots.
+ */
+
+import type { ElementStackingInfo } from "../services/videoFrameInjector.js";
+
+export type { ElementStackingInfo };
+
+export type CompositeLayer =
+  | { type: "dom"; elementIds: string[] }
+  | { type: "hdr"; element: ElementStackingInfo };
+
+/**
+ * Group z-sorted elements into composite layers. Adjacent DOM elements merge
+ * into a single layer; each HDR video/image is its own layer.
+ *
+ * Elements are sorted by \`zIndex\` ascending (back to front). Ties fall
+ * through to V8's stable sort, which preserves \`querySelectorAll\` DOM order —
+ * this is the same order Chrome uses for equal-z elements in a stacking
+ * context, so the blit order matches what the user sees in-browser.
+ *
+ * The DOM merge doesn't lose information: DOM layers are rendered via a
+ * full-page screenshot with non-layer elements hidden, so within-layer
+ * z-order is handled by Chrome itself.
+ *
+ * Invisible elements ARE included (video elements are hidden by the frame
+ * injector, but their injected \`<img>\` replacements are visible — they must
+ * stay in the correct z-ordered layer so sibling layers' DOM screenshots
+ * hide them).
+ */
+export function groupIntoLayers(elements: ElementStackingInfo[]): CompositeLayer[] {
+  // Include ALL elements regardless of visibility. Video elements are hidden by
+  // the frame injector (HEVC can't decode in headless Chrome) but their injected
+  // <img> replacements ARE visible. We need them in the correct z-ordered layer
+  // so they get hidden from other layers' DOM screenshots.
+  const sorted = [...elements].sort((a, b) => a.zIndex - b.zIndex);
+
+  const layers: CompositeLayer[] = [];
+
+  for (const el of sorted) {
+    if (el.isHdr) {
+      layers.push({ type: "hdr", element: el });
+    } else {
+      const last = layers[layers.length - 1];
+      if (last && last.type === "dom") {
+        last.elementIds.push(el.id);
+      } else {
+        layers.push({ type: "dom", elementIds: [el.id] });
+      }
+    }
+  }
+
+  return layers;
+}