simple-ffmpegjs 0.3.4 → 0.3.6

package/src/ffmpeg/video_builder.js

@@ -1,19 +1,203 @@
 const { detectVisualGaps } = require("../core/gaps");
 
 /**
- * Create synthetic black clips to fill visual gaps
+ * Create synthetic clips to fill visual gaps.
+ * The actual fill color is determined by the project's fillGaps option
+ * and applied when building the filter graph.
  */
-function createBlackClipsForGaps(gaps, fps, width, height) {
+function createGapFillClips(gaps) {
   return gaps.map((gap, index) => ({
-    type: "_black",
+    type: "_gapfill",
     position: gap.start,
     end: gap.end,
     _gapIndex: index,
-    _isBlackFill: true,
+    _isGapFill: true,
   }));
 }
 
-function buildVideoFilter(project, videoClips) {
+const DEFAULT_KEN_BURNS_ZOOM = 0.15;
+const DEFAULT_PAN_ZOOM = 1.12;
+
+function clamp01(value) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return undefined;
+  }
+  return Math.min(1, Math.max(0, value));
+}
+
+function formatNumber(value, decimals) {
+  return Number(value.toFixed(decimals)).toString();
+}
+
+function buildEasingExpr(framesMinusOne, easing) {
+  const t = `(on/${framesMinusOne})`;
+  if (easing === "ease-in") {
+    return `(${t})*(${t})`;
+  }
+  if (easing === "ease-out") {
+    return `1-((1-${t})*(1-${t}))`;
+  }
+  if (easing === "ease-in-out") {
+    return `0.5-0.5*cos(PI*${t})`;
+  }
+  return t;
+}
+
+function buildInterpolatedExpr(start, end, framesMinusOne, easing, decimals) {
+  const delta = end - start;
+  const startStr = formatNumber(start, decimals);
+  if (framesMinusOne <= 1 || Math.abs(delta) < 1e-8) {
+    return startStr;
+  }
+  const deltaStr = formatNumber(delta, decimals);
+  const ease = buildEasingExpr(framesMinusOne, easing);
+  return `${startStr}+(${deltaStr})*(${ease})`;
+}
+
+function buildZoomExpr(startZoom, endZoom, framesMinusOne, easing) {
+  return buildInterpolatedExpr(startZoom, endZoom, framesMinusOne, easing, 4);
+}
+
+function buildPositionExpr(start, end, framesMinusOne, easing) {
+  return buildInterpolatedExpr(start, end, framesMinusOne, easing, 4);
+}
+
+function resolveKenBurnsOptions(kenBurns, width, height, sourceWidth, sourceHeight) {
+  const kb = typeof kenBurns === "object" && kenBurns ? kenBurns : {};
+  const type = typeof kenBurns === "string" ? kenBurns : kb.type || "custom";
+  const easing = kb.easing || "ease-in-out";
+
+  let startZoom = 1;
+  let endZoom = 1;
+  let startX = 0.5;
+  let startY = 0.5;
+  let endX = 0.5;
+  let endY = 0.5;
+
+  if (type === "zoom-in") {
+    startZoom = 1;
+    endZoom = 1 + DEFAULT_KEN_BURNS_ZOOM;
+  } else if (type === "zoom-out") {
+    startZoom = 1 + DEFAULT_KEN_BURNS_ZOOM;
+    endZoom = 1;
+  } else if (type === "pan-left") {
+    startZoom = DEFAULT_PAN_ZOOM;
+    endZoom = DEFAULT_PAN_ZOOM;
+    startX = 1;
+    endX = 0;
+  } else if (type === "pan-right") {
+    startZoom = DEFAULT_PAN_ZOOM;
+    endZoom = DEFAULT_PAN_ZOOM;
+    startX = 0;
+    endX = 1;
+  } else if (type === "pan-up") {
+    startZoom = DEFAULT_PAN_ZOOM;
+    endZoom = DEFAULT_PAN_ZOOM;
+    startY = 1;
+    endY = 0;
+  } else if (type === "pan-down") {
+    startZoom = DEFAULT_PAN_ZOOM;
+    endZoom = DEFAULT_PAN_ZOOM;
+    startY = 0;
+    endY = 1;
+  } else if (type === "smart") {
+    const anchor = kb.anchor;
+    startZoom = DEFAULT_PAN_ZOOM;
+    endZoom = DEFAULT_PAN_ZOOM;
+
+    let panAxis = "horizontal";
+    const hasSourceDims =
+      typeof sourceWidth === "number" &&
+      typeof sourceHeight === "number" &&
+      sourceWidth > 0 &&
+      sourceHeight > 0;
+
+    if (hasSourceDims) {
+      const outputAspect = width / height;
+      const sourceAspect = sourceWidth / sourceHeight;
+      if (Math.abs(sourceAspect - outputAspect) > 0.001) {
+        panAxis = sourceAspect < outputAspect ? "vertical" : "horizontal";
+      } else {
+        panAxis = height > width ? "vertical" : "horizontal";
+      }
+    } else {
+      panAxis = height > width ? "vertical" : "horizontal";
+    }
+
+    if (panAxis === "vertical") {
+      if (anchor === "top") {
+        startY = 0;
+        endY = 1;
+      } else {
+        startY = 1;
+        endY = 0;
+      }
+    } else {
+      if (anchor === "left") {
+        startX = 0;
+        endX = 1;
+      } else {
+        startX = 1;
+        endX = 0;
+      }
+    }
+  }
+
+  if (typeof kb.startZoom === "number" && Number.isFinite(kb.startZoom)) {
+    startZoom = kb.startZoom;
+  }
+  if (typeof kb.endZoom === "number" && Number.isFinite(kb.endZoom)) {
+    endZoom = kb.endZoom;
+  }
+
+  const customStartX = clamp01(kb.startX);
+  const customEndX = clamp01(kb.endX);
+  const customStartY = clamp01(kb.startY);
+  const customEndY = clamp01(kb.endY);
+
+  if (typeof customStartX === "number") {
+    startX = customStartX;
+  }
+  if (typeof customEndX === "number") {
+    endX = customEndX;
+  }
+  if (typeof customStartY === "number") {
+    startY = customStartY;
+  }
+  if (typeof customEndY === "number") {
+    endY = customEndY;
+  }
+
+  // When positions indicate panning but zoom wasn't explicitly set (still at
+  // the default 1.0), apply a default pan zoom.  At zoom=1.0 the zoompan
+  // visible window equals the full image, so (iw - iw/zoom) = 0 and position
+  // values are multiplied by zero — making the pan completely invisible.
+  const hasPan = startX !== endX || startY !== endY;
+  const zoomWasExplicit =
+    typeof kb.startZoom === "number" || typeof kb.endZoom === "number";
+  if (hasPan && !zoomWasExplicit && startZoom === 1 && endZoom === 1) {
+    startZoom = DEFAULT_PAN_ZOOM;
+    endZoom = DEFAULT_PAN_ZOOM;
+  }
+
+  return { startZoom, endZoom, startX, startY, endX, endY, easing };
+}
+
+function computeOverscanWidth(width, startZoom, endZoom) {
+  const maxZoom = Math.max(1, startZoom, endZoom);
+  // Generous pre-scale ensures zoompan has enough pixel resolution for smooth
+  // sub-pixel motion.  The integer x/y crop offsets in zoompan need a large
+  // canvas so that small position changes don't appear as visible stepping.
+  // 3x output width (floor 4000px) provides ~5-6 pixels of displacement per
+  // frame for typical pan speeds, which is imperceptible on screen.
+  let overscan = Math.max(width * 3, 4000, Math.round(width * maxZoom * 2));
+  if (overscan % 2 !== 0) {
+    overscan += 1;
+  }
+  return overscan;
+}
+
+function buildVideoFilter(project, videoClips, options = {}) {
   let filterComplex = "";
   let videoIndex = 0;
   let blackGapIndex = 0;
@@ -22,13 +206,13 @@ function buildVideoFilter(project, videoClips) {
   const height = project.options.height;
   const fillGaps = project.options.fillGaps || "none";
 
-  // Detect and fill gaps if fillGaps is enabled
+  // Detect and fill gaps if fillGaps is enabled (any value other than "none")
   let allVisualClips = [...videoClips];
-  if (fillGaps === "black") {
-    const gaps = detectVisualGaps(videoClips);
+  if (fillGaps !== "none") {
+    const gaps = detectVisualGaps(videoClips, { timelineEnd: options.timelineEnd });
     if (gaps.length > 0) {
-      const blackClips = createBlackClipsForGaps(gaps, fps, width, height);
-      allVisualClips = [...videoClips, ...blackClips].sort(
+      const gapClips = createGapFillClips(gaps);
+      allVisualClips = [...videoClips, ...gapClips].sort(
         (a, b) => (a.position || 0) - (b.position || 0),
       );
     }
@@ -44,10 +228,10 @@ function buildVideoFilter(project, videoClips) {
       (clip.end || 0) - (clip.position || 0),
     );
 
-    // Handle synthetic black fill clips
-    if (clip._isBlackFill) {
-      // Generate a black color source for the gap duration
-      filterComplex += `color=c=black:s=${width}x${height}:d=${requestedDuration},fps=${fps},settb=1/${fps}${scaledLabel};`;
+    // Handle synthetic gap fill clips
+    if (clip._isGapFill) {
+      // Generate a color source for the gap duration
+      filterComplex += `color=c=${fillGaps}:s=${width}x${height}:d=${requestedDuration},fps=${fps},settb=1/${fps}${scaledLabel};`;
       scaledStreams.push({
         label: scaledLabel,
         clip,
@@ -71,55 +255,31 @@ function buildVideoFilter(project, videoClips) {
       const framesMinusOne = Math.max(1, frames - 1);
       const s = `${width}x${height}`;
 
-      // Use overscan pre-scale + center crop, then zoompan with center-based x/y
-      const overscanW = Math.max(width * 3, 4000);
-      const kb = clip.kenBurns;
-      const type = typeof kb === "string" ? kb : kb.type;
-      // Simplified fixed-intensity zoom. API no longer exposes strength.
-      const zoomAmount = 0.15;
-
-      let zoomExpr = `1`;
-      let xExpr = `round(iw/2 - (iw/zoom)/2)`;
-      let yExpr = `round(ih/2 - (ih/zoom)/2)`;
-
-      if (type === "zoom-in") {
-        const inc = (zoomAmount / framesMinusOne).toFixed(6);
-        // Ensure first frame starts exactly at base zoom=1 (on==0)
-        zoomExpr = `if(eq(on,0),1,zoom+${inc})`;
-      } else if (type === "zoom-out") {
-        const start = (1 + zoomAmount).toFixed(4);
-        const dec = (zoomAmount / framesMinusOne).toFixed(6);
-        // Start pre-zoomed on first frame to avoid jump
-        zoomExpr = `if(eq(on,0),${start},zoom-${dec})`;
-      } else {
-        const panZoom = 1.12;
-        zoomExpr = `${panZoom}`;
-        const dx = `(iw - iw/${panZoom})`;
-        const dy = `(ih - ih/${panZoom})`;
-        if (type === "pan-left") {
-          xExpr = `${dx} - ${dx}*on/${framesMinusOne}`;
-          yExpr = `(ih - ih/zoom)/2`;
-        } else if (type === "pan-right") {
-          xExpr = `${dx}*on/${framesMinusOne}`;
-          yExpr = `(ih - ih/zoom)/2`;
-        } else if (type === "pan-up") {
-          xExpr = `(iw - iw/zoom)/2`;
-          yExpr = `${dy} - ${dy}*on/${framesMinusOne}`;
-        } else if (type === "pan-down") {
-          xExpr = `(iw - iw/zoom)/2`;
-          yExpr = `${dy}*on/${framesMinusOne}`;
-        }
-      }
+      const { startZoom, endZoom, startX, startY, endX, endY, easing } =
+        resolveKenBurnsOptions(
+          clip.kenBurns,
+          width,
+          height,
+          clip.width,
+          clip.height
+        );
+      // Overscan provides enough pixel resolution for smooth zoompan motion.
+      const overscanW = computeOverscanWidth(width, startZoom, endZoom);
+      const zoomExpr = buildZoomExpr(startZoom, endZoom, framesMinusOne, easing);
+      const xPosExpr = buildPositionExpr(startX, endX, framesMinusOne, easing);
+      const yPosExpr = buildPositionExpr(startY, endY, framesMinusOne, easing);
+      const xExpr = `(iw - iw/zoom)*(${xPosExpr})`;
+      const yExpr = `(ih - ih/zoom)*(${yPosExpr})`;
 
       // Scale to cover target dimensions (upscaling if needed), then center crop
       // force_original_aspect_ratio=increase ensures image covers the target area
       // select='eq(n,0)' uses single quotes to protect the comma from the graph parser.
       // zoompan z/x/y values are also single-quoted — commas inside are literal.
-      filterComplex += `[${inputIndex}:v]select='eq(n,0)',setpts=PTS-STARTPTS,scale=${width}:${height}:force_original_aspect_ratio=increase,setsar=1:1,crop=${width}:${height}:(iw-${width})/2:(ih-${height})/2,scale=${overscanW}:-1,zoompan=z='${zoomExpr}':x='${xExpr}':y='${yExpr}':d=${frames}:s=${s},fps=${fps},settb=1/${fps}${scaledLabel};`;
+      filterComplex += `[${inputIndex}:v]select='eq(n,0)',setpts=PTS-STARTPTS,scale=${width}:${height}:force_original_aspect_ratio=increase,setsar=1:1,crop=${width}:${height}:(iw-${width})/2:(ih-${height})/2,scale=${overscanW}:-1,zoompan=z='${zoomExpr}':x='${xExpr}':y='${yExpr}':d=${frames}:s=${s}:fps=${fps},setsar=1:1,settb=1/${fps}${scaledLabel};`;
     } else {
       filterComplex += `[${inputIndex}:v]trim=start=${
         clip.cutFrom || 0
-      }:duration=${clipDuration},setpts=PTS-STARTPTS,fps=${fps},scale=${width}:${height}:force_original_aspect_ratio=decrease,pad=${width}:${height}:(ow-iw)/2:(oh-ih)/2,settb=1/${fps}${scaledLabel};`;
+      }:duration=${clipDuration},setpts=PTS-STARTPTS,fps=${fps},scale=${width}:${height}:force_original_aspect_ratio=decrease,pad=${width}:${height}:(ow-iw)/2:(oh-ih)/2,setsar=1:1,settb=1/${fps}${scaledLabel};`;
     }
 
     scaledStreams.push({
@@ -132,7 +292,7 @@ function buildVideoFilter(project, videoClips) {
   });
 
   if (scaledStreams.length === 0) {
-    return { filter: "", finalVideoLabel: null, hasVideo: false };
+    return { filter: "", finalVideoLabel: null, hasVideo: false, videoDuration: 0 };
   }
 
   const hasTransitions = scaledStreams.some(
@@ -141,10 +301,11 @@ function buildVideoFilter(project, videoClips) {
 
   if (!hasTransitions) {
     const labels = scaledStreams.map((s) => s.label);
+    const videoDuration = scaledStreams.reduce((sum, s) => sum + s.duration, 0);
     filterComplex += `${labels.join("")}concat=n=${
       labels.length
     }:v=1:a=0,fps=${fps},settb=1/${fps}[outv];`;
-    return { filter: filterComplex, finalVideoLabel: "[outv]", hasVideo: true };
+    return { filter: filterComplex, finalVideoLabel: "[outv]", hasVideo: true, videoDuration };
   }
 
   let currentVideo = scaledStreams[0].label;
@@ -173,6 +334,7 @@ function buildVideoFilter(project, videoClips) {
     filter: filterComplex,
     finalVideoLabel: currentVideo,
     hasVideo: true,
+    videoDuration: currentVideoDuration,
   };
 }
 

package/src/ffmpeg/watermark_builder.js

@@ -1,4 +1,5 @@
 const Strings = require("./strings");
+const { isValidFFmpegColor } = require("../core/validation");
 
 /**
  * Calculate position expressions for overlay/drawtext
@@ -321,6 +322,18 @@ function validateWatermarkConfig(config) {
     }
   }
 
+  // Validate color properties
+  const colorProps = ["fontColor", "borderColor", "shadowColor"];
+  for (const prop of colorProps) {
+    if (config[prop] != null && typeof config[prop] === "string") {
+      if (!isValidFFmpegColor(config[prop])) {
+        errors.push(
+          `watermark.${prop} "${config[prop]}" is not a valid FFmpeg color. Use a named color (e.g. "white", "red"), hex (#RRGGBB), or color@alpha (e.g. "black@0.5").`
+        );
+      }
+    }
+  }
+
   // Common validations
   if (
     typeof config.opacity === "number" &&

package/src/loaders.js

@@ -88,8 +88,15 @@ async function loadAudio(project, clipObj) {
   project.videoOrAudioClips.push({ ...clipObj, mediaDuration: durationSec });
 }
 
-function loadImage(project, clipObj) {
-  const clip = { ...clipObj, hasAudio: false, cutFrom: 0 };
+async function loadImage(project, clipObj) {
+  const metadata = await probeMedia(clipObj.url);
+  const clip = {
+    ...clipObj,
+    hasAudio: false,
+    cutFrom: 0,
+    width: clipObj.width ?? metadata.width,
+    height: clipObj.height ?? metadata.height,
+  };
   project.videoOrAudioClips.push(clip);
 }
 

package/src/schema/modules/image.js

@@ -4,12 +4,14 @@ module.exports = {
   description:
     "Display still images on the timeline, optionally with Ken Burns (pan/zoom) motion effects.",
   schema: `{
-  type: "image";              // Required: clip type identifier
-  url: string;                // Required: path to image file (jpg, png, etc.)
-  position?: number;          // Start time on timeline (seconds). Omit to auto-sequence after previous video/image clip.
-  end?: number;               // End time on timeline (seconds). Use end OR duration, not both.
-  duration?: number;          // Duration in seconds (alternative to end). end = position + duration.
-  kenBurns?: KenBurnsEffect;  // Optional: apply pan/zoom motion to the image
+  type: "image";                            // Required: clip type identifier
+  url: string;                              // Required: path to image file (jpg, png, etc.)
+  position?: number;                        // Start time on timeline (seconds). Omit to auto-sequence after previous video/image clip.
+  end?: number;                             // End time on timeline (seconds). Use end OR duration, not both.
+  duration?: number;                        // Duration in seconds (alternative to end). end = position + duration.
+  width?: number;                           // Optional: source image width (skip probe / override)
+  height?: number;                          // Optional: source image height (skip probe / override)
+  kenBurns?: KenBurnsEffect | KenBurnsSpec; // Optional: apply pan/zoom motion to the image
 }`,
   enums: {
     KenBurnsEffect: [
@@ -19,7 +21,11 @@ module.exports = {
       "pan-right",
       "pan-up",
       "pan-down",
+      "smart",
+      "custom",
     ],
+    KenBurnsAnchor: ["top", "bottom", "left", "right"],
+    KenBurnsEasing: ["linear", "ease-in", "ease-out", "ease-in-out"],
   },
   examples: [
     {
@@ -34,11 +40,23 @@ module.exports = {
   { type: "image", url: "photo3.jpg", duration: 3, kenBurns: "zoom-out" }
 ]`,
     },
+    {
+      label: "Custom Ken Burns pan with smart anchor",
+      code: `{ type: "image", url: "portrait.jpg", duration: 5, kenBurns: { type: "smart", anchor: "bottom", startZoom: 1.05, endZoom: 1.2 } }`,
+    },
+    {
+      label: "Custom Ken Burns with explicit pan endpoints",
+      code: `{ type: "image", url: "photo.jpg", duration: 4, kenBurns: { type: "custom", startX: 0.2, startY: 0.8, endX: 0.7, endY: 0.3 } }`,
+    },
   ],
   notes: [
     "If position is omitted, the clip is placed immediately after the previous video/image clip (auto-sequencing). The first clip defaults to position 0.",
     "Use duration instead of end to specify how long the image displays: end = position + duration. Cannot use both.",
     "Images are scaled to fill the project canvas. For Ken Burns, use images at least as large as the output resolution for best quality.",
+    "If width/height are provided, they override probed dimensions (useful for remote or generated images).",
     "Image clips can be placed on the same timeline as video clips and can use transitions between them.",
+    "Advanced Ken Burns accepts custom zoom/pan endpoints via normalized coordinates (0 = left/top, 1 = right/bottom).",
+    "smart mode auto-pans along the dominant axis; use anchor to pick a starting edge.",
+    "Use easing ('linear', 'ease-in', 'ease-out', 'ease-in-out') to smooth motion (default: ease-in-out).",
   ],
 };

package/src/simpleffmpeg.js

@@ -16,6 +16,7 @@ const {
   validateConfig,
   formatValidationResult,
   ValidationCodes,
+  normalizeFillGaps,
 } = require("./core/validation");
 const {
   SimpleffmpegError,
@@ -44,6 +45,7 @@ const {
 const { getSchema, getSchemaModules } = require("./schema");
 const { resolveClips } = require("./core/resolve");
 const { probeMedia } = require("./core/media_info");
+const { detectVisualGaps } = require("./core/gaps");
 
 class SIMPLEFFMPEG {
   /**
@@ -55,7 +57,7 @@ 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')
+   * @param {string|boolean} options.fillGaps - Gap handling: 'none'/false (disabled), true/'black' (black fill), or any valid FFmpeg color (default: 'none')
    *
    * @example
    * const project = new SIMPLEFFMPEG({ preset: 'tiktok' });
@@ -67,6 +69,14 @@ class SIMPLEFFMPEG {
    *   fps: 30,
    *   fillGaps: 'black'
    * });
+   *
+   * @example
+   * // Fill gaps with a custom color
+   * const project = new SIMPLEFFMPEG({
+   *   width: 1920,
+   *   height: 1080,
+   *   fillGaps: '#1a1a2e'  // dark blue-gray
+   * });
    */
   constructor(options = {}) {
     // Apply platform preset if specified
@@ -81,13 +91,19 @@ class SIMPLEFFMPEG {
       );
     }
 
+    // Normalise and validate fillGaps
+    const fillGapsResult = normalizeFillGaps(options.fillGaps);
+    if (fillGapsResult.error) {
+      throw new ValidationError(fillGapsResult.error);
+    }
+
     // Explicit options override preset values
     this.options = {
       fps: options.fps || presetConfig.fps || C.DEFAULT_FPS,
       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'
+      fillGaps: fillGapsResult.color, // "none" | valid FFmpeg color
       preset: options.preset || null,
     };
     this.videoOrAudioClips = [];
@@ -253,7 +269,7 @@ class SIMPLEFFMPEG {
       await Promise.all(
         resolvedClips.map((clipObj) => {
           if (clipObj.type === "video" || clipObj.type === "audio") {
-            clipObj.volume = clipObj.volume || 1;
+            clipObj.volume = clipObj.volume != null ? clipObj.volume : 1;
             clipObj.cutFrom = clipObj.cutFrom || 0;
             if (clipObj.type === "video" && clipObj.transition) {
               clipObj.transition = {
@@ -397,7 +413,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,22 +441,100 @@ class SIMPLEFFMPEG {
       )
       .map((c) => (typeof c.end === "number" ? c.end : 0));
     const bgOrAudioEnd = audioEnds.length > 0 ? Math.max(...audioEnds) : 0;
-    const finalVisualEnd =
+
+    // Compute desired timeline end for trailing gap filling.
+    // When fillGaps is enabled, extend the video to cover text/audio clips
+    // that extend past the last visual clip (e.g. ending with text on black).
+    //
+    // The trailing gap duration must be precise so the video output ends
+    // exactly when the last content ends.  Two factors affect this:
+    //
+    // 1. Transition compensation — when active (default), text timestamps
+    //    shift left by the cumulative transition overlap, so the target end
+    //    is the compensated value.  When off, use the raw overall end.
+    //
+    // 2. Existing gaps — leading/middle gaps that will also be filled add
+    //    to the video output but are NOT included in totalVideoDuration.
+    //    We must subtract them so the trailing gap isn't oversized.
+    let timelineEnd;
+    if (this.options.fillGaps !== "none" && videoClips.length > 0) {
+      const visualEnd = Math.max(...videoClips.map((c) => c.end || 0));
+      const overallEnd = Math.max(visualEnd, textEnd, bgOrAudioEnd);
+      if (overallEnd - visualEnd > 1e-3) {
+        // Target output duration depends on whether text is compensated
+        let desiredOutputDuration;
+        if (exportOptions.compensateTransitions && videoClips.length > 1) {
+          const transitionOverlap = this._getTransitionOffsetAt(
+            videoClips,
+            overallEnd
+          );
+          desiredOutputDuration = overallEnd - transitionOverlap;
+        } else {
+          desiredOutputDuration = overallEnd;
+        }
+
+        // Account for existing gaps (leading + middle) that will also be
+        // filled — these add to the video output but aren't reflected in
+        // totalVideoDuration (which only sums clip durations − transitions).
+        const existingGaps = detectVisualGaps(videoClips);
+        const existingGapDuration = existingGaps.reduce(
+          (sum, g) => sum + g.duration,
+          0
+        );
+        const videoOutputBeforeTrailing =
+          totalVideoDuration + existingGapDuration;
+
+        const trailingGapDuration =
+          desiredOutputDuration - videoOutputBeforeTrailing;
+        if (trailingGapDuration > 1e-3) {
+          timelineEnd = visualEnd + trailingGapDuration;
+        }
+      }
+    }
+
+    let finalVisualEnd =
       videoClips.length > 0
         ? Math.max(...videoClips.map((c) => c.end))
         : Math.max(textEnd, bgOrAudioEnd);
 
     // Build video filter
     if (videoClips.length > 0) {
-      const vres = buildVideoFilter(this, videoClips);
+      const vres = buildVideoFilter(this, videoClips, { timelineEnd });
       filterComplex += vres.filter;
       finalVideoLabel = vres.finalVideoLabel;
       hasVideo = vres.hasVideo;
+
+      // Update durations to account for gap fills (including trailing gaps).
+      // videoDuration reflects the actual output length of the video filter
+      // chain, which includes any black gap-fill clips.
+      if (typeof vres.videoDuration === "number" && vres.videoDuration > 0) {
+        totalVideoDuration = vres.videoDuration;
+      }
+      // 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 > finalVisualEnd
+      ) {
+        finalVisualEnd = vres.videoDuration;
+      }
     }
 
     // Audio for video clips (aligned amix)
+    // Compute cumulative transition offsets so audio adelay values
+    // match the xfade-compressed video timeline.
     if (videoClips.length > 0) {
-      const ares = buildAudioForVideoClips(this, videoClips);
+      const transitionOffsets = new Map();
+      let cumOffset = 0;
+      for (let i = 0; i < videoClips.length; i++) {
+        if (i > 0 && videoClips[i].transition) {
+          cumOffset += videoClips[i].transition.duration || 0;
+        }
+        transitionOffsets.set(videoClips[i], cumOffset);
+      }
+      const ares = buildAudioForVideoClips(this, videoClips, transitionOffsets);
       filterComplex += ares.filter;
       finalAudioLabel = ares.finalAudioLabel || finalAudioLabel;
       hasAudio = hasAudio || ares.hasAudio;
@@ -1109,7 +1203,7 @@ 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
+   * @param {string|boolean} options.fillGaps - Gap handling ('none'/false to disable, or any valid FFmpeg color) - affects gap validation
    * @returns {Object} Validation result { valid, errors, warnings }
    *
    * @example