reframe-video 0.6.17 → 0.6.18

package/dist/bin.js

@@ -578,6 +578,15 @@ function validateScene(ir) {
     if (cue.gain !== void 0 && cue.gain < 0) {
       problems.push(`audio.cues[${i}]: gain must be >= 0`);
     }
+    if (cue.fadeIn !== void 0 && cue.fadeIn < 0) {
+      problems.push(`audio.cues[${i}]: fadeIn must be >= 0`);
+    }
+    if (cue.fadeOut !== void 0 && cue.fadeOut < 0) {
+      problems.push(`audio.cues[${i}]: fadeOut must be >= 0`);
+    }
+    if (cue.pan !== void 0 && (cue.pan < -1 || cue.pan > 1)) {
+      problems.push(`audio.cues[${i}]: pan must be in [-1, 1] (-1 left \u2026 +1 right)`);
+    }
   }
   const duck = ir.audio?.bgm?.duck;
   if (typeof duck === "object" && duck !== null && duck.depth !== void 0 && (duck.depth < 0 || duck.depth > 1)) {
@@ -644,7 +653,7 @@ var init_validate = __esm({
       line: ["x1", "y1", "x2", "y2", "stroke", "strokeWidth", "opacity", "progress", ...FX_PROPS],
       text: [...COMMON_PROPS, "content", "contentDecimals", "contentThousands", "prefix", "suffix", "fontFamily", "fontSize", "fontWeight", "fill", "letterSpacing"],
       image: [...COMMON_PROPS, "src", "width", "height", "fit"],
-      video: [...COMMON_PROPS, "src", "width", "height", "fit", "start", "rate", "clipStart", "volume"],
+      video: [...COMMON_PROPS, "src", "width", "height", "fit", "start", "rate", "clipStart", "volume", "fadeIn", "pan"],
       path: [...COMMON_PROPS, "d", "fill", "stroke", "strokeWidth", "progress", "originX", "originY"],
       group: COMMON_PROPS
     };
@@ -1251,7 +1260,7 @@ function collectClipAudio(ir, duration, warnings) {
           warnings.push(`video "${node.id}": start ${start.toFixed(2)}s past the scene end \u2014 audio dropped`);
           continue;
         }
-        out.push({ nodeId: node.id, src: node.props.src, start, rate: node.props.rate ?? 1, clipStart: node.props.clipStart ?? 0, gain });
+        out.push({ nodeId: node.id, src: node.props.src, start, rate: node.props.rate ?? 1, clipStart: node.props.clipStart ?? 0, gain, fadeIn: node.props.fadeIn ?? 0, pan: node.props.pan ?? 0 });
       }
       if (node.type === "group") walk(node.children);
     }
@@ -1293,6 +1302,9 @@ function resolveAudioPlan(compiled) {
       t,
       gain: cue.gain ?? 1,
       duration: cueDuration,
+      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 }
     });
   }
@@ -1985,6 +1997,10 @@ function atempoChain(rate) {
   out.push(`atempo=${r.toFixed(4)}`);
   return out;
 }
