simple-ffmpegjs 0.5.3 → 0.5.4

package/README.md

@@ -8,6 +8,7 @@
   <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
   <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg" alt="Node.js ≥20"></a>
   <a href="https://codecov.io/gh/Fats403/simple-ffmpegjs"><img src="https://codecov.io/gh/Fats403/simple-ffmpegjs/branch/main/graph/badge.svg" alt="Coverage"></a>
+  <img src="https://img.shields.io/badge/dependencies-0-brightgreen.svg" alt="Zero Dependencies">
 </p>
 
 <p align="center">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simple-ffmpegjs",
-  "version": "0.5.3",
+  "version": "0.5.4",
   "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/resolve.js

@@ -11,6 +11,10 @@
  *    `position`, it is placed immediately after the previous clip on the
  *    same track (visual or audio). The first clip defaults to position 0.
  *
+ * 3. **fullDuration**: If an effect or text clip has `fullDuration: true`,
+ *    its position defaults to 0 and end is resolved later in _prepareExport()
+ *    once the visual timeline duration is known.
+ *
  * Clips are shallow-cloned — the caller's original objects are not mutated.
  */
 
@@ -48,6 +52,35 @@ function resolveClips(clips) {
     const c = { ...clip };
     const path = `clips[${index}]`;
 
+    // ── fullDuration shorthand ─────────────────────────────────────────
+    if (c.fullDuration === true) {
+      if (c.end != null) {
+        errors.push({
+          code: "INVALID_VALUE",
+          path: `${path}`,
+          message:
+            "Cannot specify both 'fullDuration' and 'end'. fullDuration spans the entire visual timeline automatically.",
+          received: { fullDuration: true, end: c.end },
+        });
+        return c;
+      }
+      if (c.duration != null) {
+        errors.push({
+          code: "INVALID_VALUE",
+          path: `${path}`,
+          message:
+            "Cannot specify both 'fullDuration' and 'duration'. fullDuration spans the entire visual timeline automatically.",
+          received: { fullDuration: true, duration: c.duration },
+        });
+        return c;
+      }
+      // Default position to 0; end is resolved in _prepareExport()
+      if (c.position == null) {
+        c.position = 0;
+      }
+      return c;
+    }
+
     // ── Conflict check: duration + end ──────────────────────────────────
     if (c.duration != null && c.end != null) {
       errors.push({

package/src/core/validation.js

@@ -474,12 +474,37 @@ function validateClip(clip, index, options = {}) {
     }
   }
 
-  // Types that require position/end on timeline
+  // fullDuration validation
+  const fullDurationTypes = ["effect", "text"];
+  if (clip.fullDuration != null) {
+    if (clip.fullDuration !== true) {
+      errors.push(
+        createIssue(
+          ValidationCodes.INVALID_VALUE,
+          `${path}.fullDuration`,
+          "fullDuration must be true when specified",
+          clip.fullDuration,
+        ),
+      );
+    } else if (!fullDurationTypes.includes(clip.type)) {
+      errors.push(
+        createIssue(
+          ValidationCodes.INVALID_VALUE,
+          `${path}.fullDuration`,
+          `fullDuration is only supported on ${fullDurationTypes.join(", ")} clips`,
+          clip.type,
+        ),
+      );
+    }
+  }
+
+  // Types that require position/end on timeline (unless fullDuration is set)
+  const hasFullDuration = clip.fullDuration === true && fullDurationTypes.includes(clip.type);
   const requiresTimeline = ["video", "audio", "text", "image", "color", "effect"].includes(
     clip.type,
   );
 
-  if (requiresTimeline) {
+  if (requiresTimeline && !hasFullDuration) {
     if (typeof clip.position !== "number") {
       errors.push(
         createIssue(

package/src/schema/modules/effect.js

@@ -8,9 +8,10 @@ module.exports = {
   effect: "vignette" | "filmGrain" | "gaussianBlur" | "colorAdjust"
         | "sepia" | "blackAndWhite" | "sharpen" | "chromaticAberration"
         | "letterbox";                      // Required: effect kind
-  position: number;                         // Required: start time on timeline (seconds)
-  end?: number;                             // End time on timeline (seconds). Use end OR duration, not both.
-  duration?: number;                        // Duration in seconds (alternative to end). end = position + duration.
+  position?: number;                        // Start time on timeline (seconds). Required unless fullDuration is true.
+  end?: number;                             // End time on timeline (seconds). Use end OR duration, not both. Mutually exclusive with fullDuration.
+  duration?: number;                        // Duration in seconds (alternative to end). end = position + duration. Mutually exclusive with fullDuration.
+  fullDuration?: boolean;                   // When true, spans the full visual timeline. Mutually exclusive with end and duration.
   fadeIn?: number;                          // Optional: seconds to ramp in from 0 to full intensity
   fadeOut?: number;                         // Optional: seconds to ramp out from full intensity to 0
   params: EffectParams;                     // Required: effect-specific parameters
@@ -116,7 +117,7 @@ module.exports = {
     "Effect clips are adjustment layers: they modify underlying video during their active window.",
     "Effects do not satisfy visual timeline continuity checks and do not fill gaps.",
     "Use duration instead of end to specify length: end = position + duration. Cannot use both.",
-    "position is required for effect clips (no auto-sequencing).",
+    "position is required unless fullDuration: true is set, which spans the entire visual timeline.",
     "fadeIn/fadeOut are optional linear envelope controls that avoid abrupt on/off changes.",
     "params.amount is a normalized blend amount from 0 to 1 (default: 1).",
     "filmGrain: use params.strength (0-1) for noise intensity, params.amount for blend alpha.",

package/src/schema/modules/text.js

@@ -5,9 +5,10 @@ module.exports = {
     "Render text overlays on the video with multiple display modes, positioning, styling, and animations.",
   schema: `{
   type: "text";                   // Required: clip type identifier
-  position: number;               // Required: start time on timeline (seconds)
-  end?: number;                   // End time on timeline (seconds). Use end OR duration, not both.
-  duration?: number;              // Duration in seconds (alternative to end). end = position + duration.
+  position?: number;              // Start time on timeline (seconds). Required unless fullDuration is true.
+  end?: number;                   // End time on timeline (seconds). Use end OR duration, not both. Mutually exclusive with fullDuration.
+  duration?: number;              // Duration in seconds (alternative to end). end = position + duration. Mutually exclusive with fullDuration.
+  fullDuration?: boolean;         // When true, spans the full visual timeline. Mutually exclusive with end and duration.
 
   // Content
   text?: string;                  // Text content (required for "static" mode)

package/src/simpleffmpeg.js

@@ -561,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);

package/types/index.d.mts

@@ -4,9 +4,7 @@ declare namespace SIMPLEFFMPEG {
   // ─────────────────────────────────────────────────────────────────────────────
 
   /** Base error class for all simple-ffmpeg errors */
-  class SimpleffmpegError extends Error {
-    name: "SimpleffmpegError";
-  }
+  class SimpleffmpegError extends Error {}
 
   /** Thrown when clip validation fails */
   class ValidationError extends SimpleffmpegError {
@@ -159,8 +157,12 @@ declare namespace SIMPLEFFMPEG {
   interface TextClip {
     type: "text";
     text?: string;
-    position: number;
-    end: number;
+    /** Start time on timeline in seconds. Required unless fullDuration is true. */
+    position?: number;
+    /** End time on timeline in seconds. Mutually exclusive with fullDuration. */
+    end?: number;
+    /** When true, the clip spans the full visual timeline (position 0 to end of last video/image/color clip). Mutually exclusive with end and duration. */
+    fullDuration?: boolean;
     mode?: TextMode;
     words?: TextWordWindow[];
     wordTimestamps?: number[];
@@ -337,12 +339,14 @@ declare namespace SIMPLEFFMPEG {
   interface EffectClip {
     type: "effect";
     effect: EffectName;
-    /** Start time on timeline in seconds. Required for effect clips. */
-    position: number;
-    /** End time on timeline in seconds. Mutually exclusive with duration. */
+    /** Start time on timeline in seconds. Required unless fullDuration is true. */
+    position?: number;
+    /** End time on timeline in seconds. Mutually exclusive with duration and fullDuration. */
     end?: number;
-    /** Duration in seconds (alternative to end). end = position + duration. */
+    /** Duration in seconds (alternative to end). end = position + duration. Mutually exclusive with fullDuration. */
     duration?: number;
+    /** When true, the clip spans the full visual timeline (position 0 to end of last video/image/color clip). Mutually exclusive with end and duration. */
+    fullDuration?: boolean;
     /** Ramp-in duration in seconds */
     fadeIn?: number;
     /** Ramp-out duration in seconds */
@@ -979,6 +983,26 @@ declare class SIMPLEFFMPEG {
    */
   static getDuration(clips: SIMPLEFFMPEG.Clip[]): number;
 
+  /**
+   * Calculate the total transition overlap for a clips configuration.
+   * Returns the total seconds consumed by xfade transition overlaps
+   * among visual clips (video, image, color).
+   *
+   * Pure function — same clips always produce the same result. No file I/O.
+   *
+   * @param clips - Array of clip objects
+   * @returns 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: SIMPLEFFMPEG.Clip[]): number;
+
   /**
    * Probe a media file and return comprehensive metadata.
    *
@@ -1066,36 +1090,6 @@ declare class SIMPLEFFMPEG {
    */
   static formatValidationResult(result: SIMPLEFFMPEG.ValidationResult): string;
 
-  /**
-   * Validation error codes for programmatic handling
-   */
-  static readonly ValidationCodes: typeof SIMPLEFFMPEG.ValidationCodes;
-
-  /**
-   * Base error class for all simple-ffmpeg errors
-   */
-  static readonly SimpleffmpegError: typeof SIMPLEFFMPEG.SimpleffmpegError;
-
-  /**
-   * Thrown when clip validation fails
-   */
-  static readonly ValidationError: typeof SIMPLEFFMPEG.ValidationError;
-
-  /**
-   * Thrown when FFmpeg command execution fails
-   */
-  static readonly FFmpegError: typeof SIMPLEFFMPEG.FFmpegError;
-
-  /**
-   * Thrown when a media file cannot be found or accessed
-   */
-  static readonly MediaNotFoundError: typeof SIMPLEFFMPEG.MediaNotFoundError;
-
-  /**
-   * Thrown when export is cancelled via AbortSignal
-   */
-  static readonly ExportCancelledError: typeof SIMPLEFFMPEG.ExportCancelledError;
-
   /**
    * Get the clip schema as formatted prompt-ready text.
    * Returns a structured description of all clip types accepted by load(),

package/types/index.d.ts

@@ -4,9 +4,7 @@ declare namespace SIMPLEFFMPEG {
   // ─────────────────────────────────────────────────────────────────────────────
 
   /** Base error class for all simple-ffmpeg errors */
-  class SimpleffmpegError extends Error {
-    name: "SimpleffmpegError";
-  }
+  class SimpleffmpegError extends Error {}
 
   /** Thrown when clip validation fails */
   class ValidationError extends SimpleffmpegError {
@@ -159,8 +157,12 @@ declare namespace SIMPLEFFMPEG {
   interface TextClip {
     type: "text";
     text?: string;
-    position: number;
-    end: number;
+    /** Start time on timeline in seconds. Required unless fullDuration is true. */
+    position?: number;
+    /** End time on timeline in seconds. Mutually exclusive with fullDuration. */
+    end?: number;
+    /** When true, the clip spans the full visual timeline (position 0 to end of last video/image/color clip). Mutually exclusive with end and duration. */
+    fullDuration?: boolean;
     mode?: TextMode;
     words?: TextWordWindow[];
     wordTimestamps?: number[];
@@ -337,12 +339,14 @@ declare namespace SIMPLEFFMPEG {
   interface EffectClip {
     type: "effect";
     effect: EffectName;
-    /** Start time on timeline in seconds. Required for effect clips. */
-    position: number;
-    /** End time on timeline in seconds. Mutually exclusive with duration. */
+    /** Start time on timeline in seconds. Required unless fullDuration is true. */
+    position?: number;
+    /** End time on timeline in seconds. Mutually exclusive with duration and fullDuration. */
     end?: number;
-    /** Duration in seconds (alternative to end). end = position + duration. */
+    /** Duration in seconds (alternative to end). end = position + duration. Mutually exclusive with fullDuration. */
     duration?: number;
+    /** When true, the clip spans the full visual timeline (position 0 to end of last video/image/color clip). Mutually exclusive with end and duration. */
+    fullDuration?: boolean;
     /** Ramp-in duration in seconds */
     fadeIn?: number;
     /** Ramp-out duration in seconds */
@@ -1086,36 +1090,6 @@ declare class SIMPLEFFMPEG {
    */
   static formatValidationResult(result: SIMPLEFFMPEG.ValidationResult): string;
 
-  /**
-   * Validation error codes for programmatic handling
-   */
-  static readonly ValidationCodes: typeof SIMPLEFFMPEG.ValidationCodes;
-
-  /**
-   * Base error class for all simple-ffmpeg errors
-   */
-  static readonly SimpleffmpegError: typeof SIMPLEFFMPEG.SimpleffmpegError;
-
-  /**
-   * Thrown when clip validation fails
-   */
-  static readonly ValidationError: typeof SIMPLEFFMPEG.ValidationError;
-
-  /**
-   * Thrown when FFmpeg command execution fails
-   */
-  static readonly FFmpegError: typeof SIMPLEFFMPEG.FFmpegError;
-
-  /**
-   * Thrown when a media file cannot be found or accessed
-   */
-  static readonly MediaNotFoundError: typeof SIMPLEFFMPEG.MediaNotFoundError;
-
-  /**
-   * Thrown when export is cancelled via AbortSignal
-   */
-  static readonly ExportCancelledError: typeof SIMPLEFFMPEG.ExportCancelledError;
-
   /**
    * Get the clip schema as formatted prompt-ready text.
    * Returns a structured description of all clip types accepted by load(),