dsh-hyperframes 0.10.1 → 0.11.0

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

@@ -0,0 +1,285 @@
+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 },
+  );
+});

package/skills/media-use/scripts/lib/heygen-cli.mjs

@@ -0,0 +1,208 @@
+import { execFileSync } from "node:child_process";
+import { track } from "./telemetry.mjs";
+
+// v0.3.0 is the first CLI that can use an OAuth session; v0.1.x/0.2.x reject it
+// ("heygen-cli can't use OAuth yet"), and OAuth is what the free-usage path
+// needs — so anything below this can't authenticate for free usage at all.
+export const HEYGEN_MIN_VERSION = "0.3.0";
+// Free-usage path is OAuth (`--oauth` → subscription/free credits); `--api-key`
+// bills API credits, so the onboarding steers to OAuth. Keep pipe-to-shell
+// installer text out of the runtime module; the docs are the safer source of
+// truth for platform-specific setup.
+export const HEYGEN_INSTALL_COMMAND =
+  "Install the CLI from https://developers.heygen.com/cli, then run: heygen auth login --oauth";
+export const HEYGEN_AUTH_COMMAND = "heygen auth login --oauth";
+export const HEYGEN_UPDATE_COMMAND = "heygen update";
+export const HEYGEN_CLIENT_SOURCE_ARGV = ["--headers", "X-HeyGen-Client-Source: media-use"];
+
+export const HEYGEN_NOT_FOUND_MESSAGE = `media-use: heygen CLI not found — it's the free path for bgm/image/voice/avatar-video. ${HEYGEN_INSTALL_COMMAND}`;
+export const HEYGEN_NOT_AUTHENTICATED_MESSAGE = `media-use: heygen CLI not authenticated (free usage) — run: ${HEYGEN_AUTH_COMMAND}`;
+export const HEYGEN_OUTDATED_MESSAGE = `media-use: heygen CLI is outdated — run: ${HEYGEN_UPDATE_COMMAND}  (need >= v${HEYGEN_MIN_VERSION})`;
+
+const ACTIONABLE_MESSAGES = new Set([
+  HEYGEN_NOT_FOUND_MESSAGE,
+  HEYGEN_NOT_AUTHENTICATED_MESSAGE,
+  HEYGEN_OUTDATED_MESSAGE,
+]);
+
+export function classifyHeygenError(err) {
+  return classifyHeygenErrorResult(err).message;
+}
+
+export function classifyHeygenErrorCode(err) {
+  return classifyHeygenErrorResult(err).code;
+}
+
+function classifyHeygenErrorResult(err) {
+  const detail = heygenErrorDetail(err);
+  const text = [err?.stderr, err?.stdout, err?.message, detail]
+    .map((value) => textOf(value))
+    .filter(Boolean)
+    .join("\n");
+  const lower = text.toLowerCase();
+
+  // Only ENOENT (spawn of a missing binary) or a shell's "command not found"
+  // mean the CLI itself is absent. A bare "not found" would misfire on the CLI's
+  // own resource errors (e.g. a stale voiceId → "voice not found"), whose message
+  // embeds the `heygen ...` command line — sending users to reinstall a CLI they
+  // just ran successfully. Keep this narrow.
+  if (err?.code === "ENOENT" || lower.includes("command not found")) {
+    return { code: "not_found", message: HEYGEN_NOT_FOUND_MESSAGE };
+  }
+
+  if (
+    lower.includes("unauthorized") ||
+    lower.includes("unauthenticated") ||
+    // \b401\b, not a bare "401" substring — otherwise request IDs (req-401abc),
+    // URLs, and retry-after headers would misclassify as an auth failure.
+    /\b401\b/.test(lower) ||
+    lower.includes("not logged in") ||
+    lower.includes("no api key") ||
+    lower.includes("missing api key") ||
+    lower.includes("invalid api key") ||
+    lower.includes("login required") ||
+    lower.includes("auth required") ||
+    lower.includes("authentication required")
+  ) {
+    return { code: "not_authenticated", message: HEYGEN_NOT_AUTHENTICATED_MESSAGE };
+  }
+
+  const version = firstSemver(text);
+  // A CLI older than the --headers flag rejects it before printing any version.
+  if (
+    (version && versionLessThan(version, HEYGEN_MIN_VERSION)) ||
+    lower.includes("unknown flag: --headers")
+  ) {
+    return { code: "outdated", message: HEYGEN_OUTDATED_MESSAGE };
+  }
+
+  if (
+    lower.includes("rate limit") ||
+    lower.includes("quota") ||
+    lower.includes("insufficient credit") ||
+    lower.includes("too many requests") ||
+    lower.includes("throttled") ||
+    /\b429\b/.test(lower)
+  ) {
+    return { code: "rate_limited", message: detail };
+  }
+
+  return { code: "other", message: detail };
+}
+
+// reportHeygenFailure's callers (voice-provider.mjs, heygen-search.mjs) are
+// synchronous and several layers below the CLI's process.exit() calls, so
+// they can't await this tracking call themselves. Stash each attempt's
+// promise here so a caller closer to exit (resolve.mjs) can join it first —
+// same "awaited so a short-lived run flushes it" discipline telemetry.mjs's
+// track() already documents, just reachable from a sync call site.
+const pendingFailureTracking = new Set();
+// resolve.mjs is a single-shot CLI (one resolve per process), so one shared
+// consume-once slot is sufficient. If resolve becomes an in-process/concurrent
+// API, move this state into a per-resolve context before reusing that path.
+let pendingRemediation = null;
+
+/** A music resolve miss after the heygen CLI was missing or too old: what is missing, the host app's own
+ * tool, the fix. Other types keep the generic miss. */
+export function heygenMiss(type, { code }) {
+  if (type !== "bgm") return null;
+  const outdated = code === "outdated";
+  const state = outdated ? `older than v${HEYGEN_MIN_VERSION}` : "not installed";
+  return {
+    code: outdated ? "heygen_cli_outdated" : "heygen_cli_missing",
+    fix: outdated ? HEYGEN_UPDATE_COMMAND : HEYGEN_INSTALL_COMMAND,
+    error: `${type} needs the heygen CLI, which is ${state}: use your host app's own music tool if it has one, or ${outdated ? "update" : "install"} the CLI.`,
+  };
+}
+
+export function consumeHeygenRemediation() {
+  const remediation = pendingRemediation;
+  pendingRemediation = null;
+  return remediation;
+}
+
+export function reportHeygenFailure(err, context, trackEvent = track) {
+  const { code, message } = classifyHeygenErrorResult(err);
+  if (code === "not_found" || code === "outdated") {
+    pendingRemediation = { code, message };
+  }
+  if (ACTIONABLE_MESSAGES.has(message)) {
+    console.error(message);
+  } else {
+    console.error(`media-use: \`${context}\` failed: ${message}`);
+  }
+  try {
+    const tracked = Promise.resolve(
+      trackEvent("media_use_provider_error", { provider: "heygen", reason: code }),
+    ).catch(() => {});
+    pendingFailureTracking.add(tracked);
+    void tracked.finally(() => pendingFailureTracking.delete(tracked));
+    return tracked;
+  } catch {
+    // Telemetry must never affect the provider failure path.
+    return Promise.resolve();
+  }
+}
+
+// Awaits every provider-error track fired since the last flush, so a caller
+// about to process.exit() doesn't orphan one mid-request (both are separate,
+// non-keepalive HTTP connections with no ordering guarantee otherwise).
+// Never rejects: each tracked promise already swallows its own failure.
+export async function flushHeygenFailureTracking() {
+  if (pendingFailureTracking.size === 0) return;
+  await Promise.all(pendingFailureTracking);
+}
+
+// Shared discovery/generation helper for the CLI-shelling providers (voice,
+// avatar-video): run a heygen JSON subcommand, report+classify on failure,
+// and hand the caller the classified reason via onError (used by callers that
+// need to distinguish e.g. not_authenticated from other failures).
+export function runHeygenJson(bin, argv, label, onError) {
+  let out;
+  try {
+    out = execFileSync(bin, argv, {
+      encoding: "utf8",
+      timeout: 120000,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+  } catch (err) {
+    reportHeygenFailure(err, `${bin} ${label}`);
+    onError?.(classifyHeygenErrorCode(err));
+    return null;
+  }
+  try {
+    return JSON.parse(out);
+  } catch {
+    console.error(`media-use: \`${bin} ${label}\` returned non-JSON output`);
+    return null;
+  }
+}
+
+export function firstSemver(text) {
+  const match = String(text || "").match(/\bv?(\d+)\.(\d+)\.(\d+)\b/);
+  return match ? `${match[1]}.${match[2]}.${match[3]}` : null;
+}
+
+export function versionLessThan(version, minimum) {
+  const left = versionParts(version);
+  const right = versionParts(minimum);
+  if (!left || !right) return false;
+  for (let i = 0; i < 3; i++) {
+    if (left[i] < right[i]) return true;
+    if (left[i] > right[i]) return false;
+  }
+  return false;
+}
+
+function heygenErrorDetail(err) {
+  return textOf(err?.stderr) || textOf(err?.stdout) || err?.message || String(err);
+}
+
+function textOf(value) {
+  return value == null ? "" : String(value).trim();
+}
+
+function versionParts(version) {
+  const match = String(version || "").match(/^v?(\d+)\.(\d+)\.(\d+)$/);
+  return match ? match.slice(1).map((part) => Number.parseInt(part, 10)) : null;
+}