hyperframes 0.8.169 → 0.8.170

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

@@ -4,9 +4,18 @@ import { mkdtempSync, mkdirSync, writeFileSync, existsSync, readFileSync, rmSync
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { appendRecord } from "../../../scripts/lib/manifest.mjs";
-import { resolveSfx } from "./sfx.mjs";
+import { BUNDLED_SFX_DIR, findSoundEffect, resolveSfx } from "./sfx.mjs";
 
-// Offline (no HeyGen) SFX resolution: the bundled library may ship manifest.json
+// No real network: each test serves Openverse's answers; by default it is unreachable.
+const offline = async () => {
+  throw new TypeError("fetch failed");
+};
+let serve = offline;
+const UNREACHABLE =
+  "Openverse unreachable (fetch failed): the remaining SFX cues use the bundled library";
+globalThis.fetch = (url, init) => serve(String(url), init);
+
+// Offline SFX resolution: the bundled library may ship manifest.json
 // without the actual mp3s. The old code copied only when the source existed but
 // pushed the sfx entry unconditionally — producing a dangling reference that
 // silently dropped downstream ("not on disk"). These tests lock in the loud
@@ -37,7 +46,6 @@ test("offline: copies and references a present bundled file", async () => {
     writeFileSync(join(libDir, "whoosh.mp3"), "ID3-fake-bytes");
     const { sfx, anomalies } = await resolveSfx({
       cues: [{ id: "s1", name: "whoosh" }],
-      heygenOK: false,
       hyperframesDir: projDir,
       sfxLibDir: libDir,
     });
@@ -45,7 +53,7 @@ test("offline: copies and references a present bundled file", async () => {
     assert.equal(sfx[0].file, "assets/sfx/whoosh.mp3");
     assert.equal(sfx[0].source, "local");
     assert.ok(existsSync(join(projDir, "assets/sfx/whoosh.mp3")), "mp3 copied into project");
-    assert.equal(anomalies.length, 0);
+    assert.deepEqual(anomalies, [UNREACHABLE]);
   });
 });
 
@@ -58,13 +66,12 @@ test("offline: a matched-but-missing bundled file yields an anomaly and NO dangl
     );
     const { sfx, anomalies } = await resolveSfx({
       cues: [{ id: "s1", name: "whoosh" }],
-      heygenOK: false,
       hyperframesDir: projDir,
       sfxLibDir: libDir,
     });
     assert.equal(sfx.length, 0, "no dangling entry for a file that was never copied");
-    assert.equal(anomalies.length, 1);
-    assert.match(anomalies[0], /missing from the offline library/);
+    assert.equal(anomalies.length, 2);
+    assert.match(anomalies[1], /missing from the offline library/);
     assert.ok(!existsSync(join(projDir, "assets/sfx/whoosh.mp3")), "nothing copied");
   });
 });
@@ -78,10 +85,9 @@ const whooshLibrary = (libDir, withFile) => {
 };
 const record = (projDir, source) =>
   appendRecord(projDir, { id: "sfx_001", type: "sfx", path: "assets/sfx/whoosh.mp3", source });
-const offline = (libDir, projDir) =>
+const bundledOnly = (libDir, projDir) =>
   resolveSfx({
     cues: [{ id: "s1", name: "whoosh" }],
-    heygenOK: false,
     hyperframesDir: projDir,
     sfxLibDir: libDir,
   });
@@ -93,13 +99,13 @@ test("offline: the engine's earlier copy stands in for a library file this insta
     writeFileSync(join(projDir, "assets/sfx/whoosh.mp3"), "engine copy");
     record(projDir, "bundled");
 
-    const { sfx, anomalies } = await offline(libDir, projDir);
+    const { sfx, anomalies } = await bundledOnly(libDir, projDir);
 
     assert.deepEqual(
       sfx.map(({ file }) => file),
       ["assets/sfx/whoosh.mp3"],
     );
-    assert.deepEqual(anomalies, []);
+    assert.deepEqual(anomalies, [UNREACHABLE]);
   });
 });
 
@@ -110,7 +116,7 @@ test("offline: a person's file with the library's bytes stays theirs once record
     writeFileSync(join(projDir, "assets/sfx/whoosh.mp3"), "ID3-library-bytes");
     record(projDir, "existing");
 
-    const { sfx } = await offline(libDir, projDir);
+    const { sfx } = await bundledOnly(libDir, projDir);
 
     assert.deepEqual(
       sfx.map(({ file }) => file),
@@ -119,3 +125,207 @@ test("offline: a person's file with the library's bytes stays theirs once record
     assert.equal(readFileSync(join(projDir, "assets/sfx/whoosh.mp3"), "utf8"), "ID3-library-bytes");
   });
 });
