simple-ffmpegjs 0.3.3 → 0.3.5

package/README.md

@@ -28,6 +28,7 @@
   - [Platform Presets](#platform-presets)
   - [Watermarks](#watermarks)
   - [Progress Information](#progress-information)
+  - [Logging](#logging)
   - [Error Handling](#error-handling)
   - [Cancellation](#cancellation)
   - [Gap Handling](#gap-handling)
@@ -390,6 +391,47 @@ console.log(audio.duration); // 180.5
 console.log(audio.sampleRate); // 44100
 ```
 
+#### `SIMPLEFFMPEG.snapshot(filePath, options)`
+
+Capture a single frame from a video file and save it as an image. This is a static method — no project instance needed.
+
+The output format is determined by the `outputPath` file extension. FFmpeg handles format detection internally, so `.jpg` produces JPEG, `.png` produces PNG, `.webp` produces WebP, etc.
+
+```ts
+await SIMPLEFFMPEG.snapshot("./video.mp4", {
+  outputPath: "./frame.png",
+  time: 5,
+});
+```
+
+**Snapshot Options:**
+
+| Option       | Type     | Default | Description                                                                 |
+| ------------ | -------- | ------- | --------------------------------------------------------------------------- |
+| `outputPath` | `string` | -       | **Required.** Output image path (extension determines format)               |
+| `time`       | `number` | `0`     | Time in seconds to capture the frame at                                     |
+| `width`      | `number` | -       | Output width in pixels (maintains aspect ratio if height omitted)           |
+| `height`     | `number` | -       | Output height in pixels (maintains aspect ratio if width omitted)           |
+| `quality`    | `number` | `2`     | JPEG quality 1-31, lower is better (only applies to `.jpg`/`.jpeg` output)  |
+
+**Supported formats:** `.jpg` / `.jpeg`, `.png`, `.webp`, `.bmp`, `.tiff`
+
+```ts
+// Save as JPEG with quality control and resize
+await SIMPLEFFMPEG.snapshot("./video.mp4", {
+  outputPath: "./thumb.jpg",
+  time: 10,
+  width: 640,
+  quality: 4,
+});
+
+// Save as WebP
+await SIMPLEFFMPEG.snapshot("./video.mp4", {
+  outputPath: "./preview.webp",
+  time: 0,
+});
+```
+
 #### `project.export(options)`
 
 Build and execute the FFmpeg command to render the final video.
@@ -421,6 +463,7 @@ await project.export(options?: ExportOptions): Promise<string>
 | `verbose`               | `boolean`     | `false`          | Enable verbose logging                                                           |
 | `saveCommand`           | `string`      | -                | Save FFmpeg command to file                                                      |
 | `onProgress`            | `function`    | -                | Progress callback                                                                |
+| `onLog`                 | `function`    | -                | FFmpeg log callback (see [Logging](#logging) section)                            |
 | `signal`                | `AbortSignal` | -                | Cancellation signal                                                              |
 | `watermark`             | `object`      | -                | Add watermark overlay (see Watermarks section)                                   |
 | `compensateTransitions` | `boolean`     | `true`           | Auto-adjust text timings for transition overlap (see below)                      |
@@ -722,6 +765,21 @@ onProgress: ({ percent, phase }) => {
 }
 ```
 
+### Logging
+
+Use the `onLog` callback to receive real-time FFmpeg output. Each log entry includes a `level` (`"stderr"` or `"stdout"`) and the raw `message` string. This is useful for debugging, monitoring, or piping FFmpeg output to your own logging system.
+
+```ts
+await project.export({
+  outputPath: "./output.mp4",
+  onLog: ({ level, message }) => {
+    console.log(`[ffmpeg:${level}] ${message}`);
+  },
+});
+```
+
+The callback fires for every data chunk FFmpeg writes, including encoding stats, warnings, and codec information. It works alongside `onProgress` — both can be used simultaneously.
+
 ### Error Handling
 
 The library provides custom error classes for structured error handling:
@@ -729,7 +787,7 @@ The library provides custom error classes for structured error handling:
 | Error Class            | When Thrown                | Properties                                                                  |
 | ---------------------- | -------------------------- | --------------------------------------------------------------------------- |
 | `ValidationError`      | Invalid clip configuration | `errors[]`, `warnings[]` (structured issues with `code`, `path`, `message`) |
-| `FFmpegError`          | FFmpeg command fails       | `stderr`, `command`, `exitCode`                                             |
+| `FFmpegError`          | FFmpeg command fails       | `stderr`, `command`, `exitCode`, `details`                                  |
 | `MediaNotFoundError`   | File not found             | `path`                                                                      |
 | `ExportCancelledError` | Export aborted             | -                                                                           |
 
@@ -746,8 +804,9 @@ try {
       console.warn(`[${w.code}] ${w.path}: ${w.message}`)
     );
   } else if (error.name === "FFmpegError") {
-    console.error("FFmpeg failed:", error.stderr);
-    console.error("Command was:", error.command);
+    // Structured details for bug reports (last 50 lines of stderr, command, exitCode)
+    console.error("FFmpeg failed:", error.details);
+    // { stderrTail: "...", command: "ffmpeg ...", exitCode: 1 }
   } else if (error.name === "MediaNotFoundError") {
     console.error("File not found:", error.path);
   } else if (error.name === "ExportCancelledError") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simple-ffmpegjs",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "Declarative video composition for Node.js — define clips, transitions, text, and audio as simple objects, and let FFmpeg handle the rest.",
   "author": "Brayden Blackwell <braydenblackwell21@gmail.com> (https://github.com/Fats403)",
   "license": "MIT",

package/src/core/errors.js

@@ -32,6 +32,20 @@ class FFmpegError extends SimpleffmpegError {
     this.command = command;
     this.exitCode = exitCode;
   }
+
+  /**
+   * Structured error details for easy bug reporting.
+   * Contains the last 50 lines of stderr, the command, and exit code.
+   */
+  get details() {
+    const lines = (this.stderr || "").split("\n");
+    const tail = lines.slice(-50).join("\n");
+    return {
+      stderrTail: tail,
+      command: this.command,
+      exitCode: this.exitCode,
+    };
+  }
 }
 
 /**

package/src/ffmpeg/audio_builder.js

@@ -1,4 +1,11 @@
-function buildAudioForVideoClips(project, videoClips) {
+/**
+ * Build audio filter chain for video clips.
+ *
+ * @param {Object} project - The SIMPLEFFMPEG project instance
+ * @param {Array} videoClips - Array of video clip objects
+ * @param {Map} [transitionOffsets] - Map of clip -> cumulative transition offset in seconds
+ */
+function buildAudioForVideoClips(project, videoClips, transitionOffsets) {
   let audioFilter = "";
   const labels = [];
 
@@ -15,9 +22,11 @@ function buildAudioForVideoClips(project, videoClips) {
         : requestedDuration;
     const clipDuration = Math.max(0, Math.min(requestedDuration, maxAvailable));
 
-    const adelayMs = Math.round(Math.max(0, clip.position || 0) * 1000);
+    const offset = transitionOffsets ? (transitionOffsets.get(clip) || 0) : 0;
+    const adelayMs = Math.round(Math.max(0, (clip.position || 0) - offset) * 1000);
+    const vol = clip.volume != null ? clip.volume : 1;
     const out = `[va${inputIndex}]`;
-    audioFilter += `[${inputIndex}:a]atrim=start=${clip.cutFrom}:duration=${clipDuration},asetpts=PTS-STARTPTS,adelay=${adelayMs}|${adelayMs}${out};`;
+    audioFilter += `[${inputIndex}:a]volume=${vol},atrim=start=${clip.cutFrom}:duration=${clipDuration},asetpts=PTS-STARTPTS,adelay=${adelayMs}|${adelayMs}${out};`;
     labels.push(out);
   });
 

package/src/ffmpeg/command_builder.js

@@ -209,6 +209,45 @@ function buildThumbnailCommand({ inputPath, outputPath, time, width, height }) {
   return cmd;
 }
 
+/**
+ * Build command to capture a single frame from a video file.
+ * Output format is determined by the outputPath extension (jpg, png, webp, etc.).
+ *
+ * @param {Object} options
+ * @param {string} options.inputPath - Path to source video
+ * @param {string} options.outputPath - Output image path (extension determines format)
+ * @param {number} [options.time=0] - Time in seconds to capture
+ * @param {number} [options.width] - Output width (maintains aspect if height omitted)
+ * @param {number} [options.height] - Output height (maintains aspect if width omitted)
+ * @param {number} [options.quality] - JPEG quality 1-31, lower is better (only applies to JPEG)
+ * @returns {string} FFmpeg command string
+ */
+function buildSnapshotCommand({
+  inputPath,
+  outputPath,
+  time = 0,
+  width,
+  height,
+  quality,
+}) {
+  let cmd = `ffmpeg -y -ss ${time} -i "${escapeFilePath(
+    inputPath
+  )}" -vframes 1 `;
+
+  if (width || height) {
+    const w = width || -1;
+    const h = height || -1;
+    cmd += `-vf "scale=${w}:${h}" `;
+  }
+
+  if (quality != null) {
+    cmd += `-q:v ${quality} `;
+  }
+
+  cmd += `"${escapeFilePath(outputPath)}"`;
+  return cmd;
+}
+
 /**
  * Escape metadata value for FFmpeg
  */
@@ -223,5 +262,6 @@ module.exports = {
   buildMainCommand,
   buildTextBatchCommand,
   buildThumbnailCommand,
+  buildSnapshotCommand,
   escapeMetadata,
 };

package/src/ffmpeg/strings.js

@@ -1,7 +1,3 @@
-function escapeSingleQuotes(text) {
-  return String(text).replace(/'/g, "\\'");
-}
-
 /**
  * Escape a file path for use in FFmpeg command line arguments.
  * Prevents command injection by escaping quotes and backslashes.
@@ -21,32 +17,54 @@ function escapeFilePath(filePath) {
  */
 function hasProblematicChars(text) {
   if (typeof text !== "string") return false;
-  // These characters cannot be reliably escaped in filter_complex parsing
-  // when passed through shell double-quoting
-  return /[,;{}\[\]"]/.test(text);
+  // These characters cannot be reliably escaped in filter_complex parsing.
+  // Single quotes (') are included because FFmpeg's av_get_token does NOT
+  // support \' inside single-quoted strings — ' always ends the quoted value.
+  // Non-ASCII characters are also routed to textfile to avoid parser issues
+  // with UTF-8 inside filter_complex.
+  return /[,;{}\[\]"']/.test(text) || /[^\x20-\x7E]/.test(text);
 }
 
 function escapeDrawtextText(text) {
   if (typeof text !== "string") return "";
-  // Escape characters that have special meaning in FFmpeg drawtext filter
-  // AND characters that break shell parsing (since filter_complex is double-quoted)
+  // Escape characters that have special meaning in FFmpeg drawtext filter.
+  //
+  // FFmpeg parses the filter_complex value through TWO levels of av_get_token:
+  //   Level 1 — filter-graph parser (terminators: [ , ; \n)
+  //   Level 2 — filter option parser (terminators: : = )
+  // Both levels handle '...' quoting and \x escaping identically.
+  //
+  // To embed a literal single quote that survives both levels:
+  //   1. End the current level-1 quoted segment:      '
+  //   2. \\  — level 1 escape → produces \  in output
+  //   3. \'  — level 1 escape → produces '  in output
+  //      So level 2 sees \' → escaped quote → literal '
+  //   4. Re-open a new level-1 quoted segment:        '
+  // The 6-char replacement per apostrophe is:  '\\\''
+  //
+  // Backslash (\\) and colon (\:) escaping inside the quoted segments is
+  // passed through literally by level 1 (no escape processing inside '...'),
+  // then processed by level 2 as escape sequences: \\ → \ and \: → :
   return text
-    .replace(/\\/g, "\\\\") // Escape backslashes first
-    .replace(/'/g, "\\'") // Escape single quotes (text delimiter)
-    .replace(/"/g, '\\"') // Escape double quotes (shell safety)
-    .replace(/:/g, "\\:") // Escape colons (option separator)
+    .replace(/\\/g, "\\\\") // Escape backslashes (level 2 decodes \\ → \)
+    .replace(/'/g, "'\\\\\\''" ) // End quote, \\' (two-level escape), re-open quote
+    .replace(/:/g, "\\:") // Escape colons (level 2 decodes \: → :)
     .replace(/\n/g, " ") // Replace newlines with space (multiline not supported)
     .replace(/\r/g, ""); // Remove carriage returns
 }
 
 /**
- * Escape a file path for use in FFmpeg filters (Windows paths need special handling)
+ * Escape a file path for use inside single-quoted FFmpeg filter parameters
+ * (e.g., textfile='...', ass='...').
+ *
+ * These paths are parsed through two levels of av_get_token, so single
+ * quotes need the same '\\\'' two-level escape as drawtext text values.
  */
 function escapeTextFilePath(filePath) {
   if (typeof filePath !== "string") return "";
-  // FFmpeg on Windows needs forward slashes and escaped colons
   return filePath
     .replace(/\\/g, "/") // Convert backslashes to forward slashes
+    .replace(/'/g, "'\\\\\\''" ) // Two-level apostrophe escape (same as escapeDrawtextText)
     .replace(/:/g, "\\:"); // Escape colons (for Windows drive letters)
 }
 
@@ -62,7 +80,6 @@ function getClipAudioString(clip, inputIndex) {
 }
 
 module.exports = {
-  escapeSingleQuotes,
   escapeFilePath,
   escapeDrawtextText,
   getClipAudioString,

package/src/ffmpeg/subtitle_builder.js

@@ -637,11 +637,11 @@ function loadSubtitleFile(filePath, options, canvasWidth, canvasHeight) {
  * @returns {{ filter: string, finalLabel: string }}
  */
 function buildASSFilter(assFilePath, inputLabel) {
-  // Escape path for FFmpeg filter
+  // Escape path for FFmpeg filter (must survive two levels of av_get_token)
   const escapedPath = assFilePath
     .replace(/\\/g, "/")
     .replace(/:/g, "\\:")
-    .replace(/'/g, "'\\''");
+    .replace(/'/g, "'\\\\\\''" );
 
   const outputLabel = "[outass]";
   const filter = `${inputLabel}ass='${escapedPath}'${outputLabel}`;

package/src/ffmpeg/text_passes.js

@@ -8,10 +8,11 @@ const { parseFFmpegCommand } = require("../lib/utils");
 /**
  * Run an FFmpeg command using spawn() to avoid command injection.
  * @param {string} cmd - The full FFmpeg command string
+ * @param {Function} [onLog] - Optional log callback receiving { level, message }
  * @returns {Promise<void>}
  * @throws {FFmpegError} If ffmpeg fails
  */
-function runCmd(cmd) {
+function runCmd(cmd, onLog) {
   return new Promise((resolve, reject) => {
     const args = parseFFmpegCommand(cmd);
     const ffmpegPath = args.shift(); // Remove 'ffmpeg' from args
@@ -22,8 +23,19 @@ function runCmd(cmd) {
 
     let stderr = "";
 
+    proc.stdout.on("data", (data) => {
+      const chunk = data.toString();
+      if (onLog && typeof onLog === "function") {
+        onLog({ level: "stdout", message: chunk });
+      }
+    });
+
     proc.stderr.on("data", (data) => {
-      stderr += data.toString();
+      const chunk = data.toString();
+      stderr += chunk;
+      if (onLog && typeof onLog === "function") {
+        onLog({ level: "stderr", message: chunk });
+      }
     });
 
     proc.on("error", (error) => {
@@ -61,6 +73,7 @@ async function runTextPasses({
   intermediatePreset,
   intermediateCrf,
   batchSize = 75,
+  onLog,
 }) {
   const tempOutputs = [];
   let currentInput = baseOutputPath;
@@ -89,7 +102,7 @@ async function runTextPasses({
       intermediateCrf,
       outputPath: batchOutput,
     });
-    await runCmd(cmd);
+    await runCmd(cmd, onLog);
     currentInput = batchOutput;
     passes += 1;
   }

package/src/ffmpeg/text_renderer.js

@@ -147,7 +147,7 @@ function buildDrawtextParams(
   end
 ) {
   const fontSpec = baseClip.fontFile
-    ? `fontfile=${baseClip.fontFile}`
+    ? `fontfile='${Strings.escapeTextFilePath(baseClip.fontFile)}'`
     : baseClip.fontFamily
     ? `font=${baseClip.fontFamily}`
     : `font=Sans`;

package/src/ffmpeg/video_builder.js

@@ -29,7 +29,7 @@ function buildVideoFilter(project, videoClips) {
     if (gaps.length > 0) {
       const blackClips = createBlackClipsForGaps(gaps, fps, width, height);
       allVisualClips = [...videoClips, ...blackClips].sort(
-        (a, b) => (a.position || 0) - (b.position || 0)
+        (a, b) => (a.position || 0) - (b.position || 0),
       );
     }
   }
@@ -41,7 +41,7 @@ function buildVideoFilter(project, videoClips) {
 
     const requestedDuration = Math.max(
       0,
-      (clip.end || 0) - (clip.position || 0)
+      (clip.end || 0) - (clip.position || 0),
     );
 
     // Handle synthetic black fill clips
@@ -85,12 +85,12 @@ function buildVideoFilter(project, videoClips) {
       if (type === "zoom-in") {
         const inc = (zoomAmount / framesMinusOne).toFixed(6);
         // Ensure first frame starts exactly at base zoom=1 (on==0)
-        zoomExpr = `if(eq(on\\,0)\\,1\\,zoom+${inc})`;
+        zoomExpr = `if(eq(on,0),1,zoom+${inc})`;
       } else if (type === "zoom-out") {
         const start = (1 + zoomAmount).toFixed(4);
         const dec = (zoomAmount / framesMinusOne).toFixed(6);
         // Start pre-zoomed on first frame to avoid jump
-        zoomExpr = `if(eq(on\\,0)\\,${start}\\,zoom-${dec})`;
+        zoomExpr = `if(eq(on,0),${start},zoom-${dec})`;
       } else {
         const panZoom = 1.12;
         zoomExpr = `${panZoom}`;
@@ -113,7 +113,9 @@ function buildVideoFilter(project, videoClips) {
 
       // Scale to cover target dimensions (upscaling if needed), then center crop
       // force_original_aspect_ratio=increase ensures image covers the target area
-      filterComplex += `[${inputIndex}:v]select=eq(n\\,0),setpts=PTS-STARTPTS,scale=${width}:${height}:force_original_aspect_ratio=increase,setsar=1:1,crop=${width}:${height}:(iw-${width})/2:(ih-${height})/2,scale=${overscanW}:-1,zoompan=z='${zoomExpr}':x='${xExpr}':y='${yExpr}':d=${frames}:s=${s},fps=${fps},settb=1/${fps}${scaledLabel};`;
+      // select='eq(n,0)' uses single quotes to protect the comma from the graph parser.
+      // zoompan z/x/y values are also single-quoted — commas inside are literal.
+      filterComplex += `[${inputIndex}:v]select='eq(n,0)',setpts=PTS-STARTPTS,scale=${width}:${height}:force_original_aspect_ratio=increase,setsar=1:1,crop=${width}:${height}:(iw-${width})/2:(ih-${height})/2,scale=${overscanW}:-1,zoompan=z='${zoomExpr}':x='${xExpr}':y='${yExpr}':d=${frames}:s=${s},fps=${fps},settb=1/${fps}${scaledLabel};`;
     } else {
       filterComplex += `[${inputIndex}:v]trim=start=${
         clip.cutFrom || 0
@@ -134,7 +136,7 @@ function buildVideoFilter(project, videoClips) {
   }
 
   const hasTransitions = scaledStreams.some(
-    (s, i) => i > 0 && s.clip.transition
+    (s, i) => i > 0 && s.clip.transition,
   );
 
   if (!hasTransitions) {

package/src/ffmpeg/watermark_builder.js

@@ -1,16 +1,5 @@
 const Strings = require("./strings");
 
-/**
- * Position presets for watermarks
- */
-const POSITION_PRESETS = {
-  "top-left": (margin) => ({ x: margin, y: margin }),
-  "top-right": (margin) => ({ x: `W-w-${margin}`, y: margin }),
-  "bottom-left": (margin) => ({ x: margin, y: `H-h-${margin}` }),
-  "bottom-right": (margin) => ({ x: `W-w-${margin}`, y: `H-h-${margin}` }),
-  center: () => ({ x: "(W-w)/2", y: "(H-h)/2" }),
-};
-
 /**
  * Calculate position expressions for overlay/drawtext
  * @param {Object} config - Watermark config with position, margin
@@ -91,7 +80,7 @@ function buildImageWatermark(
   watermarkInputIndex,
   canvasWidth,
   canvasHeight,
-  totalDuration
+  totalDuration,
 ) {
   const scale = typeof config.scale === "number" ? config.scale : 0.15;
   const opacity = typeof config.opacity === "number" ? config.opacity : 1;
@@ -144,7 +133,7 @@ function buildTextWatermark(
   videoLabel,
   canvasWidth,
   canvasHeight,
-  totalDuration
+  totalDuration,
 ) {
   const text = config.text || "";
   const fontSize = typeof config.fontSize === "number" ? config.fontSize : 24;
@@ -158,9 +147,8 @@ function buildTextWatermark(
   // Escape text for drawtext
   const escapedText = Strings.escapeDrawtextText(text);
 
-  // Font specification
   const fontSpec = config.fontFile
-    ? `fontfile=${config.fontFile}`
+    ? `fontfile='${Strings.escapeTextFilePath(config.fontFile)}'`
     : `font=${fontFamily}`;
 
   // Calculate position (for text)
@@ -257,7 +245,7 @@ function buildWatermarkFilter(
   watermarkInputIndex,
   canvasWidth,
   canvasHeight,
-  totalDuration
+  totalDuration,
 ) {
   if (!config || typeof config !== "object") {
     return { filter: "", finalLabel: videoLabel, needsInput: false };
@@ -271,7 +259,7 @@ function buildWatermarkFilter(
       videoLabel,
       canvasWidth,
       canvasHeight,
-      totalDuration
+      totalDuration,
     );
     return { ...result, needsInput: false };
   }
@@ -288,7 +276,7 @@ function buildWatermarkFilter(
       watermarkInputIndex,
       canvasWidth,
       canvasHeight,
-      totalDuration
+      totalDuration,
     );
     return { ...result, needsInput: true };
   }
@@ -369,8 +357,8 @@ function validateWatermarkConfig(config) {
     if (!validPositions.includes(config.position)) {
       errors.push(
         `watermark.position must be one of: ${validPositions.join(
-          ", "
-        )}; got '${config.position}'`
+          ", ",
+        )}; got '${config.position}'`,
       );
     }
   } else if (typeof config.position === "object" && config.position !== null) {

package/src/lib/utils.js

@@ -76,9 +76,10 @@ function parseFFmpegProgress(line, totalDuration) {
  * @param {number} options.totalDuration - Expected output duration in seconds (for progress %)
  * @param {Function} options.onProgress - Progress callback
  * @param {AbortSignal} options.signal - AbortSignal for cancellation
+ * @param {Function} options.onLog - Log callback receiving { level: "stderr"|"stdout", message: string }
  * @returns {Promise<{stdout: string, stderr: string}>}
  */
-function runFFmpeg({ command, totalDuration = 0, onProgress, signal }) {
+function runFFmpeg({ command, totalDuration = 0, onProgress, signal, onLog }) {
   return new Promise((resolve, reject) => {
     // Parse command into args (simple split, assumes no quoted args with spaces in values)
     // FFmpeg commands from this library don't have spaces in quoted paths handled this way
@@ -115,13 +116,21 @@ function runFFmpeg({ command, totalDuration = 0, onProgress, signal }) {
     }
 
     proc.stdout.on("data", (data) => {
-      stdout += data.toString();
+      const chunk = data.toString();
+      stdout += chunk;
+      if (onLog && typeof onLog === "function") {
+        onLog({ level: "stdout", message: chunk });
+      }
     });
 
     proc.stderr.on("data", (data) => {
       const chunk = data.toString();
       stderr += chunk;
 
+      if (onLog && typeof onLog === "function") {
+        onLog({ level: "stderr", message: chunk });
+      }
+
       // Parse progress from stderr (FFmpeg outputs progress to stderr)
       if (onProgress && typeof onProgress === "function") {
         const progress = parseFFmpegProgress(chunk, totalDuration);
@@ -164,8 +173,22 @@ function runFFmpeg({ command, totalDuration = 0, onProgress, signal }) {
 }
 
 /**
- * Parse a command string into an array of arguments
- * Handles quoted strings and escaped characters
+ * Parse a command string into an array of arguments.
+ *
+ * Inside quoted strings (single or double):
+ *   - All characters are literal (no escape processing).
+ *   - The matching closing quote ends the argument segment.
+ *
+ * This deliberately avoids backslash-escape handling because the
+ * filter_complex value relies on \\, \, and \: being passed through
+ * verbatim to FFmpeg.  For example drawtext's fontsize expressions
+ * use \\, (which drawtext decodes as \, → escaped comma) and text
+ * values use \\\\ (which drawtext decodes as \\ → literal backslash).
+ * Any unescaping here would corrupt those sequences.
+ *
+ * Outside quotes:
+ *   - Whitespace separates arguments.
+ *   - All other characters (including backslash) are literal.
  */
 function parseFFmpegCommand(command) {
   const args = [];
@@ -179,14 +202,12 @@ function parseFFmpegCommand(command) {
     if (inQuote) {
       if (char === quoteChar) {
         inQuote = false;
-        // Don't add the closing quote to the argument
       } else {
         current += char;
       }
     } else if (char === '"' || char === "'") {
       inQuote = true;
       quoteChar = char;
-      // Don't add the opening quote to the argument
     } else if (char === " " || char === "\t") {
       if (current.length > 0) {
         args.push(current);

package/src/simpleffmpeg.js

@@ -28,6 +28,7 @@ const C = require("./core/constants");
 const {
   buildMainCommand,
   buildThumbnailCommand,
+  buildSnapshotCommand,
 } = require("./ffmpeg/command_builder");
 const { runTextPasses } = require("./ffmpeg/text_passes");
 const { formatBytes, runFFmpeg } = require("./lib/utils");
@@ -252,7 +253,7 @@ class SIMPLEFFMPEG {
       await Promise.all(
         resolvedClips.map((clipObj) => {
           if (clipObj.type === "video" || clipObj.type === "audio") {
-            clipObj.volume = clipObj.volume || 1;
+            clipObj.volume = clipObj.volume != null ? clipObj.volume : 1;
             clipObj.cutFrom = clipObj.cutFrom || 0;
             if (clipObj.type === "video" && clipObj.transition) {
               clipObj.transition = {
@@ -438,8 +439,18 @@ class SIMPLEFFMPEG {
     }
 
     // Audio for video clips (aligned amix)
+    // Compute cumulative transition offsets so audio adelay values
+    // match the xfade-compressed video timeline.
     if (videoClips.length > 0) {
-      const ares = buildAudioForVideoClips(this, videoClips);
+      const transitionOffsets = new Map();
+      let cumOffset = 0;
+      for (let i = 0; i < videoClips.length; i++) {
+        if (i > 0 && videoClips[i].transition) {
+          cumOffset += videoClips[i].transition.duration || 0;
+        }
+        transitionOffsets.set(videoClips[i], cumOffset);
+      }
+      const ares = buildAudioForVideoClips(this, videoClips, transitionOffsets);
       filterComplex += ares.filter;
       finalAudioLabel = ares.finalAudioLabel || finalAudioLabel;
       hasAudio = hasAudio || ares.hasAudio;
@@ -860,7 +871,7 @@ class SIMPLEFFMPEG {
 
     this._isExporting = true;
     const t0 = Date.now();
-    const { onProgress, signal } = options;
+    const { onProgress, signal, onLog } = options;
 
     let prepared;
     try {
@@ -948,6 +959,7 @@ class SIMPLEFFMPEG {
           command: pass1Command,
           totalDuration,
           signal,
+          onLog,
         });
 
         // Second pass
@@ -984,6 +996,7 @@ class SIMPLEFFMPEG {
           totalDuration,
           onProgress,
           signal,
+          onLog,
         });
 
         // Clean up pass log files
@@ -998,6 +1011,7 @@ class SIMPLEFFMPEG {
           totalDuration,
           onProgress,
           signal,
+          onLog,
         });
       }
 
@@ -1020,6 +1034,7 @@ class SIMPLEFFMPEG {
           intermediatePreset: exportOptions.intermediatePreset,
           intermediateCrf: exportOptions.intermediateCrf,
           batchSize: exportOptions.textMaxNodesPerPass,
+          onLog,
         });
         passes = textPasses;
         if (finalPath !== exportOptions.outputPath) {
@@ -1047,7 +1062,7 @@ class SIMPLEFFMPEG {
           console.log("simple-ffmpeg: Generating thumbnail...");
         }
 
-        await runFFmpeg({ command: thumbCommand });
+        await runFFmpeg({ command: thumbCommand, onLog });
         console.log(`simple-ffmpeg: Thumbnail -> ${thumbOptions.outputPath}`);
       }
 
@@ -1211,6 +1226,72 @@ class SIMPLEFFMPEG {
     return probeMedia(filePath);
   }
 
+  /**
+   * Capture a single frame from a video file and save it as an image.
+   *
+   * The output format is determined by the `outputPath` file extension.
+   * Supported formats include: `.jpg`/`.jpeg`, `.png`, `.webp`, `.bmp`, `.tiff`.
+   *
+   * @param {string} filePath - Path to the source video file
+   * @param {Object} options - Snapshot options
+   * @param {string} options.outputPath - Output image path (extension determines format)
+   * @param {number} [options.time=0] - Time in seconds to capture the frame at
+   * @param {number} [options.width] - Output width in pixels (maintains aspect ratio if height omitted)
+   * @param {number} [options.height] - Output height in pixels (maintains aspect ratio if width omitted)
+   * @param {number} [options.quality] - JPEG quality 1-31, lower is better (default: 2, only applies to JPEG)
+   * @returns {Promise<string>} The resolved output path
+   * @throws {SimpleffmpegError} If filePath or outputPath is missing
+   * @throws {FFmpegError} If FFmpeg fails to extract the frame
+   *
+   * @example
+   * // Save as PNG
+   * await SIMPLEFFMPEG.snapshot("./video.mp4", {
+   *   outputPath: "./frame.png",
+   *   time: 5,
+   * });
+   *
+   * @example
+   * // Save as JPEG with quality and resize
+   * await SIMPLEFFMPEG.snapshot("./video.mp4", {
+   *   outputPath: "./thumb.jpg",
+   *   time: 10,
+   *   width: 640,
+   *   quality: 4,
+   * });
+   */
+  static async snapshot(filePath, options = {}) {
+    if (!filePath) {
+      throw new SimpleffmpegError(
+        "snapshot() requires a filePath as the first argument"
+      );
+    }
+    if (!options.outputPath) {
+      throw new SimpleffmpegError(
+        "snapshot() requires options.outputPath to be specified"
+      );
+    }
+
+    const {
+      outputPath,
+      time = 0,
+      width,
+      height,
+      quality,
+    } = options;
+
+    const command = buildSnapshotCommand({
+      inputPath: filePath,
+      outputPath,
+      time,
+      width,
+      height,
+      quality,
+    });
+
+    await runFFmpeg({ command });
+    return outputPath;
+  }
+
   /**
    * Format validation result as human-readable string
    * @param {Object} result - Validation result from validate()

package/types/index.d.mts

@@ -21,6 +21,12 @@ declare namespace SIMPLEFFMPEG {
     stderr: string;
     command: string;
     exitCode: number | null;
+    /** Structured error details for bug reporting */
+    readonly details: {
+      stderrTail: string;
+      command: string;
+      exitCode: number | null;
+    };
   }
 
   /** Thrown when a media file cannot be found or accessed */
@@ -295,6 +301,12 @@ declare namespace SIMPLEFFMPEG {
     fillGaps?: "none" | "black";
   }
 
+  /** Log entry passed to onLog callback */
+  interface LogEntry {
+    level: "stderr" | "stdout";
+    message: string;
+  }
+
   /** Progress information passed to onProgress callback */
   interface ProgressInfo {
     /** Current frame number being processed */
@@ -334,6 +346,20 @@ declare namespace SIMPLEFFMPEG {
     height?: number;
   }
 
+  /** Options for SIMPLEFFMPEG.snapshot() — capture a single frame from a video */
+  interface SnapshotOptions {
+    /** Output image path (extension determines format: .jpg, .png, .webp, .bmp, .tiff) */
+    outputPath: string;
+    /** Time in seconds to capture the frame at (default: 0) */
+    time?: number;
+    /** Output width in pixels (maintains aspect ratio if height omitted) */
+    width?: number;
+    /** Output height in pixels (maintains aspect ratio if width omitted) */
+    height?: number;
+    /** JPEG quality 1-31, lower is better (default: 2, only applies to JPEG output) */
+    quality?: number;
+  }
+
   type HardwareAcceleration =
     | "auto"
     | "videotoolbox"
@@ -483,6 +509,8 @@ declare namespace SIMPLEFFMPEG {
 
     // Callbacks & Control
     onProgress?: (progress: ProgressInfo) => void;
+    /** FFmpeg log callback for real-time stderr/stdout output */
+    onLog?: (entry: LogEntry) => void;
     signal?: AbortSignal;
 
     // Text Batching
@@ -670,6 +698,28 @@ declare class SIMPLEFFMPEG {
    */
   static probe(filePath: string): Promise<SIMPLEFFMPEG.MediaInfo>;
 
+  /**
+   * Capture a single frame from a video file and save it as an image.
+   * The output format is determined by the outputPath file extension
+   * (.jpg, .png, .webp, .bmp, .tiff).
+   *
+   * @param filePath - Path to the source video file
+   * @param options - Snapshot options
+   * @returns The output path
+   * @throws {SIMPLEFFMPEG.SimpleffmpegError} If filePath or outputPath is missing
+   * @throws {SIMPLEFFMPEG.FFmpegError} If FFmpeg fails to extract the frame
+   *
+   * @example
+   * await SIMPLEFFMPEG.snapshot("./video.mp4", {
+   *   outputPath: "./frame.png",
+   *   time: 5,
+   * });
+   */
+  static snapshot(
+    filePath: string,
+    options: SIMPLEFFMPEG.SnapshotOptions
+  ): Promise<string>;
+
   /**
    * Format validation result as human-readable string
    */

package/types/index.d.ts

@@ -21,6 +21,12 @@ declare namespace SIMPLEFFMPEG {
     stderr: string;
     command: string;
     exitCode: number | null;
+    /** Structured error details for bug reporting */
+    readonly details: {
+      stderrTail: string;
+      command: string;
+      exitCode: number | null;
+    };
   }
 
   /** Thrown when a media file cannot be found or accessed */
@@ -295,6 +301,12 @@ declare namespace SIMPLEFFMPEG {
     fillGaps?: "none" | "black";
   }
 
+  /** Log entry passed to onLog callback */
+  interface LogEntry {
+    level: "stderr" | "stdout";
+    message: string;
+  }
+
   /** Progress information passed to onProgress callback */
   interface ProgressInfo {
     /** Current frame number being processed */
@@ -339,6 +351,20 @@ declare namespace SIMPLEFFMPEG {
     height?: number;
   }
 
+  /** Options for SIMPLEFFMPEG.snapshot() — capture a single frame from a video */
+  interface SnapshotOptions {
+    /** Output image path (extension determines format: .jpg, .png, .webp, .bmp, .tiff) */
+    outputPath: string;
+    /** Time in seconds to capture the frame at (default: 0) */
+    time?: number;
+    /** Output width in pixels (maintains aspect ratio if height omitted) */
+    width?: number;
+    /** Output height in pixels (maintains aspect ratio if width omitted) */
+    height?: number;
+    /** JPEG quality 1-31, lower is better (default: 2, only applies to JPEG output) */
+    quality?: number;
+  }
+
   /** Hardware acceleration options */
   type HardwareAcceleration =
     | "auto"
@@ -563,6 +589,8 @@ declare namespace SIMPLEFFMPEG {
 
     /** Progress callback for monitoring export progress */
     onProgress?: (progress: ProgressInfo) => void;
+    /** FFmpeg log callback for real-time stderr/stdout output */
+    onLog?: (entry: LogEntry) => void;
     /** AbortSignal for cancelling the export */
     signal?: AbortSignal;
 
@@ -769,6 +797,28 @@ declare class SIMPLEFFMPEG {
    */
   static probe(filePath: string): Promise<SIMPLEFFMPEG.MediaInfo>;
 
+  /**
+   * Capture a single frame from a video file and save it as an image.
+   * The output format is determined by the outputPath file extension
+   * (.jpg, .png, .webp, .bmp, .tiff).
+   *
+   * @param filePath - Path to the source video file
+   * @param options - Snapshot options
+   * @returns The output path
+   * @throws {SIMPLEFFMPEG.SimpleffmpegError} If filePath or outputPath is missing
+   * @throws {SIMPLEFFMPEG.FFmpegError} If FFmpeg fails to extract the frame
+   *
+   * @example
+   * await SIMPLEFFMPEG.snapshot("./video.mp4", {
+   *   outputPath: "./frame.png",
+   *   time: 5,
+   * });
+   */
+  static snapshot(
+    filePath: string,
+    options: SIMPLEFFMPEG.SnapshotOptions
+  ): Promise<string>;
+
   /**
    * Format validation result as human-readable string
    */