@lumy-pack/scene-sieve 0.1.0 → 0.2.1

package/README.md

@@ -8,17 +8,17 @@ Automatically extract the most meaningful frames from video and GIF files using
 
 ```
 Video/GIF ──▶ Extract (FFmpeg) ──▶ Analyze (OpenCV) ──▶ Prune ──▶ Output
-               I-frames / FPS       AKAZE + DBSCAN        MinHeap    JPG / Buffer
+               FPS grid             AKAZE + DBSCAN        MinHeap    JPG / Buffer
 ```
 
 ## Features
 
 - **Animation Tracking** — Detects and records loading spinners or other repetitive animations
-- **Rich Metadata** — Generates `.metadata.json` with scene timestamps and animation details
+- **Change signals and contact sheets** — Metadata v2 records regions, raw scores and holds, with an optional `sheet.jpg` overview
 - **Smart frame selection** — Identifies visually significant scene changes, not just evenly-spaced samples
 - **Computer vision pipeline** — AKAZE feature detection, DBSCAN clustering, IoU tracking, and information gain scoring
 - **Three input modes** — File path, video Buffer, or pre-extracted frame Buffers
-- **Flexible pruning** — Keep a fixed count, filter by threshold, or combine both
+- **Flexible pruning** — Filter by a distribution-normalized threshold, then apply a count cap
 - **Bundled FFmpeg** — No system-level FFmpeg installation required
 - **Dual output** — ESM and CommonJS compatible
 - **Progress callbacks** — Track extraction progress in real time
@@ -40,7 +40,7 @@ yarn add @lumy-pack/scene-sieve
 # Extract 20 key scenes (default)
 npx scene-sieve input.mp4
 
-# Keep exactly 8 scenes
+# Keep up to 8 scenes
 npx scene-sieve input.mp4 -n 8
 
 # Use threshold-based selection
@@ -84,13 +84,15 @@ scene-sieve <input> [options]
 | `-n, --count <number>`         | Max number of frames to keep                    | `20`                         |
 | `-t, --threshold <number>`     | Normalized score threshold (0, 1]               | `0.5`                        |
 | `-o, --output <path>`          | Output directory                                | Same directory as input      |
-| `--fps <number>`               | Max FPS for frame extraction                    | `5`                          |
-| `-mf, --max-frames <number>`   | Max frames to extract (auto-reduces FPS)        | `300`                        |
-| `-s, --scale <number>`         | Scale size for vision analysis (px)             | `720`                        |
+| `--fps <number>`               | Requested extraction FPS (positive decimals allowed)                    | `5`                          |
+| `-mf, --max-frames <number>`   | Strict candidate cap (auto-reduces FPS)        | `300`                        |
+| `-s, --scale <number>`         | Extraction height / analysis width (px)             | `720`                        |
 | `-q, --quality <number>`       | JPEG output quality (1–100)                     | `80`                         |
 | `-it, --iou-threshold <number>`| IoU threshold for animation tracking (0–1)      | `0.9`                        |
 | `-at, --anim-threshold <number>`| Min consecutive frames for animation            | `5`                          |
 | `--debug`                      | Preserve temp workspace for inspection          | `false`                      |
+| `--sheet` | Generate a selected-frame contact sheet | `false` |
+| `--include-edges` | Include candidate edge diagnostics in metadata | `false` |
 
 ### Supported Formats
 
@@ -114,7 +116,7 @@ Not sure where to start? Here's how each parameter affects the output, based on
 
 #### `--threshold` — Minimum score to keep a frame
 
-Higher values = stricter filtering = fewer frames.
+Higher values mean stricter filtering and fewer frames. Scores are normalized against the positive-score distribution within the video: min-max for up to 10 positive scores, otherwise a blend of median/MAD-based logistic scores and percentile ranks. `0.5` is neither an absolute change level nor half the maximum score.
 
 | Setting | Selected | Notes |
 |---------|----------|-------|
@@ -124,24 +126,27 @@ Higher values = stricter filtering = fewer frames.
 | `-t 0.7` | 19 | Starts filtering subtle changes |
 | `-t 0.9` | 12 | Only major scene transitions survive |
 
-> **Tip**: Use `-t` alone for "give me everything important". Combine with `-n` to set an upper bound (e.g., `-t 0.3 -n 10`).
+> **Tip**: Using `-t` alone still applies the default `count=20` cap. Adjust it with `-n` (e.g., `-t 0.3 -n 10`).
 
 #### `--fps` and `--max-frames` — Extraction density
 
 These control how many frames are pulled from the video before analysis. More frames = more precision but longer processing.
 
