@hyperframes/engine 0.6.119 → 0.6.121

package/src/utils/gpuEncoder.ts

@@ -1,268 +0,0 @@
-// fallow-ignore-file complexity
-/**
- * GPU Encoder Detection
- *
- * Shared GPU encoder detection and naming utilities used by both
- * chunkEncoder and streamingEncoder services.
- */
-
-import { spawn } from "child_process";
-import { getFfmpegBinary } from "./ffmpegBinaries.js";
-
-export type ConcreteGpuEncoder = "nvenc" | "videotoolbox" | "vaapi" | "qsv" | "amf";
-export type GpuEncoder = ConcreteGpuEncoder | null;
-
-const GPU_ENCODER_CANDIDATES: ConcreteGpuEncoder[] = [
-  "nvenc",
-  "videotoolbox",
-  "vaapi",
-  "qsv",
-  "amf",
-];
-
-const H264_ENCODER_BY_GPU: Record<ConcreteGpuEncoder, string> = {
-  nvenc: "h264_nvenc",
-  videotoolbox: "h264_videotoolbox",
-  vaapi: "h264_vaapi",
-  qsv: "h264_qsv",
-  amf: "h264_amf",
-};
-
-const GPU_PROBE_TIMEOUT_MS = 2000;
-const GPU_PROBE_KILL_GRACE_MS = 1000;
-
-export function getCompiledGpuEncoders(ffmpegEncodersStdout: string): ConcreteGpuEncoder[] {
-  return GPU_ENCODER_CANDIDATES.filter((encoder) =>
-    ffmpegEncodersStdout.includes(H264_ENCODER_BY_GPU[encoder]),
-  );
-}
-
-export async function selectUsableGpuEncoder(
-  candidates: readonly ConcreteGpuEncoder[],
-  isUsable: (encoder: ConcreteGpuEncoder) => Promise<boolean>,
-): Promise<GpuEncoder> {
-  const results = await Promise.all(
-    candidates.map(async (encoder) => {
-      try {
-        return { encoder, usable: await isUsable(encoder) };
-      } catch {
-        return { encoder, usable: false };
-      }
-    }),
-  );
-
-  for (const result of results) {
-    if (result.usable) {
-      return result.encoder;
-    }
-  }
-  return null;
-}
-
-export async function detectGpuEncoder(): Promise<GpuEncoder> {
-  return new Promise((resolve) => {
-    const ffmpeg = spawn(getFfmpegBinary(), ["-encoders"], {
-      stdio: ["pipe", "pipe", "pipe"],
-    });
-    let stdout = "";
-
-    ffmpeg.stdout.on("data", (data) => {
-      stdout += data.toString();
-    });
-
-    ffmpeg.on("close", () => {
-      const candidates = getCompiledGpuEncoders(stdout);
-      void selectUsableGpuEncoder(candidates, canUseGpuEncoder)
-        .then(resolve)
-        .catch(() => resolve(null));
-    });
-
-    ffmpeg.on("error", () => resolve(null));
-  });
-}
-
-let cachedGpuEncoder: GpuEncoder | undefined = undefined;
-
-export async function getCachedGpuEncoder(): Promise<GpuEncoder> {
-  if (cachedGpuEncoder === undefined) {
-    cachedGpuEncoder = await detectGpuEncoder();
-  }
-  return cachedGpuEncoder;
-}
-
-export function getGpuEncoderName(encoder: GpuEncoder, codec: "h264" | "h265"): string {
-  if (!encoder) return codec === "h264" ? "libx264" : "libx265";
-  switch (encoder) {
-    case "nvenc":
-      return codec === "h264" ? "h264_nvenc" : "hevc_nvenc";
-    case "videotoolbox":
-      return codec === "h264" ? "h264_videotoolbox" : "hevc_videotoolbox";
-    case "vaapi":
-      return codec === "h264" ? "h264_vaapi" : "hevc_vaapi";
-    case "qsv":
-      return codec === "h264" ? "h264_qsv" : "hevc_qsv";
-    case "amf":
-      return codec === "h264" ? "h264_amf" : "hevc_amf";
-    default:
-      return codec === "h264" ? "libx264" : "libx265";
-  }
-}
-
-// Minimum probe dimensions must clear every GPU encoder's hardware minimum.
-// NVIDIA data-center SKUs (L4/T4/A10/A100) reject frames below ~257px on
-// either dimension with "Frame Dimension less than the minimum supported
-// value" (observed on driver 595.58.03, CUDA 13.2). The documented SDK
-// minimums (145×49 H.264, 129×33 HEVC) are lower, but the driver enforces
-// a stricter per-SKU alignment. 320×240 clears all known GPU encoder
-// minimums (NVENC, VideoToolbox, VAAPI, QSV, AMF) while staying cheap.
-const GPU_PROBE_WIDTH = 320;
-const GPU_PROBE_HEIGHT = 240;
-
-export function getProbeArgs(encoder: ConcreteGpuEncoder): string[] {
-  const args = [
-    "-hide_banner",
-    "-loglevel",
-    "error",
-    "-f",
-    "lavfi",
-    "-i",
-    `color=size=${GPU_PROBE_WIDTH}x${GPU_PROBE_HEIGHT}:rate=1:duration=1`,
-    "-frames:v",
-    "1",
-    "-an",
-  ];
-
-  if (encoder === "vaapi") {
-    args.push("-vaapi_device", "/dev/dri/renderD128", "-vf", "format=nv12,hwupload");
-  }
-
-  args.push("-c:v", getGpuEncoderName(encoder, "h264"));
-
-  if (encoder === "amf") {
-    args.push("-rc", "cqp", "-qp_i", "28", "-qp_p", "28");
-  }
-
-  args.push("-f", "null", "-");
-  return args;
-}
-
-async function canUseGpuEncoder(encoder: ConcreteGpuEncoder): Promise<boolean> {
-  return new Promise((resolve) => {
-    let settled = false;
-    let timedOut = false;
-    let killTimer: ReturnType<typeof setTimeout> | undefined;
-    let stderr = "";
-    const finish = (usable: boolean) => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      if (killTimer) clearTimeout(killTimer);
-      resolve(usable);
-    };
-    const ffmpeg = spawn(getFfmpegBinary(), getProbeArgs(encoder), {
-      stdio: ["ignore", "ignore", "pipe"],
-    });
-
-    ffmpeg.stderr?.on("data", (data) => {
-      stderr += data.toString();
-    });
-
-    const timer = setTimeout(() => {
-      timedOut = true;
-      ffmpeg.kill("SIGTERM");
-      killTimer = setTimeout(() => {
-        ffmpeg.kill("SIGKILL");
-        finish(false);
-      }, GPU_PROBE_KILL_GRACE_MS);
-    }, GPU_PROBE_TIMEOUT_MS);
-
-    ffmpeg.on("close", (code, signal) => {
-      const usable = code === 0;
-      logGpuProbeFailure(encoder, { code, signal, stderr, timedOut });
-      finish(usable);
-    });
-
-    ffmpeg.on("error", (error) => {
-      logGpuProbeFailure(encoder, { error, timedOut });
-      finish(false);
-    });
-  });
-}
-
-function logGpuProbeFailure(
-  encoder: ConcreteGpuEncoder,
-  result: {
-    code?: number | null;
-    error?: Error;
-    signal?: NodeJS.Signals | null;
-    stderr?: string;
-    timedOut?: boolean;
-  },
-): void {
-  if (!isGpuProbeDebugEnabled()) return;
-  if (result.code === 0 && !result.error && !result.timedOut) return;
-
-  const reason = result.error
-    ? result.error.message
-    : result.timedOut
-      ? `timed out after ${GPU_PROBE_TIMEOUT_MS}ms`
-      : `exit=${String(result.code)} signal=${String(result.signal ?? "")}`;
-  const stderr = result.stderr?.trim();
-  console.warn(`[gpuEncoder] ${encoder} probe failed: ${reason}${stderr ? `\n${stderr}` : ""}`);
-}
-
-function isGpuProbeDebugEnabled(): boolean {
-  const value = process.env.HYPERFRAMES_DEBUG_GPU_PROBE;
-  return value === "1" || value === "true";
-}
-
-// libx264 preset names (ultrafast/superfast/.../placebo) mapped to the
-// equivalent NVENC p1..p7 preset. NVENC rejects libx264 names with
-// AVERROR(EINVAL) ("Error applying encoder options: Invalid argument"),
-// which surfaces as a generic "FFmpeg exited with code -22" — so callers
-// that share a single `preset` field across CPU and GPU paths (e.g. the
-// `draft`/`standard`/`high` quality tiers) must translate before passing
-// the value to h264_nvenc / hevc_nvenc.
-const NVENC_PRESET_MAP: Record<string, string> = {
-  ultrafast: "p1",
-  superfast: "p1",
-  veryfast: "p2",
-  faster: "p3",
-  fast: "p4",
-  medium: "p4",
-  slow: "p5",
-  slower: "p6",
-  veryslow: "p7",
-  placebo: "p7",
-};
-
-// QSV accepts most libx264 preset names but rejects `ultrafast`,
-// `superfast`, and `placebo`. Map those to the nearest supported values.
-const QSV_PRESET_MAP: Record<string, string> = {
-  ultrafast: "veryfast",
-  superfast: "veryfast",
-  placebo: "veryslow",
-};
-
-/**
- * Translate a libx264-style `-preset` value to one accepted by the given
- * GPU encoder.
- *
- * - `nvenc`: libx264 names → `p1`..`p7`. Already-native `pN` values pass
- *   through unchanged. Unknown values fall back to `p4` (medium).
- * - `qsv`:  `ultrafast`/`superfast`/`placebo` → nearest supported name;
- *   everything else passes through.
- * - `videotoolbox`, `vaapi`, `amf`, `null`: no remap (they either ignore
- *   `-preset` entirely or accept the libx264 vocabulary).
- */
-export function mapPresetForGpuEncoder(encoder: GpuEncoder, preset: string): string {
-  switch (encoder) {
-    case "nvenc":
-      if (/^p[1-7]$/.test(preset)) return preset;
-      return NVENC_PRESET_MAP[preset] ?? "p4";
-    case "qsv":
-      return QSV_PRESET_MAP[preset] ?? preset;
-    default:
-      return preset;
-  }
-}

package/src/utils/hdr.test.ts

@@ -1,191 +0,0 @@
-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

@@ -1,137 +0,0 @@
-/**
- * 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 };
-}