simple-ffmpegjs 0.3.5 → 0.4.0

package/src/core/validation.js

@@ -1,4 +1,76 @@
 const fs = require("fs");
+const { detectVisualGaps } = require("./gaps");
+
+// ========================================================================
+// FFmpeg named colors (X11/CSS color names accepted by libavutil)
+// This list is extremely stable — identical across FFmpeg versions.
+// Reference: https://ffmpeg.org/ffmpeg-utils.html#Color
+// ========================================================================
+const FFMPEG_NAMED_COLORS = new Set([
+  "aliceblue", "antiquewhite", "aqua", "aquamarine", "azure",
+  "beige", "bisque", "black", "blanchedalmond", "blue",
+  "blueviolet", "brown", "burlywood", "cadetblue", "chartreuse",
+  "chocolate", "coral", "cornflowerblue", "cornsilk", "crimson",
+  "cyan", "darkblue", "darkcyan", "darkgoldenrod", "darkgray",
+  "darkgreen", "darkgrey", "darkkhaki", "darkmagenta", "darkolivegreen",
+  "darkorange", "darkorchid", "darkred", "darksalmon", "darkseagreen",
+  "darkslateblue", "darkslategray", "darkslategrey", "darkturquoise", "darkviolet",
+  "deeppink", "deepskyblue", "dimgray", "dimgrey", "dodgerblue",
+  "firebrick", "floralwhite", "forestgreen", "fuchsia", "gainsboro",
+  "ghostwhite", "gold", "goldenrod", "gray", "green",
+  "greenyellow", "grey", "honeydew", "hotpink", "indianred",
+  "indigo", "ivory", "khaki", "lavender", "lavenderblush",
+  "lawngreen", "lemonchiffon", "lightblue", "lightcoral", "lightcyan",
+  "lightgoldenrodyellow", "lightgray", "lightgreen", "lightgrey", "lightpink",
+  "lightsalmon", "lightseagreen", "lightskyblue", "lightslategray", "lightslategrey",
+  "lightsteelblue", "lightyellow", "lime", "limegreen", "linen",
+  "magenta", "maroon", "mediumaquamarine", "mediumblue", "mediumorchid",
+  "mediumpurple", "mediumseagreen", "mediumslateblue", "mediumspringgreen", "mediumturquoise",
+  "mediumvioletred", "midnightblue", "mintcream", "mistyrose", "moccasin",
+  "navajowhite", "navy", "oldlace", "olive", "olivedrab",
+  "orange", "orangered", "orchid", "palegoldenrod", "palegreen",
+  "paleturquoise", "palevioletred", "papayawhip", "peachpuff", "peru",
+  "pink", "plum", "powderblue", "purple", "red",
+  "rosybrown", "royalblue", "saddlebrown", "salmon", "sandybrown",
+  "seagreen", "seashell", "sienna", "silver", "skyblue",
+  "slateblue", "slategray", "slategrey", "snow", "springgreen",
+  "steelblue", "tan", "teal", "thistle", "tomato",
+  "turquoise", "violet", "wheat", "white", "whitesmoke",
+  "yellow", "yellowgreen",
+]);
+
+// Hex patterns accepted by FFmpeg: #RGB, #RRGGBB, #RRGGBBAA, 0xRRGGBB, 0xRRGGBBAA
+const HEX_COLOR_RE = /^(#[0-9a-fA-F]{3}|#[0-9a-fA-F]{6}|#[0-9a-fA-F]{8}|0x[0-9a-fA-F]{6}|0x[0-9a-fA-F]{8})$/;
+
+/**
+ * Check whether a string is a valid FFmpeg color value.
+ *
+ * Accepted formats:
+ *   - Named colors (case-insensitive): "black", "Red", "DarkSlateGray", …
+ *   - Hex:  #RGB, #RRGGBB, #RRGGBBAA, 0xRRGGBB, 0xRRGGBBAA
+ *   - Special keyword: "random"
+ *   - Any of the above with an @alpha suffix: "white@0.5", "#FF0000@0.8"
+ *
+ * @param {string} value
+ * @returns {boolean}
+ */
+function isValidFFmpegColor(value) {
+  if (typeof value !== "string" || value.length === 0) return false;
+
+  // Strip optional @alpha suffix (e.g. "white@0.5", "#FF0000@0.8")
+  let color = value;
+  const atIdx = value.indexOf("@");
+  if (atIdx > 0) {
+    const alphaPart = value.slice(atIdx + 1);
+    const alpha = Number(alphaPart);
+    if (!Number.isFinite(alpha) || alpha < 0 || alpha > 1) return false;
+    color = value.slice(0, atIdx);
+  }
+
+  if (color === "random") return true;
+  if (HEX_COLOR_RE.test(color)) return true;
+  return FFMPEG_NAMED_COLORS.has(color.toLowerCase());
+}
 
 /**
  * Error/warning codes for programmatic handling
@@ -34,6 +106,172 @@ function createIssue(code, path, message, received = undefined) {
   return issue;
 }
 
+const EFFECT_TYPES = ["vignette", "filmGrain", "gaussianBlur", "colorAdjust"];
+const EFFECT_EASING = ["linear", "ease-in", "ease-out", "ease-in-out"];
+
+function validateFiniteNumber(value, path, errors, opts = {}) {
+  const { min = null, max = null, minInclusive = true, maxInclusive = true } = opts;
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    errors.push(
+      createIssue(
+        ValidationCodes.INVALID_VALUE,
+        path,
+        "Must be a finite number",
+        value
+      )
+    );
+    return;
+  }
+  if (min != null) {
+    const failsMin = minInclusive ? value < min : value <= min;
+    if (failsMin) {
+      errors.push(
+        createIssue(
+          ValidationCodes.INVALID_RANGE,
+          path,
+          minInclusive ? `Must be >= ${min}` : `Must be > ${min}`,
+          value
+        )
+      );
+      return;
+    }
+  }
+  if (max != null) {
+    const failsMax = maxInclusive ? value > max : value >= max;
+    if (failsMax) {
+      errors.push(
+        createIssue(
+          ValidationCodes.INVALID_RANGE,
+          path,
+          maxInclusive ? `Must be <= ${max}` : `Must be < ${max}`,
+          value
+        )
+      );
+    }
+  }
+}
+
+function validateEffectClip(clip, path, errors) {
+  if (!EFFECT_TYPES.includes(clip.effect)) {
+    errors.push(
+      createIssue(
+        ValidationCodes.INVALID_VALUE,
+        `${path}.effect`,
+        `Invalid effect '${clip.effect}'. Expected: ${EFFECT_TYPES.join(", ")}`,
+        clip.effect
+      )
+    );
+  }
+
+  if (clip.fadeIn != null) {
+    validateFiniteNumber(clip.fadeIn, `${path}.fadeIn`, errors, { min: 0 });
+  }
+  if (clip.fadeOut != null) {
+    validateFiniteNumber(clip.fadeOut, `${path}.fadeOut`, errors, { min: 0 });
+  }
+  if (clip.easing != null && !EFFECT_EASING.includes(clip.easing)) {
+    errors.push(
+      createIssue(
+        ValidationCodes.INVALID_VALUE,
+        `${path}.easing`,
+        `Invalid easing '${clip.easing}'. Expected: ${EFFECT_EASING.join(", ")}`,
+        clip.easing
+      )
+    );
+  }
+
+  if (typeof clip.position === "number" && typeof clip.end === "number") {
+    const duration = clip.end - clip.position;
+    const fadeTotal = (clip.fadeIn || 0) + (clip.fadeOut || 0);
+    if (fadeTotal > duration + 1e-9) {
+      errors.push(
+        createIssue(
+          ValidationCodes.INVALID_TIMELINE,
+          `${path}`,
+          `fadeIn + fadeOut (${fadeTotal}) must be <= clip duration (${duration})`,
+          { fadeIn: clip.fadeIn || 0, fadeOut: clip.fadeOut || 0, duration }
+        )
+      );
+    }
+  }
+
+  if (
+    clip.params == null ||
+    typeof clip.params !== "object" ||
+    Array.isArray(clip.params)
+  ) {
+    errors.push(
+      createIssue(
+        ValidationCodes.MISSING_REQUIRED,
+        `${path}.params`,
+        "params is required and must be an object for effect clips",
+        clip.params
+      )
+    );
+    return;
+  }
+
+  const params = clip.params;
+  if (params.amount != null) {
+    validateFiniteNumber(params.amount, `${path}.params.amount`, errors, {
+      min: 0,
+      max: 1,
+    });
+  }
+
+  if (clip.effect === "vignette") {
+    if (params.angle != null) {
+      validateFiniteNumber(params.angle, `${path}.params.angle`, errors, {
+        min: 0,
+        max: 6.283185307179586,
+      });
+    }
+  } else if (clip.effect === "filmGrain") {
+    if (params.temporal != null && typeof params.temporal !== "boolean") {
+      errors.push(
+        createIssue(
+          ValidationCodes.INVALID_VALUE,
+          `${path}.params.temporal`,
+          "temporal must be a boolean",
+          params.temporal
+        )
+      );
+    }
+  } else if (clip.effect === "gaussianBlur") {
+    if (params.sigma != null) {
+      validateFiniteNumber(params.sigma, `${path}.params.sigma`, errors, {
+        min: 0,
+        max: 100,
+      });
+    }
+  } else if (clip.effect === "colorAdjust") {
+    if (params.brightness != null) {
+      validateFiniteNumber(params.brightness, `${path}.params.brightness`, errors, {
+        min: -1,
+        max: 1,
+      });
+    }
+    if (params.contrast != null) {
+      validateFiniteNumber(params.contrast, `${path}.params.contrast`, errors, {
+        min: 0,
+        max: 3,
+      });
+    }
+    if (params.saturation != null) {
+      validateFiniteNumber(params.saturation, `${path}.params.saturation`, errors, {
+        min: 0,
+        max: 3,
+      });
+    }
+    if (params.gamma != null) {
+      validateFiniteNumber(params.gamma, `${path}.params.gamma`, errors, {
+        min: 0.1,
+        max: 10,
+      });
+    }
+  }
+}
+
 /**
  * Validate a single clip and return issues
  */
@@ -52,6 +290,8 @@ function validateClip(clip, index, options = {}) {
     "backgroundAudio",
     "image",
     "subtitle",
+    "color",
+    "effect",
   ];
 
   // Check type
@@ -123,7 +363,7 @@ function validateClip(clip, index, options = {}) {
   }
 
   // Types that require position/end on timeline
-  const requiresTimeline = ["video", "audio", "text", "image"].includes(
+  const requiresTimeline = ["video", "audio", "text", "image", "color", "effect"].includes(
     clip.type
   );
 
@@ -525,6 +765,29 @@ function validateClip(clip, index, options = {}) {
         );
       }
     }
