simple-ffmpegjs 0.5.2 → 0.5.4

package/src/simpleffmpeg.js

@@ -9,8 +9,8 @@ const { buildVideoFilter } = require("./ffmpeg/video_builder");
 const { buildAudioForVideoClips } = require("./ffmpeg/audio_builder");
 const { buildBackgroundMusicMix } = require("./ffmpeg/bgm_builder");
 const { buildEffectFilters } = require("./ffmpeg/effect_builder");
+const { buildStandaloneAudioMix } = require("./ffmpeg/standalone_audio_builder");
 const {
-  getClipAudioString,
   hasProblematicChars,
   hasEmoji,
   stripEmoji,
@@ -87,7 +87,7 @@ class SIMPLEFFMPEG {
       console.warn(
         `Unknown platform preset '${
           options.preset
-        }'. Valid presets: ${Object.keys(C.PLATFORM_PRESETS).join(", ")}`
+        }'. Valid presets: ${Object.keys(C.PLATFORM_PRESETS).join(", ")}`,
       );
     }
 
@@ -105,12 +105,12 @@ class SIMPLEFFMPEG {
     if (this.options.tempDir) {
       if (typeof this.options.tempDir !== "string") {
         throw new SimpleffmpegError(
-          "tempDir must be a string path to an existing directory."
+          "tempDir must be a string path to an existing directory.",
         );
       }
       if (!fs.existsSync(this.options.tempDir)) {
         throw new SimpleffmpegError(
-          `tempDir "${this.options.tempDir}" does not exist. Create it before constructing SIMPLEFFMPEG.`
+          `tempDir "${this.options.tempDir}" does not exist. Create it before constructing SIMPLEFFMPEG.`,
         );
       }
     }
@@ -119,7 +119,7 @@ class SIMPLEFFMPEG {
       const family = parseFontFamily(this.options.emojiFont);
       if (!family) {
         console.warn(
-          `simple-ffmpeg: Could not parse font family from "${this.options.emojiFont}". Emoji will be stripped from text.`
+          `simple-ffmpeg: Could not parse font family from "${this.options.emojiFont}". Emoji will be stripped from text.`,
         );
       } else {
         this._emojiFontInfo = {
@@ -154,7 +154,7 @@ class SIMPLEFFMPEG {
         const escapedUrl = escapeFilePath(clip.url);
         // Gradient color clips and image clips are looped images
         if (clip.type === "image" || (clip.type === "color" && !clip._isFlatColor)) {
-          const duration = Math.max(0, clip.end - clip.position || 0);
+          const duration = Math.max(0, (clip.end ?? 0) - (clip.position ?? 0));
           return `-loop 1 -t ${duration} -i "${escapedUrl}"`;
         }
         // Loop background music if specified
@@ -189,7 +189,7 @@ class SIMPLEFFMPEG {
             console.error("Error cleaning up file:", error);
           }
         }
-      })
+      }),
     );
   }
 
@@ -230,6 +230,41 @@ class SIMPLEFFMPEG {
     return timestamp - this._getTransitionOffsetAt(videoClips, timestamp);
   }
 
