simple-ffmpegjs 0.3.2 → 0.3.4

package/src/core/validation.js

@@ -79,6 +79,49 @@ function validateClip(clip, index, options = {}) {
     return { errors, warnings }; // Can't validate further with invalid type
   }
 
+  // Validate duration field if present (applies to all clip types)
+  if (clip.duration != null) {
+    if (typeof clip.duration !== "number") {
+      errors.push(
+        createIssue(
+          ValidationCodes.INVALID_VALUE,
+          `${path}.duration`,
+          "Duration must be a number",
+          clip.duration
+        )
+      );
+    } else if (!Number.isFinite(clip.duration)) {
+      errors.push(
+        createIssue(
+          ValidationCodes.INVALID_VALUE,
+          `${path}.duration`,
+          "Duration must be a finite number (not NaN or Infinity)",
+          clip.duration
+        )
+      );
+    } else if (clip.duration <= 0) {
+      errors.push(
+        createIssue(
+          ValidationCodes.INVALID_RANGE,
+          `${path}.duration`,
+          "Duration must be greater than 0",
+          clip.duration
+        )
+      );
+    }
+    // Conflict check: duration + end both set
+    if (clip.end != null) {
+      errors.push(
+        createIssue(
+          ValidationCodes.INVALID_VALUE,
+          `${path}`,
+          "Cannot specify both 'duration' and 'end'. Use one or the other.",
+          { duration: clip.duration, end: clip.end }
+        )
+      );
+    }
+  }
+
   // Types that require position/end on timeline
   const requiresTimeline = ["video", "audio", "text", "image"].includes(
     clip.type

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,17 +116,26 @@ 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);
         if (Object.keys(progress).length > 0) {
+          progress.phase = "rendering";
           onProgress(progress);
         }
       }
@@ -163,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 = [];
@@ -178,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/loaders.js

@@ -1,15 +1,15 @@
 const fs = require("fs");
 const path = require("path");