+
+const libraryWith = (libDir, names) => {
+  const manifest = {};
+  for (const name of names) {
+    manifest[name] = { file: `${name}.mp3`, duration: 0.5 };
+    writeFileSync(join(libDir, `${name}.mp3`), `library ${name}`);
+  }
+  writeFileSync(join(libDir, "manifest.json"), JSON.stringify(manifest));
+};
+const sound = (overrides = {}) => ({
+  id: "ov-1",
+  title: "Swoosh",
+  creator: "Ana",
+  license: "by",
+  foreign_landing_url: "https://freesound.org/s/1",
+  url: "https://cdn.freesound.test/swoosh.mp3",
+  filetype: "mp3",
+  duration: 820,
+  attribution: '"Swoosh" by Ana is licensed under CC BY 4.0.',
+  ...overrides,
+});
+// Openverse stand-in: `answer(query)` gives a search response; any other URL is the sound file.
+function openverse(answer) {
+  const searches = [];
+  serve = async (url) => {
+    const query = new URL(url).searchParams.get("q");
+    if (!url.startsWith("https://api.openverse.org/")) return new Response(`bytes of ${url}`);
+    searches.push(query);
+    return answer(query);
+  };
+  return searches;
+}
+const run = (libDir, projDir, names) =>
+  resolveSfx({
+    cues: names.map((name, index) => ({ id: String(index + 1), name })),
+    hyperframesDir: projDir,
+    sfxLibDir: libDir,
+  });
+
+test("openverse: each cue gets the best licensed sound, with its licence and credit", async () => {
+  await withDirs(async ({ libDir, projDir }) => {
+    libraryWith(libDir, ["whoosh"]);
+    openverse(() => Response.json({ results: [sound()] }));
+    try {
+      const { sfx, anomalies } = await run(libDir, projDir, ["whoosh"]);
+      assert.deepEqual(sfx, [
+        {
+          id: "1",
+          name: "whoosh",
+          file: "assets/sfx/whoosh.mp3",
+          source: "openverse",
+          duration_s: 0.82,
+          license: "by",
+          credit: '"Swoosh" by Ana is licensed under CC BY 4.0.',
+          offset_s: 0,
+          volume: 0.35,
+        },
+      ]);
+      assert.deepEqual(anomalies, []);
+      assert.equal(
+        readFileSync(join(projDir, "assets/sfx/whoosh.mp3"), "utf8"),
+        "bytes of https://cdn.freesound.test/swoosh.mp3",
+      );
+      assert.match(
+        readFileSync(join(projDir, "assets/sfx/CREDITS.md"), "utf8"),
+        /- `assets\/sfx\/whoosh\.mp3`: "Swoosh" by Ana is licensed under CC BY 4\.0\. Source: https:\/\/freesound\.org\/s\/1/,
+      );
+    } finally {
+      serve = offline;
+    }
+  });
+});
+
+test("openverse: a rate limit sends this and every later cue to the bundled library, asking once", async () => {
+  await withDirs(async ({ libDir, projDir }) => {
+    libraryWith(libDir, ["whoosh", "pop"]);
+    const searches = openverse(() => new Response("slow down", { status: 429 }));
+    try {
+      const { sfx, anomalies } = await run(libDir, projDir, ["whoosh", "pop"]);
+      assert.deepEqual(searches, ["whoosh"]);
+      assert.deepEqual(
+        sfx.map(({ file, source }) => [file, source]),
+        [
+          ["assets/sfx/whoosh.mp3", "local"],
+          ["assets/sfx/pop.mp3", "local"],
+        ],
+      );
+      assert.equal(readFileSync(join(projDir, "assets/sfx/pop.mp3"), "utf8"), "library pop");
+      assert.deepEqual(anomalies, [
+        "Openverse rate limit reached (HTTP 429): the remaining SFX cues use the bundled library",
+      ]);
+    } finally {
+      serve = offline;
+    }
+  });
+});
+
+test("openverse: a cue with no licensed match falls back to the bundled library alone", async () => {
+  await withDirs(async ({ libDir, projDir }) => {
+    libraryWith(libDir, ["pop"]);
+    const searches = openverse((query) =>
+      Response.json({ results: query === "pop" ? [sound({ license: "by-nc" })] : [sound()] }),
+    );
+    try {
+      const { sfx } = await run(libDir, projDir, ["pop", "swoosh"]);
+      assert.deepEqual(searches, ["pop", "swoosh"]);
+      assert.deepEqual(
+        sfx.map(({ file, source }) => [file, source]),
+        [
+          ["assets/sfx/pop.mp3", "local"],
+          ["assets/sfx/swoosh.mp3", "openverse"],
+        ],
+      );
+    } finally {
+      serve = offline;
+    }
+  });
+});
+
+test("openverse: a failed download falls back to the bundled file with an anomaly", async () => {
+  await withDirs(async ({ libDir, projDir }) => {
+    libraryWith(libDir, ["whoosh"]);
+    serve = async (url) =>
+      url.startsWith("https://api.openverse.org/")
+        ? Response.json({ results: [sound()] })
+        : new Response("gone", { status: 404 });
+    try {
+      const { sfx, anomalies } = await run(libDir, projDir, ["whoosh"]);
+      assert.deepEqual(
+        sfx.map(({ file, source }) => [file, source]),
+        [["assets/sfx/whoosh.mp3", "local"]],
+      );
+      assert.match(anomalies[0], /Openverse download failed — download HTTP 404/);
+    } finally {
+      serve = offline;
+    }
+  });
+});
+
+test("openverse: one effect named in two lines is searched and downloaded once", async () => {
+  await withDirs(async ({ libDir, projDir }) => {
+    libraryWith(libDir, []);
+    const searches = openverse(() => Response.json({ results: [sound({ license: "cc0" })] }));
+    try {
+      const { sfx } = await run(libDir, projDir, ["whoosh", "whoosh"]);
+      assert.deepEqual(searches, ["whoosh"]);
+      assert.deepEqual(
+        sfx.map(({ id, file }) => [id, file]),
+        [
+          ["1", "assets/sfx/whoosh.mp3"],
+          ["2", "assets/sfx/whoosh.mp3"],
+        ],
+      );
+      assert.equal(
+        existsSync(join(projDir, "assets/sfx/CREDITS.md")),
+        false,
+        "CC0 needs no credit",
+      );
+    } finally {
+      serve = offline;
+    }
+  });
+});
+
+test("findSoundEffect: a host gets the saved file, licence, credit and duration for one query", async () => {
+  await withDirs(async ({ projDir }) => {
+    const searches = openverse(() => Response.json({ results: [sound()] }));
+    try {
+      assert.deepEqual(await findSoundEffect("whoosh", { hyperframesDir: projDir }), {
+        sound: {
+          file: "assets/sfx/whoosh.mp3",
+          source: "openverse",
+          duration_s: 0.82,
+          license: "by",
+          credit: '"Swoosh" by Ana is licensed under CC BY 4.0.',
+        },
+        anomalies: [],
+      });
+      assert.deepEqual(searches, ["whoosh"]);
+    } finally {
+      serve = offline;
+    }
+  });
+});
+
+test("findSoundEffect: offline, the skill's own bundled library answers", async () => {
+  await withDirs(async ({ projDir }) => {
+    const { sound, anomalies } = await findSoundEffect("whoosh", { hyperframesDir: projDir });
+    assert.deepEqual(sound, {
+      file: "assets/sfx/whoosh.mp3",
+      source: "local",
+      duration_s: sound.duration_s,
+    });
+    assert.deepEqual(
+      readFileSync(join(projDir, sound.file)),
+      readFileSync(join(BUNDLED_SFX_DIR, "whoosh.mp3")),
+    );
+    assert.deepEqual(anomalies, [UNREACHABLE]);
+    assert.equal(
+      (await findSoundEffect("no such sound at all", { hyperframesDir: projDir })).sound,
+      null,
+    );
+  });
+});