+function panFilter(pan) {
+  const clamp = (v) => Math.max(0, Math.min(1, v)).toFixed(4);
+  return `pan=stereo|c0=${clamp(1 - pan)}*c0|c1=${clamp(1 + pan)}*c1`;
+}
 function buildFilterGraph(plan, inputs) {
   const lines = [];
   const mixIn = ["[anchor]"];
@@ -2013,7 +2029,14 @@ function buildFilterGraph(plan, inputs) {
   }
   plan.cues.forEach((cue, i) => {
     const delayMs = Math.round(cue.t * 1e3);
-    lines.push(`[${inputIndex}:a]${FORMAT},volume=${cue.gain},adelay=${delayMs}:all=1[c${i}]`);
+    const chain = [FORMAT, `volume=${cue.gain}`];
+    if (cue.fadeIn > 0) chain.push(`afade=t=in:st=0:d=${cue.fadeIn}`);
+    if (cue.fadeOut > 0) {
+      chain.push(`afade=t=out:st=${Math.max(0, cue.duration - cue.fadeOut).toFixed(3)}:d=${cue.fadeOut}`);
+    }
+    if (cue.pan !== 0) chain.push(panFilter(cue.pan));
+    chain.push(`adelay=${delayMs}:all=1`);
+    lines.push(`[${inputIndex}:a]${chain.join(",")}[c${i}]`);
     mixIn.push(`[c${i}]`);
     inputIndex++;
   });
@@ -2021,6 +2044,8 @@ function buildFilterGraph(plan, inputs) {
     const chain = [];
     if (audio.clipStart > 0) chain.push(`atrim=start=${audio.clipStart.toFixed(3)}`, "asetpts=PTS-STARTPTS");
     chain.push(...atempoChain(audio.rate), FORMAT, `volume=${audio.gain}`);
+    if (audio.fadeIn > 0) chain.push(`afade=t=in:st=0:d=${audio.fadeIn}`);
+    if (audio.pan !== 0) chain.push(panFilter(audio.pan));
     const delayMs = Math.round(audio.start * 1e3);
     if (delayMs > 0) chain.push(`adelay=${delayMs}:all=1`);
     lines.push(`[${inputIndex}:a]${chain.join(",")}[k${i}]`);

package/dist/browserEntry.js

@@ -350,7 +350,7 @@
     line: ["x1", "y1", "x2", "y2", "stroke", "strokeWidth", "opacity", "progress", ...FX_PROPS],
     text: [...COMMON_PROPS, "content", "contentDecimals", "contentThousands", "prefix", "suffix", "fontFamily", "fontSize", "fontWeight", "fill", "letterSpacing"],
     image: [...COMMON_PROPS, "src", "width", "height", "fit"],
-    video: [...COMMON_PROPS, "src", "width", "height", "fit", "start", "rate", "clipStart", "volume"],
+    video: [...COMMON_PROPS, "src", "width", "height", "fit", "start", "rate", "clipStart", "volume", "fadeIn", "pan"],
     path: [...COMMON_PROPS, "d", "fill", "stroke", "strokeWidth", "progress", "originX", "originY"],
     group: COMMON_PROPS
   };

package/dist/cli.js

@@ -355,7 +355,7 @@ var PROPS_BY_TYPE = {
   line: ["x1", "y1", "x2", "y2", "stroke", "strokeWidth", "opacity", "progress", ...FX_PROPS],
   text: [...COMMON_PROPS, "content", "contentDecimals", "contentThousands", "prefix", "suffix", "fontFamily", "fontSize", "fontWeight", "fill", "letterSpacing"],
   image: [...COMMON_PROPS, "src", "width", "height", "fit"],
-  video: [...COMMON_PROPS, "src", "width", "height", "fit", "start", "rate", "clipStart", "volume"],
+  video: [...COMMON_PROPS, "src", "width", "height", "fit", "start", "rate", "clipStart", "volume", "fadeIn", "pan"],
   path: [...COMMON_PROPS, "d", "fill", "stroke", "strokeWidth", "progress", "originX", "originY"],
   group: COMMON_PROPS
 };
@@ -592,6 +592,15 @@ function validateScene(ir) {
     if (cue.gain !== void 0 && cue.gain < 0) {
       problems.push(`audio.cues[${i}]: gain must be >= 0`);
     }
+    if (cue.fadeIn !== void 0 && cue.fadeIn < 0) {
+      problems.push(`audio.cues[${i}]: fadeIn must be >= 0`);
+    }
+    if (cue.fadeOut !== void 0 && cue.fadeOut < 0) {
+      problems.push(`audio.cues[${i}]: fadeOut must be >= 0`);
+    }
+    if (cue.pan !== void 0 && (cue.pan < -1 || cue.pan > 1)) {
+      problems.push(`audio.cues[${i}]: pan must be in [-1, 1] (-1 left \u2026 +1 right)`);
+    }
   }
   const duck = ir.audio?.bgm?.duck;
   if (typeof duck === "object" && duck !== null && duck.depth !== void 0 && (duck.depth < 0 || duck.depth > 1)) {
@@ -919,7 +928,7 @@ function collectClipAudio(ir, duration, warnings) {
           warnings.push(`video "${node.id}": start ${start.toFixed(2)}s past the scene end \u2014 audio dropped`);
           continue;
         }
-        out.push({ nodeId: node.id, src: node.props.src, start, rate: node.props.rate ?? 1, clipStart: node.props.clipStart ?? 0, gain });
+        out.push({ nodeId: node.id, src: node.props.src, start, rate: node.props.rate ?? 1, clipStart: node.props.clipStart ?? 0, gain, fadeIn: node.props.fadeIn ?? 0, pan: node.props.pan ?? 0 });
       }
       if (node.type === "group") walk(node.children);
     }
@@ -961,6 +970,9 @@ function resolveAudioPlan(compiled) {
       t,
       gain: cue.gain ?? 1,
       duration: cueDuration,
+      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 }
     });
   }
