simple-ffmpegjs 0.3.4 → 0.3.6

package/README.md

@@ -77,7 +77,7 @@ _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
+- **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
@@ -284,7 +284,7 @@ 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')
+  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')
 })
 ```
@@ -406,13 +406,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 +552,22 @@ 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";
+      };
 }
 ```
 
@@ -762,7 +777,7 @@ onProgress: ({ percent, phase }) => {
   } else {
     console.log(`${percent}%`);
   }
-}
+};
 ```
 
 ### Logging
@@ -798,10 +813,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)
@@ -839,7 +854,7 @@ try {
 
 ### Gap Handling
 
-By default, timeline gaps (periods with no video/image content) throw a validation error. Enable automatic black frame fill:
+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({
@@ -847,7 +862,34 @@ const project = new SIMPLEFFMPEG({
 });
 
 await project.load([
-  { type: "video", url: "./clip.mp4", position: 2, end: 5 }, // Gap from 0-2s filled with black
+  { 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" },
 ]);
 ```
 
@@ -880,9 +922,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 +1320,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 +1330,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,43 +1416,31 @@ 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 (timeline, transitions, text, Ken Burns, audio, watermarks, karaoke, torture test)
 node examples/run-examples.js
+
+# Run a specific demo by name (partial match)
+node examples/run-examples.js transitions
+node examples/run-examples.js torture ken
 ```
 
-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:
+Available demo scripts (can also be run individually):
 
-```bash
-open examples/output/   # macOS
-xdg-open examples/output/   # Linux
-```
+| 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 |
+
+Each script header contains a `WHAT TO CHECK` section describing the expected visual output at every timestamp, making it easy to spot regressions.
 
 ## Contributing
 
@@ -1395,3 +1459,4 @@ 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.4",
+  "version": "0.3.6",
   "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

@@ -5,10 +5,12 @@
  * @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 } = options;
+  const { epsilon = 1e-3, timelineEnd } = options;
 
   // Filter to only visual clips (video/image) and sort by position
   const visual = clips
@@ -22,6 +24,18 @@ 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;
   }
 
@@ -48,6 +62,18 @@ 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;
 }
 

package/src/core/validation.js

@@ -1,5 +1,109 @@
 const fs = require("fs");
 
+// ========================================================================
+// FFmpeg named colors (X11/CSS color names accepted by libavutil)
+// This list is extremely stable — identical across FFmpeg versions.
+// Reference: https://ffmpeg.org/ffmpeg-utils.html#Color
+// ========================================================================
+const FFMPEG_NAMED_COLORS = new Set([
+  "aliceblue", "antiquewhite", "aqua", "aquamarine", "azure",
+  "beige", "bisque", "black", "blanchedalmond", "blue",
+  "blueviolet", "brown", "burlywood", "cadetblue", "chartreuse",
+  "chocolate", "coral", "cornflowerblue", "cornsilk", "crimson",
+  "cyan", "darkblue", "darkcyan", "darkgoldenrod", "darkgray",
+  "darkgreen", "darkgrey", "darkkhaki", "darkmagenta", "darkolivegreen",
+  "darkorange", "darkorchid", "darkred", "darksalmon", "darkseagreen",
+  "darkslateblue", "darkslategray", "darkslategrey", "darkturquoise", "darkviolet",
+  "deeppink", "deepskyblue", "dimgray", "dimgrey", "dodgerblue",
+  "firebrick", "floralwhite", "forestgreen", "fuchsia", "gainsboro",
+  "ghostwhite", "gold", "goldenrod", "gray", "green",
+  "greenyellow", "grey", "honeydew", "hotpink", "indianred",
+  "indigo", "ivory", "khaki", "lavender", "lavenderblush",
+  "lawngreen", "lemonchiffon", "lightblue", "lightcoral", "lightcyan",
+  "lightgoldenrodyellow", "lightgray", "lightgreen", "lightgrey", "lightpink",
+  "lightsalmon", "lightseagreen", "lightskyblue", "lightslategray", "lightslategrey",
+  "lightsteelblue", "lightyellow", "lime", "limegreen", "linen",
+  "magenta", "maroon", "mediumaquamarine", "mediumblue", "mediumorchid",
+  "mediumpurple", "mediumseagreen", "mediumslateblue", "mediumspringgreen", "mediumturquoise",
+  "mediumvioletred", "midnightblue", "mintcream", "mistyrose", "moccasin",
+  "navajowhite", "navy", "oldlace", "olive", "olivedrab",
+  "orange", "orangered", "orchid", "palegoldenrod", "palegreen",
+  "paleturquoise", "palevioletred", "papayawhip", "peachpuff", "peru",
+  "pink", "plum", "powderblue", "purple", "red",
+  "rosybrown", "royalblue", "saddlebrown", "salmon", "sandybrown",
+  "seagreen", "seashell", "sienna", "silver", "skyblue",
+  "slateblue", "slategray", "slategrey", "snow", "springgreen",
+  "steelblue", "tan", "teal", "thistle", "tomato",
+  "turquoise", "violet", "wheat", "white", "whitesmoke",
+  "yellow", "yellowgreen",
+]);
+
+// Hex patterns accepted by FFmpeg: #RGB, #RRGGBB, #RRGGBBAA, 0xRRGGBB, 0xRRGGBBAA
+const HEX_COLOR_RE = /^(#[0-9a-fA-F]{3}|#[0-9a-fA-F]{6}|#[0-9a-fA-F]{8}|0x[0-9a-fA-F]{6}|0x[0-9a-fA-F]{8})$/;
+
+/**
+ * Check whether a string is a valid FFmpeg color value.
+ *
+ * Accepted formats:
+ *   - Named colors (case-insensitive): "black", "Red", "DarkSlateGray", …
+ *   - Hex:  #RGB, #RRGGBB, #RRGGBBAA, 0xRRGGBB, 0xRRGGBBAA
+ *   - Special keyword: "random"
+ *   - Any of the above with an @alpha suffix: "white@0.5", "#FF0000@0.8"
+ *
+ * @param {string} value
+ * @returns {boolean}
+ */
+function isValidFFmpegColor(value) {
+  if (typeof value !== "string" || value.length === 0) return false;
+
+  // Strip optional @alpha suffix (e.g. "white@0.5", "#FF0000@0.8")
+  let color = value;
+  const atIdx = value.indexOf("@");
+  if (atIdx > 0) {
+    const alphaPart = value.slice(atIdx + 1);
+    const alpha = Number(alphaPart);
+    if (!Number.isFinite(alpha) || alpha < 0 || alpha > 1) return false;
+    color = value.slice(0, atIdx);
+  }
+
+  if (color === "random") return true;
+  if (HEX_COLOR_RE.test(color)) return true;
+  return FFMPEG_NAMED_COLORS.has(color.toLowerCase());
+}
+
+/**
+ * Normalise a fillGaps option value to either "none" (disabled) or a
+ * valid FFmpeg color string.
+ *
+ * Accepted inputs:
+ *   - false / "none" / "off" / undefined → "none"
+ *   - true                               → "black"
+ *   - "black", "red", "#FF0000", …       → the color string (validated)
+ *
+ * @param {*} value - Raw fillGaps option value
+ * @returns {{ color: string|null, error: string|null }}
+ *   color is the normalised value ("none" when disabled), error is a
+ *   human-readable message when the value is invalid.
+ */
+function normalizeFillGaps(value) {
+  if (value === undefined || value === null || value === false || value === "none" || value === "off") {
+    return { color: "none", error: null };
+  }
+  if (value === true) {
+    return { color: "black", error: null };
+  }
+  if (typeof value !== "string") {
+    return { color: null, error: `fillGaps must be a string color value, boolean, or "none" — got ${typeof value}` };
+  }
+  if (!isValidFFmpegColor(value)) {
+    return {
+      color: null,
+      error: `fillGaps color "${value}" is not a recognised FFmpeg color. Use a named color (e.g. "black", "red", "navy"), hex (#RRGGBB, 0xRRGGBB), or "random".`,
+    };
+  }
+  return { color: value, error: null };
+}
+
 /**
  * Error/warning codes for programmatic handling
  */