package/dist/skills/media-use/references/audio.md

@@ -12,7 +12,7 @@ node <SKILL_DIR>/audio/scripts/audio.mjs --request ./audio_request.json --out ./
 - **Request** `{ provider?, voice?, lang?, speed?, tts_model?, style?, lines: [{ id, text, style?, sfx?: [names] }], bgm: { mode?, query?, prompt? } }`: `id` joins each line back to your model; `bgm.mode` = `retrieve | generate | none` (omit for auto). `--only tts,bgm,sfx` runs a subset and merges into an existing `--out`.
 - **Gemini narration** is opt-in with `provider: "gemini"` and an API key or service-account credentials. `tts_model` defaults to `gemini-3.8-flash-tts`; 3.8 Flash-Lite, 3.1 Flash Preview, and 2.5 Pro/Flash Preview TTS are also supported. `style` directs delivery; a line's style overrides the request's style. CLI overrides: `--tts-model`, `--style`. See `audio/references/tts.md` for a complete request. The existing automatic provider order is unchanged.
 - **Output** `audio_meta.json` (id-keyed): `voices[].{path,duration_s,words[]}` (word timestamps for captions), `sfx[]`, `bgm`, `total_duration_s`.
-- **HeyGen free-usage path**: HeyGen CLI auth unlocks TTS plus music/SFX retrieval. Local/provider-specific generators are explicit alternatives where installed; run `npx hyperframes media-use resolve --doctor` before assuming retrieval or TTS will work.
+- **HeyGen free-usage path**: HeyGen CLI auth unlocks TTS plus music retrieval; SFX come from Openverse with no account (`audio/references/sfx.md`). Local/provider-specific generators are explicit alternatives where installed; run `npx hyperframes media-use resolve --doctor` before assuming retrieval or TTS will work.
 - If BGM took the generate path (`bgm_pending: true`), run `audio/scripts/wait-bgm.mjs` before final render.
 
 Single-shot helpers: `audio/scripts/heygen-tts.mjs` (one voice file). Transcription / background removal / captions use the `hyperframes` CLI (`transcribe`, `remove-background`), see the per-topic guides in `audio/references/` (`tts.md`, `bgm.md`, `sfx.md`, `transcribe.md`, `remove-background.md`, `captions/`).

