simple-ffmpegjs 0.3.5 → 0.4.0

package/src/lib/gradient.js

@@ -0,0 +1,257 @@
+/**
+ * Pure Node.js gradient image generator.
+ *
+ * Produces PPM (P6) format images — the simplest binary image format.
+ * FFmpeg reads PPM natively on all versions, so no external dependencies
+ * are needed.
+ *
+ * Supports:
+ *   - Linear gradients (vertical, horizontal, or arbitrary angle)
+ *   - Radial gradients (center → edge)
+ *   - Multi-color stop support (2+ colors, evenly distributed)
+ */
+
+// ── Named color → RGB lookup ────────────────────────────────────────────────
+// Subset of X11/CSS colors that FFmpeg accepts. This list mirrors the
+// FFMPEG_NAMED_COLORS set in validation.js but maps to RGB values.
+const NAMED_COLORS = {
+  aliceblue: [240, 248, 255], antiquewhite: [250, 235, 215], aqua: [0, 255, 255],
+  aquamarine: [127, 255, 212], azure: [240, 255, 255], beige: [245, 245, 220],
+  bisque: [255, 228, 196], black: [0, 0, 0], blanchedalmond: [255, 235, 205],
+  blue: [0, 0, 255], blueviolet: [138, 43, 226], brown: [165, 42, 42],
+  burlywood: [222, 184, 135], cadetblue: [95, 158, 160], chartreuse: [127, 255, 0],
+  chocolate: [210, 105, 30], coral: [255, 127, 80], cornflowerblue: [100, 149, 237],
+  cornsilk: [255, 248, 220], crimson: [220, 20, 60], cyan: [0, 255, 255],
+  darkblue: [0, 0, 139], darkcyan: [0, 139, 139], darkgoldenrod: [184, 134, 11],
+  darkgray: [169, 169, 169], darkgreen: [0, 100, 0], darkgrey: [169, 169, 169],
+  darkkhaki: [189, 183, 107], darkmagenta: [139, 0, 139], darkolivegreen: [85, 107, 47],
+  darkorange: [255, 140, 0], darkorchid: [153, 50, 204], darkred: [139, 0, 0],
+  darksalmon: [233, 150, 122], darkseagreen: [143, 188, 143], darkslateblue: [72, 61, 139],
+  darkslategray: [47, 79, 79], darkslategrey: [47, 79, 79], darkturquoise: [0, 206, 209],
+  darkviolet: [148, 0, 211], deeppink: [255, 20, 147], deepskyblue: [0, 191, 255],
+  dimgray: [105, 105, 105], dimgrey: [105, 105, 105], dodgerblue: [30, 144, 255],
+  firebrick: [178, 34, 34], floralwhite: [255, 250, 240], forestgreen: [34, 139, 34],
+  fuchsia: [255, 0, 255], gainsboro: [220, 220, 220], ghostwhite: [248, 248, 255],
+  gold: [255, 215, 0], goldenrod: [218, 165, 32], gray: [128, 128, 128],
+  green: [0, 128, 0], greenyellow: [173, 255, 47], grey: [128, 128, 128],
+  honeydew: [240, 255, 240], hotpink: [255, 105, 180], indianred: [205, 92, 92],
+  indigo: [75, 0, 130], ivory: [255, 255, 240], khaki: [240, 230, 140],
+  lavender: [230, 230, 250], lavenderblush: [255, 240, 245], lawngreen: [124, 252, 0],
+  lemonchiffon: [255, 250, 205], lightblue: [173, 216, 230], lightcoral: [240, 128, 128],
+  lightcyan: [224, 255, 255], lightgoldenrodyellow: [250, 250, 210],
+  lightgray: [211, 211, 211], lightgreen: [144, 238, 144], lightgrey: [211, 211, 211],
+  lightpink: [255, 182, 193], lightsalmon: [255, 160, 122], lightseagreen: [32, 178, 170],
+  lightskyblue: [135, 206, 250], lightslategray: [119, 136, 153],
+  lightslategrey: [119, 136, 153], lightsteelblue: [176, 196, 222],
+  lightyellow: [255, 255, 224], lime: [0, 255, 0], limegreen: [50, 205, 50],
+  linen: [250, 240, 230], magenta: [255, 0, 255], maroon: [128, 0, 0],
+  mediumaquamarine: [102, 205, 170], mediumblue: [0, 0, 205],
+  mediumorchid: [186, 85, 211], mediumpurple: [147, 112, 219],
+  mediumseagreen: [60, 179, 113], mediumslateblue: [123, 104, 238],
+  mediumspringgreen: [0, 250, 154], mediumturquoise: [72, 209, 204],
+  mediumvioletred: [199, 21, 133], midnightblue: [25, 25, 112],
+  mintcream: [245, 255, 250], mistyrose: [255, 228, 225], moccasin: [255, 228, 181],
+  navajowhite: [255, 222, 173], navy: [0, 0, 128], oldlace: [253, 245, 230],
+  olive: [128, 128, 0], olivedrab: [107, 142, 35], orange: [255, 165, 0],
+  orangered: [255, 69, 0], orchid: [218, 112, 214], palegoldenrod: [238, 232, 170],
+  palegreen: [152, 251, 152], paleturquoise: [175, 238, 238],
+  palevioletred: [219, 112, 147], papayawhip: [255, 239, 213],
+  peachpuff: [255, 218, 185], peru: [205, 133, 63], pink: [255, 192, 203],
+  plum: [221, 160, 221], powderblue: [176, 224, 230], purple: [128, 0, 128],
+  red: [255, 0, 0], rosybrown: [188, 143, 143], royalblue: [65, 105, 225],
+  saddlebrown: [139, 69, 19], salmon: [250, 128, 114], sandybrown: [244, 164, 96],
+  seagreen: [46, 139, 87], seashell: [255, 245, 238], sienna: [160, 82, 45],
+  silver: [192, 192, 192], skyblue: [135, 206, 235], slateblue: [106, 90, 205],
+  slategray: [112, 128, 144], slategrey: [112, 128, 144], snow: [255, 250, 250],
+  springgreen: [0, 255, 127], steelblue: [70, 130, 180], tan: [210, 180, 140],
+  teal: [0, 128, 128], thistle: [216, 191, 216], tomato: [255, 99, 71],
+  turquoise: [64, 224, 208], violet: [238, 130, 238], wheat: [245, 222, 179],
+  white: [255, 255, 255], whitesmoke: [245, 245, 245], yellow: [255, 255, 0],
+  yellowgreen: [154, 205, 50],
+};
+
+/**
+ * Parse a color string to [r, g, b] (0-255 each).
+ *
+ * Accepted formats:
+ *   - Named colors: "black", "navy", "red", …
+ *   - Hex: "#RGB", "#RRGGBB"
+ *   - 0x hex: "0xRRGGBB"
+ *
+ * @param {string} str - Color string
+ * @returns {number[]} [r, g, b]
+ */
+function parseColor(str) {
+  if (typeof str !== "string" || str.length === 0) {
+    return [0, 0, 0]; // fallback to black
+  }
+
+  // Strip @alpha suffix if present (e.g. "white@0.5")
+  const atIdx = str.indexOf("@");
+  const color = atIdx > 0 ? str.slice(0, atIdx) : str;
+
+  // Named color
+  const named = NAMED_COLORS[color.toLowerCase()];
+  if (named) return [...named];
+
+  // #RGB → #RRGGBB
+  if (/^#[0-9a-fA-F]{3}$/.test(color)) {
+    const r = parseInt(color[1] + color[1], 16);
+    const g = parseInt(color[2] + color[2], 16);
+    const b = parseInt(color[3] + color[3], 16);
+    return [r, g, b];
+  }
+
+  // #RRGGBB or #RRGGBBAA
+  if (/^#[0-9a-fA-F]{6}([0-9a-fA-F]{2})?$/.test(color)) {
+    const r = parseInt(color.slice(1, 3), 16);
+    const g = parseInt(color.slice(3, 5), 16);
+    const b = parseInt(color.slice(5, 7), 16);
+    return [r, g, b];
+  }
+
+  // 0xRRGGBB or 0xRRGGBBAA
+  if (/^0x[0-9a-fA-F]{6}([0-9a-fA-F]{2})?$/.test(color)) {
+    const r = parseInt(color.slice(2, 4), 16);
+    const g = parseInt(color.slice(4, 6), 16);
+    const b = parseInt(color.slice(6, 8), 16);
+    return [r, g, b];
+  }
+
+  return [0, 0, 0]; // fallback
+}
+
+/**
+ * Interpolate between an array of colors at position t (0–1).
+ * Colors are evenly distributed across the 0–1 range.
+ *
+ * @param {number[][]} colors - Array of [r,g,b] colors
+ * @param {number} t - Position in gradient (0 = first color, 1 = last color)
+ * @returns {number[]} [r, g, b]
+ */
+function interpolateColors(colors, t) {
+  if (colors.length === 1) return colors[0];
+
+  const clamped = Math.max(0, Math.min(1, t));
+  const segments = colors.length - 1;
+  const segFloat = clamped * segments;
+  const segIdx = Math.min(Math.floor(segFloat), segments - 1);
+  const segT = segFloat - segIdx;
+
+  const c0 = colors[segIdx];
+  const c1 = colors[segIdx + 1];
+  return [
+    Math.round(c0[0] + (c1[0] - c0[0]) * segT),
+    Math.round(c0[1] + (c1[1] - c0[1]) * segT),
+    Math.round(c0[2] + (c1[2] - c0[2]) * segT),
+  ];
+}
+
+/**
+ * Generate a linear gradient PPM image buffer.
+ *
+ * @param {number} width
+ * @param {number} height
+ * @param {number[][]} colors - Parsed [r,g,b] color stops
+ * @param {string|number} direction - "vertical", "horizontal", or angle in degrees
+ * @returns {Buffer}
+ */
+function generateLinearGradient(width, height, colors, direction) {
+  const pixels = Buffer.alloc(width * height * 3);
+
+  // Compute unit direction vector from direction spec
+  let dx = 0;
+  let dy = 1; // default: vertical (top to bottom)
+  if (direction === "horizontal") {
+    dx = 1;
+    dy = 0;
+  } else if (direction === "vertical") {
+    dx = 0;
+    dy = 1;
+  } else if (typeof direction === "number") {
+    const rad = (direction * Math.PI) / 180;
+    dx = Math.cos(rad);
+    dy = Math.sin(rad);
+  }
+
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      // Project pixel onto gradient axis (normalized 0–1)
+      const nx = width > 1 ? x / (width - 1) : 0.5;
+      const ny = height > 1 ? y / (height - 1) : 0.5;
+      const t = nx * dx + ny * dy;
+
+      const [r, g, b] = interpolateColors(colors, t);
+      const idx = (y * width + x) * 3;
+      pixels[idx] = r;
+      pixels[idx + 1] = g;
+      pixels[idx + 2] = b;
+    }
+  }
+
+  return pixels;
+}
+
+/**
+ * Generate a radial gradient PPM image buffer.
+ *
+ * @param {number} width
+ * @param {number} height
+ * @param {number[][]} colors - Parsed [r,g,b] color stops (center → edge)
+ * @returns {Buffer}
+ */
+function generateRadialGradient(width, height, colors) {
+  const pixels = Buffer.alloc(width * height * 3);
+  const cx = (width - 1) / 2;
+  const cy = (height - 1) / 2;
+  // Max distance from center to any corner
+  const maxDist = Math.sqrt(cx * cx + cy * cy) || 1;
+
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      const dist = Math.sqrt((x - cx) * (x - cx) + (y - cy) * (y - cy));
+      const t = dist / maxDist;
+
+      const [r, g, b] = interpolateColors(colors, t);
+      const idx = (y * width + x) * 3;
+      pixels[idx] = r;
+      pixels[idx + 1] = g;
+      pixels[idx + 2] = b;
+    }
+  }
+
+  return pixels;
+}
+
+/**
+ * Generate a gradient image as a PPM (P6) buffer.
+ *
+ * @param {number} width - Image width
+ * @param {number} height - Image height
+ * @param {Object} colorSpec - Gradient specification
+ * @param {string} colorSpec.type - "linear-gradient" or "radial-gradient"
+ * @param {string[]} colorSpec.colors - Array of color strings (2+ colors)
+ * @param {string|number} [colorSpec.direction] - For linear: "vertical", "horizontal", or angle in degrees (default: "vertical")
+ * @returns {Buffer} PPM image buffer ready to write to disk
+ */
+function generateGradientPPM(width, height, colorSpec) {
+  const parsedColors = colorSpec.colors.map(parseColor);
+
+  let pixels;
+  if (colorSpec.type === "radial-gradient") {
+    pixels = generateRadialGradient(width, height, parsedColors);
+  } else {
+    // linear-gradient (default)
+    const direction = colorSpec.direction || "vertical";
+    pixels = generateLinearGradient(width, height, parsedColors, direction);
+  }
+
+  const header = Buffer.from(`P6\n${width} ${height}\n255\n`);
+  return Buffer.concat([header, pixels]);
+}
+
+module.exports = {
+  generateGradientPPM,
+  parseColor,
+  interpolateColors,
+};

