@lumy-pack/scene-sieve 0.0.8 → 0.0.10

package/dist/cli.mjs

@@ -9,49 +9,13 @@ var __export = (target, all) => {
     __defProp(target, name, { get: all[name], enumerable: true });
 };
 
-// src/utils/logger.ts
-import pc from "picocolors";
-function setDebugMode(enabled) {
-  debugMode = enabled;
-}
-function timestamp() {
-  return (/* @__PURE__ */ new Date()).toLocaleTimeString("en-US", { hour12: false });
-}
-var debugMode, logger;
-var init_logger = __esm({
-  "src/utils/logger.ts"() {
-    "use strict";
-    debugMode = false;
-    logger = {
-      info(message) {
-        console.log(`${pc.blue("info")} ${message}`);
-      },
-      success(message) {
-        console.log(`
-${pc.green("done")} ${message}`);
-      },
-      warn(message) {
-        console.warn(`${pc.yellow("warn")} ${message}`);
-      },
-      error(message) {
-        console.error(`${pc.red("error")} ${message}`);
-      },
-      debug(message) {
-        if (debugMode) {
-          console.log(`${pc.gray(`[${timestamp()}] debug`)} ${message}`);
-        }
-      }
-    };
-  }
-});
-
 // src/constants.ts
 import { tmpdir } from "os";
 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 +45,44 @@ 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;
+  }
+});
+
+// src/utils/logger.ts
+import pc from "picocolors";
+function setDebugMode(enabled) {
+  debugMode = enabled;
+}
+function timestamp() {
+  return (/* @__PURE__ */ new Date()).toLocaleTimeString("en-US", { hour12: false });
+}
+var debugMode, logger;
+var init_logger = __esm({
+  "src/utils/logger.ts"() {
+    "use strict";
+    debugMode = false;
+    logger = {
+      info(message) {
+        console.log(`${pc.blue("info")} ${message}`);
+      },
+      success(message) {
+        console.log(`
+${pc.green("done")} ${message}`);
+      },
+      warn(message) {
+        console.warn(`${pc.yellow("warn")} ${message}`);
+      },
+      error(message) {
+        console.error(`${pc.red("error")} ${message}`);
+      },
+      debug(message) {
+        if (debugMode) {
+          console.log(`${pc.gray(`[${timestamp()}] debug`)} ${message}`);
+        }
+      }
+    };
   }
 });
 
@@ -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 collectAllFrames(segmentResults) {
+  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
+      });
+    }
+  }
+  return allFrames;
+}
+function deduplicateFrames(frames, effectiveFps) {
+  frames.sort((a, b) => a.frame.timestamp - b.frame.timestamp);
+  const dupThreshold = 1 / (effectiveFps * 2);
+  const unique = [];
+  for (const entry of frames) {
+    if (unique.length > 0) {
+      const last = unique[unique.length - 1];
+      if (Math.abs(entry.frame.timestamp - last.frame.timestamp) < dupThreshold) {
+        continue;
+      }
+    }
+    unique.push(entry);
+  }
+  return unique;
+}
+function remapFrameIds(uniqueFrames) {
+  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
+    };
+  });
+  return { frames, globalIdMap };
+}
+function remapEdges(segmentResults, globalIdMap) {
+  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 });
+      }
+    }
+  }
+  return edges;
+}
+function remapAnimations(segmentResults, globalIdMap) {
+  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 animations;
+}
+function mergeSegmentFrames(segmentResults) {
+  if (segmentResults.length === 0) {
+    return { frames: [], edges: [], animations: [] };
+  }
+  const effectiveFps = segmentResults[0].segment.effectiveFps;
+  const allFrames = collectAllFrames(segmentResults);
+  const uniqueFrames = deduplicateFrames(allFrames, effectiveFps);
+  const { frames, globalIdMap } = remapFrameIds(uniqueFrames);
+  const edges = remapEdges(segmentResults, globalIdMap);
+  const animations = remapAnimations(segmentResults, globalIdMap);
+  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();
   }
 });
@@ -1243,12 +1637,41 @@ var init_orchestrator = __esm({
 // src/cli.ts
 import { createRequire as createRequire2 } from "module";
 import { Command } from "commander";
-import { render } from "ink";
-import React2 from "react";
+
+// ../shared/src/respond.ts
+function respond(command, data, startTime, version2) {
+  const response = {
+    ok: true,
+    command,
+    data,
+    meta: {
+      version: version2,
+      durationMs: Date.now() - startTime,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    }
+  };
+  process.stdout.write(JSON.stringify(response) + "\n");
+}
+function respondError(command, code, message, startTime, version2, details) {
+  const response = {
+    ok: false,
+    command,
+    error: { code, message, ...details !== void 0 ? { details } : {} },
+    meta: {
+      version: version2,
+      durationMs: Date.now() - startTime,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    }
+  };
+  process.stdout.write(JSON.stringify(response) + "\n");
+  process.exitCode = 1;
+}
 
 // src/commands/Sieve.tsx
+import { existsSync } from "fs";
 import { Box as Box2, Text as Text3, useApp } from "ink";
-import { useEffect, useState } from "react";
+import { render } from "ink";
+import React, { useEffect, useState } from "react";
 
 // src/components/PhaseStep.tsx
 import { Box, Text as Text2 } from "ink";
@@ -1309,8 +1732,12 @@ var PhaseStep = ({ phase }) => {
   ] });
 };
 
