simple-ffmpegjs 0.3.6 → 0.4.0

package/src/core/validation.js

@@ -1,4 +1,5 @@
 const fs = require("fs");
+const { detectVisualGaps } = require("./gaps");
 
 // ========================================================================
 // FFmpeg named colors (X11/CSS color names accepted by libavutil)
@@ -71,39 +72,6 @@ function isValidFFmpegColor(value) {
   return FFMPEG_NAMED_COLORS.has(color.toLowerCase());
 }
 
-/**
- * Normalise a fillGaps option value to either "none" (disabled) or a
- * valid FFmpeg color string.
- *
- * Accepted inputs:
- *   - false / "none" / "off" / undefined → "none"
- *   - true                               → "black"
- *   - "black", "red", "#FF0000", …       → the color string (validated)
- *
- * @param {*} value - Raw fillGaps option value
- * @returns {{ color: string|null, error: string|null }}
- *   color is the normalised value ("none" when disabled), error is a
- *   human-readable message when the value is invalid.
- */
-function normalizeFillGaps(value) {
-  if (value === undefined || value === null || value === false || value === "none" || value === "off") {
-    return { color: "none", error: null };
-  }
-  if (value === true) {
-    return { color: "black", error: null };
-  }
-  if (typeof value !== "string") {
-    return { color: null, error: `fillGaps must be a string color value, boolean, or "none" — got ${typeof value}` };
-  }
-  if (!isValidFFmpegColor(value)) {
-    return {
-      color: null,
-      error: `fillGaps color "${value}" is not a recognised FFmpeg color. Use a named color (e.g. "black", "red", "navy"), hex (#RRGGBB, 0xRRGGBB), or "random".`,
-    };
-  }
-  return { color: value, error: null };
-}
-
 /**
  * Error/warning codes for programmatic handling
  */
@@ -138,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
  */
@@ -156,6 +290,8 @@ function validateClip(clip, index, options = {}) {
     "backgroundAudio",
     "image",
     "subtitle",
+    "color",
+    "effect",
   ];
 
   // Check type
@@ -227,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
   );
 
