simple-ffmpegjs 0.3.6 → 0.4.1

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,216 @@ function createIssue(code, path, message, received = undefined) {
   return issue;
 }
 
+const EFFECT_TYPES = [
+  "vignette",
+  "filmGrain",
+  "gaussianBlur",
+  "colorAdjust",
+  "sepia",
+  "blackAndWhite",
+  "sharpen",
+  "chromaticAberration",
+  "letterbox",
+];
+
+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 (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.strength != null) {
+      validateFiniteNumber(params.strength, `${path}.params.strength`, errors, {
+        min: 0,
+        max: 1,
+      });
+    }
+    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,
+      });
+    }
+  } else if (clip.effect === "sepia") {
+    // sepia only uses amount (base param) — no extra params to validate
+  } else if (clip.effect === "blackAndWhite") {
+    if (params.contrast != null) {
+      validateFiniteNumber(params.contrast, `${path}.params.contrast`, errors, {
+        min: 0,
+        max: 3,
+      });
+    }
+  } else if (clip.effect === "sharpen") {
+    if (params.strength != null) {
+      validateFiniteNumber(params.strength, `${path}.params.strength`, errors, {
+        min: 0,
+        max: 3,
+      });
+    }
+  } else if (clip.effect === "chromaticAberration") {
+    if (params.shift != null) {
+      validateFiniteNumber(params.shift, `${path}.params.shift`, errors, {
+        min: 0,
+        max: 20,
+      });
+    }
+  } else if (clip.effect === "letterbox") {
+    if (params.size != null) {
+      validateFiniteNumber(params.size, `${path}.params.size`, errors, {
+        min: 0,
+        max: 0.5,
+      });
+    }
+    if (params.color != null && typeof params.color !== "string") {
+      errors.push(
+        createIssue(
+          ValidationCodes.INVALID_VALUE,
+          `${path}.params.color`,
+          "color must be a string",
+          params.color
+        )
+      );
+    }
+  }
+}
+
 /**
  * Validate a single clip and return issues
  */
@@ -156,6 +334,8 @@ function validateClip(clip, index, options = {}) {
     "backgroundAudio",
     "image",
     "subtitle",
+    "color",
+    "effect",
   ];
 
   // Check type
@@ -227,7 +407,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 +923,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 +1078,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 +1201,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 option (e.g. '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 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 +1269,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 +1354,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 =
@@ -41,15 +43,31 @@ function buildBackgroundMusicMix(
     const adelay = effectivePosition * 1000;
     const trimEnd = effectiveCutFrom + (effectiveEnd - effectivePosition);
     const outLabel = `[bg${i}]`;
-    filter += `[${inputIndex}:a]volume=${effectiveVolume},atrim=start=${effectiveCutFrom}:end=${trimEnd},adelay=${adelay}|${adelay},asetpts=PTS-STARTPTS${outLabel};`;
+    filter += `[${inputIndex}:a]volume=${effectiveVolume},atrim=start=${effectiveCutFrom}:end=${trimEnd},asetpts=PTS-STARTPTS,adelay=${adelay}|${adelay}${outLabel};`;
     bgLabels.push(outLabel);
   });
 
   if (bgLabels.length > 0) {
     if (existingAudioLabel) {
-      filter += `${existingAudioLabel}${bgLabels.join("")}amix=inputs=${
-        bgLabels.length + 1
-      }:duration=longest[finalaudio];`;
+      // Generate a silence anchor from time 0 so that amix starts producing
+      // output immediately. Without this, amix waits for ALL inputs to have
+      // frames before outputting — if the existing audio (e.g. delayed video
+      // audio) starts later on the timeline, background music is silenced
+      // until that point.
+      const anchorDur = Math.max(projectDuration, visualEnd || 0, 0.1);
+      const padLabel = "[_bgmpad]";
+      filter += `anullsrc=cl=stereo,atrim=end=${anchorDur}${padLabel};`;
+
+      // Use normalize=0 with explicit weights so the silence anchor
+      // contributes no audio energy while preserving the same volume
+      // balance as a direct amix of the real inputs.
+      const realCount = bgLabels.length + 1; // bgm tracks + existing audio
+      const w = (1 / realCount).toFixed(6);
+      const weights = ["0", ...Array(realCount).fill(w)].join(" ");
+
+      filter += `${padLabel}${existingAudioLabel}${bgLabels.join("")}amix=inputs=${
+        bgLabels.length + 2
+      }:duration=longest:weights='${weights}':normalize=0[finalaudio];`;
       return { filter, finalAudioLabel: "[finalaudio]", hasAudio: true };
     }
     filter += `${bgLabels.join("")}amix=inputs=${