simple-ffmpegjs 0.3.5 → 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,
@@ -55,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} options.fillGaps - Gap handling: 'none' or 'black' (default: 'none')
    *
    * @example
    * const project = new SIMPLEFFMPEG({ preset: 'tiktok' });
@@ -64,8 +64,7 @@ class SIMPLEFFMPEG {
    * const project = new SIMPLEFFMPEG({
    *   width: 1920,
    *   height: 1080,
-   *   fps: 30,
-   *   fillGaps: 'black'
+   *   fps: 30
    * });
    */
   constructor(options = {}) {
@@ -87,12 +86,12 @@ class SIMPLEFFMPEG {
       width: options.width || presetConfig.width || C.DEFAULT_WIDTH,
       height: options.height || presetConfig.height || C.DEFAULT_HEIGHT,
       validationMode: options.validationMode || C.DEFAULT_VALIDATION_MODE,
-      fillGaps: options.fillGaps || "none", // 'none' | 'black'
       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
@@ -105,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}"`;
         }
@@ -188,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
@@ -223,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,
       });
@@ -255,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);
@@ -271,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);
           }
@@ -381,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"
@@ -397,7 +425,7 @@ class SIMPLEFFMPEG {
     let hasVideo = false;
     let hasAudio = false;
 
-    const totalVideoDuration = (() => {
+    let totalVideoDuration = (() => {
       if (videoClips.length === 0) return 0;
       const baseSum = videoClips.reduce(
         (acc, c) => acc + Math.max(0, (c.end || 0) - (c.position || 0)),
@@ -425,7 +453,8 @@ class SIMPLEFFMPEG {
       )
       .map((c) => (typeof c.end === "number" ? c.end : 0));
     const bgOrAudioEnd = audioEnds.length > 0 ? Math.max(...audioEnds) : 0;
-    const finalVisualEnd =
+
+    let finalVisualEnd =
       videoClips.length > 0
         ? Math.max(...videoClips.map((c) => c.end))
         : Math.max(textEnd, bgOrAudioEnd);
@@ -436,6 +465,27 @@ class SIMPLEFFMPEG {
       filterComplex += vres.filter;
       finalVideoLabel = vres.finalVideoLabel;
       hasVideo = vres.hasVideo;
+
+      // 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
+      ) {
+        finalVisualEnd = vres.videoDuration;
+      }
+    }
+
+    // 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)
@@ -461,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
@@ -1119,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} options.fillGaps - Gap handling ('none' | 'black') - affects gap validation
    * @returns {Object} Validation result { valid, errors, warnings }
    *
    * @example
@@ -1166,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;
@@ -1379,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;
@@ -88,16 +90,37 @@ declare namespace SIMPLEFFMPEG {
     loop?: boolean;
   }
 
+  type KenBurnsEffect =
+    | "zoom-in"
+    | "zoom-out"
+    | "pan-left"
+    | "pan-right"
+    | "pan-up"
+    | "pan-down"
+    | "smart"
+    | "custom";
+
+  type KenBurnsAnchor = "top" | "bottom" | "left" | "right";
+  type KenBurnsEasing = "linear" | "ease-in" | "ease-out" | "ease-in-out";
+
+  interface KenBurnsSpec {
+    type?: KenBurnsEffect;
+    startZoom?: number;
+    endZoom?: number;
+    startX?: number;
+    startY?: number;
+    endX?: number;
+    endY?: number;
+    anchor?: KenBurnsAnchor;
+    easing?: KenBurnsEasing;
+  }
+
   interface ImageClip extends BaseClip {
     type: "image";
     url: string;
-    kenBurns?:
-      | "zoom-in"
-      | "zoom-out"
-      | "pan-left"
-      | "pan-right"
-      | "pan-up"
-      | "pan-down";
+    width?: number;
+    height?: number;
+    kenBurns?: KenBurnsEffect | KenBurnsSpec;
   }
 
   type TextMode = "static" | "word-replace" | "word-sequential" | "karaoke";
@@ -199,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;
 
@@ -276,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 */
-    fillGaps?: "none" | "black";
     /** Project width - used to validate Ken Burns images are large enough */
     width?: number;
     /** Project height - used to validate Ken Burns images are large enough */
@@ -297,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' throws error, 'black' fills with black frames (default: 'none') */
-    fillGaps?: "none" | "black";
   }
 
   /** Log entry passed to onLog callback */
@@ -539,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;
@@ -88,16 +90,37 @@ declare namespace SIMPLEFFMPEG {
     loop?: boolean;
   }
 
+  type KenBurnsEffect =
+    | "zoom-in"
+    | "zoom-out"
+    | "pan-left"
+    | "pan-right"
+    | "pan-up"
+    | "pan-down"
+    | "smart"
+    | "custom";
+
+  type KenBurnsAnchor = "top" | "bottom" | "left" | "right";
+  type KenBurnsEasing = "linear" | "ease-in" | "ease-out" | "ease-in-out";
+
+  interface KenBurnsSpec {
+    type?: KenBurnsEffect;
+    startZoom?: number;
+    endZoom?: number;
+    startX?: number;
+    startY?: number;
+    endX?: number;
+    endY?: number;
+    anchor?: KenBurnsAnchor;
+    easing?: KenBurnsEasing;
+  }
+
   interface ImageClip extends BaseClip {
     type: "image";
     url: string;
-    kenBurns?:
-      | "zoom-in"
-      | "zoom-out"
-      | "pan-left"
-      | "pan-right"
-      | "pan-up"
-      | "pan-down";
+    width?: number;
+    height?: number;
+    kenBurns?: KenBurnsEffect | KenBurnsSpec;
   }
 
   type TextMode = "static" | "word-replace" | "word-sequential" | "karaoke";
@@ -199,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;
 
@@ -276,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 */
-    fillGaps?: "none" | "black";
     /** Project width - used to validate Ken Burns images are large enough */
     width?: number;
     /** Project height - used to validate Ken Burns images are large enough */
@@ -297,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' throws error, 'black' fills with black frames (default: 'none') */
-    fillGaps?: "none" | "black";
   }
 
   /** Log entry passed to onLog callback */
@@ -636,6 +737,8 @@ declare namespace SIMPLEFFMPEG {
     | "video"
     | "audio"
     | "image"
+    | "color"
+    | "effect"
     | "text"
     | "subtitle"
     | "music";