@@ -743,7 +879,9 @@ function validateClip(clip, index, options = {}) {
         "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(
@@ -896,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(
@@ -932,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;
+  for (const gap of gaps) {
+    const isLeading = gap.start === 0 || (visual.length > 0 && gap.end <= visual[0].clip.position + 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 option (e.g. 'black') to auto-fill.`,
-        { start: 0, end: visual[0].clip.position }
-      )
-    );
-  }
-
-  // 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 option (e.g. '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 }
         )
       );
     }
@@ -1005,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 = {}) {
@@ -1091,6 +1310,5 @@ module.exports = {
   formatValidationResult,
   ValidationCodes,
   isValidFFmpegColor,
-  normalizeFillGaps,
   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 =

package/src/ffmpeg/effect_builder.js

@@ -0,0 +1,138 @@
+function formatNumber(value, decimals = 6) {
+  return Number(value.toFixed(decimals)).toString();
+}
+
+function clamp(value, min, max) {
+  return Math.min(max, Math.max(min, value));
+}
+
+function buildProcessedEffectFilter(effectClip, inputLabel, outputLabel) {
+  const params = effectClip.params || {};
+  const amount = clamp(
+    typeof params.amount === "number" ? params.amount : 1,
+    0,
+    1
+  );
+
+  if (effectClip.effect === "vignette") {
+    const angle =
+      typeof params.angle === "number" ? params.angle : Math.PI / 5;
+    return {
+      filter: `${inputLabel}vignette=angle=${formatNumber(angle)}:eval=frame${outputLabel};`,
+      amount,
+    };
+  }
+
+  if (effectClip.effect === "filmGrain") {
+    const grainStrength = clamp(
+      (typeof params.amount === "number" ? params.amount : 0.35) * 100,
+      0,
+      100
+    );
+    const flags = params.temporal === false ? "u" : "t+u";
+    return {
+      filter: `${inputLabel}noise=alls=${formatNumber(
+        grainStrength,
+        3
+      )}:allf=${flags}${outputLabel};`,
+      amount,
+    };
+  }
+
+  if (effectClip.effect === "gaussianBlur") {
+    const sigma = clamp(
+      typeof params.sigma === "number"
+        ? params.sigma
+        : (typeof params.amount === "number" ? params.amount : 0.5) * 20,
+      0,
+      100
+    );
+    return {
+      filter: `${inputLabel}gblur=sigma=${formatNumber(sigma, 4)}${outputLabel};`,
+      amount,
+    };
+  }
+
+  // colorAdjust
+  const brightness =
+    typeof params.brightness === "number" ? params.brightness : 0;
+  const contrast = typeof params.contrast === "number" ? params.contrast : 1;
+  const saturation =
+    typeof params.saturation === "number" ? params.saturation : 1;
+  const gamma = typeof params.gamma === "number" ? params.gamma : 1;
+
+  return {
+    filter:
+      `${inputLabel}eq=` +
+      `brightness=${formatNumber(brightness, 4)}:` +
+      `contrast=${formatNumber(contrast, 4)}:` +
+      `saturation=${formatNumber(saturation, 4)}:` +
+      `gamma=${formatNumber(gamma, 4)}` +
+      `${outputLabel};`,
+    amount,
+  };
+}
+
+function buildEffectFilters(effectClips, inputLabel) {
+  if (!Array.isArray(effectClips) || effectClips.length === 0) {
+    return { filter: "", finalVideoLabel: inputLabel };
+  }
+
+  const ordered = [...effectClips]
+    .filter((c) => typeof c.position === "number" && typeof c.end === "number")
+    .sort((a, b) => {
+      if (a.position !== b.position) return a.position - b.position;
+      return a.end - b.end;
+    });
+
+  if (ordered.length === 0) {
+    return { filter: "", finalVideoLabel: inputLabel };
+  }
+
+  let filter = "";
+  let currentLabel = inputLabel;
+
+  ordered.forEach((clip, i) => {
+    const baseLabel = `[fxbase${i}]`;
+    const procSrcLabel = `[fxsrc${i}]`;
+    const fxLabel = `[fxraw${i}]`;
+    const fxAlphaLabel = `[fxa${i}]`;
+    const outLabel = `[fxout${i}]`;
+
+    // Split current frame stream into base + processed branches so compositing
+    // is deterministic and frame-aligned across all effects.
+    filter += `${currentLabel}split=2${baseLabel}${procSrcLabel};`;
+
+    const { filter: fxFilter, amount } = buildProcessedEffectFilter(
+      clip,
+      procSrcLabel,
+      fxLabel
+    );
+    filter += fxFilter;
+
+    const start = formatNumber(clip.position || 0, 4);
+    const end = formatNumber(clip.end || 0, 4);
+    const fadeIn = Math.max(0, clip.fadeIn || 0);
+    const fadeOut = Math.max(0, clip.fadeOut || 0);
+    const fadeOutStart = Math.max(clip.position || 0, (clip.end || 0) - fadeOut);
+
+    let alphaChain = `format=rgba,colorchannelmixer=aa=${formatNumber(amount, 4)}`;
+    if (fadeIn > 0) {
+      alphaChain += `,fade=t=in:st=${start}:d=${formatNumber(fadeIn, 4)}:alpha=1`;
+    }
+    if (fadeOut > 0) {
+      alphaChain += `,fade=t=out:st=${formatNumber(
+        fadeOutStart,
+        4
+      )}:d=${formatNumber(fadeOut, 4)}:alpha=1`;
+    }
+
+    filter += `${fxLabel}${alphaChain}${fxAlphaLabel};`;
+    filter += `${baseLabel}${fxAlphaLabel}overlay=shortest=1:eof_action=pass:enable='between(t,${start},${end})'${outLabel};`;
+    currentLabel = outLabel;
+  });
+
+  return { filter, finalVideoLabel: currentLabel };
+}
+
+module.exports = { buildEffectFilters };