reframe-video 0.6.6 → 0.6.7

package/dist/index.js

@@ -357,7 +357,7 @@ var PROPS_BY_TYPE = {
   line: ["x1", "y1", "x2", "y2", "stroke", "strokeWidth", "opacity", "progress", ...FX_PROPS],
   text: [...COMMON_PROPS, "content", "contentDecimals", "contentThousands", "fontFamily", "fontSize", "fontWeight", "fill", "letterSpacing"],
   image: [...COMMON_PROPS, "src", "width", "height", "fit"],
-  video: [...COMMON_PROPS, "src", "width", "height", "fit", "start", "rate", "clipStart"],
+  video: [...COMMON_PROPS, "src", "width", "height", "fit", "start", "rate", "clipStart", "volume"],
   path: [...COMMON_PROPS, "d", "fill", "stroke", "strokeWidth", "progress", "originX", "originY"],
   group: COMMON_PROPS
 };
@@ -2628,11 +2628,34 @@ var SFX_DURATION = {
   thud: 0.25
 };
 var FILE_CUE_DURATION = 0.4;
+function collectClipAudio(ir, duration, warnings) {
+  const out = [];
+  const walk = (nodes) => {
+    for (const node of nodes) {
+      if (node.type === "video") {
+        const gain = node.props.volume ?? 1;
+        const start = node.props.start ?? 0;
+        if (gain <= 0) continue;
+        if (start >= duration) {
+          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 });
+      }
+      if (node.type === "group") walk(node.children);
+    }
+  };
+  walk(ir.nodes);
+  return out;
+}
 function resolveAudioPlan(compiled) {
   const audio = compiled.ir.audio;
-  if (!audio || !audio.bgm && (audio.cues ?? []).length === 0) return null;
   const warnings = [];
   const duration = compiled.duration;
+  const clipAudio = collectClipAudio(compiled.ir, duration, warnings);
+  if (!audio || !audio.bgm && (audio.cues ?? []).length === 0) {
+    return clipAudio.length === 0 ? null : { duration, bgm: null, cues: [], duckWindows: [], clipAudio, warnings };
+  }
   const cues = [];
   for (const [index, cue] of (audio.cues ?? []).entries()) {
     let anchor;
@@ -2668,6 +2691,7 @@ function resolveAudioPlan(compiled) {
     bgm: resolveBgm(audio.bgm),
     cues,
     duckWindows: mergeDuckWindows(cues, duration),
+    clipAudio,
     warnings
   };
 }
@@ -2701,6 +2725,7 @@ function resolveCompositionAudioPlan(comp) {
   const duration = comp.duration;
   const warnings = [];
   const cues = [];
+  const clipAudio = [];
   for (const placement of comp.scenes) {
     const plan = resolveAudioPlan(placement.compiled);
     if (!plan) continue;
@@ -2713,6 +2738,11 @@ function resolveCompositionAudioPlan(comp) {
       if (t >= duration) continue;
       cues.push({ ...cue, t });
     }
+    for (const clip of plan.clipAudio) {
+      const start = clip.start + placement.start;
+      if (start >= duration) continue;
+      clipAudio.push({ ...clip, start });
+    }
   }
   for (const [index, cue] of (audio?.cues ?? []).entries()) {
     if (typeof cue.at !== "number") {
@@ -2732,13 +2762,14 @@ function resolveCompositionAudioPlan(comp) {
       source: cue.sfx ? { kind: "sfx", name: cue.sfx, params: cue.params ?? {} } : { kind: "file", path: cue.file }
     });
   }
-  if (!audio?.bgm && cues.length === 0) return null;
+  if (!audio?.bgm && cues.length === 0 && clipAudio.length === 0) return null;
   cues.sort((a, b) => a.t - b.t);
   return {
     duration,
     bgm: resolveBgm(audio?.bgm),
     cues,
     duckWindows: mergeDuckWindows(cues, duration),
+    clipAudio,
     warnings
   };
 }

package/dist/labels.js

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

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", "fontFamily", "fontSize", "fontWeight", "fill", "letterSpacing"],
   image: [...COMMON_PROPS, "src", "width", "height", "fit"],
-  video: [...COMMON_PROPS, "src", "width", "height", "fit", "start", "rate", "clipStart"],
+  video: [...COMMON_PROPS, "src", "width", "height", "fit", "start", "rate", "clipStart", "volume"],
   path: [...COMMON_PROPS, "d", "fill", "stroke", "strokeWidth", "progress", "originX", "originY"],
   group: COMMON_PROPS
 };

package/dist/types/audio.d.ts

@@ -24,6 +24,19 @@ export interface ResolvedCue {
         path: string;
     };
 }
