simple-ffmpegjs 0.3.6 → 0.4.0

package/src/ffmpeg/video_builder.js

@@ -1,20 +1,3 @@
-const { detectVisualGaps } = require("../core/gaps");
-
-/**
- * Create synthetic clips to fill visual gaps.
- * The actual fill color is determined by the project's fillGaps option
- * and applied when building the filter graph.
- */
-function createGapFillClips(gaps) {
-  return gaps.map((gap, index) => ({
-    type: "_gapfill",
-    position: gap.start,
-    end: gap.end,
-    _gapIndex: index,
-    _isGapFill: true,
-  }));
-}
-
 const DEFAULT_KEN_BURNS_ZOOM = 0.15;
 const DEFAULT_PAN_ZOOM = 1.12;
 
@@ -197,30 +180,31 @@ function computeOverscanWidth(width, startZoom, endZoom) {
   return overscan;
 }
 
-function buildVideoFilter(project, videoClips, options = {}) {
+function buildVideoFilter(project, videoClips) {
   let filterComplex = "";
   let videoIndex = 0;
-  let blackGapIndex = 0;
   const fps = project.options.fps;
   const width = project.options.width;
   const height = project.options.height;
-  const fillGaps = project.options.fillGaps || "none";
-
-  // Detect and fill gaps if fillGaps is enabled (any value other than "none")
-  let allVisualClips = [...videoClips];
-  if (fillGaps !== "none") {
-    const gaps = detectVisualGaps(videoClips, { timelineEnd: options.timelineEnd });
-    if (gaps.length > 0) {
-      const gapClips = createGapFillClips(gaps);
-      allVisualClips = [...videoClips, ...gapClips].sort(
-        (a, b) => (a.position || 0) - (b.position || 0),
-      );
+
+  // Use the project-level input index map (built in _prepareExport) when available,
+  // otherwise build a local one for standalone usage (e.g. unit tests).
+  let inputIndexMap = project._inputIndexMap;
+  if (!inputIndexMap) {
+    inputIndexMap = new Map();
+    let inputIdx = 0;
+    for (const clip of project.videoOrAudioClips) {
+      if (clip.type === "color" && clip._isFlatColor) {
+        continue;
+      }
+      inputIndexMap.set(clip, inputIdx);
+      inputIdx++;
     }
   }
 
   // Build scaled streams
   const scaledStreams = [];
-  allVisualClips.forEach((clip) => {
+  videoClips.forEach((clip) => {
     const scaledLabel = `[scaled${videoIndex}]`;
 
     const requestedDuration = Math.max(
@@ -228,10 +212,10 @@ function buildVideoFilter(project, videoClips, options = {}) {
       (clip.end || 0) - (clip.position || 0),
     );
 
-    // Handle synthetic gap fill clips
-    if (clip._isGapFill) {
-      // Generate a color source for the gap duration
-      filterComplex += `color=c=${fillGaps}:s=${width}x${height}:d=${requestedDuration},fps=${fps},settb=1/${fps}${scaledLabel};`;
+    // Handle flat color clips — generate using color= filter source
+    if (clip.type === "color" && clip._isFlatColor) {
+      const colorValue = clip.color;
+      filterComplex += `color=c=${colorValue}:s=${width}x${height}:d=${requestedDuration},fps=${fps},settb=1/${fps}${scaledLabel};`;
       scaledStreams.push({
         label: scaledLabel,
         clip,
@@ -239,11 +223,10 @@ function buildVideoFilter(project, videoClips, options = {}) {
         duration: requestedDuration,
       });
       videoIndex++;
-      blackGapIndex++;
       return;
     }
 
-    const inputIndex = project.videoOrAudioClips.indexOf(clip);
+    const inputIndex = inputIndexMap.get(clip);
     const maxAvailable =
       typeof clip.mediaDuration === "number" && typeof clip.cutFrom === "number"
         ? Math.max(0, clip.mediaDuration - clip.cutFrom)

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);
@@ -173,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)) {
@@ -209,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).",
+  ],
+};