simple-ffmpegjs 0.3.2 → 0.3.3

package/README.md

@@ -298,6 +298,98 @@ Load clip descriptors into the project. Validates the timeline and reads media m
 await project.load(clips: Clip[]): Promise<void[]>
 ```
 
+#### `SIMPLEFFMPEG.getDuration(clips)`
+
+Calculate the total visual timeline duration from a clips array. Handles `duration` and auto-sequencing shorthand, and subtracts transition overlaps. Pure function — no file I/O.
+
+```ts
+const clips = [
+  { type: "video", url: "./a.mp4", duration: 5 },
+  {
+    type: "video",
+    url: "./b.mp4",
+    duration: 10,
+    transition: { type: "fade", duration: 0.5 },
+  },
+];
+SIMPLEFFMPEG.getDuration(clips); // 14.5
+```
+
+Useful for computing text overlay timings or background music end times before calling `load()`.
+
+**Duration and Auto-Sequencing:**
+
+For video, image, and audio clips, you can use shorthand to avoid specifying explicit `position` and `end` values:
+
+- **`duration`** — Use instead of `end`. The library computes `end = position + duration`. You cannot specify both `duration` and `end` on the same clip.
+- **Omit `position`** — The clip is placed immediately after the previous clip on its track. Video and image clips share the visual track; audio clips have their own track. The first clip defaults to `position: 0`.
+
+These can be combined:
+
+```ts
+// Before: manual position/end for every clip
+await project.load([
+  { type: "video", url: "./a.mp4", position: 0, end: 5 },
+  { type: "video", url: "./b.mp4", position: 5, end: 10 },
+  { type: "video", url: "./c.mp4", position: 10, end: 18, cutFrom: 3 },
+]);
+
+// After: auto-sequencing + duration
+await project.load([
+  { type: "video", url: "./a.mp4", duration: 5 },
+  { type: "video", url: "./b.mp4", duration: 5 },
+  { type: "video", url: "./c.mp4", duration: 8, cutFrom: 3 },
+]);
+```
+
+You can mix explicit and implicit positioning freely. Clips with explicit `position` are placed there; subsequent auto-sequenced clips follow from the last clip's end:
+
+```ts
+await project.load([
+  { type: "video", url: "./a.mp4", duration: 5 }, // position: 0, end: 5
+  { type: "video", url: "./b.mp4", position: 10, end: 15 }, // explicit gap
+  { type: "video", url: "./c.mp4", duration: 5 }, // position: 15, end: 20
+]);
+```
+
+Text clips always require an explicit `position` (they're overlays on specific moments). Background music and subtitle clips already have optional `position`/`end` with their own defaults.
+
+#### `SIMPLEFFMPEG.probe(filePath)`
+
+Probe a media file and return comprehensive metadata using ffprobe. Works with video, audio, and image files.
+
+```ts
+const info = await SIMPLEFFMPEG.probe("./video.mp4");
+// {
+//   duration: 30.5,         // seconds
+//   width: 1920,            // pixels
+//   height: 1080,           // pixels
+//   hasVideo: true,
+//   hasAudio: true,
+//   rotation: 0,            // iPhone/mobile rotation
+//   videoCodec: "h264",
+//   audioCodec: "aac",
+//   format: "mov,mp4,m4a,3gp,3g2,mj2",
+//   fps: 30,
+//   size: 15728640,         // bytes
+//   bitrate: 4125000,       // bits/sec
+//   sampleRate: 48000,      // Hz
+//   channels: 2             // stereo
+// }
+```
+
+Fields that don't apply to the file type are `null` (e.g. `width`/`height`/`videoCodec`/`fps` for audio-only files, `audioCodec`/`sampleRate`/`channels` for video-only files).
+
+Throws `MediaNotFoundError` if the file cannot be found or probed.
+
+```ts
+// Audio file
+const audio = await SIMPLEFFMPEG.probe("./music.wav");
+console.log(audio.hasVideo); // false
+console.log(audio.duration); // 180.5
+console.log(audio.sampleRate); // 44100
+```
+
 #### `project.export(options)`
 
 Build and execute the FFmpeg command to render the final video.
@@ -353,8 +445,9 @@ await project.preview(options?: ExportOptions): Promise<{
 {
   type: "video";
   url: string;              // File path
-  position: number;         // Timeline start (seconds)
-  end: number;              // Timeline end (seconds)
+  position?: number;        // Timeline start (seconds). Omit to auto-sequence after previous clip.
+  end?: number;             // Timeline end (seconds). Use end OR duration, not both.
+  duration?: number;        // Duration in seconds (alternative to end). end = position + duration.
   cutFrom?: number;         // Source offset (default: 0)
   volume?: number;          // Audio volume (default: 1)
   transition?: {
@@ -372,8 +465,9 @@ All [xfade transitions](https://trac.ffmpeg.org/wiki/Xfade) are supported.
 {
   type: "audio";
   url: string;
-  position: number;
-  end: number;
+  position?: number;        // Omit to auto-sequence after previous audio clip
+  end?: number;             // Use end OR duration, not both
+  duration?: number;        // Duration in seconds (alternative to end)
   cutFrom?: number;
   volume?: number;
 }
@@ -412,8 +506,9 @@ await project.load([
 {
   type: "image";
   url: string;
-  position: number;
-  end: number;
+  position?: number;        // Omit to auto-sequence after previous video/image clip
+  end?: number;             // Use end OR duration, not both
+  duration?: number;        // Duration in seconds (alternative to end)
   kenBurns?: "zoom-in" | "zoom-out" | "pan-left" | "pan-right" | "pan-up" | "pan-down";
 }
 ```
