@lumy-pack/scene-sieve 0.0.6 → 0.0.7

package/README.md

@@ -13,6 +13,8 @@ Video/GIF ──▶ Extract (FFmpeg) ──▶ Analyze (OpenCV) ──▶ Prune
 
 ## Features
 
+- **Animation Tracking** — Detects and records loading spinners or other repetitive animations
+- **Rich Metadata** — Generates `.metadata.json` with scene timestamps and animation details
 - **Smart frame selection** — Identifies visually significant scene changes, not just evenly-spaced samples
 - **Computer vision pipeline** — AKAZE feature detection, DBSCAN clustering, IoU tracking, and information gain scoring
 - **Three input modes** — File path, video Buffer, or pre-extracted frame Buffers
@@ -35,7 +37,7 @@ yarn add @lumy-pack/scene-sieve
 ### CLI
 
 ```bash
-# Extract 5 key scenes (default)
+# Extract 20 key scenes (default)
 npx scene-sieve input.mp4
 
 # Keep exactly 8 scenes
@@ -44,8 +46,8 @@ npx scene-sieve input.mp4 -n 8
 # Use threshold-based selection
 npx scene-sieve input.mp4 -t 0.3
 
-# Specify output directory and JPEG quality
-npx scene-sieve input.mp4 -n 10 -o ./scenes -q 90
+# Specify max frames to extract and output directory
+npx scene-sieve input.mp4 -mf 500 -o ./scenes -q 90
 ```
 
 ### Module
