simple-ffmpegjs 0.3.6 → 0.4.1

package/README.md

@@ -24,14 +24,14 @@
 - [API Reference](#api-reference)
   - [Constructor](#constructor)
   - [Methods](#methods)
-  - [Clip Types](#clip-types)
+  - [Auto-Sequencing & Duration Shorthand](#auto-sequencing--duration-shorthand)
+  - [Clip Types](#clip-types) — Video, Image, Color, Effect, Text, Subtitle, Audio, Background Music
   - [Platform Presets](#platform-presets)
   - [Watermarks](#watermarks)
   - [Progress Information](#progress-information)
   - [Logging](#logging)
   - [Error Handling](#error-handling)
   - [Cancellation](#cancellation)
-  - [Gap Handling](#gap-handling)
 - [Examples](#examples)
   - [Clips & Transitions](#clips--transitions)
   - [Text & Animations](#text--animations)
@@ -66,18 +66,26 @@ _Click to watch a "Wonders of the World" video created with simple-ffmpeg — co
 
 ## Features
 
+**Video & Images**
 - **Video Concatenation** — Join multiple clips with optional xfade transitions
+- **Image Support** — Ken Burns effects (zoom, pan) for static images
+- **Color Clips** — Flat colors and gradients (linear, radial) as first-class timeline clips with full transition support
+
+**Audio**
 - **Audio Mixing** — Layer audio tracks, voiceovers, and background music
+
+**Overlays & Effects**
 - **Text Overlays** — Static, word-by-word, and cumulative text with animations
 - **Text Animations** — Typewriter, scale-in, pulse, fade effects
 - **Karaoke Mode** — Word-by-word highlighting with customizable colors
 - **Subtitle Import** — Load SRT, VTT, ASS/SSA subtitle files
 - **Watermarks** — Text or image overlays with positioning and timing control
+- **Effect Clips** — Timed overlay effects (vignette, film grain, blur, color adjust, sepia, black & white, sharpen, chromatic aberration, letterbox) with fade-in/out envelopes
+
+**Developer Experience**
 - **Platform Presets** — Quick configuration for TikTok, YouTube, Instagram, etc.
-- **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** — Auto-fill timeline gaps with any color (including trailing gaps for text-on-background endings)
 - **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 +245,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 +255,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, color adjust, sepia, B&W, sharpen, chromatic aberration, letterbox |
 | `text`     | Text overlays — all modes, animations, positioning, styling |
 | `subtitle` | Subtitle file import (SRT, VTT, ASS, SSA)                   |
 | `music`    | Background music / background audio, looping                |
@@ -284,11 +294,28 @@ new SIMPLEFFMPEG(options?: {
   height?: number;          // Output height (default: 1080)
   fps?: number;             // Frame rate (default: 30)
   validationMode?: 'warn' | 'strict';  // Validation behavior (default: 'warn')
-  fillGaps?: boolean | string;         // Gap handling: true/"black", any FFmpeg color, or "none"/false (default: "none")
   preset?: string;          // Platform preset (e.g., 'tiktok', 'youtube', 'instagram-post')
+  fontFile?: string;        // Default font file for all text clips (individual clips can override)
 })
 ```
 
+When `fontFile` is set at the project level, every text clip (including karaoke) inherits it automatically. You can still override it on any individual clip:
+
+```js
+const project = new SIMPLEFFMPEG({
+  preset: "tiktok",
+  fontFile: "./fonts/Montserrat-Bold.ttf",   // applies to all text clips
+});
+
+await project.load([
+  { type: "video", url: "intro.mp4", position: 0, end: 10 },
+  // Uses the global font
+  { type: "text", text: "Hello!", position: 1, end: 4, fontSize: 72 },
+  // Overrides with a different font
+  { type: "text", text: "Special", position: 5, end: 8, fontFile: "./fonts/Italic.otf" },
+]);
+```
+
 ### Methods
 
 #### `project.load(clips)`
@@ -318,43 +345,6 @@ SIMPLEFFMPEG.getDuration(clips); // 14.5
 
 Useful for computing text overlay timings or background music end times before calling `load()`.
 
-**Duration and Auto-Sequencing:**
-
-For video, image, and audio clips, you can use shorthand to avoid specifying explicit `position` and `end` values:
-
-- **`duration`** — Use instead of `end`. The library computes `end = position + duration`. You cannot specify both `duration` and `end` on the same clip.
-- **Omit `position`** — The clip is placed immediately after the previous clip on its track. Video and image clips share the visual track; audio clips have their own track. The first clip defaults to `position: 0`.
-
-These can be combined:
-
-```ts
-// Before: manual position/end for every clip
-await project.load([
-  { type: "video", url: "./a.mp4", position: 0, end: 5 },
-  { type: "video", url: "./b.mp4", position: 5, end: 10 },
-  { type: "video", url: "./c.mp4", position: 10, end: 18, cutFrom: 3 },
-]);
-
-// After: auto-sequencing + duration
-await project.load([
-  { type: "video", url: "./a.mp4", duration: 5 },
-  { type: "video", url: "./b.mp4", duration: 5 },
-  { type: "video", url: "./c.mp4", duration: 8, cutFrom: 3 },
-]);
-```
-
-You can mix explicit and implicit positioning freely. Clips with explicit `position` are placed there; subsequent auto-sequenced clips follow from the last clip's end:
-
-```ts
-await project.load([
-  { type: "video", url: "./a.mp4", duration: 5 }, // position: 0, end: 5
-  { type: "video", url: "./b.mp4", position: 10, end: 15 }, // explicit gap
-  { type: "video", url: "./c.mp4", duration: 5 }, // position: 15, end: 20
-]);
-```
-
-Text clips always require an explicit `position` (they're overlays on specific moments). Background music and subtitle clips already have optional `position`/`end` with their own defaults.
-
 #### `SIMPLEFFMPEG.probe(filePath)`
 
 Probe a media file and return comprehensive metadata using ffprobe. Works with video, audio, and image files.
@@ -480,6 +470,43 @@ await project.preview(options?: ExportOptions): Promise<{
 }>
 ```
 
+### Auto-Sequencing & Duration Shorthand
+
+For video, image, and audio clips, you can use shorthand to avoid specifying explicit `position` and `end` values:
+
+- **`duration`** — Use instead of `end`. The library computes `end = position + duration`. You cannot specify both `duration` and `end` on the same clip.
+- **Omit `position`** — The clip is placed immediately after the previous clip on its track. Video and image clips share the visual track; audio clips have their own track. The first clip defaults to `position: 0`.
+
+These can be combined:
+
+```ts
+// Before: manual position/end for every clip
+await project.load([
+  { type: "video", url: "./a.mp4", position: 0, end: 5 },
+  { type: "video", url: "./b.mp4", position: 5, end: 10 },
+  { type: "video", url: "./c.mp4", position: 10, end: 18, cutFrom: 3 },
+]);
+
+// After: auto-sequencing + duration
+await project.load([
+  { type: "video", url: "./a.mp4", duration: 5 },
+  { type: "video", url: "./b.mp4", duration: 5 },
+  { type: "video", url: "./c.mp4", duration: 8, cutFrom: 3 },
+]);
+```
+
+You can mix explicit and implicit positioning freely. Clips with explicit `position` are placed there; subsequent auto-sequenced clips follow from the last clip's end:
+
+```ts
+await project.load([
+  { type: "video", url: "./a.mp4", duration: 5 }, // position: 0, end: 5
+  { type: "video", url: "./b.mp4", position: 10, end: 15 }, // explicit gap
+  { type: "video", url: "./c.mp4", duration: 5 }, // position: 15, end: 20
+]);
+```
+
+Text clips always require an explicit `position` (they're overlays on specific moments). Background music and subtitle clips already have optional `position`/`end` with their own defaults.
+
 ### Clip Types
 
 #### Video Clip
@@ -502,75 +529,155 @@ await project.preview(options?: ExportOptions): Promise<{
 
 All [xfade transitions](https://trac.ffmpeg.org/wiki/Xfade) are supported.
 
-#### Audio Clip
+#### Image Clip
 
 ```ts
 {
-  type: "audio";
+  type: "image";
   url: string;
-  position?: number;        // Omit to auto-sequence after previous audio clip
+  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)
-  cutFrom?: number;
-  volume?: number;
+  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";
+      };
 }
 ```
 
-#### Background Music
+#### Color Clip
+
+Color clips add flat colors or gradients as first-class visual elements. 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.
 
 ```ts
 {
-  type: "music";            // or "backgroundAudio"
-  url: string;
-  position?: number;        // default: 0
-  end?: number;             // default: project duration
-  cutFrom?: number;
-  volume?: number;          // default: 0.2
-  loop?: boolean;           // Loop audio to fill video duration
+  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;
+  };
 }
 ```
 
-Background music is mixed after transitions, so video crossfades won't affect its volume.
+`color` accepts any valid FFmpeg color name or hex code:
 
-**Looping Music:**
+```ts
+{ type: "color", color: "navy", position: 0, end: 3 }
+{ type: "color", color: "#1a1a2e", position: 0, end: 3 }
+```
 
-If your music track is shorter than your video, enable looping:
+**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:**
 
 ```ts
 await project.load([
-  { type: "video", url: "./video.mp4", position: 0, end: 120 },
-  { type: "music", url: "./30s-track.mp3", volume: 0.3, loop: true },
+  { 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",
+  },
 ]);
 ```
 
-#### Image Clip
+> **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.
+
+#### 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: "image";
-  url: string;
-  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)
-  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";
-      };
+  type: "effect";
+  effect: EffectName;         // See table below
+  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)
+  params: EffectParams;       // Effect-specific parameters (see table below)
 }
 ```
 
+All effects accept `params.amount` (0-1, default 1) to control the blend intensity. Additional per-effect parameters:
+
+| Effect | Description | Extra Params |
+|---|---|---|
+| `vignette` | Darkened edges | `angle`: radians (default: PI/5) |
+| `filmGrain` | Noise overlay | `strength`: noise intensity 0-1 (default: 0.35), `temporal`: boolean (default: true) |
+| `gaussianBlur` | Gaussian blur | `sigma`: blur radius (default derived from amount) |
+| `colorAdjust` | Color grading | `brightness`: -1..1, `contrast`: 0..3, `saturation`: 0..3, `gamma`: 0.1..10 |
+| `sepia` | Warm vintage tone | — |
+| `blackAndWhite` | Desaturate to grayscale | `contrast`: boost 0-3 (default: 1) |
+| `sharpen` | Sharpen detail | `strength`: unsharp amount 0-3 (default: 1) |
+| `chromaticAberration` | RGB channel split | `shift`: pixel offset 0-20 (default: 4) |
+| `letterbox` | Cinematic bars | `size`: bar height as fraction of frame 0-0.5 (default: 0.12), `color`: string (default: "black") |
+
 #### Text Clip
 
 ```ts
@@ -640,6 +747,47 @@ Import external subtitle files (SRT, VTT, ASS/SSA):
 }
 ```
 
+#### Audio Clip
+
+```ts
+{
+  type: "audio";
+  url: string;
+  position?: number;        // Omit to auto-sequence after previous audio clip
+  end?: number;             // Use end OR duration, not both
+  duration?: number;        // Duration in seconds (alternative to end)
+  cutFrom?: number;
+  volume?: number;
+}
+```
+
+#### Background Music
+
+```ts
+{
+  type: "music";            // or "backgroundAudio"
+  url: string;
+  position?: number;        // default: 0
+  end?: number;             // default: project duration
+  cutFrom?: number;
+  volume?: number;          // default: 0.2
+  loop?: boolean;           // Loop audio to fill video duration
+}
+```
+
+Background music is mixed after transitions, so video crossfades won't affect its volume.
+
+**Looping Music:**
+
+If your music track is shorter than your video, enable looping:
+
+```ts
+await project.load([
+  { type: "video", url: "./video.mp4", position: 0, end: 120 },
+  { type: "music", url: "./30s-track.mp3", volume: 0.3, loop: true },
+]);
+```
+
 ### Platform Presets
 
 Use platform presets to quickly configure optimal dimensions for social media:
@@ -852,47 +1000,6 @@ try {
 }
 ```
 
-### Gap Handling
-
-By default, timeline gaps (periods with no video/image content) produce a validation warning. Enable automatic gap filling to insert solid-color frames wherever there's no visual media — leading gaps, middle gaps, and trailing gaps are all handled:
-
-```ts
-const project = new SIMPLEFFMPEG({
-  fillGaps: "black", // Fill gaps with black frames
-});
-
-await project.load([
-  { type: "video", url: "./clip.mp4", position: 2, end: 5 }, // Leading gap from 0-2s filled with black
-]);
-```
-
-`fillGaps` accepts any valid FFmpeg color — named colors, hex codes, or `true` as shorthand for `"black"`:
-
-```ts
-// Custom color fill
-const project = new SIMPLEFFMPEG({ fillGaps: "#0a0a2e" }); // dark navy
-const project = new SIMPLEFFMPEG({ fillGaps: "navy" });     // named color
-const project = new SIMPLEFFMPEG({ fillGaps: true });        // same as "black"
-```
-
-All three gap types are supported:
-
-- **Leading gaps** — no visual media at the start of the timeline (e.g. video starts at 2s, gap from 0-2s)
-- **Middle gaps** — periods between visual clips with no media
-- **Trailing gaps** — text or audio extends past the last visual clip, so the video is extended with the fill color
-
-Trailing gaps are useful for ending a video with text on a solid background:
-
-```ts
-const project = new SIMPLEFFMPEG({ fillGaps: "#1a1a2e" });
-
-await project.load([
-  { type: "video", url: "./clip.mp4", position: 0, end: 5 },
-  // Text extends 5 seconds past the video — dark blue fill from 5-10s
-  { type: "text", text: "The End", position: 4, end: 10, fontSize: 64, fontColor: "white" },
-]);
-```
-
 ## Examples
 
 ### Clips & Transitions
@@ -954,7 +1061,7 @@ await project.load([
 ]);
 ```
 
-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.
+When `position` is omitted, clips are placed sequentially — see [Auto-Sequencing & Duration Shorthand](#auto-sequencing--duration-shorthand) for details.
 
 > **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).
@@ -1419,7 +1526,7 @@ npm run test:watch
 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 (timeline, transitions, text, Ken Burns, audio, watermarks, karaoke, torture test)
+# Run all demos (color clips, effects, transitions, text, Ken Burns, audio, watermarks, karaoke, torture test)
 node examples/run-examples.js
 
 # Run a specific demo by name (partial match)
@@ -1429,16 +1536,17 @@ node examples/run-examples.js torture ken
 
 Available demo scripts (can also be run individually):
 
-| Script | What it tests |
-| --- | --- |
-| `demo-timeline-and-gaps.js` | Leading/middle/trailing gaps, custom fill colors, `fillGaps: true` shorthand |
-| `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 |
+| Script                          | What it tests                                                                          |
+| ------------------------------- | -------------------------------------------------------------------------------------- |
+| `demo-color-clips.js`           | Flat colors, linear/radial gradients, transitions, full composition with color clips   |
+| `demo-effects.js`               | Timed overlay effects (all 9 effects) with smooth fade 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.
 
@@ -1459,4 +1567,3 @@ Inspired by [ezffmpeg](https://github.com/ezffmpeg/ezffmpeg) by John Chen.
 ## License
 
 MIT
-```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simple-ffmpegjs",
-  "version": "0.3.6",
+  "version": "0.4.1",
   "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,20 +1,18 @@
 /**
- * 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
  * @param {Object} options - Options
  * @param {number} options.epsilon - Tolerance for gap detection (default 0.001)
- * @param {number} [options.timelineEnd] - Desired end of the timeline; if set and greater
- *   than the last visual clip's end, a trailing gap is appended.
  * @returns {Array<{start: number, end: number, duration: number}>} Array of gaps
  */
 function detectVisualGaps(clips, options = {}) {
-  const { epsilon = 1e-3, timelineEnd } = 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,
@@ -24,18 +22,6 @@ function detectVisualGaps(clips, options = {}) {
   const gaps = [];
 
   if (visual.length === 0) {
-    // If no visual clips but a timeline end is specified, the entire range is a gap
-    if (
-      typeof timelineEnd === "number" &&
-      Number.isFinite(timelineEnd) &&
-      timelineEnd > epsilon
-    ) {
-      gaps.push({
-        start: 0,
-        end: timelineEnd,
-        duration: timelineEnd,
-      });
-    }
     return gaps;
   }
 
@@ -62,18 +48,6 @@ function detectVisualGaps(clips, options = {}) {
     }
   }
 
-  // Check for trailing gap (gap at the end after last clip)
-  if (typeof timelineEnd === "number" && Number.isFinite(timelineEnd)) {
-    const lastEnd = visual[visual.length - 1].end;
-    if (timelineEnd - lastEnd > epsilon) {
-      gaps.push({
-        start: lastEnd,
-        end: timelineEnd,
-        duration: timelineEnd - lastEnd,
-      });
-    }
-  }
-
   return gaps;
 }
 
@@ -95,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.