@lumy-pack/scene-sieve 0.0.7 → 0.0.9

package/dist/pipeline-worker.mjs

@@ -2,7 +2,7 @@
 import { parentPort, workerData } from "worker_threads";
 
 // src/core/orchestrator.ts
-import { randomUUID } from "crypto";
+import { randomUUID as randomUUID2 } from "crypto";
 
 // src/utils/logger.ts
 import pc from "picocolors";
@@ -48,7 +48,10 @@ 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 FRAME_OUTPUT_EXTENSION = ".jpg";
@@ -64,6 +67,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 join(TEMP_BASE_DIR, `${WORKSPACE_PREFIX}${sessionId}`);
 }
@@ -656,6 +661,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);
+}
 
 // src/core/input-resolver.ts
 import { join as join4 } from "path";
@@ -718,6 +740,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 {
@@ -778,7 +809,9 @@ function resolveOptions(options2) {
     quality: options2.quality ?? DEFAULT_QUALITY,
     iouThreshold: options2.iouThreshold ?? IOU_THRESHOLD,
     animationThreshold: options2.animationThreshold ?? ANIMATION_FRAME_THRESHOLD,
-    debug: options2.debug ?? false
+    debug: options2.debug ?? false,
+    maxSegmentDuration: options2.maxSegmentDuration ?? DEFAULT_MAX_SEGMENT_DURATION,
+    concurrency: options2.concurrency ?? DEFAULT_SEGMENT_CONCURRENCY
   };
 }
 async function resolveInput(options2, workspacePath) {
@@ -802,6 +835,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 = [];
@@ -896,20 +966,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;
@@ -1007,13 +1063,361 @@ function pruneByThresholdWithCap(graph, frames, threshold, maxCount) {
   return pruneTo(syntheticEdges, survivingFrames, maxCount);
 }
 
+// src/core/segmenter.ts
+import { randomUUID } from "crypto";
+import { join as join5 } from "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 = 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(options2, 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(options2, 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 (!options2.onProgress) return;
+      const overall = weights.reduce(
+        (sum, w, i) => sum + w * (segmentProgresses[i] ?? 0),
+        0
+      );
+      options2.onProgress(phase, Math.min(100, overall));
+    };
+    options2.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;
+        })
+      )
+    );
+    options2.onProgress?.("ANALYZING", 100);
+    const { frames, edges, animations } = mergeSegmentFrames(results);
+    logger.debug(
+      `Merged: ${frames.length} frames, ${edges.length} edges, ${animations.length} animations`
+    );
+    options2.onProgress?.("PRUNING", 0);
+    const survivingIds = pruneByThresholdWithCap(
+      edges,
+      frames,
+      resolvedOptions.threshold,
+      resolvedOptions.count
+    );
+    const prunedFrames = frames.filter((f) => survivingIds.has(f.id));
+    options2.onProgress?.("PRUNING", 100);
+    options2.onProgress?.("FINALIZING", 0);
+    const ctx = {
+      options: resolvedOptions,
+      workspacePath: mainWorkspace,
+      frames,
+      graph: edges,
+      animations,
+      status: "FINALIZING",
+      emitProgress: (percent) => options2.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);
+    }
+    options2.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(options2) {
-  const startTime = Date.now();
-  const sessionId = randomUUID();
   const debug = options2.debug ?? false;
   if (debug) setDebugMode(true);
   const resolvedOptions = resolveOptions(options2);
+  if (shouldSegment(resolvedOptions, options2)) {
+    return runSegmentedPipeline(options2, resolvedOptions);
+  }
+  const startTime = Date.now();
+  const sessionId = randomUUID2();
   const ctx = {
     options: resolvedOptions,
     workspacePath: "",

package/dist/types/index.d.ts

@@ -21,6 +21,8 @@ export interface SieveOptionsBase {
     animationThreshold?: number;
     debug?: boolean;
     onProgress?: (phase: ProgressPhase, percent: number) => void;
+    maxSegmentDuration?: number;
+    concurrency?: number;
 }
 export type SieveOptions = SieveOptionsBase & SieveInput;
 export interface ResolvedOptions {
@@ -37,6 +39,8 @@ export interface ResolvedOptions {
     iouThreshold: number;
     animationThreshold: number;
     debug: boolean;
+    maxSegmentDuration: number;
+    concurrency: number;
 }
 export interface SieveResult {
     success: boolean;
@@ -105,3 +109,21 @@ export interface AnalysisResult {
     edges: ScoreEdge[];
     animations: AnimationMetadata[];
 }
+export interface SegmentPlan {
+    index: number;
+    startTime: number;
+    endTime: number;
+    duration: number;
+    allocatedFrames: number;
+    effectiveFps: number;
+    overlapBefore: number;
+    overlapAfter: number;
+    extractStartTime: number;
+    extractDuration: number;
+}
+export interface SegmentResult {
+    segment: SegmentPlan;
+    frames: FrameNode[];
+    edges: ScoreEdge[];
+    animations: AnimationMetadata[];
+}

package/dist/utils/concurrency.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Creates a concurrency limiter that runs at most `limit` tasks in parallel.
+ * Lightweight replacement for p-limit to avoid external dependency.
+ */
+export declare function concurrencyLimit(limit: number): <T>(fn: () => Promise<T>) => Promise<T>;

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumy-pack/scene-sieve",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "description": "CLI tool for extracting key frames from video and GIF files",
   "keywords": [
     "cli",