@lumy-pack/scene-sieve 0.0.8 → 0.0.9

package/dist/core/segmenter.d.ts

@@ -0,0 +1,38 @@
+import type { AnimationMetadata, FrameNode, ResolvedOptions, ScoreEdge, SegmentPlan, SegmentResult, SieveOptions, SieveResult } from '../types/index.js';
+/**
+ * Determine whether segmentation should be used.
+ * Returns false for frames mode and GIF files.
+ * Actual duration check happens inside runSegmentedPipeline after metadata fetch.
+ */
+export declare function shouldSegment(resolvedOptions: ResolvedOptions, originalOptions: SieveOptions): boolean;
+/**
+ * Compute segment boundaries with overlap, frame allocation, and effectiveFps.
+ * Pure function — no I/O.
+ *
+ * - effectiveFps is uniform across all segments
+ * - Overlap: 1 frame at each internal boundary
+ * - allocatedFrames total <= maxFrames (last segment adjusted if needed)
+ */
+export declare function computeSegmentPlan(totalDuration: number, maxSegmentDuration: number, maxFrames: number, fps: number): SegmentPlan[];
+/**
+ * Merge multiple segment results into a single unified frame/edge/animation set.
+ * - Timestamps adjusted using extractStartTime (Section 18 note 1)
+ * - Overlap frames deduplicated by threshold 1/(effectiveFps*2) (Section 18 note 5)
+ * - Global IDs reassigned after dedup
+ * - Duplicate edges keep higher score
+ */
+export declare function mergeSegmentFrames(segmentResults: SegmentResult[]): {
+    frames: FrameNode[];
+    edges: ScoreEdge[];
+    animations: AnimationMetadata[];
+};
+/**
+ * Extract frames for a single segment and analyze them.
+ * Each segment uses an isolated workspace directory.
+ */
+export declare function processSegment(inputPath: string, segment: SegmentPlan, workspacePath: string, resolvedOptions: ResolvedOptions, onProgress: (percent: number) => void): Promise<SegmentResult>;
+/**
+ * Full segmented pipeline: metadata → plan → parallel extract+analyze → merge → prune → finalize.
+ * Called from runPipeline when shouldSegment() returns true.
+ */
+export declare function runSegmentedPipeline(options: SieveOptions, resolvedOptions: ResolvedOptions): Promise<SieveResult>;

package/dist/core/workspace.d.ts

@@ -1,6 +1,7 @@
 import type { FrameNode, ProcessContext } from '../types/index.js';
 export declare function createWorkspace(sessionId: string): Promise<string>;
 export declare function finalizeOutput(ctx: ProcessContext, selectedFrames: FrameNode[]): Promise<string[]>;
+export declare function createSegmentWorkspace(parentWorkspacePath: string, segmentIndex: number): Promise<string>;
 export declare function cleanupWorkspace(workspacePath: string): Promise<void>;
 /**
  * Remove stale workspace directories left by previous interrupted runs.

package/dist/index.cjs

@@ -39,7 +39,7 @@ var getImportMetaUrl = () => typeof document === "undefined" ? new URL(`file:${_
 var importMetaUrl = /* @__PURE__ */ getImportMetaUrl();
 
 // src/core/orchestrator.ts
-var import_node_crypto = require("crypto");
+var import_node_crypto2 = require("crypto");
 
 // src/utils/logger.ts
 var import_picocolors = __toESM(require("picocolors"), 1);
@@ -104,6 +104,8 @@ var PIXELDIFF_GAUSSIAN_KERNEL = 3;
 var PIXELDIFF_BINARY_THRESHOLD = 30;
 var PIXELDIFF_CONTOUR_MIN_AREA = 100;
 var PIXELDIFF_SAMPLE_SPACING = 8;
+var DEFAULT_MAX_SEGMENT_DURATION = 300;
+var DEFAULT_SEGMENT_CONCURRENCY = 2;
 function getTempWorkspaceDir(sessionId) {
   return (0, import_node_path.join)(TEMP_BASE_DIR, `${WORKSPACE_PREFIX}${sessionId}`);
 }
@@ -696,6 +698,23 @@ async function buildFrameList(framesDir, duration) {
     extractPath: (0, import_node_path3.join)(framesDir, file)
   }));
 }
+async function extractFramesForRange(inputPath, outputDir, fps, scale, startTime, duration) {
+  const outputPattern = (0, import_node_path3.join)(outputDir, FRAME_FILENAME_PATTERN);
+  await (0, import_execa.execa)(import_ffmpeg_static.default, [
+    "-ss",
+    String(startTime),
+    "-i",
+    inputPath,
+    "-t",
+    String(duration),
+    "-vf",
+    `fps=${fps},scale=-1:${scale}`,
+    "-q:v",
+    "2",
+    outputPattern
+  ]);
+  return buildFrameList(outputDir, duration);
+}
 
 // src/core/input-resolver.ts
 var import_node_path5 = require("path");
@@ -758,6 +777,15 @@ async function finalizeOutput(ctx, selectedFrames) {
   await (0, import_promises3.rename)(stagingDir, outputPath);
   return outputFiles;
 }
+async function createSegmentWorkspace(parentWorkspacePath, segmentIndex) {
+  const segmentPath = (0, import_node_path4.join)(
+    parentWorkspacePath,
+    "segments",
+    String(segmentIndex)
+  );
+  await ensureDir((0, import_node_path4.join)(segmentPath, "frames"));
+  return segmentPath;
+}
 async function cleanupWorkspace(workspacePath) {
   if (!workspacePath) return;
   try {
@@ -818,7 +846,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) {
@@ -1070,13 +1100,361 @@ function pruneByThresholdWithCap(graph, frames, threshold, maxCount) {
   return pruneTo(syntheticEdges, survivingFrames, maxCount);
 }
 
+// src/core/segmenter.ts
+var import_node_crypto = require("crypto");
+var import_node_path6 = require("path");
+
+// 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()?.();
+    }
+  };
+}
+
+// src/core/segmenter.ts
+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 = (0, import_node_path6.join)(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 = (0, import_node_crypto.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}`);
+    }
+  }
+}
+
 // src/core/orchestrator.ts
 async function runPipeline(options) {
-  const startTime = Date.now();
-  const sessionId = (0, import_node_crypto.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 = (0, import_node_crypto2.randomUUID)();
   const ctx = {
     options: resolvedOptions,
     workspacePath: "",