@@ -424,7 +519,8 @@ await project.load([
 {
   type: "text";
   position: number;
-  end: number;
+  end?: number;             // Use end OR duration, not both
+  duration?: number;        // Duration in seconds (alternative to end)
 
   // Content
   text?: string;
@@ -601,6 +697,7 @@ The `onProgress` callback receives:
 ```ts
 {
   percent?: number;         // 0-100
+  phase?: string;           // "rendering" or "batching"
   timeProcessed?: number;   // Seconds processed
   frame?: number;           // Current frame
   fps?: number;             // Processing speed
@@ -608,6 +705,23 @@ The `onProgress` callback receives:
 }
 ```
 
+The `phase` field indicates what the export is doing:
+
+- `"rendering"` — main video export (includes `percent`, `frame`, etc.)
+- `"batching"` — text overlay passes are running (fired once when batching starts)
+
+Use `phase` to update your UI when the export hits 100% but still has work to do:
+
+```ts
+onProgress: ({ percent, phase }) => {
+  if (phase === "batching") {
+    console.log("Applying text overlays...");
+  } else {
+    console.log(`${percent}%`);
+  }
+}
+```
+
 ### Error Handling
 
 The library provides custom error classes for structured error handling:
@@ -700,31 +814,15 @@ await project.load([
 
 ```ts
 await project.load([
-  {
-    type: "image",
-    url: "./photo1.jpg",
-    position: 0,
-    end: 3,
-    kenBurns: "zoom-in",
-  },
-  {
-    type: "image",
-    url: "./photo2.jpg",
-    position: 3,
-    end: 6,
-    kenBurns: "pan-right",
-  },
-  {
-    type: "image",
-    url: "./photo3.jpg",
-    position: 6,
-    end: 9,
-    kenBurns: "zoom-out",
-  },
+  { 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" },
   { type: "music", url: "./music.mp3", volume: 0.3 },
 ]);
 ```
 
+When `position` is omitted, clips are placed sequentially — each one starts where the previous one ended. `duration` is an alternative to `end`: the library computes `end = position + duration`. The explicit form (`position: 0, end: 3`) still works identically.
+
 > **Note:** Ken Burns effects work best with images at least as large as your output resolution. Smaller images are automatically upscaled (with a validation warning). Use `strictKenBurns: true` in validation options to enforce size requirements instead.
 
 ### Text & Animations
@@ -952,16 +1050,19 @@ async function generateListingVideo(listing, outputPath) {
   const photos = listing.photos; // ['kitchen.jpg', 'living-room.jpg', ...]
   const slideDuration = 4;
 
-  // Build an image slideshow from listing photos
+  // Build an image slideshow from listing photos (auto-sequenced with crossfades)
+  const transitionDuration = 0.5;
   const photoClips = photos.map((photo, i) => ({
     type: "image",
     url: photo,
-    position: i * slideDuration,
-    end: (i + 1) * slideDuration,
+    duration: slideDuration,
     kenBurns: i % 2 === 0 ? "zoom-in" : "pan-right",
+    ...(i > 0 && {
+      transition: { type: "fade", duration: transitionDuration },
+    }),
   }));
 
-  const totalDuration = photos.length * slideDuration;
+  const totalDuration = SIMPLEFFMPEG.getDuration(photoClips);
 
   const clips = [
     ...photoClips,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simple-ffmpegjs",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "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/media_info.js

@@ -57,101 +57,138 @@ function runFFprobe(args, timeoutMs = DEFAULT_FFPROBE_TIMEOUT_MS) {
 }
 
 /**
- * Get video metadata using ffprobe
- * @param {string} url - Path to the video file
- * @returns {Promise<{iphoneRotation: number, hasAudio: boolean, width: number|null, height: number|null, durationSec: number|null}>}
- * @throws {MediaNotFoundError} If the file cannot be probed
+ * Parse a fraction string like "30000/1001" or "30/1" into a number.
+ * Returns null if the input is not a valid fraction.
+ * @param {string} fraction
+ * @returns {number|null}
  */
-function getVideoMetadata(url) {
-  return runFFprobe([
-    "-v",
-    "error",
-    "-show_streams",
-    "-show_format",
-    "-of",
-    "json",
-    url,
-  ])
-    .then((stdout) => {
-      let metadata;
-      try {
-        metadata = JSON.parse(stdout);
-      } catch (parseError) {
-        throw new Error(
-          `Invalid JSON response from ffprobe: ${parseError.message}`
-        );
-      }
-
-      // Validate metadata structure
-      if (!metadata || !Array.isArray(metadata.streams)) {
-        throw new Error(
-          "Invalid metadata structure: missing or invalid 'streams' array"
-        );
-      }
-
-      const videoStream = metadata.streams.find(
-        (s) => s.codec_type === "video"
-      );
-      const hasAudio = metadata.streams.some((s) => s.codec_type === "audio");
-      const iphoneRotation = videoStream?.side_data_list?.[0]?.rotation
-        ? videoStream.side_data_list[0].rotation
-        : 0;
-      const formatDuration = metadata.format?.duration
-        ? parseFloat(metadata.format.duration)
-        : null;
-      const streamDuration = videoStream?.duration
-        ? parseFloat(videoStream.duration)
-        : null;
-      const durationSec = Number.isFinite(formatDuration)
-        ? formatDuration
-        : Number.isFinite(streamDuration)
-        ? streamDuration
-        : null;
-      return {
-        iphoneRotation,
-        hasAudio,
-        width: videoStream?.width,
-        height: videoStream?.height,
-        durationSec,
-      };
-    })
-    .catch((error) => {
-      throw new MediaNotFoundError(
-        `Failed to get video metadata for "${url}": ${error.message}`,
-        { path: url }
-      );
-    });
+function parseFraction(fraction) {
+  if (!fraction || typeof fraction !== "string") return null;
+  const parts = fraction.split("/");
+  if (parts.length !== 2) return null;
+  const num = parseFloat(parts[0]);
+  const den = parseFloat(parts[1]);
+  if (!Number.isFinite(num) || !Number.isFinite(den) || den === 0) return null;
+  const result = num / den;
+  return Number.isFinite(result) ? result : null;
 }
 
 /**
- * Get media duration using ffprobe
- * @param {string} url - Path to the media file
- * @returns {Promise<number|null>} Duration in seconds, or null if unavailable
+ * Probe a media file and return comprehensive metadata.
+ *
+ * Returns a flat, user-friendly object with duration, dimensions, codecs,
+ * format, bitrate, audio details, and rotation info. All fields that are
+ * not applicable (e.g. width/height for audio-only files) are set to null.
+ *
+ * @param {string} filePath - Path to the media file
+ * @returns {Promise<{
+ *   duration: number|null,
+ *   width: number|null,
+ *   height: number|null,
+ *   hasVideo: boolean,
+ *   hasAudio: boolean,
+ *   rotation: number,
+ *   videoCodec: string|null,
+ *   audioCodec: string|null,
+ *   format: string|null,
+ *   fps: number|null,
+ *   size: number|null,
+ *   bitrate: number|null,
+ *   sampleRate: number|null,
+ *   channels: number|null
+ * }>}
  * @throws {MediaNotFoundError} If the file cannot be probed
  */
-function getMediaDuration(url) {
-  return runFFprobe(["-v", "error", "-show_format", "-of", "json", url])
-    .then((stdout) => {
-      let metadata;
-      try {
-        metadata = JSON.parse(stdout);
-      } catch (parseError) {
-        throw new Error(
-          `Invalid JSON response from ffprobe: ${parseError.message}`
-        );
-      }
-
-      const formatDuration = metadata?.format?.duration
-        ? parseFloat(metadata.format.duration)
-        : null;
-      return Number.isFinite(formatDuration) ? formatDuration : null;
-    })
-    .catch((error) => {
-      throw new MediaNotFoundError(
-        `Failed to get media duration for "${url}": ${error.message}`,
-        { path: url }
-      );
-    });
+async function probeMedia(filePath) {
+  let stdout;
+  try {
+    stdout = await runFFprobe([
+      "-v",
+      "error",
+      "-show_streams",
+      "-show_format",
+      "-of",
+      "json",
+      filePath,
+    ]);
+  } catch (error) {
+    throw new MediaNotFoundError(
+      `Failed to probe "${filePath}": ${error.message}`,
+      { path: filePath }
+    );
+  }
+
+  let metadata;
+  try {
+    metadata = JSON.parse(stdout);
+  } catch (parseError) {
+    throw new MediaNotFoundError(
+      `Invalid JSON response from ffprobe for "${filePath}": ${parseError.message}`,
+      { path: filePath }
+    );
+  }
+
+  if (!metadata || !Array.isArray(metadata.streams)) {
+    throw new MediaNotFoundError(
+      `Invalid metadata structure for "${filePath}": missing or invalid 'streams' array`,
+      { path: filePath }
+    );
+  }
+
+  const videoStream = metadata.streams.find((s) => s.codec_type === "video");
+  const audioStream = metadata.streams.find((s) => s.codec_type === "audio");
+  const format = metadata.format || {};
+
+  // ── Duration ────────────────────────────────────────────────────────────
+  const formatDuration = format.duration ? parseFloat(format.duration) : null;
+  const streamDuration = videoStream?.duration
+    ? parseFloat(videoStream.duration)
+    : null;
+  const duration = Number.isFinite(formatDuration)
+    ? formatDuration
+    : Number.isFinite(streamDuration)
+    ? streamDuration
+    : null;
+
+  // ── FPS ─────────────────────────────────────────────────────────────────
+  // Prefer avg_frame_rate, fall back to r_frame_rate
+  const fps =
+    parseFraction(videoStream?.avg_frame_rate) ??
+    parseFraction(videoStream?.r_frame_rate) ??
+    null;
+
+  // ── Rotation ────────────────────────────────────────────────────────────
+  const rotation = videoStream?.side_data_list?.[0]?.rotation
+    ? videoStream.side_data_list[0].rotation
+    : 0;
+
+  // ── Size & bitrate ─────────────────────────────────────────────────────
+  const size = format.size ? parseInt(format.size, 10) : null;
+  const bitrate = format.bit_rate ? parseInt(format.bit_rate, 10) : null;
+
+  // ── Audio details ──────────────────────────────────────────────────────
+  const sampleRate = audioStream?.sample_rate
+    ? parseInt(audioStream.sample_rate, 10)
+    : null;
+  const channels =
+    typeof audioStream?.channels === "number" ? audioStream.channels : null;
+
+  return {
+    duration,
+    width: videoStream?.width ?? null,
+    height: videoStream?.height ?? null,
+    hasVideo: !!videoStream,
+    hasAudio: !!audioStream,
+    rotation,
+    videoCodec: videoStream?.codec_name ?? null,
+    audioCodec: audioStream?.codec_name ?? null,
+    format: format.format_name ?? null,
+    fps: Number.isFinite(fps) ? Math.round(fps * 100) / 100 : null,
+    size: Number.isFinite(size) ? size : null,
+    bitrate: Number.isFinite(bitrate) ? bitrate : null,
+    sampleRate: Number.isFinite(sampleRate) ? sampleRate : null,
+    channels,
+  };
 }
 
-module.exports = { getVideoMetadata, getMediaDuration };
+module.exports = { probeMedia };

package/src/core/resolve.js

@@ -0,0 +1,96 @@
+/**
+ * Clip resolution — transforms shorthand clip properties into canonical form.
+ *
+ * This runs BEFORE validation, so the rest of the pipeline always sees
+ * standard { position, end } clips. Two features are handled here:
+ *
+ * 1. **duration → end**: If a clip has `duration` instead of `end`,
+ *    compute `end = position + duration`.
+ *
+ * 2. **Auto-sequential positioning**: If a video/image/audio clip omits
+ *    `position`, it is placed immediately after the previous clip on the
+ *    same track (visual or audio). The first clip defaults to position 0.
+ *
+ * Clips are shallow-cloned — the caller's original objects are not mutated.
+ */
+
+/**
+ * Types that auto-sequence on the visual track (video + image share a timeline).
+ */
+const VISUAL_TYPES = ["video", "image"];
+
+/**
+ * Types that auto-sequence on the audio track.
+ */
+const AUDIO_TYPES = ["audio"];
+
+/**
+ * All types eligible for auto-sequencing (position can be omitted).
+ */
+const AUTO_SEQUENCE_TYPES = [...VISUAL_TYPES, ...AUDIO_TYPES];
+
+/**
+ * Resolve shorthand clip properties into canonical { position, end } form.
+ *
+ * @param {Array} clips - Array of clip objects (not mutated)
+ * @returns {{ clips: Array, errors: Array }} Resolved clips and any resolution errors
+ */
+function resolveClips(clips) {
+  if (!Array.isArray(clips)) {
+    return { clips, errors: [] };
+  }
+
+  const errors = [];
+  let lastVisualEnd = 0;
+  let lastAudioEnd = 0;
+
+  const resolved = clips.map((clip, index) => {
+    const c = { ...clip };
+    const path = `clips[${index}]`;
+
+    // ── Conflict check: duration + end ──────────────────────────────────
+    if (c.duration != null && c.end != null) {
+      errors.push({
+        code: "INVALID_VALUE",
+        path: `${path}`,
+        message:
+          "Cannot specify both 'duration' and 'end'. Use one or the other.",
+        received: { duration: c.duration, end: c.end },
+      });
+      // Don't resolve further — let validation report the canonical errors
+      return c;
+    }
+
+    // ── Auto-sequential positioning ─────────────────────────────────────
+    const isVisual = VISUAL_TYPES.includes(c.type);
+    const isAudio = AUDIO_TYPES.includes(c.type);
+    const canAutoSequence = AUTO_SEQUENCE_TYPES.includes(c.type);
+
+    if (canAutoSequence && c.position == null) {
+      c.position = isVisual ? lastVisualEnd : lastAudioEnd;
+    }
+
+    // ── Duration → end ──────────────────────────────────────────────────
+    if (c.duration != null && c.end == null) {
+      if (typeof c.position === "number" && typeof c.duration === "number") {
+        c.end = c.position + c.duration;
+      }
+      // Remove duration so the rest of the pipeline sees canonical { position, end }
+      delete c.duration;
+    }
+
+    // ── Track the end of the last clip on each track ────────────────────
+    if (isVisual && typeof c.end === "number") {
+      lastVisualEnd = c.end;
+    }
+    if (isAudio && typeof c.end === "number") {
+      lastAudioEnd = c.end;
+    }
+
+    return c;
+  });
+
+  return { clips: resolved, errors };
+}
+
+module.exports = { resolveClips };

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/lib/utils.js

@@ -126,6 +126,7 @@ function runFFmpeg({ command, totalDuration = 0, onProgress, signal }) {
       if (onProgress && typeof onProgress === "function") {
         const progress = parseFFmpegProgress(chunk, totalDuration);
         if (Object.keys(progress).length > 0) {
+          progress.phase = "rendering";
           onProgress(progress);
         }
       }

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).",

package/src/schema/modules/video.js

@@ -6,8 +6,9 @@ module.exports = {
   schema: `{
   type: "video";              // Required: clip type identifier
   url: string;                // Required: path to video 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 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;           // Trim: start playback from this point in the source (default: 0)
   volume?: number;            // Audio volume multiplier (default: 1, 0 = mute, >1 = amplify)
   transition?: {              // Crossfade transition INTO this clip from the previous one
@@ -70,11 +71,20 @@ module.exports = {
 ]`,
     },
     {
-      label: "Trim source video (use 10s-20s of the file)",
-      code: `{ type: "video", url: "long-clip.mp4", position: 0, end: 10, cutFrom: 10 }`,
+      label: "Auto-sequenced clips using duration",
+      code: `[
+  { type: "video", url: "intro.mp4", duration: 5 },
+  { type: "video", url: "main.mp4", duration: 10 }
+]`,
+    },
+    {
+      label: "Trim source video (use 10s starting at the 10s mark)",
+      code: `{ type: "video", url: "long-clip.mp4", cutFrom: 10, duration: 10 }`,
     },
   ],
   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 clip appears: end = position + duration. Cannot use both.",
     "Transitions overlap clips: a 0.5s fade means clip B's position should start 0.5s before clip A's end.",
     "The first clip in the timeline cannot have a transition (there's nothing to transition from).",
     "The total video duration is shortened by the sum of all transition durations.",

package/src/simpleffmpeg.js

@@ -41,6 +41,8 @@ const {
   buildASSFilter,
 } = require("./ffmpeg/subtitle_builder");
 const { getSchema, getSchemaModules } = require("./schema");
+const { resolveClips } = require("./core/resolve");
+const { probeMedia } = require("./core/media_info");
 
 class SIMPLEFFMPEG {
   /**
@@ -215,12 +217,20 @@ class SIMPLEFFMPEG {
     this._isLoading = true;
 
     try {
-      const result = validateConfig(clipObjs, {
+      // Resolve shorthand: duration → end, auto-sequential positioning
+      const resolved = resolveClips(clipObjs);
+
+      // Merge resolution errors into validation
+      const result = validateConfig(resolved.clips, {
         fillGaps: this.options.fillGaps,
         width: this.options.width,
         height: this.options.height,
       });
 
+      // Prepend resolution errors (e.g. duration+end conflict)
+      result.errors.unshift(...resolved.errors);
+      result.valid = result.valid && resolved.errors.length === 0;
+
       if (!result.valid) {
         throw new ValidationError(formatValidationResult(result), {
           errors: result.errors,
@@ -236,8 +246,11 @@ class SIMPLEFFMPEG {
         result.warnings.forEach((w) => console.warn(`${w.path}: ${w.message}`));
       }
 
+      // Use resolved clips (with position/end computed) for loading
+      const resolvedClips = resolved.clips;
+
       await Promise.all(
-        clipObjs.map((clipObj) => {
+        resolvedClips.map((clipObj) => {
           if (clipObj.type === "video" || clipObj.type === "audio") {
             clipObj.volume = clipObj.volume || 1;
             clipObj.cutFrom = clipObj.cutFrom || 0;
@@ -991,6 +1004,9 @@ class SIMPLEFFMPEG {
       // Handle multi-pass text overlays if needed
       let passes = 0;
       if (needTextPasses) {
+        if (onProgress && typeof onProgress === "function") {
+          onProgress({ phase: "batching" });
+        }
         const {
           finalPath,
           tempOutputs,
@@ -1099,7 +1115,100 @@ class SIMPLEFFMPEG {
    * }
    */
   static validate(clips, options = {}) {
-    return validateConfig(clips, options);
+    // Resolve shorthand (duration, auto-sequencing) before validation
+    const resolved = resolveClips(clips);
+    const result = validateConfig(resolved.clips, options);
+
+    // Merge resolution errors
+    result.errors.unshift(...resolved.errors);
+    result.valid = result.valid && resolved.errors.length === 0;
+
+    return result;
+  }
+
+  /**
+   * Calculate the total duration of a clips configuration.
+   * Resolves shorthand (duration, auto-sequencing) before computing.
+   * Returns the visual timeline duration: sum of video/image clip durations
+   * minus transition overlaps.
+   *
+   * This is a pure function — same clips always produce the same result.
+   * No file I/O is performed.
+   *
+   * @param {Array} clips - Array of clip objects
+   * @returns {number} Total duration in seconds
+   *
+   * @example
+   * const duration = SIMPLEFFMPEG.getDuration([
+   *   { type: "video", url: "./a.mp4", duration: 5 },
+   *   { type: "video", url: "./b.mp4", duration: 10, transition: { type: "fade", duration: 0.5 } },
+   * ]);
+   * // duration === 14.5 (15 - 0.5 transition overlap)
+   */
+  static getDuration(clips) {
+    if (!Array.isArray(clips) || clips.length === 0) return 0;
+
+    // Resolve shorthand (duration → end, auto-sequencing)
+    const { clips: resolved } = resolveClips(clips);
+
+    // Filter to visual clips (video + image)
+    const visual = resolved.filter(
+      (c) => c.type === "video" || c.type === "image"
+    );
+
+    if (visual.length === 0) return 0;
+
+    const baseSum = visual.reduce(
+      (acc, c) => acc + Math.max(0, (c.end || 0) - (c.position || 0)),
+      0
+    );
+
+    const transitionsOverlap = visual.reduce((acc, c) => {
+      const d =
+        c.transition && typeof c.transition.duration === "number"
+          ? c.transition.duration
+          : 0;
+      return acc + d;
+    }, 0);
+
+    return Math.max(0, baseSum - transitionsOverlap);
+  }
+
+  /**
+   * Probe a media file and return comprehensive metadata.
+   *
+   * Uses ffprobe to extract duration, dimensions, codecs, format,
+   * bitrate, audio details, and rotation info from any media file
+   * (video, audio, or image).
+   *
+   * @param {string} filePath - Path to the media file
+   * @returns {Promise<Object>} Media info object with:
+   *   - duration (number|null) — total duration in seconds
+   *   - width (number|null) — video width in pixels
+   *   - height (number|null) — video height in pixels
+   *   - hasVideo (boolean) — true if file contains a video stream
+   *   - hasAudio (boolean) — true if file contains an audio stream
+   *   - rotation (number) — iPhone/mobile rotation value (0 if none)
+   *   - videoCodec (string|null) — e.g. "h264", "hevc", "vp9"
+   *   - audioCodec (string|null) — e.g. "aac", "mp3"
+   *   - format (string|null) — container format, e.g. "mov,mp4,m4a,3gp,3g2,mj2"
+   *   - fps (number|null) — frames per second
+   *   - size (number|null) — file size in bytes
+   *   - bitrate (number|null) — overall bitrate in bits/sec
+   *   - sampleRate (number|null) — audio sample rate, e.g. 48000
+   *   - channels (number|null) — audio channels (1=mono, 2=stereo)
+   * @throws {MediaNotFoundError} If the file cannot be found or probed
+   *
+   * @example
+   * const info = await SIMPLEFFMPEG.probe("./video.mp4");
+   * console.log(info.duration);   // 30.5
+   * console.log(info.width);      // 1920
+   * console.log(info.height);     // 1080
+   * console.log(info.videoCodec); // "h264"
+   * console.log(info.hasAudio);   // true
+   */
+  static async probe(filePath) {
+    return probeMedia(filePath);
   }
 
   /**

package/types/index.d.mts

@@ -50,8 +50,12 @@ declare namespace SIMPLEFFMPEG {
   interface BaseClip {
     type: ClipType;
     url?: string;
-    position: number;
-    end: number;
+    /** Start time on timeline in seconds. For video/image/audio: omit to auto-sequence after the previous clip. */
+    position?: number;
+    /** End time on timeline in seconds. Mutually exclusive with duration. */
+    end?: number;
+    /** Duration in seconds (alternative to end). Computes end = position + duration. Mutually exclusive with end. */
+    duration?: number;
   }
 
   interface VideoClip extends BaseClip {
@@ -307,6 +311,8 @@ declare namespace SIMPLEFFMPEG {
     bitrate?: number;
     /** Current output size in bytes */
     size?: number;
+    /** Export phase: "rendering" during main export, "batching" during text overlay passes */
+    phase?: "rendering" | "batching";
   }
 
   /** Metadata to embed in output file */
@@ -530,6 +536,42 @@ declare namespace SIMPLEFFMPEG {
     /** Total expected duration in seconds */
     totalDuration: number;
   }
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Media Info (probe)
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  /** Result from SIMPLEFFMPEG.probe() — comprehensive media file metadata */
+  interface MediaInfo {
+    /** Total duration in seconds */
+    duration: number | null;
+    /** Video width in pixels (null for audio-only files) */
+    width: number | null;
+    /** Video height in pixels (null for audio-only files) */
+    height: number | null;
+    /** Whether the file contains a video stream */
+    hasVideo: boolean;
+    /** Whether the file contains an audio stream */
+    hasAudio: boolean;
+    /** iPhone/mobile rotation value in degrees (0 if none) */
+    rotation: number;
+    /** Video codec name, e.g. "h264", "hevc", "vp9" (null if no video) */
+    videoCodec: string | null;
+    /** Audio codec name, e.g. "aac", "mp3", "pcm_s16le" (null if no audio) */
+    audioCodec: string | null;
+    /** Container format name, e.g. "mov,mp4,m4a,3gp,3g2,mj2" */
+    format: string | null;
+    /** Frames per second (null for non-video files) */
+    fps: number | null;
+    /** File size in bytes */
+    size: number | null;
+    /** Overall bitrate in bits per second */
+    bitrate: number | null;
+    /** Audio sample rate in Hz, e.g. 48000, 44100 (null if no audio) */
+    sampleRate: number | null;
+    /** Number of audio channels (1=mono, 2=stereo) (null if no audio) */
+    channels: number | null;
+  }
 }
 
 declare class SIMPLEFFMPEG {
@@ -587,6 +629,47 @@ declare class SIMPLEFFMPEG {
     options?: SIMPLEFFMPEG.ValidateOptions
   ): SIMPLEFFMPEG.ValidationResult;
 
+  /**
+   * Calculate the total duration of a clips configuration.
+   * Resolves shorthand (duration, auto-sequencing) before computing.
+   * Returns the visual timeline duration: sum of video/image clip durations
+   * minus transition overlaps.
+   *
+   * Pure function — same clips always produce the same result. No file I/O.
+   *
+   * @param clips - Array of clip objects
+   * @returns Total duration in seconds
+   *
+   * @example
+   * const duration = SIMPLEFFMPEG.getDuration([
+   *   { type: "video", url: "./a.mp4", duration: 5 },
+   *   { type: "video", url: "./b.mp4", duration: 10,
+   *     transition: { type: "fade", duration: 0.5 } },
+   * ]);
+   * // duration === 14.5
+   */
+  static getDuration(clips: SIMPLEFFMPEG.Clip[]): number;
+
+  /**
+   * Probe a media file and return comprehensive metadata.
+   *
+   * Uses ffprobe to extract duration, dimensions, codecs, format,
+   * bitrate, audio details, and rotation info from any media file.
+   *
+   * @param filePath - Path to the media file
+   * @returns Media info object
+   * @throws {SIMPLEFFMPEG.MediaNotFoundError} If the file cannot be found or probed
+   *
+   * @example
+   * const info = await SIMPLEFFMPEG.probe("./video.mp4");
+   * console.log(info.duration);   // 30.5
+   * console.log(info.width);      // 1920
+   * console.log(info.height);     // 1080
+   * console.log(info.videoCodec); // "h264"
+   * console.log(info.hasAudio);   // true
+   */
+  static probe(filePath: string): Promise<SIMPLEFFMPEG.MediaInfo>;
+
   /**
    * Format validation result as human-readable string
    */

package/types/index.d.ts

@@ -50,8 +50,12 @@ declare namespace SIMPLEFFMPEG {
   interface BaseClip {
     type: ClipType;
     url?: string;
-    position: number;
-    end: number;
+    /** Start time on timeline in seconds. For video/image/audio: omit to auto-sequence after the previous clip. */
+    position?: number;
+    /** End time on timeline in seconds. Mutually exclusive with duration. */
+    end?: number;
+    /** Duration in seconds (alternative to end). Computes end = position + duration. Mutually exclusive with end. */
+    duration?: number;
   }
 
   interface VideoClip extends BaseClip {
@@ -307,6 +311,8 @@ declare namespace SIMPLEFFMPEG {
     bitrate?: number;
     /** Current output size in bytes */
     size?: number;
+    /** Export phase: "rendering" during main export, "batching" during text overlay passes */
+    phase?: "rendering" | "batching";
   }
 
   /** Metadata to embed in output file */
@@ -627,6 +633,42 @@ declare namespace SIMPLEFFMPEG {
     /** Total expected duration in seconds */
     totalDuration: number;
   }
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Media Info (probe)
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  /** Result from SIMPLEFFMPEG.probe() — comprehensive media file metadata */
+  interface MediaInfo {
+    /** Total duration in seconds */
+    duration: number | null;
+    /** Video width in pixels (null for audio-only files) */
+    width: number | null;
+    /** Video height in pixels (null for audio-only files) */
+    height: number | null;
+    /** Whether the file contains a video stream */
+    hasVideo: boolean;
+    /** Whether the file contains an audio stream */
+    hasAudio: boolean;
+    /** iPhone/mobile rotation value in degrees (0 if none) */
+    rotation: number;
+    /** Video codec name, e.g. "h264", "hevc", "vp9" (null if no video) */
+    videoCodec: string | null;
+    /** Audio codec name, e.g. "aac", "mp3", "pcm_s16le" (null if no audio) */
+    audioCodec: string | null;
+    /** Container format name, e.g. "mov,mp4,m4a,3gp,3g2,mj2" */
+    format: string | null;
+    /** Frames per second (null for non-video files) */
+    fps: number | null;
+    /** File size in bytes */
+    size: number | null;
+    /** Overall bitrate in bits per second */
+    bitrate: number | null;
+    /** Audio sample rate in Hz, e.g. 48000, 44100 (null if no audio) */
+    sampleRate: number | null;
+    /** Number of audio channels (1=mono, 2=stereo) (null if no audio) */
+    channels: number | null;
+  }
 }
 
 declare class SIMPLEFFMPEG {
@@ -686,6 +728,47 @@ declare class SIMPLEFFMPEG {
     options?: SIMPLEFFMPEG.ValidateOptions
   ): SIMPLEFFMPEG.ValidationResult;
 
+  /**
+   * Calculate the total duration of a clips configuration.
+   * Resolves shorthand (duration, auto-sequencing) before computing.
+   * Returns the visual timeline duration: sum of video/image clip durations
+   * minus transition overlaps.
+   *
+   * Pure function — same clips always produce the same result. No file I/O.
+   *
+   * @param clips - Array of clip objects
+   * @returns Total duration in seconds
+   *
+   * @example
+   * const duration = SIMPLEFFMPEG.getDuration([
+   *   { type: "video", url: "./a.mp4", duration: 5 },
+   *   { type: "video", url: "./b.mp4", duration: 10,
+   *     transition: { type: "fade", duration: 0.5 } },
+   * ]);
+   * // duration === 14.5
+   */
+  static getDuration(clips: SIMPLEFFMPEG.Clip[]): number;
+
+  /**
+   * Probe a media file and return comprehensive metadata.
+   *
+   * Uses ffprobe to extract duration, dimensions, codecs, format,
+   * bitrate, audio details, and rotation info from any media file.
+   *
+   * @param filePath - Path to the media file
+   * @returns Media info object
+   * @throws {SIMPLEFFMPEG.MediaNotFoundError} If the file cannot be found or probed
+   *
+   * @example
+   * const info = await SIMPLEFFMPEG.probe("./video.mp4");
+   * console.log(info.duration);   // 30.5
+   * console.log(info.width);      // 1920
+   * console.log(info.height);     // 1080
+   * console.log(info.videoCodec); // "h264"
+   * console.log(info.hasAudio);   // true
+   */
+  static probe(filePath: string): Promise<SIMPLEFFMPEG.MediaInfo>;
+
   /**
    * Format validation result as human-readable string
    */