@@ -525,6 +629,29 @@ function validateClip(clip, index, options = {}) {
         );
       }
     }
+
+    // Validate text clip color properties
+    const textColorProps = [
+      "fontColor",
+      "borderColor",
+      "shadowColor",
+      "backgroundColor",
+      "highlightColor",
+    ];
+    for (const prop of textColorProps) {
+      if (clip[prop] != null && typeof clip[prop] === "string") {
+        if (!isValidFFmpegColor(clip[prop])) {
+          warnings.push(
+            createIssue(
+              ValidationCodes.INVALID_VALUE,
+              `${path}.${prop}`,
+              `Invalid color "${clip[prop]}". Use a named color (e.g. "white", "red"), hex (#RRGGBB), or color@alpha (e.g. "black@0.5").`,
+              clip[prop]
+            )
+          );
+        }
+      }
+    }
   }
 
   // Subtitle clip validation
@@ -583,6 +710,23 @@ function validateClip(clip, index, options = {}) {
         )
       );
     }
+
+    // Validate subtitle color properties
+    const subtitleColorProps = ["fontColor", "borderColor"];
+    for (const prop of subtitleColorProps) {
+      if (clip[prop] != null && typeof clip[prop] === "string") {
+        if (!isValidFFmpegColor(clip[prop])) {
+          warnings.push(
+            createIssue(
+              ValidationCodes.INVALID_VALUE,
+              `${path}.${prop}`,
+              `Invalid color "${clip[prop]}". Use a named color (e.g. "white", "red"), hex (#RRGGBB), or color@alpha (e.g. "black@0.5").`,
+              clip[prop]
+            )
+          );
+        }
+      }
+    }
   }
 
   // Image clip validation