package/src/loaders.js

@@ -1,8 +1,10 @@
 const fs = require("fs");
+const os = require("os");
 const path = require("path");
 const { probeMedia } = require("./core/media_info");
 const { ValidationError, MediaNotFoundError } = require("./core/errors");
 const C = require("./core/constants");
+const { generateGradientPPM } = require("./lib/gradient");
 
 async function loadVideo(project, clipObj) {
   const metadata = await probeMedia(clipObj.url);
@@ -88,8 +90,15 @@ async function loadAudio(project, clipObj) {
   project.videoOrAudioClips.push({ ...clipObj, mediaDuration: durationSec });
 }
 
-function loadImage(project, clipObj) {
-  const clip = { ...clipObj, hasAudio: false, cutFrom: 0 };
+async function loadImage(project, clipObj) {
+  const metadata = await probeMedia(clipObj.url);
+  const clip = {
+    ...clipObj,
+    hasAudio: false,
+    cutFrom: 0,
+    width: clipObj.width ?? metadata.width,
+    height: clipObj.height ?? metadata.height,
+  };
   project.videoOrAudioClips.push(clip);
 }
 
@@ -166,6 +175,17 @@ function loadText(project, clipObj) {
   }
 }
 
+function loadEffect(project, clipObj) {
+  const clip = {
+    ...clipObj,
+    fadeIn: typeof clipObj.fadeIn === "number" ? clipObj.fadeIn : 0,
+    fadeOut: typeof clipObj.fadeOut === "number" ? clipObj.fadeOut : 0,
+    easing: clipObj.easing || "linear",
+    params: clipObj.params || {},
+  };
+  project.effectClips.push(clip);
+}
+
 function loadSubtitle(project, clipObj) {
   // Validate file exists
   if (!fs.existsSync(clipObj.url)) {
@@ -202,11 +222,44 @@ function loadSubtitle(project, clipObj) {
   project.subtitleClips.push(clip);
 }
 
+async function loadColor(project, clipObj) {
+  if (typeof clipObj.color === "string") {
+    // Flat color — no file needed, uses FFmpeg color= filter source directly
+    project.videoOrAudioClips.push({
+      ...clipObj,
+      hasAudio: false,
+      _isFlatColor: true,
+    });
+  } else {
+    // Gradient — generate a temp PPM image and treat as an image clip
+    const width = project.options.width || C.DEFAULT_WIDTH;
+    const height = project.options.height || C.DEFAULT_HEIGHT;
+    const ppmBuffer = generateGradientPPM(width, height, clipObj.color);
+
+    const tempPath = path.join(
+      os.tmpdir(),
+      `simpleffmpeg-gradient-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.ppm`
+    );
+    fs.writeFileSync(tempPath, ppmBuffer);
+
+    // Register for cleanup
+    project.filesToClean.push(tempPath);
+
+    project.videoOrAudioClips.push({
+      ...clipObj,
+      url: tempPath,
+      hasAudio: false,
+    });
+  }
+}
+
 module.exports = {
   loadVideo,
   loadAudio,
   loadImage,
   loadBackgroundAudio,
   loadText,
+  loadEffect,
   loadSubtitle,
+  loadColor,
 };

package/src/schema/formatter.js

@@ -143,6 +143,8 @@ function formatSchema(modules, options = {}) {
     video: '"video"',
     audio: '"audio"',
     image: '"image"',
+    color: '"color"',
+    effect: '"effect"',
     text: '"text"',
     subtitle: '"subtitle"',
     music: '"music" or "backgroundAudio"',

package/src/schema/index.js

@@ -12,6 +12,8 @@ const { formatSchema } = require("./formatter");
 const videoModule = require("./modules/video");
 const audioModule = require("./modules/audio");
 const imageModule = require("./modules/image");
+const colorModule = require("./modules/color");
+const effectModule = require("./modules/effect");
 const textModule = require("./modules/text");
 const subtitleModule = require("./modules/subtitle");
 const musicModule = require("./modules/music");
@@ -24,6 +26,8 @@ const ALL_MODULES = {
   video: videoModule,
   audio: audioModule,
   image: imageModule,
+  color: colorModule,
+  effect: effectModule,
   text: textModule,
   subtitle: subtitleModule,
   music: musicModule,

package/src/schema/modules/color.js

@@ -0,0 +1,54 @@
+module.exports = {
+  id: "color",
+  name: "Color Clips",
+  description:
+    "Solid color or gradient clips for filling gaps, creating transitions to/from black, or adding visual backgrounds to the timeline.",
+  schema: `{
+  type: "color";                            // Required: clip type identifier
+  color: string | GradientSpec;             // Required: flat color string or gradient specification
+  position?: number;                        // Start time on timeline (seconds). Omit to auto-sequence after previous visual clip.
+  end?: number;                             // End time on timeline (seconds). Use end OR duration, not both.
+  duration?: number;                        // Duration in seconds (alternative to end). end = position + duration.
+  transition?: TransitionConfig;            // Optional: transition effect from the previous visual clip
+}`,
+  enums: {
+    GradientType: ["linear-gradient", "radial-gradient"],
+    GradientDirection: ["vertical", "horizontal"],
+  },
+  examples: [
+    {
+      label: "Black gap between clips",
+      code: `{ type: "color", color: "black", position: 5, end: 7 }`,
+    },
+    {
+      label: "Fade to black between videos",
+      code: `[
+  { type: "video", url: "intro.mp4", position: 0, end: 5 },
+  { type: "color", color: "black", position: 5, end: 7, transition: { type: "fade", duration: 0.5 } },
+  { type: "video", url: "main.mp4", position: 7, end: 15, transition: { type: "fade", duration: 0.5 } }
+]`,
+    },
+    {
+      label: "Linear gradient clip",
+      code: `{ type: "color", color: { type: "linear-gradient", colors: ["#000000", "#0a0a2e"], direction: "vertical" }, duration: 3 }`,
+    },
+    {
+      label: "Radial gradient clip",
+      code: `{ type: "color", color: { type: "radial-gradient", colors: ["white", "navy"] }, duration: 2 }`,
+    },
+    {
+      label: "Multi-stop gradient",
+      code: `{ type: "color", color: { type: "linear-gradient", colors: ["#ff0000", "#00ff00", "#0000ff"], direction: "horizontal" }, duration: 4 }`,
+    },
+  ],
+  notes: [
+    "Flat color accepts any valid FFmpeg color: named colors (\"black\", \"navy\", \"red\"), hex (#RGB, #RRGGBB), or \"random\".",
+    "Gradient clips generate a temporary image internally and flow through the image pipeline — no external dependencies required.",
+    "Linear gradients support direction as \"vertical\" (default), \"horizontal\", or a number (angle in degrees).",
+    "Radial gradients interpolate from the center outward.",
+    "Gradient colors array must have at least 2 colors; multiple stops are evenly distributed.",
+    "Color clips support transitions just like video and image clips (e.g. fade, wipe, dissolve).",
+    "If position is omitted, the clip is placed immediately after the previous visual clip (auto-sequencing).",
+    "Use duration instead of end to specify length: end = position + duration. Cannot use both.",
+  ],
+};

package/src/schema/modules/effect.js

@@ -0,0 +1,77 @@
+module.exports = {
+  id: "effect",
+  name: "Effect Clips",
+  description:
+    "Overlay adjustment clips that apply timed visual effects to the composed video (they do not create visual content by themselves).",
+  schema: `{
+  type: "effect";                           // Required: clip type identifier
+  effect: "vignette" | "filmGrain" | "gaussianBlur" | "colorAdjust"; // Required: effect kind
+  position: number;                         // Required: start time on timeline (seconds)
+  end?: number;                             // End time on timeline (seconds). Use end OR duration, not both.
+  duration?: number;                        // Duration in seconds (alternative to end). end = position + duration.
+  fadeIn?: number;                          // Optional: seconds to ramp in from 0 to full intensity
+  fadeOut?: number;                         // Optional: seconds to ramp out from full intensity to 0
+  easing?: "linear" | "ease-in" | "ease-out" | "ease-in-out"; // Optional envelope easing (default: "linear")
+  params: EffectParams;                     // Required: effect-specific parameters
+}`,
+  enums: {
+    EffectType: ["vignette", "filmGrain", "gaussianBlur", "colorAdjust"],
+    EffectEasing: ["linear", "ease-in", "ease-out", "ease-in-out"],
+    VignetteParams: `{ amount?: number; angle?: number; }`,
+    FilmGrainParams: `{ amount?: number; temporal?: boolean; }`,
+    GaussianBlurParams: `{ amount?: number; sigma?: number; }`,
+    ColorAdjustParams:
+      `{ amount?: number; brightness?: number; contrast?: number; saturation?: number; gamma?: number; }`,
+  },
+  examples: [
+    {
+      label: "Vignette that ramps in (duration shorthand)",
+      code: `{
+  type: "effect",
+  effect: "vignette",
+  position: 0,
+  duration: 4,
+  fadeIn: 1,
+  params: { amount: 0.8 }
+}`,
+    },
+    {
+      label: "Film grain only during the middle section",
+      code: `{
+  type: "effect",
+  effect: "filmGrain",
+  position: 3,
+  end: 8,
+  fadeIn: 0.4,
+  fadeOut: 0.6,
+  easing: "ease-in-out",
+  params: { amount: 0.45, temporal: true }
+}`,
+    },
+    {
+      label: "Color adjustment look with smooth exit",
+      code: `{
+  type: "effect",
+  effect: "colorAdjust",
+  position: 0,
+  end: 10,
+  fadeOut: 1,
+  params: {
+    amount: 0.7,
+    contrast: 1.12,
+    saturation: 1.18,
+    gamma: 1.04,
+    brightness: -0.02
+  }
+}`,
+    },
+  ],
+  notes: [
+    "Effect clips are adjustment layers: they modify underlying video during their active window.",
+    "Effects do not satisfy visual timeline continuity checks and do not fill gaps.",
+    "Use duration instead of end to specify length: end = position + duration. Cannot use both.",
+    "position is required for effect clips (no auto-sequencing).",
+    "fadeIn/fadeOut are optional envelope controls that avoid abrupt on/off changes.",
+    "params.amount is a normalized blend amount from 0 to 1 (default: 1).",
+  ],
+};

package/src/schema/modules/image.js

@@ -4,12 +4,14 @@ module.exports = {
   description:
     "Display still images on the timeline, optionally with Ken Burns (pan/zoom) motion effects.",
   schema: `{
-  type: "image";              // Required: clip type identifier
-  url: string;                // Required: path to image file (jpg, png, etc.)
-  position?: number;          // Start time on timeline (seconds). Omit to auto-sequence after previous video/image clip.
-  end?: number;               // End time on timeline (seconds). Use end OR duration, not both.
-  duration?: number;          // Duration in seconds (alternative to end). end = position + duration.
-  kenBurns?: KenBurnsEffect;  // Optional: apply pan/zoom motion to the image
+  type: "image";                            // Required: clip type identifier
+  url: string;                              // Required: path to image file (jpg, png, etc.)
+  position?: number;                        // Start time on timeline (seconds). Omit to auto-sequence after previous video/image clip.
+  end?: number;                             // End time on timeline (seconds). Use end OR duration, not both.
+  duration?: number;                        // Duration in seconds (alternative to end). end = position + duration.
+  width?: number;                           // Optional: source image width (skip probe / override)
+  height?: number;                          // Optional: source image height (skip probe / override)
+  kenBurns?: KenBurnsEffect | KenBurnsSpec; // Optional: apply pan/zoom motion to the image
 }`,
   enums: {
     KenBurnsEffect: [
@@ -19,7 +21,11 @@ module.exports = {
       "pan-right",
       "pan-up",
       "pan-down",
+      "smart",
+      "custom",
     ],
+    KenBurnsAnchor: ["top", "bottom", "left", "right"],
+    KenBurnsEasing: ["linear", "ease-in", "ease-out", "ease-in-out"],
   },
   examples: [
     {
@@ -34,11 +40,23 @@ module.exports = {
   { type: "image", url: "photo3.jpg", duration: 3, kenBurns: "zoom-out" }
 ]`,
     },
+    {
+      label: "Custom Ken Burns pan with smart anchor",
+      code: `{ type: "image", url: "portrait.jpg", duration: 5, kenBurns: { type: "smart", anchor: "bottom", startZoom: 1.05, endZoom: 1.2 } }`,
+    },
+    {
+      label: "Custom Ken Burns with explicit pan endpoints",
+      code: `{ type: "image", url: "photo.jpg", duration: 4, kenBurns: { type: "custom", startX: 0.2, startY: 0.8, endX: 0.7, endY: 0.3 } }`,
+    },
   ],
   notes: [
     "If position is omitted, the clip is placed immediately after the previous video/image clip (auto-sequencing). The first clip defaults to position 0.",
     "Use duration instead of end to specify how long the image displays: end = position + duration. Cannot use both.",
     "Images are scaled to fill the project canvas. For Ken Burns, use images at least as large as the output resolution for best quality.",
+    "If width/height are provided, they override probed dimensions (useful for remote or generated images).",
     "Image clips can be placed on the same timeline as video clips and can use transitions between them.",
+    "Advanced Ken Burns accepts custom zoom/pan endpoints via normalized coordinates (0 = left/top, 1 = right/bottom).",
+    "smart mode auto-pans along the dominant axis; use anchor to pick a starting edge.",
+    "Use easing ('linear', 'ease-in', 'ease-out', 'ease-in-out') to smooth motion (default: ease-in-out).",
   ],
 };