+
+    // Validate text clip color properties
+    const textColorProps = [
+      "fontColor",
+      "borderColor",
+      "shadowColor",
+      "backgroundColor",
+      "highlightColor",
+    ];
+    for (const prop of textColorProps) {
+      if (clip[prop] != null && typeof clip[prop] === "string") {
+        if (!isValidFFmpegColor(clip[prop])) {
+          warnings.push(
+            createIssue(
+              ValidationCodes.INVALID_VALUE,
+              `${path}.${prop}`,
+              `Invalid color "${clip[prop]}". Use a named color (e.g. "white", "red"), hex (#RRGGBB), or color@alpha (e.g. "black@0.5").`,
+              clip[prop]
+            )
+          );
+        }
+      }
+    }
   }
 
   // Subtitle clip validation
@@ -583,6 +846,23 @@ function validateClip(clip, index, options = {}) {
         )
       );
     }
+
+    // Validate subtitle color properties
+    const subtitleColorProps = ["fontColor", "borderColor"];
+    for (const prop of subtitleColorProps) {
+      if (clip[prop] != null && typeof clip[prop] === "string") {
+        if (!isValidFFmpegColor(clip[prop])) {
+          warnings.push(
+            createIssue(
+              ValidationCodes.INVALID_VALUE,
+              `${path}.${prop}`,
+              `Invalid color "${clip[prop]}". Use a named color (e.g. "white", "red"), hex (#RRGGBB), or color@alpha (e.g. "black@0.5").`,
+              clip[prop]
+            )
+          );
+        }
+      }
+    }
   }
 
   // Image clip validation
