@hyperframes/engine 0.4.9 → 0.4.11-alpha.1

package/src/utils/ffprobe.test.ts

@@ -0,0 +1,109 @@
+import { readFileSync } from "fs";
+import { resolve } from "path";
+import { describe, expect, it } from "vitest";
+import { extractPngMetadataFromBuffer, extractVideoMetadata } from "./ffprobe.js";
+
+function crc32(buf: Buffer): number {
+  let crc = 0xffffffff;
+  for (let i = 0; i < buf.length; i++) {
+    crc ^= buf[i] ?? 0;
+    for (let bit = 0; bit < 8; bit++) {
+      const mask = -(crc & 1);
+      crc = (crc >>> 1) ^ (0xedb88320 & mask);
+    }
+  }
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+function pngChunk(type: string, data: number[]): Buffer {
+  const chunkData = Buffer.from(data);
+  const header = Buffer.alloc(8);
+  header.writeUInt32BE(chunkData.length, 0);
+  header.write(type, 4, 4, "ascii");
+  const crc = Buffer.alloc(4);
+  crc.writeUInt32BE(crc32(Buffer.concat([Buffer.from(type, "ascii"), chunkData])), 0);
+  return Buffer.concat([header, chunkData, crc]);
+}
+
+function buildPngWithChunks(chunks: Buffer[]): Buffer {
+  return Buffer.concat([Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]), ...chunks]);
+}
+
+function buildMinimalPng(options?: {
+  cIcpAfterIdat?: boolean;
+  invalidCrc?: boolean;
+  longCicp?: boolean;
+}) {
+  const ihdr = pngChunk("IHDR", [0, 0, 0, 1, 0, 0, 0, 1, 16, 2, 0, 0, 0]);
+  const cicpData = options?.longCicp ? [9, 16, 0, 1, 255] : [9, 16, 0, 1];
+  let cicp = pngChunk("cICP", cicpData);
+  if (options?.invalidCrc) {
+    cicp = Buffer.from(cicp);
+    cicp[cicp.length - 1] ^= 0xff;
+  }
+  const idat = pngChunk(
+    "IDAT",
+    [0x78, 0x9c, 0x63, 0x60, 0x60, 0x60, 0x00, 0x00, 0x00, 0x04, 0x00, 0x01],
+  );
+  const iend = pngChunk("IEND", []);
+  return options?.cIcpAfterIdat
+    ? buildPngWithChunks([ihdr, idat, cicp, iend])
+    : buildPngWithChunks([ihdr, cicp, idat, iend]);
+}
+
+describe("extractVideoMetadata", () => {
+  it("reads HDR PNG cICP metadata when ffprobe color fields are absent", async () => {
+    const fixturePath = resolve(
+      __dirname,
+      "../../../producer/tests/hdr-image-only/src/hdr-photo.png",
+    );
+
+    const metadata = await extractVideoMetadata(fixturePath);
+
+    expect(metadata.colorSpace).toEqual({
+      colorPrimaries: "bt2020",
+      colorTransfer: "smpte2084",
+      colorSpace: "gbr",
+    });
+  });
+});
+
+describe("extractPngMetadataFromBuffer", () => {
+  it("accepts a valid cICP chunk before IDAT", () => {
+    const metadata = extractPngMetadataFromBuffer(buildMinimalPng());
+    expect(metadata?.colorSpace).toEqual({
+      colorPrimaries: "bt2020",
+      colorTransfer: "smpte2084",
+      colorSpace: "gbr",
+    });
+  });
+
+  it("rejects cICP chunks after IDAT", () => {
+    const metadata = extractPngMetadataFromBuffer(buildMinimalPng({ cIcpAfterIdat: true }));
+    expect(metadata).toEqual({
+      width: 1,
+      height: 1,
+      colorSpace: null,
+    });
+  });
+
+  it("rejects cICP chunks with invalid CRC", () => {
+    expect(extractPngMetadataFromBuffer(buildMinimalPng({ invalidCrc: true }))).toBeNull();
+  });
+
+  it("rejects cICP chunks whose payload is not exactly four bytes", () => {
+    const metadata = extractPngMetadataFromBuffer(buildMinimalPng({ longCicp: true }));
+    expect(metadata).toEqual({
+      width: 1,
+      height: 1,
+      colorSpace: null,
+    });
+  });
+
+  it("continues to parse the checked-in HDR PNG fixture", () => {
+    const fixture = readFileSync(
+      resolve(__dirname, "../../../producer/tests/hdr-image-only/src/hdr-photo.png"),
+    );
+    expect(extractPngMetadataFromBuffer(fixture)?.colorSpace?.colorTransfer).toBe("smpte2084");
+  });
+});

