simple-ffmpegjs 0.5.4 → 0.5.5

package/package.json

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

@@ -388,7 +388,7 @@ function validateEffectClip(clip, path, errors) {
  * Validate a single clip and return issues
  */
 function validateClip(clip, index, options = {}) {
-  const { skipFileChecks = false } = options;
+  const { skipFileChecks = false, skipExtensionsCheck = false } = options;
   const errors = [];
   const warnings = [];
   const path = `clips[${index}]`;
@@ -639,7 +639,9 @@ function validateClip(clip, index, options = {}) {
       } catch (_) {}
     }
 
-    validateMediaUrlExtension(clip, path, errors);
+    if (!skipExtensionsCheck) {
+      validateMediaUrlExtension(clip, path, errors);
+    }
 
     if (typeof clip.cutFrom === "number") {
       if (!Number.isFinite(clip.cutFrom)) {
@@ -1406,6 +1408,7 @@ function validateTimelineGaps(clips) {
  * @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 validation)
+ * @param {boolean} options.skipExtensionsCheck - Skip media extension/type checks (video/image)
  * @returns {Object} Validation result { valid, errors, warnings }
  */
 function validateConfig(clips, options = {}) {

package/src/simpleffmpeg.js

@@ -63,6 +63,8 @@ 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 {boolean} options.skipFileChecks - Skip file existence checks during load() validation
+   * @param {boolean} options.skipExtensionsCheck - Skip media URL extension/type checks (video/image) during load() validation
    * @param {string} options.fontFile - Default font file path (.ttf, .otf) applied to all text clips unless overridden per-clip
    * @param {string} options.emojiFont - Path to a .ttf/.otf emoji font for rendering emoji in text overlays (opt-in). Without this, emoji are silently stripped from text. Recommended: Noto Emoji (B&W outline).
    * @param {string} options.tempDir - Custom directory for temporary files (gradient images, unrotated videos, intermediate renders). Defaults to os.tmpdir(). Useful for fast SSDs, ramdisks, or environments with constrained /tmp.
@@ -97,6 +99,8 @@ class SIMPLEFFMPEG {
       width: options.width || presetConfig.width || C.DEFAULT_WIDTH,
       height: options.height || presetConfig.height || C.DEFAULT_HEIGHT,
       validationMode: options.validationMode || C.DEFAULT_VALIDATION_MODE,
+      skipFileChecks: options.skipFileChecks === true,
+      skipExtensionsCheck: options.skipExtensionsCheck === true,
       preset: options.preset || null,
       fontFile: options.fontFile || null,
       emojiFont: options.emojiFont || null,
@@ -279,6 +283,9 @@ class SIMPLEFFMPEG {
    * @param {string} clipObjs[].text - Text content (for text clips)
    * @param {string} clipObjs[].mode - Text mode: 'static', 'word-replace', 'word-sequential', 'karaoke'
    * @param {string} clipObjs[].kenBurns - Ken Burns effect for images: 'zoom-in', 'zoom-out', 'pan-left', etc.
+   * @param {Object} options - Load options
+   * @param {boolean} options.skipFileChecks - Override file existence checks for media URLs
+   * @param {boolean} options.skipExtensionsCheck - Override extension/type validation for media URLs
    * @returns {Promise<void>} Resolves when all clips are loaded
    * @throws {ValidationError} If clip configuration is invalid
    *
@@ -288,7 +295,7 @@ class SIMPLEFFMPEG {
    *   { type: 'text', text: 'Hello', position: 1, end: 4, fontSize: 48 }
    * ]);
    */
-  async load(clipObjs) {
+  async load(clipObjs, options = {}) {
     // Guard against concurrent load() calls
     if (this._isLoading) {
       throw new SimpleffmpegError(
@@ -308,11 +315,21 @@ class SIMPLEFFMPEG {
 
       // Resolve shorthand: duration → end, auto-sequential positioning
       const resolved = resolveClips(clipObjs);
+      const skipExtensionsCheck =
+        typeof options.skipExtensionsCheck === "boolean"
+          ? options.skipExtensionsCheck
+          : this.options.skipExtensionsCheck;
+      const skipFileChecks =
+        typeof options.skipFileChecks === "boolean"
+          ? options.skipFileChecks
+          : this.options.skipFileChecks;
 
       // Merge resolution errors into validation
       const result = validateConfig(resolved.clips, {
         width: this.options.width,
         height: this.options.height,
+        skipFileChecks,
+        skipExtensionsCheck,
       });
 
       // Prepend resolution errors (e.g. duration+end conflict)
@@ -1286,6 +1303,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 {boolean} options.skipExtensionsCheck - Skip media URL extension/type checks (video/image)
    * @returns {Object} Validation result { valid, errors, warnings }
    *
    * @example

package/types/index.d.mts

@@ -434,6 +434,8 @@ declare namespace SIMPLEFFMPEG {
   interface ValidateOptions {
     /** Skip file existence checks (useful for AI generating configs before files exist) */
     skipFileChecks?: boolean;
+    /** Skip media URL extension/type checks for video/image clips */
+    skipExtensionsCheck?: boolean;
     /** Project width - used to validate Ken Burns images are large enough */
     width?: number;
     /** Project height - used to validate Ken Burns images are large enough */
@@ -453,6 +455,10 @@ declare namespace SIMPLEFFMPEG {
     height?: number;
     /** Validation mode: 'warn' logs warnings, 'strict' throws on warnings (default: 'warn') */
     validationMode?: "warn" | "strict";
+    /** Skip file existence checks during load() validation */
+    skipFileChecks?: boolean;
+    /** Skip media URL extension/type checks for video/image clips during load() validation */
+    skipExtensionsCheck?: boolean;
     /** Default font file path (.ttf, .otf) applied to all text clips. Individual clips can override this with their own fontFile. */
     fontFile?: string;
     /** Path to a .ttf/.otf emoji font for rendering emoji in text overlays (opt-in). Without this, emoji are silently stripped from text. Recommended: Noto Emoji (B&W outline). */
@@ -868,6 +874,14 @@ declare namespace SIMPLEFFMPEG {
     totalDuration: number;
   }
 
+  /** Options for load() */
+  interface LoadOptions {
+    /** Override file existence checks for media URLs */
+    skipFileChecks?: boolean;
+    /** Override extension/type validation for media URLs (video/image) */
+    skipExtensionsCheck?: boolean;
+  }
+
   // ─────────────────────────────────────────────────────────────────────────────
   // Media Info (probe)
   // ─────────────────────────────────────────────────────────────────────────────
@@ -911,8 +925,12 @@ declare class SIMPLEFFMPEG {
   /**
    * Load clips into the project
    * @param clips Array of clip descriptors (video, audio, text, image, music)
+   * @param options Load options
    */
-  load(clips: SIMPLEFFMPEG.Clip[]): Promise<void[]>;
+  load(
+    clips: SIMPLEFFMPEG.Clip[],
+    options?: SIMPLEFFMPEG.LoadOptions
+  ): Promise<void[]>;
 
   /**
    * Get a preview of the FFmpeg command without executing it (dry-run)

package/types/index.d.ts

@@ -434,6 +434,8 @@ declare namespace SIMPLEFFMPEG {
   interface ValidateOptions {
     /** Skip file existence checks (useful for AI generating configs before files exist) */
     skipFileChecks?: boolean;
+    /** Skip media URL extension/type checks for video/image clips */
+    skipExtensionsCheck?: boolean;
     /** Project width - used to validate Ken Burns images are large enough */
     width?: number;
     /** Project height - used to validate Ken Burns images are large enough */
@@ -453,6 +455,10 @@ declare namespace SIMPLEFFMPEG {
     height?: number;
     /** Validation mode: 'warn' logs warnings, 'strict' throws on warnings (default: 'warn') */
     validationMode?: "warn" | "strict";
+    /** Skip file existence checks during load() validation */
+    skipFileChecks?: boolean;
+    /** Skip media URL extension/type checks for video/image clips during load() validation */
+    skipExtensionsCheck?: boolean;
     /** Default font file path (.ttf, .otf) applied to all text clips. Individual clips can override this with their own fontFile. */
     fontFile?: string;
     /** Path to a .ttf/.otf emoji font for rendering emoji in text overlays (opt-in). Without this, emoji are silently stripped from text. Recommended: Noto Emoji (B&W outline). */
@@ -868,6 +874,14 @@ declare namespace SIMPLEFFMPEG {
     totalDuration: number;
   }
 
+  /** Options for load() */
+  interface LoadOptions {
+    /** Override file existence checks for media URLs */
+    skipFileChecks?: boolean;
+    /** Override extension/type validation for media URLs (video/image) */
+    skipExtensionsCheck?: boolean;
+  }
+
   // ─────────────────────────────────────────────────────────────────────────────
   // Media Info (probe)
   // ─────────────────────────────────────────────────────────────────────────────
@@ -911,8 +925,12 @@ declare class SIMPLEFFMPEG {
   /**
    * Load clips into the project
    * @param clips Array of clip descriptors (video, audio, text, image, music)
+   * @param options Load options
    */
-  load(clips: SIMPLEFFMPEG.Clip[]): Promise<void[]>;
+  load(
+    clips: SIMPLEFFMPEG.Clip[],
+    options?: SIMPLEFFMPEG.LoadOptions
+  ): Promise<void[]>;
 
   /**
    * Get a preview of the FFmpeg command without executing it (dry-run)