hyperframes 0.8.169 → 0.8.171

package/dist/{render-QBQYF2NC.js → render-FTVXKXSQ.js}

@@ -6,24 +6,24 @@ var __filename = __hf_fileURLToPath(import.meta.url);
 var __dirname = __hf_dirname(__filename);
 import {
   maybePromptRenderFeedback
-} from "./chunk-2F4HJFGW.js";
+} from "./chunk-PAFCKH3S.js";
 import {
   captureArtifactRevision
-} from "./chunk-NKG3LTPI.js";
-import "./chunk-YT6TFGIS.js";
+} from "./chunk-KQCWIE76.js";
+import "./chunk-IWLOARQZ.js";
 import "./chunk-X7MTZ4T2.js";
 import {
   reportVariableIssues,
   resolveVariablesArg,
   validateVariablesAgainstProject
-} from "./chunk-RZKQ3G6B.js";
+} from "./chunk-T5LGOTQR.js";
 import {
   loadProducer
-} from "./chunk-CESKA6VO.js";
+} from "./chunk-NSJLCWLG.js";
 import {
   renderJobObservabilityTelemetryPayload,
   startRenderCpuSampler
-} from "./chunk-QLHXC4E6.js";
+} from "./chunk-UJQQITCY.js";
 import {
   hasExplicitCompositionArg,
   parseGifLoopArg,
@@ -32,11 +32,11 @@ import {
   resolveCompositionEntryArg,
   resolveDefaultFpsArg,
   windowsChromeCrashRemediation
-} from "./chunk-TEFHMDVR.js";
+} from "./chunk-LMMFO5UV.js";
 import {
   sandboxDeniedRemediation
 } from "./chunk-WICIV6R3.js";
-import "./chunk-EFP25BUY.js";
+import "./chunk-JAERN4RH.js";
 import {
   formatLintStartupMessage
 } from "./chunk-6CSYCFQV.js";
@@ -45,7 +45,7 @@ import {
 } from "./chunk-EDUBJPGL.js";
 import {
   resolveProject
-} from "./chunk-AP5AVVAB.js";
+} from "./chunk-A3SQJCPU.js";
 import {
   errorBox,
   formatBytes,
@@ -57,7 +57,7 @@ import {
 import {
   recordRenderSuccess,
   registerRenderOutput
-} from "./chunk-JGYHWVXQ.js";
+} from "./chunk-GMJ3ILLW.js";
 import "./chunk-FFDC5OWV.js";
 import "./chunk-DCAI5DBR.js";
 import "./chunk-DQBY7FRR.js";
@@ -69,15 +69,16 @@ import {
   loadProjectConfig,
   readProjectConfigWithStatus,
   seedProjectAuthoringSkill
-} from "./chunk-J5Z56PU3.js";
+} from "./chunk-EDGJ2OMH.js";
 import "./chunk-XT7X6QCP.js";
 import "./chunk-4YYJOFKS.js";
 import {
   normalizeSkillSlug
 } from "./chunk-HVW7ABXD.js";
-import "./chunk-5SQHHBAR.js";
-import "./chunk-5FWVFCQM.js";
-import "./chunk-EELTMBCC.js";
+import "./chunk-JMJTXBVF.js";
+import "./chunk-JHOCK3DG.js";
+import "./chunk-XGFYN53T.js";
+import "./chunk-RTW6WSC7.js";
 import "./chunk-AWDFDFI3.js";
 import "./chunk-P6LJ4Y32.js";
 import "./chunk-GMECXFAN.js";
@@ -86,8 +87,8 @@ import {
   trackRenderError,
   trackRenderObservation,
   trackRenderPreflightRejected
-} from "./chunk-FQJDV2RI.js";
-import "./chunk-FSX7GTBB.js";
+} from "./chunk-6I24ZSCR.js";
+import "./chunk-5HLJ4JMB.js";
 import "./chunk-VWG7OQKU.js";
 import {
   bytesToMb
@@ -128,11 +129,11 @@ import {
 } from "./chunk-ISN5GRYI.js";
 import {
   VERSION
-} from "./chunk-BNEKKUPG.js";
+} from "./chunk-BYFG74OA.js";
 import "./chunk-EOVYQ3IG.js";
 import {
   createRenderCancellationScope
-} from "./chunk-A6K7M46D.js";
+} from "./chunk-AWSVUIWG.js";
 import {
   H264EncoderUnavailableError,
   chromeLaunchRemediation,
@@ -148,8 +149,8 @@ import {
   MIN_VP9_CPU_USED,
   audioFailureDiagnostics,
   isVideoFrameFormat
-} from "./chunk-7FHFPHEM.js";
-import "./chunk-P24X6CGY.js";
+} from "./chunk-VKFYI7AQ.js";
+import "./chunk-FAORS3UR.js";
 import "./chunk-KCF6GHJP.js";
 import "./chunk-JYVGYKXG.js";
 import "./chunk-7KDQAD2W.js";
