simple-ffmpegjs 0.3.6 → 0.4.1

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,130 @@ 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"
+    | "sepia"
+    | "blackAndWhite"
+    | "sharpen"
+    | "chromaticAberration"
+    | "letterbox";
+
+  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 {
+    /** Noise intensity 0-1 (default: 0.35). Independent from blend amount. */
+    strength?: number;
+    /** 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;
+  }
+
+  interface SepiaEffectParams extends EffectParamsBase {}
+
+  interface BlackAndWhiteEffectParams extends EffectParamsBase {
+    /** Optional contrast boost (default: 1, range 0-3) */
+    contrast?: number;
+  }
+
+  interface SharpenEffectParams extends EffectParamsBase {
+    /** Unsharp amount (default: 1.0, range 0-3) */
+    strength?: number;
+  }
+
+  interface ChromaticAberrationEffectParams extends EffectParamsBase {
+    /** Horizontal pixel offset for R/B channels (default: 4, range 0-20) */
+    shift?: number;
+  }
+
+  interface LetterboxEffectParams extends EffectParamsBase {
+    /** Bar height as fraction of frame height (default: 0.12, range 0-0.5) */
+    size?: number;
+    /** Bar color (default: "black") */
+    color?: string;
+  }
+
+  type EffectParams =
+    | VignetteEffectParams
+    | FilmGrainEffectParams
+    | GaussianBlurEffectParams
+    | ColorAdjustEffectParams
+    | SepiaEffectParams
+    | BlackAndWhiteEffectParams
+    | SharpenEffectParams
+    | ChromaticAberrationEffectParams
+    | LetterboxEffectParams;
+
+  /** 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;
+    /** Effect-specific params */
+    params: EffectParams;
+  }
+
   type Clip =
     | VideoClip
     | AudioClip
     | BackgroundMusicClip
     | ImageClip
+    | ColorClip
+    | EffectClip
     | TextClip
     | SubtitleClip;
 
@@ -297,8 +418,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 +437,8 @@ 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;
+    /** Default font file path (.ttf, .otf) applied to all text clips. Individual clips can override this with their own fontFile. */
+    fontFile?: string;
   }
 
   /** Log entry passed to onLog callback */
@@ -657,6 +776,8 @@ declare namespace SIMPLEFFMPEG {
     | "video"
     | "audio"
     | "image"
+    | "color"
+    | "effect"
     | "text"
     | "subtitle"
     | "music";