dsh-hyperframes 0.9.1 → 0.9.3

package/skills/media-use/audio/scripts/lib/media-record.test.mjs

@@ -0,0 +1,224 @@
+import { strict as assert } from "node:assert";
+import { test } from "node:test";
+import { mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { findByPrompt, readManifest } from "../../../scripts/lib/manifest.mjs";
+import { agentWritePath, recordInManifest, voicePaths, writtenAssets } from "./media-record.mjs";
+
+const noBgm = { bgm: null, bgmFields: { bgm_pending: false } };
+
+function project(t) {
+  const dir = mkdtempSync(join(tmpdir(), "mu-record-"));
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+  return dir;
+}
+
+test("a voice run leaves a manifest entry marked generated", (t) => {
+  const dir = project(t);
+  const assets = writtenAssets({
+    only: new Set(["tts"]),
+    lines: [{ id: "01", text: "Welcome to the launch" }],
+    voices: [{ id: "01", path: "assets/voice/01.wav", duration_s: 2.34 }],
+    ttsProvider: "kokoro",
+    sfx: [],
+    ...noBgm,
+  });
+
+  assert.deepEqual(recordInManifest(dir, assets), []);
+
+  assert.deepEqual(
+    readManifest(dir).map(({ path, type, source, description, duration, provenance }) => ({
+      path,
+      type,
+      source,
+      description,
+      duration,
+      provenance,
+    })),
+    [
+      {
+        path: "assets/voice/01.wav",
+        type: "voice",
+        source: "generated",
+        description: "Welcome to the launch",
+        duration: 2.3,
+        provenance: { provider: "kokoro", prompt: "Welcome to the launch" },
+      },
+    ],
+  );
+});
+
+const voiceLine = (intent, duration) => [
+  { path: "assets/voice/01.wav", type: "voice", source: "generated", intent, duration },
+];
+
+test("a rerun that writes the same take keeps one record, and a new length is a new take", (t) => {
+  const dir = project(t);
+
+  recordInManifest(dir, voiceLine("Hello world", 1.25));
+  recordInManifest(dir, voiceLine("Hello world", 1.25));
+  assert.equal(readManifest(dir).length, 1);
+
+  recordInManifest(dir, voiceLine("Hello world", 2));
+  assert.deepEqual(
+    readManifest(dir).map(({ duration }) => duration),
+    [1.3, 2],
+  );
+});
+
+test("a rerun with new text records the new take, and the old text no longer finds the file", (t) => {
+  const dir = project(t);
+
+  recordInManifest(dir, voiceLine("Hello world", 1.25));
+  recordInManifest(dir, voiceLine("Welcome back to the show", 3.5));
+
+  assert.deepEqual(
+    readManifest(dir).map(({ description, duration }) => [description, duration]),
+    [
+      ["Hello world", 1.3],
+      ["Welcome back to the show", 3.5],
+    ],
+  );
+  assert.equal(findByPrompt(dir, "Hello world", "voice"), null);
+  const index = readFileSync(join(dir, ".media/index.md"), "utf8");
+  assert.match(index, /Welcome back to the show/);
+  assert.doesNotMatch(index, /Hello world/);
+  assert.equal(findByPrompt(dir, "Welcome back to the show", "voice")?.path, "assets/voice/01.wav");
+});
+
+test("music and sound effects are marked by where they came from", () => {
+  const assets = writtenAssets({
+    only: new Set(["bgm", "sfx"]),
+    lines: [],
+    voices: [{ id: "01", path: "assets/voice/01.wav" }],
+    bgm: { path: "assets/bgm/track.mp3", query: "calm" },
+    bgmFields: { bgm_pending: false, bgm_mode: "retrieve" },
+    sfx: [
+      { file: "assets/sfx/whoosh.mp3", name: "whoosh", source: "local" },
+      { file: "assets/sfx/whoosh.mp3", name: "whoosh", source: "local" },
+      { file: "assets/sfx/glass.mp3", name: "glass", source: "openverse" },
+    ],
+  });
+
+  assert.deepEqual(
+    assets.map(({ path, source, provider }) => [path, source, provider]),
+    [
+      ["assets/bgm/track.mp3", "search", undefined],
+      ["assets/sfx/whoosh.mp3", "bundled", "bundled.sfx"],
+      ["assets/sfx/glass.mp3", "search", "openverse.audio"],
+    ],
+  );
+});
+
+test("a rerun of an Openverse sound effect writes over its own file, not a numbered copy", (t) => {
+  const dir = project(t);
+  mkdirSync(join(dir, "assets/sfx"), { recursive: true });
+  const anomalies = [];
+  for (let run = 0; run < 3; run++) {
+    const file = agentWritePath(dir, "assets/sfx/door-knock.mp3", { anomalies });
+    writeFileSync(join(dir, file), "knock");
+    const sfx = [{ file, name: "door knock", source: "openverse", duration_s: 1 }];
+    recordInManifest(
+      dir,
+      writtenAssets({ only: new Set(["sfx"]), lines: [], voices: [], sfx, ...noBgm }),
+    );
+  }
+
+  assert.deepEqual(readdirSync(join(dir, "assets/sfx")), ["door-knock.mp3"]);
+  assert.deepEqual(anomalies, []);
+  assert.equal(readManifest(dir).length, 1);
+});
+
+test("music made locally is marked generated once it is ready, not while pending", () => {
+  const written = (bgm_pending) =>
+    writtenAssets({
+      only: new Set(["bgm"]),
+      lines: [],
+      voices: [],
+      sfx: [],
+      bgm: { path: "assets/bgm/track.wav" },
+      bgmFields: { bgm_pending, bgm_mode: "detached-single" },
+    }).map(({ source }) => source);
+
+  assert.deepEqual(written(true), []);
+  assert.deepEqual(written(false), ["generated"]);
+});
+
+test("a file that cannot be recorded becomes an anomaly, not a failure", (t) => {
+  const dir = project(t);
+  writeFileSync(join(dir, ".media"), "a file where the media folder should be");
+
+  const anomalies = recordInManifest(dir, [
+    { path: "assets/voice/01.wav", type: "voice", source: "generated" },
+  ]);
+
+  assert.equal(anomalies.length, 1);
+  assert.match(anomalies[0], /^assets\/voice\/01\.wav: not recorded in the media manifest/);
+});
+
+test("the engine writes over only its own files, else the next free name", (t) => {
+  const dir = project(t);
+  mkdirSync(join(dir, "assets/sfx"), { recursive: true });
+  const names = ["mine", "made", "adopted", "twice", "twice-2", "kept", "kept-2"];
+  for (const name of names) writeFileSync(join(dir, `assets/sfx/${name}.mp3`), name);
+  for (const path of ["assets/sfx/made.mp3", "assets/sfx/kept-2.mp3"])
+    recordInManifest(dir, [{ path, type: "sfx", source: "search" }]);
+  recordInManifest(dir, [{ path: "assets/sfx/adopted.mp3", type: "sfx", source: "existing" }]);
+  const anomalies = [];
+  const at = (name, reusable) =>
+    agentWritePath(dir, `assets/sfx/${name}.mp3`, { anomalies, reusable });
+
+  assert.equal(at("new"), "assets/sfx/new.mp3");
+  assert.equal(at("made"), "assets/sfx/made.mp3");
+  assert.equal(
+    at("mine", (path) => path === "assets/sfx/mine.mp3"),
+    "assets/sfx/mine.mp3",
+  );
+  assert.deepEqual(anomalies, []);
+  assert.equal(at("mine"), "assets/sfx/mine-2.mp3");
+  assert.equal(at("adopted"), "assets/sfx/adopted-2.mp3");
+  assert.equal(at("twice"), "assets/sfx/twice-3.mp3");
+  assert.equal(at("kept"), "assets/sfx/kept-2.mp3");
+  assert.equal(anomalies.length, 4);
+  assert.match(
+    anomalies[0],
+    /^assets\/sfx\/mine\.mp3: kept, .* writing assets\/sfx\/mine-2\.mp3 instead/,
+  );
+});
+
+test("two spoken lines never share a file when one's name is taken by the person", (t) => {
+  const dir = project(t);
+  mkdirSync(join(dir, "assets/voice"), { recursive: true });
+  writeFileSync(join(dir, "assets/voice/hook.wav"), "the person's own hook");
+  const anomalies = [];
+
+  const paths = voicePaths(
+    dir,
+    [
+      { id: "hook", text: "First" },
+      { id: "hook-2", text: "Second" },
+      { id: "blank", text: " " },
+    ],
+    anomalies,
+  );
+
+  assert.deepEqual(Object.fromEntries(paths), {
+    hook: "assets/voice/hook-2.wav",
+    "hook-2": "assets/voice/hook-2-2.wav",
+  });
+  assert.equal(anomalies.length, 2);
+});
+
+test("a record never takes the id of a download still in flight", (t) => {
+  const dir = project(t);
+  mkdirSync(join(dir, ".media/audio/bgm"), { recursive: true });
+  writeFileSync(join(dir, ".media/audio/bgm/bgm_001.mp3"), "");
+
+  recordInManifest(dir, [{ path: "assets/bgm/track.wav", type: "bgm", source: "generated" }]);
+
+  assert.deepEqual(
+    readManifest(dir).map(({ id }) => id),
+    ["bgm_002"],
+  );
+});

package/skills/media-use/audio/scripts/lib/openverse.mjs

@@ -0,0 +1,134 @@
+// Sound effects from Openverse (https://api.openverse.org): free, no key.
+// Anonymous use is rate limited (20 requests a minute, 200 a day); callers fall
+// back to the bundled library when it is unavailable.
+
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+const OPENVERSE_AUDIO_URL = "https://api.openverse.org/v1/audio/";
+// The only licences media-use accepts: no NonCommercial, ShareAlike or NoDerivatives.
+export const OPENVERSE_SFX_LICENSES = new Set(["cc0", "by"]);
+const PLAYABLE_FILETYPES = new Set(["mp3", "wav", "ogg", "flac"]);
+const MAX_SFX_MS = 15000;
+const IDEAL_SFX_MS = 4000;
+const BY_PENALTY = 2;
+const SEARCH_TIMEOUT_MS = 10000;
+
+// Openverse text lands in markdown and JSON: one line, no control or markdown-structure characters, bounded.
+const oneLine = (text) =>
+  String(text ?? "")
+    .replace(/[\p{Cc}`[\]<>\\]+/gu, " ")
+    .trim()
+    .slice(0, 300);
+// Openverse's audio providers (api.openverse.org/v1/audio/stats/); a new provider's link is dropped until listed.
+const SOURCE_HOSTS = new Set(["freesound.org", "www.jamendo.com", "commons.wikimedia.org"]);
+function httpsUrl(url, hosts) {
+  try {
+    const parsed = new URL(url);
+    return parsed.protocol === "https:" && (!hosts || hosts.has(parsed.hostname))
+      ? oneLine(parsed.href)
+      : "";
+  } catch {
+    return "";
+  }
+}
+
+/** Openverse could not answer (offline, rate limited, server error): stop asking it this run. */
+export class OpenverseUnavailableError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "OpenverseUnavailableError";
+  }
+}
+
+function usable(result) {
+  return (
+    OPENVERSE_SFX_LICENSES.has(result?.license) &&
+    PLAYABLE_FILETYPES.has(result.filetype) &&
+    typeof result.url === "string" &&
+    result.url.startsWith("https://") &&
+    Number.isFinite(result.duration) &&
+    result.duration > 0 &&
+    result.duration <= MAX_SFX_MS
+  );
+}
+
+// Lower is better: relevance position, then seconds past a typical cue length, then CC0 over CC BY.
+function penalty(result, position) {
+  const longBy = Math.max(0, result.duration - IDEAL_SFX_MS) / 1000;
+  return position + longBy + (result.license === "by" ? BY_PENALTY : 0);
+}
+
+/** Best usable sound in Openverse's relevance-ordered results, or null. */
+export function pickOpenverseSfx(results) {
+  let best = null;
+  results.forEach((result, position) => {
+    if (!usable(result)) return;
+    const score = penalty(result, position);
+    if (!best || score < best.score) best = { result, score };
+  });
+  if (!best) return null;
+  const r = best.result;
+  return {
+    id: r.id,
+    url: r.url,
+    ext: `.${r.filetype}`,
+    title: oneLine(r.title),
+    creator: oneLine(r.creator),
+    license: r.license,
+    licenseUrl: httpsUrl(r.license_url),
+    sourceUrl: httpsUrl(r.foreign_landing_url, SOURCE_HOSTS),
+    credit: oneLine(r.attribution),
+    durationS: Math.round(r.duration) / 1000,
+  };
+}
+
+/** Best licensed sound effect for `query`, null on no match; throws OpenverseUnavailableError. */
+export async function searchOpenverseSfx(query, { fetchImpl = fetch } = {}) {
+  const params = new URLSearchParams({
+    q: query,
+    page_size: "20",
+    license: [...OPENVERSE_SFX_LICENSES].join(","),
+  });
+  let response;
+  try {
+    response = await fetchImpl(`${OPENVERSE_AUDIO_URL}?${params}`, {
+      headers: { Accept: "application/json" },
+      signal: AbortSignal.timeout(SEARCH_TIMEOUT_MS),
+    });
+  } catch (error) {
+    throw new OpenverseUnavailableError(`Openverse unreachable (${error.message})`);
+  }
+  if (response.status === 429)
+    throw new OpenverseUnavailableError("Openverse rate limit reached (HTTP 429)");
+  if (!response.ok) throw new OpenverseUnavailableError(`Openverse HTTP ${response.status}`);
+  let body;
+  try {
+    body = await response.json();
+  } catch {
+    throw new OpenverseUnavailableError("Openverse returned non-JSON");
+  }
+  return pickOpenverseSfx(Array.isArray(body?.results) ? body.results : []);
+}
+
+/** Record a CC BY sound's credit for `file` in the project's credits file (one line per file). */
+export function writeSfxCredit(creditsPath, file, sound) {
+  if (sound.license !== "by") return;
+  // The sound may come from a saved record, not this run's pick: clean it again here.
+  const sourceUrl = httpsUrl(sound.sourceUrl, SOURCE_HOSTS);
+  const source = sourceUrl ? ` Source: ${sourceUrl}` : "";
+  const line = `- \`${file}\`: ${oneLine(sound.credit)}${source}`;
+  let prior = "";
+  try {
+    prior = readFileSync(creditsPath, "utf8");
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+  const kept = prior
+    .split("\n")
+    .filter((l) => l.startsWith("- ") && !l.startsWith(`- \`${file}\`:`));
+  const header =
+    "# Sound effect credits\n\nThese sounds are licensed CC BY: credit them wherever the video is published.\n\n";
+  mkdirSync(dirname(creditsPath), { recursive: true });
+  writeFileSync(creditsPath, `${header}${[...kept, line].join("\n")}\n`);
+}

package/skills/media-use/audio/scripts/lib/python.mjs

@@ -11,12 +11,20 @@
 // Resolve once, per process: probe the platform's candidates in order and take
 // the first that actually runs. `py` is the launcher, so it needs a `-3` arg to
 // select Python 3 — hence candidates are argv PREFIXES, not bare names.
+//
+// `HYPERFRAMES_PYTHON` (the documented PEP 668 venv setup) wins over the PATH probe, matching
+// the CLI's `findPython()`; ignoring it made BGM silently disable itself (#4614).
 
 import { spawnSync } from "node:child_process";
 
-function defaultProbe(cmd, args) {
+// Accept only an interpreter whose `--version` reports Python 3, as the CLI's
+// `validatePythonOverride()` does. Exit status alone would take a Python 2
+// `python` (or any executable that exits 0) that `doctor` rejects. Python 2
+// prints its version to stderr, so read both streams.
+export function defaultProbe(cmd, args) {
   try {
-    return spawnSync(cmd, args, { stdio: "ignore" }).status === 0;
+    const result = spawnSync(cmd, args, { encoding: "utf-8", timeout: 5000 });
+    return result.status === 0 && /Python 3/.test(`${result.stdout}${result.stderr}`);
   } catch {
     return false;
   }
@@ -26,12 +34,18 @@ function defaultProbe(cmd, args) {
  * Pick the argv prefix that launches Python 3 on this platform.
  * Returns e.g. `["python3"]`, `["python"]`, or `["py", "-3"]`.
  *
- * Pure except for `probe` (which runs `<cmd> … --version`); both `platform`
- * and `probe` are injectable so every branch is unit-testable without spawning.
+ * Pure except for `probe` (which runs `<cmd> … --version`); `platform`, `probe`
+ * and `env` are injectable so every branch is unit-testable without spawning.
  * If nothing probes OK, falls back to the canonical name for the platform so
  * the eventual spawn fails loudly exactly as it did before — never worse.
  */
-export function resolvePythonCommand(platform = process.platform, probe = defaultProbe) {
+export function resolvePythonCommand(
+  platform = process.platform,
+  probe = defaultProbe,
+  env = process.env,
+) {
+  const override = env.HYPERFRAMES_PYTHON;
+  if (override && probe(override, ["--version"])) return [override];
   const candidates =
     platform === "win32" ? [["python3"], ["python"], ["py", "-3"]] : [["python3"], ["python"]];
   for (const prefix of candidates) {

package/skills/media-use/audio/scripts/lib/python.test.mjs

@@ -1,6 +1,9 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { resolvePythonCommand, pythonInvocation } from "./python.mjs";
+import { chmodSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { defaultProbe, resolvePythonCommand, pythonInvocation } from "./python.mjs";
 
 // Regression: on Windows a standard python.org install has no `python3.exe`
 // (only `python.exe` + the `py` launcher), so `spawn("python3", …)` ENOENTs and
@@ -55,6 +58,71 @@ test("falls back to the canonical name (loud failure, unchanged) when nothing ru
   );
 });
 
+// Regression (#4614): on PEP 668 systems the documented setup is a venv named
+// by HYPERFRAMES_PYTHON; the audio engine ignored it and probed the bare
+// system python3, so MusicGen BGM was skipped while `doctor` said installed.
+const VENV = "/home/u/.venvs/hf/bin/python";
+
+test("HYPERFRAMES_PYTHON wins over python3 on PATH when it runs", () => {
+  const env = { HYPERFRAMES_PYTHON: VENV };
+  assert.deepEqual(resolvePythonCommand("darwin", probeFor(VENV, "python3"), env), [VENV]);
+  assert.deepEqual(resolvePythonCommand("win32", probeFor(VENV, "python", "py"), env), [VENV]);
+});
+
+test("a HYPERFRAMES_PYTHON that doesn't run falls through to the PATH probe", () => {
+  const env = { HYPERFRAMES_PYTHON: "/nope/python" };
+  assert.deepEqual(resolvePythonCommand("linux", probeFor("python3"), env), ["python3"]);
+});
+
+test("an empty HYPERFRAMES_PYTHON is ignored without being probed", () => {
+  const seen = [];
+  const probe = (cmd) => {
+    seen.push(cmd);
+    return cmd === "python3";
+  };
+  assert.deepEqual(resolvePythonCommand("linux", probe, { HYPERFRAMES_PYTHON: "" }), ["python3"]);
+  assert.deepEqual(seen, ["python3"]);
+});
+
+// defaultProbe must match the CLI's validatePythonOverride(): exiting 0 is not
+// enough, `--version` has to report Python 3. Stubs are shell scripts, so
+// these run on POSIX only.
+function withStub(script, fn) {
+  const dir = mkdtempSync(join(tmpdir(), "hf-python-probe-"));
+  try {
+    const stub = join(dir, "python");
+    writeFileSync(stub, `#!/bin/sh\n${script}\n`);
+    chmodSync(stub, 0o755);
+    fn(stub);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+const posixOnly = { skip: process.platform === "win32" && "stub scripts need a POSIX shell" };
+
+test("defaultProbe accepts an interpreter reporting Python 3", posixOnly, () => {
+  withStub('echo "Python 3.12.4"', (stub) => assert.equal(defaultProbe(stub, ["--version"]), true));
+});
+
+test("defaultProbe rejects Python 2, which prints its version to stderr", posixOnly, () => {
+  withStub('echo "Python 2.7.18" >&2', (stub) =>
+    assert.equal(defaultProbe(stub, ["--version"]), false),
+  );
+});
+
+test(
+  "defaultProbe rejects an executable that exits 0 without a Python 3 version",
+  posixOnly,
+  () => {
+    withStub("exit 0", (stub) => assert.equal(defaultProbe(stub, ["--version"]), false));
+  },
+);
+
+test("defaultProbe rejects a command that doesn't exist", () => {
+  assert.equal(defaultProbe("/nonexistent/hf-python", ["--version"]), false);
+});
+
 test("pythonInvocation prepends the resolved prefix ahead of caller args", () => {
   assert.deepEqual(pythonInvocation(["-c", "import x"], ["python"]), {
     cmd: "python",