@lumy-pack/scene-sieve 0.2.0 → 0.2.1

package/dist/types/index.d.ts

@@ -10,6 +10,10 @@ 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;
@@ -27,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;
@@ -51,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 {
@@ -70,6 +84,15 @@ export interface VideoMetadata {
         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;
@@ -88,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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumy-pack/scene-sieve",
-  "version": "0.2.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"
   }
 }