-const { getVideoMetadata, getMediaDuration } = require("./core/media_info");
+const { probeMedia } = require("./core/media_info");
 const { ValidationError, MediaNotFoundError } = require("./core/errors");
 const C = require("./core/constants");
 
 async function loadVideo(project, clipObj) {
-  const metadata = await getVideoMetadata(clipObj.url);
-  if (typeof clipObj.cutFrom === "number" && metadata.durationSec != null) {
-    if (clipObj.cutFrom >= metadata.durationSec) {
+  const metadata = await probeMedia(clipObj.url);
+  if (typeof clipObj.cutFrom === "number" && metadata.duration != null) {
+    if (clipObj.cutFrom >= metadata.duration) {
       throw new ValidationError(
-        `Video clip cutFrom (${clipObj.cutFrom}s) must be < source duration (${metadata.durationSec}s)`,
+        `Video clip cutFrom (${clipObj.cutFrom}s) must be < source duration (${metadata.duration}s)`,
         {
           errors: [
             {
@@ -26,10 +26,10 @@ async function loadVideo(project, clipObj) {
     typeof clipObj.position === "number" &&
     typeof clipObj.end === "number" &&
     typeof clipObj.cutFrom === "number" &&
-    metadata.durationSec != null
+    metadata.duration != null
   ) {
     const requestedDuration = Math.max(0, clipObj.end - clipObj.position);
-    const maxAvailable = Math.max(0, metadata.durationSec - clipObj.cutFrom);
+    const maxAvailable = Math.max(0, metadata.duration - clipObj.cutFrom);
     if (requestedDuration > maxAvailable) {
       const clampedEnd = clipObj.position + maxAvailable;
       console.warn(
@@ -42,14 +42,15 @@ async function loadVideo(project, clipObj) {
   }
   project.videoOrAudioClips.push({
     ...clipObj,
-    iphoneRotation: metadata.iphoneRotation,
+    iphoneRotation: metadata.rotation,
     hasAudio: metadata.hasAudio,
-    mediaDuration: metadata.durationSec,
+    mediaDuration: metadata.duration,
   });
 }
 
 async function loadAudio(project, clipObj) {
-  const durationSec = await getMediaDuration(clipObj.url);
+  const metadata = await probeMedia(clipObj.url);
+  const durationSec = metadata.duration;
   if (typeof clipObj.cutFrom === "number" && durationSec != null) {
     if (clipObj.cutFrom >= durationSec) {
       throw new ValidationError(
@@ -93,7 +94,8 @@ function loadImage(project, clipObj) {
 }
 
 async function loadBackgroundAudio(project, clipObj) {
-  const durationSec = await getMediaDuration(clipObj.url);
+  const metadata = await probeMedia(clipObj.url);
+  const durationSec = metadata.duration;
   const clip = {
     ...clipObj,
     volume:

package/src/schema/formatter.js

@@ -107,6 +107,12 @@ function formatSchema(modules, options = {}) {
   lines.push(
     "- All times are in **seconds**. `position` = when the clip starts, `end` = when it ends."
   );
+  lines.push(
+    "- **`duration`** can be used instead of `end`: the library computes `end = position + duration`. Cannot use both."
+  );
+  lines.push(
+    "- **Auto-sequencing:** For video, image, and audio clips, `position` can be omitted. The clip will be placed immediately after the previous clip on its track. The first clip defaults to position 0."
+  );
   lines.push(
     "- Video/image clips form the visual timeline. Audio, text, and music are layered on top."
   );

package/src/schema/modules/audio.js

@@ -6,8 +6,9 @@ module.exports = {
   schema: `{
   type: "audio";              // Required: clip type identifier
   url: string;                // Required: path to audio file
-  position: number;           // Required: start time on timeline (seconds)
-  end: number;                // Required: end time on timeline (seconds)
+  position?: number;          // Start time on timeline (seconds). Omit to auto-sequence after previous audio clip.
+  end?: number;               // End time on timeline (seconds). Use end OR duration, not both.
+  duration?: number;          // Duration in seconds (alternative to end). end = position + duration.
   cutFrom?: number;           // Start playback from this point in the source (default: 0)
   volume?: number;            // Volume multiplier (default: 1, 0 = mute, >1 = amplify)
 }`,
@@ -22,6 +23,8 @@ module.exports = {
     },
   ],
   notes: [
+    "If position is omitted, the clip is placed immediately after the previous audio clip (auto-sequencing). The first clip defaults to position 0.",
+    "Use duration instead of end to specify how long the clip plays: end = position + duration. Cannot use both.",
     "Audio clips are mixed (layered) with video audio and background music — they don't replace other audio.",
     "Use cutFrom to start playback partway through the source file.",
   ],

package/src/schema/modules/image.js

@@ -6,8 +6,9 @@ module.exports = {
   schema: `{
   type: "image";              // Required: clip type identifier
   url: string;                // Required: path to image file (jpg, png, etc.)
-  position: number;           // Required: start time on timeline (seconds)
-  end: number;                // Required: end time on timeline (seconds)
+  position?: number;          // Start time on timeline (seconds). Omit to auto-sequence after previous video/image clip.
+  end?: number;               // End time on timeline (seconds). Use end OR duration, not both.
+  duration?: number;          // Duration in seconds (alternative to end). end = position + duration.
   kenBurns?: KenBurnsEffect;  // Optional: apply pan/zoom motion to the image
 }`,
   enums: {
@@ -23,14 +24,20 @@ module.exports = {
   examples: [
     {
       label: "Static image for 5 seconds",
-      code: `{ type: "image", url: "photo.jpg", position: 0, end: 5 }`,
+      code: `{ type: "image", url: "photo.jpg", duration: 5 }`,
     },
     {
-      label: "Image with slow zoom-in effect",
-      code: `{ type: "image", url: "landscape.png", position: 5, end: 12, kenBurns: "zoom-in" }`,
+      label: "Image slideshow with Ken Burns effects (auto-sequenced)",
+      code: `[
+  { type: "image", url: "photo1.jpg", duration: 3, kenBurns: "zoom-in" },
+  { type: "image", url: "photo2.jpg", duration: 3, kenBurns: "pan-right" },
+  { type: "image", url: "photo3.jpg", duration: 3, kenBurns: "zoom-out" }
+]`,
     },
   ],
   notes: [
+    "If position is omitted, the clip is placed immediately after the previous video/image clip (auto-sequencing). The first clip defaults to position 0.",
+    "Use duration instead of end to specify how long the image displays: end = position + duration. Cannot use both.",
     "Images are scaled to fill the project canvas. For Ken Burns, use images at least as large as the output resolution for best quality.",
     "Image clips can be placed on the same timeline as video clips and can use transitions between them.",
   ],

package/src/schema/modules/music.js

@@ -7,7 +7,8 @@ module.exports = {
   type: "music";              // Required: clip type ("music" or "backgroundAudio")
   url: string;                // Required: path to audio file
   position?: number;          // Start time on timeline (default: 0)
-  end?: number;               // End time on timeline (default: end of video)
+  end?: number;               // End time on timeline (default: end of video). Use end OR duration, not both.
+  duration?: number;          // Duration in seconds (alternative to end). end = position + duration.
   cutFrom?: number;           // Start playback from this point in the source (default: 0)
   volume?: number;            // Volume multiplier (default: 0.2 — quieter than main audio)
   loop?: boolean;             // Loop the track to fill the entire video duration (default: false)

package/src/schema/modules/subtitle.js

@@ -7,7 +7,8 @@ module.exports = {
   type: "subtitle";           // Required: clip type identifier
   url: string;                // Required: path to subtitle file (.srt, .vtt, .ass, .ssa)
   position?: number;          // Timeline offset — shifts all subtitle timestamps forward (default: 0)
-  end?: number;               // Optional end time to cut off subtitles
+  end?: number;               // Optional end time to cut off subtitles. Use end OR duration, not both.
+  duration?: number;          // Duration in seconds (alternative to end). end = position + duration.
 
   // Styling (applies to SRT/VTT imports — ASS/SSA files use their own embedded styles)
   fontFamily?: string;        // Font family (default: "Sans")

package/src/schema/modules/text.js

@@ -6,7 +6,8 @@ module.exports = {
   schema: `{
   type: "text";                   // Required: clip type identifier
   position: number;               // Required: start time on timeline (seconds)
-  end: number;                    // Required: end time on timeline (seconds)
+  end?: number;                   // End time on timeline (seconds). Use end OR duration, not both.
+  duration?: number;              // Duration in seconds (alternative to end). end = position + duration.
 
   // Content
   text?: string;                  // Text content (required for "static" mode)
@@ -111,6 +112,7 @@ module.exports = {
     },
   ],
   notes: [
+    "Use duration instead of end to specify how long the text appears: end = position + duration. Cannot use both.",
     "If no position is specified (xPercent/yPercent/x/y), text defaults to center of the screen.",
     "For karaoke mode, provide the words array with per-word start/end times.",
     "For word-replace and word-sequential, you can use either words[] or wordTimestamps[] (paired with a space-separated text string).",