+/** A video node's own audio track, placed on the scene clock. */
+export interface ClipAudio {
+    nodeId: string;
+    src: string;
+    /** Scene-time (s) the clip's audio begins. */
+    start: number;
+    /** Playback speed (atempo). */
+    rate: number;
+    /** Source in-point (s) — audio is trimmed to begin here. */
+    clipStart: number;
+    /** Linear gain. */
+    gain: number;
+}
 export interface AudioPlan {
     duration: number;
     bgm: {
@@ -49,6 +62,8 @@ export interface AudioPlan {
         t0: number;
         t1: number;
     }[];
+    /** Video clip soundtracks to mux in (a clip with no audio stream is skipped at render). */
+    clipAudio: ClipAudio[];
     warnings: string[];
 }
 export declare function resolveAudioPlan(compiled: CompiledScene): AudioPlan | null;

package/dist/types/index.d.ts

@@ -17,7 +17,7 @@ export { characterPreset, CHARACTER_PRESET_NAMES, type CharacterPresetName, type
 export { figure, type FigureStyle, type FigureOpts, type FigurePalette } from "./figure.js";
 export { splitText, textIn, textLoop, textOut, textTypeCues, type SplitOpts, type Glyph, type TextBlock, type FontWeight, type TextInName, type TextLoopName, type TextOutName, type TextLoopOpts, type TextOutOpts, type TypeCueOpts, } from "./textFx.js";
 export { motionOp, motionOpLabel, MOTION_OPS, type MotionOpName, type MotionOpOpts, type MotionOpResult } from "./motionOps.js";
-export { resolveAudioPlan, resolveCompositionAudioPlan, SFX_DURATION, type AudioPlan, type ResolvedCue, } from "./audio.js";
+export { resolveAudioPlan, resolveCompositionAudioPlan, SFX_DURATION, type AudioPlan, type ResolvedCue, type ClipAudio, } from "./audio.js";
 export { evaluate, sampleProp, nodeParentMatrix, type DisplayList, type DisplayOp, type Mat2D, type ClipRegion, type TextAlign, type TextBaseline, } from "./evaluate.js";
 export { resolveEase, lerpValue, isColor, EASE_NAMES } from "./interpolate.js";
 export { sampleBehavior } from "./behaviors.js";

package/dist/types/ir.d.ts

@@ -208,6 +208,11 @@ export interface VideoProps extends BaseProps {
     rate?: number;
     /** Source in-point (seconds) shown at `start`. Default 0. */
     clipStart?: number;
+    /**
+     * Linear gain for the clip's own audio track, muxed into the output at `start`
+     * (trimmed from `clipStart`, sped by `rate`). Default 1; `0` mutes the clip.
+     */
+    volume?: number;
 }
 export type NodeIR = {
     type: "rect";

package/guides/edsl-guide.md

@@ -324,19 +324,23 @@ shows the source frame at `clipStart + max(0, t - start) * rate`.
 
 ```ts
 video({ id: "clip", src: "shot.mp4", x: 960, y: 540, width: 1920, height: 1080,
-        anchor: "center", fit: "cover", start: 0, rate: 1, clipStart: 0 })
+        anchor: "center", fit: "cover", start: 0, rate: 1, clipStart: 0, volume: 1 })
 tween("clip", { scale: 1.08 }, { duration: 5 })  // transform composes with playback (Ken Burns)
 ```
 
 - Props: `src` (mp4 / mov / webm / m4v / mkv, absolute or scene-relative), `width`/`height`,
   `fit` (`"cover"` like the image node), `start` (scene-time playback begins), `rate`
-  (speed), `clipStart` (source in-point s). Transform/opacity/effects compose as usual.
+  (speed), `clipStart` (source in-point s), `volume` (clip-audio gain, default 1; `0` mutes).
+  Transform/opacity/effects compose as usual.
 - **Deterministic by frame extraction**: render-cli runs `ffmpeg -vf fps=<sceneFps>` to pull
   the clip's frames, and the renderer draws frame `round(t·fps)` — no live `<video>` seek, so
   it stays byte-identical (same machine).
-- **v1 limitations**: visual-only (the clip's own audio is not muxed — use `scene.audio`);
-  all frames are pre-decoded so keep clips short (≤~5s); like images, not rendered in
-  `reframe player` / artifacts (mp4 only). See `examples/scenes/video-demo.ts`.
+- **Clip audio**: the clip's own audio track is muxed into the output, placed at `start`
+  (trimmed from `clipStart`, sped by `rate`, scaled by `volume`), mixed with `scene.audio`.
+  A clip with no audio stream is skipped; set `volume: 0` to drop a clip's sound.
+- **Limitations**: all frames are pre-decoded so keep clips short (≤~5s); like images, video
+  sources are not rendered in `reframe player` / artifacts (mp4 only). See
+  `examples/scenes/video-demo.ts`.
 
 ## Cursor (UI demos)
 

package/package.json

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