package/dist/skills/media-use/references/resolve.md

@@ -11,7 +11,7 @@ Returns one line: `resolved <id> → <path> (<type>, <metadata>)`
 | Type    | What it finds                    | Provider / cascade                                           |
 | ------- | -------------------------------- | ------------------------------------------------------------ |
 | `bgm`   | Background music                 | HeyGen audio catalog (10k+ tracks)                           |
-| `sfx`   | Sound effects                    | Bundled 19-file library + HeyGen catalog                     |
+| `sfx`   | Sound effects                    | Openverse (CC0 / CC BY), then the bundled 21-file library    |
 | `image` | Photos, backgrounds              | HeyGen asset search (75k+ vectors)                           |
 | `icon`  | Icons, symbols                   | HeyGen asset search (type=icon)                              |
 | `logo`  | Official brand marks             | theSVG → GitHub org avatar → domain favicon                  |

package/dist/skills/media-use/references/setup-providers.md

@@ -9,7 +9,7 @@ heygen update             # free usage needs the OAuth-capable CLI (v0.3.0+)
 heygen auth login --oauth # OAuth = free subscription credits; --api-key bills API credits
 ```
 
-This unlocks the FREE path for bgm/sfx/image/icon catalog search, TTS (voice), and avatar videos. Sign in with `--oauth` — the free allowance rides on the OAuth session (an API key bills API credits instead). **media-use requires heygen >= v0.3.0 uniformly** (the OAuth free-usage path needs it), so `--doctor` nudges older CLIs to update even for API-key-only use. Before resolving anything, verify setup with:
+This unlocks the FREE path for bgm/image/icon catalog search, TTS (voice), and avatar videos. Sign in with `--oauth` — the free allowance rides on the OAuth session (an API key bills API credits instead). **media-use requires heygen >= v0.3.0 uniformly** (the OAuth free-usage path needs it), so `--doctor` nudges older CLIs to update even for API-key-only use. Before resolving anything, verify setup with:
 
 ```bash
 npx hyperframes media-use resolve --doctor
@@ -41,7 +41,8 @@ in `references/operations.md`).
 
 | Type      | Provider / path                                                                                                                                                               |
 | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| bgm/sfx   | heygen catalog free-usage path; a host app's own music and sound tools come first                                                                                             |
