reframe-video 0.6.30 → 0.6.32

package/assets/sfx/LICENSE.md

@@ -14,9 +14,15 @@ Verified against each asset page's license field on 2026-06-11.
 | thud.wav (trimmed) | [Muffled Distant Explosion](https://opengameart.org/content/muffled-distant-explosion) | NenadSimic | CC0 |
 | footstep_001/002/003.ogg (footstep00/03/06) | [RPG Audio](https://kenney.nl/assets/rpg-audio) | Kenney (kenney.nl) | CC0 |
 | bgm-song21.mp3 | [Mysterious Ambience (song21)](https://opengameart.org/content/mysterious-ambience-song21) | cynicmusic (pixelsphere.org) | multi-licensed; used under its CC0 option |
+| bgm-synthwave.mp3 | [Calm Ambient 1 (Synthwave)](https://opengameart.org/content/calm-ambient-1-synthwave-4k) | cynicmusic (pixelsphere.org) | multi-licensed; used under its CC0 option |
+| bgm-piano.mp3 | [Calm Piano 1 (Vaporware)](https://opengameart.org/content/calm-piano-1-vaporware) | cynicmusic (pixelsphere.org) | multi-licensed; used under its CC0 option |
+| bgm-battle.mp3 | [Battle Theme B for RPG](https://opengameart.org/content/battle-theme-b-for-rpg) | cynicmusic (pixelsphere.org) | multi-licensed; used under its CC0 option |
+
+(The three `bgm-{synthwave,piano,battle}.mp3` are re-encoded to mono 96 kbps to keep the package small.)
 
 CC0 requires no attribution; this file records provenance anyway.
-These files are loaded only by an explicit `file:` cue (e.g.
-`{ sfx: undefined, file: "whoosh.wav" }`). A bare `sfx:` name always uses the
-procedural synthesizer (so its pitch/auto-variation applies) — it is no longer
-auto-overridden by a same-named `.wav` here.
+Six names (`whoosh`/`rise`/`shimmer`/`thud`/`pop`/`tick`) ship a curated `.wav`
+that sounds better than the synth, so a bare `sfx:` uses that sample by default
+(fixed — it doesn't pitch-vary); pass `params: { synth: 1 }` to force the varying
+synth. Every other name synthesizes. Any `.wav`/`.ogg` here is also playable
+directly via an explicit `file:` cue.

package/dist/bin.js

@@ -2453,6 +2453,10 @@ async function resolveCueFile(cue, sceneDir) {
     );
   }
   const { name, params } = cue.source;
+  if (SAMPLE_DEFAULT.has(name) && !params.synth) {
+    const vendored = join(VENDORED, `${name}.wav`);
+    if (existsSync2(vendored)) return vendored;
+  }
   return writeCached(`${name}-${fnv1a(JSON.stringify(params))}`, () => synthSfx(name, params));
 }
 async function resolveBgmFile(source, duration, sceneDir) {
@@ -2465,7 +2469,7 @@ async function resolveBgmFile(source, duration, sceneDir) {
   }
   return writeCached(`${source.name}-${duration.toFixed(2)}`, () => synthBgm(source.name, duration));
 }
-var ROOT, VENDORED, CACHE;
+var ROOT, VENDORED, CACHE, SAMPLE_DEFAULT;
 var init_sfx = __esm({
   "../render-cli/src/audio/sfx.ts"() {
     "use strict";
@@ -2474,6 +2478,7 @@ var init_sfx = __esm({
     ROOT = true ? resolve(dirname(fileURLToPath(import.meta.url)), "..") : resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "..");
     VENDORED = join(ROOT, "assets", "sfx");
     CACHE = join(tmpdir(), "reframe-sfx-cache");
+    SAMPLE_DEFAULT = /* @__PURE__ */ new Set(["whoosh", "rise", "shimmer", "thud", "pop", "tick"]);
   }
 });
 

package/dist/cli.js

@@ -1913,6 +1913,7 @@ function synthBgm(name, duration, seed = 0) {
 var ROOT = true ? resolve(dirname(fileURLToPath(import.meta.url)), "..") : resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "..");
 var VENDORED = join(ROOT, "assets", "sfx");
 var CACHE = join(tmpdir(), "reframe-sfx-cache");
+var SAMPLE_DEFAULT = /* @__PURE__ */ new Set(["whoosh", "rise", "shimmer", "thud", "pop", "tick"]);
 function fnv1a(text2) {
   let h = 2166136261;
   for (let i = 0; i < text2.length; i++) {
@@ -1945,6 +1946,10 @@ async function resolveCueFile(cue, sceneDir) {
     );
   }
   const { name, params } = cue.source;
+  if (SAMPLE_DEFAULT.has(name) && !params.synth) {
+    const vendored = join(VENDORED, `${name}.wav`);
+    if (existsSync(vendored)) return vendored;
+  }
   return writeCached(`${name}-${fnv1a(JSON.stringify(params))}`, () => synthSfx(name, params));
 }
 async function resolveBgmFile(source, duration, sceneDir) {

package/guides/edsl-guide.md

@@ -578,16 +578,19 @@ explicitly with `params`: `{ sfx: "blip", params: { seed: 4 } }` (pick the varia
 `{ sfx: "tick", params: { pitch: 1.5 } }` (an explicit frequency multiplier; `2` = octave
 up). `params.gainDb` trims a single hit.
 
-**bgm beds** (`bgm.synth`): `ambient-pad` `lofi` `pulse` `tension` `uplift` — or
-`bgm.file` for your own. **Mixing**: any cue takes `fadeIn`/`fadeOut` (seconds) and `pan`
+**bgm beds**: synthesized via `bgm.synth` (`ambient-pad` `lofi` `pulse` `tension`
+`uplift`), or a file via `bgm.file` — bundled CC0 music: `bgm-song21.mp3` (ambient),
+`bgm-synthwave.mp3` (chill), `bgm-piano.mp3` (elegant), `bgm-battle.mp3` (energetic),
+or your own path. **Mixing**: any cue takes `fadeIn`/`fadeOut` (seconds) and `pan`
 (-1 left … 0 centre … +1 right). A `video` clip's audio takes `fadeIn` and `pan` too
 (clip fade-out isn't supported yet). The bed auto-ducks under cues (`bgm.duck`).
 
 **Recorded samples** are a separate layer from the synth palette: use a `file:` cue to
 play a CC0 file from `assets/sfx/` — keyboard typing (`keypress-*.wav`, also driven by
 `textTypeCues`), `footstep_*`, and the Kenney UI pack (`click_*`/`confirmation_*`/
-`select_*`/…). A bare `sfx:` name always synthesizes (so it pitch-varies); pass
-`file: "whoosh.wav"` to play the recorded version instead. Audition the procedural set
+`select_*`/…). Six "hero" names (`whoosh`/`rise`/`shimmer`/`thud`/`pop`/`tick`) default to a
+curated CC0 sample (better fidelity, fixed — no pitch-vary); add `params: { synth: 1 }`
+to use the varying synth instead. Every other `sfx:` name synthesizes. Audition the procedural set
 with `examples/scenes/sfx-showcase.ts` and the samples with `sample-showcase.ts`.
 
 ## Rules

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reframe-video",
-  "version": "0.6.30",
+  "version": "0.6.32",
   "description": "Declarative motion graphics that AI can write and humans can tweak — human edits survive AI regeneration. Deterministic mp4 renders from a plain-data scene format.",
   "keywords": [
     "motion-graphics",