@lumy-pack/scene-sieve 0.1.0 → 0.2.1

package/dist/types/index.d.ts

@@ -10,10 +10,15 @@ export type SieveInput = {
     inputFrames: Buffer[];
 };
 export interface SieveOptionsBase {
+    /** Enable a contact sheet with defaults or selected overrides; disabled by default. */
+    sheet?: boolean | SheetOptions;
+    /** Include adjacent candidate edge diagnostics in the metadata document. */
+    includeEdges?: boolean;
     count?: number;
     threshold?: number;
     outputPath?: string;
     fps?: number;
+    /** Strict file/buffer candidate frame limit (default: 300); ignored in frames mode. */
     maxFrames?: number;
     scale?: number;
     quality?: number;
@@ -26,6 +31,10 @@ export interface SieveOptionsBase {
 }
 export type SieveOptions = SieveOptionsBase & SieveInput;
 export interface ResolvedOptions {
+    /** Complete contact sheet settings, or null when disabled. */
+    sheet: Required<SheetOptions> | null;
+    /** Whether the document contains candidate edge diagnostics. */
+    includeEdges: boolean;
     mode: 'file' | 'buffer' | 'frames';
     inputPath?: string;
     count: number;
@@ -50,6 +59,12 @@ export interface SieveResult {
     outputBuffers?: Buffer[];
     animations?: AnimationMetadata[];
     video?: VideoMetadata;
+    /** Selected frames paired with output files or buffers; IDs are one-based. */
+    frames?: FrameMetadata[];
+    /** Layout of the rendered contact sheet; absent when no sheet exists. */
+    sheet?: SheetMetadata;
+    /** Encoded contact sheet for buffer and frames modes only. */
+    sheetBuffer?: Buffer;
     executionTimeMs: number;
 }
 export interface AnimationMetadata {
@@ -60,12 +75,24 @@ export interface AnimationMetadata {
     durationMs: number;
 }
 export interface VideoMetadata {
+    /** Source duration from ffprobe, or the final candidate timestamp in frames mode. */
     originalDurationMs: number;
+    /** Effective sampling frequency; frames mode uses one frame per second. */
     fps: number;
+    /** Actual output JPEG dimensions; zero when no candidate exists. */
     resolution: {
         width: number;
         height: number;
     };
+    /** Number of candidates before pruning. */
+    candidatesCount: number;
+    /** Number of selected frames after pruning. */
+    selectedCount: number;
+    /** Input mode and basename only; in-memory inputs have no file name. */
+    source: {
+        fileName: string | null;
+        mode: 'file' | 'buffer' | 'frames';
+    };
 }
 export interface FrameNode {
     id: number;
@@ -84,6 +111,131 @@ export interface ScoreEdge {
      * Maps directly to G(t) from the vision analysis pipeline.
      */
     score: number;
+    /** Analysis-space cluster partition; absent on failed pairs and synthetic edges. */
+    change?: EdgeChange;
+}
+/** Optional contact sheet overrides, validated before defaults are applied. */
+export interface SheetOptions {
+    /** Maximum columns, an integer at least one; defaults to four. */
+    columns?: number;
+    /** Tile width in pixels, an integer at least sixteen; defaults to 320. */
+    tileWidth?: number;
+    /** Tile limit, an integer at least two; defaults to forty. */
+    maxTiles?: number;
+    /** Burn a frame ID and timestamp into each tile; defaults to true. */
+    label?: boolean;
+}
+/** Adjacent-pair cluster boxes in analysis coordinates, partitioned by the tracker. */
+export interface EdgeChange {
+    /** Non-animation clusters in DBSCAN label order. */
+    regions: BoundingBox[];
+    /** Clusters whose indices the tracker classified as animation. */
+    animatedRegions: BoundingBox[];
+}
+/** Change across the candidate edges between two selected frames. */
+export interface FrameChange {
+    /** Previous selected frame ID, one-based. */
+    fromFrameId: number;
+    /** Candidates pruned between the selected endpoints. */
+    skippedCandidates: number;
+    /** Maximum raw information gain, rounded to six decimals. */
+    peakScore: number;
+    /** Sum of raw information gain, rounded to six decimals. */
+    sumScore: number;
+    /** Non-animation union area fraction, clamped and rounded to four decimals. */
+    areaRatio: number;
+    /** Up to five distinct largest regions in clamped integer output pixels. */
+    regions: BoundingBox[];
+}
+/** Selected frame timing and change signals shared by file and API output. */
+export interface FrameMetadata {
+    /** One-based position in the selected sequence. */
+    step: number;
+    /** Deterministic JPEG name, including for in-memory output pairing. */
+    fileName: string;
+    /** One-based candidate frame ID. */
+    frameId: number;
+    /** Rounded candidate timestamp in milliseconds. */
+    timestampMs: number;
+    /** Nonnegative time until the next selection or the source end. */
+    holdsMs: number;
+    /** Span summary, or null for the first selection. */
+    change: FrameChange | null;
+}
+/** Raw candidate edge diagnostics in graph order. */
+export interface EdgeMetadata {
+    /** One-based source candidate ID. */
+    sourceFrameId: number;
+    /** One-based target candidate ID. */
+    targetFrameId: number;
+    /** Raw information gain rounded to six decimals. */
+    score: number;
+    /** Non-animation union area fraction rounded to four decimals. */
+    areaRatio: number;
+    /** Animation union area fraction rounded to four decimals. */
+    animatedAreaRatio: number;
+}
+/** Selection and encoding settings in deterministic serialization order. */
+export interface ToolParams {
+    /** Requested extraction frequency, before the candidate cap. */
+    fps: number;
+    /** Requested maximum selected frame count. */
+    count: number;
+    /** Normalized pruning threshold. */
+    threshold: number;
+    /** Analysis image height in pixels. */
+    scale: number;
+    /** JPEG encoding quality. */
+    quality: number;
+    /** Strict file/buffer candidate cap. */
+    maxFrames: number;
+    /** Tracker overlap threshold. */
+    iouThreshold: number;
+    /** Consecutive frames required for animation classification. */
+    animationThreshold: number;
+    /** Maximum logical segment duration in seconds. */
+    maxSegmentDuration: number;
+}
+/** Tool provenance and reproducible pipeline parameters. */
+export interface ToolMetadata {
+    /** Published package identifier. */
+    name: '@lumy-pack/scene-sieve';
+    /** Version from the runtime package manifest. */
+    version: string;
+    /** Nine selection and encoding parameters, excluding operational options. */
+    params: ToolParams;
+}
+/** Contact sheet layout and sampled frame IDs in tile order. */
+export interface SheetMetadata {
+    /** Fixed output name. */
+    fileName: 'sheet.jpg';
+    /** Effective columns, capped by tile count. */
+    columns: number;
+    /** Tile width in pixels. */
+    tileWidth: number;
+    /** Aspect-preserving rounded tile height, at least one pixel. */
+    tileHeight: number;
+    /** One-based frame IDs ordered left-to-right, then top-to-bottom. */
+    frameIds: number[];
+    /** Whether the tile limit required uniform sampling. */
+    sampled: boolean;
+}
+/** Version-two document; properties are serialized in declaration order. */
+export interface SieveMetadata {
+    /** Schema discriminator; absent in version-one documents. */
+    metadataVersion: 2;
+    /** Runtime tool provenance. */
+    tool: ToolMetadata;
+    /** Source timing, dimensions and candidate counts. */
+    video: VideoMetadata;
+    /** Selected frame summaries in temporal order. */
+    frames: FrameMetadata[];
+    /** Output-space animations with one-based IDs and integer durations. */
+    animations: AnimationMetadata[];
+    /** Present only when a sheet was rendered. */
+    sheet?: SheetMetadata;
+    /** Present only when includeEdges was enabled. */
+    edges?: EdgeMetadata[];
 }
 export interface BoundingBox {
     x: number;
@@ -97,6 +249,15 @@ export interface DBSCANResult {
 }
 export interface ProcessContext {
     options: ResolvedOptions;
+    /** Actual extraction grid frequency; frames mode uses one-second intervals. */
+    effectiveFps?: number;
+    /** Original video duration reported by ffprobe, in seconds. */
+    sourceDurationSec?: number;
+    /** Dimensions of analysis-space boxes; absent or zero if no pair was analyzed. */
+    analysisResolution?: {
+        width: number;
+        height: number;
+    };
     workspacePath: string;
     frames: FrameNode[];
     graph: ScoreEdge[];
@@ -108,16 +269,23 @@ export interface ProcessContext {
 export interface AnalysisResult {
     edges: ScoreEdge[];
     animations: AnimationMetadata[];
+    /** First analyzed image dimensions, or zero dimensions when no pair exists. */
+    analysisResolution: {
+        width: number;
+        height: number;
+    };
 }
 export interface SegmentPlan {
     index: number;
     startTime: number;
     endTime: number;
     duration: number;
+    /** FFmpeg output limit, including overlap slots; a single segment uses the full budget. */
     allocatedFrames: number;
     effectiveFps: number;
     overlapBefore: number;
     overlapAfter: number;
+    /** First extraction grid time in seconds, including overlap. */
     extractStartTime: number;
     extractDuration: number;
 }
@@ -126,4 +294,9 @@ export interface SegmentResult {
     frames: FrameNode[];
     edges: ScoreEdge[];
     animations: AnimationMetadata[];
+    /** Analysis coordinates retained through merging for output-only box scaling. */
+    analysisResolution: {
+        width: number;
+        height: number;
+    };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumy-pack/scene-sieve",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "CLI tool for extracting key frames from video and GIF files",
   "keywords": [
     "cli",
@@ -22,6 +22,9 @@
   },
   "sideEffects": false,
   "type": "module",
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -54,23 +57,23 @@
     "version:patch": "yarn version patch"
   },
   "dependencies": {
-    "@ffprobe-installer/ffprobe": "^1.4.1",
+    "@ffprobe-installer/ffprobe": "^2.1.2",
     "@techstark/opencv-js": "4.12.0-release.1",
-    "@winglet/common-utils": "^0.12.2",
+    "@winglet/common-utils": "^0.14.1",
     "commander": "^12.1.0",
-    "execa": "^9.5.0",
-    "ffmpeg-static": "^5.2.0",
-    "ink": "^5.0.0",
+    "execa": "^9.6.1",
+    "ffmpeg-static": "^5.3.0",
+    "ink": "^6.8.0",
     "ink-spinner": "^5.0.0",
     "picocolors": "^1.1.1",
-    "react": "^18.0.0",
-    "sharp": "^0.33.0"
+    "react": "^19.3.0",
+    "sharp": "^0.35.4"
   },
   "devDependencies": {
     "@lumy-pack/shared": "0.0.1",
-    "@types/node": "^20.11.0",
-    "@types/react": "^18.0.0",
+    "@types/node": "^20.19.43",
+    "@types/react": "^19.3.0",
     "@vitest/coverage-v8": "^3.2.4",
-    "rolldown": "^1.2.0"
+    "rolldown": "^1.2.8"
   }
 }

package/dist/constants.d.ts

@@ -1,32 +0,0 @@
-export declare const APP_NAME = "scene-sieve";
-export declare const DEFAULT_COUNT = 20;
-export declare const DEFAULT_THRESHOLD = 0.5;
-export declare const DEFAULT_FPS = 5;
-export declare const DEFAULT_SCALE = 720;
-export declare const DEFAULT_QUALITY = 80;
-export declare const DEFAULT_MAX_FRAMES = 300;
-export declare const NORMALIZATION_MIN_PERCENTILE = 0.1;
-export declare const NORMALIZATION_MAX_PERCENTILE = 0.9;
-export declare const NORMALIZATION_LOGISTIC_K = 3;
-export declare const NORMALIZATION_ALPHA = 0.4;
-export declare const NORMALIZATION_MAD_COEFFICIENT = 1.4826;
-export declare const NORMALIZATION_MIN_SAMPLE_SIZE = 10;
-export declare const WORKSPACE_PREFIX = "scene-sieve-";
-export declare const TEMP_BASE_DIR: string;
-export declare const FRAME_OUTPUT_EXTENSION = ".jpg";
-export declare const FRAME_FILENAME_PATTERN = "frame_%06d.jpg";
-export declare const OPENCV_BATCH_SIZE = 10;
-export declare const MIN_IFRAME_COUNT = 3;
-export declare const DBSCAN_ALPHA = 0.03;
-export declare const DBSCAN_MIN_PTS = 4;
-export declare const IOU_THRESHOLD = 0.9;
-export declare const DECAY_LAMBDA = 0.95;
-export declare const ANIMATION_FRAME_THRESHOLD = 5;
-export declare const MATCH_DISTANCE_THRESHOLD = 0.25;
-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/orchestrator.d.ts

@@ -1,2 +0,0 @@
-import type { SieveOptions, SieveResult } from '../types/index.js';
-export declare function runPipeline(options: SieveOptions): Promise<SieveResult>;