hyperframes 0.8.169 → 0.8.171

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 };
+}