@@ -158,8 +159,8 @@ import {
   fpsToFfmpegArg,
   fpsToNumber,
   parseFps
-} from "./chunk-O3J7BHBU.js";
-import "./chunk-BIV5HVTQ.js";
+} from "./chunk-QZUVPWC4.js";
+import "./chunk-6M3IPJS6.js";
 import "./chunk-VC76R6W2.js";
 import "./chunk-UJKQWGFF.js";
 import {
@@ -690,7 +691,7 @@ async function executeRenderPlan(plan, dependencies, cancellation) {
   let batchModule;
   let preparedBatch;
   if (plan.batchPath) {
-    batchModule = await import("./batchRender-YKTTAIHH.js");
+    batchModule = await import("./batchRender-KWBVAUE3.js");
     try {
       preparedBatch = batchModule.prepareBatchRender({
         batchPath: plan.batchPath,

package/dist/{render-Q6QAXJCN.js → render-RZUU76V5.js}

@@ -35,18 +35,18 @@ import {
   reportVariableIssues,
   resolveVariablesArg,
   validateVariablesAgainstProject
-} from "./chunk-RZKQ3G6B.js";
+} from "./chunk-T5LGOTQR.js";
 import {
   resolveProject
-} from "./chunk-AP5AVVAB.js";
+} from "./chunk-A3SQJCPU.js";
 import {
   errorBox,
   formatBytes,
   formatDuration
 } from "./chunk-K2FLNJVB.js";
 import "./chunk-442JNXRM.js";
-import "./chunk-FQJDV2RI.js";
-import "./chunk-FSX7GTBB.js";
+import "./chunk-6I24ZSCR.js";
+import "./chunk-5HLJ4JMB.js";
 import "./chunk-VWG7OQKU.js";
 import "./chunk-QWQ6GQTI.js";
 import {
@@ -61,12 +61,12 @@ import {
 } from "./chunk-ZTZA4UWZ.js";
 import {
   withMeta
-} from "./chunk-K5PU5ISL.js";
+} from "./chunk-GSABLXZV.js";
 import "./chunk-K4WIOZFP.js";
 import "./chunk-XUXGIA7H.js";
 import "./chunk-WERLJGIC.js";
 import "./chunk-ISN5GRYI.js";
-import "./chunk-BNEKKUPG.js";
+import "./chunk-BYFG74OA.js";
 import {
   downloadToFile
 } from "./chunk-BXCMXMJQ.js";
@@ -74,8 +74,8 @@ import "./chunk-EOVYQ3IG.js";
 import "./chunk-XT6MXC7A.js";
 import "./chunk-JYVGYKXG.js";
 import "./chunk-7KDQAD2W.js";
-import "./chunk-O3J7BHBU.js";
-import "./chunk-BIV5HVTQ.js";
+import "./chunk-QZUVPWC4.js";
+import "./chunk-6M3IPJS6.js";
 import "./chunk-VC76R6W2.js";
 import "./chunk-UJKQWGFF.js";
 import "./chunk-YMS5FOMC.js";

package/dist/{render-batch-JLANN5Y2.js → render-batch-FCR7RX6U.js}

@@ -14,12 +14,15 @@ import {
   loadProjectVariableSchema,
   reportVariableIssues,
   validateVariablesAgainstSchema
-} from "./chunk-RZKQ3G6B.js";
+} from "./chunk-T5LGOTQR.js";
 import "./chunk-FH7WODJH.js";
 import {
   errorBox
 } from "./chunk-K2FLNJVB.js";
 import "./chunk-442JNXRM.js";
+import {
+  runWithConcurrencyLimit
+} from "./chunk-JHOCK3DG.js";
 import {
   failCommand,
   setCommandExitCode
@@ -27,8 +30,8 @@ import {
 import {
   c
 } from "./chunk-ZTZA4UWZ.js";
-import "./chunk-O3J7BHBU.js";
-import "./chunk-BIV5HVTQ.js";
+import "./chunk-QZUVPWC4.js";
+import "./chunk-6M3IPJS6.js";
 import "./chunk-VC76R6W2.js";
 import "./chunk-UJKQWGFF.js";
 import "./chunk-YMS5FOMC.js";
@@ -269,24 +272,8 @@ function parseBatchFile(path) {
   }
   return out;
 }
-async function runWithConcurrencyLimit(inputs, limit, worker) {
-  if (limit < 1) throw new Error(`runWithConcurrencyLimit: limit must be \u2265 1, got ${limit}`);
-  const results = new Array(inputs.length);
-  let cursor = 0;
-  const workerCount = Math.min(limit, inputs.length);
-  await Promise.all(
-    Array.from({ length: workerCount }, async () => {
-      while (cursor < inputs.length) {
-        const idx = cursor++;
-        results[idx] = await worker(inputs[idx], idx);
-      }
-    })
-  );
-  return results;
-}
 export {
   buildLambdaBatchRenderConfig,
   parseBatchFile,
-  runRenderBatch,
-  runWithConcurrencyLimit
+  runRenderBatch
 };

package/dist/renderSetupWorker.js

@@ -43,10 +43,18 @@ var disposeSignalHandlers = installRenderSetupSignalHandlers(
   (signal) => process.kill(process.pid, signal),
   process.env.HYPERFRAMES_RENDER_DETACHED !== "1"
 );
+function lowerPriority() {
+  try {
+    setPriority(constants.priority.PRIORITY_LOW);
+  } catch (error) {
+    process.stderr.write(`Lint runs at normal priority: ${error.message}
+`);
+  }
+}
 async function runMode() {
   if (mode === "browser") return ensureBrowser(input);
   if (mode === "lint") {
-    setPriority(constants.priority.PRIORITY_LOW);
+    lowerPriority();
     return lintProject(
       input.projectDir,
       input.entryFile,

package/dist/{resolver-EDUM4DHG.js → resolver-4SPHOGY7.js}

@@ -11,13 +11,14 @@ import {
   resolveItemWithDependencies,
   resolveItemsByTag,
   unreachableRegistryMessage
-} from "./chunk-5SQHHBAR.js";
-import "./chunk-EELTMBCC.js";
+} from "./chunk-JMJTXBVF.js";
+import "./chunk-JHOCK3DG.js";
+import "./chunk-RTW6WSC7.js";
 import "./chunk-AWDFDFI3.js";
 import "./chunk-P6LJ4Y32.js";
 import "./chunk-GMECXFAN.js";
-import "./chunk-O3J7BHBU.js";
-import "./chunk-BIV5HVTQ.js";
+import "./chunk-QZUVPWC4.js";
+import "./chunk-6M3IPJS6.js";
 import "./chunk-VC76R6W2.js";
 import "./chunk-UJKQWGFF.js";
 import "./chunk-YMS5FOMC.js";

package/dist/{sherpa-QEM5XYHD.js → sherpa-VMADZBF7.js}

@@ -17,24 +17,24 @@ import {
   sherpaRuntimeLoadError,
   sherpaUnsupportedReason,
   transcribeWithSherpa
-} from "./chunk-U7P2XTRY.js";
+} from "./chunk-PECICVTJ.js";
 import "./chunk-BXCMXMJQ.js";
 import "./chunk-3DKN5WKL.js";
 import "./chunk-EOVYQ3IG.js";
-import "./chunk-UISU4SYG.js";
-import "./chunk-A6K7M46D.js";
+import "./chunk-V2T7FFPB.js";
+import "./chunk-AWSVUIWG.js";
 import "./chunk-6BEFEWFB.js";
 import "./chunk-X3SCQP2A.js";
 import "./chunk-PO2SDVQA.js";
 import "./chunk-IK3SOMZ4.js";
 import "./chunk-XT6MXC7A.js";
-import "./chunk-7FHFPHEM.js";
-import "./chunk-P24X6CGY.js";
+import "./chunk-VKFYI7AQ.js";
+import "./chunk-FAORS3UR.js";
 import "./chunk-KCF6GHJP.js";
 import "./chunk-JYVGYKXG.js";
 import "./chunk-7KDQAD2W.js";
-import "./chunk-O3J7BHBU.js";
-import "./chunk-BIV5HVTQ.js";
+import "./chunk-QZUVPWC4.js";
+import "./chunk-6M3IPJS6.js";
 import "./chunk-VC76R6W2.js";
 import "./chunk-UJKQWGFF.js";
 import "./chunk-YMS5FOMC.js";

package/dist/skills/media-use/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: media-use
-description: Agent Media OS for a HyperFrames project. Resolve BGM, SFX, image, icon, brand logo, voice, color grade, or LUT into a frozen local file or paste-ready block + ledger record (one verb, `resolve`); generate via TTS / music / image models when the catalog misses; produce voiceover, transcription, captions, and background removal through one shared audio engine; operate on media (cut / reframe / transform); and reuse assets across projects. Also use for vague feedback that real footage looks dark, flat, boring, should feel retro/camcorder/print/ASCII, needs privacy, or needs a media reveal. When the host app provides its own music or sound-effect tools, use those for music and sound effects; `resolve --type bgm|sfx` needs the heygen CLI. When `HEYGEN_API_BASE` is set, HeyGen calls go through that host with no CLI sign-in.
+description: Agent Media OS for a HyperFrames project. Resolve BGM, SFX, image, icon, brand logo, voice, color grade, or LUT into a frozen local file or paste-ready block + ledger record (one verb, `resolve`); generate via TTS / music / image models when the catalog misses; produce voiceover, transcription, captions, and background removal through one shared audio engine; operate on media (cut / reframe / transform); and reuse assets across projects. Also use for vague feedback that real footage looks dark, flat, boring, should feel retro/camcorder/print/ASCII, needs privacy, or needs a media reveal. When the host app provides its own music or sound-effect tools, use those for music and sound effects; `resolve --type bgm` needs the heygen CLI, while `--type sfx` needs no account (Openverse, then a bundled library). When `HEYGEN_API_BASE` is set, HeyGen calls go through that host with no CLI sign-in.
 ---
 
 **Plugin installs:** Before setup or freshness commands, follow [plugin execution rules](../hyperframes/references/plugin-installation.md) when this skill is inside a HyperFrames plugin. Standalone installs keep the update instructions below.
@@ -13,7 +13,7 @@ Only when `HEYGEN_API_BASE` is set in your environment (a host app set it and pa
 
 First run otherwise (no `HEYGEN_API_BASE`), when you will use HeyGen media (catalog search, TTS, avatar video): install and sign in to the `heygen` CLI (the free-usage path), then verify with `npx hyperframes media-use resolve --doctor`. Setup and providers: `references/setup-providers.md`.
 
-Music and sound effects inside a host app: when the app you run in gives you its own music or sound-effect tools, use those. Without `HEYGEN_API_BASE`, `resolve --type bgm` and `--type sfx` search the HeyGen catalog through the `heygen` CLI; without it they fail and say so (`sfx` still answers from its bundled library).
+Music and sound effects inside a host app: when the app you run in gives you its own music or sound-effect tools, use those. Without `HEYGEN_API_BASE`, `resolve --type bgm` searches the HeyGen catalog through the `heygen` CLI and fails without it, saying so. `resolve --type sfx` searches Openverse (CC0 and CC BY only, no account) and falls back to its bundled library offline; credit CC BY sounds as `audio/references/sfx.md` says.
 
 Without `HEYGEN_API_BASE`, before generating a voiceover or an avatar video, tell the person: signing in to the heygen CLI with OAuth (`heygen auth login --oauth`) gives a free allowance for TTS voiceover and avatar videos, while an API key bills API credits.
 
@@ -28,7 +28,7 @@ Returns one line: `resolved <id> → <path> (<type>, <metadata>)`. All search no
 | Type    | One-line intent                                                                  |
 | ------- | -------------------------------------------------------------------------------- |
 | `bgm`   | background music (HeyGen catalog via the `heygen` CLI, 10k+ tracks)              |
-| `sfx`   | sound effects (bundled 19-file library + catalog via the `heygen` CLI)           |
+| `sfx`   | sound effects (Openverse CC0 / CC BY, bundled 21-file library offline)           |
 | `image` | photos, backgrounds (HeyGen asset search, 75k+ vectors)                          |
 | `icon`  | icons, symbols (transparent)                                                     |
 | `logo`  | official brand marks (theSVG → GitHub avatar → favicon; never redrawn)           |

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

@@ -4,13 +4,13 @@
 
 Run `npx hyperframes auth status` to see what's configured and which engines a workflow will use (see the skill's **Preflight** section). Keys resolve in this order — **first match wins**:
 
-| Provider                             | Resolution order (first non-empty wins)                                                                                                                                    | Local deps when used                             |
-| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
-| **HeyGen** (TTS + BGM/SFX retrieval) | `$HEYGEN_API_KEY` → `$HYPERFRAMES_API_KEY` → `~/.heygen/credentials` (shared with heygen-cli; `$HEYGEN_CONFIG_DIR` overrides the dir; written by `hyperframes auth login`) | none (REST)                                      |
-| **ElevenLabs** (TTS fallback)        | `$ELEVENLABS_API_KEY`                                                                                                                                                      | `pip install elevenlabs`                         |
-| **Lyria** (BGM fallback)             | `$GEMINI_API_KEY` → `$GOOGLE_API_KEY`                                                                                                                                      | `pip install google-genai`                       |
-| **Kokoro** (TTS, no key)             | always — final voice fallback                                                                                                                                              | `pip install kokoro-onnx soundfile`              |
-| **MusicGen** (BGM, no key)           | always — final music fallback                                                                                                                                              | `pip install transformers torch soundfile numpy` |
+| Provider                         | Resolution order (first non-empty wins)                                                                                                                                    | Local deps when used                             |
+| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
+| **HeyGen** (TTS + BGM retrieval) | `$HEYGEN_API_KEY` → `$HYPERFRAMES_API_KEY` → `~/.heygen/credentials` (shared with heygen-cli; `$HEYGEN_CONFIG_DIR` overrides the dir; written by `hyperframes auth login`) | none (REST)                                      |
+| **ElevenLabs** (TTS fallback)    | `$ELEVENLABS_API_KEY`                                                                                                                                                      | `pip install elevenlabs`                         |
+| **Lyria** (BGM fallback)         | `$GEMINI_API_KEY` → `$GOOGLE_API_KEY`                                                                                                                                      | `pip install google-genai`                       |
+| **Kokoro** (TTS, no key)         | always — final voice fallback                                                                                                                                              | `pip install kokoro-onnx soundfile`              |
+| **MusicGen** (BGM, no key)       | always — final music fallback                                                                                                                                              | `pip install transformers torch soundfile numpy` |
 
 `hyperframes auth login` (browser OAuth) is the recommended setup: one sign-in, every project, no per-repo `.env`. An OAuth login is sent as `Authorization: Bearer`; an API key as `X-Api-Key`; both are tagged with `X-HeyGen-Source: cli`. OAuth CLI users can consume the web-plan free allowance for HeyGen TTS (10 min/month); API keys follow the normal API billing path. With no HeyGen credential, voice/BGM run fully locally (Kokoro / MusicGen) — `hyperframes auth status` and `hyperframes doctor` both report whether those local deps are installed.
 

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

@@ -1,35 +1,41 @@
 # Sound effects (SFX)
 
-Named sound effects, produced by the shared audio engine (`scripts/audio.mjs` → `scripts/lib/sfx.mjs`). **Provider-gated** by the engine's one switch — whether a HeyGen credential is present, decided once (not per cue):
+Named sound effects, produced by the shared audio engine (`scripts/audio.mjs` → `scripts/lib/sfx.mjs`). No account or key is needed:
 
-- **HeyGen credential present → retrieve every cue** from HeyGen's audio library (`/v3/audio/sounds`, `type=sound_effects`, `min_score=0.4`). Search-and-download, **not** generation. The bundled library is NOT consulted.
-- **No credential → the bundled 21-file library** (`assets/sfx/` + `manifest.json`): match each cue name, copy the matched file into the project. Offline, deterministic, free.
+- **Openverse first, per cue.** Each cue is searched on [Openverse](https://openverse.org)'s free audio API (most sound effects come from Freesound). Search-and-download, **not** generation.
+- **The bundled 21-file library is the fallback** (`assets/sfx/` + `manifest.json`): a cue Openverse has no usable match for, and every cue once Openverse is offline or rate limited, is matched against it and the file copied into the project.
 
-There is no `npx hyperframes sfx` command. SFX is never generated — it is retrieved (online) or taken from the bundled library (offline).
+There is no `npx hyperframes sfx` command. SFX is never generated — it is retrieved from Openverse (online) or taken from the bundled library (offline). `npx hyperframes media-use resolve --type sfx` follows the same order (`--local-only` skips Openverse).
+
+## Licences
+
+Only **CC0** and **CC BY** sounds are used: never NonCommercial, ShareAlike or NoDerivatives. Each CC BY sound is credited in the project's `assets/sfx/CREDITS.md` (title, creator, licence, source link; for `resolve`, in a `CREDITS.md` beside the sound files it saves) and its `audio_meta.sfx[]` entry carries `license` and `credit`. Tell the person to include those credits wherever the video is published.
 
 ## Cues — request → meta
 
-Each line names the effects it wants: `lines[].sfx: ["whoosh", "ui click"]`. The engine flattens these into cues, resolves them per the switch, dedupes identical `(id, name)` pairs (the same effect named twice downloads/copies once), and writes `audio_meta.sfx[]`:
+Each line names the effects it wants: `lines[].sfx: ["whoosh", "ui click"]`. The engine flattens these into cues, resolves each, dedupes identical `(id, name)` pairs (the same effect named twice downloads/copies once), and writes `audio_meta.sfx[]`:
 
 ```jsonc
 {
   "id": "3",                       // joins the cue to the caller's model (frame / scene / segment)
   "name": "whoosh",
   "file": "assets/sfx/whoosh.mp3", // downloaded or copied, relative to project root
-  "source": "heygen" | "local",    // which route resolved it
+  "source": "openverse" | "local", // which route resolved it
   "offset_s": 0,                   // delay from the line's start
   "duration_s": 0.57,
-  "volume": 0.35                   // SFX sit UNDER voice + BGM
+  "volume": 0.35,                  // SFX sit UNDER voice + BGM
+  "license": "by",                 // Openverse only: "cc0" or "by"
+  "credit": "\"Swoosh\" by Ana is licensed under CC BY 4.0. …" // Openverse only
 }
 ```
 
 A cue that matches nothing is **skipped** (recorded as an anomaly); SFX never blocks a render. Neither route replaces a file of yours already at the output name: the cue gets the next free name (`whoosh-2.mp3`), reported as an anomaly, and `file` carries the real path.
 
-## HeyGen retrieval (credentialed)
+## Openverse
 
-`searchSounds(name, "sound_effects", { limit: 3, minScore: 0.4 })` → top hit → `assets/sfx/<slug>.mp3`. Results are ranked by `score` (each carries a presigned `audio_url`, `duration`, `description`). The floor is **0.4** because good SFX hits score ~0.5–0.67 — below the API's default `0.7`, which would silently drop most named cues (only whoosh/swoosh-family clears 0.7). `duration_s` comes from the result (else 1.0). Name effects concretely (`glass shatter`, not `dramatic sound`); a vague query returns a poor match.
+One search per distinct effect name (20 results, `license=cc0,by`; each result's licence is checked again). The pick keeps Openverse's relevance order, prefers clips that fit a cue (15 s at most; past ~4 s ranks lower) and CC0 over CC BY when they are close. The file lands at `assets/sfx/<slug>.<ext>` and `duration_s` comes from the result. Name effects concretely (`glass shatter`, not `dramatic sound`); a vague query returns a poor match. Anonymous use allows 20 searches a minute and 200 a day: past that, the rest of the run uses the bundled library.
 
-## Bundled library (no credential)
+## Bundled library (fallback)
 
 21 curated files in `assets/sfx/`, indexed by `manifest.json` — `{ file, duration, description }` per key (e.g. `whoosh`, `pop`, `click`, `chime`, `riser`, `impact-bass-1`, `glitch-1`, `typing`, …). A cue name resolves by **manifest key, file basename, or slug**, so `whoosh`, `whoosh.mp3`, or `"ui click"` (→ slug) all match. Matched files are copied into the project's `assets/sfx/`; `duration_s` comes from the manifest, so timing is known **offline** — e.g. `riser` is 10.03s, so trigger it at `climax − 10.03s`. The manifest's `description` field carries placement hints per effect; read `assets/sfx/manifest.json` for the full set and usage.
 
@@ -37,6 +43,6 @@ A cue that matches nothing is **skipped** (recorded as an anomaly); SFX never bl
 
 - **Volume ~0.35.** SFX must sit under narration and BGM, not fight them.
 - **No match → skip, don't fail.** A missing effect logs an anomaly and moves on; never a render blocker.
-- **Retrieval (credentialed) or bundled library (offline) — never generation.** You search HeyGen by text, or match a name against the 21-file manifest.
-- **One asset per distinct name.** Reuse across lines is deduped to a single download/copy, many cues.
-- **The switch is global, not per cue.** With a credential, retrieval handles even the long tail (effects not in the 21); without one, only the 21 bundled names resolve.
+- **Retrieval (Openverse) or bundled library (offline) — never generation.**
+- **One asset per distinct name.** Reuse across lines is deduped to a single search and download, many cues.
+- **Credit CC BY sounds.** `CREDITS.md` lists them; keep it with the project.

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({