@@ -595,6 +739,8 @@ function validateClip(clip, index, options = {}) {
         "pan-right",
         "pan-up",
         "pan-down",
+        "smart",
+        "custom",
       ];
       const kbType =
         typeof clip.kenBurns === "string" ? clip.kenBurns : clip.kenBurns.type;
@@ -611,6 +757,105 @@ function validateClip(clip, index, options = {}) {
         );
       }
 
+      if (typeof clip.kenBurns === "object") {
+        const {
+          anchor,
+          easing,
+          startZoom,
+          endZoom,
+          startX,
+          startY,
+          endX,
+          endY,
+        } =
+          clip.kenBurns;
+        if (anchor !== undefined) {
+          const validAnchors = ["top", "bottom", "left", "right"];
+          if (!validAnchors.includes(anchor)) {
+            errors.push(
+              createIssue(
+                ValidationCodes.INVALID_VALUE,
+                `${path}.kenBurns.anchor`,
+                `Invalid kenBurns anchor '${anchor}'. Expected: ${validAnchors.join(
+                  ", "
+                )}`,
+                anchor
+              )
+            );
+          }
+        }
+
+        if (easing !== undefined) {
+          const validEasing = ["linear", "ease-in", "ease-out", "ease-in-out"];
+          if (!validEasing.includes(easing)) {
+            errors.push(
+              createIssue(
+                ValidationCodes.INVALID_VALUE,
+                `${path}.kenBurns.easing`,
+                `Invalid kenBurns easing '${easing}'. Expected: ${validEasing.join(
+                  ", "
+                )}`,
+                easing
+              )
+            );
+          }
+        }
+
+        const numericFields = [
+          ["startZoom", startZoom],
+          ["endZoom", endZoom],
+          ["startX", startX],
+          ["startY", startY],
+          ["endX", endX],
+          ["endY", endY],
+        ];
+
+        numericFields.forEach(([field, value]) => {
+          if (value === undefined) {
+            return;
+          }
+          if (typeof value !== "number" || !Number.isFinite(value)) {
+            errors.push(
+              createIssue(
+                ValidationCodes.INVALID_TYPE,
+                `${path}.kenBurns.${field}`,
+                `kenBurns.${field} must be a finite number`,
+                value
+              )
+            );
+            return;
+          }
+
+          if ((field === "startZoom" || field === "endZoom") && value <= 0) {
+            errors.push(
+              createIssue(
+                ValidationCodes.INVALID_RANGE,
+                `${path}.kenBurns.${field}`,
+                `kenBurns.${field} must be > 0`,
+                value
+              )
+            );
+          }
+
+          if (
+            (field === "startX" ||
+              field === "startY" ||
+              field === "endX" ||
+              field === "endY") &&
+            (value < 0 || value > 1)
+          ) {
+            errors.push(
+              createIssue(
+                ValidationCodes.INVALID_RANGE,
+                `${path}.kenBurns.${field}`,
+                `kenBurns.${field} must be between 0 and 1`,
+                value
+              )
+            );
+          }
+        });
+      }
+
       // Check if image dimensions are provided and sufficient for project dimensions
       // By default, undersized images are upscaled automatically (with a warning)
       // Set strictKenBurns: true to make this an error instead