package/src/utils/ffprobe.ts

@@ -1,4 +1,6 @@
 import { spawn } from "child_process";
+import { readFileSync } from "fs";
+import { extname } from "path";
 
 /** Spawn ffprobe with given args, return stdout. Throws on non-zero exit or missing binary. */
 function runFfprobe(args: string[]): Promise<string> {
@@ -96,6 +98,107 @@ interface FFProbeOutput {
   format: FFProbeFormat;
 }
 
+interface StillImageMetadata {
+  width: number;
+  height: number;
+  colorSpace: VideoColorSpace | null;
+}
+
+function crc32(buf: Buffer): number {
+  let crc = 0xffffffff;
+  for (let i = 0; i < buf.length; i++) {
+    crc ^= buf[i] ?? 0;
+    for (let bit = 0; bit < 8; bit++) {
+      const mask = -(crc & 1);
+      crc = (crc >>> 1) ^ (0xedb88320 & mask);
+    }
+  }
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+export function extractPngMetadataFromBuffer(buf: Buffer): StillImageMetadata | null {
+  if (
+    buf.length < 8 ||
+    buf[0] !== 137 ||
+    buf[1] !== 80 ||
+    buf[2] !== 78 ||
+    buf[3] !== 71 ||
+    buf[4] !== 13 ||
+    buf[5] !== 10 ||
+    buf[6] !== 26 ||
+    buf[7] !== 10
+  ) {
+    return null;
+  }
+
+  let width = 0;
+  let height = 0;
+  let seenIdat = false;
+  let pos = 8;
+  while (pos + 12 <= buf.length) {
+    const chunkLen = buf.readUInt32BE(pos);
+    const chunkType = buf.toString("ascii", pos + 4, pos + 8);
+    if (pos + 12 + chunkLen > buf.length) return null;
+    const chunkData = buf.subarray(pos + 8, pos + 8 + chunkLen);
+    const chunkCrc = buf.readUInt32BE(pos + 8 + chunkLen);
+    const chunkBytes = Buffer.concat([Buffer.from(chunkType, "ascii"), chunkData]);
+    if (crc32(chunkBytes) !== chunkCrc) return null;
+
+    if (chunkType === "IHDR" && chunkLen >= 8) {
+      width = buf.readUInt32BE(pos + 8);
+      height = buf.readUInt32BE(pos + 12);
+    }
+
+    if (chunkType === "IDAT") {
+      seenIdat = true;
+    }
+
+    if (chunkType === "cICP" && chunkLen === 4 && !seenIdat) {
+      const primariesCode = chunkData[0] ?? 0;
+      const transferCode = chunkData[1] ?? 0;
+      const matrixCode = chunkData[2] ?? 0;
+
+      return {
+        width,
+        height,
+        colorSpace: {
+          colorPrimaries:
+            primariesCode === 9
+              ? "bt2020"
+              : primariesCode === 1
+                ? "bt709"
+                : `unknown-${primariesCode}`,
+          colorTransfer:
+            transferCode === 16
+              ? "smpte2084"
+              : transferCode === 18
+                ? "arib-std-b67"
+                : transferCode === 1
+                  ? "bt709"
+                  : `unknown-${transferCode}`,
+          colorSpace:
+            matrixCode === 9 ? "bt2020nc" : matrixCode === 0 ? "gbr" : `unknown-${matrixCode}`,
+        },
+      };
+    }
+
+    if (chunkType === "IEND") break;
+    pos += 12 + chunkLen;
+  }
+
+  return width > 0 && height > 0 ? { width, height, colorSpace: null } : null;
+}
+
+function extractStillImageMetadata(filePath: string): StillImageMetadata | null {
+  if (extname(filePath).toLowerCase() !== ".png") return null;
+
+  try {
+    return extractPngMetadataFromBuffer(readFileSync(filePath));
+  } catch {
+    return null;
+  }
+}
+
 function parseFrameRate(frameRateStr: string | undefined): number {
   if (!frameRateStr) return 0;
   const parts = frameRateStr.split("/");
@@ -112,18 +215,40 @@ export async function extractVideoMetadata(filePath: string): Promise<VideoMetad
   if (cached) return cached;
 
   const probePromise = (async (): Promise<VideoMetadata> => {
-    const stdout = await runFfprobe([
-      "-v",
-      "quiet",
-      "-print_format",
-      "json",
-      "-show_format",
-      "-show_streams",
-      filePath,
-    ]);
-    const output = parseProbeJson(stdout);
-    const videoStream = output.streams.find((s) => s.codec_type === "video");
-    if (!videoStream) throw new Error("[FFmpeg] No video stream found");
+    const stillImageMeta = extractStillImageMetadata(filePath);
+
+    let output: FFProbeOutput | null = null;
+    try {
+      const stdout = await runFfprobe([
+        "-v",
+        "quiet",
+        "-print_format",
+        "json",
+        "-show_format",
+        "-show_streams",
+        filePath,
+      ]);
+      output = parseProbeJson(stdout);
+    } catch (error) {
+      if (!stillImageMeta) throw error;
+    }
+
+    const videoStream = output?.streams.find((s) => s.codec_type === "video");
+    if (!videoStream) {
+      if (stillImageMeta) {
+        return {
+          durationSeconds: 0,
+          width: stillImageMeta.width,
+          height: stillImageMeta.height,
+          fps: 0,
+          videoCodec: "png",
+          hasAudio: false,
+          isVFR: false,
+          colorSpace: stillImageMeta.colorSpace,
+        };
+      }
+      throw new Error("[FFmpeg] No video stream found");
+    }
 
     const rFps = parseFrameRate(videoStream.r_frame_rate);
     const avgFps = parseFrameRate(videoStream.avg_frame_rate);
@@ -134,19 +259,21 @@ export async function extractVideoMetadata(filePath: string): Promise<VideoMetad
     const colorTransfer = videoStream.color_transfer || "";
     const colorPrimaries = videoStream.color_primaries || "";
     const colorSpaceVal = videoStream.color_space || "";
-    const hasColorInfo = !!(colorTransfer || colorPrimaries || colorSpaceVal);
+    const ffprobeColorSpace =
+      colorTransfer || colorPrimaries || colorSpaceVal
+        ? { colorTransfer, colorPrimaries, colorSpace: colorSpaceVal }
+        : null;
+    const colorSpace = ffprobeColorSpace ?? stillImageMeta?.colorSpace ?? null;
 
     return {
-      durationSeconds: output.format.duration ? parseFloat(output.format.duration) : 0,
-      width: videoStream.width || 0,
-      height: videoStream.height || 0,
+      durationSeconds: output?.format.duration ? parseFloat(output.format.duration) : 0,
+      width: videoStream.width || stillImageMeta?.width || 0,
+      height: videoStream.height || stillImageMeta?.height || 0,
       fps,
       videoCodec: videoStream.codec_name || "unknown",
-      hasAudio: output.streams.some((s) => s.codec_type === "audio"),
+      hasAudio: output?.streams.some((s) => s.codec_type === "audio") ?? false,
       isVFR,
-      colorSpace: hasColorInfo
-        ? { colorTransfer, colorPrimaries, colorSpace: colorSpaceVal }
-        : null,
+      colorSpace,
     };
   })();