@@ -1038,6 +1050,9 @@ function resolveCompositionAudioPlan(comp) {
       t,
       gain: cue.gain ?? 1,
       duration: cueDuration,
+      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 }
     });
   }
@@ -1457,6 +1472,10 @@ function atempoChain(rate) {
   out.push(`atempo=${r.toFixed(4)}`);
   return out;
 }
+function panFilter(pan) {
+  const clamp = (v) => Math.max(0, Math.min(1, v)).toFixed(4);
+  return `pan=stereo|c0=${clamp(1 - pan)}*c0|c1=${clamp(1 + pan)}*c1`;
+}
 function buildFilterGraph(plan, inputs) {
   const lines = [];
   const mixIn = ["[anchor]"];
@@ -1485,7 +1504,14 @@ function buildFilterGraph(plan, inputs) {
   }
   plan.cues.forEach((cue, i) => {
     const delayMs = Math.round(cue.t * 1e3);
-    lines.push(`[${inputIndex}:a]${FORMAT},volume=${cue.gain},adelay=${delayMs}:all=1[c${i}]`);
+    const chain = [FORMAT, `volume=${cue.gain}`];
+    if (cue.fadeIn > 0) chain.push(`afade=t=in:st=0:d=${cue.fadeIn}`);
+    if (cue.fadeOut > 0) {
+      chain.push(`afade=t=out:st=${Math.max(0, cue.duration - cue.fadeOut).toFixed(3)}:d=${cue.fadeOut}`);
+    }
+    if (cue.pan !== 0) chain.push(panFilter(cue.pan));
+    chain.push(`adelay=${delayMs}:all=1`);
+    lines.push(`[${inputIndex}:a]${chain.join(",")}[c${i}]`);
     mixIn.push(`[c${i}]`);
     inputIndex++;
   });
@@ -1493,6 +1519,8 @@ function buildFilterGraph(plan, inputs) {
     const chain = [];
     if (audio.clipStart > 0) chain.push(`atrim=start=${audio.clipStart.toFixed(3)}`, "asetpts=PTS-STARTPTS");
     chain.push(...atempoChain(audio.rate), FORMAT, `volume=${audio.gain}`);
+    if (audio.fadeIn > 0) chain.push(`afade=t=in:st=0:d=${audio.fadeIn}`);
+    if (audio.pan !== 0) chain.push(panFilter(audio.pan));
     const delayMs = Math.round(audio.start * 1e3);
     if (delayMs > 0) chain.push(`adelay=${delayMs}:all=1`);
     lines.push(`[${inputIndex}:a]${chain.join(",")}[k${i}]`);

package/dist/diff.js

@@ -361,7 +361,7 @@ var PROPS_BY_TYPE = {
   line: ["x1", "y1", "x2", "y2", "stroke", "strokeWidth", "opacity", "progress", ...FX_PROPS],
   text: [...COMMON_PROPS, "content", "contentDecimals", "contentThousands", "prefix", "suffix", "fontFamily", "fontSize", "fontWeight", "fill", "letterSpacing"],
   image: [...COMMON_PROPS, "src", "width", "height", "fit"],
-  video: [...COMMON_PROPS, "src", "width", "height", "fit", "start", "rate", "clipStart", "volume"],
+  video: [...COMMON_PROPS, "src", "width", "height", "fit", "start", "rate", "clipStart", "volume", "fadeIn", "pan"],
   path: [...COMMON_PROPS, "d", "fill", "stroke", "strokeWidth", "progress", "originX", "originY"],
   group: COMMON_PROPS
 };
@@ -598,6 +598,15 @@ function validateScene(ir) {
     if (cue.gain !== void 0 && cue.gain < 0) {
       problems.push(`audio.cues[${i}]: gain must be >= 0`);
     }
+    if (cue.fadeIn !== void 0 && cue.fadeIn < 0) {
+      problems.push(`audio.cues[${i}]: fadeIn must be >= 0`);
+    }
+    if (cue.fadeOut !== void 0 && cue.fadeOut < 0) {
+      problems.push(`audio.cues[${i}]: fadeOut must be >= 0`);
+    }
+    if (cue.pan !== void 0 && (cue.pan < -1 || cue.pan > 1)) {
+      problems.push(`audio.cues[${i}]: pan must be in [-1, 1] (-1 left \u2026 +1 right)`);
+    }
   }
   const duck = ir.audio?.bgm?.duck;
   if (typeof duck === "object" && duck !== null && duck.depth !== void 0 && (duck.depth < 0 || duck.depth > 1)) {

package/dist/index.js

@@ -365,7 +365,7 @@ var PROPS_BY_TYPE = {
   line: ["x1", "y1", "x2", "y2", "stroke", "strokeWidth", "opacity", "progress", ...FX_PROPS],
   text: [...COMMON_PROPS, "content", "contentDecimals", "contentThousands", "prefix", "suffix", "fontFamily", "fontSize", "fontWeight", "fill", "letterSpacing"],
   image: [...COMMON_PROPS, "src", "width", "height", "fit"],
-  video: [...COMMON_PROPS, "src", "width", "height", "fit", "start", "rate", "clipStart", "volume"],
+  video: [...COMMON_PROPS, "src", "width", "height", "fit", "start", "rate", "clipStart", "volume", "fadeIn", "pan"],
   path: [...COMMON_PROPS, "d", "fill", "stroke", "strokeWidth", "progress", "originX", "originY"],
   group: COMMON_PROPS
 };
@@ -602,6 +602,15 @@ function validateScene(ir) {
     if (cue.gain !== void 0 && cue.gain < 0) {
       problems.push(`audio.cues[${i}]: gain must be >= 0`);
     }
+    if (cue.fadeIn !== void 0 && cue.fadeIn < 0) {
+      problems.push(`audio.cues[${i}]: fadeIn must be >= 0`);
+    }
+    if (cue.fadeOut !== void 0 && cue.fadeOut < 0) {
+      problems.push(`audio.cues[${i}]: fadeOut must be >= 0`);
+    }
+    if (cue.pan !== void 0 && (cue.pan < -1 || cue.pan > 1)) {
+      problems.push(`audio.cues[${i}]: pan must be in [-1, 1] (-1 left \u2026 +1 right)`);
+    }
   }
   const duck = ir.audio?.bgm?.duck;
   if (typeof duck === "object" && duck !== null && duck.depth !== void 0 && (duck.depth < 0 || duck.depth > 1)) {
@@ -2690,7 +2699,7 @@ function collectClipAudio(ir, duration, warnings) {
           warnings.push(`video "${node.id}": start ${start.toFixed(2)}s past the scene end \u2014 audio dropped`);
           continue;
         }
-        out.push({ nodeId: node.id, src: node.props.src, start, rate: node.props.rate ?? 1, clipStart: node.props.clipStart ?? 0, gain });
+        out.push({ nodeId: node.id, src: node.props.src, start, rate: node.props.rate ?? 1, clipStart: node.props.clipStart ?? 0, gain, fadeIn: node.props.fadeIn ?? 0, pan: node.props.pan ?? 0 });
       }
       if (node.type === "group") walk(node.children);
     }
@@ -2732,6 +2741,9 @@ function resolveAudioPlan(compiled) {
       t,
       gain: cue.gain ?? 1,
       duration: cueDuration,
+      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 }
     });
   }
