simple-ffmpegjs 0.3.5 → 0.4.0

package/README.md

@@ -31,7 +31,7 @@
   - [Logging](#logging)
   - [Error Handling](#error-handling)
   - [Cancellation](#cancellation)
-  - [Gap Handling](#gap-handling)
+  - [Color Clips](#color-clips)
 - [Examples](#examples)
   - [Clips & Transitions](#clips--transitions)
   - [Text & Animations](#text--animations)
@@ -77,7 +77,8 @@ _Click to watch a "Wonders of the World" video created with simple-ffmpeg — co
 - **Image Support** — Ken Burns effects (zoom, pan) for static images
 - **Progress Tracking** — Real-time export progress callbacks
 - **Cancellation** — AbortController support for stopping exports
-- **Gap Handling** — Optional black frame fill for timeline gaps
+- **Color Clips** — Flat colors and gradients (linear, radial) as first-class timeline clips with full transition support
+- **Effect Clips** — Timed overlay effects (vignette, film grain, gaussian blur, color adjustment) with fade-in/out envelopes
 - **Auto-Batching** — Automatically splits complex filter graphs to avoid OS command limits
 - **Schema Export** — Generate a structured description of the clip format for documentation, code generation, or AI context
 - **Pre-Validation** — Validate clip configurations before processing with structured, machine-readable error codes
@@ -237,7 +238,7 @@ const schema = SIMPLEFFMPEG.getSchema({ exclude: ["text", "subtitle"] });
 
 // See all available module IDs
 SIMPLEFFMPEG.getSchemaModules();
-// ['video', 'audio', 'image', 'text', 'subtitle', 'music']
+// ['video', 'audio', 'image', 'color', 'effect', 'text', 'subtitle', 'music']
 ```
 
 Available modules:
@@ -247,6 +248,8 @@ Available modules:
 | `video`    | Video clips, transitions, volume, trimming                  |
 | `audio`    | Standalone audio clips                                      |
 | `image`    | Image clips, Ken Burns effects                              |
+| `color`    | Color clips — flat colors, linear/radial gradients          |
+| `effect`   | Overlay adjustment effects — vignette, grain, blur, grading |
 | `text`     | Text overlays — all modes, animations, positioning, styling |
 | `subtitle` | Subtitle file import (SRT, VTT, ASS, SSA)                   |
 | `music`    | Background music / background audio, looping                |
@@ -284,7 +287,6 @@ new SIMPLEFFMPEG(options?: {
   height?: number;          // Output height (default: 1080)
   fps?: number;             // Frame rate (default: 30)
   validationMode?: 'warn' | 'strict';  // Validation behavior (default: 'warn')
-  fillGaps?: 'none' | 'black';         // Gap handling (default: 'none')
   preset?: string;          // Platform preset (e.g., 'tiktok', 'youtube', 'instagram-post')
 })
 ```
@@ -406,13 +408,13 @@ await SIMPLEFFMPEG.snapshot("./video.mp4", {
 
 **Snapshot Options:**
 
-| Option       | Type     | Default | Description                                                                 |
-| ------------ | -------- | ------- | --------------------------------------------------------------------------- |
-| `outputPath` | `string` | -       | **Required.** Output image path (extension determines format)               |
-| `time`       | `number` | `0`     | Time in seconds to capture the frame at                                     |
-| `width`      | `number` | -       | Output width in pixels (maintains aspect ratio if height omitted)           |
-| `height`     | `number` | -       | Output height in pixels (maintains aspect ratio if width omitted)           |
-| `quality`    | `number` | `2`     | JPEG quality 1-31, lower is better (only applies to `.jpg`/`.jpeg` output)  |
+| Option       | Type     | Default | Description                                                                |
+| ------------ | -------- | ------- | -------------------------------------------------------------------------- |
+| `outputPath` | `string` | -       | **Required.** Output image path (extension determines format)              |
+| `time`       | `number` | `0`     | Time in seconds to capture the frame at                                    |
+| `width`      | `number` | -       | Output width in pixels (maintains aspect ratio if height omitted)          |
+| `height`     | `number` | -       | Output height in pixels (maintains aspect ratio if width omitted)          |
+| `quality`    | `number` | `2`     | JPEG quality 1-31, lower is better (only applies to `.jpg`/`.jpeg` output) |
 
 **Supported formats:** `.jpg` / `.jpeg`, `.png`, `.webp`, `.bmp`, `.tiff`
 
@@ -552,7 +554,78 @@ await project.load([
   position?: number;        // Omit to auto-sequence after previous video/image clip
   end?: number;             // Use end OR duration, not both
   duration?: number;        // Duration in seconds (alternative to end)
-  kenBurns?: "zoom-in" | "zoom-out" | "pan-left" | "pan-right" | "pan-up" | "pan-down";
+  width?: number;           // Optional: source image width (skip probe / override)
+  height?: number;          // Optional: source image height (skip probe / override)
+  kenBurns?:
+    | "zoom-in" | "zoom-out" | "pan-left" | "pan-right" | "pan-up" | "pan-down"
+    | "smart" | "custom"
+    | {
+        type?: "zoom-in" | "zoom-out" | "pan-left" | "pan-right" | "pan-up" | "pan-down" | "smart" | "custom";
+        startZoom?: number;
+        endZoom?: number;
+        startX?: number;     // 0 = left, 1 = right
+        startY?: number;     // 0 = top, 1 = bottom
+        endX?: number;
+        endY?: number;
+        anchor?: "top" | "bottom" | "left" | "right";
+        easing?: "linear" | "ease-in" | "ease-out" | "ease-in-out";
+      };
+}
+```
+
+#### Color Clip
+
+```ts
+{
+  type: "color";
+  color: string | {                // Flat color string or gradient spec
+    type: "linear-gradient" | "radial-gradient";
+    colors: string[];              // 2+ color stops (named, hex, or 0x hex)
+    direction?: "vertical" | "horizontal";  // For linear gradients (default: "vertical")
+  };
+  position?: number;               // Timeline start (seconds). Omit to auto-sequence.
+  end?: number;                    // Timeline end. Use end OR duration, not both.
+  duration?: number;               // Duration in seconds (alternative to end).
+  transition?: {
+    type: string;                  // Any xfade transition (e.g., 'fade', 'wipeleft')
+    duration: number;
+  };
+}
+```
+
+#### Effect Clip
+
+Effects are overlay adjustment layers. They apply to the already-composed video
+for a time window, and can ramp in/out smoothly (instead of appearing instantly):
+
+```ts
+{
+  type: "effect";
+  effect: "vignette" | "filmGrain" | "gaussianBlur" | "colorAdjust";
+  position: number;           // Required timeline start (seconds)
+  end?: number;               // Use end OR duration, not both
+  duration?: number;          // Duration in seconds (alternative to end)
+  fadeIn?: number;            // Optional smooth ramp-in (seconds)
+  fadeOut?: number;           // Optional smooth ramp-out (seconds)
+  easing?: "linear" | "ease-in" | "ease-out" | "ease-in-out"; // default: "linear"
+  params: {
+    amount?: number;          // Blend amount 0..1 (default: 1)
+
+    // vignette
+    angle?: number;           // radians
+
+    // filmGrain
+    temporal?: boolean;       // default: true
+
+    // gaussianBlur
+    sigma?: number;
+
+    // colorAdjust
+    brightness?: number;      // -1..1
+    contrast?: number;        // 0..3
+    saturation?: number;      // 0..3
+    gamma?: number;           // 0.1..10
+  };
 }
 ```
 
@@ -762,7 +835,7 @@ onProgress: ({ percent, phase }) => {
   } else {
     console.log(`${percent}%`);
   }
-}
+};
 ```
 
 ### Logging
@@ -798,10 +871,10 @@ try {
   if (error.name === "ValidationError") {
     // Structured validation errors
     error.errors.forEach((e) =>
-      console.error(`[${e.code}] ${e.path}: ${e.message}`)
+      console.error(`[${e.code}] ${e.path}: ${e.message}`),
     );
     error.warnings.forEach((w) =>
-      console.warn(`[${w.code}] ${w.path}: ${w.message}`)
+      console.warn(`[${w.code}] ${w.path}: ${w.message}`),
     );
   } else if (error.name === "FFmpegError") {
     // Structured details for bug reports (last 50 lines of stderr, command, exitCode)
@@ -837,20 +910,90 @@ try {
 }
 ```
 
-### Gap Handling
+### Color Clips
+
+Color clips let you add flat colors or gradients as first-class visual elements in your timeline. They support transitions, text overlays, and all the same timeline features as video and image clips. Use them for intros, outros, title cards, or anywhere you need a background:
 
-By default, timeline gaps (periods with no video/image content) throw a validation error. Enable automatic black frame fill:
+**Flat color:**
 
 ```ts
-const project = new SIMPLEFFMPEG({
-  fillGaps: "black", // Fill gaps with black frames
-});
+await project.load([
+  // Black intro screen for 2 seconds
+  { type: "color", color: "black", position: 0, end: 2 },
+  // Video starts at 2s
+  { type: "video", url: "./clip.mp4", position: 2, end: 7 },
+]);
+```
+
+`color` accepts any valid FFmpeg color name or hex code:
+
+```ts
+{ type: "color", color: "navy", position: 0, end: 3 }
+{ type: "color", color: "#1a1a2e", position: 0, end: 3 }
+```
 
+**Gradients:**
+
+```ts
+// Linear gradient (vertical by default)
+{
+  type: "color",
+  color: { type: "linear-gradient", colors: ["#0a0a2e", "#4a148c"] },
+  position: 0,
+  end: 4,
+}
+
+// Horizontal linear gradient
+{
+  type: "color",
+  color: { type: "linear-gradient", colors: ["#e74c3c", "#f1c40f", "#2ecc71"], direction: "horizontal" },
+  position: 0,
+  end: 4,
+}
+
+// Radial gradient
+{
+  type: "color",
+  color: { type: "radial-gradient", colors: ["#ff8c00", "#1a0000"] },
+  position: 0,
+  end: 3,
+}
+```
+
+**With transitions:**
+
+Color clips support the same `transition` property as video and image clips:
+
+```ts
 await project.load([
-  { type: "video", url: "./clip.mp4", position: 2, end: 5 }, // Gap from 0-2s filled with black
+  { type: "color", color: "black", position: 0, end: 3 },
+  {
+    type: "video",
+    url: "./main.mp4",
+    position: 3,
+    end: 8,
+    transition: { type: "fade", duration: 0.5 },
+  },
+  {
+    type: "color",
+    color: { type: "radial-gradient", colors: ["#2c3e50", "#000000"] },
+    position: 8,
+    end: 11,
+    transition: { type: "fade", duration: 0.5 },
+  },
+  {
+    type: "text",
+    text: "The End",
+    position: 8.5,
+    end: 10.5,
+    fontSize: 64,
+    fontColor: "white",
+  },
 ]);
 ```
 
+> **Note:** Timeline gaps (periods with no visual content) always produce a validation error. If a gap is intentional, fill it with a `type: "color"` clip or adjust your clip positions to close the gap.
+
 ## Examples
 
 ### Clips & Transitions
@@ -880,9 +1023,43 @@ await project.load([
 ]);
 ```
 
+**Custom Ken Burns (smart anchor + explicit endpoints):**
+
+```ts
+await project.load([
+  {
+    type: "image",
+    url: "./portrait.jpg",
+    duration: 5,
+    kenBurns: {
+      type: "smart",
+      anchor: "bottom",
+      startZoom: 1.05,
+      endZoom: 1.2,
+      easing: "ease-in-out",
+    },
+  },
+  {
+    type: "image",
+    url: "./wide.jpg",
+    duration: 4,
+    kenBurns: {
+      type: "custom",
+      startX: 0.15,
+      startY: 0.7,
+      endX: 0.85,
+      endY: 0.2,
+      easing: "ease-in-out",
+    },
+  },
+]);
+```
+
 When `position` is omitted, clips are placed sequentially — each one starts where the previous one ended. `duration` is an alternative to `end`: the library computes `end = position + duration`. The explicit form (`position: 0, end: 3`) still works identically.
 
 > **Note:** Ken Burns effects work best with images at least as large as your output resolution. Smaller images are automatically upscaled (with a validation warning). Use `strictKenBurns: true` in validation options to enforce size requirements instead.
+> If you pass `width`/`height`, they override probed dimensions (useful for remote or generated images).
+> `smart` mode uses source vs output aspect (when known) to choose pan direction.
 
 ### Text & Animations
 
@@ -1244,7 +1421,7 @@ async function generateVideo(userPrompt, media) {
         `Your previous output had validation errors:\n${errorFeedback}`,
         `\nOriginal request: ${userPrompt}`,
         "\nPlease fix the errors and return the corrected clips array.",
-      ].join("\n")
+      ].join("\n"),
     );
 
     result = SIMPLEFFMPEG.validate(clips, { skipFileChecks: true });
@@ -1254,7 +1431,7 @@ async function generateVideo(userPrompt, media) {
   if (!result.valid) {
     throw new Error(
       `Failed to generate valid config after ${attempts} attempts:\n` +
-        SIMPLEFFMPEG.formatValidationResult(result)
+        SIMPLEFFMPEG.formatValidationResult(result),
     );
   }
 
@@ -1340,44 +1517,33 @@ npm run test:watch
 
 ### Manual Verification
 
-For visual verification of output quality, run the examples script which generates test media and demonstrates all major features:
+For visual verification, run the demo suite to generate sample videos covering all major features. Each demo outputs to its own subfolder under `examples/output/` and includes annotated expected timelines so you know exactly what to look for:
 
 ```bash
+# Run all demos (color clips, effects, transitions, text, Ken Burns, audio, watermarks, karaoke, torture test)
 node examples/run-examples.js
-```
-
-This creates example videos in `examples/output/` covering:
-
-- Basic video concatenation
-- Crossfade transitions
-- Text overlays with animations
-- Background music mixing
-- Ken Burns effects on images
-- Gap filling with black frames
-- Quality settings (CRF, preset)
-- Resolution scaling
-- Metadata embedding
-- Thumbnail generation
-- Complex multi-track compositions
-- Word-by-word text
-- Platform presets (TikTok, YouTube, etc.)
-- Typewriter text animation
-- Scale-in text animation
-- Pulse text animation
-- Fade-out text animation
-- Text watermarks
-- Image watermarks
-- Timed watermarks
-- Karaoke text (word-by-word highlighting)
-- SRT/VTT subtitle import
-
-View the outputs to confirm everything renders correctly:
 
-```bash
-open examples/output/   # macOS
-xdg-open examples/output/   # Linux
+# Run a specific demo by name (partial match)
+node examples/run-examples.js transitions
+node examples/run-examples.js torture ken
 ```
 
+Available demo scripts (can also be run individually):
+
+| Script                          | What it tests                                                                          |
+| ------------------------------- | -------------------------------------------------------------------------------------- |
+| `demo-color-clips.js`           | Flat colors, linear/radial gradients, transitions, full composition with color clips   |
+| `demo-effects-pack-1.js`        | Timed overlay effects (vignette, grain, blur, color adjustment) with smooth ramps      |
+| `demo-transitions.js`           | Fade, wipe, slide, dissolve, fadeblack/white, short/long durations, image transitions  |
+| `demo-text-and-animations.js`   | Positioning, fade, pop, pop-bounce, typewriter, scale-in, pulse, styling, word-replace |
+| `demo-ken-burns.js`             | All 6 presets, smart anchors, custom diagonal, slideshow with transitions              |
+| `demo-audio-mixing.js`          | Volume levels, background music, standalone audio, loop, multi-source mix              |
+| `demo-watermarks.js`            | Text/image watermarks, all positions, timed appearance, styled over transitions        |
+| `demo-karaoke-and-subtitles.js` | Smooth/instant karaoke, word timestamps, multiline, SRT, VTT, mixed text+karaoke       |
+| `demo-torture-test.js`          | Kitchen sink, many clips+gaps+transitions, 6 simultaneous text animations, edge cases  |
+
+Each script header contains a `WHAT TO CHECK` section describing the expected visual output at every timestamp, making it easy to spot regressions.
+
 ## Contributing
 
 Contributions are welcome. Please open an issue to discuss significant changes before submitting a pull request.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simple-ffmpegjs",
-  "version": "0.3.5",
+  "version": "0.4.0",
   "description": "Declarative video composition for Node.js — define clips, transitions, text, and audio as simple objects, and let FFmpeg handle the rest.",
   "author": "Brayden Blackwell <braydenblackwell21@gmail.com> (https://github.com/Fats403)",
   "license": "MIT",

package/src/core/gaps.js

@@ -1,5 +1,5 @@
 /**
- * Detect visual gaps in a timeline of video/image clips.
+ * Detect visual gaps in a timeline of video/image/color clips.
  * Returns an array of gap objects with {start, end, duration} properties.
  *
  * @param {Array<{type: string, position: number, end: number}>} clips - Array of clips
@@ -10,9 +10,9 @@
 function detectVisualGaps(clips, options = {}) {
   const { epsilon = 1e-3 } = options;
 
-  // Filter to only visual clips (video/image) and sort by position
+  // Filter to only visual clips (video/image/color) and sort by position
   const visual = clips
-    .filter((c) => c.type === "video" || c.type === "image")
+    .filter((c) => c.type === "video" || c.type === "image" || c.type === "color")
     .map((c) => ({
       position: c.position || 0,
       end: c.end || 0,
@@ -69,7 +69,7 @@ function hasVisualGaps(clips, options = {}) {
  * @returns {number} The end time of the last visual clip, or 0 if no visual clips
  */
 function getVisualTimelineEnd(clips) {
-  const visual = clips.filter((c) => c.type === "video" || c.type === "image");
+  const visual = clips.filter((c) => c.type === "video" || c.type === "image" || c.type === "color");
   if (visual.length === 0) return 0;
   return Math.max(...visual.map((c) => c.end || 0));
 }

package/src/core/resolve.js

@@ -17,7 +17,7 @@
 /**
  * Types that auto-sequence on the visual track (video + image share a timeline).
  */
-const VISUAL_TYPES = ["video", "image"];
+const VISUAL_TYPES = ["video", "image", "color"];
 
 /**
  * Types that auto-sequence on the audio track.