@@ -595,9 +875,13 @@ function validateClip(clip, index, options = {}) {
         "pan-right",
         "pan-up",
         "pan-down",
+        "smart",
+        "custom",
       ];
       const kbType =
-        typeof clip.kenBurns === "string" ? clip.kenBurns : clip.kenBurns.type;
+        typeof clip.kenBurns === "string"
+          ? clip.kenBurns
+          : clip.kenBurns.type;
       if (kbType && !validKenBurns.includes(kbType)) {
         errors.push(
           createIssue(
@@ -611,6 +895,105 @@ function validateClip(clip, index, options = {}) {
         );
       }
 
+      if (typeof clip.kenBurns === "object") {
+        const {
+          anchor,
+          easing,
+          startZoom,
+          endZoom,
+          startX,
+          startY,
+          endX,
+          endY,
+        } =
+          clip.kenBurns;
+        if (anchor !== undefined) {
+          const validAnchors = ["top", "bottom", "left", "right"];
+          if (!validAnchors.includes(anchor)) {
+            errors.push(
+              createIssue(
+                ValidationCodes.INVALID_VALUE,
+                `${path}.kenBurns.anchor`,
+                `Invalid kenBurns anchor '${anchor}'. Expected: ${validAnchors.join(
+                  ", "
+                )}`,
+                anchor
+              )
+            );
+          }
+        }
+
+        if (easing !== undefined) {
+          const validEasing = ["linear", "ease-in", "ease-out", "ease-in-out"];
+          if (!validEasing.includes(easing)) {
+            errors.push(
+              createIssue(
+                ValidationCodes.INVALID_VALUE,
+                `${path}.kenBurns.easing`,
+                `Invalid kenBurns easing '${easing}'. Expected: ${validEasing.join(
+                  ", "
+                )}`,
+                easing
+              )
+            );
+          }
+        }
+
+        const numericFields = [
+          ["startZoom", startZoom],
+          ["endZoom", endZoom],
+          ["startX", startX],
+          ["startY", startY],
+          ["endX", endX],
+          ["endY", endY],
+        ];
+
+        numericFields.forEach(([field, value]) => {
+          if (value === undefined) {
+            return;
+          }
+          if (typeof value !== "number" || !Number.isFinite(value)) {
+            errors.push(
+              createIssue(
+                ValidationCodes.INVALID_TYPE,
+                `${path}.kenBurns.${field}`,
+                `kenBurns.${field} must be a finite number`,
+                value
+              )
+            );
+            return;
+          }
+
+          if ((field === "startZoom" || field === "endZoom") && value <= 0) {
+            errors.push(
+              createIssue(
+                ValidationCodes.INVALID_RANGE,
+                `${path}.kenBurns.${field}`,
+                `kenBurns.${field} must be > 0`,
+                value
+              )
+            );
+          }
+
+          if (
+            (field === "startX" ||
+              field === "startY" ||
+              field === "endX" ||
+              field === "endY") &&
+            (value < 0 || value > 1)
+          ) {
+            errors.push(
+              createIssue(
+                ValidationCodes.INVALID_RANGE,
+                `${path}.kenBurns.${field}`,
+                `kenBurns.${field} must be between 0 and 1`,
+                value
+              )
+            );
+          }
+        });
+      }
+
       // Check if image dimensions are provided and sufficient for project dimensions
       // By default, undersized images are upscaled automatically (with a warning)
       // Set strictKenBurns: true to make this an error instead
@@ -651,8 +1034,95 @@ function validateClip(clip, index, options = {}) {
     }
   }
 
-  // Video transition validation
-  if (clip.type === "video" && clip.transition) {
+  // Color clip validation
+  if (clip.type === "color") {
+    if (clip.color == null) {
+      errors.push(
+        createIssue(
+          ValidationCodes.MISSING_REQUIRED,
+          `${path}.color`,
+          "Color is required for color clips",
+          clip.color
+        )
+      );
+    } else if (typeof clip.color === "string") {
+      if (!isValidFFmpegColor(clip.color)) {
+        errors.push(
+          createIssue(
+            ValidationCodes.INVALID_VALUE,
+            `${path}.color`,
+            `Invalid color "${clip.color}". Use a named color (e.g. "black", "navy"), hex (#RRGGBB, 0xRRGGBB), or "random".`,
+            clip.color
+          )
+        );
+      }
+    } else if (typeof clip.color === "object" && clip.color !== null) {
+      const validGradientTypes = ["linear-gradient", "radial-gradient"];
+      if (!clip.color.type || !validGradientTypes.includes(clip.color.type)) {
+        errors.push(
+          createIssue(
+            ValidationCodes.INVALID_VALUE,
+            `${path}.color.type`,
+            `Invalid gradient type '${clip.color.type}'. Expected: ${validGradientTypes.join(", ")}`,
+            clip.color.type
+          )
+        );
+      }
+      if (!Array.isArray(clip.color.colors) || clip.color.colors.length < 2) {
+        errors.push(
+          createIssue(
+            ValidationCodes.INVALID_VALUE,
+            `${path}.color.colors`,
+            "Gradient colors must be an array of at least 2 color strings",
+            clip.color.colors
+          )
+        );
+      } else {
+        clip.color.colors.forEach((c, ci) => {
+          if (typeof c !== "string" || !isValidFFmpegColor(c)) {
+            errors.push(
+              createIssue(
+                ValidationCodes.INVALID_VALUE,
+                `${path}.color.colors[${ci}]`,
+                `Invalid gradient color "${c}". Use a named color (e.g. "black", "navy"), hex (#RRGGBB), or "random".`,
+                c
+              )
+            );
+          }
+        });
+      }
+      if (clip.color.direction != null) {
+        const validDirections = ["vertical", "horizontal"];
+        if (typeof clip.color.direction !== "number" && !validDirections.includes(clip.color.direction)) {
+          errors.push(
+            createIssue(
+              ValidationCodes.INVALID_VALUE,
+              `${path}.color.direction`,
+              `Invalid gradient direction '${clip.color.direction}'. Expected: "vertical", "horizontal", or a number (angle in degrees)`,
+              clip.color.direction
+            )
+          );
+        }
+      }
+    } else {
+      errors.push(
+        createIssue(
+          ValidationCodes.INVALID_VALUE,
+          `${path}.color`,
+          "Color must be a string (flat color) or an object (gradient spec)",
+          clip.color
+        )
+      );
+    }
+  }
+
+  if (clip.type === "effect") {
+    validateEffectClip(clip, path, errors);
+  }
+
+  // Visual clip transition validation (video, image, color)
+  const visualTypes = ["video", "image", "color"];
+  if (visualTypes.includes(clip.type) && clip.transition) {
     if (typeof clip.transition.duration !== "number") {
       errors.push(
         createIssue(
@@ -687,65 +1157,60 @@ function validateClip(clip, index, options = {}) {
 }
 
 /**
- * Validate timeline gaps (visual continuity)
+ * Validate timeline gaps (visual continuity).
+ * Uses detectVisualGaps() from gaps.js as the single source of truth
+ * for gap detection logic.
  */
-function validateTimelineGaps(clips, options = {}) {
-  const { fillGaps = "none" } = options;
+function validateTimelineGaps(clips) {
   const errors = [];
 
-  // Skip gap checking if fillGaps is enabled
-  if (fillGaps !== "none") {
+  // Build clip objects with original indices for error messages
+  const indexed = clips.map((c, i) => ({ ...c, _origIndex: i }));
+  const gaps = detectVisualGaps(indexed);
+
+  if (gaps.length === 0) {
     return { errors, warnings: [] };
   }
 
-  // Get visual clips (video and image)
+  // Build a sorted visual clip list so we can reference neighbours in messages
   const visual = clips
     .map((c, i) => ({ clip: c, index: i }))
-    .filter(({ clip }) => clip.type === "video" || clip.type === "image")
+    .filter(({ clip }) => clip.type === "video" || clip.type === "image" || clip.type === "color")
     .filter(
       ({ clip }) =>
         typeof clip.position === "number" && typeof clip.end === "number"
     )
     .sort((a, b) => a.clip.position - b.clip.position);
 
-  if (visual.length === 0) {
-    return { errors, warnings: [] };
-  }
-
-  const eps = 1e-3;
-
-  // Check for leading gap
-  if (visual[0].clip.position > eps) {
-    errors.push(
-      createIssue(
-        ValidationCodes.TIMELINE_GAP,
-        "timeline",
-        `Gap at start of timeline [0, ${visual[0].clip.position.toFixed(
-          3
-        )}s] - no video/image content. Use fillGaps: 'black' to auto-fill.`,
-        { start: 0, end: visual[0].clip.position }
-      )
-    );
-  }
+  for (const gap of gaps) {
+    const isLeading = gap.start === 0 || (visual.length > 0 && gap.end <= visual[0].clip.position + 1e-3);
 
-  // Check for gaps between clips
-  for (let i = 1; i < visual.length; i++) {
-    const prev = visual[i - 1].clip;
-    const curr = visual[i].clip;
-    const gapStart = prev.end;
-    const gapEnd = curr.position;
+    if (isLeading && gap.start < 1e-3) {
+      errors.push(
+        createIssue(
+          ValidationCodes.TIMELINE_GAP,
+          "timeline",
+          `Gap at start of visual timeline [0, ${gap.end.toFixed(
+            3
+          )}s]. If intentional, fill it with a { type: "color" } clip. Otherwise, start your first clip at position 0.`,
+          { start: gap.start, end: gap.end }
+        )
+      );
+    } else {
+      // Find the surrounding clip indices for a helpful message
+      const before = visual.filter(v => v.clip.end <= gap.start + 1e-3);
+      const after = visual.filter(v => v.clip.position >= gap.end - 1e-3);
+      const prevIdx = before.length > 0 ? before[before.length - 1].index : "?";
+      const nextIdx = after.length > 0 ? after[0].index : "?";
 
-    if (gapEnd - gapStart > eps) {
       errors.push(
         createIssue(
           ValidationCodes.TIMELINE_GAP,
           "timeline",
-          `Gap in timeline [${gapStart.toFixed(3)}s, ${gapEnd.toFixed(
+          `Gap in visual timeline [${gap.start.toFixed(3)}s, ${gap.end.toFixed(
             3
-          )}s] between clips[${visual[i - 1].index}] and clips[${
-            visual[i].index
-          }]. Use fillGaps: 'black' to auto-fill.`,
-          { start: gapStart, end: gapEnd }
+          )}s] between clips[${prevIdx}] and clips[${nextIdx}]. If intentional, fill it with a { type: "color" } clip. Otherwise, adjust clip positions to remove the gap.`,
+          { start: gap.start, end: gap.end }
         )
       );
     }
@@ -760,7 +1225,6 @@ function validateTimelineGaps(clips, options = {}) {
  * @param {Array} clips - Array of clip objects to validate
  * @param {Object} options - Validation options
  * @param {boolean} options.skipFileChecks - Skip file existence checks (useful for AI validation)
- * @param {string} options.fillGaps - Gap handling mode ('none' | 'black')
  * @returns {Object} Validation result { valid, errors, warnings }
  */
 function validateConfig(clips, options = {}) {
@@ -845,4 +1309,6 @@ module.exports = {
   validateConfig,
   formatValidationResult,
   ValidationCodes,
+  isValidFFmpegColor,
+  FFMPEG_NAMED_COLORS,
 };

package/src/ffmpeg/audio_builder.js

@@ -11,7 +11,9 @@ function buildAudioForVideoClips(project, videoClips, transitionOffsets) {
 
   videoClips.forEach((clip) => {
     if (!clip.hasAudio) return;
-    const inputIndex = project.videoOrAudioClips.indexOf(clip);
+    const inputIndex = project._inputIndexMap
+      ? project._inputIndexMap.get(clip)
+      : project.videoOrAudioClips.indexOf(clip);
     const requestedDuration = Math.max(
       0,
       (clip.end || 0) - (clip.position || 0)

package/src/ffmpeg/bgm_builder.js

@@ -29,7 +29,9 @@ function buildBackgroundMusicMix(
   let filter = "";
   const bgLabels = [];
   backgroundClips.forEach((clip, i) => {
-    const inputIndex = project.videoOrAudioClips.indexOf(clip);
+    const inputIndex = project._inputIndexMap
+      ? project._inputIndexMap.get(clip)
+      : project.videoOrAudioClips.indexOf(clip);
     const effectivePosition =
       typeof clip.position === "number" ? clip.position : 0;
     const effectiveEnd =