simple-ffmpegjs 0.3.6 → 0.4.0

package/src/simpleffmpeg.js

@@ -7,6 +7,7 @@ const Loaders = require("./loaders");
 const { buildVideoFilter } = require("./ffmpeg/video_builder");
 const { buildAudioForVideoClips } = require("./ffmpeg/audio_builder");
 const { buildBackgroundMusicMix } = require("./ffmpeg/bgm_builder");
+const { buildEffectFilters } = require("./ffmpeg/effect_builder");
 const {
   getClipAudioString,
   hasProblematicChars,
@@ -16,7 +17,6 @@ const {
   validateConfig,
   formatValidationResult,
   ValidationCodes,
-  normalizeFillGaps,
 } = require("./core/validation");
 const {
   SimpleffmpegError,
@@ -45,7 +45,6 @@ const {
 const { getSchema, getSchemaModules } = require("./schema");
 const { resolveClips } = require("./core/resolve");
 const { probeMedia } = require("./core/media_info");
-const { detectVisualGaps } = require("./core/gaps");
 
 class SIMPLEFFMPEG {
   /**
@@ -57,7 +56,6 @@ class SIMPLEFFMPEG {
    * @param {number} options.fps - Frames per second (default: 30)
    * @param {string} options.preset - Platform preset ('tiktok', 'youtube', 'instagram-post', etc.)
    * @param {string} options.validationMode - Validation behavior: 'warn' or 'strict' (default: 'warn')
-   * @param {string|boolean} options.fillGaps - Gap handling: 'none'/false (disabled), true/'black' (black fill), or any valid FFmpeg color (default: 'none')
    *
    * @example
    * const project = new SIMPLEFFMPEG({ preset: 'tiktok' });
@@ -66,16 +64,7 @@ class SIMPLEFFMPEG {
    * const project = new SIMPLEFFMPEG({
    *   width: 1920,
    *   height: 1080,
-   *   fps: 30,
-   *   fillGaps: 'black'
-   * });
-   *
-   * @example
-   * // Fill gaps with a custom color
-   * const project = new SIMPLEFFMPEG({
-   *   width: 1920,
-   *   height: 1080,
-   *   fillGaps: '#1a1a2e'  // dark blue-gray
+   *   fps: 30
    * });
    */
   constructor(options = {}) {
@@ -91,24 +80,18 @@ class SIMPLEFFMPEG {
       );
     }
 
-    // Normalise and validate fillGaps
-    const fillGapsResult = normalizeFillGaps(options.fillGaps);
-    if (fillGapsResult.error) {
-      throw new ValidationError(fillGapsResult.error);
-    }
-
     // Explicit options override preset values
     this.options = {
       fps: options.fps || presetConfig.fps || C.DEFAULT_FPS,
       width: options.width || presetConfig.width || C.DEFAULT_WIDTH,
       height: options.height || presetConfig.height || C.DEFAULT_HEIGHT,
       validationMode: options.validationMode || C.DEFAULT_VALIDATION_MODE,
-      fillGaps: fillGapsResult.color, // "none" | valid FFmpeg color
       preset: options.preset || null,
     };
     this.videoOrAudioClips = [];
     this.textClips = [];
     this.subtitleClips = [];
+    this.effectClips = [];
     this.filesToClean = [];
     this._isLoading = false; // Guard against concurrent load() calls
     this._isExporting = false; // Guard against concurrent export() calls
@@ -121,9 +104,15 @@ class SIMPLEFFMPEG {
    */
   _getInputStreams() {
     return this.videoOrAudioClips
+      .filter((clip) => {
+        // Flat color clips use the color= filter source — no file input needed
+        if (clip.type === "color" && clip._isFlatColor) return false;
+        return true;
+      })
       .map((clip) => {
         const escapedUrl = escapeFilePath(clip.url);
-        if (clip.type === "image") {
+        // Gradient color clips and image clips are looped images
+        if (clip.type === "image" || (clip.type === "color" && !clip._isFlatColor)) {
           const duration = Math.max(0, clip.end - clip.position || 0);
           return `-loop 1 -t ${duration} -i "${escapedUrl}"`;
         }
@@ -204,7 +193,7 @@ class SIMPLEFFMPEG {
    * Load clips into the project for processing
    *
    * @param {Array} clipObjs - Array of clip configuration objects
-   * @param {string} clipObjs[].type - Clip type: 'video', 'audio', 'image', 'text', 'music', 'backgroundAudio', 'subtitle'
+   * @param {string} clipObjs[].type - Clip type: 'video', 'audio', 'image', 'color', 'text', 'effect', 'music', 'backgroundAudio', 'subtitle'
    * @param {string} clipObjs[].url - Media file path (required for video, audio, image, music, subtitle)
    * @param {number} clipObjs[].position - Start time on timeline in seconds
    * @param {number} clipObjs[].end - End time on timeline in seconds
@@ -239,7 +228,6 @@ class SIMPLEFFMPEG {
 
       // Merge resolution errors into validation
       const result = validateConfig(resolved.clips, {
-        fillGaps: this.options.fillGaps,
         width: this.options.width,
         height: this.options.height,
       });
@@ -271,12 +259,16 @@ class SIMPLEFFMPEG {
           if (clipObj.type === "video" || clipObj.type === "audio") {
             clipObj.volume = clipObj.volume != null ? clipObj.volume : 1;
             clipObj.cutFrom = clipObj.cutFrom || 0;
-            if (clipObj.type === "video" && clipObj.transition) {
-              clipObj.transition = {
-                type: clipObj.transition.type || clipObj.transition,
-                duration: clipObj.transition.duration || 0.5,
-              };
-            }
+          }
+          // Normalize transitions for all visual clip types
+          if (
+            (clipObj.type === "video" || clipObj.type === "image" || clipObj.type === "color") &&
+            clipObj.transition
+          ) {
+            clipObj.transition = {
+              type: clipObj.transition.type || clipObj.transition,
+              duration: clipObj.transition.duration || 0.5,
+            };
           }
           if (clipObj.type === "video") {
             return Loaders.loadVideo(this, clipObj);
@@ -287,9 +279,15 @@ class SIMPLEFFMPEG {
           if (clipObj.type === "text") {
             return Loaders.loadText(this, clipObj);
           }
+          if (clipObj.type === "effect") {
+            return Loaders.loadEffect(this, clipObj);
+          }
           if (clipObj.type === "image") {
             return Loaders.loadImage(this, clipObj);
           }
+          if (clipObj.type === "color") {
+            return Loaders.loadColor(this, clipObj);
+          }
           if (clipObj.type === "music" || clipObj.type === "backgroundAudio") {
             return Loaders.loadBackgroundAudio(this, clipObj);
           }
@@ -397,8 +395,22 @@ class SIMPLEFFMPEG {
       })
     );
 
+    // Build a mapping from clip to its FFmpeg input stream index.
+    // Flat color clips use the color= filter source and do not have file inputs,
+    // so they are skipped by _getInputStreams(). All other clips' indices must
+    // account for this offset.
+    this._inputIndexMap = new Map();
+    let _inputIdx = 0;
+    for (const clip of this.videoOrAudioClips) {
+      if (clip.type === "color" && clip._isFlatColor) {
+        continue; // No file input for flat color clips
+      }
+      this._inputIndexMap.set(clip, _inputIdx);
+      _inputIdx++;
+    }
+
     const videoClips = this.videoOrAudioClips.filter(
-      (clip) => clip.type === "video" || clip.type === "image"
+      (clip) => clip.type === "video" || clip.type === "image" || clip.type === "color"
     );
     const audioClips = this.videoOrAudioClips.filter(
       (clip) => clip.type === "audio"
@@ -442,56 +454,6 @@ class SIMPLEFFMPEG {
       .map((c) => (typeof c.end === "number" ? c.end : 0));
     const bgOrAudioEnd = audioEnds.length > 0 ? Math.max(...audioEnds) : 0;
 
-    // Compute desired timeline end for trailing gap filling.
-    // When fillGaps is enabled, extend the video to cover text/audio clips
-    // that extend past the last visual clip (e.g. ending with text on black).
-    //
-    // The trailing gap duration must be precise so the video output ends
-    // exactly when the last content ends.  Two factors affect this:
-    //
-    // 1. Transition compensation — when active (default), text timestamps
-    //    shift left by the cumulative transition overlap, so the target end
-    //    is the compensated value.  When off, use the raw overall end.
-    //
-    // 2. Existing gaps — leading/middle gaps that will also be filled add
-    //    to the video output but are NOT included in totalVideoDuration.
-    //    We must subtract them so the trailing gap isn't oversized.
-    let timelineEnd;
-    if (this.options.fillGaps !== "none" && videoClips.length > 0) {
-      const visualEnd = Math.max(...videoClips.map((c) => c.end || 0));
-      const overallEnd = Math.max(visualEnd, textEnd, bgOrAudioEnd);
-      if (overallEnd - visualEnd > 1e-3) {
-        // Target output duration depends on whether text is compensated
-        let desiredOutputDuration;
-        if (exportOptions.compensateTransitions && videoClips.length > 1) {
-          const transitionOverlap = this._getTransitionOffsetAt(
-            videoClips,
-            overallEnd
-          );
-          desiredOutputDuration = overallEnd - transitionOverlap;
-        } else {
-          desiredOutputDuration = overallEnd;
-        }
-
-        // Account for existing gaps (leading + middle) that will also be
-        // filled — these add to the video output but aren't reflected in
-        // totalVideoDuration (which only sums clip durations − transitions).
-        const existingGaps = detectVisualGaps(videoClips);
-        const existingGapDuration = existingGaps.reduce(
-          (sum, g) => sum + g.duration,
-          0
-        );
-        const videoOutputBeforeTrailing =
-          totalVideoDuration + existingGapDuration;
-
-        const trailingGapDuration =
-          desiredOutputDuration - videoOutputBeforeTrailing;
-        if (trailingGapDuration > 1e-3) {
-          timelineEnd = visualEnd + trailingGapDuration;
-        }
-      }
-    }
-
     let finalVisualEnd =
       videoClips.length > 0
         ? Math.max(...videoClips.map((c) => c.end))
@@ -499,21 +461,18 @@ class SIMPLEFFMPEG {
 
     // Build video filter
     if (videoClips.length > 0) {
-      const vres = buildVideoFilter(this, videoClips, { timelineEnd });
+      const vres = buildVideoFilter(this, videoClips);
       filterComplex += vres.filter;
       finalVideoLabel = vres.finalVideoLabel;
       hasVideo = vres.hasVideo;
 
-      // Update durations to account for gap fills (including trailing gaps).
-      // videoDuration reflects the actual output length of the video filter
-      // chain, which includes any black gap-fill clips.
-      if (typeof vres.videoDuration === "number" && vres.videoDuration > 0) {
-        totalVideoDuration = vres.videoDuration;
-      }
       // Use the actual video output length for finalVisualEnd so that
       // audio trim and BGM duration match the real video stream length,
       // rather than an original-timeline position that may differ due to
       // transition compression.
+      if (typeof vres.videoDuration === "number" && vres.videoDuration > 0) {
+        totalVideoDuration = vres.videoDuration;
+      }
       if (
         typeof vres.videoDuration === "number" &&
         vres.videoDuration > finalVisualEnd
@@ -522,6 +481,13 @@ class SIMPLEFFMPEG {
       }
     }
 
+    // Overlay effects (adjustment layer clips) on the composed video output.
+    if (this.effectClips.length > 0 && hasVideo && finalVideoLabel) {
+      const effectRes = buildEffectFilters(this.effectClips, finalVideoLabel);
+      filterComplex += effectRes.filter;
+      finalVideoLabel = effectRes.finalVideoLabel || finalVideoLabel;
+    }
+
     // Audio for video clips (aligned amix)
     // Compute cumulative transition offsets so audio adelay values
     // match the xfade-compressed video timeline.
@@ -545,7 +511,9 @@ class SIMPLEFFMPEG {
       let audioString = "";
       let audioConcatInputs = [];
       audioClips.forEach((clip) => {
-        const inputIndex = this.videoOrAudioClips.indexOf(clip);
+        const inputIndex = this._inputIndexMap
+          ? this._inputIndexMap.get(clip)
+          : this.videoOrAudioClips.indexOf(clip);
         const { audioStringPart, audioConcatInput } = getClipAudioString(
           clip,
           inputIndex
@@ -1203,7 +1171,6 @@ class SIMPLEFFMPEG {
    * @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)
-   * @param {string|boolean} options.fillGaps - Gap handling ('none'/false to disable, or any valid FFmpeg color) - affects gap validation
    * @returns {Object} Validation result { valid, errors, warnings }
    *
    * @example
@@ -1250,9 +1217,9 @@ class SIMPLEFFMPEG {
     // Resolve shorthand (duration → end, auto-sequencing)
     const { clips: resolved } = resolveClips(clips);
 
-    // Filter to visual clips (video + image)
+    // Filter to visual clips (video + image + color)
     const visual = resolved.filter(
-      (c) => c.type === "video" || c.type === "image"
+      (c) => c.type === "video" || c.type === "image" || c.type === "color"
     );
 
     if (visual.length === 0) return 0;
@@ -1463,7 +1430,7 @@ class SIMPLEFFMPEG {
    * Get the list of available schema module IDs.
    * Use these IDs with getSchema({ include: [...] }) or getSchema({ exclude: [...] }).
    *
-   * @returns {string[]} Array of module IDs: ['video', 'audio', 'image', 'text', 'subtitle', 'music']
+   * @returns {string[]} Array of module IDs: ['video', 'audio', 'image', 'color', 'effect', 'text', 'subtitle', 'music']
    */
   static getSchemaModules() {
     return getSchemaModules();

package/types/index.d.mts

@@ -51,7 +51,9 @@ declare namespace SIMPLEFFMPEG {
     | "music"
     | "backgroundAudio"
     | "image"
-    | "subtitle";
+    | "subtitle"
+    | "color"
+    | "effect";
 
   interface BaseClip {
     type: ClipType;
@@ -220,11 +222,82 @@ declare namespace SIMPLEFFMPEG {
     opacity?: number;
   }
 
+  /** Gradient specification for color clips */
+  interface GradientSpec {
+    type: "linear-gradient" | "radial-gradient";
+    /** Array of color strings (at least 2). Evenly distributed across the gradient. */
+    colors: string[];
+    /** For linear gradients: "vertical" (default), "horizontal", or angle in degrees */
+    direction?: "vertical" | "horizontal" | number;
+  }
+
+  /** Color clip — solid color or gradient for filling gaps, transitions, etc. */
+  interface ColorClip {
+    type: "color";
+    /** Flat color string (e.g. "black", "#FF0000") or gradient specification */
+    color: string | GradientSpec;
+    /** Start time on timeline in seconds. Omit to auto-sequence after previous visual clip. */
+    position?: number;
+    /** End time on timeline in seconds. Mutually exclusive with duration. */
+    end?: number;
+    /** Duration in seconds (alternative to end). end = position + duration. */
+    duration?: number;
+    /** Transition effect from the previous visual clip */
+    transition?: { type: string; duration: number };
+  }
+
+  type EffectName = "vignette" | "filmGrain" | "gaussianBlur" | "colorAdjust";
+  type EffectEasing = "linear" | "ease-in" | "ease-out" | "ease-in-out";
+
+  interface EffectParamsBase {
+    amount?: number;
+  }
+
+  interface VignetteEffectParams extends EffectParamsBase {
+    angle?: number;
+  }
+
+  interface FilmGrainEffectParams extends EffectParamsBase {
+    temporal?: boolean;
+  }
+
+  interface GaussianBlurEffectParams extends EffectParamsBase {
+    sigma?: number;
+  }
+
+  interface ColorAdjustEffectParams extends EffectParamsBase {
+    brightness?: number;
+    contrast?: number;
+    saturation?: number;
+    gamma?: number;
+  }
+
+  type EffectParams =
+    | VignetteEffectParams
+    | FilmGrainEffectParams
+    | GaussianBlurEffectParams
+    | ColorAdjustEffectParams;
+
+  /** Effect clip — timed overlay adjustment layer over composed video */
+  interface EffectClip {
+    type: "effect";
+    effect: EffectName;
+    position: number;
+    end?: number;
+    duration?: number;
+    fadeIn?: number;
+    fadeOut?: number;
+    easing?: EffectEasing;
+    params: EffectParams;
+  }
+
   type Clip =
     | VideoClip
     | AudioClip
     | BackgroundMusicClip
     | ImageClip
+    | ColorClip
+    | EffectClip
     | TextClip
     | SubtitleClip;
 
@@ -297,8 +370,6 @@ declare namespace SIMPLEFFMPEG {
   interface ValidateOptions {
     /** Skip file existence checks (useful for AI generating configs before files exist) */
     skipFileChecks?: boolean;
-    /** Gap handling mode - affects timeline gap validation. Any valid FFmpeg color, or "none"/false to disable. */
-    fillGaps?: "none" | string | boolean;
     /** Project width - used to validate Ken Burns images are large enough */
     width?: number;
     /** Project height - used to validate Ken Burns images are large enough */
@@ -318,8 +389,6 @@ declare namespace SIMPLEFFMPEG {
     height?: number;
     /** Validation mode: 'warn' logs warnings, 'strict' throws on warnings (default: 'warn') */
     validationMode?: "warn" | "strict";
-    /** How to handle visual gaps: 'none'/false (disabled), true/'black' (black fill), or any valid FFmpeg color name/hex (default: 'none') */
-    fillGaps?: "none" | string | boolean;
   }
 
   /** Log entry passed to onLog callback */
@@ -560,6 +629,8 @@ declare namespace SIMPLEFFMPEG {
     | "video"
     | "audio"
     | "image"
+    | "color"
+    | "effect"
     | "text"
     | "subtitle"
     | "music";

package/types/index.d.ts

@@ -51,7 +51,9 @@ declare namespace SIMPLEFFMPEG {
     | "music"
     | "backgroundAudio"
     | "image"
-    | "subtitle";
+    | "subtitle"
+    | "color"
+    | "effect";
 
   interface BaseClip {
     type: ClipType;
@@ -220,11 +222,93 @@ declare namespace SIMPLEFFMPEG {
     opacity?: number;
   }
 
+  /** Gradient specification for color clips */
+  interface GradientSpec {
+    type: "linear-gradient" | "radial-gradient";
+    /** Array of color strings (at least 2). Evenly distributed across the gradient. */
+    colors: string[];
+    /** For linear gradients: "vertical" (default), "horizontal", or angle in degrees */
+    direction?: "vertical" | "horizontal" | number;
+  }
+
+  /** Color clip — solid color or gradient for filling gaps, transitions, etc. */
+  interface ColorClip {
+    type: "color";
+    /** Flat color string (e.g. "black", "#FF0000") or gradient specification */
+    color: string | GradientSpec;
+    /** Start time on timeline in seconds. Omit to auto-sequence after previous visual clip. */
+    position?: number;
+    /** End time on timeline in seconds. Mutually exclusive with duration. */
+    end?: number;
+    /** Duration in seconds (alternative to end). end = position + duration. */
+    duration?: number;
+    /** Transition effect from the previous visual clip */
+    transition?: { type: string; duration: number };
+  }
+
+  type EffectName = "vignette" | "filmGrain" | "gaussianBlur" | "colorAdjust";
+  type EffectEasing = "linear" | "ease-in" | "ease-out" | "ease-in-out";
+
+  interface EffectParamsBase {
+    /** Base blend amount from 0 to 1 (default: 1) */
+    amount?: number;
+  }
+
+  interface VignetteEffectParams extends EffectParamsBase {
+    /** Vignette angle in radians (default: PI/5) */
+    angle?: number;
+  }
+
+  interface FilmGrainEffectParams extends EffectParamsBase {
+    /** Temporal grain changes every frame (default: true) */
+    temporal?: boolean;
+  }
+
+  interface GaussianBlurEffectParams extends EffectParamsBase {
+    /** Gaussian blur sigma (default derived from amount) */
+    sigma?: number;
+  }
+
+  interface ColorAdjustEffectParams extends EffectParamsBase {
+    brightness?: number;
+    contrast?: number;
+    saturation?: number;
+    gamma?: number;
+  }
+
+  type EffectParams =
+    | VignetteEffectParams
+    | FilmGrainEffectParams
+    | GaussianBlurEffectParams
+    | ColorAdjustEffectParams;
+
+  /** Effect clip — timed overlay adjustment layer over composed video */
+  interface EffectClip {
+    type: "effect";
+    effect: EffectName;
+    /** Start time on timeline in seconds. Required for effect clips. */
+    position: number;
+    /** End time on timeline in seconds. Mutually exclusive with duration. */
+    end?: number;
+    /** Duration in seconds (alternative to end). end = position + duration. */
+    duration?: number;
+    /** Ramp-in duration in seconds */
+    fadeIn?: number;
+    /** Ramp-out duration in seconds */
+    fadeOut?: number;
+    /** Envelope easing for fade ramps */
+    easing?: EffectEasing;
+    /** Effect-specific params */
+    params: EffectParams;
+  }
+
   type Clip =
     | VideoClip
     | AudioClip
     | BackgroundMusicClip
     | ImageClip
+    | ColorClip
+    | EffectClip
     | TextClip
     | SubtitleClip;
 
@@ -297,8 +381,6 @@ declare namespace SIMPLEFFMPEG {
   interface ValidateOptions {
     /** Skip file existence checks (useful for AI generating configs before files exist) */
     skipFileChecks?: boolean;
-    /** Gap handling mode - affects timeline gap validation. Any valid FFmpeg color, or "none"/false to disable. */
-    fillGaps?: "none" | string | boolean;
     /** Project width - used to validate Ken Burns images are large enough */
     width?: number;
     /** Project height - used to validate Ken Burns images are large enough */
@@ -318,8 +400,6 @@ declare namespace SIMPLEFFMPEG {
     height?: number;
     /** Validation mode: 'warn' logs warnings, 'strict' throws on warnings (default: 'warn') */
     validationMode?: "warn" | "strict";
-    /** How to handle visual gaps: 'none'/false (disabled), true/'black' (black fill), or any valid FFmpeg color name/hex (default: 'none') */
-    fillGaps?: "none" | string | boolean;
   }
 
   /** Log entry passed to onLog callback */
@@ -657,6 +737,8 @@ declare namespace SIMPLEFFMPEG {
     | "video"
     | "audio"
     | "image"
+    | "color"
+    | "effect"
     | "text"
     | "subtitle"
     | "music";