@@ -2809,6 +2821,9 @@ function resolveCompositionAudioPlan(comp) {
       t,
       gain: cue.gain ?? 1,
       duration: cueDuration,
+      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 }
     });
   }

package/dist/labels.js

@@ -349,7 +349,7 @@ var PROPS_BY_TYPE = {
   line: ["x1", "y1", "x2", "y2", "stroke", "strokeWidth", "opacity", "progress", ...FX_PROPS],
   text: [...COMMON_PROPS, "content", "contentDecimals", "contentThousands", "prefix", "suffix", "fontFamily", "fontSize", "fontWeight", "fill", "letterSpacing"],
   image: [...COMMON_PROPS, "src", "width", "height", "fit"],
-  video: [...COMMON_PROPS, "src", "width", "height", "fit", "start", "rate", "clipStart", "volume"],
+  video: [...COMMON_PROPS, "src", "width", "height", "fit", "start", "rate", "clipStart", "volume", "fadeIn", "pan"],
   path: [...COMMON_PROPS, "d", "fill", "stroke", "strokeWidth", "progress", "originX", "originY"],
   group: COMMON_PROPS
 };
@@ -586,6 +586,15 @@ function validateScene(ir) {
     if (cue.gain !== void 0 && cue.gain < 0) {
       problems.push(`audio.cues[${i}]: gain must be >= 0`);
     }
+    if (cue.fadeIn !== void 0 && cue.fadeIn < 0) {
+      problems.push(`audio.cues[${i}]: fadeIn must be >= 0`);
+    }
+    if (cue.fadeOut !== void 0 && cue.fadeOut < 0) {
+      problems.push(`audio.cues[${i}]: fadeOut must be >= 0`);
+    }
+    if (cue.pan !== void 0 && (cue.pan < -1 || cue.pan > 1)) {
+      problems.push(`audio.cues[${i}]: pan must be in [-1, 1] (-1 left \u2026 +1 right)`);
+    }
   }
   const duck = ir.audio?.bgm?.duck;
   if (typeof duck === "object" && duck !== null && duck.depth !== void 0 && (duck.depth < 0 || duck.depth > 1)) {

package/dist/trace-cli.js

@@ -14,7 +14,7 @@ var PROPS_BY_TYPE = {
   line: ["x1", "y1", "x2", "y2", "stroke", "strokeWidth", "opacity", "progress", ...FX_PROPS],
   text: [...COMMON_PROPS, "content", "contentDecimals", "contentThousands", "prefix", "suffix", "fontFamily", "fontSize", "fontWeight", "fill", "letterSpacing"],
   image: [...COMMON_PROPS, "src", "width", "height", "fit"],
-  video: [...COMMON_PROPS, "src", "width", "height", "fit", "start", "rate", "clipStart", "volume"],
+  video: [...COMMON_PROPS, "src", "width", "height", "fit", "start", "rate", "clipStart", "volume", "fadeIn", "pan"],
   path: [...COMMON_PROPS, "d", "fill", "stroke", "strokeWidth", "progress", "originX", "originY"],
   group: COMMON_PROPS
 };

package/dist/types/audio.d.ts

@@ -15,6 +15,12 @@ export interface ResolvedCue {
     t: number;
     gain: number;
     duration: number;
+    /** Fade in over N seconds from the cue start (0 = none). */
+    fadeIn: number;
+    /** Fade out over N seconds before the cue end (0 = none). */
+    fadeOut: number;
+    /** Stereo balance: -1 left … 0 centre … +1 right. */
+    pan: number;
     source: {
         kind: "sfx";
         name: SfxName;
@@ -36,6 +42,10 @@ export interface ClipAudio {
     clipStart: number;
     /** Linear gain. */
     gain: number;
+    /** Fade in over N seconds from the clip's `start` (0 = none). */
+    fadeIn: number;
+    /** Stereo balance: -1 left … 0 centre … +1 right. */
+    pan: number;
 }
 export interface AudioPlan {
     duration: number;

package/dist/types/ir.d.ts

@@ -256,6 +256,10 @@ export interface VideoProps extends BaseProps {
      * (trimmed from `clipStart`, sped by `rate`). Default 1; `0` mutes the clip.
      */
     volume?: number;
+    /** Fade the clip audio in over N seconds from `start` (default 0 = hard in). */
+    fadeIn?: number;
+    /** Stereo balance for the clip audio: -1 full left, 0 centre, +1 full right. */
+    pan?: number;
 }
 export type NodeIR = {
     type: "rect";
@@ -420,6 +424,12 @@ export interface AudioCueIR {
     file?: string;
     /** Linear gain, default 1. */
     gain?: number;
+    /** Fade the cue in over N seconds from its start (default 0 = hard in). */
+    fadeIn?: number;
+    /** Fade the cue out over N seconds before its end (default 0 = hard out). */
+    fadeOut?: number;
+    /** Stereo balance: -1 full left, 0 centre (default), +1 full right. */
+    pan?: number;
     /** Synth parameter overrides (seed, duration, …) — numbers only. */
     params?: Record<string, number>;
 }

package/guides/edsl-guide.md

@@ -510,15 +510,19 @@ Label-anchored sound design — cues follow retiming and regeneration:
 audio: {
   bgm: { synth: "ambient-pad", gain: 0.3, fadeIn: 1, fadeOut: 2, duck: { depth: 0.5 } },
   cues: [
-    { at: "enter", sfx: "whoosh", gain: 0.8 },          // anchored to a timeline label
-    { at: "enter", offset: 0.2, sfx: "pop" },
-    { at: 5.0, file: "keypress-001.wav", gain: 0.5 },   // absolute seconds; file from assets/sfx/
+    { at: "enter", sfx: "whoosh", gain: 0.8, pan: -0.6 },     // anchored to a label; panned left
+    { at: "enter", offset: 0.2, sfx: "pop", fadeIn: 0.05, fadeOut: 0.1 },
+    { at: 5.0, file: "keypress-001.wav", gain: 0.5 },         // absolute seconds; file from assets/sfx/
   ],
 }
 ```
 
 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`).
 
 ## Rules
 

package/package.json

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