@lumy-pack/scene-sieve 0.0.8 → 0.0.9

package/README.md

@@ -99,6 +99,99 @@ scene-sieve <input> [options]
 | Video     | `.mp4`, `.mov`, `.avi`, `.mkv`, `.webm` |
 | Animation | `.gif`                                  |
 
+### Parameter Tuning Guide
+
+Not sure where to start? Here's how each parameter affects the output, based on real benchmarks with a ~19s screen recording (MOV) and a GIF animation.
+
+#### `--count` — How many frames to keep
+
+| Setting | Extracted | Selected | Notes |
+|---------|-----------|----------|-------|
+| `-n 3` | 90 | 3 | First and last frames are always preserved (boundary protection) |
+| `-n 10` | 90 | 10 | Good for short summaries |
+| `-n 20` (default) | 90 | 20 | Balanced for most videos |
+| `-n 50` | 90 | 22 | Only 22 frames passed the score threshold — count above actual scenes has no effect |
+
+#### `--threshold` — Minimum score to keep a frame
+
+Higher values = stricter filtering = fewer frames.
+
+| Setting | Selected | Notes |
+|---------|----------|-------|
+| `-t 0.1` | 20 | Very permissive — most scene changes pass |
+| `-t 0.3` | 20 | Still permissive for screen recordings |
+| `-t 0.5` (default) | 20 | Capped by the default count of 20 |
+| `-t 0.7` | 19 | Starts filtering subtle changes |
+| `-t 0.9` | 12 | Only major scene transitions survive |
+
+> **Tip**: Use `-t` alone for "give me everything important". Combine with `-n` to set an upper bound (e.g., `-t 0.3 -n 10`).
+
+#### `--fps` and `--max-frames` — Extraction density
+
+These control how many frames are pulled from the video before analysis. More frames = more precision but longer processing.
+
+| Setting | Extracted | Selected | Time |
+|---------|-----------|----------|------|
+| `--fps 1` | 18 | 6 | ~5s |
+| `--fps 5` (default) | 90 | 20 | ~25s |
+| `--fps 10` | 180 | 20 | ~47s |
+| `-mf 50` | 47 | 13 | ~13s |
+
+> **Tip**: For quick previews, `--fps 1` is 5x faster. For frame-accurate analysis, `--fps 10` captures finer transitions.
+
+#### `--scale` — Analysis resolution
+
+Controls the resolution used for vision analysis (not output resolution). Lower = faster but less sensitive.
+
+| Setting | Selected | Time | Output Size |
+|---------|----------|------|-------------|
+| `-s 360` | 7 | ~6s | 72 KB |
+| `-s 720` (default) | 20 | ~25s | 634 KB |
+| `-s 1080` | 20 | ~54s | 1,172 KB |
+
+> **Tip**: `360` is good for quick scans. `720` provides the best speed/quality balance. `1080` is only needed when detecting very subtle UI changes.
+
+#### `--iou-threshold` and `--anim-threshold` — Animation sensitivity
+
+These control how aggressively repeating animations (spinners, blinking cursors) are detected and suppressed.
+
+| Setting | Animations Detected | Notes |
+|---------|-------------------|-------|
+| `-it 0.5 -at 3` | 7 (MOV), 4 (GIF) | Sensitive — catches most repeating motion |
+| `-it 0.9 -at 5` (default) | 0 | Conservative — only obvious loops |
+| `-it 0.95 -at 10` | 0 | Very conservative |
+
+> **Tip**: If your video has loading spinners or repeated UI animations, try `-it 0.5 -at 3` to suppress them.
+
+#### `--quality` — Output JPEG quality
+
+Only affects file size, **not** scene detection. The same frames are selected regardless of quality.
+
+| Setting | File Size (5 frames) |
+|---------|---------------------|
+| `-q 30` | 62 KB |
+| `-q 80` (default) | 151 KB |
+| `-q 100` | 407 KB |
+
+### Recommended Presets
+
+```bash
+# Quick preview — fast, rough selection
+scene-sieve input.mp4 --fps 1 -s 360 -n 10
+
+# Balanced (default) — good for most use cases
+scene-sieve input.mp4
+
+# High precision — catches subtle transitions
+scene-sieve input.mp4 --fps 10 -s 1080 -t 0.3
+
+# UI recording — suppress animations, keep key states
+scene-sieve recording.mov -it 0.5 -at 3 -t 0.3 -n 15
+
+# Minimal summary — just the major scenes
+scene-sieve input.mp4 -t 0.9 -n 5
+```
+
 ### Examples
 
 ```bash

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_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 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, DEFAULT_MAX_SEGMENT_DURATION, DEFAULT_SEGMENT_CONCURRENCY;
 var init_constants = __esm({
   "src/constants.ts"() {
     "use strict";
@@ -81,6 +81,8 @@ var init_constants = __esm({
     PIXELDIFF_BINARY_THRESHOLD = 30;
     PIXELDIFF_CONTOUR_MIN_AREA = 100;
     PIXELDIFF_SAMPLE_SPACING = 8;
+    DEFAULT_MAX_SEGMENT_DURATION = 300;
+    DEFAULT_SEGMENT_CONCURRENCY = 2;
   }
 });
 
@@ -693,6 +695,23 @@ async function buildFrameList(framesDir, duration) {
     extractPath: join2(framesDir, file)
   }));
 }
+async function extractFramesForRange(inputPath, outputDir, fps, scale, startTime, duration) {
+  const outputPattern = join2(outputDir, FRAME_FILENAME_PATTERN);
+  await execa(ffmpegPath, [
+    "-ss",
+    String(startTime),
+    "-i",
+    inputPath,
+    "-t",
+    String(duration),
+    "-vf",
+    `fps=${fps},scale=-1:${scale}`,
+    "-q:v",
+    "2",
+    outputPattern
+  ]);
+  return buildFrameList(outputDir, duration);
+}
 var init_extractor = __esm({
   "src/core/extractor.ts"() {
     "use strict";
@@ -760,6 +779,15 @@ async function finalizeOutput(ctx, selectedFrames) {
   await rename(stagingDir, outputPath);
   return outputFiles;
 }
+async function createSegmentWorkspace(parentWorkspacePath, segmentIndex) {
+  const segmentPath = join3(
+    parentWorkspacePath,
+    "segments",
+    String(segmentIndex)
+  );
+  await ensureDir(join3(segmentPath, "frames"));
+  return segmentPath;
+}
 async function cleanupWorkspace(workspacePath) {
   if (!workspacePath) return;
   try {
@@ -844,7 +872,9 @@ function resolveOptions(options) {
     quality: options.quality ?? DEFAULT_QUALITY,
     iouThreshold: options.iouThreshold ?? IOU_THRESHOLD,
     animationThreshold: options.animationThreshold ?? ANIMATION_FRAME_THRESHOLD,
-    debug: options.debug ?? false
+    debug: options.debug ?? false,
+    maxSegmentDuration: options.maxSegmentDuration ?? DEFAULT_MAX_SEGMENT_DURATION,
+    concurrency: options.concurrency ?? DEFAULT_SEGMENT_CONCURRENCY
   };
 }
 async function resolveInput(options, workspacePath) {
@@ -1123,18 +1153,381 @@ var init_pruner = __esm({
   }
 });
 
+// src/utils/concurrency.ts
+function concurrencyLimit(limit) {
+  limit = Math.max(1, limit);
+  let active = 0;
+  const queue = [];
+  return async (fn) => {
+    while (active >= limit) {
+      await new Promise((resolve2) => queue.push(resolve2));
+    }
+    active++;
+    try {
+      return await fn();
+    } finally {
+      active--;
+      queue.shift()?.();
+    }
+  };
+}
+var init_concurrency = __esm({
+  "src/utils/concurrency.ts"() {
+    "use strict";
+  }
+});
+
+// src/core/segmenter.ts
+import { randomUUID } from "crypto";
+import { join as join5 } from "path";
+function shouldSegment(resolvedOptions, originalOptions) {
+  if (resolvedOptions.mode === "frames") return false;
+  if (originalOptions.mode === "file") {
+    if (originalOptions.inputPath.toLowerCase().endsWith(".gif")) return false;
+  }
+  return true;
+}
+function computeSegmentPlan(totalDuration, maxSegmentDuration, maxFrames, fps) {
+  const effectiveFps = Math.max(0.5, Math.min(fps, maxFrames / totalDuration));
+  if (totalDuration <= maxSegmentDuration) {
+    return [
+      {
+        index: 0,
+        startTime: 0,
+        endTime: totalDuration,
+        duration: totalDuration,
+        allocatedFrames: Math.min(
+          Math.ceil(effectiveFps * totalDuration),
+          maxFrames
+        ),
+        effectiveFps,
+        overlapBefore: 0,
+        overlapAfter: 0,
+        extractStartTime: 0,
+        extractDuration: totalDuration
+      }
+    ];
+  }
+  const segmentCount = Math.ceil(totalDuration / maxSegmentDuration);
+  const overlapTime = 1 / effectiveFps;
+  const segments = [];
+  for (let i = 0; i < segmentCount; i++) {
+    const startTime = i * maxSegmentDuration;
+    const endTime = Math.min((i + 1) * maxSegmentDuration, totalDuration);
+    const duration = endTime - startTime;
+    const overlapBefore = i > 0 ? 1 : 0;
+    const overlapAfter = i < segmentCount - 1 ? 1 : 0;
+    const extractStartTime = Math.max(
+      0,
+      startTime - overlapBefore * overlapTime
+    );
+    const extractEndTime = Math.min(
+      totalDuration,
+      endTime + overlapAfter * overlapTime
+    );
+    const extractDuration = extractEndTime - extractStartTime;
+    segments.push({
+      index: i,
+      startTime,
+      endTime,
+      duration,
+      allocatedFrames: Math.ceil(effectiveFps * duration),
+      effectiveFps,
+      overlapBefore,
+      overlapAfter,
+      extractStartTime,
+      extractDuration
+    });
+  }
+  const totalAllocated = segments.reduce(
+    (sum, s) => sum + s.allocatedFrames,
+    0
+  );
+  if (totalAllocated > maxFrames) {
+    segments[segments.length - 1].allocatedFrames -= totalAllocated - maxFrames;
+  }
+  return segments;
+}
+function mergeSegmentFrames(segmentResults) {
+  if (segmentResults.length === 0) {
+    return { frames: [], edges: [], animations: [] };
+  }
+  const allFrames = [];
+  for (const result of segmentResults) {
+    for (const frame of result.frames) {
+      allFrames.push({
+        frame: {
+          ...frame,
+          // Use extractStartTime for timestamp correction (Section 18 note 1)
+          timestamp: frame.timestamp + result.segment.extractStartTime
+        },
+        segmentIndex: result.segment.index,
+        localId: frame.id
+      });
+    }
+  }
+  allFrames.sort((a, b) => a.frame.timestamp - b.frame.timestamp);
+  const effectiveFps = segmentResults[0].segment.effectiveFps;
+  const dupThreshold = 1 / (effectiveFps * 2);
+  const uniqueFrames = [];
+  for (const entry of allFrames) {
+    if (uniqueFrames.length > 0) {
+      const last = uniqueFrames[uniqueFrames.length - 1];
+      if (Math.abs(entry.frame.timestamp - last.frame.timestamp) < dupThreshold) {
+        continue;
+      }
+    }
+    uniqueFrames.push(entry);
+  }
+  const globalIdMap = /* @__PURE__ */ new Map();
+  const frames = uniqueFrames.map((entry, globalId) => {
+    globalIdMap.set(`${entry.segmentIndex}:${entry.localId}`, globalId);
+    return {
+      id: globalId,
+      timestamp: entry.frame.timestamp,
+      extractPath: entry.frame.extractPath
+    };
+  });
+  const edges = [];
+  const edgeMap = /* @__PURE__ */ new Map();
+  for (const result of segmentResults) {
+    for (const edge of result.edges) {
+      const newSourceId = globalIdMap.get(
+        `${result.segment.index}:${edge.sourceId}`
+      );
+      const newTargetId = globalIdMap.get(
+        `${result.segment.index}:${edge.targetId}`
+      );
+      if (newSourceId === void 0 || newTargetId === void 0) continue;
+      const edgeKey = `${newSourceId}-${newTargetId}`;
+      const existingIdx = edgeMap.get(edgeKey);
+      if (existingIdx !== void 0) {
+        if (edges[existingIdx].score < edge.score) {
+          edges[existingIdx] = {
+            sourceId: newSourceId,
+            targetId: newTargetId,
+            score: edge.score
+          };
+        }
+      } else {
+        edgeMap.set(edgeKey, edges.length);
+        edges.push({
+          sourceId: newSourceId,
+          targetId: newTargetId,
+          score: edge.score
+        });
+      }
+    }
+  }
+  const animations = [];
+  for (const result of segmentResults) {
+    for (const anim of result.animations) {
+      const newStartId = globalIdMap.get(
+        `${result.segment.index}:${anim.startFrameId}`
+      );
+      const newEndId = globalIdMap.get(
+        `${result.segment.index}:${anim.endFrameId}`
+      );
+      if (newStartId === void 0 || newEndId === void 0) continue;
+      animations.push({
+        ...anim,
+        startFrameId: newStartId,
+        endFrameId: newEndId
+      });
+    }
+  }
+  return { frames, edges, animations };
+}
+function buildSegmentContext(segment, frames, segmentWorkspacePath, resolvedOptions, onProgress) {
+  return {
+    options: {
+      ...resolvedOptions,
+      fps: segment.effectiveFps,
+      maxFrames: segment.allocatedFrames
+    },
+    workspacePath: segmentWorkspacePath,
+    frames,
+    graph: [],
+    status: "ANALYZING",
+    emitProgress: onProgress
+  };
+}
+async function processSegment(inputPath, segment, workspacePath, resolvedOptions, onProgress) {
+  const framesDir = join5(workspacePath, "frames");
+  const frames = await extractFramesForRange(
+    inputPath,
+    framesDir,
+    segment.effectiveFps,
+    resolvedOptions.scale,
+    segment.extractStartTime,
+    segment.extractDuration
+  );
+  if (frames.length < 2) {
+    return { segment, frames, edges: [], animations: [] };
+  }
+  const ctx = buildSegmentContext(
+    segment,
+    frames,
+    workspacePath,
+    resolvedOptions,
+    onProgress
+  );
+  const { edges, animations } = await analyzeFrames(ctx);
+  return { segment, frames, edges, animations };
+}
+async function runSegmentedPipeline(options, resolvedOptions) {
+  const pipelineStart = Date.now();
+  const sessionId = randomUUID();
+  let mainWorkspace = "";
+  try {
+    mainWorkspace = await createWorkspace(sessionId);
+    logger.debug(`Segmented pipeline: workspace at ${mainWorkspace}`);
+    const { resolvedInputPath } = await resolveInput(options, mainWorkspace);
+    const inputPath = resolvedInputPath ?? resolvedOptions.inputPath;
+    if (!inputPath) {
+      throw new Error("No input path available for segmented pipeline");
+    }
+    const metadata = await getVideoMetadata(inputPath);
+    const totalDuration = parseFloat(metadata.format?.duration ?? "0");
+    if (totalDuration <= 0) {
+      throw new Error(`Invalid video duration: ${totalDuration}`);
+    }
+    logger.debug(`Video duration: ${totalDuration}s`);
+    const segments = computeSegmentPlan(
+      totalDuration,
+      resolvedOptions.maxSegmentDuration,
+      resolvedOptions.maxFrames,
+      resolvedOptions.fps
+    );
+    logger.debug(`Segment plan: ${segments.length} segments`);
+    const limit = concurrencyLimit(resolvedOptions.concurrency);
+    const segmentProgresses = new Array(segments.length).fill(0);
+    const weights = segments.map((s) => s.duration / totalDuration);
+    const emitOverallProgress = (phase) => {
+      if (!options.onProgress) return;
+      const overall = weights.reduce(
+        (sum, w, i) => sum + w * (segmentProgresses[i] ?? 0),
+        0
+      );
+      options.onProgress(phase, Math.min(100, overall));
+    };
+    options.onProgress?.("EXTRACTING", 0);
+    const results = await Promise.all(
+      segments.map(
+        (segment) => limit(async () => {
+          const segWorkspace = await createSegmentWorkspace(
+            mainWorkspace,
+            segment.index
+          );
+          const result = await processSegment(
+            inputPath,
+            segment,
+            segWorkspace,
+            resolvedOptions,
+            (percent) => {
+              segmentProgresses[segment.index] = percent;
+              emitOverallProgress("ANALYZING");
+            }
+          );
+          return result;
+        })
+      )
+    );
+    options.onProgress?.("ANALYZING", 100);
+    const { frames, edges, animations } = mergeSegmentFrames(results);
+    logger.debug(
+      `Merged: ${frames.length} frames, ${edges.length} edges, ${animations.length} animations`
+    );
+    options.onProgress?.("PRUNING", 0);
+    const survivingIds = pruneByThresholdWithCap(
+      edges,
+      frames,
+      resolvedOptions.threshold,
+      resolvedOptions.count
+    );
+    const prunedFrames = frames.filter((f) => survivingIds.has(f.id));
+    options.onProgress?.("PRUNING", 100);
+    options.onProgress?.("FINALIZING", 0);
+    const ctx = {
+      options: resolvedOptions,
+      workspacePath: mainWorkspace,
+      frames,
+      graph: edges,
+      animations,
+      status: "FINALIZING",
+      emitProgress: (percent) => options.onProgress?.("FINALIZING", percent)
+    };
+    let outputFiles = [];
+    let outputBuffers;
+    if (resolvedOptions.mode === "buffer" || resolvedOptions.mode === "frames") {
+      outputBuffers = await readFramesAsBuffers(
+        prunedFrames,
+        resolvedOptions.quality
+      );
+    } else {
+      outputFiles = await finalizeOutput(ctx, prunedFrames);
+    }
+    options.onProgress?.("FINALIZING", 100);
+    logger.success(
+      `Segmented pipeline: ${prunedFrames.length} scenes from ${frames.length} frames (${segments.length} segments)`
+    );
+    return {
+      success: true,
+      originalFramesCount: frames.length,
+      prunedFramesCount: prunedFrames.length,
+      outputFiles,
+      outputBuffers,
+      animations,
+      video: {
+        originalDurationMs: totalDuration * 1e3,
+        fps: resolvedOptions.fps,
+        resolution: {
+          width: resolvedOptions.scale,
+          height: Math.round(resolvedOptions.scale * 9 / 16)
+        }
+      },
+      executionTimeMs: Date.now() - pipelineStart
+    };
+  } catch (error) {
+    const err = error instanceof Error ? error : new Error(String(error));
+    logger.error(`Segmented pipeline failed: ${err.message}`);
+    throw err;
+  } finally {
+    if (!resolvedOptions.debug) {
+      await cleanupWorkspace(mainWorkspace);
+    } else {
+      logger.debug(`Debug mode: workspace preserved at ${mainWorkspace}`);
+    }
+  }
+}
+var init_segmenter = __esm({
+  "src/core/segmenter.ts"() {
+    "use strict";
+    init_concurrency();
+    init_logger();
+    init_analyzer();
+    init_extractor();
+    init_input_resolver();
+    init_pruner();
+    init_workspace();
+  }
+});
+
 // src/core/orchestrator.ts
 var orchestrator_exports = {};
 __export(orchestrator_exports, {
   runPipeline: () => runPipeline
 });
-import { randomUUID } from "crypto";
+import { randomUUID as randomUUID2 } from "crypto";
 async function runPipeline(options) {
-  const startTime = Date.now();
-  const sessionId = randomUUID();
   const debug = options.debug ?? false;
   if (debug) setDebugMode(true);
   const resolvedOptions = resolveOptions(options);
+  if (shouldSegment(resolvedOptions, options)) {
+    return runSegmentedPipeline(options, resolvedOptions);
+  }
+  const startTime = Date.now();
+  const sessionId = randomUUID2();
   const ctx = {
     options: resolvedOptions,
     workspacePath: "",
@@ -1236,6 +1629,7 @@ var init_orchestrator = __esm({
     init_extractor();
     init_input_resolver();
     init_pruner();
+    init_segmenter();
     init_workspace();
   }
 });
@@ -1310,7 +1704,7 @@ var PhaseStep = ({ phase }) => {
 };
 
 // src/core/run-in-worker.ts
-import { dirname, join as join5 } from "path";
+import { dirname, join as join6 } from "path";
 import { fileURLToPath } from "url";
 import { Worker } from "worker_threads";
 async function runPipelineInWorker(options, onProgress) {
@@ -1319,7 +1713,7 @@ async function runPipelineInWorker(options, onProgress) {
     const { runPipeline: runPipeline2 } = await Promise.resolve().then(() => (init_orchestrator(), orchestrator_exports));
     return runPipeline2({ ...options, onProgress });
   }
-  const workerPath = join5(dirname(currentFile), "pipeline-worker.mjs");
+  const workerPath = join6(dirname(currentFile), "pipeline-worker.mjs");
   return new Promise((resolve2, reject) => {
     const worker = new Worker(workerPath, { workerData: options });
     worker.on(
@@ -1397,6 +1791,8 @@ var SieveView = (props) => {
             quality: props.quality,
             iouThreshold: props.iouThreshold,
             animationThreshold: props.animationThreshold,
+            maxSegmentDuration: props.maxSegmentDuration,
+            concurrency: props.concurrency,
             debug: props.debug
           },
           (phase, percent) => {
@@ -1544,6 +1940,12 @@ program.name("scene-sieve").description("Extract key frames from video and GIF f
 ).option(
   "-at, --anim-threshold <number>",
   `Min consecutive frames for animation (default: ${ANIMATION_FRAME_THRESHOLD})`
+).option(
+  "--max-segment-duration <number>",
+  `Max segment duration in seconds for long video splitting (default: ${DEFAULT_MAX_SEGMENT_DURATION})`
+).option(
+  "--concurrency <number>",
+  `Number of segments to process in parallel (default: ${DEFAULT_SEGMENT_CONCURRENCY})`
 ).option("--debug", "Enable debug mode (preserve temp workspace)").action(async (input, opts) => {
   const { waitUntilExit } = render(
     React2.createElement(SieveView, {
@@ -1557,6 +1959,8 @@ program.name("scene-sieve").description("Extract key frames from video and GIF f
       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,
+      maxSegmentDuration: opts.maxSegmentDuration !== void 0 ? parseInt(opts.maxSegmentDuration, 10) : void 0,
+      concurrency: opts.concurrency !== void 0 ? parseInt(opts.concurrency, 10) : void 0,
       debug: opts.debug ?? false
     })
   );

package/dist/commands/Sieve.d.ts

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

package/dist/constants.d.ts

@@ -27,4 +27,6 @@ export declare const PIXELDIFF_GAUSSIAN_KERNEL = 3;
 export declare const PIXELDIFF_BINARY_THRESHOLD = 30;
 export declare const PIXELDIFF_CONTOUR_MIN_AREA = 100;
 export declare const PIXELDIFF_SAMPLE_SPACING = 8;
+export declare const DEFAULT_MAX_SEGMENT_DURATION = 300;
+export declare const DEFAULT_SEGMENT_CONCURRENCY = 2;
 export declare function getTempWorkspaceDir(sessionId: string): string;

package/dist/core/extractor.d.ts

@@ -1,7 +1,30 @@
 import type { FrameNode, ProcessContext } from '../types/index.js';
+export interface FFprobeMetadata {
+    format?: {
+        format_name?: string;
+        duration?: string;
+    };
+    streams?: Array<{
+        codec_type?: string;
+    }>;
+}
 /**
  * Extract frames from video/GIF using FFmpeg.
  * Always uses FPS-based extraction. For long videos, FPS is automatically
  * reduced to stay within maxFrames budget.
  */
 export declare function extractFrames(ctx: ProcessContext): Promise<FrameNode[]>;
+export declare function getVideoMetadata(inputPath: string): Promise<FFprobeMetadata>;
+/**
+ * Extract frames from a specific time range of a video using FFmpeg.
+ * Uses input seeking (-ss before -i) for fast seek + -t for duration.
+ *
+ * @param inputPath - Path to the video file
+ * @param outputDir - Directory to write extracted frames
+ * @param fps - Frames per second for extraction
+ * @param scale - Height scale for vision analysis
+ * @param startTime - Start time in seconds
+ * @param duration - Duration in seconds to extract
+ * @returns Array of FrameNode with segment-local timestamps (starting from 0)
+ */
+export declare function extractFramesForRange(inputPath: string, outputDir: string, fps: number, scale: number, startTime: number, duration: number): Promise<FrameNode[]>;

package/dist/core/index.d.ts

@@ -5,4 +5,5 @@ export { pruneTo, pruneByThreshold, pruneByThresholdWithCap, suppressConsecutive
 export { dbscan } from './dbscan.js';
 export type { Point2D } from './dbscan.js';
 export { resolveInput, resolveOptions } from './input-resolver.js';
-export { createWorkspace, cleanupWorkspace, finalizeOutput, readFramesAsBuffers, writeInputBuffer, writeInputFrames, } from './workspace.js';
+export { shouldSegment, computeSegmentPlan, processSegment, mergeSegmentFrames, runSegmentedPipeline, } from './segmenter.js';
+export { createWorkspace, createSegmentWorkspace, cleanupWorkspace, finalizeOutput, readFramesAsBuffers, writeInputBuffer, writeInputFrames, } from './workspace.js';