@lumy-pack/scene-sieve 0.0.6 → 0.0.8

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_LOGISTIC_K, NORMALIZATION_ALPHA, NORMALIZATION_MAD_COEFFICIENT, NORMALIZATION_MIN_SAMPLE_SIZE, 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";
@@ -62,17 +62,12 @@ var init_constants = __esm({
     DEFAULT_SCALE = 720;
     DEFAULT_QUALITY = 80;
     DEFAULT_MAX_FRAMES = 300;
-    NORMALIZATION_PERCENTILE = 0.9;
+    NORMALIZATION_LOGISTIC_K = 3;
+    NORMALIZATION_ALPHA = 0.4;
+    NORMALIZATION_MAD_COEFFICIENT = 1.4826;
+    NORMALIZATION_MIN_SAMPLE_SIZE = 10;
     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 +595,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 +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 = join2(outputDir, FRAME_FILENAME_PATTERN);
   await execa(ffmpegPath, [
     "-i",
@@ -660,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 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,
@@ -877,6 +876,49 @@ var init_input_resolver = __esm({
   }
 });
 
+// src/utils/math.ts
+function normalizeScores(items) {
+  if (items.length === 0) return [];
+  const safeScores = items.map(
+    (e) => Number.isFinite(e.score) && e.score > 0 ? e.score : 0
+  );
+  const positiveScores = safeScores.filter((s) => s > 0);
+  if (positiveScores.length === 0) return safeScores;
+  const sorted = [...positiveScores].sort((a, b) => a - b);
+  if (positiveScores.length <= NORMALIZATION_MIN_SAMPLE_SIZE) {
+    const min = sorted[0];
+    const max = sorted[sorted.length - 1];
+    if (max === min) return safeScores.map((s) => s > 0 ? 1 : 0);
+    return safeScores.map(
+      (s) => s <= 0 ? 0 : Math.max(0, Math.min((s - min) / (max - min), 1))
+    );
+  }
+  const median = sorted[Math.floor(sorted.length / 2)];
+  const absoluteDiffs = positiveScores.map((v) => Math.abs(v - median));
+  const mad = [...absoluteDiffs].sort((a, b) => a - b)[Math.floor(absoluteDiffs.length / 2)];
+  const scale = mad === 0 ? median : mad * NORMALIZATION_MAD_COEFFICIENT;
+  const logisticZ = safeScores.map((s) => {
+    if (s <= 0) return 0;
+    if (scale === 0) return 1;
+    const z = (s - median) / scale;
+    return 1 / (1 + Math.exp(-NORMALIZATION_LOGISTIC_K * z));
+  });
+  const cdf = safeScores.map((s) => {
+    if (s <= 0) return 0;
+    const rank = sorted.findIndex((v) => v >= s);
+    return rank / sorted.length;
+  });
+  return logisticZ.map(
+    (z, i) => z * (1 - NORMALIZATION_ALPHA) + cdf[i] * NORMALIZATION_ALPHA
+  );
+}
+var init_math = __esm({
+  "src/utils/math.ts"() {
+    "use strict";
+    init_constants();
+  }
+});
+
 // src/utils/min-heap.ts
 var MinHeap;
 var init_min_heap = __esm({
@@ -977,20 +1019,6 @@ function pruneTo(graph, frames, targetCount) {
   }
   return surviving;
 }
-function normalizeScores(graph) {
-  if (graph.length === 0) return [];
-  const safeScores = graph.map(
-    (e) => Number.isFinite(e.score) && e.score > 0 ? e.score : 0
-  );
-  const sorted = [...safeScores].filter((s) => s > 0).sort((a, b) => a - b);
-  if (sorted.length === 0) return safeScores;
-  const pIdx = Math.min(
-    Math.floor(sorted.length * NORMALIZATION_PERCENTILE),
-    sorted.length - 1
-  );
-  const refScore = sorted[pIdx];
-  return safeScores.map((s) => Math.min(s / refScore, 1));
-}
 function suppressConsecutiveRuns(graph, passingIndices, normalizedScores) {
   const result = /* @__PURE__ */ new Set();
   let runStart = 0;
@@ -1090,7 +1118,7 @@ function pruneByThresholdWithCap(graph, frames, threshold, maxCount) {
 var init_pruner = __esm({
   "src/core/pruner.ts"() {
     "use strict";
-    init_constants();
+    init_math();
     init_min_heap();
   }
 });

package/dist/constants.d.ts

@@ -5,11 +5,14 @@ export declare const DEFAULT_FPS = 5;
 export declare const DEFAULT_SCALE = 720;
 export declare const DEFAULT_QUALITY = 80;
 export declare const DEFAULT_MAX_FRAMES = 300;
-export declare const NORMALIZATION_PERCENTILE = 0.9;
+export declare const NORMALIZATION_MIN_PERCENTILE = 0.1;
+export declare const NORMALIZATION_MAX_PERCENTILE = 0.9;
+export declare const NORMALIZATION_LOGISTIC_K = 3;
+export declare const NORMALIZATION_ALPHA = 0.4;
+export declare const NORMALIZATION_MAD_COEFFICIENT = 1.4826;
+export declare const NORMALIZATION_MIN_SAMPLE_SIZE = 10;
 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

@@ -85,17 +85,12 @@ var DEFAULT_FPS = 5;
 var DEFAULT_SCALE = 720;
 var DEFAULT_QUALITY = 80;
 var DEFAULT_MAX_FRAMES = 300;
-var NORMALIZATION_PERCENTILE = 0.9;
+var NORMALIZATION_LOGISTIC_K = 3;
+var NORMALIZATION_ALPHA = 0.4;
+var NORMALIZATION_MAD_COEFFICIENT = 1.4826;
+var NORMALIZATION_MIN_SAMPLE_SIZE = 10;
 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 +608,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 +620,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 +670,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,
@@ -843,6 +842,43 @@ async function resolveInput(options, workspacePath) {
   throw new Error(`Unsupported input mode: ${options.mode}`);
 }
 
+// src/utils/math.ts
+function normalizeScores(items) {
+  if (items.length === 0) return [];
+  const safeScores = items.map(
+    (e) => Number.isFinite(e.score) && e.score > 0 ? e.score : 0
+  );
+  const positiveScores = safeScores.filter((s) => s > 0);
+  if (positiveScores.length === 0) return safeScores;
+  const sorted = [...positiveScores].sort((a, b) => a - b);
+  if (positiveScores.length <= NORMALIZATION_MIN_SAMPLE_SIZE) {
+    const min = sorted[0];
+    const max = sorted[sorted.length - 1];
+    if (max === min) return safeScores.map((s) => s > 0 ? 1 : 0);
+    return safeScores.map(
+      (s) => s <= 0 ? 0 : Math.max(0, Math.min((s - min) / (max - min), 1))
+    );
+  }
+  const median = sorted[Math.floor(sorted.length / 2)];
+  const absoluteDiffs = positiveScores.map((v) => Math.abs(v - median));
+  const mad = [...absoluteDiffs].sort((a, b) => a - b)[Math.floor(absoluteDiffs.length / 2)];
+  const scale = mad === 0 ? median : mad * NORMALIZATION_MAD_COEFFICIENT;
+  const logisticZ = safeScores.map((s) => {
+    if (s <= 0) return 0;
+    if (scale === 0) return 1;
+    const z = (s - median) / scale;
+    return 1 / (1 + Math.exp(-NORMALIZATION_LOGISTIC_K * z));
+  });
+  const cdf = safeScores.map((s) => {
+    if (s <= 0) return 0;
+    const rank = sorted.findIndex((v) => v >= s);
+    return rank / sorted.length;
+  });
+  return logisticZ.map(
+    (z, i) => z * (1 - NORMALIZATION_ALPHA) + cdf[i] * NORMALIZATION_ALPHA
+  );
+}
+
 // src/utils/min-heap.ts
 var MinHeap = class {
   h = [];
@@ -937,20 +973,6 @@ function pruneTo(graph, frames, targetCount) {
   }
   return surviving;
 }
-function normalizeScores(graph) {
-  if (graph.length === 0) return [];
-  const safeScores = graph.map(
-    (e) => Number.isFinite(e.score) && e.score > 0 ? e.score : 0
-  );
-  const sorted = [...safeScores].filter((s) => s > 0).sort((a, b) => a - b);
-  if (sorted.length === 0) return safeScores;
-  const pIdx = Math.min(
-    Math.floor(sorted.length * NORMALIZATION_PERCENTILE),
-    sorted.length - 1
-  );
-  const refScore = sorted[pIdx];
-  return safeScores.map((s) => Math.min(s / refScore, 1));
-}
 function suppressConsecutiveRuns(graph, passingIndices, normalizedScores) {
   const result = /* @__PURE__ */ new Set();
   let runStart = 0;

package/dist/index.mjs

@@ -45,17 +45,12 @@ var DEFAULT_FPS = 5;
 var DEFAULT_SCALE = 720;
 var DEFAULT_QUALITY = 80;
 var DEFAULT_MAX_FRAMES = 300;
-var NORMALIZATION_PERCENTILE = 0.9;
+var NORMALIZATION_LOGISTIC_K = 3;
+var NORMALIZATION_ALPHA = 0.4;
+var NORMALIZATION_MAD_COEFFICIENT = 1.4826;
+var NORMALIZATION_MIN_SAMPLE_SIZE = 10;
 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 +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) {
@@ -588,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}`);
+  }
+  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 +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,
@@ -803,6 +802,43 @@ async function resolveInput(options, workspacePath) {
   throw new Error(`Unsupported input mode: ${options.mode}`);
 }
 
+// src/utils/math.ts
+function normalizeScores(items) {
+  if (items.length === 0) return [];
+  const safeScores = items.map(
+    (e) => Number.isFinite(e.score) && e.score > 0 ? e.score : 0
+  );
+  const positiveScores = safeScores.filter((s) => s > 0);
+  if (positiveScores.length === 0) return safeScores;
+  const sorted = [...positiveScores].sort((a, b) => a - b);
+  if (positiveScores.length <= NORMALIZATION_MIN_SAMPLE_SIZE) {
+    const min = sorted[0];
+    const max = sorted[sorted.length - 1];
+    if (max === min) return safeScores.map((s) => s > 0 ? 1 : 0);
+    return safeScores.map(
+      (s) => s <= 0 ? 0 : Math.max(0, Math.min((s - min) / (max - min), 1))
+    );
+  }
+  const median = sorted[Math.floor(sorted.length / 2)];
+  const absoluteDiffs = positiveScores.map((v) => Math.abs(v - median));
+  const mad = [...absoluteDiffs].sort((a, b) => a - b)[Math.floor(absoluteDiffs.length / 2)];
+  const scale = mad === 0 ? median : mad * NORMALIZATION_MAD_COEFFICIENT;
+  const logisticZ = safeScores.map((s) => {
+    if (s <= 0) return 0;
+    if (scale === 0) return 1;
+    const z = (s - median) / scale;
+    return 1 / (1 + Math.exp(-NORMALIZATION_LOGISTIC_K * z));
+  });
+  const cdf = safeScores.map((s) => {
+    if (s <= 0) return 0;
+    const rank = sorted.findIndex((v) => v >= s);
+    return rank / sorted.length;
+  });
+  return logisticZ.map(
+    (z, i) => z * (1 - NORMALIZATION_ALPHA) + cdf[i] * NORMALIZATION_ALPHA
+  );
+}
+
 // src/utils/min-heap.ts
 var MinHeap = class {
   h = [];
@@ -897,20 +933,6 @@ function pruneTo(graph, frames, targetCount) {
   }
   return surviving;
 }
-function normalizeScores(graph) {
-  if (graph.length === 0) return [];
-  const safeScores = graph.map(
-    (e) => Number.isFinite(e.score) && e.score > 0 ? e.score : 0
-  );
-  const sorted = [...safeScores].filter((s) => s > 0).sort((a, b) => a - b);
-  if (sorted.length === 0) return safeScores;
-  const pIdx = Math.min(
-    Math.floor(sorted.length * NORMALIZATION_PERCENTILE),
-    sorted.length - 1
-  );
-  const refScore = sorted[pIdx];
-  return safeScores.map((s) => Math.min(s / refScore, 1));
-}
 function suppressConsecutiveRuns(graph, passingIndices, normalizedScores) {
   const result = /* @__PURE__ */ new Set();
   let runStart = 0;

package/dist/pipeline-worker.mjs

@@ -48,17 +48,12 @@ var DEFAULT_FPS = 5;
 var DEFAULT_SCALE = 720;
 var DEFAULT_QUALITY = 80;
 var DEFAULT_MAX_FRAMES = 300;
-var NORMALIZATION_PERCENTILE = 0.9;
+var NORMALIZATION_LOGISTIC_K = 3;
+var NORMALIZATION_ALPHA = 0.4;
+var NORMALIZATION_MAD_COEFFICIENT = 1.4826;
+var NORMALIZATION_MIN_SAMPLE_SIZE = 10;
 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 +571,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 +583,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 +633,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,
@@ -806,6 +805,43 @@ async function resolveInput(options2, workspacePath) {
   throw new Error(`Unsupported input mode: ${options2.mode}`);
 }
 
+// src/utils/math.ts
+function normalizeScores(items) {
+  if (items.length === 0) return [];
+  const safeScores = items.map(
+    (e) => Number.isFinite(e.score) && e.score > 0 ? e.score : 0
+  );
+  const positiveScores = safeScores.filter((s) => s > 0);
+  if (positiveScores.length === 0) return safeScores;
+  const sorted = [...positiveScores].sort((a, b) => a - b);
+  if (positiveScores.length <= NORMALIZATION_MIN_SAMPLE_SIZE) {
+    const min = sorted[0];
+    const max = sorted[sorted.length - 1];
+    if (max === min) return safeScores.map((s) => s > 0 ? 1 : 0);
+    return safeScores.map(
+      (s) => s <= 0 ? 0 : Math.max(0, Math.min((s - min) / (max - min), 1))
+    );
+  }
+  const median = sorted[Math.floor(sorted.length / 2)];
+  const absoluteDiffs = positiveScores.map((v) => Math.abs(v - median));
+  const mad = [...absoluteDiffs].sort((a, b) => a - b)[Math.floor(absoluteDiffs.length / 2)];
+  const scale = mad === 0 ? median : mad * NORMALIZATION_MAD_COEFFICIENT;
+  const logisticZ = safeScores.map((s) => {
+    if (s <= 0) return 0;
+    if (scale === 0) return 1;
+    const z = (s - median) / scale;
+    return 1 / (1 + Math.exp(-NORMALIZATION_LOGISTIC_K * z));
+  });
+  const cdf = safeScores.map((s) => {
+    if (s <= 0) return 0;
+    const rank = sorted.findIndex((v) => v >= s);
+    return rank / sorted.length;
+  });
+  return logisticZ.map(
+    (z, i) => z * (1 - NORMALIZATION_ALPHA) + cdf[i] * NORMALIZATION_ALPHA
+  );
+}
+
 // src/utils/min-heap.ts
 var MinHeap = class {
   h = [];
@@ -900,20 +936,6 @@ function pruneTo(graph, frames, targetCount) {
   }
   return surviving;
 }
-function normalizeScores(graph) {
-  if (graph.length === 0) return [];
-  const safeScores = graph.map(
-    (e) => Number.isFinite(e.score) && e.score > 0 ? e.score : 0
-  );
-  const sorted = [...safeScores].filter((s) => s > 0).sort((a, b) => a - b);
-  if (sorted.length === 0) return safeScores;
-  const pIdx = Math.min(
-    Math.floor(sorted.length * NORMALIZATION_PERCENTILE),
-    sorted.length - 1
-  );
-  const refScore = sorted[pIdx];
-  return safeScores.map((s) => Math.min(s / refScore, 1));
-}
 function suppressConsecutiveRuns(graph, passingIndices, normalizedScores) {
   const result = /* @__PURE__ */ new Set();
   let runStart = 0;

package/dist/utils/math.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Interface for objects that have a numeric score.
+ */
+export interface ScoredItem {
+    score: number;
+}
+/**
+ * Normalize raw scores to [0, 1] range via Robust Hybrid Normalization.
+ *
+ * This model combines two mathematical approaches to provide a stable "relative" threshold:
+ *
+ * 1. Logistic-Robust-Z (Intensity):
+ *    Calculates Z-scores using Median and Median Absolute Deviation (MAD).
+ *    Maps these to a sigmoid (logistic) curve. This suppresses noise (scores near median)
+ *    and highlights significant signals (outliers) without letting extreme outliers
+ *    crush other meaningful transitions.
+ *
+ * 2. CDF / Percentile Rank (Relative Position):
+ *    Maps each score to its percentile rank in the sequence. This ensures that 't'
+ *    always has a consistent meaning as a "relative rank" regardless of absolute values.
+ *
+ * The final score is a weighted sum (NORMALIZATION_ALPHA) of both.
+ *
+ * @param items - Array of items with scores to normalize
+ * @returns normalized scores array (same length as input)
+ */
+export declare function normalizeScores<T extends ScoredItem>(items: T[]): number[];

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.8",
   "description": "CLI tool for extracting key frames from video and GIF files",
   "keywords": [
     "cli",