+File/buffer candidates obey the strict `maxFrames` cap (integer ≥ 2). Effective FPS is `min(fps, maxFrames / duration)`, with no 0.5 FPS floor. Positive decimals such as `--fps 0.5` are accepted. A one-hour video with a 300-frame budget is sampled at about 0.083 FPS (every 12 seconds). This cap does not apply to frames input.
+
+Timestamps describe the FFmpeg output grid `k / effectiveFps`, rather than the original source frame PTS. The FPS filter keeps its default rounding. When the budget binds, the last grid point is `duration - duration / maxFrames`, leaving no candidate in the remaining interval to the end.
+
 | Setting | Extracted | Selected | Time |
 |---------|-----------|----------|------|
 | `--fps 1` | 18 | 6 | ~5s |
 | `--fps 5` (default) | 90 | 20 | ~25s |
 | `--fps 10` | 180 | 20 | ~47s |
-| `-mf 50` | 47 | 13 | ~13s |
 
 > **Tip**: For quick previews, `--fps 1` is 5x faster. For frame-accurate analysis, `--fps 10` captures finer transitions.
 
 #### `--scale` — Analysis resolution
 
-Controls the resolution used for vision analysis (not output resolution). Lower = faster but less sensitive.
+File/buffer extraction scales height to `scale`, while analysis preprocessing scales width to `scale`. Final JPEGs retain extraction dimensions; frames input retains its input dimensions in the output. Lower values are faster but less sensitive.
 
 | Setting | Selected | Time | Output Size |
 |---------|----------|------|-------------|
@@ -283,12 +288,16 @@ interface SieveOptionsBase {
   count?: number; // Max frames to keep (default: 20)
   threshold?: number; // Score threshold in range (0, 1] (default: 0.5)
   outputPath?: string; // Output directory (file mode only)
-  fps?: number; // Extraction FPS (default: 5)
-  maxFrames?: number; // Max frames to extract (default: 300)
-  scale?: number; // Analysis scale in px (default: 720)
+  fps?: number; // Requested FPS, positive decimals allowed (default: 5)
+  maxFrames?: number; // Strict file/buffer candidate cap (default: 300)
+  scale?: number; // Extraction height / analysis width in px (default: 720)
   quality?: number; // JPEG quality 1-100 (default: 80)
   iouThreshold?: number; // IoU for animation tracking (default: 0.9)
   animationThreshold?: number; // Min frames for animation (default: 5)
+  maxSegmentDuration?: number; // Segment duration in seconds (default: 300)
+  concurrency?: number; // Parallel segment workers (default: 2)
+  sheet?: boolean | SheetOptions; // Contact sheet (default: false)
+  includeEdges?: boolean; // Candidate edge diagnostics (default: false)
   debug?: boolean; // Preserve temp workspace (default: false)
   onProgress?: (phase: ProgressPhase, percent: number) => void;
 }