@@ -63,7 +65,11 @@ const result = await extractScenes({
 console.log(
   `${result.prunedFramesCount} scenes extracted in ${result.executionTimeMs}ms`,
 );
-// Output: scenes/scene_001.jpg, scenes/scene_002.jpg, ...
+// Output:
+//   scenes/frame_0001.jpg
+//   scenes/frame_0002.jpg
+//   ...
+//   scenes/.metadata.json
 ```
 
 ## CLI Reference
@@ -72,16 +78,19 @@ console.log(
 scene-sieve <input> [options]
 ```
 
-| Option                     | Description                            | Default                     |
-| -------------------------- | -------------------------------------- | --------------------------- |
-| `<input>`                  | Input video or GIF file path           | (required)                  |
-| `-n, --count <number>`     | Number of frames to keep               | `5` (when no `--threshold`) |
-| `-t, --threshold <number>` | Normalized score threshold (0, 1]      | —                           |
-| `-o, --output <path>`      | Output directory                       | Same directory as input     |
-| `--fps <number>`           | Fallback FPS for frame extraction      | `5`                         |
-| `-s, --scale <number>`     | Scale size for vision analysis (px)    | `720`                       |
-| `-q, --quality <number>`   | JPEG output quality (1–100)            | `80`                        |
-| `--debug`                  | Preserve temp workspace for inspection | `false`                     |
+| Option                         | Description                                     | Default                      |
+| ------------------------------ | ----------------------------------------------- | ---------------------------- |
+| `<input>`                      | Input video or GIF file path                    | (required)                   |
+| `-n, --count <number>`         | Max number of frames to keep                    | `20`                         |
+| `-t, --threshold <number>`     | Normalized score threshold (0, 1]               | `0.5`                        |
+| `-o, --output <path>`          | Output directory                                | Same directory as input      |
+| `--fps <number>`               | Max FPS for frame extraction                    | `5`                          |
+| `-mf, --max-frames <number>`   | Max frames to extract (auto-reduces FPS)        | `300`                        |
+| `-s, --scale <number>`         | Scale size for vision analysis (px)             | `720`                        |
+| `-q, --quality <number>`       | JPEG output quality (1–100)                     | `80`                         |
+| `-it, --iou-threshold <number>`| IoU threshold for animation tracking (0–1)      | `0.9`                        |
+| `-at, --anim-threshold <number>`| Min consecutive frames for animation            | `5`                          |
+| `--debug`                      | Preserve temp workspace for inspection          | `false`                      |
 
 ### Supported Formats
 
@@ -134,7 +143,7 @@ const result = await extractScenes({
 });
 
 console.log(result.outputFiles);
-// ['./output/scene_001.jpg', './output/scene_002.jpg', ...]
+// ['./output/frame_0001.jpg', './output/frame_0002.jpg', ..., './output/.metadata.json']
 ```
 
 #### Buffer Mode
@@ -178,12 +187,15 @@ console.log(result.outputBuffers?.length); // 5
 
 ```typescript
 interface SieveOptionsBase {
-  count?: number; // Frames to keep (default: 5 when no threshold)
-  threshold?: number; // Score threshold in range (0, 1]
+  count?: number; // Max frames to keep (default: 20)
+  threshold?: number; // Score threshold in range (0, 1] (default: 0.5)
   outputPath?: string; // Output directory (file mode only)
   fps?: number; // Extraction FPS (default: 5)
+  maxFrames?: number; // Max frames to extract (default: 300)
   scale?: number; // Analysis scale in px (default: 720)
   quality?: number; // JPEG quality 1-100 (default: 80)
+  iouThreshold?: number; // IoU for animation tracking (default: 0.9)
+  animationThreshold?: number; // Min frames for animation (default: 5)
   debug?: boolean; // Preserve temp workspace (default: false)
   onProgress?: (phase: ProgressPhase, percent: number) => void;
 }
@@ -200,6 +212,8 @@ interface SieveResult {
   prunedFramesCount: number; // Frames selected as key scenes
   outputFiles: string[]; // File paths (file mode)
   outputBuffers?: Buffer[]; // JPEG buffers (buffer/frames mode)
+  animations?: AnimationMetadata[]; // Detected animations
+  video?: VideoMetadata; // Video source metadata
   executionTimeMs: number;
 }
 ```
@@ -228,6 +242,37 @@ const result = await extractScenes({
 });
 ```
 
+## Output Metadata
+
+When running in `file` mode, `scene-sieve` generates a `.metadata.json` file in the output directory.
+
+```json
+{
+  "video": {
+    "originalDurationMs": 15000,
+    "fps": 5,
+    "resolution": { "width": 720, "height": 405 }
+  },
+  "frames": [
+    {
+      "step": 1,
+      "fileName": "frame_0001.jpg",
+      "frameId": 1,
+      "timestampMs": 0
+    }
+  ],
+  "animations": [
+    {
+      "type": "loading_spinner",
+      "boundingBox": { "x": 100, "y": 200, "width": 50, "height": 50 },
+      "startFrameId": 12,
+      "endFrameId": 25,
+      "durationMs": 2600
+    }
+  ]
+}
+```
+
 ## How It Works
 
 ### Pipeline
@@ -246,8 +291,8 @@ The analyzer scores each pair of adjacent frames through 4 stages:
 
 1. **AKAZE Feature Diff** — Detects and matches keypoints between frames; identifies newly appeared and disappeared features
 2. **DBSCAN Clustering** — Groups new feature points into spatial clusters
-3. **IoU Tracking** — Tracks cluster bounding boxes across time; applies decay to repeated animation regions
-4. **G(t) Scoring** — Calculates information gain from cluster area ratio and feature density, discounting animated areas
+3. **IoU Tracking** — Tracks cluster bounding boxes across time; identifies and records repeated animation regions (e.g. loading spinners)
+4. **G(t) Scoring** — Calculates information gain from cluster area ratio and feature density, discounting animated areas to focus on unique scene content
 
 Frames with higher G(t) scores represent greater visual change and are preserved during pruning.
 

package/dist/cli.mjs

@@ -51,7 +51,7 @@ import { join } from "path";
 function getTempWorkspaceDir(sessionId) {
   return join(TEMP_BASE_DIR, `${WORKSPACE_PREFIX}${sessionId}`);
 }
-var APP_NAME, DEFAULT_COUNT, DEFAULT_THRESHOLD, DEFAULT_FPS, DEFAULT_SCALE, DEFAULT_QUALITY, DEFAULT_MAX_FRAMES, NORMALIZATION_PERCENTILE, WORKSPACE_PREFIX, TEMP_BASE_DIR, SUPPORTED_VIDEO_EXTENSIONS, SUPPORTED_GIF_EXTENSIONS, FRAME_OUTPUT_EXTENSION, FRAME_FILENAME_PATTERN, OPENCV_BATCH_SIZE, DBSCAN_ALPHA, DBSCAN_MIN_PTS, IOU_THRESHOLD, DECAY_LAMBDA, ANIMATION_FRAME_THRESHOLD, MATCH_DISTANCE_THRESHOLD, PIXELDIFF_GAUSSIAN_KERNEL, PIXELDIFF_BINARY_THRESHOLD, PIXELDIFF_CONTOUR_MIN_AREA, PIXELDIFF_SAMPLE_SPACING;
+var APP_NAME, DEFAULT_COUNT, DEFAULT_THRESHOLD, DEFAULT_FPS, DEFAULT_SCALE, DEFAULT_QUALITY, DEFAULT_MAX_FRAMES, NORMALIZATION_PERCENTILE, WORKSPACE_PREFIX, TEMP_BASE_DIR, FRAME_OUTPUT_EXTENSION, FRAME_FILENAME_PATTERN, OPENCV_BATCH_SIZE, DBSCAN_ALPHA, DBSCAN_MIN_PTS, IOU_THRESHOLD, DECAY_LAMBDA, ANIMATION_FRAME_THRESHOLD, MATCH_DISTANCE_THRESHOLD, PIXELDIFF_GAUSSIAN_KERNEL, PIXELDIFF_BINARY_THRESHOLD, PIXELDIFF_CONTOUR_MIN_AREA, PIXELDIFF_SAMPLE_SPACING;
 var init_constants = __esm({
   "src/constants.ts"() {
     "use strict";
@@ -65,14 +65,6 @@ var init_constants = __esm({
     NORMALIZATION_PERCENTILE = 0.9;
     WORKSPACE_PREFIX = `${APP_NAME}-`;
     TEMP_BASE_DIR = tmpdir();
-    SUPPORTED_VIDEO_EXTENSIONS = [
-      ".mp4",
-      ".mov",
-      ".avi",
-      ".mkv",
-      ".webm"
-    ];
-    SUPPORTED_GIF_EXTENSIONS = [".gif"];
     FRAME_OUTPUT_EXTENSION = ".jpg";
     FRAME_FILENAME_PATTERN = "frame_%06d.jpg";
     OPENCV_BATCH_SIZE = 10;
@@ -600,9 +592,6 @@ function deriveOutputPath(inputPath) {
   const name = basename(inputPath, extname(inputPath));
   return resolve(dir, `${name}_scenes`);
 }
-function isSupportedFile(filePath, extensions) {
-  return extensions.includes(extname(filePath).toLowerCase());
-}
 var init_paths = __esm({
   "src/utils/paths.ts"() {
     "use strict";
@@ -625,31 +614,46 @@ async function extractFrames(ctx) {
   if (!exists) {
     throw new Error(`Input file not found: ${inputPath}`);
   }
-  const allExtensions = [
-    ...SUPPORTED_VIDEO_EXTENSIONS,
-    ...SUPPORTED_GIF_EXTENSIONS
-  ];
-  if (!isSupportedFile(inputPath, allExtensions)) {
-    throw new Error(`Unsupported file format: ${inputPath}`);
+  const metadata = await getVideoMetadata(inputPath).catch((err) => {
+    logger.debug(`ffprobe failed: ${err.message}`);
+    return null;
+  });
+  if (!metadata || !metadata.format) {
+    throw new Error(`Could not read file metadata: ${inputPath}`);
   }
-  logger.debug(`Extracting frames from: ${inputPath}`);
+  const formatName = metadata.format.format_name ?? "";
+  const duration = parseFloat(metadata.format.duration ?? "0");
+  const hasVideoStream = metadata.streams?.some((s) => s.codec_type === "video") ?? false;
+  if (!hasVideoStream) {
+    throw new Error(
+      `No video stream found in file: ${inputPath} (detected format: ${formatName})`
+    );
+  }
+  logger.debug(
+    `Detected format: ${formatName} (Duration: ${duration.toFixed(1)}s), path: ${inputPath}`
+  );
   await ensureDir(framesDir);
   let effectiveFps = fps;
-  const duration = await getVideoDuration(inputPath).catch(() => 0);
   if (duration > 0) {
     const fpsCap = maxFrames / duration;
     effectiveFps = Math.min(fps, fpsCap);
     effectiveFps = Math.max(0.5, effectiveFps);
     logger.debug(
-      `Duration: ${duration.toFixed(1)}s, FPS: ${fps} \u2192 effective: ${effectiveFps.toFixed(2)} (maxFrames: ${maxFrames})`
+      `FPS: ${fps} \u2192 effective: ${effectiveFps.toFixed(2)} (maxFrames: ${maxFrames})`
     );
   }
-  const frames = await extractByFps(inputPath, framesDir, effectiveFps, scale);
+  const frames = await extractByFps(
+    inputPath,
+    framesDir,
+    effectiveFps,
+    scale,
+    duration
+  );
   ctx.emitProgress(100);
   logger.debug(`Extracted ${frames.length} frames`);
   return frames;
 }
-async function extractByFps(inputPath, outputDir, fps, scale) {
+async function extractByFps(inputPath, outputDir, fps, scale, duration) {
   const outputPattern = join2(outputDir, FRAME_FILENAME_PATTERN);
   await execa(ffmpegPath, [
     "-i",
@@ -660,34 +664,26 @@ async function extractByFps(inputPath, outputDir, fps, scale) {
     "2",
     outputPattern
   ]);
-  return buildFrameList(outputDir, inputPath);
+  return buildFrameList(outputDir, duration);
 }
-async function getVideoDuration(inputPath) {
+async function getVideoMetadata(inputPath) {
   const { stdout } = await execa(ffprobePath, [
     "-v",
     "quiet",
     "-print_format",
     "json",
     "-show_format",
+    "-show_streams",
     inputPath
   ]);
-  const metadata = JSON.parse(stdout);
-  return parseFloat(metadata.format?.duration ?? "0");
+  return JSON.parse(stdout);
 }
-async function buildFrameList(framesDir, inputPath) {
+async function buildFrameList(framesDir, duration) {
   const files = await readdir(framesDir);
   const jpgFiles = files.filter((f) => f.endsWith(".jpg")).sort();
   if (jpgFiles.length === 0) {
     return [];
   }
-  let duration = 0;
-  try {
-    duration = await getVideoDuration(inputPath);
-  } catch {
-    logger.debug(
-      "Could not determine video duration; using frame index for timestamps"
-    );
-  }
   return jpgFiles.map((file, index) => ({
     id: index,
     timestamp: duration > 0 && jpgFiles.length > 1 ? duration * index / (jpgFiles.length - 1) : index,

package/dist/constants.d.ts

@@ -8,8 +8,6 @@ export declare const DEFAULT_MAX_FRAMES = 300;
 export declare const NORMALIZATION_PERCENTILE = 0.9;
 export declare const WORKSPACE_PREFIX = "scene-sieve-";
 export declare const TEMP_BASE_DIR: string;
-export declare const SUPPORTED_VIDEO_EXTENSIONS: string[];
-export declare const SUPPORTED_GIF_EXTENSIONS: string[];
 export declare const FRAME_OUTPUT_EXTENSION = ".jpg";
 export declare const FRAME_FILENAME_PATTERN = "frame_%06d.jpg";
 export declare const OPENCV_BATCH_SIZE = 10;

package/dist/index.cjs

@@ -88,14 +88,6 @@ var DEFAULT_MAX_FRAMES = 300;
 var NORMALIZATION_PERCENTILE = 0.9;
 var WORKSPACE_PREFIX = `${APP_NAME}-`;
 var TEMP_BASE_DIR = (0, import_node_os.tmpdir)();
-var SUPPORTED_VIDEO_EXTENSIONS = [
-  ".mp4",
-  ".mov",
-  ".avi",
-  ".mkv",
-  ".webm"
-];
-var SUPPORTED_GIF_EXTENSIONS = [".gif"];
 var FRAME_OUTPUT_EXTENSION = ".jpg";
 var FRAME_FILENAME_PATTERN = "frame_%06d.jpg";
 var OPENCV_BATCH_SIZE = 10;
@@ -613,9 +605,6 @@ function deriveOutputPath(inputPath) {
   const name = (0, import_node_path2.basename)(inputPath, (0, import_node_path2.extname)(inputPath));
   return (0, import_node_path2.resolve)(dir, `${name}_scenes`);
 }
-function isSupportedFile(filePath, extensions) {
-  return extensions.includes((0, import_node_path2.extname)(filePath).toLowerCase());
-}
 
 // src/core/extractor.ts
 async function extractFrames(ctx) {
@@ -628,31 +617,46 @@ async function extractFrames(ctx) {
   if (!exists) {
     throw new Error(`Input file not found: ${inputPath}`);
   }
-  const allExtensions = [
-    ...SUPPORTED_VIDEO_EXTENSIONS,
-    ...SUPPORTED_GIF_EXTENSIONS
-  ];
-  if (!isSupportedFile(inputPath, allExtensions)) {
-    throw new Error(`Unsupported file format: ${inputPath}`);
+  const metadata = await getVideoMetadata(inputPath).catch((err) => {
+    logger.debug(`ffprobe failed: ${err.message}`);
+    return null;
+  });
+  if (!metadata || !metadata.format) {
+    throw new Error(`Could not read file metadata: ${inputPath}`);
+  }
+  const formatName = metadata.format.format_name ?? "";
+  const duration = parseFloat(metadata.format.duration ?? "0");
+  const hasVideoStream = metadata.streams?.some((s) => s.codec_type === "video") ?? false;
+  if (!hasVideoStream) {
+    throw new Error(
+      `No video stream found in file: ${inputPath} (detected format: ${formatName})`
+    );
   }
-  logger.debug(`Extracting frames from: ${inputPath}`);
+  logger.debug(
+    `Detected format: ${formatName} (Duration: ${duration.toFixed(1)}s), path: ${inputPath}`
+  );
   await ensureDir(framesDir);
   let effectiveFps = fps;
-  const duration = await getVideoDuration(inputPath).catch(() => 0);
   if (duration > 0) {
     const fpsCap = maxFrames / duration;
     effectiveFps = Math.min(fps, fpsCap);
     effectiveFps = Math.max(0.5, effectiveFps);
     logger.debug(
-      `Duration: ${duration.toFixed(1)}s, FPS: ${fps} \u2192 effective: ${effectiveFps.toFixed(2)} (maxFrames: ${maxFrames})`
+      `FPS: ${fps} \u2192 effective: ${effectiveFps.toFixed(2)} (maxFrames: ${maxFrames})`
     );
   }
-  const frames = await extractByFps(inputPath, framesDir, effectiveFps, scale);
+  const frames = await extractByFps(
+    inputPath,
+    framesDir,
+    effectiveFps,
+    scale,
+    duration
+  );
   ctx.emitProgress(100);
   logger.debug(`Extracted ${frames.length} frames`);
   return frames;
 }
-async function extractByFps(inputPath, outputDir, fps, scale) {
+async function extractByFps(inputPath, outputDir, fps, scale, duration) {
   const outputPattern = (0, import_node_path3.join)(outputDir, FRAME_FILENAME_PATTERN);
   await (0, import_execa.execa)(import_ffmpeg_static.default, [
     "-i",
@@ -663,34 +667,26 @@ async function extractByFps(inputPath, outputDir, fps, scale) {
     "2",
     outputPattern
   ]);
-  return buildFrameList(outputDir, inputPath);
+  return buildFrameList(outputDir, duration);
 }
-async function getVideoDuration(inputPath) {
+async function getVideoMetadata(inputPath) {
   const { stdout } = await (0, import_execa.execa)(import_ffprobe.path, [
     "-v",
     "quiet",
     "-print_format",
     "json",
     "-show_format",
+    "-show_streams",
     inputPath
   ]);
-  const metadata = JSON.parse(stdout);
-  return parseFloat(metadata.format?.duration ?? "0");
+  return JSON.parse(stdout);
 }
-async function buildFrameList(framesDir, inputPath) {
+async function buildFrameList(framesDir, duration) {
   const files = await (0, import_promises2.readdir)(framesDir);
   const jpgFiles = files.filter((f) => f.endsWith(".jpg")).sort();
   if (jpgFiles.length === 0) {
     return [];
   }
-  let duration = 0;
-  try {
-    duration = await getVideoDuration(inputPath);
-  } catch {
-    logger.debug(
-      "Could not determine video duration; using frame index for timestamps"
-    );
-  }
   return jpgFiles.map((file, index) => ({
     id: index,
     timestamp: duration > 0 && jpgFiles.length > 1 ? duration * index / (jpgFiles.length - 1) : index,

package/dist/index.mjs

@@ -48,14 +48,6 @@ var DEFAULT_MAX_FRAMES = 300;
 var NORMALIZATION_PERCENTILE = 0.9;
 var WORKSPACE_PREFIX = `${APP_NAME}-`;
 var TEMP_BASE_DIR = tmpdir();
-var SUPPORTED_VIDEO_EXTENSIONS = [
-  ".mp4",
-  ".mov",
-  ".avi",
-  ".mkv",
-  ".webm"
-];
-var SUPPORTED_GIF_EXTENSIONS = [".gif"];
 var FRAME_OUTPUT_EXTENSION = ".jpg";
 var FRAME_FILENAME_PATTERN = "frame_%06d.jpg";
 var OPENCV_BATCH_SIZE = 10;
@@ -573,9 +565,6 @@ function deriveOutputPath(inputPath) {
   const name = basename(inputPath, extname(inputPath));
   return resolve(dir, `${name}_scenes`);
 }
-function isSupportedFile(filePath, extensions) {
-  return extensions.includes(extname(filePath).toLowerCase());
-}
 
 // src/core/extractor.ts
 async function extractFrames(ctx) {
@@ -588,31 +577,46 @@ async function extractFrames(ctx) {
   if (!exists) {
     throw new Error(`Input file not found: ${inputPath}`);
   }
-  const allExtensions = [
-    ...SUPPORTED_VIDEO_EXTENSIONS,
-    ...SUPPORTED_GIF_EXTENSIONS
-  ];
-  if (!isSupportedFile(inputPath, allExtensions)) {
-    throw new Error(`Unsupported file format: ${inputPath}`);
+  const metadata = await getVideoMetadata(inputPath).catch((err) => {
+    logger.debug(`ffprobe failed: ${err.message}`);
+    return null;
+  });
+  if (!metadata || !metadata.format) {
+    throw new Error(`Could not read file metadata: ${inputPath}`);
+  }
+  const formatName = metadata.format.format_name ?? "";
+  const duration = parseFloat(metadata.format.duration ?? "0");
+  const hasVideoStream = metadata.streams?.some((s) => s.codec_type === "video") ?? false;
+  if (!hasVideoStream) {
+    throw new Error(
+      `No video stream found in file: ${inputPath} (detected format: ${formatName})`
+    );
   }
-  logger.debug(`Extracting frames from: ${inputPath}`);
+  logger.debug(
+    `Detected format: ${formatName} (Duration: ${duration.toFixed(1)}s), path: ${inputPath}`
+  );
   await ensureDir(framesDir);
   let effectiveFps = fps;
-  const duration = await getVideoDuration(inputPath).catch(() => 0);
   if (duration > 0) {
     const fpsCap = maxFrames / duration;
     effectiveFps = Math.min(fps, fpsCap);
     effectiveFps = Math.max(0.5, effectiveFps);
     logger.debug(
-      `Duration: ${duration.toFixed(1)}s, FPS: ${fps} \u2192 effective: ${effectiveFps.toFixed(2)} (maxFrames: ${maxFrames})`
+      `FPS: ${fps} \u2192 effective: ${effectiveFps.toFixed(2)} (maxFrames: ${maxFrames})`
     );
   }
-  const frames = await extractByFps(inputPath, framesDir, effectiveFps, scale);
+  const frames = await extractByFps(
+    inputPath,
+    framesDir,
+    effectiveFps,
+    scale,
+    duration
+  );
   ctx.emitProgress(100);
   logger.debug(`Extracted ${frames.length} frames`);
   return frames;
 }
-async function extractByFps(inputPath, outputDir, fps, scale) {
+async function extractByFps(inputPath, outputDir, fps, scale, duration) {
   const outputPattern = join2(outputDir, FRAME_FILENAME_PATTERN);
   await execa(ffmpegPath, [
     "-i",
@@ -623,34 +627,26 @@ async function extractByFps(inputPath, outputDir, fps, scale) {
     "2",
     outputPattern
   ]);
-  return buildFrameList(outputDir, inputPath);
+  return buildFrameList(outputDir, duration);
 }
-async function getVideoDuration(inputPath) {
+async function getVideoMetadata(inputPath) {
   const { stdout } = await execa(ffprobePath, [
     "-v",
     "quiet",
     "-print_format",
     "json",
     "-show_format",
+    "-show_streams",
     inputPath
   ]);
-  const metadata = JSON.parse(stdout);
-  return parseFloat(metadata.format?.duration ?? "0");
+  return JSON.parse(stdout);
 }
-async function buildFrameList(framesDir, inputPath) {
+async function buildFrameList(framesDir, duration) {
   const files = await readdir(framesDir);
   const jpgFiles = files.filter((f) => f.endsWith(".jpg")).sort();
   if (jpgFiles.length === 0) {
     return [];
   }
-  let duration = 0;
-  try {
-    duration = await getVideoDuration(inputPath);
-  } catch {
-    logger.debug(
-      "Could not determine video duration; using frame index for timestamps"
-    );
-  }
   return jpgFiles.map((file, index) => ({
     id: index,
     timestamp: duration > 0 && jpgFiles.length > 1 ? duration * index / (jpgFiles.length - 1) : index,

package/dist/pipeline-worker.mjs

@@ -51,14 +51,6 @@ var DEFAULT_MAX_FRAMES = 300;
 var NORMALIZATION_PERCENTILE = 0.9;
 var WORKSPACE_PREFIX = `${APP_NAME}-`;
 var TEMP_BASE_DIR = tmpdir();
-var SUPPORTED_VIDEO_EXTENSIONS = [
-  ".mp4",
-  ".mov",
-  ".avi",
-  ".mkv",
-  ".webm"
-];
-var SUPPORTED_GIF_EXTENSIONS = [".gif"];
 var FRAME_OUTPUT_EXTENSION = ".jpg";
 var FRAME_FILENAME_PATTERN = "frame_%06d.jpg";
 var OPENCV_BATCH_SIZE = 10;
@@ -576,9 +568,6 @@ function deriveOutputPath(inputPath) {
   const name = basename(inputPath, extname(inputPath));
   return resolve(dir, `${name}_scenes`);
 }
-function isSupportedFile(filePath, extensions) {
-  return extensions.includes(extname(filePath).toLowerCase());
-}
 
 // src/core/extractor.ts
 async function extractFrames(ctx) {
@@ -591,31 +580,46 @@ async function extractFrames(ctx) {
   if (!exists) {
     throw new Error(`Input file not found: ${inputPath}`);
   }
-  const allExtensions = [
-    ...SUPPORTED_VIDEO_EXTENSIONS,
-    ...SUPPORTED_GIF_EXTENSIONS
-  ];
-  if (!isSupportedFile(inputPath, allExtensions)) {
-    throw new Error(`Unsupported file format: ${inputPath}`);
+  const metadata = await getVideoMetadata(inputPath).catch((err) => {
+    logger.debug(`ffprobe failed: ${err.message}`);
+    return null;
+  });
+  if (!metadata || !metadata.format) {
+    throw new Error(`Could not read file metadata: ${inputPath}`);
   }
-  logger.debug(`Extracting frames from: ${inputPath}`);
+  const formatName = metadata.format.format_name ?? "";
+  const duration = parseFloat(metadata.format.duration ?? "0");
+  const hasVideoStream = metadata.streams?.some((s) => s.codec_type === "video") ?? false;
+  if (!hasVideoStream) {
+    throw new Error(
+      `No video stream found in file: ${inputPath} (detected format: ${formatName})`
+    );
+  }
+  logger.debug(
+    `Detected format: ${formatName} (Duration: ${duration.toFixed(1)}s), path: ${inputPath}`
+  );
   await ensureDir(framesDir);
   let effectiveFps = fps;
-  const duration = await getVideoDuration(inputPath).catch(() => 0);
   if (duration > 0) {
     const fpsCap = maxFrames / duration;
     effectiveFps = Math.min(fps, fpsCap);
     effectiveFps = Math.max(0.5, effectiveFps);
     logger.debug(
-      `Duration: ${duration.toFixed(1)}s, FPS: ${fps} \u2192 effective: ${effectiveFps.toFixed(2)} (maxFrames: ${maxFrames})`
+      `FPS: ${fps} \u2192 effective: ${effectiveFps.toFixed(2)} (maxFrames: ${maxFrames})`
     );
   }
-  const frames = await extractByFps(inputPath, framesDir, effectiveFps, scale);
+  const frames = await extractByFps(
+    inputPath,
+    framesDir,
+    effectiveFps,
+    scale,
+    duration
+  );
   ctx.emitProgress(100);
   logger.debug(`Extracted ${frames.length} frames`);
   return frames;
 }
-async function extractByFps(inputPath, outputDir, fps, scale) {
+async function extractByFps(inputPath, outputDir, fps, scale, duration) {
   const outputPattern = join2(outputDir, FRAME_FILENAME_PATTERN);
   await execa(ffmpegPath, [
     "-i",
@@ -626,34 +630,26 @@ async function extractByFps(inputPath, outputDir, fps, scale) {
     "2",
     outputPattern
   ]);
-  return buildFrameList(outputDir, inputPath);
+  return buildFrameList(outputDir, duration);
 }
-async function getVideoDuration(inputPath) {
+async function getVideoMetadata(inputPath) {
   const { stdout } = await execa(ffprobePath, [
     "-v",
     "quiet",
     "-print_format",
     "json",
     "-show_format",
+    "-show_streams",
     inputPath
   ]);
-  const metadata = JSON.parse(stdout);
-  return parseFloat(metadata.format?.duration ?? "0");
+  return JSON.parse(stdout);
 }
-async function buildFrameList(framesDir, inputPath) {
+async function buildFrameList(framesDir, duration) {
   const files = await readdir(framesDir);
   const jpgFiles = files.filter((f) => f.endsWith(".jpg")).sort();
   if (jpgFiles.length === 0) {
     return [];
   }
-  let duration = 0;
-  try {
-    duration = await getVideoDuration(inputPath);
-  } catch {
-    logger.debug(
-      "Could not determine video duration; using frame index for timestamps"
-    );
-  }
   return jpgFiles.map((file, index) => ({
     id: index,
     timestamp: duration > 0 && jpgFiles.length > 1 ? duration * index / (jpgFiles.length - 1) : index,

package/dist/utils/paths.d.ts

@@ -16,4 +16,3 @@ export declare function resolveAbsolute(p: string): string;
  * e.g., /path/to/video.mp4 -> /path/to/video_scenes
  */
 export declare function deriveOutputPath(inputPath: string): string;
-export declare function isSupportedFile(filePath: string, extensions: string[]): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumy-pack/scene-sieve",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "description": "CLI tool for extracting key frames from video and GIF files",
   "keywords": [
     "cli",