hyperframes 0.8.168 → 0.8.170

package/dist/skills/media-use/audio/scripts/audio.mjs

@@ -6,12 +6,12 @@
 //
 //   node <MEDIA_DIR>/scripts/audio.mjs --request ./audio_request.json --hyperframes . --out ./audio_meta.json
 //
-// The three capabilities degrade on ONE switch — whether HeyGen is configured
-// (credential present, NOT the CLI). This mirrors the table in ../SKILL.md:
+// TTS and BGM degrade on ONE switch — whether HeyGen is configured (credential
+// present, NOT the CLI). SFX needs no credential. This mirrors ../SKILL.md:
 //
 //   TTS : HeyGen REST → ElevenLabs → Kokoro (CLI)
 //   BGM : HeyGen retrieve  → (no credential) Lyria/MusicGen generate
-//   SFX : HeyGen retrieve  → (no credential) bundled 19-file library
+//   SFX : Openverse (CC0 / CC BY) → (offline, rate limited, no match) bundled library
 //
 // ── audio_request.json (input) ────────────────────────────────────────────────
 //   {
@@ -31,7 +31,7 @@
 //     bgm: { path, volume, mode, query?, duration_s? } | null,
 //     bgm_pending, bgm_provider, bgm_pid, bgm_log, bgm_mode, bgm_target_duration_s, …,
 //     voices: [ { id, path, duration_s, words: [{id,text,start,end}] } ],
-//     sfx:    [ { id, name, file, source, offset_s, duration_s, volume } ],
+//     sfx:    [ { id, name, file, source, offset_s, duration_s, volume, license?, credit? } ],
 //     total_duration_s }
 //
 // --only tts,bgm,sfx  runs a subset and MERGES into an existing --out (so a
@@ -52,7 +52,7 @@ import {
   withWordIds,
 } from "./lib/tts.mjs";
 import { generateBgmDetached, inferBgmPrompt, retrieveBgm } from "./lib/bgm.mjs";
-import { resolveSfx } from "./lib/sfx.mjs";
+import { BUNDLED_SFX_DIR, resolveSfx } from "./lib/sfx.mjs";
 import { mapWithConcurrency } from "./lib/concurrency.mjs";
 import { openAudioMeta } from "./lib/audio-meta.mjs";
 import { recordInManifest, voicePaths, writtenAssets } from "./lib/media-record.mjs";
