dsh-hyperframes 0.10.1 → 0.11.0

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.test.mjs

@@ -0,0 +1,174 @@
+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));
+// These legacy wrappers remain under skills/media-use/scripts because the
+// skill's public audio entrypoints still invoke them; the moved engine tests
+// their implementation here while preserving that compatibility surface.
+const SCRIPT = join(
+  HERE,
+  "..",
+  "..",
+  "..",
+  "..",
+  "..",
+  "skills",
+  "media-use",
+  "scripts",
+  "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("kept ranges keep frame precision instead of rounding to the millisecond", () => {
+  const transcript = [word("w0", "start", 0, 1), word("w1", "end", 14, 15)];
+
+  // Frame 386 at 30 fps is 12.866666 s. These bounds become ffmpeg's -ss/-to, so
+  // rounding them to 12.867 hands ffmpeg a time just past the frame and the
+  // segment starts one frame late.
+  assert.deepEqual(compileCutList(transcript, { keep: "0-1,12.866666666666667-14" }), [
+    { start: 0, end: 1 },
+    { start: 12.866667, end: 14 },
+  ]);
+});
+
+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 };
+}

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

@@ -0,0 +1,319 @@
+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 { duckKeyframes, duckLane, speechSpans } from "./duck.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+// Keep the skill-owned wrapper path under test until the compatibility layer
+// is removed in a later release.
+const SCRIPT = join(
+  HERE,
+  "..",
+  "..",
+  "..",
+  "..",
+  "..",
+  "skills",
+  "media-use",
+  "scripts",
+  "audio-duck.mjs",
+);
+
+test("speechSpans bridges gaps smaller than mergeGap", () => {
+  const meta = {
+    words: [word("w0", "one", 0, 0.5), word("w1", "two", 0.8, 1), word("w2", "three", 2, 2.2)],
+  };
+
+  assert.deepEqual(speechSpans(meta, { mergeGap: 0.4 }), [
+    { start: 0, end: 1 },
+    { start: 2, end: 2.2 },
+  ]);
+});
+
+test("speechSpans refuses multi-line meta without placement (file-relative times)", () => {
+  const meta = {
+    voices: [
+      { id: "a", words: [word("w0", "one", 0, 1)] },
+      { id: "b", words: [word("w1", "two", 0, 1)] },
+    ],
+  };
+  assert.throws(() => speechSpans(meta, { mergeGap: 0.2 }), /--sequential or --offsets/);
+});
+
+test("speechSpans sequential stacks lines by duration plus gap", () => {
+  const meta = {
+    voices: [
+      { id: "a", duration_s: 2, words: [word("w0", "one", 0.1, 1.9)] },
+      { id: "b", duration_s: 1, words: [word("w1", "two", 0.1, 0.9)] },
+    ],
+  };
+  assert.deepEqual(speechSpans(meta, { mergeGap: 0.2, sequential: true, gap: 0.5 }), [
+    { start: 0.1, end: 1.9 },
+    { start: 2.6, end: 3.4 },
+  ]);
+});
+
+test("speechSpans explicit offsets place each line at composition time", () => {
+  const meta = {
+    voices: [
+      { id: "a", words: [word("w0", "one", 0, 1)] },
+      { id: "b", words: [word("w1", "two", 0, 1)] },
+    ],
+  };
+  assert.deepEqual(speechSpans(meta, { mergeGap: 0.2, offsets: { a: 0, b: 4 } }), [
+    { start: 0, end: 1 },
+    { start: 4, end: 5 },
+  ]);
+  assert.throws(() => speechSpans(meta, { offsets: { a: 0 } }), /missing voice "b"/);
+});
+
+test("speechSpans returns empty spans for empty input", () => {
+  assert.deepEqual(speechSpans({ voices: [] }, { mergeGap: 0.6 }), []);
+});
+
+test("speechSpans offsets retain voice IDs across empty transcripts", () => {
+  const meta = {
+    voices: [
+      { id: "silent", duration_s: 2, words: [] },
+      { id: "narration", duration_s: 1, words: [word("w0", "hello", 0.1, 0.9)] },
+    ],
+  };
+  const expected = [{ start: 4.1, end: 4.9 }];
+  assert.deepEqual(speechSpans(meta, { offsets: { silent: 0, narration: 4 } }), expected);
+  assert.deepEqual(speechSpans(meta, { offsets: { narration: 4 } }), expected);
+  assert.throws(() => speechSpans(meta, { offsets: { silent: 0 } }), /missing voice "narration"/);
+});
+
+test("speechSpans sequential counts empty line durations and gaps", () => {
+  const meta = {
+    voices: [
+      { id: "intro", duration_s: 2, words: [] },
+      { id: "first", duration_s: 1, words: [word("w0", "hello", 0.1, 0.9)] },
+      { id: "pause", duration_s: 3, words: [] },
+      { id: "last", duration_s: 1, words: [word("w1", "goodbye", 0.1, 0.9)] },
+    ],
+  };
+  assert.deepEqual(speechSpans(meta, { sequential: true, gap: 0.5 }), [
+    { start: 2.6, end: 3.4 },
+    { start: 7.6, end: 8.4 },
+  ]);
+});
+
+test("speechSpans offsets without IDs retain original voice indices", () => {
+  const meta = {
+    voices: [{ duration_s: 2 }, { duration_s: 1, words: [word("w0", "hello", 0.1, 0.9)] }],
+  };
+  assert.deepEqual(speechSpans(meta, { offsets: { 1: 4 } }), [{ start: 4.1, end: 4.9 }]);
+});
+
+test("speechSpans keeps normalized-empty transcripts aligned with their voices", () => {
+  const meta = {
+    voices: [
+      { id: "untimed", duration_s: 2, words: [{ text: "hello" }] },
+      { id: "narration", duration_s: 1, words: [word("w0", "hello", 0.1, 0.9)] },
+    ],
+  };
+  assert.deepEqual(speechSpans(meta, { sequential: true }), [{ start: 2.1, end: 2.9 }]);
+});
+
+test("speechSpans does not require placement for transcripts without speech", () => {
+  const meta = {
+    voices: [
+      { id: "a", duration_s: 2, words: [] },
+      { id: "b", duration_s: 1 },
+    ],
+  };
+  assert.deepEqual(speechSpans(meta), []);
+  assert.deepEqual(speechSpans(meta, { offsets: {} }), []);
+  assert.deepEqual(speechSpans(meta, { sequential: true }), []);
+});
+
+test("duckKeyframes shapes attack and release from base volume", () => {
+  assert.deepEqual(
+    duckKeyframes([{ start: 3, end: 5 }], {
+      duck: 0.25,
+      attack: 0.15,
+      release: 0.4,
+      baseVolume: 0.6,
+    }),
+    [
+      { time: 3, volume: 0.15, duration: 0.15 },
+      { time: 5, volume: 0.6, duration: 0.4 },
+    ],
+  );
+});
+
+test("duckLane turns composition-time keyframes into clip-local ramps", () => {
+  const keyframes = [
+    { time: 3, volume: 0.15, duration: 0.15 },
+    { time: 5, volume: 0.6, duration: 0.4 },
+  ];
+  assert.deepEqual(duckLane(keyframes, { clipStart: 1, baseVolume: 0.6 }), {
+    version: 1,
+    lanes: [
+      {
+        target: "volume",
+        points: [
+          { t: 0, v: 0.6 },
+          { t: 2, v: 0.6 },
+          { t: 2.15, v: 0.15 },
+          { t: 4, v: 0.15 },
+          { t: 4.4, v: 0.6 },
+        ],
+      },
+    ],
+  });
+});
+
+for (const [name, clipStart, expected] of [
+  [
+    "before the attack",
+    0.5,
+    [
+      { t: 0, v: 0.6 },
+      { t: 0.5, v: 0.6 },
+      { t: 0.65, v: 0.15 },
+      { t: 2.5, v: 0.15 },
+      { t: 2.9, v: 0.6 },
+    ],
+  ],
+  [
+    "during the attack",
+    1.075,
+    [
+      { t: 0, v: 0.375 },
+      { t: 0.075, v: 0.15 },
+      { t: 1.925, v: 0.15 },
+      { t: 2.325, v: 0.6 },
+    ],
+  ],
+  [
+    "during speech",
+    2,
+    [
+      { t: 0, v: 0.15 },
+      { t: 1, v: 0.15 },
+      { t: 1.4, v: 0.6 },
+    ],
+  ],
+  [
+    "at the release",
+    3,
+    [
+      { t: 0, v: 0.15 },
+      { t: 0.4, v: 0.6 },
+    ],
+  ],
+  [
+    "during the release",
+    3.2,
+    [
+      { t: 0, v: 0.375 },
+      { t: 0.2, v: 0.6 },
+    ],
+  ],
+  ["after narration", 4, [{ t: 0, v: 0.6 }]],
+]) {
+  test(`duckLane preserves composition-time gain when music starts ${name}`, () => {
+    const keyframes = duckKeyframes([{ start: 1, end: 3 }], { baseVolume: 0.6 });
+    const points = duckLane(keyframes, { clipStart, baseVolume: 0.6 }).lanes[0].points;
+
+    assert.equal(points.length, expected.length);
+    for (let i = 0; i < points.length; i++) {
+      assert.equal(points[i].t, expected[i].t);
+      assert.ok(
+        Math.abs(points[i].v - expected[i].v) < 1e-9,
+        `gain at ${points[i].t}s: expected ${expected[i].v}, received ${points[i].v}`,
+      );
+    }
+  });
+}
+
+test("duckLane discards earlier narration and retains the next speech span", () => {
+  const keyframes = duckKeyframes([
+    { start: 1, end: 2 },
+    { start: 5, end: 6 },
+  ]);
+
+  assert.deepEqual(duckLane(keyframes, { clipStart: 3 }).lanes[0].points, [
+    { t: 0, v: 1 },
+    { t: 2, v: 1 },
+    { t: 2.15, v: 0.25 },
+    { t: 3, v: 0.25 },
+    { t: 3.4, v: 1 },
+  ]);
+});
+
+test("--json spans match --merge-gap semantics exactly", () => {
+  const dir = mkdtempSync(join(tmpdir(), "media-use-duck-"));
+  try {
+    const metaPath = join(dir, "audio_meta.json");
+    writeFileSync(
+      metaPath,
+      JSON.stringify({
+        voices: [
+          {
+            id: "narration",
+            words: [
+              word("w0", "one", 0, 0.4),
+              word("w1", "two", 0.9, 1.2),
+              word("w2", "three", 1.8, 2.1),
+            ],
+          },
+        ],
+      }),
+    );
+
+    const out = execFileSync(
+      process.execPath,
+      [SCRIPT, "--meta", metaPath, "--target", "#bgm", "--merge-gap", "0.6", "--json"],
+      { encoding: "utf8" },
+    );
+
+    const parsed = JSON.parse(out);
+    assert.deepEqual(parsed.spans, [
+      { start: 0, end: 1.2 },
+      { start: 1.8, end: 2.1 },
+    ]);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+for (const [placement, flags, expected] of [
+  ["sequential", ["--sequential", "--gap", "0.5"], [{ start: 2.6, end: 3.4 }]],
+  ["offsets", ["--offsets", "narration=4"], [{ start: 4.1, end: 4.9 }]],
+]) {
+  test(`audio-duck --json preserves empty voice placement with ${placement}`, (t) => {
+    const dir = mkdtempSync(join(tmpdir(), "media-use-duck-empty-"));
+    t.after(() => rmSync(dir, { recursive: true, force: true }));
+    const metaPath = join(dir, "audio_meta.json");
+    writeFileSync(
+      metaPath,
+      JSON.stringify({
+        voices: [
+          { id: "silent", duration_s: 2, words: [] },
+          { id: "narration", duration_s: 1, words: [word("w0", "hello", 0.1, 0.9)] },
+        ],
+      }),
+    );
+    const result = JSON.parse(
+      execFileSync(
+        process.execPath,
+        [SCRIPT, "--meta", metaPath, "--target", "#bgm", ...flags, "--json"],
+        { encoding: "utf8" },
+      ),
+    );
+    assert.deepEqual(result.spans, expected);
+    assert.equal(result.keyframes[0].time, expected[0].start);
+    assert.equal(result.lane.lanes[0].points[1].t, expected[0].start);
+  });
+}
+
+function word(id, text, start, end) {
+  return { id, text, start, end };
+}