dsh-hyperframes 0.3.1 → 0.4.0

package/skills/media-use/scripts/lib/grade-analyzer.mjs

@@ -1,264 +0,0 @@
-// Vendored plain-JS copy of packages/core/src/mediaGradeAnalyzer.ts.
-// packages/core/src/mediaGradeAnalyzer.vendoredParity.test.ts guards behavior drift.
-import { execFileSync } from "node:child_process";
-import { basename, extname } from "node:path";
-
-const IMAGE_EXT = new Set([".jpg", ".jpeg", ".png", ".webp", ".gif", ".bmp", ".tif", ".tiff"]);
-const SAMPLE_FRAMES = 5;
-const DEFAULT_TIMEOUT_MS = 15_000;
-
-const ADJUST_LIMITS = {
-  exposure: { min: -2, max: 2 },
-  contrast: { min: -1, max: 1 },
-  whites: { min: -1, max: 1 },
-  blacks: { min: -1, max: 1 },
-  temperature: { min: -1, max: 1 },
-  tint: { min: -1, max: 1 },
-};
-
-function clamp(value, key) {
-  const limit = ADJUST_LIMITS[key];
-  if (!Number.isFinite(value)) return 0;
-  return Math.min(limit.max, Math.max(limit.min, value));
-}
-
-function round(value) {
-  const rounded = Math.round(value * 1000) / 1000;
-  return Object.is(rounded, -0) ? 0 : rounded;
-}
-
-function average(values) {
-  return values.reduce((sum, value) => sum + value, 0) / Math.max(1, values.length);
-}
-
-function probeMedia(mediaPath, ffprobePath) {
-  try {
-    const raw = execFileSync(
-      ffprobePath,
-      [
-        "-v",
-        "error",
-        "-select_streams",
-        "v:0",
-        "-show_entries",
-        "stream=color_space,color_transfer,color_primaries,pix_fmt,duration:format=duration",
-        "-of",
-        "json",
-        "--",
-        mediaPath,
-      ],
-      { encoding: "utf8", timeout: 5_000, stdio: ["ignore", "pipe", "pipe"] },
-    );
-    const parsed = JSON.parse(raw);
-    const stream = Array.isArray(parsed.streams) ? (parsed.streams[0] ?? {}) : {};
-    const duration = Number(stream.duration ?? parsed.format?.duration);
-    const text = (key) =>
-      typeof stream[key] === "string" && stream[key] ? stream[key] : "unknown";
-    return {
-      duration: Number.isFinite(duration) && duration > 0 ? duration : null,
-      colorSpace: text("color_space"),
-      transfer: text("color_transfer"),
-      primaries: text("color_primaries"),
-      pixelFormat: text("pix_fmt"),
-    };
-  } catch {
-    return {
-      duration: null,
-      colorSpace: "unknown",
-      transfer: "unknown",
-      primaries: "unknown",
-      pixelFormat: "unknown",
-    };
-  }
-}
-
-export function parseMediaTreatmentSignalStats(raw) {
-  const frames = [];
-  let current = null;
-  for (const line of String(raw).split(/\r?\n/)) {
-    const frame = line.match(/^frame:\d+.*pts_time:([+-]?(?:\d+(?:\.\d+)?|\.\d+))/);
-    if (frame) {
-      if (current) frames.push(current);
-      current = { ptsTime: Number(frame[1]) };
-      continue;
-    }
-    const stat = line.match(/lavfi\.signalstats\.([A-Z]+)=([+-]?(?:\d+(?:\.\d+)?|\.\d+))/);
-    if (!stat) continue;
-    current ??= {};
-    current[stat[1]] = Number(stat[2]);
-  }
-  if (current) frames.push(current);
-  return frames.filter(
-    (frame) =>
-      Number.isFinite(frame.YMIN) &&
-      Number.isFinite(frame.YLOW) &&
-      Number.isFinite(frame.YAVG) &&
-      Number.isFinite(frame.YHIGH) &&
-      Number.isFinite(frame.YMAX) &&
-      Number.isFinite(frame.UAVG) &&
-      Number.isFinite(frame.VAVG),
-  );
-}
-
-function summarizeFrames(frames) {
-  if (frames.length === 0) throw new Error("FFmpeg returned no analyzable video frames");
-  return {
-    frames: frames.length,
-    yMin: Math.min(...frames.map((frame) => frame.YMIN)),
-    yLow: average(frames.map((frame) => frame.YLOW)),
-    yAvg: average(frames.map((frame) => frame.YAVG)),
-    yHigh: average(frames.map((frame) => frame.YHIGH)),
-    yMax: Math.max(...frames.map((frame) => frame.YMAX)),
-    uAvg: average(frames.map((frame) => frame.UAVG)),
-    vAvg: average(frames.map((frame) => frame.VAVG)),
-    satAvg: average(frames.map((frame) => frame.SATAVG ?? 0)),
-    shadowClipRisk: average(frames.map((frame) => (frame.YLOW <= 16 ? 1 : 0))),
-    highlightClipRisk: average(frames.map((frame) => (frame.YHIGH >= 235 ? 1 : 0))),
-  };
-}
-
-function suggestedExposure(normalizedAverage, yLow, yHigh) {
-  if (normalizedAverage < 0.28 && yHigh / 255 < 0.65) {
-    return clamp((0.32 - normalizedAverage) * 1.2, "exposure");
-  }
-  if (normalizedAverage > 0.72 && yLow / 255 > 0.3) {
-    return clamp((0.68 - normalizedAverage) * 1.2, "exposure");
-  }
-  return 0;
-}
-
-function suggestedTemperature(uAverage, vAverage) {
-  const chromaWarmth = (vAverage - 128 + (128 - uAverage)) / 128;
-  return Math.abs(chromaWarmth) >= 0.08 ? clamp(-chromaWarmth * 0.25, "temperature") : 0;
-}
-
-function suggestedTint(uAverage, vAverage) {
-  const cast = uAverage + vAverage - 256;
-  return Math.abs(cast) >= 10 ? clamp(-cast / 512, "tint") : 0;
-}
-
-export function statsToAdjust(stats) {
-  const yMin = Number(stats.yMin);
-  const yLow = Number(stats.yLow ?? stats.yMin);
-  const yMax = Number(stats.yMax);
-  const yHigh = Number(stats.yHigh ?? stats.yMax);
-  const yAvg = Number(stats.yAvg);
-  const uAvg = Number(stats.uAvg);
-  const vAvg = Number(stats.vAvg);
-  const shadowClipRisk = Number(stats.shadowClipRisk ?? (yLow <= 16 ? 1 : 0));
-  const highlightClipRisk = Number(stats.highlightClipRisk ?? (yHigh >= 235 ? 1 : 0));
-  const percentileSpread = (yHigh - yLow) / 255;
-  const normalizedAverage = yAvg / 255;
-  const contrast = percentileSpread < 0.35 ? clamp((0.35 - percentileSpread) * 0.4, "contrast") : 0;
-
-  return {
-    adjust: {
-      exposure: round(suggestedExposure(normalizedAverage, yLow, yHigh)),
-      contrast: round(contrast),
-      blacks: round(clamp(shadowClipRisk * 0.08, "blacks")),
-      whites: round(clamp(-highlightClipRisk * 0.08, "whites")),
-      temperature: round(suggestedTemperature(uAvg, vAvg)),
-      tint: round(suggestedTint(uAvg, vAvg)),
-    },
-    measured: {
-      frames: Number(stats.frames ?? 1),
-      yMin: round(yMin),
-      yLow: round(yLow),
-      yAvg: round(yAvg),
-      yHigh: round(yHigh),
-      yMax: round(yMax),
-      uAvg: round(uAvg),
-      vAvg: round(vAvg),
-      satAvg: round(Number(stats.satAvg ?? 0)),
-      shadowClipRisk: round(shadowClipRisk),
-      highlightClipRisk: round(highlightClipRisk),
-    },
-  };
-}
-
-export function summarizeMediaTreatmentAnalysis(probe, frames) {
-  const result = statsToAdjust(summarizeFrames(frames));
-  const hdr = ["smpte2084", "arib-std-b67"].includes(probe.transfer);
-  const diagnosis = [];
-  if (result.measured.shadowClipRisk > 0) {
-    diagnosis.push("sampled frames contain deep or clipped shadows");
-  }
-  if (result.measured.highlightClipRisk > 0) {
-    diagnosis.push("sampled frames contain bright or clipped highlights");
-  }
-  if (diagnosis.length === 0) diagnosis.push("no obvious technical imbalance in sampled frames");
-
-  const warnings = [];
-  if (hdr) warnings.push("HDR transfer detected; the realtime treatment path is SDR/Rec.709.");
-  if (probe.colorSpace === "unknown" || probe.transfer === "unknown") {
-    warnings.push(
-      "Source color metadata is incomplete; camera LOG cannot be identified reliably from container metadata alone.",
-    );
-  }
-
-  return {
-    ...result,
-    source: {
-      colorSpace: probe.colorSpace,
-      transfer: probe.transfer,
-      primaries: probe.primaries,
-      pixelFormat: probe.pixelFormat,
-      hdr,
-      log: "unknown",
-    },
-    diagnosis,
-    warnings,
-  };
-}
-
-export function analyzeMediaGrade(
-  mediaPath,
-  { ffmpegPath = "ffmpeg", ffprobePath = "ffprobe" } = {},
-) {
-  try {
-    const probe = probeMedia(mediaPath, ffprobePath);
-    const isImage = IMAGE_EXT.has(extname(mediaPath).toLowerCase());
-    const fps =
-      !isImage && probe.duration
-        ? Math.max(0.1, Math.min(2, SAMPLE_FRAMES / probe.duration))
-        : null;
-    const filters = [
-      fps ? `fps=${fps.toFixed(4)}` : null,
-      "format=yuv444p",
-      "signalstats",
-      "metadata=print:file=-",
-    ]
-      .filter(Boolean)
-      .join(",");
-    const raw = execFileSync(
-      ffmpegPath,
-      [
-        "-hide_banner",
-        "-nostdin",
-        "-v",
-        "error",
-        "-i",
-        mediaPath,
-        "-vf",
-        filters,
-        "-frames:v",
-        String(SAMPLE_FRAMES),
-        "-f",
-        "null",
-        "-",
-      ],
-      {
-        encoding: "utf8",
-        timeout: Number(process.env.HYPERFRAMES_ANALYZE_TIMEOUT_MS) || DEFAULT_TIMEOUT_MS,
-        stdio: ["ignore", "pipe", "pipe"],
-      },
-    );
-    return summarizeMediaTreatmentAnalysis(probe, parseMediaTreatmentSignalStats(raw));
-  } catch (error) {
-    throw new Error(`grade analysis failed for ${mediaPath}: ${error.message}`);
-  }
-}
-
-export function formatMeasuredNote(mediaPath, measured) {
-  return `media-use: measured ${basename(mediaPath)}: frames=${measured.frames}, YMIN=${measured.yMin}, YLOW=${measured.yLow}, YAVG=${measured.yAvg}, YHIGH=${measured.yHigh}, YMAX=${measured.yMax}, UAVG=${measured.uAvg}, VAVG=${measured.vAvg}; adjust is a starting suggestion`;
-}