+| bgm       | heygen catalog free-usage path; a host app's own music tools come first                                                                                                       |
+| sfx       | Openverse (CC0 / CC BY, no account), bundled library offline; a host app's own sound tools come first                                                                         |
 | image     | heygen search free-usage path; optional local mflux; codex `image_gen` upsell                                                                                                 |
 | voice     | heygen tts free-usage path; optional local **Kokoro** (free, on-device)                                                                                                       |
 | icon      | heygen asset search free-usage path                                                                                                                                           |
@@ -67,21 +68,21 @@ HeyGen-only types, that means no fresh resolve.
 ## CLI tools used (what to run, and how to enable each)
 
 `resolve` auto-cascades; each provider shells one CLI. HeyGen is the
-free-usage path for bgm/sfx/image/icon catalog search, TTS (voice), and avatar
+free-usage path for bgm/image/icon catalog search, TTS (voice), and avatar
 video, so those capabilities need `heygen` installed and authenticated. Local
 tools are OPT-IN alternatives where they exist; install one to unlock its free,
 private, on-device path instead of or ahead of HeyGen for that type. Only
 `ffmpeg`/`ffprobe` are strictly required for the tool to run at all.
 
-| Tool               | Serves                                                                          | Install                                                                                                                                                                                     |
-| ------------------ | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ffmpeg`/`ffprobe` | adopt probing, smart-grade signalstats, cut, duck bake, loudnorm                | system package (`brew install ffmpeg`)                                                                                                                                                      |
-| `heygen`           | catalog (bgm/sfx/image/icon) + TTS (voice) + avatar video — the free-usage path | install through [verified HeyGen release instructions](https://developers.heygen.com/cli), then `heygen auth login --oauth` (needs >= v0.3.0)                                               |
-| `mflux-generate`   | local image gen (FLUX), best-for-RAM                                            | `uv venv ~/.venvs/mflux && VIRTUAL_ENV=~/.venvs/mflux uv pip install mflux==0.9.6`                                                                                                          |
-| `codex`            | image gen upsell (ChatGPT sub)                                                  | Codex CLI, logged in via ChatGPT (owns its own auth)                                                                                                                                        |
-| `parakeet-mlx`     | local transcription (default ASR, best) on Apple Silicon                        | `uv venv ~/.venvs/parakeet && VIRTUAL_ENV=~/.venvs/parakeet uv pip install parakeet-mlx`                                                                                                    |
-| `ltx-2-mlx`        | local video gen                                                                 | `git clone https://github.com/dgrauet/ltx-2-mlx && cd ltx-2-mlx && uv sync --all-extras`                                                                                                    |
-| `npx hyperframes`  | Kokoro TTS (voice), Parakeet or whisper.cpp (transcribe), remove-background     | via the hyperframes CLI; Parakeet on macOS, Windows and glibc 2.32+ Linux: `npx hyperframes models install parakeet`; whisper.cpp is built on first use (Homebrew on macOS, else git+cmake) |
+| Tool               | Serves                                                                      | Install                                                                                                                                                                                     |
+| ------------------ | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ffmpeg`/`ffprobe` | adopt probing, smart-grade signalstats, cut, duck bake, loudnorm            | system package (`brew install ffmpeg`)                                                                                                                                                      |
+| `heygen`           | catalog (bgm/image/icon) + TTS (voice) + avatar video — the free-usage path | install through [verified HeyGen release instructions](https://developers.heygen.com/cli), then `heygen auth login --oauth` (needs >= v0.3.0)                                               |
+| `mflux-generate`   | local image gen (FLUX), best-for-RAM                                        | `uv venv ~/.venvs/mflux && VIRTUAL_ENV=~/.venvs/mflux uv pip install mflux==0.9.6`                                                                                                          |
+| `codex`            | image gen upsell (ChatGPT sub)                                              | Codex CLI, logged in via ChatGPT (owns its own auth)                                                                                                                                        |
+| `parakeet-mlx`     | local transcription (default ASR, best) on Apple Silicon                    | `uv venv ~/.venvs/parakeet && VIRTUAL_ENV=~/.venvs/parakeet uv pip install parakeet-mlx`                                                                                                    |
+| `ltx-2-mlx`        | local video gen                                                             | `git clone https://github.com/dgrauet/ltx-2-mlx && cd ltx-2-mlx && uv sync --all-extras`                                                                                                    |
+| `npx hyperframes`  | Kokoro TTS (voice), Parakeet or whisper.cpp (transcribe), remove-background | via the hyperframes CLI; Parakeet on macOS, Windows and glibc 2.32+ Linux: `npx hyperframes models install parakeet`; whisper.cpp is built on first use (Homebrew on macOS, else git+cmake) |
 
 The RAM-graded local-model shortlist + exact per-tier install/invoke lives in
 the CLI's bundled media-use engine, not in the standalone skill. Without a tool on PATH, its provider

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