+  /**
+   * Compensate a clip's position, end, words, and wordTimestamps for
+   * transition timeline compression. Returns a new clip object.
+   * @private
+   * @param {Array} videoClips - Array of video clips sorted by position
+   * @param {Object} clip - The clip to compensate
+   * @returns {Object} New clip with adjusted timings
+   */
+  _compensateClipTimings(videoClips, clip) {
+    const adjusted = {
+      ...clip,
+      position: this._adjustTimestampForTransitions(
+        videoClips,
+        clip.position || 0,
+      ),
+      end: this._adjustTimestampForTransitions(videoClips, clip.end || 0),
+    };
+    if (Array.isArray(clip.words)) {
+      adjusted.words = clip.words.map((word) => ({
+        ...word,
+        start: this._adjustTimestampForTransitions(
+          videoClips,
+          word.start || 0,
+        ),
+        end: this._adjustTimestampForTransitions(videoClips, word.end || 0),
+      }));
+    }
+    if (Array.isArray(clip.wordTimestamps)) {
+      adjusted.wordTimestamps = clip.wordTimestamps.map((ts) =>
+        this._adjustTimestampForTransitions(videoClips, ts),
+      );
+    }
+    return adjusted;
+  }
+
   /**
    * Load clips into the project for processing
    *
@@ -257,13 +292,20 @@ class SIMPLEFFMPEG {
     // Guard against concurrent load() calls
     if (this._isLoading) {
       throw new SimpleffmpegError(
-        "Cannot call load() while another load() is in progress. Await the previous load() call first."
+        "Cannot call load() while another load() is in progress. Await the previous load() call first.",
       );
     }
 
     this._isLoading = true;
 
     try {
+      // Clear previous state for idempotent reload
+      this.videoOrAudioClips = [];
+      this.textClips = [];
+      this.subtitleClips = [];
+      this.effectClips = [];
+      this.filesToClean = [];
+
       // Resolve shorthand: duration → end, auto-sequential positioning
       const resolved = resolveClips(clipObjs);
 
@@ -299,7 +341,7 @@ class SIMPLEFFMPEG {
         resolvedClips.map((clipObj) => {
           if (clipObj.type === "video" || clipObj.type === "audio") {
             clipObj.volume = clipObj.volume != null ? clipObj.volume : 1;
-            clipObj.cutFrom = clipObj.cutFrom || 0;
+            clipObj.cutFrom = clipObj.cutFrom ?? 0;
           }
           // Normalize transitions for all visual clip types
           if (
@@ -308,7 +350,7 @@ class SIMPLEFFMPEG {
           ) {
             clipObj.transition = {
               type: clipObj.transition.type || clipObj.transition,
-              duration: clipObj.transition.duration || 0.5,
+              duration: clipObj.transition.duration ?? 0.5,
             };
           }
           if (clipObj.type === "video") {
@@ -335,7 +377,7 @@ class SIMPLEFFMPEG {
           if (clipObj.type === "subtitle") {
             return Loaders.loadSubtitle(this, clipObj);
           }
-        })
+        }),
       );
     } finally {
       this._isLoading = false;
@@ -422,7 +464,8 @@ class SIMPLEFFMPEG {
       if (!a.position) return -1;
       if (!b.position) return 1;
       if (a.position < b.position) return -1;
-      return 1;
+      if (a.position > b.position) return 1;
+      return 0;
     });
 
     // Handle rotation
@@ -435,7 +478,7 @@ class SIMPLEFFMPEG {
           this.filesToClean.push(unrotatedUrl);
           clip.url = unrotatedUrl;
         }
-      })
+      }),
     );
 
     // Build a mapping from clip to its FFmpeg input stream index.
@@ -453,13 +496,13 @@ class SIMPLEFFMPEG {
     }
 
     const videoClips = this.videoOrAudioClips.filter(
-      (clip) => clip.type === "video" || clip.type === "image" || clip.type === "color"
+      (clip) => clip.type === "video" || clip.type === "image" || clip.type === "color",
     );
     const audioClips = this.videoOrAudioClips.filter(
-      (clip) => clip.type === "audio"
+      (clip) => clip.type === "audio",
     );
     const backgroundClips = this.videoOrAudioClips.filter(
-      (clip) => clip.type === "music" || clip.type === "backgroundAudio"
+      (clip) => clip.type === "music" || clip.type === "backgroundAudio",
     );
 
     let filterComplex = "";
@@ -472,7 +515,7 @@ class SIMPLEFFMPEG {
       if (videoClips.length === 0) return 0;
       const baseSum = videoClips.reduce(
         (acc, c) => acc + Math.max(0, (c.end || 0) - (c.position || 0)),
-        0
+        0,
       );
       const transitionsOverlap = videoClips.reduce((acc, c) => {
         const d =
@@ -492,7 +535,7 @@ class SIMPLEFFMPEG {
         (c) =>
           c.type === "audio" ||
           c.type === "music" ||
-          c.type === "backgroundAudio"
+          c.type === "backgroundAudio",
       )
       .map((c) => (typeof c.end === "number" ? c.end : 0));
     const bgOrAudioEnd = audioEnds.length > 0 ? Math.max(...audioEnds) : 0;
@@ -518,6 +561,20 @@ class SIMPLEFFMPEG {
       }
     }
 
+    // Expand fullDuration clips now that finalVisualEnd is known
+    for (const clip of this.effectClips) {
+      if (clip.fullDuration === true) {
+        clip.position = clip.position ?? 0;
+        clip.end = finalVisualEnd;
+      }
+    }
+    for (const clip of this.textClips) {
+      if (clip.fullDuration === true) {
+        clip.position = clip.position ?? 0;
+        clip.end = finalVisualEnd;
+      }
+    }
+
     // Overlay effects (adjustment layer clips) on the composed video output.
     if (this.effectClips.length > 0 && hasVideo && finalVideoLabel) {
       const effectRes = buildEffectFilters(this.effectClips, finalVideoLabel);
@@ -545,33 +602,15 @@ class SIMPLEFFMPEG {
 
     // Standalone audio clips
     if (audioClips.length > 0) {
-      let audioString = "";
-      let audioConcatInputs = [];
-      audioClips.forEach((clip) => {
-        const inputIndex = this._inputIndexMap
-          ? this._inputIndexMap.get(clip)
-          : this.videoOrAudioClips.indexOf(clip);
-        const { audioStringPart, audioConcatInput } = getClipAudioString(
-          clip,
-          inputIndex
-        );
-        audioString += audioStringPart;
-        audioConcatInputs.push(audioConcatInput);
+      const sares = buildStandaloneAudioMix(this, audioClips, {
+        compensateTransitions: exportOptions.compensateTransitions,
+        videoClips,
+        hasAudio,
+        finalAudioLabel,
       });
-      if (audioConcatInputs.length > 0) {
-        filterComplex += audioString;
-        filterComplex += audioConcatInputs.join("");
-        if (hasAudio) {
-          filterComplex += `${finalAudioLabel}amix=inputs=${
-            audioConcatInputs.length + 1
-          }:duration=longest[finalaudio];`;
-          finalAudioLabel = "[finalaudio]";
-        } else {
-          filterComplex += `amix=inputs=${audioConcatInputs.length}:duration=longest[finalaudio];`;
-          finalAudioLabel = "[finalaudio]";
-          hasAudio = true;
-        }
-      }
+      filterComplex += sares.filter;
+      finalAudioLabel = sares.finalAudioLabel || finalAudioLabel;
+      hasAudio = sares.hasAudio;
     }
 
     // Background music after other audio
@@ -580,7 +619,7 @@ class SIMPLEFFMPEG {
         this,
         backgroundClips,
         hasAudio ? finalAudioLabel : null,
-        finalVisualEnd
+        finalVisualEnd,
       );
       filterComplex += bgres.filter;
       finalAudioLabel = bgres.finalAudioLabel || finalAudioLabel;
@@ -600,45 +639,9 @@ class SIMPLEFFMPEG {
       // Compensate text timings for transition overlap if enabled
       let adjustedTextClips = this.textClips;
       if (exportOptions.compensateTransitions && videoClips.length > 1) {
-        adjustedTextClips = this.textClips.map((clip) => {
-          const adjustedPosition = this._adjustTimestampForTransitions(
-            videoClips,
-            clip.position || 0
-          );
-          const adjustedEnd = this._adjustTimestampForTransitions(
-            videoClips,
-            clip.end || 0
-          );
-          // Also adjust word timings if present
-          let adjustedWords = clip.words;
-          if (Array.isArray(clip.words)) {
-            adjustedWords = clip.words.map((word) => ({
-              ...word,
-              start: this._adjustTimestampForTransitions(
-                videoClips,
-                word.start || 0
-              ),
-              end: this._adjustTimestampForTransitions(
-                videoClips,
-                word.end || 0
-              ),
-            }));
-          }
-          // Also adjust wordTimestamps if present
-          let adjustedWordTimestamps = clip.wordTimestamps;
-          if (Array.isArray(clip.wordTimestamps)) {
-            adjustedWordTimestamps = clip.wordTimestamps.map((ts) =>
-              this._adjustTimestampForTransitions(videoClips, ts)
-            );
-          }
-          return {
-            ...clip,
-            position: adjustedPosition,
-            end: adjustedEnd,
-            words: adjustedWords,
-            wordTimestamps: adjustedWordTimestamps,
-          };
-        });
+        adjustedTextClips = this.textClips.map((clip) =>
+          this._compensateClipTimings(videoClips, clip),
+        );
       }
 
       // Emoji handling: opt-in via emojiFont, otherwise strip emoji from text.
@@ -660,7 +663,7 @@ class SIMPLEFFMPEG {
           } else {
             console.warn(
               `simple-ffmpeg: Text "${textContent.slice(0, 40)}..." contains emoji but uses '${animType}' animation ` +
-                `which is not supported in ASS. Emoji will be stripped.`
+              `which is not supported in ASS. Emoji will be stripped.`,
             );
             drawtextClips.push({ ...clip, text: stripEmoji(textContent) });
           }
@@ -669,8 +672,8 @@ class SIMPLEFFMPEG {
             this._emojiStrippedWarned = true;
             console.warn(
               "simple-ffmpeg: Text contains emoji but no emojiFont is configured. " +
-                "Emoji will be stripped. To render emoji, pass emojiFont in the constructor: " +
-                "new SIMPLEFFMPEG({ emojiFont: '/path/to/NotoEmoji-Regular.ttf' })"
+              "Emoji will be stripped. To render emoji, pass emojiFont in the constructor: " +
+              "new SIMPLEFFMPEG({ emojiFont: '/path/to/NotoEmoji-Regular.ttf' })",
             );
           }
           drawtextClips.push({ ...clip, text: stripEmoji(textContent) });
@@ -680,7 +683,7 @@ class SIMPLEFFMPEG {
         if (!(clip.text || "").trim()) {
           console.warn(
             `simple-ffmpeg: Text clip at ${clip.position}s–${clip.end}s ` +
-              `has no visible text after emoji stripping. Skipping.`
+            `has no visible text after emoji stripping. Skipping.`,
           );
           return false;
         }
@@ -695,7 +698,7 @@ class SIMPLEFFMPEG {
         if (hasProblematicChars(textContent)) {
           const tempPath = path.join(
             textTempBase,
-            `.simpleffmpeg_text_${idx}_${Date.now()}.txt`
+            `.simpleffmpeg_text_${idx}_${Date.now()}.txt`,
           );
           const normalizedText = textContent.replace(/\r?\n/g, " ").replace(/ {2,}/g, " ");
           try {
@@ -703,7 +706,7 @@ class SIMPLEFFMPEG {
           } catch (writeError) {
             throw new SimpleffmpegError(
               `Failed to write temporary text file "${tempPath}": ${writeError.message}`,
-              { cause: writeError }
+              { cause: writeError },
             );
           }
           this.filesToClean.push(tempPath);
@@ -728,7 +731,7 @@ class SIMPLEFFMPEG {
             adjustedTextClips,
             this.options.width,
             this.options.height,
-            finalVideoLabel
+            finalVideoLabel,
           );
 
         // Auto-batch if filter_complex would exceed safe command length limit
@@ -737,18 +740,18 @@ class SIMPLEFFMPEG {
           // Calculate optimal batch size based on filter length
           const avgNodeLength = filterString.length / textWindows.length;
           const safeNodes = Math.floor(
-            (C.MAX_FILTER_COMPLEX_LENGTH - filterComplex.length) / avgNodeLength
+            (C.MAX_FILTER_COMPLEX_LENGTH - filterComplex.length) / avgNodeLength,
           );
           exportOptions.textMaxNodesPerPass = Math.max(
             10,
-            Math.min(safeNodes, 50)
+            Math.min(safeNodes, 50),
           );
           needTextPasses = true;
 
           if (exportOptions.verbose) {
             console.log(
               `simple-ffmpeg: Auto-batching text (filter too long: ${potentialLength} > ${C.MAX_FILTER_COMPLEX_LENGTH}). ` +
-                `Using ${exportOptions.textMaxNodesPerPass} nodes per pass.`
+              `Using ${exportOptions.textMaxNodesPerPass} nodes per pass.`,
             );
           }
         } else {
@@ -766,18 +769,18 @@ class SIMPLEFFMPEG {
             emojiClip,
             this.options.width,
             this.options.height,
-            emojiFont
+            emojiFont,
           );
           const assFilePath = path.join(
             this.options.tempDir || path.dirname(exportOptions.outputPath),
-            `.simpleffmpeg_emoji_${i}_${Date.now()}.ass`
+            `.simpleffmpeg_emoji_${i}_${Date.now()}.ass`,
           );
           try {
             fs.writeFileSync(assFilePath, assContent, "utf-8");
           } catch (writeError) {
             throw new SimpleffmpegError(
               `Failed to write temporary ASS file "${assFilePath}": ${writeError.message}`,
-              { cause: writeError }
+              { cause: writeError },
             );
           }
           this.filesToClean.push(assFilePath);
@@ -788,7 +791,7 @@ class SIMPLEFFMPEG {
           const uniqueLabel = `[outemoji${i}]`;
           const filter = assResult.filter.replace(
             assResult.finalLabel,
-            uniqueLabel
+            uniqueLabel,
           );
           filterComplex += filter + ";";
           finalVideoLabel = uniqueLabel;
@@ -808,41 +811,7 @@ class SIMPLEFFMPEG {
           videoClips.length > 1 &&
           subClip.mode === "karaoke"
         ) {
-          const adjustedPosition = this._adjustTimestampForTransitions(
-            videoClips,
-            subClip.position || 0
-          );
-          const adjustedEnd = this._adjustTimestampForTransitions(
-            videoClips,
-            subClip.end || 0
-          );
-          let adjustedWords = subClip.words;
-          if (Array.isArray(subClip.words)) {
-            adjustedWords = subClip.words.map((word) => ({
-              ...word,
-              start: this._adjustTimestampForTransitions(
-                videoClips,
-                word.start || 0
-              ),
-              end: this._adjustTimestampForTransitions(
-                videoClips,
-                word.end || 0
-              ),
-            }));
-          }
-          let adjustedWordTimestamps = subClip.wordTimestamps;
-          if (Array.isArray(subClip.wordTimestamps)) {
-            adjustedWordTimestamps = subClip.wordTimestamps.map((ts) =>
-              this._adjustTimestampForTransitions(videoClips, ts)
-            );
-          }
-          subClip = {
-            ...subClip,
-            position: adjustedPosition,
-            end: adjustedEnd,
-            words: adjustedWords,
-            wordTimestamps: adjustedWordTimestamps,
-          };
+          subClip = this._compensateClipTimings(videoClips, subClip);
         }
 
         let assContent = "";
@@ -860,7 +829,7 @@ class SIMPLEFFMPEG {
               subClip.url,
               subClip,
               this.options.width,
-              this.options.height
+              this.options.height,
             );
           }
         } else if (subClip.mode === "karaoke") {
@@ -868,7 +837,7 @@ class SIMPLEFFMPEG {
           assContent = buildKaraokeASS(
             subClip,
             this.options.width,
-            this.options.height
+            this.options.height,
           );
         }
 
@@ -876,14 +845,14 @@ class SIMPLEFFMPEG {
         if (assContent && !assFilePath) {
           assFilePath = path.join(
             this.options.tempDir || path.dirname(exportOptions.outputPath),
-            `.simpleffmpeg_sub_${i}_${Date.now()}.ass`
+            `.simpleffmpeg_sub_${i}_${Date.now()}.ass`,
           );
           try {
             fs.writeFileSync(assFilePath, assContent, "utf-8");
           } catch (writeError) {
             throw new SimpleffmpegError(
               `Failed to write temporary ASS file "${assFilePath}": ${writeError.message}`,
-              { cause: writeError }
+              { cause: writeError },
             );
           }
           assFilesToClean.push(assFilePath);
@@ -897,7 +866,7 @@ class SIMPLEFFMPEG {
           const uniqueLabel = `[outsub${i}]`;
           const filter = assResult.filter.replace(
             assResult.finalLabel,
-            uniqueLabel
+            uniqueLabel,
           );
           filterComplex += filter + ";";
           finalVideoLabel = uniqueLabel;
@@ -913,7 +882,7 @@ class SIMPLEFFMPEG {
       const wmValidation = validateWatermarkConfig(exportOptions.watermark);
       if (!wmValidation.valid) {
         throw new Error(
-          `Watermark validation failed: ${wmValidation.errors.join(", ")}`
+          `Watermark validation failed: ${wmValidation.errors.join(", ")}`,
         );
       }
 
@@ -934,7 +903,7 @@ class SIMPLEFFMPEG {
         watermarkInputIndex,
         this.options.width,
         this.options.height,
-        totalVideoDuration
+        totalVideoDuration,
       );
 
       if (wmResult.filter) {
@@ -1010,12 +979,16 @@ class SIMPLEFFMPEG {
    * @returns {Promise<{command: string, filterComplex: string, totalDuration: number}>}
    */
   async preview(options = {}) {
-    const result = await this._prepareExport(options);
-    return {
-      command: result.command,
-      filterComplex: result.filterComplex,
-      totalDuration: result.totalDuration,
-    };
+    try {
+      const result = await this._prepareExport(options);
+      return {
+        command: result.command,
+        filterComplex: result.filterComplex,
+        totalDuration: result.totalDuration,
+      };
+    } finally {
+      await this._cleanup();
+    }
   }
 
   /**
@@ -1048,7 +1021,7 @@ class SIMPLEFFMPEG {
     // Guard against concurrent export() calls
     if (this._isExporting) {
       throw new SimpleffmpegError(
-        "Cannot call export() while another export() is in progress. Await the previous export() call first."
+        "Cannot call export() while another export() is in progress. Await the previous export() call first.",
       );
     }
 
@@ -1082,7 +1055,7 @@ class SIMPLEFFMPEG {
     if (exportOptions.verbose) {
       console.log(
         "simple-ffmpeg: Export options:",
-        JSON.stringify(exportOptions, null, 2)
+        JSON.stringify(exportOptions, null, 2),
       );
     }
 
@@ -1091,12 +1064,12 @@ class SIMPLEFFMPEG {
       try {
         fs.writeFileSync(exportOptions.saveCommand, command, "utf8");
         console.log(
-          `simple-ffmpeg: Command saved to ${exportOptions.saveCommand}`
+          `simple-ffmpeg: Command saved to ${exportOptions.saveCommand}`,
         );
       } catch (writeError) {
         throw new SimpleffmpegError(
           `Failed to save command to "${exportOptions.saveCommand}": ${writeError.message}`,
-          { cause: writeError }
+          { cause: writeError },
         );
       }
     }
@@ -1108,7 +1081,7 @@ class SIMPLEFFMPEG {
       if (exportOptions.twoPass && exportOptions.videoBitrate && hasVideo) {
         const passLogFile = path.join(
           this.options.tempDir || path.dirname(exportOptions.outputPath),
-          `ffmpeg2pass-${Date.now()}`
+          `ffmpeg2pass-${Date.now()}`,
         );
 
         // First pass
@@ -1219,6 +1192,7 @@ class SIMPLEFFMPEG {
           batchSize: exportOptions.textMaxNodesPerPass,
           onLog,
           tempDir: this.options.tempDir,
+          signal,
         });
         passes = textPasses;
         if (finalPath !== exportOptions.outputPath) {
@@ -1270,12 +1244,12 @@ class SIMPLEFFMPEG {
         fileSizeStr = formatBytes(size);
       } catch (_) {}
       console.log(
-        `simple-ffmpeg: Output -> ${exportOptions.outputPath} (${fileSizeStr})`
+        `simple-ffmpeg: Output -> ${exportOptions.outputPath} (${fileSizeStr})`,
       );
       console.log(
         `simple-ffmpeg: Export finished in ${(elapsedMs / 1000).toFixed(
-          2
-        )}s (video:${visualCount}, audio:${audioCount}, music:${musicCount}, textPasses:${passes})`
+          2,
+        )}s (video:${visualCount}, audio:${audioCount}, music:${musicCount}, textPasses:${passes})`,
       );
 
       await this._cleanup();
@@ -1360,14 +1334,14 @@ class SIMPLEFFMPEG {
 
     // Filter to visual clips (video + image + color)
     const visual = resolved.filter(
-      (c) => c.type === "video" || c.type === "image" || c.type === "color"
+      (c) => c.type === "video" || c.type === "image" || c.type === "color",
     );
 
     if (visual.length === 0) return 0;
 
     const baseSum = visual.reduce(
       (acc, c) => acc + Math.max(0, (c.end || 0) - (c.position || 0)),
-      0
+      0,
     );
 
     const transitionsOverlap = visual.reduce((acc, c) => {
@@ -1381,6 +1355,45 @@ class SIMPLEFFMPEG {
     return Math.max(0, baseSum - transitionsOverlap);
   }
 
+  /**
+   * Calculate the total transition overlap for a clips configuration.
+   * Resolves shorthand (duration, auto-sequencing) before computing.
+   * Returns the total seconds consumed by xfade transition overlaps
+   * among visual clips (video, image, color).
+   *
+   * This is a pure function — same clips always produce the same result.
+   * No file I/O is performed.
+   *
+   * @param {Array} clips - Array of clip objects
+   * @returns {number} Total transition overlap in seconds
+   *
+   * @example
+   * const overlap = SIMPLEFFMPEG.getTransitionOverlap([
+   *   { type: "video", url: "./a.mp4", duration: 5 },
+   *   { type: "video", url: "./b.mp4", duration: 10, transition: { type: "fade", duration: 0.5 } },
+   * ]);
+   * // overlap === 0.5
+   */
+  static getTransitionOverlap(clips) {
+    if (!Array.isArray(clips) || clips.length === 0) return 0;
+
+    const { clips: resolved } = resolveClips(clips);
+
+    const visual = resolved.filter(
+      (c) => c.type === "video" || c.type === "image" || c.type === "color",
+    );
+
+    if (visual.length === 0) return 0;
+
+    return visual.reduce((acc, c) => {
+      const d =
+        c.transition && typeof c.transition.duration === "number"
+          ? c.transition.duration
+          : 0;
+      return acc + d;
+    }, 0);
+  }
+
   /**
    * Probe a media file and return comprehensive metadata.
    *
@@ -1454,12 +1467,12 @@ class SIMPLEFFMPEG {
   static async snapshot(filePath, options = {}) {
     if (!filePath) {
       throw new SimpleffmpegError(
-        "snapshot() requires a filePath as the first argument"
+        "snapshot() requires a filePath as the first argument",
       );
     }
     if (!options.outputPath) {
       throw new SimpleffmpegError(
-        "snapshot() requires options.outputPath to be specified"
+        "snapshot() requires options.outputPath to be specified",
       );
     }
 
@@ -1531,7 +1544,7 @@ class SIMPLEFFMPEG {
   static async extractKeyframes(filePath, options = {}) {
     if (!filePath) {
       throw new SimpleffmpegError(
-        "extractKeyframes() requires a filePath as the first argument"
+        "extractKeyframes() requires a filePath as the first argument",
       );
     }
 
@@ -1550,13 +1563,13 @@ class SIMPLEFFMPEG {
 
     if (mode !== "scene-change" && mode !== "interval") {
       throw new SimpleffmpegError(
-        `extractKeyframes() invalid mode: "${mode}". Must be "scene-change" or "interval".`
+        `extractKeyframes() invalid mode: "${mode}". Must be "scene-change" or "interval".`,
       );
     }
 
     if (format !== "jpeg" && format !== "png") {
       throw new SimpleffmpegError(
-        `extractKeyframes() invalid format: "${format}". Must be "jpeg" or "png".`
+        `extractKeyframes() invalid format: "${format}". Must be "jpeg" or "png".`,
       );
     }
 
@@ -1567,7 +1580,7 @@ class SIMPLEFFMPEG {
         sceneThreshold > 1)
     ) {
       throw new SimpleffmpegError(
-        "extractKeyframes() sceneThreshold must be a number between 0 and 1."
+        "extractKeyframes() sceneThreshold must be a number between 0 and 1.",
       );
     }
 
@@ -1576,19 +1589,19 @@ class SIMPLEFFMPEG {
       (typeof intervalSeconds !== "number" || intervalSeconds <= 0)
     ) {
       throw new SimpleffmpegError(
-        "extractKeyframes() intervalSeconds must be a positive number."
+        "extractKeyframes() intervalSeconds must be a positive number.",
       );
     }
 
     if (maxFrames != null && (!Number.isInteger(maxFrames) || maxFrames < 1)) {
       throw new SimpleffmpegError(
-        "extractKeyframes() maxFrames must be a positive integer."
+        "extractKeyframes() maxFrames must be a positive integer.",
       );
     }
 
     if (tempDir != null && typeof tempDir === "string" && !fs.existsSync(tempDir)) {
       throw new SimpleffmpegError(
-        `extractKeyframes() tempDir "${tempDir}" does not exist.`
+        `extractKeyframes() tempDir "${tempDir}" does not exist.`,
       );
     }
 
@@ -1602,7 +1615,7 @@ class SIMPLEFFMPEG {
     } else {
       const tmpBase = tempDir || os.tmpdir();
       targetDir = await fsPromises.mkdtemp(
-        path.join(tmpBase, "simpleffmpeg-keyframes-")
+        path.join(tmpBase, "simpleffmpeg-keyframes-"),
       );
     }
 
@@ -1637,7 +1650,7 @@ class SIMPLEFFMPEG {
 
     if (useTemp) {
       const buffers = await Promise.all(
-        files.map((f) => fsPromises.readFile(path.join(targetDir, f)))
+        files.map((f) => fsPromises.readFile(path.join(targetDir, f))),
       );
       await fsPromises
         .rm(targetDir, { recursive: true, force: true })