@@ -722,7 +967,7 @@ function validateTimelineGaps(clips, options = {}) {
         "timeline",
         `Gap at start of timeline [0, ${visual[0].clip.position.toFixed(
           3
-        )}s] - no video/image content. Use fillGaps: 'black' to auto-fill.`,
+        )}s] - no video/image content. Use fillGaps option (e.g. 'black') to auto-fill.`,
         { start: 0, end: visual[0].clip.position }
       )
     );
@@ -744,7 +989,7 @@ function validateTimelineGaps(clips, options = {}) {
             3
           )}s] between clips[${visual[i - 1].index}] and clips[${
             visual[i].index
-          }]. Use fillGaps: 'black' to auto-fill.`,
+          }]. Use fillGaps option (e.g. 'black') to auto-fill.`,
           { start: gapStart, end: gapEnd }
         )
       );
@@ -845,4 +1090,7 @@ module.exports = {
   validateConfig,
   formatValidationResult,
   ValidationCodes,
+  isValidFFmpegColor,
+  normalizeFillGaps,
+  FFMPEG_NAMED_COLORS,
 };

package/src/ffmpeg/audio_builder.js

@@ -1,4 +1,11 @@
-function buildAudioForVideoClips(project, videoClips) {
+/**
+ * Build audio filter chain for video clips.
+ *
+ * @param {Object} project - The SIMPLEFFMPEG project instance
+ * @param {Array} videoClips - Array of video clip objects
+ * @param {Map} [transitionOffsets] - Map of clip -> cumulative transition offset in seconds
+ */
+function buildAudioForVideoClips(project, videoClips, transitionOffsets) {
   let audioFilter = "";
   const labels = [];
 
@@ -15,9 +22,11 @@ function buildAudioForVideoClips(project, videoClips) {
         : requestedDuration;
     const clipDuration = Math.max(0, Math.min(requestedDuration, maxAvailable));
 
-    const adelayMs = Math.round(Math.max(0, clip.position || 0) * 1000);
+    const offset = transitionOffsets ? (transitionOffsets.get(clip) || 0) : 0;
+    const adelayMs = Math.round(Math.max(0, (clip.position || 0) - offset) * 1000);
+    const vol = clip.volume != null ? clip.volume : 1;
     const out = `[va${inputIndex}]`;
-    audioFilter += `[${inputIndex}:a]atrim=start=${clip.cutFrom}:duration=${clipDuration},asetpts=PTS-STARTPTS,adelay=${adelayMs}|${adelayMs}${out};`;
+    audioFilter += `[${inputIndex}:a]volume=${vol},atrim=start=${clip.cutFrom}:duration=${clipDuration},asetpts=PTS-STARTPTS,adelay=${adelayMs}|${adelayMs}${out};`;
     labels.push(out);
   });