reframe-video 0.6.26 → 0.6.27

package/dist/diff.js

@@ -13,6 +13,30 @@ import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 // ../core/src/ir.ts
+var SFX_NAMES = [
+  "whoosh",
+  "swish",
+  "rise",
+  "riser",
+  "warp",
+  "tick",
+  "click",
+  "blip",
+  "pop",
+  "select",
+  "thud",
+  "boom",
+  "knock",
+  "chime",
+  "ding",
+  "coin",
+  "sparkle",
+  "shimmer",
+  "success",
+  "zap",
+  "error"
+];
+var BGM_SYNTHS = ["ambient-pad", "lofi", "pulse", "tension", "uplift"];
 var DEFAULT_TO_DURATION = 0.5;
 var DEFAULT_TWEEN_DURATION = 0.5;
 var DEFAULT_MOTIONPATH_DURATION = 1;
@@ -662,7 +686,6 @@ function validateScene(ir) {
       }
     }
   }
-  const SFX_NAMES = ["whoosh", "pop", "tick", "rise", "shimmer", "thud"];
   for (const [i, cue] of (ir.audio?.cues ?? []).entries()) {
     if (typeof cue.at === "string" && !labels.has(cue.at)) {
       problems.push(
@@ -698,6 +721,10 @@ function validateScene(ir) {
   if (ir.audio?.bgm?.file !== void 0 && ir.audio.bgm.synth !== void 0) {
     problems.push('audio.bgm: use either "file" or "synth", not both');
   }
+  const bgmSynth = ir.audio?.bgm?.synth;
+  if (bgmSynth !== void 0 && !BGM_SYNTHS.includes(bgmSynth)) {
+    problems.push(`audio.bgm.synth: unknown synth "${bgmSynth}" \u2014 valid: ${BGM_SYNTHS.join(", ")}`);
+  }
   if (problems.length > 0) throw new SceneValidationError(problems);
 }
 var TRANSITIONS = ["cut", "crossfade"];

package/dist/frame.js

@@ -40,6 +40,30 @@ import { existsSync } from "node:fs";
 import { extname, isAbsolute, resolve } from "node:path";
 
 // ../core/src/ir.ts
+var SFX_NAMES = [
+  "whoosh",
+  "swish",
+  "rise",
+  "riser",
+  "warp",
+  "tick",
+  "click",
+  "blip",
+  "pop",
+  "select",
+  "thud",
+  "boom",
+  "knock",
+  "chime",
+  "ding",
+  "coin",
+  "sparkle",
+  "shimmer",
+  "success",
+  "zap",
+  "error"
+];
+var BGM_SYNTHS = ["ambient-pad", "lofi", "pulse", "tension", "uplift"];
 var DEFAULT_TO_DURATION = 0.5;
 var DEFAULT_TWEEN_DURATION = 0.5;
 var DEFAULT_MOTIONPATH_DURATION = 1;
@@ -689,7 +713,6 @@ function validateScene(ir) {
       }
     }
   }
-  const SFX_NAMES = ["whoosh", "pop", "tick", "rise", "shimmer", "thud"];
   for (const [i, cue] of (ir.audio?.cues ?? []).entries()) {
     if (typeof cue.at === "string" && !labels.has(cue.at)) {
       problems.push(
@@ -725,6 +748,10 @@ function validateScene(ir) {
   if (ir.audio?.bgm?.file !== void 0 && ir.audio.bgm.synth !== void 0) {
     problems.push('audio.bgm: use either "file" or "synth", not both');
   }
+  const bgmSynth = ir.audio?.bgm?.synth;
+  if (bgmSynth !== void 0 && !BGM_SYNTHS.includes(bgmSynth)) {
+    problems.push(`audio.bgm.synth: unknown synth "${bgmSynth}" \u2014 valid: ${BGM_SYNTHS.join(", ")}`);
+  }
   if (problems.length > 0) throw new SceneValidationError(problems);
 }
 var TRANSITIONS = ["cut", "crossfade"];

package/dist/index.js

@@ -1,4 +1,28 @@
 // ../core/src/ir.ts
+var SFX_NAMES = [
+  "whoosh",
+  "swish",
+  "rise",
+  "riser",
+  "warp",
+  "tick",
+  "click",
+  "blip",
+  "pop",
+  "select",
+  "thud",
+  "boom",
+  "knock",
+  "chime",
+  "ding",
+  "coin",
+  "sparkle",
+  "shimmer",
+  "success",
+  "zap",
+  "error"
+];
+var BGM_SYNTHS = ["ambient-pad", "lofi", "pulse", "tension", "uplift"];
 var DEFAULT_CROSSFADE = 0.5;
 var DEFAULT_TO_DURATION = 0.5;
 var DEFAULT_TWEEN_DURATION = 0.5;
@@ -785,7 +809,6 @@ function validateScene(ir) {
       }
     }
   }
-  const SFX_NAMES = ["whoosh", "pop", "tick", "rise", "shimmer", "thud"];
   for (const [i, cue] of (ir.audio?.cues ?? []).entries()) {
     if (typeof cue.at === "string" && !labels.has(cue.at)) {
       problems.push(
@@ -821,6 +844,10 @@ function validateScene(ir) {
   if (ir.audio?.bgm?.file !== void 0 && ir.audio.bgm.synth !== void 0) {
     problems.push('audio.bgm: use either "file" or "synth", not both');
   }
+  const bgmSynth = ir.audio?.bgm?.synth;
+  if (bgmSynth !== void 0 && !BGM_SYNTHS.includes(bgmSynth)) {
+    problems.push(`audio.bgm.synth: unknown synth "${bgmSynth}" \u2014 valid: ${BGM_SYNTHS.join(", ")}`);
+  }
   if (problems.length > 0) throw new SceneValidationError(problems);
 }
 var TRANSITIONS = ["cut", "crossfade"];
@@ -2889,12 +2916,32 @@ function motionOp(name, target, opts = {}) {
 
 // ../core/src/audio.ts
 var SFX_DURATION = {
+  // transition
   whoosh: 0.35,
-  pop: 0.12,
-  tick: 0.03,
+  swish: 0.32,
   rise: 0.5,
+  riser: 0.85,
+  warp: 0.5,
+  // ui
+  tick: 0.03,
+  click: 0.05,
+  blip: 0.1,
+  pop: 0.12,
+  select: 0.18,
+  // impact
+  thud: 0.25,
+  boom: 0.6,
+  knock: 0.14,
+  // positive
+  chime: 0.7,
+  ding: 0.5,
+  coin: 0.3,
+  sparkle: 0.6,
   shimmer: 0.9,
-  thud: 0.25
+  success: 0.6,
+  // alert
+  zap: 0.22,
+  error: 0.4
 };
 var FILE_CUE_DURATION = 0.4;
 function collectClipAudio(ir, duration, warnings) {
@@ -2954,7 +3001,11 @@ function resolveAudioPlan(compiled) {
       fadeIn: cue.fadeIn ?? 0,
       fadeOut: cue.fadeOut ?? 0,
       pan: cue.pan ?? 0,
-      source: cue.sfx ? { kind: "sfx", name: cue.sfx, params: cue.params ?? {} } : { kind: "file", path: cue.file }
+      source: cue.sfx ? (
+        // auto-vary: default the seed to the cue's order so repeated sfx differ
+        // (pitch/texture); an explicit params.seed always wins.
+        { kind: "sfx", name: cue.sfx, params: { seed: index, ...cue.params } }
+      ) : { kind: "file", path: cue.file }
     });
   }
   cues.sort((a, b) => a.t - b.t);
@@ -3034,7 +3085,11 @@ function resolveCompositionAudioPlan(comp) {
       fadeIn: cue.fadeIn ?? 0,
       fadeOut: cue.fadeOut ?? 0,
       pan: cue.pan ?? 0,
-      source: cue.sfx ? { kind: "sfx", name: cue.sfx, params: cue.params ?? {} } : { kind: "file", path: cue.file }
+      source: cue.sfx ? (
+        // auto-vary: default the seed to the cue's order so repeated sfx differ
+        // (pitch/texture); an explicit params.seed always wins.
+        { kind: "sfx", name: cue.sfx, params: { seed: index, ...cue.params } }
+      ) : { kind: "file", path: cue.file }
     });
   }
   if (!audio?.bgm && cues.length === 0 && clipAudio.length === 0) return null;
@@ -3593,6 +3648,7 @@ function sketchToTimeline(sketch, nodeIds) {
   return par(...steps);
 }
 export {
+  BGM_SYNTHS,
   CAMERA_ID,
   CAMERA_PROPS2 as CAMERA_PROPS,
   CHARACTER_PRESET_NAMES,
@@ -3608,6 +3664,7 @@ export {
   PRESET_NAMES,
   PROPS_BY_TYPE,
   SFX_DURATION,
+  SFX_NAMES,
   SceneValidationError,
   beat,
   cameraFit,

package/dist/labels.js

@@ -1,6 +1,30 @@
 #!/usr/bin/env tsx
 
 // ../core/src/ir.ts
+var SFX_NAMES = [
+  "whoosh",
+  "swish",
+  "rise",
+  "riser",
+  "warp",
+  "tick",
+  "click",
+  "blip",
+  "pop",
+  "select",
+  "thud",
+  "boom",
+  "knock",
+  "chime",
+  "ding",
+  "coin",
+  "sparkle",
+  "shimmer",
+  "success",
+  "zap",
+  "error"
+];
+var BGM_SYNTHS = ["ambient-pad", "lofi", "pulse", "tension", "uplift"];
 var DEFAULT_TO_DURATION = 0.5;
 var DEFAULT_TWEEN_DURATION = 0.5;
 var DEFAULT_MOTIONPATH_DURATION = 1;
@@ -650,7 +674,6 @@ function validateScene(ir) {
       }
     }
   }
-  const SFX_NAMES = ["whoosh", "pop", "tick", "rise", "shimmer", "thud"];
   for (const [i, cue] of (ir.audio?.cues ?? []).entries()) {
     if (typeof cue.at === "string" && !labels.has(cue.at)) {
       problems.push(
@@ -686,6 +709,10 @@ function validateScene(ir) {
   if (ir.audio?.bgm?.file !== void 0 && ir.audio.bgm.synth !== void 0) {
     problems.push('audio.bgm: use either "file" or "synth", not both');
   }
+  const bgmSynth = ir.audio?.bgm?.synth;
+  if (bgmSynth !== void 0 && !BGM_SYNTHS.includes(bgmSynth)) {
+    problems.push(`audio.bgm.synth: unknown synth "${bgmSynth}" \u2014 valid: ${BGM_SYNTHS.join(", ")}`);
+  }
   if (problems.length > 0) throw new SceneValidationError(problems);
 }
 

package/dist/types/audio.d.ts

@@ -8,7 +8,7 @@
  */
 import type { CompiledScene } from "./compile.js";
 import type { CompiledComposition } from "./composeComposition.js";
-import type { SfxName } from "./ir.js";
+import type { BgmSynth, SfxName } from "./ir.js";
 /** Nominal cue lengths (s) for duck-window math; file cues use a default. */
 export declare const SFX_DURATION: Record<SfxName, number>;
 export interface ResolvedCue {
@@ -55,7 +55,7 @@ export interface AudioPlan {
             path: string;
         } | {
             kind: "synth";
-            name: "ambient-pad";
+            name: BgmSynth;
         };
         gain: number;
         fadeIn: number;

package/dist/types/ir.d.ts

@@ -412,7 +412,20 @@ export interface BehaviorIR {
         };
     };
 }
-export type SfxName = "whoosh" | "pop" | "tick" | "rise" | "shimmer" | "thud";
+/**
+ * The procedural sfx palette — the single source of truth (the type, validation,
+ * and the render-cli synth recipes all key off this). Grouped by use:
+ *   transition: whoosh swish rise riser warp   · ui: tick click blip pop select
+ *   impact: thud boom knock   · positive: chime ding coin sparkle shimmer success
+ *   alert: zap error
+ * Every cue's pitch/texture varies with its `seed` (auto-seeded by cue order), so
+ * repeated cues sound different; `params.pitch` is an explicit multiplier.
+ */
+export declare const SFX_NAMES: readonly ["whoosh", "swish", "rise", "riser", "warp", "tick", "click", "blip", "pop", "select", "thud", "boom", "knock", "chime", "ding", "coin", "sparkle", "shimmer", "success", "zap", "error"];
+export type SfxName = (typeof SFX_NAMES)[number];
+/** Synthesized background-music beds (license-free). */
+export declare const BGM_SYNTHS: readonly ["ambient-pad", "lofi", "pulse", "tension", "uplift"];
+export type BgmSynth = (typeof BGM_SYNTHS)[number];
 export interface AudioCueIR {
     /** Anchor: a timeline label (the step's start) or absolute seconds. */
     at: string | number;
@@ -430,14 +443,18 @@ export interface AudioCueIR {
     fadeOut?: number;
     /** Stereo balance: -1 full left, 0 centre (default), +1 full right. */
     pan?: number;
-    /** Synth parameter overrides (seed, duration, …) — numbers only. */
+    /**
+     * Synth parameter overrides — numbers only. `seed` varies pitch/texture
+     * (defaults to the cue's order so repeats differ); `pitch` is an explicit
+     * frequency multiplier (1 = unchanged, 2 = an octave up); `gainDb` trims level.
+     */
     params?: Record<string, number>;
 }
 export interface AudioIR {
     bgm?: {
         file?: string;
-        /** License-free synthesized bed. */
-        synth?: "ambient-pad";
+        /** License-free synthesized bed (see {@link BGM_SYNTHS}). */
+        synth?: BgmSynth;
         gain?: number;
         fadeIn?: number;
         fadeOut?: number;

package/guides/edsl-guide.md

@@ -558,12 +558,28 @@ audio: {
 }
 ```
 
-Procedural sfx names: `whoosh` `pop` `tick` `rise` `shimmer` `thud` (deterministic,
-seedable via `params: { seed }`). Exactly one of `sfx`/`file` per cue.
-**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 — a clip has no fixed length in the plan). The bed auto-ducks under cues
-(`bgm.duck`).
+**Procedural sfx palette** (deterministic; exactly one of `sfx`/`file` per cue):
+
+| group | names |
+| --- | --- |
+| transition | `whoosh` `swish` `rise` `riser` `warp` |
+| ui | `tick` `click` `blip` `pop` `select` |
+| impact | `thud` `boom` `knock` |
+| positive | `chime` `ding` `coin` `sparkle` `shimmer` `success` |
+| alert | `zap` `error` |
+
+**Variation — repeats don't sound the same.** Each cue's `seed` shifts the sound's
+PITCH (a musical step) and texture, and it **defaults to the cue's order**, so a run of
+the same sfx becomes a little phrase instead of a stuck note — no setup needed. Override
+explicitly with `params`: `{ sfx: "blip", params: { seed: 4 } }` (pick the variant) or
+`{ 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`
+(-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`). See
+`examples/scenes/sfx-showcase.ts` to audition the whole palette.
 
 ## Rules
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reframe-video",
-  "version": "0.6.26",
+  "version": "0.6.27",
   "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",