apexify.js 5.0.3 → 5.1.0

package/lib/Canvas/ApexPainter.ts

@@ -1,10 +1,13 @@
-import { createCanvas, loadImage, GlobalFonts, Image, SKRSContext2D  } from "@napi-rs/canvas";
+import { createCanvas, loadImage, Image, SKRSContext2D  } from "@napi-rs/canvas";
 import GIFEncoder from "gifencoder";
-import ffmpeg from 'fluent-ffmpeg';
 import { PassThrough} from "stream";
+import { exec, execSync } from "child_process";
+import { promisify } from "util";
 import axios from 'axios';
 import fs, { PathLike } from "fs";
 import path from "path";
+
+const execAsync = promisify(exec);
 import { OutputFormat, CanvasConfig, TextProperties, ImageProperties, GIFOptions, GIFResults, CustomOptions, cropOptions,
     drawBackgroundGradient, drawBackgroundColor, customBackground, customLines,
     converter, resizingImg, applyColorFilters, imgEffects,verticalBarChart, pieChart,
@@ -159,7 +162,13 @@ export class ApexPainter {
       // Handle video background inherit sizing
       if (canvas.videoBg) {
         try {
-          const frameBuffer = await this.#extractVideoFrame(canvas.videoBg.source, canvas.videoBg.frame ?? 0);
+          const frameBuffer = await this.#extractVideoFrame(
+            canvas.videoBg.source, 
+            canvas.videoBg.frame ?? 0,
+            canvas.videoBg.time,
+            canvas.videoBg.format || 'jpg',
+            canvas.videoBg.quality || 2
+          );
           if (frameBuffer) {
             const img = await loadImage(frameBuffer);
             if (!canvas.width) canvas.width = img.width;
@@ -218,23 +227,61 @@ export class ApexPainter {
         ctx.globalCompositeOperation = blendMode as GlobalCompositeOperation;
       }
 
-      // Draw video background if specified
+      // Draw background - videoBg takes priority, then customBg, then gradientBg, then colorBg
       if (videoBg) {
         try {
-          const frameBuffer = await this.#extractVideoFrame(videoBg.source, videoBg.frame ?? 0);
-          if (frameBuffer) {
-            const videoImg = await loadImage(frameBuffer);
-            ctx.globalAlpha = videoBg.opacity ?? 1;
-            ctx.drawImage(videoImg, 0, 0, width, height);
-            ctx.globalAlpha = opacity;
+          // For videoBg, always use PNG format to ensure compatibility with loadImage
+          // The rgb24 pixel format for JPEG can cause issues with loadImage
+          const frameBuffer = await this.#extractVideoFrame(
+            videoBg.source, 
+            videoBg.frame ?? 0,
+            videoBg.time,
+            'png', // Force PNG format for videoBg to ensure proper color rendering
+            2
+          );
+          if (frameBuffer && frameBuffer.length > 0) {
+            // Try loading from buffer first, if that fails, save to temp file and load from file
+            // This is a workaround for potential buffer compatibility issues with loadImage
+            let videoImg: Image;
+            try {
+              videoImg = await loadImage(frameBuffer);
+            } catch (bufferError) {
+              // If loading from buffer fails, try saving to temp file and loading from file
+              const tempFramePath = path.join(process.cwd(), '.temp-frames', `video-bg-temp-${Date.now()}.png`);
+              const frameDir = path.dirname(tempFramePath);
+              if (!fs.existsSync(frameDir)) {
+                fs.mkdirSync(frameDir, { recursive: true });
+              }
+              fs.writeFileSync(tempFramePath, frameBuffer);
+              videoImg = await loadImage(tempFramePath);
+              // Cleanup temp file after loading
+              if (fs.existsSync(tempFramePath)) {
+                fs.unlinkSync(tempFramePath);
+              }
+            }
+            
+            if (videoImg && videoImg.width > 0 && videoImg.height > 0) {
+              ctx.globalAlpha = videoBg.opacity ?? 1;
+              // Draw the video frame to fill the entire canvas
+              ctx.drawImage(videoImg, 0, 0, width, height);
+              ctx.globalAlpha = opacity;
+            } else {
+              throw new Error(`Extracted video frame has invalid dimensions: ${videoImg?.width}x${videoImg?.height}`);
+            }
+          } else {
+            throw new Error('Frame extraction returned empty buffer');
           }
         } catch (e: unknown) {
-          console.warn('createCanvas: Failed to load video background frame');
+          const errorMsg = e instanceof Error ? e.message : 'Unknown error';
+          // Re-throw FFmpeg installation errors so user sees installation guide
+          if (errorMsg.includes('FFMPEG NOT FOUND') || errorMsg.includes('FFmpeg')) {
+            throw e;
+          }
+          // Re-throw other errors instead of silently failing with black background
+          throw new Error(`createCanvas: videoBg extraction failed: ${errorMsg}`);
         }
-      }
-
-      // Draw custom background with filters and opacity support
-      if (customBg) {
+      } else if (customBg) {
+        // Draw custom background with filters and opacity support
         await customBackground(ctx, { ...canvas, blur });
         // Apply filters to background if specified
         if (customBg.filters && customBg.filters.length > 0) {
@@ -258,6 +305,7 @@ export class ApexPainter {
       } else if (gradientBg) {
         await drawBackgroundGradient(ctx, { ...canvas, blur });
       } else {
+        // Default to black background if no background is specified
         await drawBackgroundColor(ctx, { ...canvas, blur, colorBg: colorBg ?? '#000' });
       }
 
@@ -1057,7 +1105,7 @@ export class ApexPainter {
       return fs.createWriteStream(outputFile);
   }
 
-  function createBufferStream() {
+  function createBufferStream(): PassThrough & { getBuffer: () => Buffer; chunks: Buffer[] } {
       const bufferStream = new PassThrough();
       const chunks: Buffer[] = [];
   
@@ -1065,12 +1113,14 @@ export class ApexPainter {
           chunks.push(chunk);
       });
   
-      return {
-          ...bufferStream,
-          getBuffer: function (): Buffer {
-              return Buffer.concat(chunks);
-          }
-      } as PassThrough & { getBuffer: () => Buffer };
+      // Properly extend the stream object
+      const extendedStream = bufferStream as PassThrough & { getBuffer: () => Buffer; chunks: Buffer[] };
+      extendedStream.getBuffer = function (): Buffer {
+          return Buffer.concat(chunks);
+      };
+      extendedStream.chunks = chunks;
+  
+      return extendedStream;
   }
 
       // Validation is done in #validateGIFOptions
@@ -1079,7 +1129,9 @@ export class ApexPainter {
       const canvasHeight = options.height || 1200;
 
       const encoder = new GIFEncoder(canvasWidth, canvasHeight);
-      const outputStream = options.outputFile ? createOutputStream(options.outputFile) : createBufferStream();
+      // Use buffer stream for buffer/base64/attachment, file stream only for 'file' format
+      const useBufferStream = options.outputFormat !== "file";
+      const outputStream = useBufferStream ? createBufferStream() : (options.outputFile ? createOutputStream(options.outputFile) : createBufferStream());
       
       encoder.createReadStream().pipe(outputStream);
       
@@ -1114,12 +1166,17 @@ export class ApexPainter {
       }
       
       encoder.finish();
-      outputStream.end();
       
       if (options.outputFormat === "file") {
+          outputStream.end();
           await new Promise<void>((resolve) => outputStream.on("finish", () => resolve()));
       } else if (options.outputFormat === "base64") {
-          if ('getBuffer' in outputStream) {
+          // Wait for stream to finish before getting buffer
+          await new Promise<void>((resolve) => {
+              outputStream.on("end", () => resolve());
+              outputStream.end();
+          });
+          if ('getBuffer' in outputStream && typeof outputStream.getBuffer === 'function') {
               return outputStream.getBuffer().toString("base64");
           }
           throw new Error("createGIF: Unable to get buffer for base64 output.");
@@ -1127,7 +1184,12 @@ export class ApexPainter {
           const gifStream = encoder.createReadStream();
           return [{ attachment: gifStream, name: "gif.js" }];
       } else if (options.outputFormat === "buffer") {
-          if ('getBuffer' in outputStream) {
+          // Wait for stream to finish before getting buffer
+          await new Promise<void>((resolve) => {
+              outputStream.on("end", () => resolve());
+              outputStream.end();
+          });
+          if ('getBuffer' in outputStream && typeof outputStream.getBuffer === 'function') {
               return outputStream.getBuffer();
           }
           throw new Error("createGIF: Unable to get buffer for buffer output.");
@@ -1482,26 +1544,185 @@ export class ApexPainter {
     }
   }
 
-    /**
-   * Extracts a single frame from a video
+  private _ffmpegAvailable: boolean | null = null;
+  private _ffmpegChecked: boolean = false;
+  private _ffmpegPath: string | null = null;
+
+  /**
+   * Gets comprehensive FFmpeg installation instructions based on OS
+   * @private
+   * @returns Detailed installation instructions
+   */
+  #getFFmpegInstallInstructions(): string {
+    const os = process.platform;
+    let instructions = '\n\n📹 FFMPEG INSTALLATION GUIDE\n';
+    instructions += '═'.repeat(50) + '\n\n';
+
+    if (os === 'win32') {
+      instructions += '🪟 WINDOWS INSTALLATION:\n\n';
+      instructions += 'OPTION 1 - Using Chocolatey (Recommended):\n';
+      instructions += '  1. Open PowerShell as Administrator\n';
+      instructions += '  2. Run: choco install ffmpeg\n';
+      instructions += '  3. Restart your terminal\n\n';
+      
+      instructions += 'OPTION 2 - Using Winget:\n';
+      instructions += '  1. Open PowerShell\n';
+      instructions += '  2. Run: winget install ffmpeg\n';
+      instructions += '  3. Restart your terminal\n\n';
+      
+      instructions += 'OPTION 3 - Manual Installation:\n';
+      instructions += '  1. Visit: https://www.gyan.dev/ffmpeg/builds/\n';
+      instructions += '  2. Download "ffmpeg-release-essentials.zip"\n';
+      instructions += '  3. Extract to C:\\ffmpeg\n';
+      instructions += '  4. Add C:\\ffmpeg\\bin to System PATH:\n';
+      instructions += '     - Press Win + X → System → Advanced → Environment Variables\n';
+      instructions += '     - Edit "Path" → Add "C:\\ffmpeg\\bin"\n';
+      instructions += '  5. Restart terminal and verify: ffmpeg -version\n\n';
+      
+      instructions += '🔍 Search Terms: "install ffmpeg windows", "ffmpeg windows tutorial"\n';
+      instructions += '📺 YouTube: Search "How to install FFmpeg on Windows 2024"\n';
+      instructions += '🌐 Official: https://ffmpeg.org/download.html\n';
+    } else if (os === 'darwin') {
+      instructions += '🍎 macOS INSTALLATION:\n\n';
+      instructions += 'OPTION 1 - Using Homebrew (Recommended):\n';
+      instructions += '  1. Install Homebrew if not installed:\n';
+      instructions += '     /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"\n';
+      instructions += '  2. Run: brew install ffmpeg\n';
+      instructions += '  3. Verify: ffmpeg -version\n\n';
+      
+      instructions += 'OPTION 2 - Using MacPorts:\n';
+      instructions += '  1. Install MacPorts from: https://www.macports.org/\n';
+      instructions += '  2. Run: sudo port install ffmpeg\n\n';
+      
+      instructions += '🔍 Search Terms: "install ffmpeg mac", "ffmpeg macos homebrew"\n';
+      instructions += '📺 YouTube: Search "Install FFmpeg on Mac using Homebrew"\n';
+      instructions += '🌐 Official: https://ffmpeg.org/download.html\n';
+    } else {
+      instructions += '🐧 LINUX INSTALLATION:\n\n';
+      instructions += 'Ubuntu/Debian:\n';
+      instructions += '  sudo apt-get update\n';
+      instructions += '  sudo apt-get install ffmpeg\n\n';
+      
+      instructions += 'RHEL/CentOS/Fedora:\n';
+      instructions += '  sudo yum install ffmpeg\n';
+      instructions += '  # OR for newer versions:\n';
+      instructions += '  sudo dnf install ffmpeg\n\n';
+      
+      instructions += 'Arch Linux:\n';
+      instructions += '  sudo pacman -S ffmpeg\n\n';
+      
+      instructions += '🔍 Search Terms: "install ffmpeg [your-distro]", "ffmpeg linux tutorial"\n';
+      instructions += '📺 YouTube: Search "Install FFmpeg on Linux"\n';
+      instructions += '🌐 Official: https://ffmpeg.org/download.html\n';
+    }
+
+    instructions += '\n' + '═'.repeat(50) + '\n';
+    instructions += '✅ After installation, restart your terminal and verify with: ffmpeg -version\n';
+    instructions += '💡 If still not working, ensure FFmpeg is in your system PATH\n';
+    
+    return instructions;
+  }
+
+  /**
+   * Checks if ffmpeg is available in the system (cached check)
    * @private
+   * @returns Promise<boolean> - True if ffmpeg is available
+   */
+  async #checkFFmpegAvailable(): Promise<boolean> {
+    // Cache the result to avoid multiple checks
+    if (this._ffmpegChecked) {
+      return this._ffmpegAvailable ?? false;
+    }
+
+    try {
+      // Try to execute ffmpeg -version (suppress output)
+      await execAsync('ffmpeg -version', { 
+        timeout: 5000,
+        maxBuffer: 1024 * 1024 // 1MB buffer
+      });
+      this._ffmpegAvailable = true;
+      this._ffmpegChecked = true;
+      this._ffmpegPath = 'ffmpeg';
+      return true;
+    } catch {
+      // Try common installation paths
+      const commonPaths = process.platform === 'win32' ? [
+        'C:\\ffmpeg\\bin\\ffmpeg.exe',
+        'C:\\Program Files\\ffmpeg\\bin\\ffmpeg.exe',
+        'C:\\Program Files (x86)\\ffmpeg\\bin\\ffmpeg.exe'
+      ] : [
+        '/usr/bin/ffmpeg',
+        '/usr/local/bin/ffmpeg',
+        '/opt/homebrew/bin/ffmpeg',
+        '/opt/local/bin/ffmpeg'
+      ];
+
+      for (const ffmpegPath of commonPaths) {
+        try {
+          await execAsync(`"${ffmpegPath}" -version`, { 
+            timeout: 3000,
+            maxBuffer: 1024 * 1024
+          });
+          this._ffmpegAvailable = true;
+          this._ffmpegChecked = true;
+          this._ffmpegPath = ffmpegPath;
+          return true;
+        } catch {
+          continue;
+        }
+      }
+
+      this._ffmpegAvailable = false;
+      this._ffmpegChecked = true;
+      return false;
+    }
+  }
+
+  /**
+   * Gets video information (duration, resolution, fps, etc.)
    * @param videoSource - Video source (path, URL, or Buffer)
-   * @param frameNumber - Frame number to extract (default: 0)
-   * @returns Buffer containing the frame image
+   * @returns Video metadata object
    */
-  async #extractVideoFrame(videoSource: string | Buffer, frameNumber: number = 0): Promise<Buffer | null> {
+  /**
+   * Gets video information (duration, resolution, fps, etc.)
+   * @param videoSource - Video source (path, URL, or Buffer)
+   * @param skipFFmpegCheck - Skip FFmpeg availability check (for internal use, default: false)
+   * @returns Video metadata object
+   */
+  async getVideoInfo(videoSource: string | Buffer, skipFFmpegCheck: boolean = false): Promise<{
+    duration: number;
+    width: number;
+    height: number;
+    fps: number;
+    bitrate: number;
+    format: string;
+  } | null> {
     try {
+      // Skip FFmpeg check if we already know it's available (for internal calls)
+      if (!skipFFmpegCheck) {
+        const ffmpegAvailable = await this.#checkFFmpegAvailable();
+        if (!ffmpegAvailable) {
+          const errorMessage = 
+            '❌ FFMPEG NOT FOUND\n' +
+            'Video processing features require FFmpeg to be installed on your system.\n' +
+            this.#getFFmpegInstallInstructions();
+          
+          throw new Error(errorMessage);
+        }
+      }
+
       const frameDir = path.join(process.cwd(), '.temp-frames');
       if (!fs.existsSync(frameDir)) {
         fs.mkdirSync(frameDir, { recursive: true });
       }
 
+      let videoPath: string;
       const tempVideoPath = path.join(frameDir, `temp-video-${Date.now()}.mp4`);
-      const frameOutputPath = path.join(frameDir, `frame-${Date.now()}.jpg`);
 
       // Handle video source
       if (Buffer.isBuffer(videoSource)) {
         fs.writeFileSync(tempVideoPath, videoSource);
+        videoPath = tempVideoPath;
       } else if (typeof videoSource === 'string' && videoSource.startsWith('http')) {
         const response = await axios({
           method: 'get',
@@ -1509,62 +1730,204 @@ export class ApexPainter {
           responseType: 'arraybuffer'
         });
         fs.writeFileSync(tempVideoPath, Buffer.from(response.data));
+        videoPath = tempVideoPath;
       } else {
-        // Local file path
         if (!fs.existsSync(videoSource)) {
           throw new Error(`Video file not found: ${videoSource}`);
         }
-        // Use the existing path
-        return await new Promise<Buffer | null>((resolve, reject) => {
-          ffmpeg(videoSource)
-            .seekInput(frameNumber / 1000) // Convert frame to seconds (approximate)
-            .frames(1)
-            .output(frameOutputPath)
-            .on('end', () => {
-              try {
-                const buffer = fs.readFileSync(frameOutputPath);
-                // Cleanup
-                if (fs.existsSync(frameOutputPath)) fs.unlinkSync(frameOutputPath);
-                resolve(buffer);
-              } catch (e) {
-                resolve(null);
-              }
-            })
-            .on('error', (err: any) => {
-              reject(err);
-            })
-            .run();
+        videoPath = videoSource;
+      }
+
+      // Use ffprobe to get video info (escape path for Windows)
+      const escapedPath = videoPath.replace(/"/g, '\\"');
+      const { stdout } = await execAsync(
+        `ffprobe -v error -show_entries stream=width,height,r_frame_rate,bit_rate -show_entries format=duration,format_name -of json "${escapedPath}"`,
+        { 
+          timeout: 30000, // 30 second timeout
+          maxBuffer: 10 * 1024 * 1024 // 10MB buffer for large JSON responses
+        }
+      );
+
+      const info = JSON.parse(stdout);
+      const videoStream = info.streams?.find((s: any) => s.width && s.height) || info.streams?.[0];
+      const format = info.format || {};
+
+      // Parse frame rate (e.g., "30/1" -> 30)
+      const fps = videoStream?.r_frame_rate 
+        ? (() => {
+            const [num, den] = videoStream.r_frame_rate.split('/').map(Number);
+            return den ? num / den : num;
+          })()
+        : 30;
+
+      const result = {
+        duration: parseFloat(format.duration || '0'),
+        width: parseInt(videoStream?.width || '0'),
+        height: parseInt(videoStream?.height || '0'),
+        fps: fps,
+        bitrate: parseInt(videoStream?.bit_rate || format.bit_rate || '0'),
+        format: format.format_name || 'unknown'
+      };
+
+      // Cleanup temp file if created
+      if (videoPath === tempVideoPath && fs.existsSync(tempVideoPath)) {
+        fs.unlinkSync(tempVideoPath);
+      }
+
+      return result;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+      // Re-throw FFmpeg installation errors
+      if (errorMessage.includes('FFMPEG NOT FOUND') || errorMessage.includes('FFmpeg')) {
+        throw error;
+      }
+      throw new Error(`getVideoInfo failed: ${errorMessage}`);
+    }
+  }
+
+  /**
+   * Extracts a single frame from a video at a specific time or frame number
+   * @private
+   * @param videoSource - Video source (path, URL, or Buffer)
+   * @param frameNumber - Frame number to extract (default: 0)
+   * @param timeSeconds - Alternative: time in seconds (overrides frameNumber if provided)
+   * @param outputFormat - Output image format ('jpg' or 'png', default: 'jpg')
+   * @param quality - JPEG quality 1-31 (lower = better, default: 2) or PNG compression
+   * @returns Buffer containing the frame image
+   */
+  async #extractVideoFrame(
+    videoSource: string | Buffer, 
+    frameNumber: number = 0,
+    timeSeconds?: number,
+    outputFormat: 'jpg' | 'png' = 'jpg',
+    quality: number = 2
+  ): Promise<Buffer | null> {
+    try {
+      const ffmpegAvailable = await this.#checkFFmpegAvailable();
+      if (!ffmpegAvailable) {
+        const errorMessage = 
+          '❌ FFMPEG NOT FOUND\n' +
+          'Video processing features require FFmpeg to be installed on your system.\n' +
+          this.#getFFmpegInstallInstructions();
+        
+        throw new Error(errorMessage);
+      }
+
+      const frameDir = path.join(process.cwd(), '.temp-frames');
+      if (!fs.existsSync(frameDir)) {
+        fs.mkdirSync(frameDir, { recursive: true });
+      }
+
+      const timestamp = Date.now();
+      const tempVideoPath = path.join(frameDir, `temp-video-${timestamp}.mp4`);
+      const frameOutputPath = path.join(frameDir, `frame-${timestamp}.${outputFormat}`);
+
+      let videoPath: string;
+      let shouldCleanupVideo = false;
+
+      // Handle video source
+      if (Buffer.isBuffer(videoSource)) {
+        fs.writeFileSync(tempVideoPath, videoSource);
+        videoPath = tempVideoPath;
+        shouldCleanupVideo = true;
+      } else if (typeof videoSource === 'string' && videoSource.startsWith('http')) {
+        const response = await axios({
+          method: 'get',
+          url: videoSource,
+          responseType: 'arraybuffer'
         });
+        fs.writeFileSync(tempVideoPath, Buffer.from(response.data));
+        videoPath = tempVideoPath;
+        shouldCleanupVideo = true;
+      } else {
+        // Resolve relative paths (similar to customBackground)
+        let resolvedPath = videoSource;
+        if (!/^https?:\/\//i.test(resolvedPath)) {
+          resolvedPath = path.join(process.cwd(), resolvedPath);
+        }
+        
+        if (!fs.existsSync(resolvedPath)) {
+          throw new Error(`Video file not found: ${videoSource} (resolved to: ${resolvedPath})`);
+        }
+        videoPath = resolvedPath;
       }
 
-      // Extract frame from temp video
-      return await new Promise<Buffer | null>((resolve, reject) => {
-        ffmpeg(tempVideoPath)
-          .seekInput(frameNumber / 1000)
-          .frames(1)
-          .output(frameOutputPath)
-          .on('end', () => {
-            try {
-              const buffer = fs.readFileSync(frameOutputPath);
-              // Cleanup
-              if (fs.existsSync(tempVideoPath)) fs.unlinkSync(tempVideoPath);
-              if (fs.existsSync(frameOutputPath)) fs.unlinkSync(frameOutputPath);
-              resolve(buffer);
-            } catch (e) {
-              resolve(null);
-            }
-          })
-          .on('error', (err: any) => {
-            // Cleanup on error
-            if (fs.existsSync(tempVideoPath)) fs.unlinkSync(tempVideoPath);
-            if (fs.existsSync(frameOutputPath)) fs.unlinkSync(frameOutputPath);
-            reject(err);
-          })
-          .run();
-      });
+      // Calculate time in seconds
+      // If time is provided, use it directly (most accurate)
+      // If only frame is provided, we need to get video FPS to convert frame to time
+      let time: number;
+      if (timeSeconds !== undefined) {
+        time = timeSeconds;
+      } else if (frameNumber === 0) {
+        // Frame 0 = start of video
+        time = 0;
+      } else {
+        // Get video FPS to convert frame number to time accurately
+        try {
+          const videoInfo = await this.getVideoInfo(videoPath, true); // Skip FFmpeg check (already done)
+          if (videoInfo && videoInfo.fps > 0) {
+            time = frameNumber / videoInfo.fps;
+          } else {
+            // Fallback to 30 FPS if we can't get video info
+            console.warn(`Could not get video FPS, assuming 30 FPS for frame ${frameNumber}`);
+            time = frameNumber / 30;
+          }
+        } catch (error) {
+          // If getVideoInfo fails, assume 30 FPS (standard video framerate)
+          console.warn(`Could not get video info, assuming 30 FPS for frame ${frameNumber}`);
+          time = frameNumber / 30;
+        }
+      }
+
+      // Build ffmpeg command (escape paths for Windows)
+      // Don't use -f flag, let FFmpeg infer format from file extension
+      // Use -frames:v 1 instead of -vframes 1 (more explicit)
+      // For PNG: use rgba pixel format (best compatibility with loadImage)
+      // For JPEG: don't specify pixel format, let FFmpeg use default (yuvj420p works better than rgb24)
+      const escapedVideoPath = videoPath.replace(/"/g, '\\"');
+      const escapedOutputPath = frameOutputPath.replace(/"/g, '\\"');
+      
+      let command: string;
+      if (outputFormat === 'png') {
+        // PNG: Use rgba pixel format for best compatibility
+        const pixFmt = '-pix_fmt rgba';
+        command = `ffmpeg -i "${escapedVideoPath}" -ss ${time} -frames:v 1 ${pixFmt} -y "${escapedOutputPath}"`;
+      } else {
+        // JPEG: Use quality flag, let FFmpeg choose pixel format (default works better than rgb24)
+        const qualityFlag = `-q:v ${quality}`;
+        command = `ffmpeg -i "${escapedVideoPath}" -ss ${time} -frames:v 1 ${qualityFlag} -y "${escapedOutputPath}"`;
+      }
+
+      try {
+        await execAsync(command, { 
+          timeout: 30000, // 30 second timeout
+          maxBuffer: 10 * 1024 * 1024 // 10MB buffer
+        });
+        
+        if (!fs.existsSync(frameOutputPath)) {
+          throw new Error('Frame extraction failed - output file not created');
+        }
+
+        const buffer = fs.readFileSync(frameOutputPath);
+
+        // Cleanup
+        if (fs.existsSync(frameOutputPath)) fs.unlinkSync(frameOutputPath);
+        if (shouldCleanupVideo && fs.existsSync(tempVideoPath)) fs.unlinkSync(tempVideoPath);
+
+        return buffer;
+      } catch (error) {
+        // Cleanup on error
+        if (fs.existsSync(frameOutputPath)) fs.unlinkSync(frameOutputPath);
+        if (shouldCleanupVideo && fs.existsSync(tempVideoPath)) fs.unlinkSync(tempVideoPath);
+        throw error;
+      }
     } catch (error) {
-      console.error('Error extracting video frame:', error);
-      return null;
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+      // Re-throw FFmpeg installation errors so user sees installation guide
+      if (errorMessage.includes('FFMPEG NOT FOUND') || errorMessage.includes('FFmpeg')) {
+        throw error;
+      }
+      throw new Error(`extractVideoFrame failed: ${errorMessage}`);
     }
   }
 
@@ -1589,83 +1952,2557 @@ export class ApexPainter {
     }
   }
 
+  /**
+   * Extracts multiple frames from a video at specified intervals
+   * @param videoSource - Video source (path, URL, or Buffer)
+   * @param options - Extraction options
+   * @returns Array of frame file paths
+   */
   async extractFrames(videoSource: string | Buffer, options: ExtractFramesOptions): Promise<Array<{ source: string; isRemote: boolean }>> {
     try {
+      const ffmpegAvailable = await this.#checkFFmpegAvailable();
+      if (!ffmpegAvailable) {
+        const errorMessage = 
+          '❌ FFMPEG NOT FOUND\n' +
+          'Video processing features require FFmpeg to be installed on your system.\n' +
+          this.#getFFmpegInstallInstructions();
+        
+        throw new Error(errorMessage);
+      }
+
       this.#validateExtractFramesInputs(videoSource, options);
       
       const frames: Array<{ source: string; isRemote: boolean }> = [];
-      const frameDir = path.join(__dirname, 'frames');
+      const frameDir = path.join(process.cwd(), '.temp-frames', `frames-${Date.now()}`);
 
-  if (!fs.existsSync(frameDir)) {
-      fs.mkdirSync(frameDir);
-  }
+      if (!fs.existsSync(frameDir)) {
+        fs.mkdirSync(frameDir, { recursive: true });
+      }
 
-  const videoPath = typeof videoSource === 'string' ? videoSource : path.join(frameDir, 'temp-video.mp4');
+      const timestamp = Date.now();
+      const videoPath = typeof videoSource === 'string' ? videoSource : path.join(frameDir, `temp-video-${timestamp}.mp4`);
+      let shouldCleanupVideo = false;
 
-  if (Buffer.isBuffer(videoSource)) {
-      fs.writeFileSync(videoPath, videoSource);
-  } else if (videoSource.startsWith('http')) {
-      await axios({
+      // Handle video source
+      if (Buffer.isBuffer(videoSource)) {
+        fs.writeFileSync(videoPath, videoSource);
+        shouldCleanupVideo = true;
+      } else if (typeof videoSource === 'string' && videoSource.startsWith('http')) {
+        const response = await axios({
           method: 'get',
           url: videoSource,
           responseType: 'arraybuffer'
-      })
-      .then((response) => {
-          fs.writeFileSync(videoPath, response.data);
-      })
-      .catch(err => {
-          throw new Error(`Error downloading video: ${err.message}`);
-      });
-  } else if (!fs.existsSync(videoPath)) {
-      throw new Error("Video file not found at specified path.");
-  }
+        });
+        fs.writeFileSync(videoPath, Buffer.from(response.data));
+        shouldCleanupVideo = true;
+      } else if (!fs.existsSync(videoPath)) {
+        throw new Error("Video file not found at specified path.");
+      }
+
+      // Get video duration using ffprobe (escape path for Windows)
+      const escapedVideoPath = videoPath.replace(/"/g, '\\"');
+      const { stdout: probeOutput } = await execAsync(
+        `ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 "${escapedVideoPath}"`,
+        { maxBuffer: 10 * 1024 * 1024 } // 10MB buffer
+      );
+      
+      const duration = parseFloat(probeOutput.trim());
+      if (isNaN(duration) || duration <= 0) {
+        throw new Error("Video duration not found in metadata.");
+      }
 
-  function processVideoExtraction(videoPath: string, frames: any[], options: ExtractFramesOptions, resolve: any, reject: any) {
       const outputFormat = options.outputFormat || 'jpg';
-      const outputFileTemplate = `frame-%03d.${outputFormat}`;
-
-      ffmpeg(videoPath)
-          .on('end', () => {
-              console.log('Frames extracted successfully.');
-              resolve(frames);
-          })
-          .on('error', (err: { message: any; }) => {
-              console.error('Error extracting frames:', err.message);
-              reject(err);
-          })
-          .outputOptions([`-vf fps=1/${options.interval / 1000}`, `-q:v 2`])
-          .saveToFile(path.join(frameDir, outputFileTemplate)); 
-
-      ffmpeg.ffprobe(videoPath, (err: any, metadata: any) => {
-          if (err) {
-              return reject(err);
-          }
-          const duration = metadata?.format?.duration;
-          if (typeof duration !== "number") {
-              return reject(new Error("Video duration not found in metadata."));
-          }
-          const totalFrames = Math.floor(duration * 1000 / options.interval);
-          for (let i = 0; i < totalFrames; i++) {
-              if (options.frameSelection && (i < (options.frameSelection.start || 0) || i > (options.frameSelection.end || totalFrames - 1))) {
-                  continue;
-              }
-              frames.push({
-                  source: path.join(frameDir, `frame-${String(i).padStart(3, '0')}.${outputFormat}`),
-                  isRemote: false
-              });
+      const fps = 1000 / options.interval; // Frames per second based on interval
+      const totalFrames = Math.floor(duration * fps);
+      
+      // Apply frame selection if specified
+      const startFrame = options.frameSelection?.start || 0;
+      const endFrame = options.frameSelection?.end !== undefined 
+        ? Math.min(options.frameSelection.end, totalFrames - 1)
+        : totalFrames - 1;
+
+      // Build ffmpeg command for frame extraction
+      const outputFileTemplate = path.join(frameDir, `frame-%03d.${outputFormat}`);
+      const qualityFlag = outputFormat === 'jpg' ? '-q:v 2' : '';
+      const pixFmt = outputFormat === 'png' ? '-pix_fmt rgba' : '-pix_fmt yuvj420p';
+      
+      // Calculate start and end times
+      const startTime = startFrame / fps;
+      const endTime = (endFrame + 1) / fps;
+      const durationToExtract = endTime - startTime;
+
+      const escapedOutputTemplate = outputFileTemplate.replace(/"/g, '\\"');
+      // Don't use -f flag, let FFmpeg infer format from file extension
+      // -vf fps=${fps} extracts frames at the specified FPS
+      // Use -ss after -i for more accurate frame extraction
+      const command = `ffmpeg -i "${escapedVideoPath}" -ss ${startTime} -t ${durationToExtract} -vf fps=${fps} ${pixFmt} ${qualityFlag} -y "${escapedOutputTemplate}"`;
+
+      try {
+        await execAsync(command, { 
+          timeout: 60000, // 60 second timeout for multiple frames
+          maxBuffer: 10 * 1024 * 1024 // 10MB buffer
+        });
+
+        // Collect all extracted frame files
+        const actualFrameCount = endFrame - startFrame + 1;
+        for (let i = 0; i < actualFrameCount; i++) {
+          const frameNumber = startFrame + i;
+          const framePath = path.join(frameDir, `frame-${String(i + 1).padStart(3, '0')}.${outputFormat}`);
+          
+          if (fs.existsSync(framePath)) {
+            frames.push({
+              source: framePath,
+              isRemote: false
+            });
           }
-      });
-  }
+        }
 
-      return new Promise((resolve, reject) => {
-        processVideoExtraction(videoPath, frames, options, resolve, reject);
-      });
+        // Cleanup temp video if created
+        if (shouldCleanupVideo && fs.existsSync(videoPath)) {
+          fs.unlinkSync(videoPath);
+        }
+
+        return frames;
+      } catch (error) {
+        // Cleanup on error
+        if (shouldCleanupVideo && fs.existsSync(videoPath)) {
+          fs.unlinkSync(videoPath);
+        }
+        throw error;
+      }
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+      // Re-throw FFmpeg installation errors so user sees installation guide
+      if (errorMessage.includes('FFMPEG NOT FOUND') || errorMessage.includes('FFmpeg')) {
+        throw error;
+      }
       throw new Error(`extractFrames failed: ${errorMessage}`);
     }
   }
 
+  /**
+   * Comprehensive video processing method - all video features in one place
+   * @param options - Video processing options
+   * @returns Results based on the operation requested
+   */
+  async createVideo(options: {
+    source: string | Buffer;
+    
+    // Get video information
+    getInfo?: boolean;
+    
+    // Extract single frame (creates canvas)
+    extractFrame?: {
+      time?: number; // Time in seconds
+      frame?: number; // Frame number (1-based, will be converted to time using video FPS)
+      width?: number; // Canvas width (default: video width)
+      height?: number; // Canvas height (default: video height)
+      outputFormat?: 'jpg' | 'png'; // Frame extraction format (default: 'png')
+      quality?: number; // JPEG quality 1-31 (lower = better, default: 2)
+    };
+    
+    // Extract multiple frames at specific times
+    extractFrames?: {
+      times?: number[]; // Array of times in seconds
+      interval?: number; // Extract frames at intervals (milliseconds)
+      frameSelection?: { start?: number; end?: number }; // Frame range for interval extraction
+      outputFormat?: 'jpg' | 'png';
+      quality?: number;
+      outputDirectory?: string; // Directory to save frames (for interval extraction)
+    };
+    
+    // Extract ALL frames from video
+    extractAllFrames?: {
+      outputFormat?: 'jpg' | 'png';
+      outputDirectory?: string;
+      quality?: number;
+      prefix?: string; // Filename prefix (default: 'frame')
+      startTime?: number; // Start time in seconds (default: 0)
+      endTime?: number; // End time in seconds (default: video duration)
+    };
+    
+    // Generate video thumbnail (multiple frames in grid)
+    generateThumbnail?: {
+      count?: number; // Number of frames to extract (default: 9)
+      grid?: { cols: number; rows: number }; // Grid layout (default: 3x3)
+      width?: number; // Thumbnail width (default: 320)
+      height?: number; // Thumbnail height (default: 180)
+      outputFormat?: 'jpg' | 'png';
+      quality?: number;
+    };
+    
+    // Convert video format
+    convert?: {
+      outputPath: string; // Output video file path
+      format?: 'mp4' | 'webm' | 'avi' | 'mov' | 'mkv'; // Output format (default: 'mp4')
+      quality?: 'low' | 'medium' | 'high' | 'ultra'; // Quality preset
+      bitrate?: number; // Custom bitrate in kbps
+      fps?: number; // Output FPS (default: source FPS)
+      resolution?: { width: number; height: number }; // Output resolution
+    };
+    
+    // Trim/Cut video
+    trim?: {
+      startTime: number; // Start time in seconds
+      endTime: number; // End time in seconds
+      outputPath: string; // Output video file path
+    };
+    
+    // Extract audio from video
+    extractAudio?: {
+      outputPath: string; // Output audio file path
+      format?: 'mp3' | 'wav' | 'aac' | 'ogg'; // Audio format (default: 'mp3')
+      bitrate?: number; // Audio bitrate in kbps (default: 128)
+    };
+    
+    // Add watermark to video
+    addWatermark?: {
+      watermarkPath: string; // Watermark image path
+      position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'center';
+      opacity?: number; // Watermark opacity 0-1 (default: 0.5)
+      size?: { width: number; height: number }; // Watermark size
+      outputPath: string; // Output video file path
+    };
+    
+    // Adjust video speed
+    changeSpeed?: {
+      speed: number; // Speed multiplier (0.5 = half speed, 2 = double speed)
+      outputPath: string; // Output video file path
+    };
+    
+    // Extract video preview (multiple frames as images)
+    generatePreview?: {
+      count?: number; // Number of preview frames (default: 10)
+      outputDirectory?: string; // Directory to save preview frames
+      outputFormat?: 'jpg' | 'png';
+      quality?: number;
+    };
+    
+    // Apply video effects/filters
+    applyEffects?: {
+      filters: Array<{
+        type: 'blur' | 'brightness' | 'contrast' | 'saturation' | 'grayscale' | 'sepia' | 'invert' | 'sharpen' | 'noise';
+        intensity?: number; // 0-100
+        value?: number; // For brightness, contrast, saturation (-100 to 100)
+      }>;
+      outputPath: string;
+    };
+    
+    // Merge/Concatenate videos
+    merge?: {
+      videos: Array<string | Buffer>; // Array of video sources
+      outputPath: string;
+      mode?: 'sequential' | 'side-by-side' | 'grid'; // Merge mode
+      grid?: { cols: number; rows: number }; // For grid mode
+    };
+    
+    // Rotate/Flip video
+    rotate?: {
+      angle?: 90 | 180 | 270; // Rotation angle
+      flip?: 'horizontal' | 'vertical' | 'both'; // Flip direction
+      outputPath: string;
+    };
+    
+    // Crop video
+    crop?: {
+      x: number; // Start X position
+      y: number; // Start Y position
+      width: number; // Crop width
+      height: number; // Crop height
+      outputPath: string;
+    };
+    
+    // Compress/Optimize video
+    compress?: {
+      outputPath: string;
+      quality?: 'low' | 'medium' | 'high' | 'ultra'; // Quality preset
+      targetSize?: number; // Target file size in MB
+      maxBitrate?: number; // Max bitrate in kbps
+    };
+    
+    // Add text overlay to video
+    addText?: {
+      text: string;
+      position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'center' | 'top-center' | 'bottom-center';
+      fontSize?: number;
+      fontColor?: string;
+      backgroundColor?: string; // Text background color
+      startTime?: number; // Start time in seconds
+      endTime?: number; // End time in seconds
+      outputPath: string;
+    };
+    
+    // Add fade effects
+    addFade?: {
+      fadeIn?: number; // Fade in duration in seconds
+      fadeOut?: number; // Fade out duration in seconds
+      outputPath: string;
+    };
+    
+    // Reverse video playback
+    reverse?: {
+      outputPath: string;
+    };
+    
+    // Create seamless loop
+    createLoop?: {
+      outputPath: string;
+      smooth?: boolean; // Try to create smooth loop
+    };
+    
+    // Batch process multiple videos
+    batch?: {
+      videos: Array<{ source: string | Buffer; operations: any }>; // Array of videos with their operations
+      outputDirectory: string;
+    };
+    
+    // Detect scene changes
+    detectScenes?: {
+      threshold?: number; // Scene change threshold (0-1)
+      outputPath?: string; // Optional: save scene markers to file
+    };
+    
+    // Stabilize video (reduce shake)
+    stabilize?: {
+      outputPath: string;
+      smoothing?: number; // Smoothing factor (default: 10)
+    };
+    
+    // Color correction
+    colorCorrect?: {
+      brightness?: number; // -100 to 100
+      contrast?: number; // -100 to 100
+      saturation?: number; // -100 to 100
+      hue?: number; // -180 to 180
+      temperature?: number; // Color temperature adjustment
+      outputPath: string;
+    };
+    
+    // Picture-in-picture
+    pictureInPicture?: {
+      overlayVideo: string | Buffer; // Overlay video source
+      position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'center';
+      size?: { width: number; height: number }; // Overlay size
+      opacity?: number; // 0-1
+      outputPath: string;
+    };
+    
+    // Split screen (side-by-side or grid)
+    splitScreen?: {
+      videos: Array<string | Buffer>; // Array of videos
+      layout?: 'side-by-side' | 'top-bottom' | 'grid'; // Layout type
+      grid?: { cols: number; rows: number }; // For grid layout
+      outputPath: string;
+    };
+    
+    // Create time-lapse
+    createTimeLapse?: {
+      speed?: number; // Speed multiplier (default: 10x)
+      outputPath: string;
+    };
+    
+    // Mute/Unmute video
+    mute?: {
+      outputPath: string;
+    };
+    
+    // Adjust audio volume
+    adjustVolume?: {
+      volume: number; // Volume multiplier (0.0 = mute, 1.0 = original, 2.0 = double)
+      outputPath: string;
+    };
+    
+    // Detect video format and codec
+    detectFormat?: boolean; // Returns detailed format information
+  }): Promise<any> {
+    try {
+      const ffmpegAvailable = await this.#checkFFmpegAvailable();
+      if (!ffmpegAvailable) {
+        const errorMessage = 
+          '❌ FFMPEG NOT FOUND\n' +
+          'Video processing features require FFmpeg to be installed on your system.\n' +
+          this.#getFFmpegInstallInstructions();
+        throw new Error(errorMessage);
+      }
+
+      // Get video info if requested or needed
+      let videoInfo: any = null;
+      if (options.getInfo || options.extractFrame?.frame || options.generateThumbnail || options.generatePreview) {
+        videoInfo = await this.getVideoInfo(options.source, true);
+      }
+
+      // Handle getInfo
+      if (options.getInfo) {
+        return videoInfo || await this.getVideoInfo(options.source, true);
+      }
+
+      // Handle extractFrame (creates canvas)
+      if (options.extractFrame) {
+        const frameBuffer = await this.#extractVideoFrame(
+          options.source,
+          options.extractFrame.frame ?? 0,
+          options.extractFrame.time,
+          options.extractFrame.outputFormat || 'png',
+          options.extractFrame.quality || 2
+        );
+
+        if (!frameBuffer || frameBuffer.length === 0) {
+          throw new Error('Failed to extract video frame');
+        }
+
+        const frameImage = await loadImage(frameBuffer);
+        const videoWidth = frameImage.width;
+        const videoHeight = frameImage.height;
+
+        const width = options.extractFrame.width ?? videoWidth;
+        const height = options.extractFrame.height ?? videoHeight;
+
+        const canvas = createCanvas(width, height);
+        const ctx = canvas.getContext('2d') as SKRSContext2D;
+        if (!ctx) {
+          throw new Error('Unable to get 2D context');
+        }
+
+        ctx.drawImage(frameImage, 0, 0, width, height);
+
+        return {
+          buffer: canvas.toBuffer('image/png'),
+          canvas: { width, height }
+        };
+      }
+
+      // Handle extractFrames (multiple frames at specific times or intervals)
+      if (options.extractFrames) {
+        if (options.extractFrames.times) {
+          // Extract frames at specific times
+          const frames: Buffer[] = [];
+          for (const time of options.extractFrames.times) {
+            const frame = await this.#extractVideoFrame(
+              options.source,
+              0,
+              time,
+              options.extractFrames.outputFormat || 'jpg',
+              options.extractFrames.quality || 2
+            );
+            if (frame) {
+              frames.push(frame);
+            }
+          }
+          return frames;
+        } else if (options.extractFrames.interval) {
+          // Extract frames at intervals
+          return await this.extractFrames(options.source, {
+            interval: options.extractFrames.interval,
+            outputFormat: options.extractFrames.outputFormat || 'jpg',
+            frameSelection: options.extractFrames.frameSelection,
+            outputDirectory: options.extractFrames.outputDirectory
+          });
+        }
+      }
+
+      // Handle extractAllFrames
+      if (options.extractAllFrames) {
+        return await this.extractAllFrames(options.source, {
+          outputFormat: options.extractAllFrames.outputFormat,
+          outputDirectory: options.extractAllFrames.outputDirectory,
+          quality: options.extractAllFrames.quality,
+          prefix: options.extractAllFrames.prefix,
+          startTime: options.extractAllFrames.startTime,
+          endTime: options.extractAllFrames.endTime
+        });
+      }
+
+      // Handle generateThumbnail
+      if (options.generateThumbnail) {
+        return await this.#generateVideoThumbnail(options.source, options.generateThumbnail, videoInfo);
+      }
+
+      // Handle convert
+      if (options.convert) {
+        return await this.#convertVideo(options.source, options.convert);
+      }
+
+      // Handle trim
+      if (options.trim) {
+        return await this.#trimVideo(options.source, options.trim);
+      }
+
+      // Handle extractAudio
+      if (options.extractAudio) {
+        return await this.#extractAudio(options.source, options.extractAudio);
+      }
+
+      // Handle addWatermark
+      if (options.addWatermark) {
+        return await this.#addWatermarkToVideo(options.source, options.addWatermark);
+      }
+
+      // Handle changeSpeed
+      if (options.changeSpeed) {
+        return await this.#changeVideoSpeed(options.source, options.changeSpeed);
+      }
+
+      // Handle generatePreview
+      if (options.generatePreview) {
+        return await this.#generateVideoPreview(options.source, options.generatePreview, videoInfo);
+      }
+
+      // Handle applyEffects
+      if (options.applyEffects) {
+        return await this.#applyVideoEffects(options.source, options.applyEffects);
+      }
+
+      // Handle merge
+      if (options.merge) {
+        return await this.#mergeVideos(options.merge);
+      }
+
+      // Handle rotate
+      if (options.rotate) {
+        return await this.#rotateVideo(options.source, options.rotate);
+      }
+
+      // Handle crop
+      if (options.crop) {
+        return await this.#cropVideo(options.source, options.crop);
+      }
+
+      // Handle compress
+      if (options.compress) {
+        return await this.#compressVideo(options.source, options.compress);
+      }
+
+      // Handle addText
+      if (options.addText) {
+        return await this.#addTextToVideo(options.source, options.addText);
+      }
+
+      // Handle addFade
+      if (options.addFade) {
+        return await this.#addFadeToVideo(options.source, options.addFade);
+      }
+
+      // Handle reverse
+      if (options.reverse) {
+        return await this.#reverseVideo(options.source, options.reverse);
+      }
+
+      // Handle createLoop
+      if (options.createLoop) {
+        return await this.#createVideoLoop(options.source, options.createLoop);
+      }
+
+      // Handle batch
+      if (options.batch) {
+        return await this.#batchProcessVideos(options.batch);
+      }
+
+      // Handle detectScenes
+      if (options.detectScenes) {
+        return await this.#detectVideoScenes(options.source, options.detectScenes);
+      }
+
+      // Handle stabilize
+      if (options.stabilize) {
+        return await this.#stabilizeVideo(options.source, options.stabilize);
+      }
+
+      // Handle colorCorrect
+      if (options.colorCorrect) {
+        return await this.#colorCorrectVideo(options.source, options.colorCorrect);
+      }
+
+      // Handle pictureInPicture
+      if (options.pictureInPicture) {
+        return await this.#addPictureInPicture(options.source, options.pictureInPicture);
+      }
+
+      // Handle splitScreen
+      if (options.splitScreen) {
+        return await this.#createSplitScreen(options.splitScreen);
+      }
+
+      // Handle createTimeLapse
+      if (options.createTimeLapse) {
+        return await this.#createTimeLapseVideo(options.source, options.createTimeLapse);
+      }
+
+      // Handle mute
+      if (options.mute) {
+        return await this.#muteVideo(options.source, options.mute);
+      }
+
+      // Handle adjustVolume
+      if (options.adjustVolume) {
+        return await this.#adjustVideoVolume(options.source, options.adjustVolume);
+      }
+
+      // Handle detectFormat
+      if (options.detectFormat) {
+        const info = await this.getVideoInfo(options.source, true);
+        // Try to get codec from ffprobe
+        let codec = 'unknown';
+        try {
+          const frameDir = path.join(process.cwd(), '.temp-frames');
+          let videoPath: string;
+          if (Buffer.isBuffer(options.source)) {
+            const tempPath = path.join(frameDir, `temp-video-${Date.now()}.mp4`);
+            fs.writeFileSync(tempPath, options.source);
+            videoPath = tempPath;
+          } else {
+            let resolvedPath = options.source;
+            if (!/^https?:\/\//i.test(resolvedPath)) {
+              resolvedPath = path.join(process.cwd(), resolvedPath);
+            }
+            videoPath = resolvedPath;
+          }
+          const escapedPath = videoPath.replace(/"/g, '\\"');
+          const { stdout } = await execAsync(
+            `ffprobe -v error -select_streams v:0 -show_entries stream=codec_name -of default=noprint_wrappers=1:nokey=1 "${escapedPath}"`,
+            { timeout: 10000, maxBuffer: 1024 * 1024 }
+          );
+          codec = stdout.toString().trim() || 'unknown';
+        } catch {
+          codec = 'unknown';
+        }
+        
+        return {
+          format: info?.format || 'unknown',
+          codec: codec,
+          container: info?.format || 'unknown',
+          width: info?.width,
+          height: info?.height,
+          fps: info?.fps,
+          bitrate: info?.bitrate,
+          duration: info?.duration
+        };
+      }
+
+      throw new Error('No video operation specified');
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+      if (errorMessage.includes('FFMPEG NOT FOUND') || errorMessage.includes('FFmpeg')) {
+        throw error;
+      }
+      throw new Error(`createVideo failed: ${errorMessage}`);
+    }
+  }
+
+  /**
+   * Generate video thumbnail (grid of frames)
+   * @private
+   */
+  async #generateVideoThumbnail(
+    videoSource: string | Buffer,
+    options: {
+      count?: number;
+      grid?: { cols: number; rows: number };
+      width?: number;
+      height?: number;
+      outputFormat?: 'jpg' | 'png';
+      quality?: number;
+    },
+    videoInfo: any
+  ): Promise<CanvasResults> {
+    const count = options.count || 9;
+    const grid = options.grid || { cols: 3, rows: 3 };
+    const frameWidth = options.width || 320;
+    const frameHeight = options.height || 180;
+    const outputFormat = options.outputFormat || 'jpg';
+    const quality = options.quality || 2;
+
+    if (!videoInfo) {
+      videoInfo = await this.getVideoInfo(videoSource, true);
+    }
+
+    const duration = videoInfo.duration;
+    const interval = duration / (count + 1); // Distribute frames evenly
+
+    // Extract frames
+    const frames: Buffer[] = [];
+    for (let i = 1; i <= count; i++) {
+      const time = interval * i;
+      const frame = await this.#extractVideoFrame(videoSource, 0, time, outputFormat, quality);
+      if (frame) {
+        frames.push(frame);
+      }
+    }
+
+    // Create thumbnail canvas
+    const thumbnailWidth = frameWidth * grid.cols;
+    const thumbnailHeight = frameHeight * grid.rows;
+    const canvas = createCanvas(thumbnailWidth, thumbnailHeight);
+    const ctx = canvas.getContext('2d') as SKRSContext2D;
+    if (!ctx) {
+      throw new Error('Unable to get 2D context');
+    }
+
+    // Draw frames in grid
+    for (let i = 0; i < frames.length; i++) {
+      const row = Math.floor(i / grid.cols);
+      const col = i % grid.cols;
+      const x = col * frameWidth;
+      const y = row * frameHeight;
+
+      const frameImage = await loadImage(frames[i]);
+      ctx.drawImage(frameImage, x, y, frameWidth, frameHeight);
+    }
+
+    return {
+      buffer: canvas.toBuffer('image/png'),
+      canvas: { width: thumbnailWidth, height: thumbnailHeight }
+    };
+  }
+
+  /**
+   * Convert video format
+   * @private
+   */
+  async #convertVideo(
+    videoSource: string | Buffer,
+    options: {
+      outputPath: string;
+      format?: 'mp4' | 'webm' | 'avi' | 'mov' | 'mkv';
+      quality?: 'low' | 'medium' | 'high' | 'ultra';
+      bitrate?: number;
+      fps?: number;
+      resolution?: { width: number; height: number };
+    }
+  ): Promise<{ outputPath: string; success: boolean }> {
+    const frameDir = path.join(process.cwd(), '.temp-frames');
+    if (!fs.existsSync(frameDir)) {
+      fs.mkdirSync(frameDir, { recursive: true });
+    }
+
+    let videoPath: string;
+    let shouldCleanupVideo = false;
+    const timestamp = Date.now();
+
+    // Handle video source
+    if (Buffer.isBuffer(videoSource)) {
+      videoPath = path.join(frameDir, `temp-video-${timestamp}.mp4`);
+      fs.writeFileSync(videoPath, videoSource);
+      shouldCleanupVideo = true;
+    } else {
+      let resolvedPath = videoSource;
+      if (!/^https?:\/\//i.test(resolvedPath)) {
+        resolvedPath = path.join(process.cwd(), resolvedPath);
+      }
+      if (!fs.existsSync(resolvedPath)) {
+        throw new Error(`Video file not found: ${videoSource}`);
+      }
+      videoPath = resolvedPath;
+    }
+
+    const format = options.format || 'mp4';
+    const qualityPresets: Record<string, string> = {
+      low: '-crf 28',
+      medium: '-crf 23',
+      high: '-crf 18',
+      ultra: '-crf 15'
+    };
+    const qualityFlag = options.bitrate 
+      ? `-b:v ${options.bitrate}k` 
+      : qualityPresets[options.quality || 'medium'];
+
+    const fpsFlag = options.fps ? `-r ${options.fps}` : '';
+    const resolutionFlag = options.resolution 
+      ? `-vf scale=${options.resolution.width}:${options.resolution.height}` 
+      : '';
+
+    const escapedVideoPath = videoPath.replace(/"/g, '\\"');
+    const escapedOutputPath = options.outputPath.replace(/"/g, '\\"');
+
+    const command = `ffmpeg -i "${escapedVideoPath}" ${qualityFlag} ${fpsFlag} ${resolutionFlag} -y "${escapedOutputPath}"`;
+
+    try {
+      await execAsync(command, { 
+        timeout: 300000, // 5 minute timeout
+        maxBuffer: 10 * 1024 * 1024
+      });
+
+      if (shouldCleanupVideo && fs.existsSync(videoPath)) {
+        fs.unlinkSync(videoPath);
+      }
+
+      return { outputPath: options.outputPath, success: true };
+    } catch (error) {
+      if (shouldCleanupVideo && fs.existsSync(videoPath)) {
+        fs.unlinkSync(videoPath);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Trim/Cut video
+   * @private
+   */
+  async #trimVideo(
+    videoSource: string | Buffer,
+    options: { startTime: number; endTime: number; outputPath: string }
+  ): Promise<{ outputPath: string; success: boolean }> {
+    const frameDir = path.join(process.cwd(), '.temp-frames');
+    if (!fs.existsSync(frameDir)) {
+      fs.mkdirSync(frameDir, { recursive: true });
+    }
+
+    let videoPath: string;
+    let shouldCleanupVideo = false;
+    const timestamp = Date.now();
+
+    if (Buffer.isBuffer(videoSource)) {
+      videoPath = path.join(frameDir, `temp-video-${timestamp}.mp4`);
+      fs.writeFileSync(videoPath, videoSource);
+      shouldCleanupVideo = true;
+    } else {
+      let resolvedPath = videoSource;
+      if (!/^https?:\/\//i.test(resolvedPath)) {
+        resolvedPath = path.join(process.cwd(), resolvedPath);
+      }
+      if (!fs.existsSync(resolvedPath)) {
+        throw new Error(`Video file not found: ${videoSource}`);
+      }
+      videoPath = resolvedPath;
+    }
+
+    const duration = options.endTime - options.startTime;
+    const escapedVideoPath = videoPath.replace(/"/g, '\\"');
+    const escapedOutputPath = options.outputPath.replace(/"/g, '\\"');
+
+    const command = `ffmpeg -i "${escapedVideoPath}" -ss ${options.startTime} -t ${duration} -c copy -y "${escapedOutputPath}"`;
+
+    try {
+      await execAsync(command, { 
+        timeout: 300000,
+        maxBuffer: 10 * 1024 * 1024
+      });
+
+      if (shouldCleanupVideo && fs.existsSync(videoPath)) {
+        fs.unlinkSync(videoPath);
+      }
+
+      return { outputPath: options.outputPath, success: true };
+    } catch (error) {
+      if (shouldCleanupVideo && fs.existsSync(videoPath)) {
+        fs.unlinkSync(videoPath);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Extract audio from video
+   * @private
+   */
+  async #extractAudio(
+    videoSource: string | Buffer,
+    options: { outputPath: string; format?: 'mp3' | 'wav' | 'aac' | 'ogg'; bitrate?: number }
+  ): Promise<{ outputPath: string; success: boolean }> {
+    const frameDir = path.join(process.cwd(), '.temp-frames');
+    if (!fs.existsSync(frameDir)) {
+      fs.mkdirSync(frameDir, { recursive: true });
+    }
+
+    let videoPath: string;
+    let shouldCleanupVideo = false;
+    const timestamp = Date.now();
+
+    if (Buffer.isBuffer(videoSource)) {
+      videoPath = path.join(frameDir, `temp-video-${timestamp}.mp4`);
+      fs.writeFileSync(videoPath, videoSource);
+      shouldCleanupVideo = true;
+    } else {
+      let resolvedPath = videoSource;
+      if (!/^https?:\/\//i.test(resolvedPath)) {
+        resolvedPath = path.join(process.cwd(), resolvedPath);
+      }
+      if (!fs.existsSync(resolvedPath)) {
+        throw new Error(`Video file not found: ${videoSource}`);
+      }
+      videoPath = resolvedPath;
+    }
+
+    // Check if video has audio stream
+    const escapedVideoPath = videoPath.replace(/"/g, '\\"');
+    try {
+      const { stdout } = await execAsync(
+        `ffprobe -v error -select_streams a:0 -show_entries stream=codec_type -of default=noprint_wrappers=1:nokey=1 "${escapedVideoPath}"`,
+        { timeout: 10000, maxBuffer: 1024 * 1024 }
+      );
+      const hasAudio = stdout.toString().trim() === 'audio';
+      if (!hasAudio) {
+        throw new Error('Video does not contain an audio stream. Cannot extract audio.');
+      }
+    } catch (error) {
+      if (error instanceof Error && error.message.includes('Video does not contain')) {
+        throw error;
+      }
+      // If ffprobe fails, assume no audio
+      throw new Error('Video does not contain an audio stream. Cannot extract audio.');
+    }
+
+    const format = options.format || 'mp3';
+    const bitrate = options.bitrate || 128;
+    const escapedOutputPath = options.outputPath.replace(/"/g, '\\"');
+
+    const command = `ffmpeg -i "${escapedVideoPath}" -vn -acodec ${format === 'mp3' ? 'libmp3lame' : format === 'wav' ? 'pcm_s16le' : format === 'aac' ? 'aac' : 'libvorbis'} -ab ${bitrate}k -y "${escapedOutputPath}"`;
+
+    try {
+      await execAsync(command, { 
+        timeout: 300000,
+        maxBuffer: 10 * 1024 * 1024
+      });
+
+      if (shouldCleanupVideo && fs.existsSync(videoPath)) {
+        fs.unlinkSync(videoPath);
+      }
+
+      return { outputPath: options.outputPath, success: true };
+    } catch (error) {
+      if (shouldCleanupVideo && fs.existsSync(videoPath)) {
+        fs.unlinkSync(videoPath);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Add watermark to video
+   * @private
+   */
+  async #addWatermarkToVideo(
+    videoSource: string | Buffer,
+    options: {
+      watermarkPath: string;
+      position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'center';
+      opacity?: number;
+      size?: { width: number; height: number };
+      outputPath: string;
+    }
+  ): Promise<{ outputPath: string; success: boolean }> {
+    const frameDir = path.join(process.cwd(), '.temp-frames');
+    if (!fs.existsSync(frameDir)) {
+      fs.mkdirSync(frameDir, { recursive: true });
+    }
+
+    let videoPath: string;
+    let shouldCleanupVideo = false;
+    const timestamp = Date.now();
+
+    if (Buffer.isBuffer(videoSource)) {
+      videoPath = path.join(frameDir, `temp-video-${timestamp}.mp4`);
+      fs.writeFileSync(videoPath, videoSource);
+      shouldCleanupVideo = true;
+    } else {
+      let resolvedPath = videoSource;
+      if (!/^https?:\/\//i.test(resolvedPath)) {
+        resolvedPath = path.join(process.cwd(), resolvedPath);
+      }
+      if (!fs.existsSync(resolvedPath)) {
+        throw new Error(`Video file not found: ${videoSource}`);
+      }
+      videoPath = resolvedPath;
+    }
+
+    let watermarkPath = options.watermarkPath;
+    if (!/^https?:\/\//i.test(watermarkPath)) {
+      watermarkPath = path.join(process.cwd(), watermarkPath);
+    }
+    if (!fs.existsSync(watermarkPath)) {
+      throw new Error(`Watermark file not found: ${options.watermarkPath}`);
+    }
+
+    const position = options.position || 'bottom-right';
+    const opacity = options.opacity || 0.5;
+    const size = options.size ? `scale=${options.size.width}:${options.size.height}` : '';
+
+    const positionMap: Record<string, string> = {
+      'top-left': '10:10',
+      'top-right': 'W-w-10:10',
+      'bottom-left': '10:H-h-10',
+      'bottom-right': 'W-w-10:H-h-10',
+      'center': '(W-w)/2:(H-h)/2'
+    };
+
+    const overlay = positionMap[position];
+    const escapedVideoPath = videoPath.replace(/"/g, '\\"');
+    const escapedWatermarkPath = watermarkPath.replace(/"/g, '\\"');
+    const escapedOutputPath = options.outputPath.replace(/"/g, '\\"');
+
+    const filter = `[1:v]${size ? size + ',' : ''}format=rgba,colorchannelmixer=aa=${opacity}[wm];[0:v][wm]overlay=${overlay}`;
+    const command = `ffmpeg -i "${escapedVideoPath}" -i "${escapedWatermarkPath}" -filter_complex "${filter}" -y "${escapedOutputPath}"`;
+
+    try {
+      await execAsync(command, { 
+        timeout: 300000,
+        maxBuffer: 10 * 1024 * 1024
+      });
+
+      if (shouldCleanupVideo && fs.existsSync(videoPath)) {
+        fs.unlinkSync(videoPath);
+      }
+
+      return { outputPath: options.outputPath, success: true };
+    } catch (error) {
+      if (shouldCleanupVideo && fs.existsSync(videoPath)) {
+        fs.unlinkSync(videoPath);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Change video speed
+   * @private
+   */
+  async #changeVideoSpeed(
+    videoSource: string | Buffer,
+    options: { speed: number; outputPath: string }
+  ): Promise<{ outputPath: string; success: boolean }> {
+    const frameDir = path.join(process.cwd(), '.temp-frames');
+    if (!fs.existsSync(frameDir)) {
+      fs.mkdirSync(frameDir, { recursive: true });
+    }
+
+    let videoPath: string;
+    let shouldCleanupVideo = false;
+    const timestamp = Date.now();
+
+    if (Buffer.isBuffer(videoSource)) {
+      videoPath = path.join(frameDir, `temp-video-${timestamp}.mp4`);
+      fs.writeFileSync(videoPath, videoSource);
+      shouldCleanupVideo = true;
+    } else {
+      let resolvedPath = videoSource;
+      if (!/^https?:\/\//i.test(resolvedPath)) {
+        resolvedPath = path.join(process.cwd(), resolvedPath);
+      }
+      if (!fs.existsSync(resolvedPath)) {
+        throw new Error(`Video file not found: ${videoSource}`);
+      }
+      videoPath = resolvedPath;
+    }
+
+    // Check if video has audio stream
+    const escapedVideoPath = videoPath.replace(/"/g, '\\"');
+    let hasAudio = false;
+    try {
+      const { stdout } = await execAsync(
+        `ffprobe -v error -select_streams a:0 -show_entries stream=codec_type -of default=noprint_wrappers=1:nokey=1 "${escapedVideoPath}"`,
+        { timeout: 10000, maxBuffer: 1024 * 1024 }
+      );
+      hasAudio = stdout.toString().trim() === 'audio';
+    } catch {
+      hasAudio = false;
+    }
+
+    const escapedOutputPath = options.outputPath.replace(/"/g, '\\"');
+    let command: string;
+
+    if (hasAudio) {
+      // Video has audio - process both video and audio
+      // For speeds > 2.0, we need to chain atempo filters (atempo max is 2.0)
+      if (options.speed > 2.0) {
+        const atempoCount = Math.ceil(Math.log2(options.speed));
+        const atempoValue = Math.pow(2, Math.log2(options.speed) / atempoCount);
+        const atempoFilters = Array(atempoCount).fill(atempoValue).map(v => `atempo=${v}`).join(',');
+        command = `ffmpeg -i "${escapedVideoPath}" -filter_complex "[0:v]setpts=${1/options.speed}*PTS[v];[0:a]${atempoFilters}[a]" -map "[v]" -map "[a]" -y "${escapedOutputPath}"`;
+      } else if (options.speed < 0.5) {
+        // For speeds < 0.5, we need to chain atempo filters
+        const atempoCount = Math.ceil(Math.log2(1 / options.speed));
+        const atempoValue = Math.pow(0.5, Math.log2(1 / options.speed) / atempoCount);
+        const atempoFilters = Array(atempoCount).fill(atempoValue).map(v => `atempo=${v}`).join(',');
+        command = `ffmpeg -i "${escapedVideoPath}" -filter_complex "[0:v]setpts=${1/options.speed}*PTS[v];[0:a]${atempoFilters}[a]" -map "[v]" -map "[a]" -y "${escapedOutputPath}"`;
+      } else {
+        // Normal speed range (0.5 to 2.0)
+        command = `ffmpeg -i "${escapedVideoPath}" -filter_complex "[0:v]setpts=${1/options.speed}*PTS[v];[0:a]atempo=${options.speed}[a]" -map "[v]" -map "[a]" -y "${escapedOutputPath}"`;
+      }
+    } else {
+      // No audio - only process video
+      command = `ffmpeg -i "${escapedVideoPath}" -filter_complex "[0:v]setpts=${1/options.speed}*PTS[v]" -map "[v]" -y "${escapedOutputPath}"`;
+    }
+
+    try {
+      await execAsync(command, { 
+        timeout: 300000,
+        maxBuffer: 10 * 1024 * 1024
+      });
+
+      if (shouldCleanupVideo && fs.existsSync(videoPath)) {
+        fs.unlinkSync(videoPath);
+      }
+
+      return { outputPath: options.outputPath, success: true };
+    } catch (error) {
+      if (shouldCleanupVideo && fs.existsSync(videoPath)) {
+        fs.unlinkSync(videoPath);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Generate video preview (multiple frames)
+   * @private
+   */
+  async #generateVideoPreview(
+    videoSource: string | Buffer,
+    options: {
+      count?: number;
+      outputDirectory?: string;
+      outputFormat?: 'jpg' | 'png';
+      quality?: number;
+    },
+    videoInfo: any
+  ): Promise<Array<{ source: string; frameNumber: number; time: number }>> {
+    const count = options.count || 10;
+    const outputDir = options.outputDirectory || path.join(process.cwd(), 'video-preview');
+    const outputFormat = options.outputFormat || 'png';
+    const quality = options.quality || 2;
+
+    if (!fs.existsSync(outputDir)) {
+      fs.mkdirSync(outputDir, { recursive: true });
+    }
+
+    if (!videoInfo) {
+      videoInfo = await this.getVideoInfo(videoSource, true);
+    }
+
+    const duration = videoInfo.duration;
+    const interval = duration / (count + 1);
+
+    const frames: Array<{ source: string; frameNumber: number; time: number }> = [];
+
+    for (let i = 1; i <= count; i++) {
+      const time = interval * i;
+      const frameBuffer = await this.#extractVideoFrame(videoSource, 0, time, outputFormat, quality);
+      
+      if (frameBuffer) {
+        const framePath = path.join(outputDir, `preview-${String(i).padStart(3, '0')}.${outputFormat}`);
+        fs.writeFileSync(framePath, frameBuffer);
+        frames.push({
+          source: framePath,
+          frameNumber: i,
+          time: time
+        });
+      }
+    }
+
+    return frames;
+  }
+
+  /**
+   * Apply video effects/filters
+   * @private
+   */
+  async #applyVideoEffects(
+    videoSource: string | Buffer,
+    options: {
+      filters: Array<{
+        type: 'blur' | 'brightness' | 'contrast' | 'saturation' | 'grayscale' | 'sepia' | 'invert' | 'sharpen' | 'noise';
+        intensity?: number;
+        value?: number;
+      }>;
+      outputPath: string;
+    }
+  ): Promise<{ outputPath: string; success: boolean }> {
+    const frameDir = path.join(process.cwd(), '.temp-frames');
+    if (!fs.existsSync(frameDir)) {
+      fs.mkdirSync(frameDir, { recursive: true });
+    }
+
+    let videoPath: string;
+    let shouldCleanupVideo = false;
+    const timestamp = Date.now();
+
+    if (Buffer.isBuffer(videoSource)) {
+      videoPath = path.join(frameDir, `temp-video-${timestamp}.mp4`);
+      fs.writeFileSync(videoPath, videoSource);
+      shouldCleanupVideo = true;
+    } else {
+      let resolvedPath = videoSource;
+      if (!/^https?:\/\//i.test(resolvedPath)) {
+        resolvedPath = path.join(process.cwd(), resolvedPath);
+      }
+      if (!fs.existsSync(resolvedPath)) {
+        throw new Error(`Video file not found: ${videoSource}`);
+      }
+      videoPath = resolvedPath;
+    }
+
+    // Build filter chain
+    const filters: string[] = [];
+    for (const filter of options.filters) {
+      switch (filter.type) {
+        case 'blur':
+          filters.push(`boxblur=${filter.intensity || 5}`);
+          break;
+        case 'brightness':
+          filters.push(`eq=brightness=${((filter.value || 0) / 100).toFixed(2)}`);
+          break;
+        case 'contrast':
+          filters.push(`eq=contrast=${1 + ((filter.value || 0) / 100)}`);
+          break;
+        case 'saturation':
+          filters.push(`eq=saturation=${1 + ((filter.value || 0) / 100)}`);
+          break;
+        case 'grayscale':
+          filters.push('hue=s=0');
+          break;
+        case 'sepia':
+          filters.push('colorchannelmixer=.393:.769:.189:0:.349:.686:.168:0:.272:.534:.131');
+          break;
+        case 'invert':
+          filters.push('negate');
+          break;
+        case 'sharpen':
+          filters.push(`unsharp=5:5:${filter.intensity || 1.0}:5:5:0.0`);
+          break;
+        case 'noise':
+          filters.push(`noise=alls=${filter.intensity || 20}:allf=t+u`);
+          break;
+      }
+    }
+
+    const filterChain = filters.length > 0 ? `-vf "${filters.join(',')}"` : '';
+    const escapedVideoPath = videoPath.replace(/"/g, '\\"');
+    const escapedOutputPath = options.outputPath.replace(/"/g, '\\"');
+
+    const command = `ffmpeg -i "${escapedVideoPath}" ${filterChain} -y "${escapedOutputPath}"`;
+
+    try {
+      await execAsync(command, { timeout: 300000, maxBuffer: 10 * 1024 * 1024 });
+      if (shouldCleanupVideo && fs.existsSync(videoPath)) {
+        fs.unlinkSync(videoPath);
+      }
+      return { outputPath: options.outputPath, success: true };
+    } catch (error) {
+      if (shouldCleanupVideo && fs.existsSync(videoPath)) {
+        fs.unlinkSync(videoPath);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Merge/Concatenate videos
+   * @private
+   */
+  async #mergeVideos(
+    options: {
+      videos: Array<string | Buffer>;
+      outputPath: string;
+      mode?: 'sequential' | 'side-by-side' | 'grid';
+      grid?: { cols: number; rows: number };
+    }
+  ): Promise<{ outputPath: string; success: boolean }> {
+    const frameDir = path.join(process.cwd(), '.temp-frames');
+    if (!fs.existsSync(frameDir)) {
+      fs.mkdirSync(frameDir, { recursive: true });
+    }
+
+    const timestamp = Date.now();
+    const videoPaths: string[] = [];
+    const shouldCleanup: boolean[] = [];
+
+    // Prepare all video files
+    for (let i = 0; i < options.videos.length; i++) {
+      const video = options.videos[i];
+      if (Buffer.isBuffer(video)) {
+        const tempPath = path.join(frameDir, `temp-video-${timestamp}-${i}.mp4`);
+        fs.writeFileSync(tempPath, video);
+        videoPaths.push(tempPath);
+        shouldCleanup.push(true);
+      } else {
+        let resolvedPath = video;
+        if (!/^https?:\/\//i.test(resolvedPath)) {
+          resolvedPath = path.join(process.cwd(), resolvedPath);
+        }
+        if (!fs.existsSync(resolvedPath)) {
+          throw new Error(`Video file not found: ${video}`);
+        }
+        videoPaths.push(resolvedPath);
+        shouldCleanup.push(false);
+      }
+    }
+
+    const mode = options.mode || 'sequential';
+    const escapedOutputPath = options.outputPath.replace(/"/g, '\\"');
+
+    let command: string;
+
+    if (mode === 'sequential') {
+      // Create concat file
+      const concatFile = path.join(frameDir, `concat-${timestamp}.txt`);
+      const concatContent = videoPaths.map(vp => `file '${vp.replace(/'/g, "\\'")}'`).join('\n');
+      fs.writeFileSync(concatFile, concatContent);
+
+      command = `ffmpeg -f concat -safe 0 -i "${concatFile.replace(/"/g, '\\"')}" -c copy -y "${escapedOutputPath}"`;
+    } else if (mode === 'side-by-side') {
+      const escapedPaths = videoPaths.map(vp => vp.replace(/"/g, '\\"'));
+      command = `ffmpeg -i "${escapedPaths[0]}" -i "${escapedPaths[1] || escapedPaths[0]}" -filter_complex "[0:v][1:v]hstack=inputs=2[v]" -map "[v]" -y "${escapedOutputPath}"`;
+    } else if (mode === 'grid') {
+      const grid = options.grid || { cols: 2, rows: 2 };
+      const escapedPaths = videoPaths.map(vp => vp.replace(/"/g, '\\"'));
+      // Simplified grid - would need more complex filter for full grid
+      command = `ffmpeg -i "${escapedPaths[0]}" -i "${escapedPaths[1] || escapedPaths[0]}" -filter_complex "[0:v][1:v]hstack=inputs=2[v]" -map "[v]" -y "${escapedOutputPath}"`;
+    } else {
+      throw new Error(`Unknown merge mode: ${mode}`);
+    }
+
+    try {
+      await execAsync(command, { timeout: 600000, maxBuffer: 20 * 1024 * 1024 });
+      
+      // Cleanup
+      for (let i = 0; i < videoPaths.length; i++) {
+        if (shouldCleanup[i] && fs.existsSync(videoPaths[i])) {
+          fs.unlinkSync(videoPaths[i]);
+        }
+      }
+      
+      return { outputPath: options.outputPath, success: true };
+    } catch (error) {
+      // Cleanup on error
+      for (let i = 0; i < videoPaths.length; i++) {
+        if (shouldCleanup[i] && fs.existsSync(videoPaths[i])) {
+          fs.unlinkSync(videoPaths[i]);
+        }
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Rotate/Flip video
+   * @private
+   */
+  async #rotateVideo(
+    videoSource: string | Buffer,
+    options: { angle?: 90 | 180 | 270; flip?: 'horizontal' | 'vertical' | 'both'; outputPath: string }
+  ): Promise<{ outputPath: string; success: boolean }> {
+    const frameDir = path.join(process.cwd(), '.temp-frames');
+    if (!fs.existsSync(frameDir)) {
+      fs.mkdirSync(frameDir, { recursive: true });
+    }
+
+    let videoPath: string;
+    let shouldCleanupVideo = false;
+    const timestamp = Date.now();
+
+    if (Buffer.isBuffer(videoSource)) {
+      videoPath = path.join(frameDir, `temp-video-${timestamp}.mp4`);
+      fs.writeFileSync(videoPath, videoSource);
+      shouldCleanupVideo = true;
+    } else {
+      let resolvedPath = videoSource;
+      if (!/^https?:\/\//i.test(resolvedPath)) {
+        resolvedPath = path.join(process.cwd(), resolvedPath);
+      }
+      if (!fs.existsSync(resolvedPath)) {
+        throw new Error(`Video file not found: ${videoSource}`);
+      }
+      videoPath = resolvedPath;
+    }
+
+    const filters: string[] = [];
+    
+    if (options.angle) {
+      const rotationMap: Record<number, string> = {
+        90: 'transpose=1',
+        180: 'transpose=1,transpose=1',
+        270: 'transpose=2'
+      };
+      filters.push(rotationMap[options.angle]);
+    }
+    
+    if (options.flip) {
+      if (options.flip === 'horizontal') {
+        filters.push('hflip');
+      } else if (options.flip === 'vertical') {
+        filters.push('vflip');
+      } else if (options.flip === 'both') {
+        filters.push('hflip', 'vflip');
+      }
+    }
+
+    const filterChain = filters.length > 0 ? `-vf "${filters.join(',')}"` : '';
+    const escapedVideoPath = videoPath.replace(/"/g, '\\"');
+    const escapedOutputPath = options.outputPath.replace(/"/g, '\\"');
+
+    const command = `ffmpeg -i "${escapedVideoPath}" ${filterChain} -y "${escapedOutputPath}"`;
+
+    try {
+      await execAsync(command, { timeout: 300000, maxBuffer: 10 * 1024 * 1024 });
+      if (shouldCleanupVideo && fs.existsSync(videoPath)) {
+        fs.unlinkSync(videoPath);
+      }
+      return { outputPath: options.outputPath, success: true };
+    } catch (error) {
+      if (shouldCleanupVideo && fs.existsSync(videoPath)) {
+        fs.unlinkSync(videoPath);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Crop video
+   * @private
+   */
+  async #cropVideo(
+    videoSource: string | Buffer,
+    options: { x: number; y: number; width: number; height: number; outputPath: string }
+  ): Promise<{ outputPath: string; success: boolean }> {
+    const frameDir = path.join(process.cwd(), '.temp-frames');
+    if (!fs.existsSync(frameDir)) {
+      fs.mkdirSync(frameDir, { recursive: true });
+    }
+
+    let videoPath: string;
+    let shouldCleanupVideo = false;
+    const timestamp = Date.now();
+
+    if (Buffer.isBuffer(videoSource)) {
+      videoPath = path.join(frameDir, `temp-video-${timestamp}.mp4`);
+      fs.writeFileSync(videoPath, videoSource);
+      shouldCleanupVideo = true;
+    } else {
+      let resolvedPath = videoSource;
+      if (!/^https?:\/\//i.test(resolvedPath)) {
+        resolvedPath = path.join(process.cwd(), resolvedPath);
+      }
+      if (!fs.existsSync(resolvedPath)) {
+        throw new Error(`Video file not found: ${videoSource}`);
+      }
+      videoPath = resolvedPath;
+    }
+
+    const escapedVideoPath = videoPath.replace(/"/g, '\\"');
+    const escapedOutputPath = options.outputPath.replace(/"/g, '\\"');
+
+    const command = `ffmpeg -i "${escapedVideoPath}" -vf "crop=${options.width}:${options.height}:${options.x}:${options.y}" -y "${escapedOutputPath}"`;
+
+    try {
+      await execAsync(command, { timeout: 300000, maxBuffer: 10 * 1024 * 1024 });
+      if (shouldCleanupVideo && fs.existsSync(videoPath)) {
+        fs.unlinkSync(videoPath);
+      }
+      return { outputPath: options.outputPath, success: true };
+    } catch (error) {
+      if (shouldCleanupVideo && fs.existsSync(videoPath)) {
+        fs.unlinkSync(videoPath);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Compress/Optimize video
+   * @private
+   */
+  async #compressVideo(
+    videoSource: string | Buffer,
+    options: { outputPath: string; quality?: 'low' | 'medium' | 'high' | 'ultra'; targetSize?: number; maxBitrate?: number }
+  ): Promise<{ outputPath: string; success: boolean; originalSize?: number; compressedSize?: number }> {
+    const frameDir = path.join(process.cwd(), '.temp-frames');
+    if (!fs.existsSync(frameDir)) {
+      fs.mkdirSync(frameDir, { recursive: true });
+    }
+
+    let videoPath: string;
+    let shouldCleanupVideo = false;
+    const timestamp = Date.now();
+    let originalSize = 0;
+
+    if (Buffer.isBuffer(videoSource)) {
+      videoPath = path.join(frameDir, `temp-video-${timestamp}.mp4`);
+      fs.writeFileSync(videoPath, videoSource);
+      shouldCleanupVideo = true;
+      originalSize = videoSource.length;
+    } else {
+      let resolvedPath = videoSource;
+      if (!/^https?:\/\//i.test(resolvedPath)) {
+        resolvedPath = path.join(process.cwd(), resolvedPath);
+      }
+      if (!fs.existsSync(resolvedPath)) {
+        throw new Error(`Video file not found: ${videoSource}`);
+      }
+      videoPath = resolvedPath;
+      originalSize = fs.statSync(resolvedPath).size;
+    }
+
+    const qualityPresets: Record<string, string> = {
+      low: '-crf 32 -preset fast',
+      medium: '-crf 28 -preset medium',
+      high: '-crf 23 -preset slow',
+      ultra: '-crf 18 -preset veryslow'
+    };
+
+    let qualityFlag = qualityPresets[options.quality || 'medium'];
+    
+    if (options.maxBitrate) {
+      qualityFlag = `-b:v ${options.maxBitrate}k -maxrate ${options.maxBitrate}k -bufsize ${options.maxBitrate * 2}k`;
+    }
+
+    const escapedVideoPath = videoPath.replace(/"/g, '\\"');
+    const escapedOutputPath = options.outputPath.replace(/"/g, '\\"');
+
+    const command = `ffmpeg -i "${escapedVideoPath}" ${qualityFlag} -y "${escapedOutputPath}"`;
+
+    try {
+      await execAsync(command, { timeout: 600000, maxBuffer: 20 * 1024 * 1024 });
+      
+      const compressedSize = fs.existsSync(options.outputPath) ? fs.statSync(options.outputPath).size : 0;
+      
+      if (shouldCleanupVideo && fs.existsSync(videoPath)) {
+        fs.unlinkSync(videoPath);
+      }
+      
+      return {
+        outputPath: options.outputPath,
+        success: true,
+        originalSize,
+        compressedSize
+      };
+    } catch (error) {
+      if (shouldCleanupVideo && fs.existsSync(videoPath)) {
+        fs.unlinkSync(videoPath);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Add text overlay to video
+   * @private
+   */
+  async #addTextToVideo(
+    videoSource: string | Buffer,
+    options: {
+      text: string;
+      position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'center' | 'top-center' | 'bottom-center';
+      fontSize?: number;
+      fontColor?: string;
+      backgroundColor?: string;
+      startTime?: number;
+      endTime?: number;
+      outputPath: string;
+    }
+  ): Promise<{ outputPath: string; success: boolean }> {
+    const frameDir = path.join(process.cwd(), '.temp-frames');
+    if (!fs.existsSync(frameDir)) {
+      fs.mkdirSync(frameDir, { recursive: true });
+    }
+
+    let videoPath: string;
+    let shouldCleanupVideo = false;
+    const timestamp = Date.now();
+
+    if (Buffer.isBuffer(videoSource)) {
+      videoPath = path.join(frameDir, `temp-video-${timestamp}.mp4`);
+      fs.writeFileSync(videoPath, videoSource);
+      shouldCleanupVideo = true;
+    } else {
+      let resolvedPath = videoSource;
+      if (!/^https?:\/\//i.test(resolvedPath)) {
+        resolvedPath = path.join(process.cwd(), resolvedPath);
+      }
+      if (!fs.existsSync(resolvedPath)) {
+        throw new Error(`Video file not found: ${videoSource}`);
+      }
+      videoPath = resolvedPath;
+    }
+
+    const position = options.position || 'bottom-center';
+    const fontSize = options.fontSize || 24;
+    const fontColor = options.fontColor || 'white';
+    const bgColor = options.backgroundColor || 'black@0.5';
+    
+    const positionMap: Record<string, string> = {
+      'top-left': `x=10:y=10`,
+      'top-center': `x=(w-text_w)/2:y=10`,
+      'top-right': `x=w-text_w-10:y=10`,
+      'center': `x=(w-text_w)/2:y=(h-text_h)/2`,
+      'bottom-left': `x=10:y=h-text_h-10`,
+      'bottom-center': `x=(w-text_w)/2:y=h-text_h-10`,
+      'bottom-right': `x=w-text_w-10:y=h-text_h-10`
+    };
+
+    const pos = positionMap[position];
+    const textEscaped = options.text.replace(/:/g, '\\:').replace(/'/g, "\\'");
+    const timeFilter = options.startTime !== undefined && options.endTime !== undefined
+      ? `:enable='between(t,${options.startTime},${options.endTime})'`
+      : '';
+
+    const escapedVideoPath = videoPath.replace(/"/g, '\\"');
+    const escapedOutputPath = options.outputPath.replace(/"/g, '\\"');
+
+    const command = `ffmpeg -i "${escapedVideoPath}" -vf "drawtext=text='${textEscaped}':fontsize=${fontSize}:fontcolor=${fontColor}:box=1:boxcolor=${bgColor}:${pos}${timeFilter}" -y "${escapedOutputPath}"`;
+
+    try {
+      await execAsync(command, { timeout: 300000, maxBuffer: 10 * 1024 * 1024 });
+      if (shouldCleanupVideo && fs.existsSync(videoPath)) {
+        fs.unlinkSync(videoPath);
+      }
+      return { outputPath: options.outputPath, success: true };
+    } catch (error) {
+      if (shouldCleanupVideo && fs.existsSync(videoPath)) {
+        fs.unlinkSync(videoPath);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Add fade effects to video
+   * @private
+   */
+  async #addFadeToVideo(
+    videoSource: string | Buffer,
+    options: { fadeIn?: number; fadeOut?: number; outputPath: string }
+  ): Promise<{ outputPath: string; success: boolean }> {
+    const frameDir = path.join(process.cwd(), '.temp-frames');
+    if (!fs.existsSync(frameDir)) {
+      fs.mkdirSync(frameDir, { recursive: true });
+    }
+
+    let videoPath: string;
+    let shouldCleanupVideo = false;
+    const timestamp = Date.now();
+
+    if (Buffer.isBuffer(videoSource)) {
+      videoPath = path.join(frameDir, `temp-video-${timestamp}.mp4`);
+      fs.writeFileSync(videoPath, videoSource);
+      shouldCleanupVideo = true;
+    } else {
+      let resolvedPath = videoSource;
+      if (!/^https?:\/\//i.test(resolvedPath)) {
+        resolvedPath = path.join(process.cwd(), resolvedPath);
+      }
+      if (!fs.existsSync(resolvedPath)) {
+        throw new Error(`Video file not found: ${videoSource}`);
+      }
+      videoPath = resolvedPath;
+    }
+
+    const videoInfo = await this.getVideoInfo(videoPath, true);
+    const duration = videoInfo?.duration || 0;
+
+    const filters: string[] = [];
+    
+    if (options.fadeIn) {
+      filters.push(`fade=t=in:st=0:d=${options.fadeIn}`);
+    }
+    
+    if (options.fadeOut && duration > options.fadeOut) {
+      filters.push(`fade=t=out:st=${duration - options.fadeOut}:d=${options.fadeOut}`);
+    }
+
+    const filterChain = filters.length > 0 ? `-vf "${filters.join(',')}"` : '';
+    const escapedVideoPath = videoPath.replace(/"/g, '\\"');
+    const escapedOutputPath = options.outputPath.replace(/"/g, '\\"');
+
+    const command = `ffmpeg -i "${escapedVideoPath}" ${filterChain} -y "${escapedOutputPath}"`;
+
+    try {
+      await execAsync(command, { timeout: 300000, maxBuffer: 10 * 1024 * 1024 });
+      if (shouldCleanupVideo && fs.existsSync(videoPath)) {
+        fs.unlinkSync(videoPath);
+      }
+      return { outputPath: options.outputPath, success: true };
+    } catch (error) {
+      if (shouldCleanupVideo && fs.existsSync(videoPath)) {
+        fs.unlinkSync(videoPath);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Reverse video playback
+   * @private
+   */
+  async #reverseVideo(
+    videoSource: string | Buffer,
+    options: { outputPath: string }
+  ): Promise<{ outputPath: string; success: boolean }> {
+    const frameDir = path.join(process.cwd(), '.temp-frames');
+    if (!fs.existsSync(frameDir)) {
+      fs.mkdirSync(frameDir, { recursive: true });
+    }
+
+    let videoPath: string;
+    let shouldCleanupVideo = false;
+    const timestamp = Date.now();
+
+    if (Buffer.isBuffer(videoSource)) {
+      videoPath = path.join(frameDir, `temp-video-${timestamp}.mp4`);
+      fs.writeFileSync(videoPath, videoSource);
+      shouldCleanupVideo = true;
+    } else {
+      let resolvedPath = videoSource;
+      if (!/^https?:\/\//i.test(resolvedPath)) {
+        resolvedPath = path.join(process.cwd(), resolvedPath);
+      }
+      if (!fs.existsSync(resolvedPath)) {
+        throw new Error(`Video file not found: ${videoSource}`);
+      }
+      videoPath = resolvedPath;
+    }
+
+    const escapedVideoPath = videoPath.replace(/"/g, '\\"');
+    const escapedOutputPath = options.outputPath.replace(/"/g, '\\"');
+
+    const command = `ffmpeg -i "${escapedVideoPath}" -vf reverse -af areverse -y "${escapedOutputPath}"`;
+
+    try {
+      await execAsync(command, { timeout: 600000, maxBuffer: 20 * 1024 * 1024 });
+      if (shouldCleanupVideo && fs.existsSync(videoPath)) {
+        fs.unlinkSync(videoPath);
+      }
+      return { outputPath: options.outputPath, success: true };
+    } catch (error) {
+      if (shouldCleanupVideo && fs.existsSync(videoPath)) {
+        fs.unlinkSync(videoPath);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Create seamless video loop
+   * @private
+   */
+  async #createVideoLoop(
+    videoSource: string | Buffer,
+    options: { outputPath: string; smooth?: boolean }
+  ): Promise<{ outputPath: string; success: boolean }> {
+    const frameDir = path.join(process.cwd(), '.temp-frames');
+    if (!fs.existsSync(frameDir)) {
+      fs.mkdirSync(frameDir, { recursive: true });
+    }
+
+    let videoPath: string;
+    let shouldCleanupVideo = false;
+    const timestamp = Date.now();
+
+    if (Buffer.isBuffer(videoSource)) {
+      videoPath = path.join(frameDir, `temp-video-${timestamp}.mp4`);
+      fs.writeFileSync(videoPath, videoSource);
+      shouldCleanupVideo = true;
+    } else {
+      let resolvedPath = videoSource;
+      if (!/^https?:\/\//i.test(resolvedPath)) {
+        resolvedPath = path.join(process.cwd(), resolvedPath);
+      }
+      if (!fs.existsSync(resolvedPath)) {
+        throw new Error(`Video file not found: ${videoSource}`);
+      }
+      videoPath = resolvedPath;
+    }
+
+    const escapedVideoPath = videoPath.replace(/"/g, '\\"');
+    const escapedOutputPath = options.outputPath.replace(/"/g, '\\"');
+
+    // Create loop by concatenating video with itself
+    const concatFile = path.join(frameDir, `loop-${timestamp}.txt`);
+    const concatContent = `file '${videoPath.replace(/'/g, "\\'")}'\nfile '${videoPath.replace(/'/g, "\\'")}'`;
+    fs.writeFileSync(concatFile, concatContent);
+
+    const command = `ffmpeg -f concat -safe 0 -i "${concatFile.replace(/"/g, '\\"')}" -c copy -y "${escapedOutputPath}"`;
+
+    try {
+      await execAsync(command, { timeout: 300000, maxBuffer: 10 * 1024 * 1024 });
+      
+      if (fs.existsSync(concatFile)) {
+        fs.unlinkSync(concatFile);
+      }
+      if (shouldCleanupVideo && fs.existsSync(videoPath)) {
+        fs.unlinkSync(videoPath);
+      }
+      
+      return { outputPath: options.outputPath, success: true };
+    } catch (error) {
+      if (fs.existsSync(concatFile)) {
+        fs.unlinkSync(concatFile);
+      }
+      if (shouldCleanupVideo && fs.existsSync(videoPath)) {
+        fs.unlinkSync(videoPath);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Batch process multiple videos
+   * @private
+   */
+  async #batchProcessVideos(
+    options: { videos: Array<{ source: string | Buffer; operations: any }>; outputDirectory: string }
+  ): Promise<Array<{ source: string; output: string; success: boolean }>> {
+    if (!fs.existsSync(options.outputDirectory)) {
+      fs.mkdirSync(options.outputDirectory, { recursive: true });
+    }
+
+    const results: Array<{ source: string; output: string; success: boolean }> = [];
+
+    for (let i = 0; i < options.videos.length; i++) {
+      const video = options.videos[i];
+      const outputPath = path.join(options.outputDirectory, `batch-${i + 1}.mp4`);
+      
+      try {
+        // Process each video with its operations
+        await this.createVideo({
+          source: video.source,
+          ...video.operations
+        });
+        
+        results.push({
+          source: typeof video.source === 'string' ? video.source : 'buffer',
+          output: outputPath,
+          success: true
+        });
+      } catch (error) {
+        results.push({
+          source: typeof video.source === 'string' ? video.source : 'buffer',
+          output: outputPath,
+          success: false
+        });
+      }
+    }
+
+    return results;
+  }
+
+  /**
+   * Detect scene changes in video
+   * @private
+   */
+  async #detectVideoScenes(
+    videoSource: string | Buffer,
+    options: { threshold?: number; outputPath?: string }
+  ): Promise<Array<{ time: number; scene: number }>> {
+    const frameDir = path.join(process.cwd(), '.temp-frames');
+    if (!fs.existsSync(frameDir)) {
+      fs.mkdirSync(frameDir, { recursive: true });
+    }
+
+    let videoPath: string;
+    let shouldCleanupVideo = false;
+    const timestamp = Date.now();
+
+    if (Buffer.isBuffer(videoSource)) {
+      videoPath = path.join(frameDir, `temp-video-${timestamp}.mp4`);
+      fs.writeFileSync(videoPath, videoSource);
+      shouldCleanupVideo = true;
+    } else {
+      let resolvedPath = videoSource;
+      if (!/^https?:\/\//i.test(resolvedPath)) {
+        resolvedPath = path.join(process.cwd(), resolvedPath);
+      }
+      if (!fs.existsSync(resolvedPath)) {
+        throw new Error(`Video file not found: ${videoSource}`);
+      }
+      videoPath = resolvedPath;
+    }
+
+    const threshold = options.threshold || 0.3;
+    const escapedVideoPath = videoPath.replace(/"/g, '\\"');
+    const sceneFile = path.join(frameDir, `scenes-${timestamp}.txt`);
+
+    // Use FFmpeg's scene detection
+    const command = `ffmpeg -i "${escapedVideoPath}" -vf "select='gt(scene,${threshold})',showinfo" -f null - 2>&1 | grep "pts_time" | awk '{print $6}' | sed 's/time=//'`;
+
+    try {
+      const { stdout } = await execAsync(command, { timeout: 300000, maxBuffer: 10 * 1024 * 1024 });
+      const times = stdout.toString().trim().split('\n').filter(t => t).map(parseFloat);
+      
+      const scenes = times.map((time, index) => ({ time, scene: index + 1 }));
+
+      if (options.outputPath && scenes.length > 0) {
+        fs.writeFileSync(options.outputPath, JSON.stringify(scenes, null, 2));
+      }
+
+      if (shouldCleanupVideo && fs.existsSync(videoPath)) {
+        fs.unlinkSync(videoPath);
+      }
+      if (fs.existsSync(sceneFile)) {
+        fs.unlinkSync(sceneFile);
+      }
+
+      return scenes;
+    } catch (error) {
+      if (shouldCleanupVideo && fs.existsSync(videoPath)) {
+        fs.unlinkSync(videoPath);
+      }
+      if (fs.existsSync(sceneFile)) {
+        fs.unlinkSync(sceneFile);
+      }
+      // Return empty array if detection fails
+      return [];
+    }
+  }
+
+  /**
+   * Stabilize video (reduce shake)
+   * @private
+   */
+  async #stabilizeVideo(
+    videoSource: string | Buffer,
+    options: { outputPath: string; smoothing?: number }
+  ): Promise<{ outputPath: string; success: boolean }> {
+    const frameDir = path.join(process.cwd(), '.temp-frames');
+    if (!fs.existsSync(frameDir)) {
+      fs.mkdirSync(frameDir, { recursive: true });
+    }
+
+    let videoPath: string;
+    let shouldCleanupVideo = false;
+    const timestamp = Date.now();
+
+    if (Buffer.isBuffer(videoSource)) {
+      videoPath = path.join(frameDir, `temp-video-${timestamp}.mp4`);
+      fs.writeFileSync(videoPath, videoSource);
+      shouldCleanupVideo = true;
+    } else {
+      let resolvedPath = videoSource;
+      if (!/^https?:\/\//i.test(resolvedPath)) {
+        resolvedPath = path.join(process.cwd(), resolvedPath);
+      }
+      if (!fs.existsSync(resolvedPath)) {
+        throw new Error(`Video file not found: ${videoSource}`);
+      }
+      videoPath = resolvedPath;
+    }
+
+    const smoothing = options.smoothing || 10;
+    const escapedVideoPath = videoPath.replace(/"/g, '\\"');
+    const escapedOutputPath = options.outputPath.replace(/"/g, '\\"');
+
+    // Two-pass stabilization
+    const transformsFile = path.join(frameDir, `transforms-${timestamp}.trf`);
+    
+    // Pass 1: Analyze
+    const analyzeCommand = `ffmpeg -i "${escapedVideoPath}" -vf vidstabdetect=shakiness=5:accuracy=15:result="${transformsFile.replace(/"/g, '\\"')}" -f null -`;
+    
+    // Pass 2: Transform
+    const transformCommand = `ffmpeg -i "${escapedVideoPath}" -vf vidstabtransform=smoothing=${smoothing}:input="${transformsFile.replace(/"/g, '\\"')}" -y "${escapedOutputPath}"`;
+
+    try {
+      await execAsync(analyzeCommand, { timeout: 600000, maxBuffer: 20 * 1024 * 1024 });
+      await execAsync(transformCommand, { timeout: 600000, maxBuffer: 20 * 1024 * 1024 });
+      
+      if (fs.existsSync(transformsFile)) {
+        fs.unlinkSync(transformsFile);
+      }
+      if (shouldCleanupVideo && fs.existsSync(videoPath)) {
+        fs.unlinkSync(videoPath);
+      }
+      
+      return { outputPath: options.outputPath, success: true };
+    } catch (error) {
+      // Fallback to simple deshake if vidstab is not available
+      const simpleCommand = `ffmpeg -i "${escapedVideoPath}" -vf "hqdn3d=4:3:6:4.5" -y "${escapedOutputPath}"`;
+      try {
+        await execAsync(simpleCommand, { timeout: 300000, maxBuffer: 10 * 1024 * 1024 });
+        if (shouldCleanupVideo && fs.existsSync(videoPath)) {
+          fs.unlinkSync(videoPath);
+        }
+        return { outputPath: options.outputPath, success: true };
+      } catch (fallbackError) {
+        if (shouldCleanupVideo && fs.existsSync(videoPath)) {
+          fs.unlinkSync(videoPath);
+        }
+        throw error;
+      }
+    }
+  }
+
+  /**
+   * Color correct video
+   * @private
+   */
+  async #colorCorrectVideo(
+    videoSource: string | Buffer,
+    options: {
+      brightness?: number;
+      contrast?: number;
+      saturation?: number;
+      hue?: number;
+      temperature?: number;
+      outputPath: string;
+    }
+  ): Promise<{ outputPath: string; success: boolean }> {
+    const frameDir = path.join(process.cwd(), '.temp-frames');
+    if (!fs.existsSync(frameDir)) {
+      fs.mkdirSync(frameDir, { recursive: true });
+    }
+
+    let videoPath: string;
+    let shouldCleanupVideo = false;
+    const timestamp = Date.now();
+
+    if (Buffer.isBuffer(videoSource)) {
+      videoPath = path.join(frameDir, `temp-video-${timestamp}.mp4`);
+      fs.writeFileSync(videoPath, videoSource);
+      shouldCleanupVideo = true;
+    } else {
+      let resolvedPath = videoSource;
+      if (!/^https?:\/\//i.test(resolvedPath)) {
+        resolvedPath = path.join(process.cwd(), resolvedPath);
+      }
+      if (!fs.existsSync(resolvedPath)) {
+        throw new Error(`Video file not found: ${videoSource}`);
+      }
+      videoPath = resolvedPath;
+    }
+
+    const filters: string[] = [];
+    
+    if (options.brightness !== undefined) {
+      filters.push(`eq=brightness=${(options.brightness / 100).toFixed(2)}`);
+    }
+    if (options.contrast !== undefined) {
+      filters.push(`eq=contrast=${1 + (options.contrast / 100)}`);
+    }
+    if (options.saturation !== undefined) {
+      filters.push(`eq=saturation=${1 + (options.saturation / 100)}`);
+    }
+    if (options.hue !== undefined) {
+      filters.push(`hue=h=${options.hue}`);
+    }
+    if (options.temperature !== undefined) {
+      // Temperature adjustment using colorbalance
+      const temp = options.temperature;
+      if (temp > 0) {
+        filters.push(`colorbalance=rs=${temp/100}:gs=-${temp/200}:bs=-${temp/100}`);
+      } else {
+        filters.push(`colorbalance=rs=${temp/100}:gs=${-temp/200}:bs=${-temp/100}`);
+      }
+    }
+
+    const filterChain = filters.length > 0 ? `-vf "${filters.join(',')}"` : '';
+    const escapedVideoPath = videoPath.replace(/"/g, '\\"');
+    const escapedOutputPath = options.outputPath.replace(/"/g, '\\"');
+
+    const command = `ffmpeg -i "${escapedVideoPath}" ${filterChain} -y "${escapedOutputPath}"`;
+
+    try {
+      await execAsync(command, { timeout: 300000, maxBuffer: 10 * 1024 * 1024 });
+      if (shouldCleanupVideo && fs.existsSync(videoPath)) {
+        fs.unlinkSync(videoPath);
+      }
+      return { outputPath: options.outputPath, success: true };
+    } catch (error) {
+      if (shouldCleanupVideo && fs.existsSync(videoPath)) {
+        fs.unlinkSync(videoPath);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Add picture-in-picture
+   * @private
+   */
+  async #addPictureInPicture(
+    videoSource: string | Buffer,
+    options: {
+      overlayVideo: string | Buffer;
+      position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'center';
+      size?: { width: number; height: number };
+      opacity?: number;
+      outputPath: string;
+    }
+  ): Promise<{ outputPath: string; success: boolean }> {
+    const frameDir = path.join(process.cwd(), '.temp-frames');
+    if (!fs.existsSync(frameDir)) {
+      fs.mkdirSync(frameDir, { recursive: true });
+    }
+
+    let videoPath: string;
+    let overlayPath: string;
+    let shouldCleanupVideo = false;
+    let shouldCleanupOverlay = false;
+    const timestamp = Date.now();
+
+    // Handle main video
+    if (Buffer.isBuffer(videoSource)) {
+      videoPath = path.join(frameDir, `temp-video-${timestamp}.mp4`);
+      fs.writeFileSync(videoPath, videoSource);
+      shouldCleanupVideo = true;
+    } else {
+      let resolvedPath = videoSource;
+      if (!/^https?:\/\//i.test(resolvedPath)) {
+        resolvedPath = path.join(process.cwd(), resolvedPath);
+      }
+      if (!fs.existsSync(resolvedPath)) {
+        throw new Error(`Video file not found: ${videoSource}`);
+      }
+      videoPath = resolvedPath;
+    }
+
+    // Handle overlay video
+    if (Buffer.isBuffer(options.overlayVideo)) {
+      overlayPath = path.join(frameDir, `temp-overlay-${timestamp}.mp4`);
+      fs.writeFileSync(overlayPath, options.overlayVideo);
+      shouldCleanupOverlay = true;
+    } else {
+      let resolvedPath = options.overlayVideo;
+      if (!/^https?:\/\//i.test(resolvedPath)) {
+        resolvedPath = path.join(process.cwd(), resolvedPath);
+      }
+      if (!fs.existsSync(resolvedPath)) {
+        throw new Error(`Overlay video file not found: ${options.overlayVideo}`);
+      }
+      overlayPath = resolvedPath;
+    }
+
+    const position = options.position || 'bottom-right';
+    const size = options.size || { width: 320, height: 180 };
+    const opacity = options.opacity || 1.0;
+
+    const positionMap: Record<string, string> = {
+      'top-left': '10:10',
+      'top-right': 'W-w-10:10',
+      'bottom-left': '10:H-h-10',
+      'bottom-right': 'W-w-10:H-h-10',
+      'center': '(W-w)/2:(H-h)/2'
+    };
+
+    const overlay = positionMap[position];
+    const escapedVideoPath = videoPath.replace(/"/g, '\\"');
+    const escapedOverlayPath = overlayPath.replace(/"/g, '\\"');
+    const escapedOutputPath = options.outputPath.replace(/"/g, '\\"');
+
+    const filter = `[1:v]scale=${size.width}:${size.height},format=rgba,colorchannelmixer=aa=${opacity}[overlay];[0:v][overlay]overlay=${overlay}`;
+    const command = `ffmpeg -i "${escapedVideoPath}" -i "${escapedOverlayPath}" -filter_complex "${filter}" -y "${escapedOutputPath}"`;
+
+    try {
+      await execAsync(command, { timeout: 300000, maxBuffer: 10 * 1024 * 1024 });
+      
+      if (shouldCleanupVideo && fs.existsSync(videoPath)) {
+        fs.unlinkSync(videoPath);
+      }
+      if (shouldCleanupOverlay && fs.existsSync(overlayPath)) {
+        fs.unlinkSync(overlayPath);
+      }
+      
+      return { outputPath: options.outputPath, success: true };
+    } catch (error) {
+      if (shouldCleanupVideo && fs.existsSync(videoPath)) {
+        fs.unlinkSync(videoPath);
+      }
+      if (shouldCleanupOverlay && fs.existsSync(overlayPath)) {
+        fs.unlinkSync(overlayPath);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Create split screen video
+   * @private
+   */
+  async #createSplitScreen(
+    options: {
+      videos: Array<string | Buffer>;
+      layout?: 'side-by-side' | 'top-bottom' | 'grid';
+      grid?: { cols: number; rows: number };
+      outputPath: string;
+    }
+  ): Promise<{ outputPath: string; success: boolean }> {
+    const frameDir = path.join(process.cwd(), '.temp-frames');
+    if (!fs.existsSync(frameDir)) {
+      fs.mkdirSync(frameDir, { recursive: true });
+    }
+
+    const timestamp = Date.now();
+    const videoPaths: string[] = [];
+    const shouldCleanup: boolean[] = [];
+
+    // Prepare all video files
+    for (let i = 0; i < options.videos.length; i++) {
+      const video = options.videos[i];
+      if (Buffer.isBuffer(video)) {
+        const tempPath = path.join(frameDir, `temp-video-${timestamp}-${i}.mp4`);
+        fs.writeFileSync(tempPath, video);
+        videoPaths.push(tempPath);
+        shouldCleanup.push(true);
+      } else {
+        let resolvedPath = video;
+        if (!/^https?:\/\//i.test(resolvedPath)) {
+          resolvedPath = path.join(process.cwd(), resolvedPath);
+        }
+        if (!fs.existsSync(resolvedPath)) {
+          throw new Error(`Video file not found: ${video}`);
+        }
+        videoPaths.push(resolvedPath);
+        shouldCleanup.push(false);
+      }
+    }
+
+    const layout = options.layout || 'side-by-side';
+    const escapedOutputPath = options.outputPath.replace(/"/g, '\\"');
+    const escapedPaths = videoPaths.map(vp => vp.replace(/"/g, '\\"'));
+
+    let command: string;
+
+    if (layout === 'side-by-side' && videoPaths.length >= 2) {
+      command = `ffmpeg -i "${escapedPaths[0]}" -i "${escapedPaths[1]}" -filter_complex "[0:v][1:v]hstack=inputs=2[v]" -map "[v]" -y "${escapedOutputPath}"`;
+    } else if (layout === 'top-bottom' && videoPaths.length >= 2) {
+      command = `ffmpeg -i "${escapedPaths[0]}" -i "${escapedPaths[1]}" -filter_complex "[0:v][1:v]vstack=inputs=2[v]" -map "[v]" -y "${escapedOutputPath}"`;
+    } else if (layout === 'grid' && videoPaths.length >= 4) {
+      const grid = options.grid || { cols: 2, rows: 2 };
+      // Simplified 2x2 grid
+      command = `ffmpeg -i "${escapedPaths[0]}" -i "${escapedPaths[1]}" -i "${escapedPaths[2]}" -i "${escapedPaths[3]}" -filter_complex "[0:v][1:v]hstack=inputs=2[top];[2:v][3:v]hstack=inputs=2[bottom];[top][bottom]vstack=inputs=2[v]" -map "[v]" -y "${escapedOutputPath}"`;
+    } else {
+      throw new Error(`Invalid layout or insufficient videos for ${layout}`);
+    }
+
+    try {
+      await execAsync(command, { timeout: 600000, maxBuffer: 20 * 1024 * 1024 });
+      
+      // Cleanup
+      for (let i = 0; i < videoPaths.length; i++) {
+        if (shouldCleanup[i] && fs.existsSync(videoPaths[i])) {
+          fs.unlinkSync(videoPaths[i]);
+        }
+      }
+      
+      return { outputPath: options.outputPath, success: true };
+    } catch (error) {
+      // Cleanup on error
+      for (let i = 0; i < videoPaths.length; i++) {
+        if (shouldCleanup[i] && fs.existsSync(videoPaths[i])) {
+          fs.unlinkSync(videoPaths[i]);
+        }
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Create time-lapse video
+   * @private
+   */
+  async #createTimeLapseVideo(
+    videoSource: string | Buffer,
+    options: { speed?: number; outputPath: string }
+  ): Promise<{ outputPath: string; success: boolean }> {
+    const speed = options.speed || 10;
+    // Time-lapse is essentially speeding up the video
+    return await this.#changeVideoSpeed(videoSource, { speed, outputPath: options.outputPath });
+  }
+
+  /**
+   * Mute video (remove audio)
+   * @private
+   */
+  async #muteVideo(
+    videoSource: string | Buffer,
+    options: { outputPath: string }
+  ): Promise<{ outputPath: string; success: boolean }> {
+    const frameDir = path.join(process.cwd(), '.temp-frames');
+    if (!fs.existsSync(frameDir)) {
+      fs.mkdirSync(frameDir, { recursive: true });
+    }
+
+    let videoPath: string;
+    let shouldCleanupVideo = false;
+    const timestamp = Date.now();
+
+    if (Buffer.isBuffer(videoSource)) {
+      videoPath = path.join(frameDir, `temp-video-${timestamp}.mp4`);
+      fs.writeFileSync(videoPath, videoSource);
+      shouldCleanupVideo = true;
+    } else {
+      let resolvedPath = videoSource;
+      if (!/^https?:\/\//i.test(resolvedPath)) {
+        resolvedPath = path.join(process.cwd(), resolvedPath);
+      }
+      if (!fs.existsSync(resolvedPath)) {
+        throw new Error(`Video file not found: ${videoSource}`);
+      }
+      videoPath = resolvedPath;
+    }
+
+    const escapedVideoPath = videoPath.replace(/"/g, '\\"');
+    const escapedOutputPath = options.outputPath.replace(/"/g, '\\"');
+
+    const command = `ffmpeg -i "${escapedVideoPath}" -c copy -an -y "${escapedOutputPath}"`;
+
+    try {
+      await execAsync(command, { timeout: 300000, maxBuffer: 10 * 1024 * 1024 });
+      if (shouldCleanupVideo && fs.existsSync(videoPath)) {
+        fs.unlinkSync(videoPath);
+      }
+      return { outputPath: options.outputPath, success: true };
+    } catch (error) {
+      if (shouldCleanupVideo && fs.existsSync(videoPath)) {
+        fs.unlinkSync(videoPath);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Adjust video volume
+   * @private
+   */
+  async #adjustVideoVolume(
+    videoSource: string | Buffer,
+    options: { volume: number; outputPath: string }
+  ): Promise<{ outputPath: string; success: boolean }> {
+    const frameDir = path.join(process.cwd(), '.temp-frames');
+    if (!fs.existsSync(frameDir)) {
+      fs.mkdirSync(frameDir, { recursive: true });
+    }
+
+    let videoPath: string;
+    let shouldCleanupVideo = false;
+    const timestamp = Date.now();
+
+    if (Buffer.isBuffer(videoSource)) {
+      videoPath = path.join(frameDir, `temp-video-${timestamp}.mp4`);
+      fs.writeFileSync(videoPath, videoSource);
+      shouldCleanupVideo = true;
+    } else {
+      let resolvedPath = videoSource;
+      if (!/^https?:\/\//i.test(resolvedPath)) {
+        resolvedPath = path.join(process.cwd(), resolvedPath);
+      }
+      if (!fs.existsSync(resolvedPath)) {
+        throw new Error(`Video file not found: ${videoSource}`);
+      }
+      videoPath = resolvedPath;
+    }
+
+    const volume = Math.max(0, Math.min(10, options.volume)); // Clamp between 0 and 10
+    const escapedVideoPath = videoPath.replace(/"/g, '\\"');
+    const escapedOutputPath = options.outputPath.replace(/"/g, '\\"');
+
+    const command = `ffmpeg -i "${escapedVideoPath}" -af "volume=${volume}" -y "${escapedOutputPath}"`;
+
+    try {
+      await execAsync(command, { timeout: 300000, maxBuffer: 10 * 1024 * 1024 });
+      if (shouldCleanupVideo && fs.existsSync(videoPath)) {
+        fs.unlinkSync(videoPath);
+      }
+      return { outputPath: options.outputPath, success: true };
+    } catch (error) {
+      if (shouldCleanupVideo && fs.existsSync(videoPath)) {
+        fs.unlinkSync(videoPath);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Extracts a frame at a specific time in seconds
+   * @param videoSource - Video source (path, URL, or Buffer)
+   * @param timeSeconds - Time in seconds
+   * @param outputFormat - Output format ('jpg' or 'png', default: 'jpg')
+   * @param quality - JPEG quality 1-31 (lower = better, default: 2)
+   * @returns Buffer containing the frame image
+   */
+  async extractFrameAtTime(
+    videoSource: string | Buffer,
+    timeSeconds: number,
+    outputFormat: 'jpg' | 'png' = 'jpg',
+    quality: number = 2
+  ): Promise<Buffer | null> {
+    return this.#extractVideoFrame(videoSource, 0, timeSeconds, outputFormat, quality);
+  }
+
+  /**
+   * Extracts a frame by frame number (converts to time using video FPS)
+   * @param videoSource - Video source (path, URL, or Buffer)
+   * @param frameNumber - Frame number to extract (1-based: frame 1 = first frame)
+   * @param outputFormat - Output format ('jpg' or 'png', default: 'jpg')
+   * @param quality - JPEG quality 1-31 (lower = better, default: 2)
+   * @returns Buffer containing the frame image
+   */
+  async extractFrameByNumber(
+    videoSource: string | Buffer,
+    frameNumber: number,
+    outputFormat: 'jpg' | 'png' = 'jpg',
+    quality: number = 2
+  ): Promise<Buffer | null> {
+    // Get video info to convert frame number to time
+    const videoInfo = await this.getVideoInfo(videoSource, true);
+    if (!videoInfo || videoInfo.fps <= 0) {
+      throw new Error('Could not get video FPS to convert frame number to time');
+    }
+    
+    // Convert frame number to time (frame 1 = 0 seconds, frame 2 = 1/fps, etc.)
+    // For 1-based frame numbers: frame 1 = time 0, frame 2 = time 1/fps
+    const timeSeconds = (frameNumber - 1) / videoInfo.fps;
+    
+    return this.#extractVideoFrame(videoSource, frameNumber - 1, timeSeconds, outputFormat, quality);
+  }
+
+  /**
+   * Extracts multiple frames at specific times
+   * @param videoSource - Video source (path, URL, or Buffer)
+   * @param times - Array of times in seconds
+   * @param outputFormat - Output format ('jpg' or 'png', default: 'jpg')
+   * @param quality - JPEG quality 1-31 (lower = better, default: 2)
+   * @returns Array of buffers containing frame images
+   */
+  async extractMultipleFrames(
+    videoSource: string | Buffer,
+    times: number[],
+    outputFormat: 'jpg' | 'png' = 'jpg',
+    quality: number = 2
+  ): Promise<Buffer[]> {
+    const frames: Buffer[] = [];
+    for (const time of times) {
+      const frame = await this.extractFrameAtTime(videoSource, time, outputFormat, quality);
+      if (frame) {
+        frames.push(frame);
+      }
+    }
+    return frames;
+  }
+
+  /**
+   * Extracts ALL frames from a video and saves them as image files
+   * @param videoSource - Video source (path, URL, or Buffer)
+   * @param options - Extraction options
+   * @returns Array of frame file paths
+   */
+  async extractAllFrames(
+    videoSource: string | Buffer,
+    options?: {
+      outputFormat?: 'jpg' | 'png';
+      outputDirectory?: string;
+      quality?: number; // JPEG quality 1-31 (lower = better, default: 2)
+      prefix?: string; // Filename prefix (default: 'frame')
+      startTime?: number; // Start time in seconds (default: 0)
+      endTime?: number; // End time in seconds (default: video duration)
+    }
+  ): Promise<Array<{ source: string; frameNumber: number; time: number }>> {
+    try {
+      const ffmpegAvailable = await this.#checkFFmpegAvailable();
+      if (!ffmpegAvailable) {
+        const errorMessage = 
+          '❌ FFMPEG NOT FOUND\n' +
+          'Video processing features require FFmpeg to be installed on your system.\n' +
+          this.#getFFmpegInstallInstructions();
+        
+        throw new Error(errorMessage);
+      }
+
+      // Get video info first
+      const videoInfo = await this.getVideoInfo(videoSource, true);
+      if (!videoInfo) {
+        throw new Error('Could not get video information');
+      }
+
+      const outputFormat = options?.outputFormat || 'png';
+      const outputDir = options?.outputDirectory || path.join(process.cwd(), 'extracted-frames');
+      const prefix = options?.prefix || 'frame';
+      const quality = options?.quality || 2;
+
+      // Create output directory
+      if (!fs.existsSync(outputDir)) {
+        fs.mkdirSync(outputDir, { recursive: true });
+      }
+
+      const frameDir = path.join(process.cwd(), '.temp-frames');
+      if (!fs.existsSync(frameDir)) {
+        fs.mkdirSync(frameDir, { recursive: true });
+      }
+
+      const timestamp = Date.now();
+      let videoPath: string;
+      let shouldCleanupVideo = false;
+
+      // Handle video source
+      if (Buffer.isBuffer(videoSource)) {
+        videoPath = path.join(frameDir, `temp-video-${timestamp}.mp4`);
+        fs.writeFileSync(videoPath, videoSource);
+        shouldCleanupVideo = true;
+      } else if (typeof videoSource === 'string' && videoSource.startsWith('http')) {
+        const response = await axios({
+          method: 'get',
+          url: videoSource,
+          responseType: 'arraybuffer'
+        });
+        videoPath = path.join(frameDir, `temp-video-${timestamp}.mp4`);
+        fs.writeFileSync(videoPath, Buffer.from(response.data));
+        shouldCleanupVideo = true;
+      } else {
+        if (!fs.existsSync(videoSource)) {
+          throw new Error(`Video file not found: ${videoSource}`);
+        }
+        videoPath = videoSource;
+      }
+
+      // Calculate time range
+      const startTime = options?.startTime ?? 0;
+      const endTime = options?.endTime ?? videoInfo.duration;
+      const duration = endTime - startTime;
+
+      // Extract all frames using ffmpeg
+      // Use -fps_mode passthrough to extract every frame (no frame skipping)
+      // Don't use -f flag, let FFmpeg infer format from file extension
+      const qualityFlag = outputFormat === 'jpg' ? `-q:v ${quality}` : '';
+      const pixFmt = outputFormat === 'png' ? '-pix_fmt rgba' : '-pix_fmt rgb24';
+      const outputTemplate = path.join(outputDir, `${prefix}-%06d.${outputFormat}`);
+      
+      const escapedVideoPath = videoPath.replace(/"/g, '\\"');
+      const escapedOutputTemplate = outputTemplate.replace(/"/g, '\\"');
+
+      // Use -fps_mode passthrough instead of deprecated -vsync 0
+      // Use -ss after -i for more accurate frame extraction
+      const command = `ffmpeg -i "${escapedVideoPath}" -ss ${startTime} -t ${duration} -fps_mode passthrough ${pixFmt} ${qualityFlag} -y "${escapedOutputTemplate}"`;
+
+      await execAsync(command, { 
+        timeout: 300000, // 5 minute timeout for large videos
+        maxBuffer: 10 * 1024 * 1024
+      });
+
+      // Collect all extracted frame files
+      const frames: Array<{ source: string; frameNumber: number; time: number }> = [];
+      let frameIndex = 0;
+      let currentTime = startTime;
+
+      while (true) {
+        const frameNumber = frameIndex + 1;
+        const framePath = path.join(outputDir, `${prefix}-${String(frameNumber).padStart(6, '0')}.${outputFormat}`);
+        
+        if (fs.existsSync(framePath)) {
+          frames.push({
+            source: framePath,
+            frameNumber: frameIndex,
+            time: currentTime
+          });
+          currentTime += 1 / videoInfo.fps; // Increment by frame duration
+          frameIndex++;
+        } else {
+          break; // No more frames
+        }
+      }
+
+      // Cleanup temp video if created
+      if (shouldCleanupVideo && fs.existsSync(videoPath)) {
+        fs.unlinkSync(videoPath);
+      }
+
+      console.log(`✅ Extracted ${frames.length} frames from video`);
+      return frames;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+      if (errorMessage.includes('FFMPEG NOT FOUND') || errorMessage.includes('FFmpeg')) {
+        throw error;
+      }
+      throw new Error(`extractAllFrames failed: ${errorMessage}`);
+    }
+  }
+