reframe-video 0.6.5 → 0.6.6

package/dist/index.js

@@ -357,6 +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"],
   path: [...COMMON_PROPS, "d", "fill", "stroke", "strokeWidth", "progress", "originX", "originY"],
   group: COMMON_PROPS
 };
@@ -654,6 +655,10 @@ function image(props) {
   const { id, ...rest } = props;
   return { type: "image", id, props: rest };
 }
+function video(props) {
+  const { id, ...rest } = props;
+  return { type: "video", id, props: rest };
+}
 function path(props) {
   const { id, ...rest } = props;
   return { type: "path", id, props: rest };
@@ -3187,6 +3192,33 @@ function evaluate(compiled, t) {
         });
         return;
       }
+      case "video": {
+        const width = num(id, "width", node.props.width);
+        const height = num(id, "height", node.props.height);
+        const [ax, ay] = ANCHOR_FACTORS[node.props.anchor ?? "top-left"];
+        const fps = compiled.ir.fps ?? 30;
+        const start = node.props.start ?? 0;
+        const rate = node.props.rate ?? 1;
+        const clipStart = node.props.clipStart ?? 0;
+        const srcT = clipStart + Math.max(0, t - start) * rate;
+        const frame = Math.max(0, Math.round(srcT * fps));
+        ops.push({
+          type: "video",
+          id,
+          transform: matrix,
+          opacity,
+          src: str(id, "src", node.props.src),
+          width,
+          height,
+          offsetX: -width * ax,
+          offsetY: -height * ay,
+          frame,
+          ...node.props.fit && node.props.fit !== "fill" ? { fit: node.props.fit } : {},
+          ...fx,
+          ...clipSpread
+        });
+        return;
+      }
       case "path": {
         const ox = num(id, "originX", node.props.originX ?? 0);
         const oy = num(id, "originY", node.props.originY ?? 0);
@@ -3255,13 +3287,13 @@ function evaluate(compiled, t) {
 }
 
 // ../core/src/assets.ts
-function collectImageSrcs(ir) {
+function collectSrcs(ir, type) {
   const srcs = /* @__PURE__ */ new Set();
-  const imageIds = /* @__PURE__ */ new Set();
+  const ids = /* @__PURE__ */ new Set();
   const walkNodes = (nodes) => {
     for (const node of nodes) {
-      if (node.type === "image") {
-        imageIds.add(node.id);
+      if (node.type === type) {
+        ids.add(node.id);
         srcs.add(node.props.src);
       }
       if (node.type === "group") walkNodes(node.children);
@@ -3270,14 +3302,14 @@ function collectImageSrcs(ir) {
   walkNodes(ir.nodes);
   for (const overrides of Object.values(ir.states ?? {})) {
     for (const [nodeId, props] of Object.entries(overrides)) {
-      if (imageIds.has(nodeId) && typeof props.src === "string") srcs.add(props.src);
+      if (ids.has(nodeId) && typeof props.src === "string") srcs.add(props.src);
     }
   }
   const walkTimeline = (step) => {
     if (!step) return;
     if (step.kind === "seq" || step.kind === "par" || step.kind === "stagger") {
       for (const child of step.children) walkTimeline(child);
-    } else if (step.kind === "tween" && imageIds.has(step.target)) {
+    } else if (step.kind === "tween" && ids.has(step.target)) {
       const src = step.props.src;
       if (typeof src === "string") srcs.add(src);
     }
@@ -3285,6 +3317,12 @@ function collectImageSrcs(ir) {
   walkTimeline(ir.timeline);
   return [...srcs];
 }
+function collectImageSrcs(ir) {
+  return collectSrcs(ir, "image");
+}
+function collectVideoSrcs(ir) {
+  return collectSrcs(ir, "video");
+}
 
 // ../core/src/motion.ts
 var EASE_BY_CLASS = {
@@ -3351,6 +3389,7 @@ export {
   cameraTo,
   characterPreset,
   collectImageSrcs,
+  collectVideoSrcs,
   compileComposition,
   compileScene,
   composeScene,
@@ -3417,6 +3456,7 @@ export {
   tween,
   validateComposition,
   validateScene,
+  video,
   wait,
   wiggle
 };

package/dist/labels.js

@@ -341,6 +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"],
   path: [...COMMON_PROPS, "d", "fill", "stroke", "strokeWidth", "progress", "originX", "originY"],
   group: COMMON_PROPS
 };

package/dist/renderer-canvas.js

@@ -25,7 +25,7 @@ function resolvePaint(ctx, paint, box) {
   for (const s of paint.stops) g.addColorStop(Math.max(0, Math.min(1, s.offset)), s.color);
   return g;
 }
-function renderFrame(ctx, compiled, t, images) {
+function renderFrame(ctx, compiled, t, images, videos) {
   const { size, background } = compiled.ir;
   ctx.setTransform(1, 0, 0, 1, 0, 0);
   ctx.clearRect(0, 0, size.width, size.height);
@@ -33,9 +33,9 @@ function renderFrame(ctx, compiled, t, images) {
     ctx.fillStyle = background;
     ctx.fillRect(0, 0, size.width, size.height);
   }
-  drawDisplayList(ctx, evaluate(compiled, t), images);
+  drawDisplayList(ctx, evaluate(compiled, t), images, videos);
 }
-function drawDisplayList(ctx, ops, images) {
+function drawDisplayList(ctx, ops, images, videos) {
   for (const op of ops) {
     ctx.save();
     if (op.clips) {
@@ -117,28 +117,11 @@ function drawDisplayList(ctx, ops, images) {
         break;
       }
       case "image": {
-        const img = images?.get(op.src);
-        if (img) {
-          if (op.fit === "cover") {
-            const [iw, ih] = intrinsicSize(img);
-            const { sx, sy, sw, sh } = coverRect(iw, ih, op.width, op.height);
-            ctx.drawImage(img, sx, sy, sw, sh, op.offsetX, op.offsetY, op.width, op.height);
-          } else {
-            ctx.drawImage(img, op.offsetX, op.offsetY, op.width, op.height);
-          }
-        } else {
-          ctx.fillStyle = "#2A2A30";
-          ctx.fillRect(op.offsetX, op.offsetY, op.width, op.height);
-          ctx.strokeStyle = "#FF00FF";
-          ctx.lineWidth = 2;
-          ctx.strokeRect(op.offsetX, op.offsetY, op.width, op.height);
-          ctx.beginPath();
-          ctx.moveTo(op.offsetX, op.offsetY);
-          ctx.lineTo(op.offsetX + op.width, op.offsetY + op.height);
-          ctx.moveTo(op.offsetX + op.width, op.offsetY);
-          ctx.lineTo(op.offsetX, op.offsetY + op.height);
-          ctx.stroke();
-        }
+        drawRaster(ctx, images?.get(op.src), op);
+        break;
+      }
+      case "video": {
+        drawRaster(ctx, videos?.frame(op.src, op.frame), op);
         break;
       }
       case "path": {
@@ -193,6 +176,29 @@ function intrinsicSize(img) {
   const a = img;
   return [a.naturalWidth || a.width || 0, a.naturalHeight || a.height || 0];
 }
+function drawRaster(ctx, img, op) {
+  if (img) {
+    if (op.fit === "cover") {
+      const [iw, ih] = intrinsicSize(img);
+      const { sx, sy, sw, sh } = coverRect(iw, ih, op.width, op.height);
+      ctx.drawImage(img, sx, sy, sw, sh, op.offsetX, op.offsetY, op.width, op.height);
+    } else {
+      ctx.drawImage(img, op.offsetX, op.offsetY, op.width, op.height);
+    }
+    return;
+  }
+  ctx.fillStyle = "#2A2A30";
+  ctx.fillRect(op.offsetX, op.offsetY, op.width, op.height);
+  ctx.strokeStyle = "#FF00FF";
+  ctx.lineWidth = 2;
+  ctx.strokeRect(op.offsetX, op.offsetY, op.width, op.height);
+  ctx.beginPath();
+  ctx.moveTo(op.offsetX, op.offsetY);
+  ctx.lineTo(op.offsetX + op.width, op.offsetY + op.height);
+  ctx.moveTo(op.offsetX + op.width, op.offsetY);
+  ctx.lineTo(op.offsetX, op.offsetY + op.height);
+  ctx.stroke();
+}
 function quoteFamily(family) {
   return family.includes(" ") && !family.includes('"') ? `"${family}"` : family;
 }

package/dist/trace-cli.js

@@ -14,6 +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"],
   path: [...COMMON_PROPS, "d", "fill", "stroke", "strokeWidth", "progress", "originX", "originY"],
   group: COMMON_PROPS
 };

package/dist/types/assets.d.ts

@@ -1,5 +1,5 @@
 /**
- * Asset discovery shared by every consumer that must preload images before
+ * Asset discovery shared by every consumer that must preload media before
  * rendering (the capture page and the preview). One walker means the two
  * sides can never disagree about which srcs a scene uses — including srcs
  * introduced only mid-scene by a state override or a tween.
@@ -7,3 +7,5 @@
 import type { SceneIR } from "./ir.js";
 /** All image srcs a scene can ever display, deduped, in discovery order. */
 export declare function collectImageSrcs(ir: SceneIR): string[];
+/** All video srcs a scene can ever display, deduped, in discovery order. */
+export declare function collectVideoSrcs(ir: SceneIR): string[];

package/dist/types/dsl.d.ts

@@ -2,7 +2,7 @@
  * The eDSL surface: thin factories that build plain IR objects.
  * `scene()` validates and returns the IR — the return value is the document.
  */
-import type { AudioIR, BehaviorIR, CameraIR, CompositionIR, CompositionSceneEntry, Ease, EllipseProps, GroupProps, ImageProps, LineProps, NodeIR, PathProps, PropValue, RectProps, SceneIR, Size, StateOverride, TextProps, TimelineIR } from "./ir.js";
+import type { AudioIR, BehaviorIR, CameraIR, CompositionIR, CompositionSceneEntry, Ease, EllipseProps, GroupProps, ImageProps, LineProps, NodeIR, PathProps, PropValue, RectProps, SceneIR, Size, StateOverride, TextProps, TimelineIR, VideoProps } from "./ir.js";
 export interface SceneInput {
     id: string;
     size: Size;
@@ -42,6 +42,9 @@ export declare function text(props: {
 export declare function image(props: {
     id: string;
 } & ImageProps): NodeIR;
+export declare function video(props: {
+    id: string;
+} & VideoProps): NodeIR;
 export declare function path(props: {
     id: string;
 } & PathProps): NodeIR;

package/dist/types/evaluate.d.ts

@@ -80,6 +80,18 @@ export type DisplayOp = (OpBase & {
     offsetY: number;
     /** Box-fit; present only when authored and not "fill". */
     fit?: ImageFit;
+}) | (OpBase & {
+    type: "video";
+    /** Raw src string as authored in the IR — consumers resolve it. */
+    src: string;
+    width: number;
+    height: number;
+    offsetX: number;
+    offsetY: number;
+    /** Source frame index at scene-time t (renderer clamps to the extracted count). */
+    frame: number;
+    /** Box-fit; present only when authored and not "fill". */
+    fit?: ImageFit;
 }) | (OpBase & {
     type: "path";
     /** SVG path data, drawn via Path2D. */

package/dist/types/index.d.ts

@@ -21,5 +21,5 @@ export { resolveAudioPlan, resolveCompositionAudioPlan, SFX_DURATION, type Audio
 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";
-export { collectImageSrcs } from "./assets.js";
+export { collectImageSrcs, collectVideoSrcs } from "./assets.js";
 export { sketchToTimeline, type MotionSketch, type MotionEvent, type MotionEventKind, type MotionRegion, } from "./motion.js";

package/dist/types/ir.d.ts

@@ -192,6 +192,23 @@ export interface ImageProps extends BaseProps {
 }
 /** Image box-fit mode. `cover` = crop-to-fill at the image's aspect (centered). */
 export type ImageFit = "fill" | "cover";
+export interface VideoProps extends BaseProps {
+    /** Video file path (absolute, or relative to the scene file). */
+    src: string;
+    width: number;
+    height: number;
+    /** Box-fit into width×height, like the image node. `"fill"` (default) | `"cover"`. */
+    fit?: ImageFit;
+    /**
+     * Scene-time (seconds) at which playback begins. Before it, frame 0 (clipStart) shows;
+     * the node's visibility is still controlled by opacity/timeline. Default 0.
+     */
+    start?: number;
+    /** Playback speed multiplier (2 = double speed). Default 1. */
+    rate?: number;
+    /** Source in-point (seconds) shown at `start`. Default 0. */
+    clipStart?: number;
+}
 export type NodeIR = {
     type: "rect";
     id: string;
@@ -212,6 +229,10 @@ export type NodeIR = {
     type: "image";
     id: string;
     props: ImageProps;
+} | {
+    type: "video";
+    id: string;
+    props: VideoProps;
 } | {
     type: "path";
     id: string;

package/guides/edsl-guide.md

@@ -317,6 +317,27 @@ scene({ size, nodes: [...m.nodes, ...titles], timeline: par(m.timeline, titleTra
 - Seeded + pure (same `(images, opts)` → identical IR). Note: image-node sources do
   not render in `reframe player` / artifacts — montage ships as mp4.
 
+## Video clips (`video`)
+
+Draw a video clip as a layer. It plays on the scene clock — at scene-time `t` it
+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 })
+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.
+- **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`.
+
 ## Cursor (UI demos)
 
 A vector mouse pointer that glides across the scene and clicks things — for app

package/package.json

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

package/preview/src/main.ts

@@ -551,7 +551,8 @@ function opCorners(op: DisplayOp): [number, number][] {
   switch (op.type) {
     case "rect":
     case "ellipse":
-    case "image": {
+    case "image":
+    case "video": {
       const { offsetX: x, offsetY: y, width: w, height: h } = op;
       return [[x, y], [x + w, y], [x + w, y + h], [x, y + h]].map(([px, py]) =>
         applyMat(op.transform, px!, py!),