dsh-hyperframes 0.2.0 → 0.3.0

package/skills/media-use/scripts/lib/cube-validate.mjs

@@ -0,0 +1,198 @@
+#!/usr/bin/env node
+
+// Standalone mirror of packages/core/src/colorLuts.ts. media-use cannot import
+// the TypeScript source at runtime, so cube-validate.test.mjs mirrors core
+// parser cases to catch drift in accepted .cube files before freezing them.
+
+import { readFileSync } from "node:fs";
+import { resolve as resolvePath } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const DEFAULT_MAX_CUBE_LUT_SIZE = 64;
+
+const DEFAULT_DOMAIN_MIN = [0, 0, 0];
+const DEFAULT_DOMAIN_MAX = [1, 1, 1];
+
+class CubeValidateError extends Error {
+  constructor(message, lineNumber = null) {
+    super(lineNumber == null ? message : `${message} at line ${lineNumber}`);
+    this.name = "CubeValidateError";
+    this.lineNumber = lineNumber;
+  }
+}
+
+function stripComment(line) {
+  let inQuote = false;
+  for (let i = 0; i < line.length; i++) {
+    const char = line[i];
+    if (char === '"') inQuote = !inQuote;
+    if (char === "#" && !inQuote) return line.slice(0, i);
+  }
+  return line;
+}
+
+function parseFiniteNumber(value, lineNumber) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) {
+    throw new CubeValidateError(`Invalid number "${value}"`, lineNumber);
+  }
+  return parsed;
+}
+
+function parseVec3(parts, keyword, lineNumber) {
+  if (parts.length !== 3) {
+    throw new CubeValidateError(`${keyword} expects three numbers`, lineNumber);
+  }
+  return [
+    parseFiniteNumber(parts[0], lineNumber),
+    parseFiniteNumber(parts[1], lineNumber),
+    parseFiniteNumber(parts[2], lineNumber),
+  ];
+}
+
+function parseSize(value, keyword, lineNumber) {
+  if (!value) throw new CubeValidateError(`${keyword} expects a size`, lineNumber);
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 2) {
+    throw new CubeValidateError(`${keyword} must be an integer greater than 1`, lineNumber);
+  }
+  return parsed;
+}
+
+function validateDomain(domainMin, domainMax) {
+  if (
+    domainMax[0] <= domainMin[0] ||
+    domainMax[1] <= domainMin[1] ||
+    domainMax[2] <= domainMin[2]
+  ) {
+    throw new CubeValidateError("DOMAIN_MAX values must be greater than DOMAIN_MIN values");
+  }
+}
+
+function isNumericDataLine(token) {
+  return /^[+-]?(?:\d|\.\d)/.test(token);
+}
+
+function parseCube(input, options = {}) {
+  const maxSize = options.maxSize ?? DEFAULT_MAX_CUBE_LUT_SIZE;
+  let domainMin = DEFAULT_DOMAIN_MIN;
+  let domainMax = DEFAULT_DOMAIN_MAX;
+  let lut1dSize = null;
+  let lut3dSize = null;
+  let rows = 0;
+
+  const lines = String(input)
+    .replace(/^\uFEFF/, "")
+    .split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const lineNumber = i + 1;
+    const line = stripComment(lines[i] ?? "").trim();
+    if (!line) continue;
+    const parts = line.split(/\s+/);
+    const keyword = (parts[0] ?? "").toUpperCase();
+    const rest = parts.slice(1);
+
+    if (keyword === "TITLE") continue;
+    if (keyword === "DOMAIN_MIN") {
+      domainMin = parseVec3(rest, keyword, lineNumber);
+      continue;
+    }
+    if (keyword === "DOMAIN_MAX") {
+      domainMax = parseVec3(rest, keyword, lineNumber);
+      continue;
+    }
+    if (keyword === "LUT_3D_INPUT_RANGE") {
+      if (rest.length !== 2) {
+        throw new CubeValidateError(`${keyword} expects two numbers`, lineNumber);
+      }
+      const min = parseFiniteNumber(rest[0], lineNumber);
+      const max = parseFiniteNumber(rest[1], lineNumber);
+      if (max <= min) {
+        throw new CubeValidateError("LUT_3D_INPUT_RANGE max must exceed min", lineNumber);
+      }
+      domainMin = [min, min, min];
+      domainMax = [max, max, max];
+      continue;
+    }
+    if (keyword === "LUT_1D_SIZE") {
+      lut1dSize = parseSize(rest[0], keyword, lineNumber);
+      continue;
+    }
+    if (keyword === "LUT_3D_SIZE") {
+      lut3dSize = parseSize(rest[0], keyword, lineNumber);
+      if (lut3dSize > maxSize) {
+        throw new CubeValidateError(`LUT_3D_SIZE ${lut3dSize} exceeds max ${maxSize}`, lineNumber);
+      }
+      continue;
+    }
+
+    if (!isNumericDataLine(keyword)) {
+      if (keyword.startsWith("LUT_")) {
+        throw new CubeValidateError(`Unsupported cube keyword ${keyword}`, lineNumber);
+      }
+      continue;
+    }
+    if (!lut3dSize) {
+      if (lut1dSize) {
+        throw new CubeValidateError("1D cube LUTs are not supported yet", lineNumber);
+      }
+      throw new CubeValidateError("LUT data appears before LUT_3D_SIZE", lineNumber);
+    }
+    if (parts.length !== 3) {
+      throw new CubeValidateError("LUT data rows must contain three numbers", lineNumber);
+    }
+    parseFiniteNumber(parts[0], lineNumber);
+    parseFiniteNumber(parts[1], lineNumber);
+    parseFiniteNumber(parts[2], lineNumber);
+    rows++;
+  }
+
+  if (lut1dSize && lut3dSize) {
+    throw new CubeValidateError("Mixed 1D and 3D cube LUTs are not supported yet");
+  }
+  if (!lut3dSize) {
+    if (lut1dSize) throw new CubeValidateError("1D cube LUTs are not supported yet");
+    throw new CubeValidateError("Missing LUT_3D_SIZE");
+  }
+  validateDomain(domainMin, domainMax);
+
+  const expectedRows = lut3dSize * lut3dSize * lut3dSize;
+  if (rows !== expectedRows) {
+    throw new CubeValidateError(
+      `Expected ${expectedRows} LUT rows for size ${lut3dSize}, found ${rows}`,
+    );
+  }
+
+  return { size: lut3dSize };
+}
+
+export function validateCube(input, options = {}) {
+  try {
+    const parsed = parseCube(input, options);
+    return { ok: true, size: parsed.size };
+  } catch (err) {
+    return { ok: false, error: err.message };
+  }
+}
+
+export function validateCubeFile(filePath, options = {}) {
+  return validateCube(readFileSync(filePath, "utf8"), options);
+}
+
+function main(argv) {
+  const file = argv[2];
+  if (!file) {
+    console.error("usage: cube-validate.mjs <file.cube>");
+    process.exit(2);
+  }
+  const result = validateCubeFile(file);
+  if (!result.ok) {
+    console.error(`error: ${result.error}`);
+    process.exit(1);
+  }
+  console.log(`ok: LUT_3D_SIZE ${result.size}`);
+}
+
+if (process.argv[1] && resolvePath(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main(process.argv);
+}

package/skills/media-use/scripts/lib/cube-validate.test.mjs

@@ -0,0 +1,125 @@
+import { strict as assert } from "node:assert";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { test } from "node:test";
+import { validateCube } from "./cube-validate.mjs";
+
+const IDENTITY_2 = `
+# comment
+TITLE "Identity 2"
+DOMAIN_MIN 0 0 0
+DOMAIN_MAX 1 1 1
+LUT_3D_SIZE 2
+0 0 0
+1 0 0
+0 1 0
+1 1 0
+0 0 1
+1 0 1
+0 1 1
+1 1 1
+`;
+
+test("accepts a valid minimal 3D cube LUT", () => {
+  const result = validateCube(IDENTITY_2);
+  assert.deepEqual(result, { ok: true, size: 2 });
+});
+
+test("rejects oversize LUTs with the core parser message", () => {
+  const result = validateCube("LUT_3D_SIZE 65", { maxSize: 64 });
+  assert.equal(result.ok, false);
+  assert.match(result.error, /LUT_3D_SIZE 65 exceeds max 64/);
+});
+
+test("rejects data rows before LUT_3D_SIZE", () => {
+  const result = validateCube("0 0 0\nLUT_3D_SIZE 2");
+  assert.equal(result.ok, false);
+  assert.match(result.error, /LUT data appears before LUT_3D_SIZE/);
+});
+
+test("rejects missing LUT_3D_SIZE", () => {
+  const result = validateCube('TITLE "No Size"');
+  assert.equal(result.ok, false);
+  assert.match(result.error, /Missing LUT_3D_SIZE/);
+});
+
+test("rejects row count mismatches with the core parser message", () => {
+  const result = validateCube("LUT_3D_SIZE 2\n0 0 0");
+  assert.equal(result.ok, false);
+  assert.match(result.error, /Expected 8 LUT rows/);
+});
+
+test("rejects inverted domains", () => {
+  const result = validateCube(`
+    DOMAIN_MIN 0 0 0
+    DOMAIN_MAX 1 0 1
+    LUT_3D_SIZE 2
+    0 0 0
+    1 0 0
+    0 1 0
+    1 1 0
+    0 0 1
+    1 0 1
+    0 1 1
+    1 1 1
+  `);
+  assert.equal(result.ok, false);
+  assert.match(result.error, /DOMAIN_MAX values must be greater than DOMAIN_MIN values/);
+});
+
+test("rejects unsupported 1D and mixed cube LUTs", () => {
+  const oneD = validateCube("LUT_1D_SIZE 2\n0 0 0\n1 1 1");
+  assert.equal(oneD.ok, false);
+  assert.match(oneD.error, /1D cube LUTs are not supported yet/);
+
+  const mixed = validateCube(`
+    LUT_1D_SIZE 2
+    LUT_3D_SIZE 2
+    0 0 0
+    1 0 0
+    0 1 0
+    1 1 0
+    0 0 1
+    1 0 1
+    0 1 1
+    1 1 1
+  `);
+  assert.equal(mixed.ok, false);
+  assert.match(mixed.error, /Mixed 1D and 3D cube LUTs are not supported yet/);
+});
+
+test("CLI exits zero for valid files and non-zero for invalid files", () => {
+  const dir = mkdtempSync(join(tmpdir(), "mu-cube-validate-"));
+  try {
+    const valid = join(dir, "valid.cube");
+    const invalid = join(dir, "invalid.cube");
+    writeFileSync(valid, IDENTITY_2);
+    writeFileSync(invalid, "LUT_3D_SIZE 65");
+
+    const out = execFileSync(
+      process.execPath,
+      [new URL("./cube-validate.mjs", import.meta.url).pathname, valid],
+      {
+        encoding: "utf8",
+      },
+    );
+    assert.match(out, /ok: LUT_3D_SIZE 2/);
+
+    assert.throws(
+      () =>
+        execFileSync(
+          process.execPath,
+          [new URL("./cube-validate.mjs", import.meta.url).pathname, invalid],
+          {
+            encoding: "utf8",
+            stdio: "pipe",
+          },
+        ),
+      (err) => err.status === 1 && String(err.stderr).includes("exceeds max 64"),
+    );
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});

package/skills/media-use/scripts/lib/cutlist.mjs

@@ -0,0 +1,184 @@
+import { normalizeWords } from "./words.mjs";
+
+const MIN_SEGMENT_SECONDS = 0.2;
+const SILENCE_PAD_SECONDS = 0.15;
+
+export function compileCutList(transcript, opts = {}) {
+  const words = normalizeWords(transcript);
+  if (opts.keep != null && hasRemovalSource(opts)) {
+    throw new Error("--keep is mutually exclusive with removal options");
+  }
+
+  if (opts.keep != null) {
+    const duration = durationFrom(words, opts);
+    const ranges = parseTimeRanges(opts.keep);
+    return finalizeKept(duration != null ? clampRanges(ranges, duration) : ranges);
+  }
+
+  const duration = durationFrom(words, opts);
+  if (!duration) return [];
+
+  const removals = [
+    ...parseTimeRanges(opts.remove),
+    ...wordIndexRanges(words, opts.removeWords),
+    ...fillerRanges(words, opts.removeFillers),
+    ...silenceRanges(words, opts.cutSilence),
+  ];
+  const mergedRemovals = mergeRanges(clampRanges(removals, duration));
+  return finalizeKept(invertRanges(mergedRemovals, duration));
+}
+
+function hasRemovalSource(opts) {
+  return (
+    opts.remove != null ||
+    opts.removeWords != null ||
+    opts.removeFillers != null ||
+    opts.cutSilence != null
+  );
+}
+
+function durationFrom(words, opts) {
+  const explicit = Number(opts.duration ?? opts.totalDuration);
+  if (Number.isFinite(explicit) && explicit > 0) return explicit;
+  const last = words.at(-1);
+  return last && Number.isFinite(last.end) && last.end > 0 ? last.end : null;
+}
+
+function parseTimeRanges(value) {
+  if (value == null || value === false || value === "") return [];
+  if (typeof value === "string") {
+    return value
+      .split(",")
+      .map((part) => part.trim())
+      .filter(Boolean)
+      .map(parseRangeString);
+  }
+  if (!Array.isArray(value)) throw new Error("range list must be a string or array");
+  return value.map((range) => {
+    if (Array.isArray(range)) return cleanRange(Number(range[0]), Number(range[1]));
+    return cleanRange(Number(range?.start), Number(range?.end));
+  });
+}
+
+function parseRangeString(value) {
+  const match = value.match(/^([0-9]*\.?[0-9]+)\s*-\s*([0-9]*\.?[0-9]+)$/);
+  if (!match) throw new Error(`invalid range: ${value}`);
+  return cleanRange(Number(match[1]), Number(match[2]));
+}
+
+function cleanRange(start, end) {
+  if (!Number.isFinite(start) || !Number.isFinite(end)) {
+    throw new Error("range start/end must be finite numbers");
+  }
+  if (end < start) throw new Error(`range end ${end} is before start ${start}`);
+  return { start, end };
+}
+
+function wordIndexRanges(words, value) {
+  if (value == null || value === false || value === "") return [];
+  const ranges = typeof value === "string" ? value.split(",") : value;
+  if (!Array.isArray(ranges)) throw new Error("--remove-words must be a string or array");
+  return ranges
+    .map((range) => (typeof range === "string" ? range.trim() : range))
+    .filter(Boolean)
+    .map((range) => {
+      const [first, last = first] =
+        typeof range === "string" ? range.split("-").map((n) => n.trim()) : range;
+      const startIndex = Number(first);
+      const endIndex = Number(last);
+      if (!Number.isInteger(startIndex) || !Number.isInteger(endIndex)) {
+        throw new Error(`invalid word range: ${range}`);
+      }
+      if (startIndex < 0 || endIndex < startIndex || endIndex >= words.length) {
+        throw new Error(`word range out of bounds: ${range}`);
+      }
+      return { start: words[startIndex].start, end: words[endIndex].end };
+    });
+}
+
+function fillerRanges(words, value) {
+  if (value == null || value === false || value === "") return [];
+  const fillers = Array.isArray(value)
+    ? value
+    : String(value)
+        .split(",")
+        .map((s) => s.trim());
+  const set = new Set(fillers.filter(Boolean).map(bareToken));
+  if (set.size === 0) return [];
+  // Whisper emits words with attached punctuation and arbitrary case
+  // ("UM," / "Um."), so compare bare tokens.
+  return words
+    .filter((word) => set.has(bareToken(word.text)))
+    .map((word) => ({ start: word.start, end: word.end }));
+}
+
+function bareToken(text) {
+  return String(text)
+    .toLowerCase()
+    .replace(/^[^\p{L}\p{N}]+|[^\p{L}\p{N}]+$/gu, "");
+}
+
+function silenceRanges(words, value) {
+  if (value == null || value === false || value === "") return [];
+  const threshold = Number(value);
+  if (!Number.isFinite(threshold) || threshold <= 0) {
+    throw new Error("--cut-silence must be a positive number");
+  }
+  const ranges = [];
+  for (let i = 0; i < words.length - 1; i++) {
+    const current = words[i];
+    const next = words[i + 1];
+    const gap = next.start - current.end;
+    if (gap <= threshold) continue;
+    const start = current.end + SILENCE_PAD_SECONDS;
+    const end = next.start - SILENCE_PAD_SECONDS;
+    if (end > start) ranges.push({ start, end });
+  }
+  return ranges;
+}
+
+function clampRanges(ranges, duration) {
+  return ranges
+    .map((range) => ({
+      start: Math.max(0, Math.min(duration, range.start)),
+      end: Math.max(0, Math.min(duration, range.end)),
+    }))
+    .filter((range) => range.end > range.start);
+}
+
+function mergeRanges(ranges) {
+  const sorted = ranges
+    .map((range) => ({ start: round3(range.start), end: round3(range.end) }))
+    .sort((a, b) => a.start - b.start || a.end - b.end);
+  const merged = [];
+  for (const range of sorted) {
+    const prev = merged.at(-1);
+    if (prev && range.start <= prev.end) {
+      prev.end = Math.max(prev.end, range.end);
+    } else {
+      merged.push({ ...range });
+    }
+  }
+  return merged;
+}
+
+function invertRanges(removals, duration) {
+  const kept = [];
+  let cursor = 0;
+  for (const range of removals) {
+    if (range.start > cursor) kept.push({ start: cursor, end: range.start });
+    cursor = Math.max(cursor, range.end);
+  }
+  if (cursor < duration) kept.push({ start: cursor, end: duration });
+  return kept;
+}
+
+function finalizeKept(ranges) {
+  return mergeRanges(ranges)
+    .map((range) => ({ start: round3(range.start), end: round3(range.end) }))
+    .filter((range) => round3(range.end - range.start) >= MIN_SEGMENT_SECONDS);
+}
+
+function round3(n) {
+  return Math.round(Number(n) * 1000) / 1000;
+}

package/skills/media-use/scripts/lib/cutlist.test.mjs

@@ -0,0 +1,148 @@
+import { strict as assert } from "node:assert";
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { test } from "node:test";
+import { compileCutList } from "./cutlist.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const SCRIPT = join(HERE, "..", "transcript-cut.mjs");
+
+test("explicit --remove ranges invert to kept segments", () => {
+  const transcript = [
+    word("w0", "alpha", 0, 1),
+    word("w1", "beta", 1.2, 2),
+    word("w2", "gamma", 2.2, 5),
+  ];
+
+  assert.deepEqual(compileCutList(transcript, { remove: "1-2.5" }), [
+    { start: 0, end: 1 },
+    { start: 2.5, end: 5 },
+  ]);
+});
+
+test("--remove-words resolves inclusive word-index ranges to time ranges", () => {
+  const transcript = [
+    word("w0", "zero", 0, 0.5),
+    word("w1", "one", 0.6, 1),
+    word("w2", "two", 1.1, 1.5),
+    word("w3", "three", 2, 3),
+  ];
+
+  assert.deepEqual(compileCutList(transcript, { removeWords: "1-2" }), [
+    { start: 0, end: 0.6 },
+    { start: 1.5, end: 3 },
+  ]);
+});
+
+test("--remove-fillers drops case-insensitive matching words", () => {
+  const transcript = [
+    word("w0", "Hello", 0, 0.5),
+    word("w1", "Um", 0.5, 0.7),
+    word("w2", "world", 0.8, 1.2),
+    word("w3", "LIKE", 1.3, 1.5),
+    word("w4", "done", 1.6, 2),
+  ];
+
+  assert.deepEqual(compileCutList(transcript, { removeFillers: "um,like" }), [
+    { start: 0, end: 0.5 },
+    { start: 0.7, end: 1.3 },
+    { start: 1.5, end: 2 },
+  ]);
+});
+
+test("--cut-silence removes only the center of long inter-word gaps", () => {
+  const transcript = [word("w0", "a", 0, 0.5), word("w1", "b", 2, 2.5), word("w2", "c", 2.7, 3)];
+
+  assert.deepEqual(compileCutList(transcript, { cutSilence: 0.8 }), [
+    { start: 0, end: 0.65 },
+    { start: 1.85, end: 3 },
+  ]);
+});
+
+test("overlapping removal sources merge before inversion", () => {
+  const transcript = [
+    word("w0", "start", 0, 0.5),
+    word("w1", "um", 0.9, 1.1),
+    word("w2", "middle", 2.5, 2.8),
+    word("w3", "more", 3.1, 3.4),
+    word("w4", "end", 5.5, 6),
+  ];
+
+  assert.deepEqual(
+    compileCutList(transcript, {
+      remove: "1-2.7",
+      removeWords: "2-3",
+      removeFillers: "um",
+    }),
+    [
+      { start: 0, end: 0.9 },
+      { start: 3.4, end: 6 },
+    ],
+  );
+});
+
+test("kept slivers shorter than 0.2s are dropped", () => {
+  const transcript = [word("w0", "start", 0, 0.5), word("w1", "end", 2.5, 3)];
+
+  assert.deepEqual(compileCutList(transcript, { remove: "0.1-2.95" }), []);
+});
+
+test("--keep is inverse mode and coalesces direct kept ranges", () => {
+  const transcript = [word("w0", "start", 0, 0.5), word("w1", "end", 4.5, 5)];
+
+  assert.deepEqual(compileCutList(transcript, { keep: "3-4,1-2,1.5-2.5,4.1-4.2" }), [
+    { start: 1, end: 2.5 },
+    { start: 3, end: 4 },
+  ]);
+});
+
+test("--plan on a fixture transcript prints the exact segment JSON", () => {
+  const dir = mkdtempSync(join(tmpdir(), "media-use-cutlist-"));
+  try {
+    const transcriptPath = join(dir, "fixture.json");
+    writeFileSync(
+      transcriptPath,
+      JSON.stringify([
+        word("w0", "hello", 0, 0.4),
+        word("w1", "um", 0.5, 0.65),
+        word("w2", "there", 0.7, 1),
+        word("w3", "pause", 2.2, 2.5),
+        word("w4", "end", 2.7, 3.2),
+      ]),
+    );
+
+    const out = execFileSync(
+      process.execPath,
+      [
+        SCRIPT,
+        "--input",
+        "ignored.mp4",
+        "--transcript",
+        transcriptPath,
+        "--remove",
+        "0.9-1.2",
+        "--remove-fillers",
+        "um",
+        "--cut-silence",
+        "0.8",
+        "--plan",
+      ],
+      { encoding: "utf8" },
+    );
+
+    assert.deepEqual(JSON.parse(out), [
+      { start: 0, end: 0.5 },
+      { start: 0.65, end: 0.9 },
+      { start: 2.05, end: 3.2 },
+    ]);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+function word(id, text, start, end) {
+  return { id, text, start, end };
+}