package/skills/media-use/scripts/lib/grade-analyzer.test.mjs

@@ -1,285 +0,0 @@
-import { strict as assert } from "node:assert";
-import { execFileSync, spawnSync } from "node:child_process";
-import { existsSync, mkdtempSync, rmSync, unlinkSync } from "node:fs";
-import { join } from "node:path";
-import { tmpdir } from "node:os";
-import { test } from "node:test";
-import {
-  analyzeMediaGrade,
-  formatMeasuredNote,
-  parseMediaTreatmentSignalStats,
-  statsToAdjust,
-  summarizeMediaTreatmentAnalysis,
-} from "./grade-analyzer.mjs";
-
-const SIGNALSTATS = `frame:0 pts:0 pts_time:0
-lavfi.signalstats.YMIN=0
-lavfi.signalstats.YLOW=8
-lavfi.signalstats.YAVG=100
-lavfi.signalstats.YHIGH=240
-lavfi.signalstats.YMAX=255
-lavfi.signalstats.UAVG=120
-lavfi.signalstats.VAVG=140
-lavfi.signalstats.SATAVG=40
-frame:1 pts:2000 pts_time:2
-lavfi.signalstats.YMIN=10
-lavfi.signalstats.YLOW=20
-lavfi.signalstats.YAVG=130
-lavfi.signalstats.YHIGH=220
-lavfi.signalstats.YMAX=245
-lavfi.signalstats.UAVG=130
-lavfi.signalstats.VAVG=125
-lavfi.signalstats.SATAVG=60`;
-
-// The "Test: skills" CI job runs bare `node --test` with no ffmpeg on PATH (by
-// design — skills tests are meant to be node-builtin-only). Tests that shell to
-// ffmpeg skip there and run wherever ffmpeg is present (locally, dev).
-const FFMPEG_SKIP =
-  spawnSync("ffmpeg", ["-version"], { stdio: "ignore" }).status === 0
-    ? false
-    : "ffmpeg not on PATH";
-
-const ADJUST_LIMITS = {
-  exposure: { min: -2, max: 2 },
-  contrast: { min: -1, max: 1 },
-  highlights: { min: -1, max: 1 },
-  shadows: { min: -1, max: 1 },
-  whites: { min: -1, max: 1 },
-  blacks: { min: -1, max: 1 },
-  temperature: { min: -1, max: 1 },
-  tint: { min: -1, max: 1 },
-  vibrance: { min: -1, max: 1 },
-  saturation: { min: -1, max: 1 },
-};
-
-function makeFrame(dir, name, color) {
-  const out = join(dir, name);
-  execFileSync(
-    "ffmpeg",
-    [
-      "-hide_banner",
-      "-loglevel",
-      "error",
-      "-f",
-      "lavfi",
-      "-i",
-      `color=c=${color}:s=64x64`,
-      "-frames:v",
-      "1",
-      "-y",
-      out,
-    ],
-    { stdio: "pipe" },
-  );
-  return out;
-}
-
-function assertWithinLimits(adjust) {
-  for (const [key, value] of Object.entries(adjust)) {
-    const limit = ADJUST_LIMITS[key];
-    assert.ok(limit, `unexpected adjust key ${key}`);
-    assert.ok(value >= limit.min && value <= limit.max, `${key} out of range: ${value}`);
-  }
-}
-
-test("under-exposed synthetic frame suggests positive exposure", { skip: FFMPEG_SKIP }, () => {
-  const dir = mkdtempSync(join(tmpdir(), "mu-grade-under-"));
-  try {
-    const file = makeFrame(dir, "under.png", "0x202020");
-    const { adjust, measured } = analyzeMediaGrade(file);
-    assert.ok(measured.frames >= 1);
-    assert.ok(adjust.exposure > 0, `expected positive exposure, got ${adjust.exposure}`);
-    assertWithinLimits(adjust);
-  } finally {
-    rmSync(dir, { recursive: true, force: true });
-  }
-});
-
-test(
-  "over-exposed synthetic frame pulls exposure down without inventing clipping",
-  { skip: FFMPEG_SKIP },
-  () => {
-    const dir = mkdtempSync(join(tmpdir(), "mu-grade-over-"));
-    try {
-      const file = makeFrame(dir, "over.png", "white");
-      const { adjust } = analyzeMediaGrade(file);
-      assert.ok(adjust.exposure < 0, `expected negative exposure, got ${adjust.exposure}`);
-      assert.ok(adjust.whites <= 0, `expected non-positive whites, got ${adjust.whites}`);
-      assertWithinLimits(adjust);
-    } finally {
-      rmSync(dir, { recursive: true, force: true });
-    }
-  },
-);
-
-test(
-  "warm-cast synthetic frame suggests negative temperature correction",
-  { skip: FFMPEG_SKIP },
-  () => {
-    const dir = mkdtempSync(join(tmpdir(), "mu-grade-warm-"));
-    try {
-      const file = makeFrame(dir, "warm.png", "orange");
-      const { adjust } = analyzeMediaGrade(file);
-      assert.ok(adjust.temperature < 0, `expected cooling correction, got ${adjust.temperature}`);
-      assertWithinLimits(adjust);
-    } finally {
-      rmSync(dir, { recursive: true, force: true });
-    }
-  },
-);
-
-test("low-spread stats suggest positive contrast", () => {
-  const { adjust } = statsToAdjust({
-    frames: 1,
-    yMin: 104,
-    yMax: 116,
-    yAvg: 110,
-    uAvg: 128,
-    vAvg: 128,
-  });
-  assert.ok(adjust.contrast > 0, `expected positive contrast, got ${adjust.contrast}`);
-  assertWithinLimits(adjust);
-});
-
-test("malformed media fails cleanly", () => {
-  assert.throws(
-    () => analyzeMediaGrade(join(tmpdir(), "does-not-exist.png")),
-    /grade analysis failed/,
-  );
-});
-
-test(
-  "media path with shell metacharacters is passed as argv, not a shell string",
-  {
-    skip: FFMPEG_SKIP,
-  },
-  () => {
-    const dir = mkdtempSync(join(tmpdir(), "mu-grade-shell-"));
-    const sentinel = join(process.cwd(), "mu-grade-shell-sentinel.png");
-    try {
-      if (existsSync(sentinel)) unlinkSync(sentinel);
-      const file = makeFrame(dir, "frame; touch mu-grade-shell-sentinel.png", "orange");
-      const result = analyzeMediaGrade(file);
-      assert.ok(result.measured.frames >= 1);
-      assert.equal(existsSync(sentinel), false);
-    } finally {
-      if (existsSync(sentinel)) unlinkSync(sentinel);
-      rmSync(dir, { recursive: true, force: true });
-    }
-  },
-);
-
-test("measured note is a stderr-safe single-line summary", () => {
-  const note = formatMeasuredNote("/tmp/frame.png", {
-    frames: 1,
-    yMin: 10,
-    yMax: 240,
-    yAvg: 80,
-    uAvg: 120,
-    vAvg: 140,
-  });
-  assert.match(note, /^media-use: measured /);
-  assert.match(note, /YMIN=10/);
-  assert.match(note, /YMAX=240/);
-  assert.match(note, /YAVG=80/);
-  assert.equal(note.includes("\n"), false);
-});
-
-test("parses deterministic FFmpeg signalstats frames", () => {
-  const frames = parseMediaTreatmentSignalStats(SIGNALSTATS);
-  assert.equal(frames.length, 2);
-  assert.deepEqual(
-    {
-      ptsTime: frames[0]?.ptsTime,
-      YLOW: frames[0]?.YLOW,
-      YAVG: frames[0]?.YAVG,
-      YHIGH: frames[0]?.YHIGH,
-      SATAVG: frames[0]?.SATAVG,
-    },
-    { ptsTime: 0, YLOW: 8, YAVG: 100, YHIGH: 240, SATAVG: 40 },
-  );
-});
-
-test("keeps adjust output while adding HDR metadata and warnings", () => {
-  const result = summarizeMediaTreatmentAnalysis(
-    {
-      duration: 4,
-      colorSpace: "bt2020nc",
-      transfer: "smpte2084",
-      primaries: "bt2020",
-      pixelFormat: "yuv420p10le",
-    },
-    parseMediaTreatmentSignalStats(SIGNALSTATS),
-  );
-
-  assert.deepEqual(
-    {
-      blacks: result.adjust.blacks,
-      whites: result.adjust.whites,
-      frames: result.measured.frames,
-      yLow: result.measured.yLow,
-      yHigh: result.measured.yHigh,
-      satAvg: result.measured.satAvg,
-      shadowClipRisk: result.measured.shadowClipRisk,
-      highlightClipRisk: result.measured.highlightClipRisk,
-    },
-    {
-      blacks: 0.04,
-      whites: -0.04,
-      frames: 2,
-      yLow: 14,
-      yHigh: 230,
-      satAvg: 50,
-      shadowClipRisk: 0.5,
-      highlightClipRisk: 0.5,
-    },
-  );
-  assert.equal(result.source.hdr, true);
-  assert.equal(result.source.log, "unknown");
-  assert.match(result.warnings[0] ?? "", /HDR/);
-});
-
-test("does not force middle-gray exposure onto healthy intentional contrast", () => {
-  const result = summarizeMediaTreatmentAnalysis(
-    {
-      duration: 4,
-      colorSpace: "bt709",
-      transfer: "bt709",
-      primaries: "bt709",
-      pixelFormat: "yuv420p",
-    },
-    [
-      {
-        YMIN: 20,
-        YLOW: 42,
-        YAVG: 122,
-        YHIGH: 190,
-        YMAX: 220,
-        UAVG: 128,
-        VAVG: 128,
-        SATAVG: 40,
-      },
-      {
-        YMIN: 18,
-        YLOW: 38,
-        YAVG: 118,
-        YHIGH: 196,
-        YMAX: 225,
-        UAVG: 128,
-        VAVG: 128,
-        SATAVG: 42,
-      },
-    ],
-  );
-
-  assert.deepEqual(
-    {
-      exposure: result.adjust.exposure,
-      blacks: result.adjust.blacks,
-      whites: result.adjust.whites,
-      temperature: result.adjust.temperature,
-      tint: result.adjust.tint,
-    },
-    { exposure: 0, blacks: 0, whites: 0, temperature: 0, tint: 0 },
-  );
-});