+// src/commands/Sieve.tsx
+init_constants();
+init_orchestrator();
+
 // 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 +1746,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(
@@ -1347,6 +1774,145 @@ async function runPipelineInWorker(options, onProgress) {
 
 // src/commands/Sieve.tsx
 init_workspace();
+
+// src/errors.ts
+var SieveErrorCode = {
+  INVALID_INPUT: "INVALID_INPUT",
+  FILE_NOT_FOUND: "FILE_NOT_FOUND",
+  INVALID_FORMAT: "INVALID_FORMAT",
+  PIPELINE_ERROR: "PIPELINE_ERROR",
+  WORKER_ERROR: "WORKER_ERROR",
+  UNKNOWN: "UNKNOWN"
+};
+function classifyError(error) {
+  const msg = error.message.toLowerCase();
+  if (error.code === "ENOENT" || msg.includes("not found")) {
+    return SieveErrorCode.FILE_NOT_FOUND;
+  } else if (msg.includes("no video stream") || msg.includes("invalid format")) {
+    return SieveErrorCode.INVALID_FORMAT;
+  } else if (msg.includes("worker")) {
+    return SieveErrorCode.WORKER_ERROR;
+  } else {
+    return SieveErrorCode.PIPELINE_ERROR;
+  }
+}
+
+// src/utils/command-registry.ts
+var SIEVE_COMMAND = {
+  name: "scene-sieve",
+  description: "Extract key frames from video and GIF files",
+  usage: "scene-sieve <input> [options]",
+  arguments: [
+    {
+      name: "input",
+      description: "Input video or GIF file path",
+      required: true
+    }
+  ],
+  options: [
+    {
+      flag: "-n, --count <number>",
+      description: "Max number of frames to keep (default: 20)",
+      type: "number"
+    },
+    {
+      flag: "-t, --threshold <number>",
+      description: "Normalized threshold 0~1 (default: 0.5; keeps frames above ratio of max change)",
+      type: "number"
+    },
+    {
+      flag: "-o, --output <path>",
+      description: "Output directory path",
+      type: "string"
+    },
+    {
+      flag: "--fps <number>",
+      description: "Max FPS for frame extraction",
+      type: "number",
+      default: "5"
+    },
+    {
+      flag: "-mf, --max-frames <number>",
+      description: "Max frames to extract (auto-reduces FPS for long videos)",
+      type: "number",
+      default: "300"
+    },
+    {
+      flag: "-s, --scale <number>",
+      description: "Scale size for vision analysis",
+      type: "number",
+      default: "720"
+    },
+    {
+      flag: "-q, --quality <number>",
+      description: "JPEG output quality 1-100",
+      type: "number",
+      default: "80"
+    },
+    {
+      flag: "-it, --iou-threshold <number>",
+      description: "IoU threshold for animation tracking (0-1) (default: 0.9)",
+      type: "number"
+    },
+    {
+      flag: "-at, --anim-threshold <number>",
+      description: "Min consecutive frames for animation (default: 5)",
+      type: "number"
+    },
+    {
+      flag: "--max-segment-duration <number>",
+      description: "Max segment duration in seconds for long video splitting (default: 300)",
+      type: "number"
+    },
+    {
+      flag: "--concurrency <number>",
+      description: "Number of segments to process in parallel (default: 2)",
+      type: "number"
+    },
+    {
+      flag: "--debug",
+      description: "Enable debug mode (preserve temp workspace)",
+      type: "boolean"
+    },
+    {
+      flag: "--json",
+      description: "Output structured JSON to stdout",
+      type: "boolean"
+    },
+    {
+      flag: "--describe",
+      description: "Output JSON schema of available options",
+      type: "boolean"
+    }
+  ],
+  examples: [
+    "scene-sieve video.mp4",
+    "scene-sieve video.mp4 -n 10",
+    "scene-sieve video.mp4 -t 0.3 -o ./output",
+    "scene-sieve video.mp4 --json",
+    "scene-sieve --describe"
+  ]
+};
+
+// src/utils/parse-options.ts
+function parsePipelineOptions(opts) {
+  return {
+    ...opts.threshold !== void 0 ? { threshold: parseFloat(opts.threshold) } : {},
+    ...opts.count !== void 0 ? { count: parseInt(opts.count, 10) } : {},
+    outputPath: opts.output,
+    fps: parseInt(opts.fps, 10),
+    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,
+    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
+  };
+}
+
+// src/commands/Sieve.tsx
 import { jsx as jsx3, jsxs as jsxs3 } from "react/jsx-runtime";
 var PHASE_DEFS = [
   { key: "INIT", label: "Initializing workspace", hasProgress: false },
@@ -1366,6 +1932,78 @@ function createInitialPhases() {
 function phaseKeyToIndex(phase) {
   return PHASE_DEFS.findIndex((d) => d.key === phase);
 }
+function registerSieveCommand(program2, version2) {
+  const cmd = SIEVE_COMMAND;
+  program2.argument("<input>", cmd.arguments[0].description).option("-n, --count <number>", cmd.options.find((o) => o.flag.includes("--count")).description).option(
+    "-t, --threshold <number>",
+    cmd.options.find((o) => o.flag.includes("--threshold")).description
+  ).option("-o, --output <path>", cmd.options.find((o) => o.flag.includes("--output")).description).option("--fps <number>", cmd.options.find((o) => o.flag.includes("--fps")).description, String(DEFAULT_FPS)).option(
+    "-mf, --max-frames <number>",
+    cmd.options.find((o) => o.flag.includes("--max-frames")).description,
+    String(DEFAULT_MAX_FRAMES)
+  ).option(
+    "-s, --scale <number>",
+    cmd.options.find((o) => o.flag.includes("--scale")).description,
+    String(DEFAULT_SCALE)
+  ).option(
+    "-q, --quality <number>",
+    cmd.options.find((o) => o.flag.includes("--quality")).description,
+    String(DEFAULT_QUALITY)
+  ).option(
+    "-it, --iou-threshold <number>",
+    cmd.options.find((o) => o.flag.includes("--iou-threshold")).description
+  ).option(
+    "-at, --anim-threshold <number>",
+    cmd.options.find((o) => o.flag.includes("--anim-threshold")).description
+  ).option(
+    "--max-segment-duration <number>",
+    cmd.options.find((o) => o.flag.includes("--max-segment-duration")).description
+  ).option(
+    "--concurrency <number>",
+    cmd.options.find((o) => o.flag.includes("--concurrency")).description
+  ).option("--debug", cmd.options.find((o) => o.flag.includes("--debug")).description).option("--json", cmd.options.find((o) => o.flag.includes("--json")).description).option("--describe", cmd.options.find((o) => o.flag.includes("--describe")).description).action(async (input, opts) => {
+    const parsed = parsePipelineOptions(opts);
+    if (opts.json) {
+      const startTime = Date.now();
+      if (!existsSync(input)) {
+        respondError("extract", SieveErrorCode.FILE_NOT_FOUND, `File not found: ${input}`, startTime, version2);
+        return;
+      }
+      try {
+        const result = await runPipeline({
+          mode: "file",
+          inputPath: input,
+          ...parsed,
+          onProgress: (phase, percent) => {
+            process.stderr.write(JSON.stringify({ phase, percent }) + "\n");
+          }
+        });
+        const data = {
+          success: result.success,
+          originalFrames: result.originalFramesCount,
+          selectedFrames: result.prunedFramesCount,
+          outputFiles: result.outputFiles,
+          animations: result.animations ?? [],
+          video: result.video ?? null
+        };
+        respond("extract", data, startTime, version2);
+      } catch (error) {
+        const err = error instanceof Error ? error : new Error(String(error));
+        respondError("extract", classifyError(err), err.message, startTime, version2);
+      }
+      return;
+    }
+    const { outputPath, ...viewOpts } = parsed;
+    const { waitUntilExit } = render(
+      React.createElement(SieveView, {
+        input,
+        ...viewOpts,
+        output: outputPath
+      })
+    );
+    await waitUntilExit();
+  });
+}
 var SieveView = (props) => {
   const { exit } = useApp();
   const [phases, setPhases] = useState(createInitialPhases);
@@ -1397,6 +2035,8 @@ var SieveView = (props) => {
             quality: props.quality,
             iouThreshold: props.iouThreshold,
             animationThreshold: props.animationThreshold,
+            maxSegmentDuration: props.maxSegmentDuration,
+            concurrency: props.concurrency,
             debug: props.debug
           },
           (phase, percent) => {
@@ -1519,50 +2159,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", String(DEFAULT_FPS)).option(
-  "-mf, --max-frames <number>",
-  "Max frames to extract (auto-reduces FPS for long videos)",
-  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,
-      ...opts.threshold !== void 0 ? { threshold: parseFloat(opts.threshold) } : {},
-      ...opts.count !== void 0 ? { count: parseInt(opts.count, 10) } : {},
-      output: opts.output,
-      fps: parseInt(opts.fps, 10),
-      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
-    })
+program.name("scene-sieve").description("Extract key frames from video and GIF files").version(version);
+registerSieveCommand(program, version);
+if (process.argv.includes("--describe")) {
+  const startTime = Date.now();
+  respond(
+    "describe",
+    {
+      name: SIEVE_COMMAND.name,
+      version,
+      description: SIEVE_COMMAND.description,
+      arguments: SIEVE_COMMAND.arguments,
+      options: SIEVE_COMMAND.options
+    },
+    startTime,
+    version
   );
-  await waitUntilExit();
-});
+  process.exit(0);
+}
 program.parseAsync(process.argv).catch((error) => {
-  console.error("Fatal error:", error.message);
+  if (process.argv.includes("--json")) {
+    respondError("extract", SieveErrorCode.UNKNOWN, error.message, Date.now(), version);
+  } else {
+    console.error("Fatal error:", error.message);
+  }
   process.exit(1);
 });