@@ -83,7 +83,7 @@ const ttsConcurrency = Math.max(1, Number(process.env.HYPERFRAMES_TTS_CONCURRENC
 const hyperframesDir = resolve(flag("hyperframes", "."));
 const requestPath = resolve(flag("request", join(hyperframesDir, "audio_request.json")));
 const outPath = resolve(flag("out", join(hyperframesDir, "audio_meta.json")));
-const sfxLibDir = resolve(flag("sfx-lib", join(HERE, "..", "assets", "sfx")));
+const sfxLibDir = resolve(flag("sfx-lib", BUNDLED_SFX_DIR));
 const lyriaRecipe = resolve(flag("lyria-recipe", join(HERE, "lyria-recipe.py")));
 const onlyArg = flag("only", "tts,bgm,sfx");
 const only = new Set(
@@ -275,12 +275,12 @@ if (only.has("sfx")) {
       .map((name) => ({ id: String(l.id), name: String(name).trim() }))
       .filter((c) => c.name),
   );
-  const headers = heygenOK && cues.length ? heygenAuthHeaders() : null;
-  const res = await resolveSfx({ cues, heygenOK, headers, hyperframesDir, sfxLibDir });
+  const res = await resolveSfx({ cues, hyperframesDir, sfxLibDir });
   sfx = res.sfx;
   anomalies.push(...res.anomalies);
+  const openverse = sfx.filter((s) => s.source === "openverse").length;
   console.error(
-    `· sfx: ${sfx.length} cue(s) resolved (${heygenOK ? "heygen retrieval" : "bundled library"})`,
+    `· sfx: ${sfx.length} cue(s) resolved (${openverse} Openverse, ${sfx.length - openverse} bundled library)`,
   );
 }
 

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

@@ -10,7 +10,11 @@ import { resolveSfx } from "./lib/sfx.mjs";
 
 // Proves the relocated engine (skills/media-use/audio/) still resolves its
 // bundled SFX library from the moved location — the path most likely to break
-// on a subtree move. Offline (heygenOK:false), no network.
+// on a subtree move. Openverse is unreachable unless a test serves it.
+const offline = async () => {
+  throw new TypeError("fetch failed");
+};
+globalThis.fetch = offline;
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const sfxLibDir = join(HERE, "..", "assets", "sfx"); // same offset the engine uses
@@ -21,7 +25,6 @@ test("bundled SFX library resolves from the relocated path", async () => {
   try {
     const { sfx, anomalies } = await resolveSfx({
       cues: [{ id: "1", name: "whoosh" }],
-      heygenOK: false,
       hyperframesDir: dir,
       sfxLibDir,
     });
@@ -39,7 +42,6 @@ test("an unknown cue is reported, not fatal", async () => {
   try {
     const { sfx, anomalies } = await resolveSfx({
       cues: [{ id: "1", name: "definitely-not-a-real-sfx" }],
-      heygenOK: false,
       hyperframesDir: dir,
       sfxLibDir,
     });
@@ -59,7 +61,6 @@ test("a person's own file under a bundled name survives, and the cue gets the ne
     const resolve = () =>
       resolveSfx({
         cues: [{ id: "1", name: "whoosh" }],
-        heygenOK: false,
         hyperframesDir: dir,
         sfxLibDir,
       });
@@ -89,18 +90,24 @@ test("two effects never share a file when one's name is taken by the person, run
   try {
     mkdirSync(join(dir, "assets", "sfx"), { recursive: true });
     writeFileSync(join(dir, "assets", "sfx", "glitch.mp3"), "the person's own glitch");
-    const realFetch = globalThis.fetch;
     globalThis.fetch = async (url) => {
-      const query = new URL(url).searchParams.get("query");
+      const query = new URL(url).searchParams.get("q");
       if (query)
-        return Response.json({ data: [{ audio_url: `https://sound.test/${query}`, score: 0.6 }] });
+        return Response.json({
+          results: [
+            {
+              license: "cc0",
+              filetype: "mp3",
+              duration: 500,
+              url: `https://sound.test/${encodeURIComponent(query)}`,
+            },
+          ],
+        });
       return new Response(`bytes of ${new URL(url).pathname}`);
     };
     const run = async (names) => {
       const { sfx } = await resolveSfx({
         cues: names.map((name, index) => ({ id: String(index), name })),
-        heygenOK: true,
-        headers: {},
         hyperframesDir: dir,
         sfxLibDir,
       });
@@ -119,7 +126,7 @@ test("two effects never share a file when one's name is taken by the person, run
         "assets/sfx/glitch-2.mp3",
       ]);
     } finally {
-      globalThis.fetch = realFetch;
+      globalThis.fetch = offline;
     }
   } finally {
     rmSync(dir, { recursive: true, force: true });

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

@@ -43,7 +43,12 @@ export function voicePaths(hyperframesDir, lines, anomalies) {
   return paths;
 }
 
-const SFX_SOURCES = { heygen: "search", local: "bundled" };
+// A cue's source as the manifest records it, and who provided it. A source missing here records as the person's
+// file, so every rerun would write a numbered copy beside it.
+const SFX_SOURCES = {
+  openverse: { source: "search", provider: "openverse.audio" },
+  local: { source: "bundled", provider: "bundled.sfx" },
+};
 
 // The files one engine run wrote, each with how it was made, for the project's media manifest.
 export function writtenAssets({ only, lines, voices, ttsProvider, bgm, bgmFields, sfx }) {
@@ -73,8 +78,7 @@ export function writtenAssets({ only, lines, voices, ttsProvider, bgm, bgmFields
   }
   if (only.has("sfx")) {
     for (const cue of new Map(sfx.map((entry) => [entry.file, entry])).values()) {
-      const source = SFX_SOURCES[cue.source];
-      const provider = source === "search" ? "heygen" : "bundled.sfx";
+      const { source, provider } = SFX_SOURCES[cue.source];
       assets.push({
         path: cue.file,
         type: "sfx",

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

@@ -1,6 +1,6 @@
 import { strict as assert } from "node:assert";
 import { test } from "node:test";
-import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+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";
@@ -97,7 +97,7 @@ test("music and sound effects are marked by where they came from", () => {
     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: "heygen" },
+      { file: "assets/sfx/glass.mp3", name: "glass", source: "openverse" },
     ],
   });
 
@@ -106,11 +106,30 @@ test("music and sound effects are marked by where they came from", () => {
     [
       ["assets/bgm/track.mp3", "search", undefined],
       ["assets/sfx/whoosh.mp3", "bundled", "bundled.sfx"],
-      ["assets/sfx/glass.mp3", "search", "heygen"],
+      ["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({

package/dist/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/dist/skills/media-use/audio/scripts/lib/sfx.mjs

@@ -1,23 +1,26 @@
-// sfx.mjs — sound effects for the media audio engine. Provider-gated (NOT a
-// per-cue merge): the decision is made once, by whether HeyGen is configured —
-// mirroring how TTS and BGM degrade.
-//
-//   HeyGen credential present  →  retrieve EVERY cue from HeyGen's audio library
-//        (/v3/audio/sounds, type=sound_effects, min_score=0.4). The bundled
-//        library is NOT consulted.
-//   HeyGen credential absent   →  resolve cues against the bundled 21-file
-//        library (assets/sfx/manifest.json), copying matched files into the
-//        project. Offline, deterministic, free.
+// sfx.mjs — sound effects for the media audio engine. Each cue is searched on
+// Openverse (CC0 / CC BY only, see openverse.mjs). A cue Openverse cannot answer,
+// and every cue after Openverse is unreachable or rate limited, resolves against
+// the bundled 21-file library (assets/sfx/manifest.json) instead.
 //
 // A cue that matches nothing is skipped (recorded as an anomaly); SFX never
 // blocks a render. Every cue sits at volume ~0.35, under voice + BGM.
 
 import { copyFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
-import { join } from "node:path";
-import { downloadTo, searchSounds } from "./heygen.mjs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { downloadTo } from "./heygen.mjs";
+import { OpenverseUnavailableError, searchOpenverseSfx, writeSfxCredit } from "./openverse.mjs";
 import { latestRecordFor } from "../../../scripts/lib/manifest.mjs";
 import { agentWritePath } from "./media-record.mjs";
 
+export const BUNDLED_SFX_DIR = join(
+  dirname(fileURLToPath(import.meta.url)),
+  "..",
+  "..",
+  "assets",
+  "sfx",
+);
 const SFX_VOLUME = 0.35;
 const slug = (s) =>
   s
@@ -27,14 +30,42 @@ const slug = (s) =>
     .slice(0, 40) || "x";
 const r3 = (x) => Number(x.toFixed(3));
 
+// Lookups by manifest key, file basename, and slug of either, so a cue can name
+// "whoosh", "whoosh.mp3", or "ui click" (→ slug match). { error } when unusable.
+function loadBundledLibrary(sfxLibDir) {
+  const manifestPath = join(sfxLibDir, "manifest.json");
+  if (!existsSync(manifestPath)) return { error: `no bundled SFX library at ${sfxLibDir}` };
+  let manifest;
+  try {
+    manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+  } catch (e) {
+    return { error: `bundled SFX manifest parse failed (${e.message})` };
+  }
+  const byKey = new Map();
+  for (const [key, entry] of Object.entries(manifest)) {
+    if (!entry?.file || !isFinite(entry.duration)) continue;
+    const rec = { key, file: entry.file, duration: entry.duration };
+    byKey.set(key, rec);
+    byKey.set(entry.file, rec);
+    byKey.set(slug(key), rec);
+    byKey.set(slug(entry.file.replace(/\.\w+$/, "")), rec);
+  }
+  return { byKey };
+}
+
 // cues: [{ id, name }] (id = the line/frame/scene the cue fires in). Returns
-// { sfx: [{ id, name, file, source, offset_s, duration_s, volume }], anomalies }.
-export async function resolveSfx({ cues, heygenOK, headers, hyperframesDir, sfxLibDir }) {
+// { sfx: [{ id, name, file, source, offset_s, duration_s, volume, license?, credit? }], anomalies }.
+export async function resolveSfx({ cues, hyperframesDir, sfxLibDir = BUNDLED_SFX_DIR }) {
   const sfx = [];
   const anomalies = [];
   const destDir = join(hyperframesDir, "assets", "sfx");
   // Each effect's file this run: one effect named twice gets one file, and two effects never share one.
   const fileFor = new Map();
+  const taken = () => new Set(fileFor.values());
+  // One Openverse sound per effect name this run, so a repeated cue costs no second request.
+  const openverseFor = new Map();
+  let openverseDown = false;
+  let library;
 
   // Dedupe identical (id,name) cues — the same effect named twice in one line
   // downloads/copies once.
@@ -46,112 +77,82 @@ export async function resolveSfx({ cues, heygenOK, headers, hyperframesDir, sfxL
     return true;
   });
 
-  if (heygenOK) {
-    for (const { id, name } of uniq) {
+  async function fromOpenverse({ id, name }) {
+    const key = `openverse:${slug(name)}`;
+    let entry = openverseFor.get(key);
+    if (!entry) {
+      const sound = await searchOpenverseSfx(name);
+      if (!sound) return null;
+      const file = agentWritePath(hyperframesDir, `assets/sfx/${slug(name)}${sound.ext}`, {
+        anomalies,
+        taken: taken(),
+      });
       try {
-        // SFX hits score low (~0.5–0.67), below the API's default 0.7 which
-        // silently drops most named cues — floor to 0.4. (BGM/music score high
-        // and keep the default.)
-        const results = await searchSounds(name, "sound_effects", headers, {
-          limit: 3,
-          minScore: 0.4,
-        });
-        if (!results.length) {
-          anomalies.push(`sfx "${name}" (id ${id}): no HeyGen match — skipped`);
-          continue;
-        }
-        const top = results[0];
-        const file =
-          fileFor.get(slug(name)) ??
-          agentWritePath(hyperframesDir, `assets/sfx/${slug(name)}.mp3`, {
-            anomalies,
-            taken: new Set(fileFor.values()),
-          });
-        await downloadTo(top.audio_url, join(hyperframesDir, file));
-        fileFor.set(slug(name), file);
-        sfx.push({
-          id,
-          name,
-          file,
-          source: "heygen",
-          offset_s: 0,
-          duration_s: typeof top.duration === "number" ? r3(top.duration) : 1.0,
-          volume: SFX_VOLUME,
-        });
+        await downloadTo(sound.url, join(hyperframesDir, file));
       } catch (e) {
-        anomalies.push(`sfx "${name}" (id ${id}): retrieval failed — ${e.message}`);
+        anomalies.push(`sfx "${name}" (id ${id}): Openverse download failed — ${e.message}`);
+        return null;
       }
+      fileFor.set(key, file);
+      writeSfxCredit(join(destDir, "CREDITS.md"), file, sound);
+      entry = {
+        file,
+        source: "openverse",
+        duration_s: r3(sound.durationS),
+        license: sound.license,
+        credit: sound.credit,
+      };
+      openverseFor.set(key, entry);
     }
-    return { sfx, anomalies };
+    return { id, name, ...entry, offset_s: 0, volume: SFX_VOLUME };
   }
 
-  // ── offline: bundled library ──
-  const manifestPath = join(sfxLibDir, "manifest.json");
-  if (!existsSync(manifestPath)) {
-    if (uniq.length)
-      anomalies.push(`no HeyGen credential and no SFX library at ${sfxLibDir} — all cues dropped`);
-    return { sfx, anomalies };
-  }
-  let manifest;
-  try {
-    manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
-  } catch (e) {
-    anomalies.push(`SFX manifest parse failed (${e.message}) — all cues dropped`);
-    return { sfx, anomalies };
-  }
-  // Build lookups: by manifest key, by file basename, and by slug of either, so
-  // a cue can name "whoosh", "whoosh.mp3", or "ui click" (→ slug match).
-  const byKey = new Map();
-  for (const [key, entry] of Object.entries(manifest)) {
-    if (!entry?.file || !isFinite(entry.duration)) continue;
-    const rec = { key, file: entry.file, duration: entry.duration };
-    byKey.set(key, rec);
-    byKey.set(entry.file, rec);
-    byKey.set(slug(key), rec);
-    byKey.set(slug(entry.file.replace(/\.\w+$/, "")), rec);
-  }
-  mkdirSync(destDir, { recursive: true });
-  for (const { id, name } of uniq) {
+  function fromBundled({ id, name }) {
+    library ??= loadBundledLibrary(sfxLibDir);
+    if (library.error) {
+      anomalies.push(`sfx "${name}" (id ${id}): ${library.error} — skipped`);
+      return null;
+    }
+    const { byKey } = library;
     const hit = byKey.get(name) ?? byKey.get(slug(name));
     if (!hit) {
       const known = [...new Set([...byKey.values()].map((v) => v.key))].slice(0, 8).join(", ");
       anomalies.push(
         `sfx "${name}" (id ${id}): not in bundled library — skipped (have: ${known}…)`,
       );
-      continue;
+      return null;
     }
+    mkdirSync(destDir, { recursive: true });
     const src = join(sfxLibDir, hit.file);
-    const library = existsSync(src) ? readFileSync(src) : null;
+    const bytes = existsSync(src) ? readFileSync(src) : null;
     const isLibraryCopy = (rel) =>
-      library &&
+      bytes &&
       existsSync(join(hyperframesDir, rel)) &&
-      readFileSync(join(hyperframesDir, rel)).equals(library);
+      readFileSync(join(hyperframesDir, rel)).equals(bytes);
     const destRel =
       fileFor.get(hit.file) ??
       agentWritePath(hyperframesDir, `assets/sfx/${hit.file}`, {
         anomalies,
-        taken: new Set(fileFor.values()),
+        taken: taken(),
         // An unrecorded copy of the library file is one an engine run made before the manifest had it.
         reusable: (rel) => !latestRecordFor(hyperframesDir, rel) && isLibraryCopy(rel),
       });
     const dest = join(hyperframesDir, destRel);
-    // The bundled library may be incomplete: some installs of the skill ship
-    // manifest.json without the actual mp3s. Pushing an sfx entry that points at
-    // a file we never copied produces a dangling reference that silently drops
-    // downstream ("not on disk"). Surface it as a loud anomaly and skip the cue
-    // instead, so the audio_meta never references a missing file.
-    if (library) {
+    // Some installs of the skill ship manifest.json without the mp3s. An entry
+    // pointing at a file we never copied would silently drop downstream, so
+    // skip the cue with a loud anomaly instead.
+    if (bytes) {
       if (!isLibraryCopy(destRel)) copyFileSync(src, dest);
     } else if (!existsSync(dest)) {
       anomalies.push(
         `sfx "${name}" (id ${id}): bundled file ${hit.file} missing from the offline ` +
           `library (${sfxLibDir}) — skipped. Reinstall the media-use skill to ` +
-          `restore assets/sfx/*.mp3, or configure a HeyGen credential for retrieval.`,
+          `restore assets/sfx/*.mp3.`,
       );
-      continue;
+      return null;
     } // else the engine's earlier copy at dest stands in for the file this install lacks
     fileFor.set(hit.file, destRel);
-    sfx.push({
+    return {
       id,
       name,
       file: destRel,
@@ -159,7 +160,37 @@ export async function resolveSfx({ cues, heygenOK, headers, hyperframesDir, sfxL
       offset_s: 0,
       duration_s: r3(hit.duration),
       volume: SFX_VOLUME,
-    });
+    };
+  }
+
+  for (const cue of uniq) {
+    let entry = null;
+    if (!openverseDown) {
+      try {
+        entry = await fromOpenverse(cue);
+      } catch (e) {
+        if (!(e instanceof OpenverseUnavailableError)) throw e;
+        openverseDown = true;
+        anomalies.push(`${e.message}: the remaining SFX cues use the bundled library`);
+      }
+    }
+    entry ??= fromBundled(cue);
+    if (entry) sfx.push(entry);
   }
   return { sfx, anomalies };
 }
+
+/**
+ * One sound effect for `query`, saved under the project's assets/sfx/ (the entry point for hosts).
+ * { sound: { file, source, duration_s, license?, credit? } | null, anomalies }.
+ */
+export async function findSoundEffect(query, { hyperframesDir, sfxLibDir = BUNDLED_SFX_DIR }) {
+  const { sfx, anomalies } = await resolveSfx({
+    cues: [{ id: "1", name: query }],
+    hyperframesDir,
+    sfxLibDir,
+  });
+  if (!sfx.length) return { sound: null, anomalies };
+  const { file, source, duration_s, license, credit } = sfx[0];
+  return { sound: { file, source, duration_s, ...(license && { license, credit }) }, anomalies };
+}