@@ -102,19 +102,16 @@ const pendingFailureTracking = new Set();
 // API, move this state into a per-resolve context before reusing that path.
 let pendingRemediation = null;
 
-const TOOL_WORDS = { bgm: "music", sfx: "sound-effect" };
-
-/** A music or sound-effect 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. */
+/** 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 }) {
-  const tool = TOOL_WORDS[type];
-  if (!tool) return null;
+  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 ${tool} tool if it has one, or ${outdated ? "update" : "install"} the CLI.`,
+    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.`,
   };
 }
 

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

@@ -301,13 +301,13 @@ test("flushHeygenFailureTracking resolves immediately when nothing is pending",
   await flushHeygenFailureTracking();
 });
 
-test("only a music or sound-effect miss names the heygen CLI and the host app's own tool", () => {
-  for (const type of ["image", "icon", "voice", "video"])
+test("only a music miss names the heygen CLI and the host app's own tool", () => {
+  for (const type of ["sfx", "image", "icon", "voice", "video"])
     assert.equal(heygenMiss(type, { code: "not_found" }), null, type);
   assert.equal(heygenMiss("bgm", { code: "not_found" }).code, "heygen_cli_missing");
-  const sfx = heygenMiss("sfx", { code: "outdated" });
-  assert.equal(sfx.code, "heygen_cli_outdated");
-  assert.match(sfx.error, /host app's own sound-effect tool/);
+  const bgm = heygenMiss("bgm", { code: "outdated" });
+  assert.equal(bgm.code, "heygen_cli_outdated");
+  assert.match(bgm.error, /host app's own music tool/);
 });
 
 test("a CLI that rejects --headers without printing a version is outdated", () => {

package/dist/skills/media-use/scripts/lib/manifest.d.mts

@@ -11,6 +11,7 @@ export function allocateId(
   type: string,
   ext: string,
 ): Omit<Reservation, "fullPath">;
+export function withMediaLock<T>(projectDir: string, fn: () => T): T;
 export function withReservedFileSync<T>(
   projectDir: string,
   type: string,

package/dist/skills/media-use/scripts/lib/manifest.mjs

@@ -107,8 +107,7 @@ export function recordInPlace(
     description: description || basename(path),
     ...(duration != null && { duration: Math.round(duration * 10) / 10 }),
   };
-  mkdirSync(mediaDir(projectDir), { recursive: true });
-  return withLock(mediaDir(projectDir), () => {
+  return withMediaLock(projectDir, () => {
     const latest = latestRecordFor(projectDir, path);
     const same = ["source", "description", "duration"].every(
       (key) => latest?.[key] === fields[key],
@@ -203,6 +202,12 @@ function withLock(dir, fn) {
   }
 }
 
+/** Runs `fn` holding the project's `.media/.lock`, so concurrent resolves take turns on what it guards. */
+export function withMediaLock(projectDir, fn) {
+  mkdirSync(mediaDir(projectDir), { recursive: true });
+  return withLock(mediaDir(projectDir), fn);
+}
+
 // Atomically allocate the next free id for `type` AND reserve it on disk, so a
 // slow download/copy between allocation and appendRecord can't let a concurrent
 // caller grab the same id (the MU-23 clobber). Under the lock we take the max id
@@ -210,10 +215,8 @@ function withLock(dir, fn) {
 // O_EXCL-create an empty marker under core's atomic temp name, which Studio's
 // project history skips. Returns { id, localPath, markerPath }.
 export function allocateId(projectDir, type, ext) {
-  mkdirSync(mediaDir(projectDir), { recursive: true });
-  const typeDir = typeDirPath(projectDir, type);
-  mkdirSync(typeDir, { recursive: true });
-  return withLock(mediaDir(projectDir), () => {
+  mkdirSync(typeDirPath(projectDir, type), { recursive: true });
+  return withMediaLock(projectDir, () => {
     const id = nextFreeId(projectDir, type);
     const localPath = `.media/${typeSubdir(type)}/${id}${ext}`;
     // Same shape as core atomicTempPath: an empty file at the final name would be committed.

package/dist/skills/media-use/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`);
+}