@@ -296,6 +305,22 @@ interface SieveOptionsBase {
 type SieveOptions = SieveOptionsBase & SieveInput;
 ```
 
+Supplied numeric options are validated before defaults; invalid values produce `INVALID_INPUT`. CLI numeric strings are checked in full, so values such as `5abc` are rejected. Both interactive and JSON CLI failures exit with code 1.
+
+| Option | Allowed range |
+| --- | --- |
+| `count`, `animationThreshold`, `concurrency` | Integer ≥ 1 |
+| `maxFrames` | Integer ≥ 2 |
+| `scale` | Integer ≥ 16 |
+| `quality` | Integer 1–100 |
+| `fps`, `maxSegmentDuration` | Finite positive number (decimals allowed) |
+| `threshold` | Finite (0, 1] |
+| `iouThreshold` | Finite [0, 1] |
+| `sheet` | Boolean or `SheetOptions`: columns integer ≥ 1, tileWidth integer ≥ 16, maxTiles integer ≥ 2, label boolean. Default false; enabled defaults 4, 320, 40, true |
+| `includeEdges` | Boolean, default false |
+
+All images in frames input must share the same width and height. Empty arrays and single images are accepted.
+
 ### Result
 
 ```typescript
@@ -307,19 +332,20 @@ interface SieveResult {
   outputBuffers?: Buffer[]; // JPEG buffers (buffer/frames mode)
   animations?: AnimationMetadata[]; // Detected animations
   video?: VideoMetadata; // Video source metadata
+  frames?: FrameMetadata[]; // Same one-based frames as the metadata document
+  sheet?: SheetMetadata; // Present only when a sheet was rendered
+  sheetBuffer?: Buffer; // JPEG sheet in buffer/frames modes only
   executionTimeMs: number;
 }
 ```
 
+`frames[i]` pairs with `outputBuffers[i]`; fileName remains the same deterministic file-mode label for in-memory output. API frames[].frameId is one-based, while API animations[].startFrameId and endFrameId remain zero-based. Document animation IDs are one-based.
+
 ### Pruning Strategies
 
-The pruning strategy is automatically selected based on which options are provided:
+The pipeline always uses **threshold-with-cap**: filter by distribution-normalized score, then prune to the `count` cap. Omitted `threshold` and `count` default to `0.5` and `20`. The selected count may be lower depending on candidates and scores.
 
-| Options                    | Strategy               | Behavior                                                         |
-| -------------------------- | ---------------------- | ---------------------------------------------------------------- |
-| `count` only               | **count**              | Greedy merge — removes lowest-scored frames until `count` remain |
-| `threshold` only           | **threshold**          | Keeps frames with normalized score >= `threshold`                |
-| Both `count` + `threshold` | **threshold-with-cap** | Applies threshold filter first, then caps at `count`             |
+The first and last candidates are protected, so both remain when `count=1` and at least two candidates exist. Standalone count and threshold strategies exist as internal functions but are not selected by the CLI or `extractScenes`.
 
 ### Progress Tracking
 
@@ -337,32 +363,92 @@ const result = await extractScenes({
 
 ## Output Metadata
 
-When running in `file` mode, `scene-sieve` generates a `.metadata.json` file in the output directory.
+File mode writes a v2 `.metadata.json` beside the selected JPEGs. Existing fields retain their meaning; treat a document without `metadataVersion` as v1. The package exports `SieveMetadata`, `FrameMetadata`, `FrameChange`, `EdgeMetadata`, `EdgeChange`, `ToolMetadata`, `ToolParams`, `SheetMetadata`, `SheetOptions`, `VideoMetadata` and `AnimationMetadata`.
+
+`tool.name` and `tool.version` identify the runtime package. `tool.params` contains exactly nine fields in the order shown below. Its `fps` is the requested value; `video.fps` is the effective value. Cache selected frames using input identity, tool version and these params. Include sheet settings and `includeEdges` when caching complete output bundles, because those output options are excluded from params.
+
+`SieveResult.video` and the document share these values:
+
+- `originalDurationMs`: ffprobe duration for file/buffer, or the last candidate timestamp for frames input.
+- `fps`: effective sampling frequency; frames input and its animation tracker use 1.
+- `resolution`: actual output JPEG size of the first selection, falling back to the first candidate or 0×0.
+- `candidatesCount` and `selectedCount`: counts before and after pruning.
+- `source`: input mode and basename only; `fileName` is null for buffer/frames input.
+
+Each `frames[]` entry has a one-based step and candidate ID, a deterministic `fileName`, rounded `timestampMs`, and `holdsMs`: time until the next selected frame, or until the source end for the last frame, clamped to zero. Frames input uses one-second candidate intervals.
+
+The first frame has `change: null`. Later entries aggregate every available adjacent candidate edge from the previous selection to this one:
+
+| Field | Meaning |
+| --- | --- |
+| `fromFrameId` | Previous selected candidate ID, one-based |
+| `skippedCandidates` | Pruned candidates between the selections |
+| `peakScore`, `sumScore` | Maximum and sum of raw G(t), before pruning normalization |
+| `areaRatio` | Exact union area of all non-animation cluster boxes divided by analysis image area, clamped to [0,1] |
+| `regions` | Up to five distinct largest boxes in integer output pixels, sorted by area descending, then y, x and width ascending |
+
+Area is computed in analysis coordinates before output rounding. It is an absolute box-area fraction, distinct from both feature-density G(t) and video-relative normalized pruning scores. Overlapping boxes contribute only once. Region boxes use the same axis-specific scaling, rounding and clamping as `animations[].boundingBox`.
+
+Animation exclusion follows `animationIndices`: exactly the clusters the tracker classified as animation and discounted in G(t) for that pair. Earlier observations can remain in change regions before the tracker recognizes repetition; there is no retrospective removal based on the final animation list. Failed pairs contribute their fallback score without boxes.
+
+`includeEdges: true` (CLI `--include-edges`) appends `edges[]` in candidate graph order with `sourceFrameId`, `targetFrameId` (one-based), raw `score`, `areaRatio` and `animatedAreaRatio`. The key is absent by default.
+
+Use `sheet: true` or CLI `--sheet` for `sheet.jpg`. API defaults are `{ columns: 4, tileWidth: 320, maxTiles: 40, label: true }`; partial objects override individual fields. Tiles preserve the output aspect ratio with a white background and 4px gaps/margins. Labels read `#<frameId> mm:ss.s` with tenths truncated. Excess tiles are sampled uniformly, always including the first and last selection. `sheet` records the effective columns, tile dimensions, one-based tile `frameIds` and `sampled`. File output order is frame JPEGs, optional sheet, then metadata. Buffer/frames mode returns `sheetBuffer`; absent or empty sheets create neither `sheet` nor `sheetBuffer` keys.
+
+Metadata keys have a fixed order. Area ratios round to four decimals; raw scores round to six. Trailing zeroes are not preserved by JSON. Identical input bytes, basename, tool version, params and output options produce identical metadata bytes regardless of concurrency, output directory or execution time. Sheet JPEG determinism is limited to the same machine, sharp version and font environment.
+
+The following complete example was generated from a four-second FFmpeg `testsrc=size=320x240:rate=5` MP4 using:
+
+```bash
+scene-sieve test_input.mp4 --fps 5 -mf 12 -n 2 -t 0.001 -s 320 --sheet
+```
+
+The runtime version is 0.2.0 before the minor changeset is released; these values come from an actual run.
 
 ```json
 {
+  "metadataVersion": 2,
+  "tool": {
+    "name": "@lumy-pack/scene-sieve",
+    "version": "0.2.0",
+    "params": {
+      "fps": 5, "count": 2, "threshold": 0.001, "scale": 320, "quality": 80,
+      "maxFrames": 12, "iouThreshold": 0.9, "animationThreshold": 5,
+      "maxSegmentDuration": 300
+    }
+  },
   "video": {
-    "originalDurationMs": 15000,
-    "fps": 5,
-    "resolution": { "width": 720, "height": 405 }
+    "originalDurationMs": 4000, "fps": 3,
+    "resolution": { "width": 427, "height": 320 },
+    "candidatesCount": 12, "selectedCount": 2,
+    "source": { "fileName": "test_input.mp4", "mode": "file" }
   },
   "frames": [
     {
-      "step": 1,
-      "fileName": "frame_0001.jpg",
-      "frameId": 1,
-      "timestampMs": 0
-    }
-  ],
-  "animations": [
+      "step": 1, "fileName": "frame_0001.jpg", "frameId": 1,
+      "timestampMs": 0, "holdsMs": 3667, "change": null
+    },
     {
-      "type": "loading_spinner",
-      "boundingBox": { "x": 100, "y": 200, "width": 50, "height": 50 },
-      "startFrameId": 12,
-      "endFrameId": 25,
-      "durationMs": 2600
+      "step": 2, "fileName": "frame_0012.jpg", "frameId": 12,
+      "timestampMs": 3667, "holdsMs": 333,
+      "change": {
+        "fromFrameId": 1, "skippedCandidates": 10,
+        "peakScore": 0.000833, "sumScore": 0.006784, "areaRatio": 0.1186,
+        "regions": [
+          { "x": 340, "y": 124, "width": 32, "height": 69 },
+          { "x": 32, "y": 240, "width": 64, "height": 32 },
+          { "x": 64, "y": 240, "width": 64, "height": 32 },
+          { "x": 113, "y": 240, "width": 64, "height": 32 },
+          { "x": 145, "y": 240, "width": 64, "height": 32 }
+        ]
+      }
     }
-  ]
+  ],
+  "animations": [],
+  "sheet": {
+    "fileName": "sheet.jpg", "columns": 2, "tileWidth": 320, "tileHeight": 240,
+    "frameIds": [1, 12], "sampled": false
+  }
 }
 ```
 
@@ -373,16 +459,16 @@ When running in `file` mode, `scene-sieve` generates a `.metadata.json` file in
 scene-sieve processes input through a 5-stage pipeline:
 
 1. **Init** — Creates a temporary workspace and resolves input mode
-2. **Extract** — Pulls frames via FFmpeg (I-frame priority, FPS fallback; skipped in `frames` mode)
+2. **Extract** — Pulls candidates on an FFmpeg FPS grid within the strict `maxFrames` cap (skipped in `frames` mode)
 3. **Analyze** — Computes an information gain score G(t) for each adjacent frame pair
-4. **Prune** — Selects frames based on G(t) scores using the chosen pruning strategy
-5. **Finalize** — Writes output files (atomic rename) or returns Buffers; cleans up workspace
+4. **Prune** — Selects frames from G(t) scores using threshold-with-cap
+5. **Finalize** — Deletes existing output before renaming staging, or returns Buffers; cleans up workspace
 
 ### Vision Analysis
 
 The analyzer scores each pair of adjacent frames through 4 stages:
 
-1. **AKAZE Feature Diff** — Detects and matches keypoints between frames; identifies newly appeared and disappeared features
+1. **AKAZE Feature Diff** — Reuses per-frame preprocessing/features and the detector to compute newly appeared points (sNew only)
 2. **DBSCAN Clustering** — Groups new feature points into spatial clusters
 3. **IoU Tracking** — Tracks cluster bounding boxes across time; identifies and records repeated animation regions (e.g. loading spinners)
 4. **G(t) Scoring** — Calculates information gain from cluster area ratio and feature density, discounting animated areas to focus on unique scene content
@@ -391,7 +477,7 @@ Frames with higher G(t) scores represent greater visual change and are preserved
 
 ## Requirements
 
-- **Node.js** >= 20
+- **Node.js** 20.19+ (20.x) or >= 22.12
 - **FFmpeg**: Bundled via `ffmpeg-static` — no system installation needed
 - **OpenCV**: Bundled as WASM via `@techstark/opencv-js` — no native build needed
 - **sharp**: Requires native binaries. Pre-built binaries are automatically downloaded for most platforms. See the [sharp installation guide](https://sharp.pixelplumbing.com/install) if you encounter build issues.

package/dist/{commands → cli/commands}/Sieve.d.ts

@@ -1,5 +1,6 @@
 import type { Command } from 'commander';
 import React from 'react';
+import type { SheetOptions } from '../../types/index.js';
 export interface SieveViewProps {
     input: string;
     count?: number;
@@ -14,6 +15,10 @@ export interface SieveViewProps {
     maxSegmentDuration?: number;
     concurrency?: number;
     debug: boolean;
+    /** Contact sheet settings forwarded to the pipeline. */
+    sheet?: boolean | SheetOptions;
+    /** Whether to include candidate edge diagnostics. */
+    includeEdges?: boolean;
 }
 export declare function registerSieveCommand(program: Command, version: string): void;
 export declare const SieveView: React.FC<SieveViewProps>;

package/dist/{errors.d.ts → cli/errors/classify-error.d.ts}

@@ -7,4 +7,9 @@ export declare const SieveErrorCode: {
     readonly UNKNOWN: "UNKNOWN";
 };
 export type SieveErrorCode = (typeof SieveErrorCode)[keyof typeof SieveErrorCode];
+/**
+ * Classify pipeline errors for structured CLI responses.
+ * @param error - Failure with a diagnostic message and optional filesystem code.
+ * @returns The existing error code matching the failure.
+ */
 export declare function classifyError(error: Error): SieveErrorCode;

package/dist/cli/index.d.ts

@@ -0,0 +1,3 @@
+export { registerSieveCommand } from './commands/Sieve.js';
+export { SIEVE_COMMAND } from './commands/command-registry.js';
+export { SieveErrorCode } from './errors/classify-error.js';

package/dist/{utils → cli/options}/parse-options.d.ts

@@ -1,9 +1,9 @@
-import type { SieveOptionsBase } from '../types/index.js';
+import type { SieveOptionsBase } from '../../types/index.js';
 /**
  * Common pipeline options parsed from CLI opts (Commander string values → typed values).
  * Does NOT include mode-specific fields (mode, inputPath, onProgress).
  */
-export type ParsedPipelineOptions = Pick<Required<SieveOptionsBase>, 'fps' | 'maxFrames' | 'scale' | 'quality' | 'debug'> & Pick<SieveOptionsBase, 'count' | 'threshold' | 'outputPath' | 'iouThreshold' | 'animationThreshold' | 'maxSegmentDuration' | 'concurrency'>;
+export type ParsedPipelineOptions = Pick<Required<SieveOptionsBase>, 'fps' | 'maxFrames' | 'scale' | 'quality' | 'debug'> & Pick<SieveOptionsBase, 'count' | 'threshold' | 'outputPath' | 'iouThreshold' | 'animationThreshold' | 'maxSegmentDuration' | 'concurrency' | 'sheet' | 'includeEdges'>;
 export interface RawCliOptions {
     count?: string;
     threshold?: string;
@@ -17,5 +17,14 @@ export interface RawCliOptions {
     maxSegmentDuration?: string;
     concurrency?: string;
     debug?: boolean;
+    /** Request a contact sheet with default settings. */
+    sheet?: boolean;
+    /** Request candidate edge diagnostics. */
+    includeEdges?: boolean;
 }
+/**
+ * Convert CLI strings to pipeline values for subsequent range validation.
+ * @param opts - Commander options with raw numeric strings.
+ * @returns Typed settings, preserving invalid numeric input as NaN.
+ */
 export declare function parsePipelineOptions(opts: RawCliOptions): ParsedPipelineOptions;