reframe-video 0.6.7 → 0.6.8

package/dist/browserEntry.js

@@ -1104,11 +1104,26 @@
   var canvas = null;
   var images = /* @__PURE__ */ new Map();
   var videoFrames = /* @__PURE__ */ new Map();
-  var decode = (dataUrl) => {
+  async function decode(dataUrl, label = "") {
     const img = new Image();
     img.src = dataUrl;
-    return img.decode().then(() => img);
-  };
+    try {
+      await img.decode();
+      return img;
+    } catch (e) {
+      throw new Error(`decode failed for ${label} (len=${dataUrl.length}): ${String(e)}`);
+    }
+  }
+  async function decodeAll(urls, label) {
+    const out = new Array(urls.length);
+    const LIMIT = 8;
+    for (let base = 0; base < urls.length; base += LIMIT) {
+      const batch = urls.slice(base, base + LIMIT);
+      const decoded = await Promise.all(batch.map((u, j) => decode(u, `${label}#${base + j}`)));
+      for (let j = 0; j < decoded.length; j++) out[base + j] = decoded[j];
+    }
+    return out;
+  }
   var videos = {
     frame(src, index) {
       const frames = videoFrames.get(src);
@@ -1126,14 +1141,14 @@
       document.body.appendChild(canvas);
       ctx = canvas.getContext("2d", { willReadFrequently: true });
       if (!ctx) throw new Error("could not create 2d context");
-      await Promise.all([
-        ...Object.entries(assets).map(async ([src, dataUrl]) => {
-          images.set(src, await decode(dataUrl));
-        }),
-        ...Object.entries(videoAssets).map(async ([src, frames]) => {
-          videoFrames.set(src, await Promise.all(frames.map(decode)));
+      await Promise.all(
+        Object.entries(assets).map(async ([src, dataUrl]) => {
+          images.set(src, await decode(dataUrl, `image ${src}`));
         })
-      ]);
+      );
+      for (const [src, frames] of Object.entries(videoAssets)) {
+        videoFrames.set(src, await decodeAll(frames, `video ${src}`));
+      }
       return { duration: compiled.duration, fps: ir.fps ?? 30 };
     },
     renderFrame(t) {

package/dist/index.js

@@ -1020,6 +1020,8 @@ function dropShadow(color, blur = 24, x = 0, y = 12) {
 }
 
 // ../core/src/montage.ts
+var VIDEO_EXT = /\.(mp4|mov|webm|m4v|mkv)$/i;
+var isVideoSrc = (src) => VIDEO_EXT.test(src);
 function makeRng(seed) {
   let a = seed >>> 0 || 2654435769;
   return () => {
@@ -1043,10 +1045,13 @@ function photoMontage(images, opts = {}) {
   const cy = H / 2;
   const nodes = [];
   const shots = [];
+  let clock = 0;
   slides.forEach((slide, i) => {
     const nid = `${id}-${i}`;
     const slideHold = Math.max(0.5, slide.hold ?? hold);
     const transition = Math.min(opts.transition ?? 0.6, slideHold * 0.9);
+    const shotStart = clock;
+    clock += slideHold;
     const kind = slide.ken ?? ["in", "out", "pan"][Math.floor(rand2() * 3)] ?? "in";
     const angle = rand2() * Math.PI * 2;
     const panFrac = 0.4 + rand2() * 0.35;
@@ -1070,19 +1075,9 @@ function photoMontage(images, opts = {}) {
       yA = cy + dy * (kA - 1) * (H / 2) * panFrac;
       yB = cy + dy * (kB - 1) * (H / 2) * panFrac;
     }
+    const box = { id: nid, src: slide.src, x: xA, y: yA, width: W, height: H, anchor: "center", fit: "cover", scale: kA, opacity: i === 0 ? 1 : 0 };
     nodes.push(
-      image({
-        id: nid,
-        src: slide.src,
-        x: xA,
-        y: yA,
-        width: W,
-        height: H,
-        anchor: "center",
-        fit: "cover",
-        scale: kA,
-        opacity: i === 0 ? 1 : 0
-      })
+      isVideoSrc(slide.src) ? video({ ...box, start: shotStart, volume: slide.volume ?? 0 }) : image(box)
     );
     const ken = tween(
       nid,
@@ -1134,6 +1129,7 @@ function photoMontage(images, opts = {}) {
   }
   return { nodes, timeline: beat("montage", { nodes: nodes.map((n3) => n3.id) }, [seq(...shots)]) };
 }
+var videoMontage = photoMontage;
 
 // ../core/src/presets.ts
 var PRESET_NAMES = [
@@ -3488,6 +3484,7 @@ export {
   validateComposition,
   validateScene,
   video,
+  videoMontage,
   wait,
   wiggle
 };

package/dist/types/index.d.ts

@@ -8,7 +8,7 @@ export { pathPoint, pathTangentAngle, type Pt } from "./path.js";
 export { cameraTo, cameraMatrix, CAMERA_ID, CAMERA_PROPS } from "./camera.js";
 export { linearGradient, radialGradient, conicGradient, isGradient } from "./gradient.js";
 export { glow, dropShadow } from "./effects.js";
-export { photoMontage, type MontageImage, type MontageOpts, type MontageResult, type KenBurns } from "./montage.js";
+export { photoMontage, videoMontage, type MontageImage, type MontageOpts, type MontageResult, type KenBurns } from "./montage.js";
 export { motionPreset, PRESET_NAMES, type PresetName, type PresetRig, type PresetOpts } from "./presets.js";
 export { devicePreset, deviceScreen, deviceScreenCenter, deviceBounds, deviceScreenPoint, DEVICE_PRESET_NAMES, type DevicePresetName, type DevicePresetOpts } from "./devicePreset.js";
 export { cursor, cursorTo, cursorPath, cursorClick, cursorDouble, type CursorStyle, type CursorOpts, type CursorToOpts, type CursorPathOpts, type CursorClickOpts } from "./cursor.js";

package/dist/types/montage.d.ts

@@ -1,9 +1,10 @@
 /**
- * Photo montage — a SEEDED GENERATOR that turns a list of images into a polished
- * slideshow: layered image nodes + a retimable `beat` that crossfades between
- * slides and pans/zooms each (Ken Burns), with an optional cinematic grade
- * (vignette + bottom scrim) built from gradients + blend modes. The photo analog
- * of `motionPreset` / `splitText`.
+ * Photo/video montage — a SEEDED GENERATOR that turns a list of shots (images AND
+ * video clips, mixed freely) into a polished slideshow: layered image/video nodes +
+ * a retimable `beat` that crossfades between shots and pans/zooms each (Ken Burns),
+ * with an optional cinematic grade (vignette + bottom scrim) built from gradients +
+ * blend modes. A video src plays as a clip for its `hold`. The photo analog of
+ * `motionPreset` / `splitText`. (`videoMontage` is the same generator, by intent.)
  *
  * Pure and deterministic: the per-slide Ken Burns direction / framing is chosen by
  * a seeded PRNG (mulberry32) — same (images, opts) → identical IR; a different
@@ -16,11 +17,16 @@
  */
 import type { NodeIR, TimelineIR } from "./ir.js";
 export type KenBurns = "in" | "out" | "pan";
-/** One slide: a bare src, or a src with per-slide overrides. */
+/**
+ * One shot: a bare src, or a src with per-shot overrides. A video src plays as a
+ * clip for its `hold`; `volume` (video shots only) is the clip-audio gain — default
+ * 0 (muted) in a montage to avoid stacking soundtracks; set it per shot to include.
+ */
 export type MontageImage = string | {
     src: string;
     hold?: number;
     ken?: KenBurns;
+    volume?: number;
 };
 export interface MontageOpts {
     /** Node-id prefix → stable regen addresses `${id}-${i}`. Default "shot". */
@@ -54,3 +60,10 @@ export interface MontageResult {
  *   scene({ size, nodes: [...m.nodes, ...titles], timeline: seq(m.timeline) });
  */
 export declare function photoMontage(images: MontageImage[], opts?: MontageOpts): MontageResult;
+/**
+ * Same as `photoMontage`, named for clip-driven montages — shots may be images or
+ * video clips (mixed freely; a video src plays for its `hold`, muted by default).
+ *
+ *   videoMontage(["intro.jpg", "shot-a.mp4", { src: "shot-b.mp4", volume: 1 }], { seed: 3 })
+ */
+export declare const videoMontage: typeof photoMontage;

package/guides/edsl-guide.md

@@ -291,14 +291,16 @@ const T = splitText("MOTION IS DATA", { id: "t", x: 960, y: 470, fontSize: 130 }
 Every effect is seeded (same `seed` → identical) and pure keyframes. To time a
 `textLoop` window, add up the `textIn` beat length (≈ `(n-1)·stagger + glyphDur`).
 
-## Photo montage (`photoMontage`)
+## Photo / video montage (`photoMontage` / `videoMontage`)
 
-Turn a list of images into a polished slideshow — crossfades + seeded Ken Burns
+Turn a list of shots into a polished slideshow — crossfades + seeded Ken Burns
 (pan/zoom) + an optional cinematic grade (vignette + bottom scrim via gradients +
-blend) — without hand-wiring each move. The photo analog of `motionPreset`.
+blend) — without hand-wiring each move. Shots may be images AND video clips, mixed
+freely (a video src, by extension, plays as a clip for its `hold`). `videoMontage`
+is the same generator, named for clip-driven cuts. The photo analog of `motionPreset`.
 
 ```ts
-const m = photoMontage(["a.jpg", "b.jpg", "c.jpg"], {
+const m = videoMontage(["a.jpg", { src: "b.mp4", volume: 1 }, "c.jpg"], {
   id: "shot", size: { width: 1920, height: 1080 },
   hold: 3.4, transition: 0.7, zoom: 1.16, seed: 7,
 });
@@ -306,16 +308,20 @@ scene({ size, nodes: [...m.nodes, ...titles], timeline: par(m.timeline, titleTra
 ```
 
 - Returns `{ nodes, timeline }` (like `splitText` owns its glyph nodes). `nodes` are
-  the stacked image layers (+ `${id}-vignette` / `${id}-scrim` grade overlays);
+  the stacked image/video layers (+ `${id}-vignette` / `${id}-scrim` grade overlays);
   `timeline` is a retimable `beat("montage", …)`. Stable addresses: `${id}-${i}`,
   labels `shot-${i}` / `cross-${i}`.
-- **Any-aspect photos work** — each layer uses `fit: "cover"`, so the renderer
-  crops to fill the frame at the image's aspect (no pre-cropping, no distortion).
+- **Any-aspect media works** — each layer uses `fit: "cover"`, so the renderer
+  crops to fill the frame at the source's aspect (no pre-cropping, no distortion).
   The Ken Burns keeps `scale ≥ 1` with the pan bounded to its slack, so an edge is
   never revealed.
-- Per-slide overrides: `{ src, hold?, ken? }` where `ken` is `"in" | "out" | "pan"`.
-- Seeded + pure (same `(images, opts)` → identical IR). Note: image-node sources do
-  not render in `reframe player` / artifacts — montage ships as mp4.
+- Per-shot overrides: `{ src, hold?, ken?, volume? }` where `ken` is `"in" | "out" |
+  "pan"`. A **video** shot plays as a clip from its slot's start; its audio is **muted
+  by default** in a montage — set `volume` (per shot) to include it, or add a `scene.audio`
+  bed.
+- Seeded + pure (same `(shots, opts)` → identical IR). Note: image/video sources do
+  not render in `reframe player` / artifacts — montage ships as mp4. See
+  `examples/scenes/video-montage.ts`.
 
 ## Video clips (`video`)
 

package/package.json

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