simple-ffmpegjs 0.3.2 → 0.3.4

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)
@@ -298,6 +299,139 @@ 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
+```
+
+#### `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.
@@ -329,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)                      |
@@ -353,8 +488,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 +508,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 +549,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 +562,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 +740,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 +748,38 @@ 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}%`);
+  }
+}
+```
+
+### 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:
@@ -615,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             | -                                                                           |
 
@@ -632,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") {
@@ -700,31 +873,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 +1109,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.4",
   "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/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 };