@lumy-pack/scene-sieve 0.0.5 → 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, 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,15 +65,8 @@ 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;
     DBSCAN_ALPHA = 0.03;
     DBSCAN_MIN_PTS = 4;
@@ -431,13 +424,17 @@ async function analyzeBatch(cvLib, frames, scale, tracker, pairOffset) {
 }
 async function analyzeFrames(ctx) {
   const { frames } = ctx;
-  if (frames.length < 2) return [];
+  if (frames.length < 2) return { edges: [], animations: [] };
   logger.debug(
     `Analyzing ${frames.length} frames in batches of ${OPENCV_BATCH_SIZE}`
   );
   const cvLib = await ensureOpenCV();
   const edges = [];
-  const tracker = new IoUTracker();
+  const tracker = new IoUTracker(
+    ctx.options.fps,
+    ctx.options.iouThreshold,
+    ctx.options.animationThreshold
+  );
   const scale = ctx.options.scale;
   for (let i = 0; i < frames.length - 1; i += OPENCV_BATCH_SIZE) {
     const batchEnd = Math.min(i + OPENCV_BATCH_SIZE + 1, frames.length);
@@ -450,8 +447,11 @@ async function analyzeFrames(ctx) {
     );
     ctx.emitProgress(progress);
   }
-  logger.debug(`Computed ${edges.length} score edges`);
-  return edges;
+  const animations = tracker.flushAndGetAnimations();
+  logger.debug(
+    `Computed ${edges.length} score edges and ${animations.length} animations`
+  );
+  return { edges, animations };
 }
 var OPENCV_INIT_TIMEOUT_MS, require2, cvReady, IoUTracker;
 var init_analyzer = __esm({
@@ -464,7 +464,13 @@ var init_analyzer = __esm({
     require2 = createRequire(import.meta.url);
     cvReady = null;
     IoUTracker = class {
+      constructor(fps = DEFAULT_FPS, iouThreshold = IOU_THRESHOLD, animationThreshold = ANIMATION_FRAME_THRESHOLD) {
+        this.fps = fps;
+        this.iouThreshold = iouThreshold;
+        this.animationThreshold = animationThreshold;
+      }
       regions = [];
+      extractedAnimations = [];
       update(boxes, pairIndex) {
         const animationIndices = /* @__PURE__ */ new Set();
         const matched = /* @__PURE__ */ new Set();
@@ -480,7 +486,7 @@ var init_analyzer = __esm({
               bestRegionIdx = ri;
             }
           }
-          if (bestIoU > IOU_THRESHOLD && bestRegionIdx !== -1) {
+          if (bestIoU > this.iouThreshold && bestRegionIdx !== -1) {
             const region = this.regions[bestRegionIdx];
             const gap = pairIndex - region.lastSeen;
             region.box = box;
@@ -488,13 +494,14 @@ var init_analyzer = __esm({
             region.lastSeen = pairIndex;
             region.weight *= Math.pow(DECAY_LAMBDA, gap);
             matched.add(bestRegionIdx);
-            if (region.consecutiveCount >= ANIMATION_FRAME_THRESHOLD) {
+            if (region.consecutiveCount >= this.animationThreshold) {
               animationIndices.add(bi);
             }
           } else {
             this.regions.push({
               box,
               consecutiveCount: 1,
+              firstSeen: pairIndex,
               lastSeen: pairIndex,
               weight: 1
             });
@@ -506,17 +513,45 @@ var init_analyzer = __esm({
             this.regions[ri].weight *= Math.pow(DECAY_LAMBDA, gap);
           }
         }
-        this.regions = this.regions.filter((r) => r.weight > 0.01);
+        for (let i = 0; i < this.regions.length; i++) {
+          const region = this.regions[i];
+          if (region.weight <= 0.01 && !matched.has(i)) {
+            this.collectAnimation(region);
+          }
+        }
+        this.regions = this.regions.filter(
+          (r, i) => r.weight > 0.01 || matched.has(i)
+        );
         return animationIndices;
       }
+      collectAnimation(region) {
+        if (region.consecutiveCount >= this.animationThreshold) {
+          const durationMs = region.consecutiveCount / this.fps * 1e3;
+          this.extractedAnimations.push({
+            type: "loading_spinner",
+            // 기본값으로 loading_spinner 사용
+            boundingBox: region.box,
+            startFrameId: region.firstSeen,
+            endFrameId: region.lastSeen,
+            durationMs
+          });
+        }
+      }
+      flushAndGetAnimations() {
+        for (const region of this.regions) {
+          this.collectAnimation(region);
+        }
+        this.regions = [];
+        return this.extractedAnimations;
+      }
       getAnimationWeight(boxIndex, boxes) {
         if (boxIndex >= boxes.length) return 0;
         const box = boxes[boxIndex];
         let maxWeight = 0;
         for (const region of this.regions) {
-          if (region.consecutiveCount >= ANIMATION_FRAME_THRESHOLD) {
+          if (region.consecutiveCount >= this.animationThreshold) {
             const iou = computeIoU(box, region.box);
-            if (iou > IOU_THRESHOLD) {
+            if (iou > this.iouThreshold) {
               maxWeight = Math.max(maxWeight, region.weight);
             }
           }
@@ -557,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";
@@ -582,32 +614,47 @@ 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) {
-  const outputPattern = join2(outputDir, "frame_%06d.jpg");
+async function extractByFps(inputPath, outputDir, fps, scale, duration) {
+  const outputPattern = join2(outputDir, FRAME_FILENAME_PATTERN);
   await execa(ffmpegPath, [
     "-i",
     inputPath,
@@ -617,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,
@@ -675,13 +714,44 @@ async function finalizeOutput(ctx, selectedFrames) {
   const outputPath = ctx.options.outputPath;
   const quality = ctx.options.quality;
   const outputFiles = [];
+  const framesMetadata = [];
+  const totalFramesCount = ctx.frames.length;
+  const padding = Math.max(4, String(totalFramesCount).length);
   for (let i = 0; i < selectedFrames.length; i++) {
     const frame = selectedFrames[i];
-    const destName = `scene_${String(i + 1).padStart(3, "0")}.jpg`;
-    const destPath = join3(stagingDir, destName);
+    const fileName = `frame_${String(frame.id + 1).padStart(padding, "0")}.jpg`;
+    const destPath = join3(stagingDir, fileName);
     await sharp2(frame.extractPath).jpeg({ quality, mozjpeg: true }).toFile(destPath);
-    outputFiles.push(join3(outputPath, destName));
+    outputFiles.push(join3(outputPath, fileName));
+    framesMetadata.push({
+      step: i + 1,
+      fileName,
+      frameId: frame.id + 1,
+      timestampMs: Math.round(frame.timestamp * 1e3)
+    });
   }
+  const metadata = {
+    video: {
+      originalDurationMs: Math.round(
+        (ctx.frames.length > 0 ? ctx.frames[ctx.frames.length - 1].timestamp : 0) * 1e3
+      ),
+      fps: ctx.options.fps,
+      resolution: {
+        width: ctx.options.scale,
+        height: Math.round(ctx.options.scale * 9 / 16)
+      }
+    },
+    frames: framesMetadata,
+    animations: (ctx.animations || []).map((anim) => ({
+      ...anim,
+      startFrameId: anim.startFrameId + 1,
+      endFrameId: anim.endFrameId + 1,
+      durationMs: Math.round(anim.durationMs)
+    }))
+  };
+  const metadataPath = join3(stagingDir, ".metadata.json");
+  await writeFile(metadataPath, JSON.stringify(metadata, null, 2));
+  outputFiles.push(join3(outputPath, ".metadata.json"));
   await ensureDir(join3(outputPath, ".."));
   await rm(outputPath, { recursive: true, force: true });
   await rename(stagingDir, outputPath);
@@ -769,6 +839,8 @@ function resolveOptions(options) {
     maxFrames: options.maxFrames ?? DEFAULT_MAX_FRAMES,
     scale: options.scale ?? DEFAULT_SCALE,
     quality: options.quality ?? DEFAULT_QUALITY,
+    iouThreshold: options.iouThreshold ?? IOU_THRESHOLD,
+    animationThreshold: options.animationThreshold ?? ANIMATION_FRAME_THRESHOLD,
     debug: options.debug ?? false
   };
 }
@@ -1065,7 +1137,9 @@ async function runPipeline(options) {
     }
     ctx.emitProgress(100);
     ctx.status = "ANALYZING";
-    ctx.graph = await analyzeFrames(ctx);
+    const { edges, animations } = await analyzeFrames(ctx);
+    ctx.graph = edges;
+    ctx.animations = animations;
     ctx.status = "PRUNING";
     const survivingIds = pruneByThresholdWithCap(
       ctx.graph,
@@ -1098,6 +1172,15 @@ async function runPipeline(options) {
       prunedFramesCount: prunedFrames.length,
       outputFiles,
       outputBuffers,
+      animations: ctx.animations,
+      video: {
+        originalDurationMs: ctx.frames.length / ctx.options.fps * 1e3,
+        fps: ctx.options.fps,
+        resolution: {
+          width: ctx.options.scale,
+          height: Math.round(ctx.options.scale * 9 / 16)
+        }
+      },
       executionTimeMs: Date.now() - startTime
     };
   } catch (error) {
@@ -1280,6 +1363,8 @@ var SieveView = (props) => {
             maxFrames: props.maxFrames,
             scale: props.scale,
             quality: props.quality,
+            iouThreshold: props.iouThreshold,
+            animationThreshold: props.animationThreshold,
             debug: props.debug
           },
           (phase, percent) => {
@@ -1374,12 +1459,19 @@ var SieveView = (props) => {
         "\u2713 Done",
         " \u2014 ",
         result.originalFramesCount,
-        " frames \u2192 ",
+        " frames \u2192",
+        " ",
         result.prunedFramesCount,
         " scenes (",
         (result.executionTimeMs / 1e3).toFixed(1),
         "s)"
       ] }),
+      result.animations && result.animations.length > 0 && /* @__PURE__ */ jsxs3(Text3, { color: "blue", children: [
+        "\u2139 Found",
+        " ",
+        result.animations.length,
+        " animations (recorded in .metadata.json)"
+      ] }),
       props.debug && result.outputFiles.length > 0 && /* @__PURE__ */ jsxs3(Box2, { flexDirection: "column", marginTop: 1, children: [
         /* @__PURE__ */ jsxs3(Text3, { color: "gray", children: [
           "Output: ",
@@ -1395,17 +1487,32 @@ var SieveView = (props) => {
 };
 
 // src/cli.ts
+init_constants();
 var require3 = createRequire2(import.meta.url);
 var { version } = require3("../package.json");
 var program = new Command();
 program.name("scene-sieve").description("Extract key frames from video and GIF files").version(version).argument("<input>", "Input video or GIF file path").option("-n, --count <number>", "Max number of frames to keep (default: 20)").option(
   "-t, --threshold <number>",
   "Normalized threshold 0~1 (default: 0.5; keeps frames above ratio of max change)"
-).option("-o, --output <path>", "Output directory path").option("--fps <number>", "Max FPS for frame extraction", "5").option(
-  "--max-frames <number>",
+).option("-o, --output <path>", "Output directory path").option("--fps <number>", "Max FPS for frame extraction", String(DEFAULT_FPS)).option(
+  "-mf, --max-frames <number>",
   "Max frames to extract (auto-reduces FPS for long videos)",
-  "300"
-).option("-s, --scale <number>", "Scale size for vision analysis", "720").option("-q, --quality <number>", "JPEG output quality 1-100", "80").option("--debug", "Enable debug mode (preserve temp workspace)").action(async (input, opts) => {
+  String(DEFAULT_MAX_FRAMES)
+).option(
+  "-s, --scale <number>",
+  "Scale size for vision analysis",
+  String(DEFAULT_SCALE)
+).option(
+  "-q, --quality <number>",
+  "JPEG output quality 1-100",
+  String(DEFAULT_QUALITY)
+).option(
+  "-it, --iou-threshold <number>",
+  `IoU threshold for animation tracking (0-1) (default: ${IOU_THRESHOLD})`
+).option(
+  "-at, --anim-threshold <number>",
+  `Min consecutive frames for animation (default: ${ANIMATION_FRAME_THRESHOLD})`
+).option("--debug", "Enable debug mode (preserve temp workspace)").action(async (input, opts) => {
   const { waitUntilExit } = render(
     React2.createElement(SieveView, {
       input,
@@ -1416,6 +1523,8 @@ program.name("scene-sieve").description("Extract key frames from video and GIF f
       maxFrames: parseInt(opts.maxFrames, 10),
       scale: parseInt(opts.scale, 10),
       quality: parseInt(opts.quality, 10),
+      iouThreshold: opts.iouThreshold !== void 0 ? parseFloat(opts.iouThreshold) : void 0,
+      animationThreshold: opts.animThreshold !== void 0 ? parseInt(opts.animThreshold, 10) : void 0,
       debug: opts.debug ?? false
     })
   );

package/dist/commands/Sieve.d.ts

@@ -8,6 +8,8 @@ export interface SieveViewProps {
     maxFrames: number;
     scale: number;
     quality: number;
+    iouThreshold?: number;
+    animationThreshold?: number;
     debug: boolean;
 }
 export declare const SieveView: React.FC<SieveViewProps>;

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/core/analyzer.d.ts

@@ -1,4 +1,4 @@
-import type { BoundingBox, ProcessContext, ScoreEdge } from '../types/index.js';
+import type { AnalysisResult, AnimationMetadata, BoundingBox, ProcessContext } from '../types/index.js';
 import type { Point2D } from './dbscan.js';
 type CvLib = typeof import('@techstark/opencv-js');
 export declare function preprocessFrame(framePath: string, scale: number): Promise<{
@@ -8,8 +8,15 @@ export declare function preprocessFrame(framePath: string, scale: number): Promi
 }>;
 export declare function computeIoU(a: BoundingBox, b: BoundingBox): number;
 export declare class IoUTracker {
+    private fps;
+    private iouThreshold;
+    private animationThreshold;
     private regions;
+    private extractedAnimations;
+    constructor(fps?: number, iouThreshold?: number, animationThreshold?: number);
     update(boxes: BoundingBox[], pairIndex: number): Set<number>;
+    private collectAnimation;
+    flushAndGetAnimations(): AnimationMetadata[];
     getAnimationWeight(boxIndex: number, boxes: BoundingBox[]): number;
 }
 export interface AKAZEResult {
@@ -51,5 +58,5 @@ export declare function computeInformationGain(clusters: BoundingBox[], clusterP
  * 3. Spatio-temporal IoU Tracking
  * 4. G(t) Information Gain Scoring
  */
-export declare function analyzeFrames(ctx: ProcessContext): Promise<ScoreEdge[]>;
+export declare function analyzeFrames(ctx: ProcessContext): Promise<AnalysisResult>;
 export {};