@lumy-pack/scene-sieve 0.1.0 → 0.2.0

package/dist/pipeline-worker.mjs

@@ -4,14 +4,14 @@ import { randomUUID } from "node:crypto";
 import { filter, map } from "@winglet/common-utils";
 import pc from "picocolors";
 import sharp from "sharp";
-import { homedir, tmpdir } from "node:os";
-import { basename, extname, join, resolve } from "node:path";
 import { mkdir, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { basename, extname, join, resolve } from "node:path";
 import { path } from "@ffprobe-installer/ffprobe";
 import { execa } from "execa";
 import ffmpegPath from "ffmpeg-static";
+import { homedir, tmpdir } from "node:os";
 
-//#region src/utils/logger.ts
+//#region src/logging/logger.ts
 let debugMode = false;
 let jsonMode = false;
 function setDebugMode(enabled) {
@@ -42,25 +42,18 @@ const logger = {
 };
 
 //#endregion
-//#region src/constants.ts
-const APP_NAME = "scene-sieve";
+//#region src/constants/pipeline-defaults.ts
 const DEFAULT_THRESHOLD = .5;
-const NORMALIZATION_ALPHA = .4;
-const NORMALIZATION_MAD_COEFFICIENT = 1.4826;
-const WORKSPACE_PREFIX = `${APP_NAME}-`;
-const TEMP_BASE_DIR = tmpdir();
-const FRAME_OUTPUT_EXTENSION = ".jpg";
-const FRAME_FILENAME_PATTERN = "frame_%06d.jpg";
-const DBSCAN_ALPHA = .03;
 const IOU_THRESHOLD = .9;
+
+//#endregion
+//#region src/core/analyzer/constants/vision-tuning.ts
+const DBSCAN_ALPHA = .03;
 const DECAY_LAMBDA = .95;
 const MATCH_DISTANCE_THRESHOLD = .25;
-function getTempWorkspaceDir(sessionId) {
-	return join(TEMP_BASE_DIR, `${WORKSPACE_PREFIX}${sessionId}`);
-}
 
 //#endregion
-//#region src/core/dbscan.ts
+//#region src/core/analyzer/clustering/dbscan.ts
 const UNVISITED = -2;
 const NOISE = -1;
 /**
@@ -140,7 +133,106 @@ function findNeighbors(points, idx, epsSquared) {
 }
 
 //#endregion
-//#region src/core/analyzer.ts
+//#region src/core/analyzer/features/feature-diff.ts
+/**
+* Match prev to next with Hamming k=2, crossCheck=false and strict ratio 0.25.
+* @param cvLib - Initialized OpenCV runtime.
+* @param prev - Previous frame's live features, owned by the caller.
+* @param next - Next frame's live features, owned by the caller.
+* @returns Unmatched next-frame coordinates without changing input ownership.
+* @throws Propagates matching errors after releasing temporary native handles.
+*/
+function computeNewPoints(cvLib, prev, next) {
+	let matcher = null;
+	let matches = null;
+	try {
+		const matchedIndices = /* @__PURE__ */ new Set();
+		if (prev.descriptors.rows > 0 && next.descriptors.rows > 0) try {
+			matcher = new cvLib.BFMatcher(cvLib.NORM_HAMMING, false);
+			matches = new cvLib.DMatchVectorVector();
+			matcher.knnMatch(prev.descriptors, next.descriptors, matches, 2);
+			for (let i = 0; i < matches.size(); i++) {
+				const pair = matches.get(i);
+				try {
+					if (pair.size() < 2) continue;
+					const best = pair.get(0);
+					const second = pair.get(1);
+					if (best.distance < .25 * second.distance) matchedIndices.add(best.trainIdx);
+				} finally {
+					pair.delete();
+				}
+			}
+		} finally {
+			matcher?.delete();
+		}
+		const points = [];
+		for (let i = 0; i < next.keypoints.size(); i++) if (!matchedIndices.has(i)) {
+			const { x, y } = next.keypoints.get(i).pt;
+			points.push({
+				x,
+				y
+			});
+		}
+		return points;
+	} finally {
+		matches?.delete();
+	}
+}
+
+//#endregion
+//#region src/core/analyzer/features/frame-features.ts
+/**
+* Detect one frame's features without retaining its image or mask.
+* @param cvLib - Initialized OpenCV runtime.
+* @param akaze - Detector owned and released by the caller.
+* @param frame - Grayscale bytes with matching width and height.
+* @returns Feature handles that the caller must delete.
+* @throws Propagates native errors after releasing partial allocations.
+*/
+function computeFrameFeatures(cvLib, akaze, frame) {
+	let image = null;
+	let mask = null;
+	let keypoints = null;
+	let descriptors = null;
+	try {
+		image = new cvLib.Mat(frame.height, frame.width, cvLib.CV_8UC1);
+		image.data.set(frame.data);
+		mask = new cvLib.Mat();
+		keypoints = new cvLib.KeyPointVector();
+		descriptors = new cvLib.Mat();
+		akaze.detectAndCompute(image, mask, keypoints, descriptors);
+		const ownedKeypoints = keypoints;
+		const ownedDescriptors = descriptors;
+		let deleted = false;
+		const features = {
+			width: frame.width,
+			height: frame.height,
+			keypoints: ownedKeypoints,
+			descriptors: ownedDescriptors,
+			/** Release the transferred handles exactly once. */
+			delete() {
+				if (deleted) return;
+				deleted = true;
+				try {
+					ownedKeypoints.delete();
+				} finally {
+					ownedDescriptors.delete();
+				}
+			}
+		};
+		keypoints = null;
+		descriptors = null;
+		return features;
+	} finally {
+		image?.delete();
+		mask?.delete();
+		keypoints?.delete();
+		descriptors?.delete();
+	}
+}
+
+//#endregion
+//#region src/core/analyzer/analyzer.ts
 const OPENCV_INIT_TIMEOUT_MS = 3e4;
 const require = createRequire(import.meta.url);
 let cvReady = null;
@@ -263,77 +355,6 @@ var IoUTracker = class {
 		return maxWeight;
 	}
 };
-async function computeAKAZEDiff(cvLib, frame1, frame2) {
-	const cv = cvLib;
-	const mat1 = new cv.Mat(frame1.height, frame1.width, cv.CV_8UC1);
-	mat1.data.set(frame1.data);
-	const mat2 = new cv.Mat(frame2.height, frame2.width, cv.CV_8UC1);
-	mat2.data.set(frame2.data);
-	const kp1 = new cvLib.KeyPointVector();
-	const kp2 = new cvLib.KeyPointVector();
-	const desc1 = new cvLib.Mat();
-	const desc2 = new cvLib.Mat();
-	const mask1 = new cvLib.Mat();
-	const mask2 = new cvLib.Mat();
-	const akaze = new cvLib.AKAZE();
-	let matches = null;
-	try {
-		akaze.detectAndCompute(mat1, mask1, kp1, desc1);
-		akaze.detectAndCompute(mat2, mask2, kp2, desc2);
-		const matchedKp1Indices = /* @__PURE__ */ new Set();
-		const matchedKp2Indices = /* @__PURE__ */ new Set();
-		if (desc1.rows > 0 && desc2.rows > 0) {
-			const matcher = new cvLib.BFMatcher(cvLib.NORM_HAMMING, false);
-			try {
-				matches = new cvLib.DMatchVectorVector();
-				matcher.knnMatch(desc1, desc2, matches, 2);
-				for (let i = 0; i < matches.size(); i++) {
-					const pair = matches.get(i);
-					if (pair.size() < 2) continue;
-					const m0 = pair.get(0);
-					const m1 = pair.get(1);
-					if (m0.distance < .25 * m1.distance) {
-						matchedKp1Indices.add(m0.queryIdx);
-						matchedKp2Indices.add(m0.trainIdx);
-					}
-				}
-			} finally {
-				matcher.delete();
-			}
-		}
-		const sNew = [];
-		for (let i = 0; i < kp2.size(); i++) if (!matchedKp2Indices.has(i)) {
-			const pt = kp2.get(i).pt;
-			sNew.push({
-				x: pt.x,
-				y: pt.y
-			});
-		}
-		const sLoss = [];
-		for (let i = 0; i < kp1.size(); i++) if (!matchedKp1Indices.has(i)) {
-			const pt = kp1.get(i).pt;
-			sLoss.push({
-				x: pt.x,
-				y: pt.y
-			});
-		}
-		return {
-			sNew,
-			sLoss
-		};
-	} finally {
-		mat1.delete();
-		mat2.delete();
-		kp1.delete();
-		kp2.delete();
-		desc1.delete();
-		desc2.delete();
-		mask1.delete();
-		mask2.delete();
-		akaze.delete();
-		if (matches) matches.delete();
-	}
-}
 /**
 * Pixel-level difference fallback for AKAZE blind spots.
 *
@@ -348,17 +369,30 @@ async function computeAKAZEDiff(cvLib, frame1, frame2) {
 * 3. threshold → binary mask of significant changes
 * 4. findContours → bounding rects of changed regions
 * 5. Grid sampling within each bounding rect → Point2D[]
+*
+* @param cvLib - Initialized OpenCV runtime shared by the analyzer.
+* @param frame1 - Previous grayscale frame, with the same dimensions as frame2.
+* @param frame2 - Next grayscale frame, with the same dimensions as frame1.
+* @returns Grid-sampled points from changed regions.
+* @throws Propagates allocation or OpenCV errors after releasing acquired handles.
 */
 function computePixelDiff(cvLib, frame1, frame2) {
 	const cv = cvLib;
-	const mat1 = new cv.Mat(frame1.height, frame1.width, cv.CV_8UC1);
-	const mat2 = new cv.Mat(frame2.height, frame2.width, cv.CV_8UC1);
-	const diff = new cv.Mat();
-	const blurred = new cv.Mat();
-	const binary = new cv.Mat();
-	const contours = new cv.MatVector();
-	const hierarchy = new cv.Mat();
+	let mat1 = null;
+	let mat2 = null;
+	let diff = null;
+	let blurred = null;
+	let binary = null;
+	let contours = null;
+	let hierarchy = null;
 	try {
+		mat1 = new cv.Mat(frame1.height, frame1.width, cv.CV_8UC1);
+		mat2 = new cv.Mat(frame2.height, frame2.width, cv.CV_8UC1);
+		diff = new cv.Mat();
+		blurred = new cv.Mat();
+		binary = new cv.Mat();
+		contours = new cv.MatVector();
+		hierarchy = new cv.Mat();
 		mat1.data.set(frame1.data);
 		mat2.data.set(frame2.data);
 		cv.absdiff(mat1, mat2, diff);
@@ -369,22 +403,26 @@ function computePixelDiff(cvLib, frame1, frame2) {
 		const points = [];
 		for (let c = 0; c < contours.size(); c++) {
 			const contour = contours.get(c);
-			const rect = cv.boundingRect(contour);
-			if (rect.width * rect.height < 100) continue;
-			for (let y = rect.y; y < rect.y + rect.height; y += 8) for (let x = rect.x; x < rect.x + rect.width; x += 8) points.push({
-				x,
-				y
-			});
+			try {
+				const rect = cv.boundingRect(contour);
+				if (rect.width * rect.height < 100) continue;
+				for (let y = rect.y; y < rect.y + rect.height; y += 8) for (let x = rect.x; x < rect.x + rect.width; x += 8) points.push({
+					x,
+					y
+				});
+			} finally {
+				contour.delete();
+			}
 		}
 		return points;
 	} finally {
-		mat1.delete();
-		mat2.delete();
-		diff.delete();
-		blurred.delete();
-		binary.delete();
-		contours.delete();
-		hierarchy.delete();
+		mat1?.delete();
+		mat2?.delete();
+		diff?.delete();
+		blurred?.delete();
+		binary?.delete();
+		contours?.delete();
+		hierarchy?.delete();
 	}
 }
 function computeInformationGain(clusters, clusterPoints, imageArea, animationIndices, animationWeights) {
@@ -403,47 +441,85 @@ function computeInformationGain(clusters, clusterPoints, imageArea, animationInd
 	}
 	return gain;
 }
-async function analyzeBatch(cvLib, frames, scale, tracker, pairOffset) {
+/**
+* Analyze one batch, retaining its boundary frame for the following batch.
+* @param cvLib - Initialized OpenCV runtime.
+* @param akaze - Detector owned by analyzeFrames.
+* @param frames - Boundary frame followed by new adjacent frames.
+* @param carry - Boundary bytes and live features transferred from the previous batch.
+* @param scale - Maximum preprocessing width.
+* @param tracker - Stateful animation tracker shared across batches.
+* @param pairOffset - Global position of this batch's first pair.
+* @returns Scores, pair failure count, and ownership of the final frame's features.
+*/
+async function analyzeBatch(cvLib, akaze, frames, carry, scale, tracker, pairOffset) {
 	const edges = [];
-	const preprocessed = await Promise.all(map(frames, (f) => preprocessFrame(f.extractPath, scale)));
-	const imageWidth = preprocessed[0]?.width ?? scale;
-	const imageHeight = preprocessed[0]?.height ?? Math.round(scale * 9 / 16);
-	const imageArea = imageWidth * imageHeight;
-	for (let i = 0; i < frames.length - 1; i++) {
-		const pairIndex = pairOffset + i;
-		try {
-			const { sNew } = await computeAKAZEDiff(cvLib, preprocessed[i], preprocessed[i + 1]);
-			let dbscanResult = dbscan(sNew, imageWidth, imageHeight);
-			let clusters = dbscanResult.boundingBoxes;
-			if (clusters.length === 0) {
-				const pixelDiffPoints = computePixelDiff(cvLib, preprocessed[i], preprocessed[i + 1]);
-				if (pixelDiffPoints.length > 0) {
-					logger.debug(`Edge ${frames[i].id}->${frames[i + 1].id}: pixel-diff fallback (${pixelDiffPoints.length} points)`);
-					dbscanResult = dbscan(pixelDiffPoints, imageWidth, imageHeight, void 0, 2);
-					clusters = dbscanResult.boundingBoxes;
+	let failures = 0;
+	let prev = carry?.features ?? null;
+	let next = null;
+	try {
+		const preprocessed = await Promise.all(map(frames, (f, index) => index === 0 && carry ? carry.preprocessed : preprocessFrame(f.extractPath, scale)));
+		const imageWidth = preprocessed[0]?.width ?? scale;
+		const imageHeight = preprocessed[0]?.height ?? Math.round(scale * 9 / 16);
+		const imageArea = imageWidth * imageHeight;
+		for (let i = 0; i < frames.length - 1; i++) {
+			const pairIndex = pairOffset + i;
+			try {
+				prev ??= computeFrameFeatures(cvLib, akaze, preprocessed[i]);
+				next = computeFrameFeatures(cvLib, akaze, preprocessed[i + 1]);
+				let dbscanResult = dbscan(computeNewPoints(cvLib, prev, next), imageWidth, imageHeight);
+				let clusters = dbscanResult.boundingBoxes;
+				if (clusters.length === 0) {
+					const pixelDiffPoints = computePixelDiff(cvLib, preprocessed[i], preprocessed[i + 1]);
+					if (pixelDiffPoints.length > 0) {
+						logger.debug(`Edge ${frames[i].id}->${frames[i + 1].id}: pixel-diff fallback (${pixelDiffPoints.length} points)`);
+						dbscanResult = dbscan(pixelDiffPoints, imageWidth, imageHeight, void 0, 2);
+						clusters = dbscanResult.boundingBoxes;
+					}
 				}
+				const clusterPointCounts = new Array(clusters.length).fill(0);
+				for (const label of dbscanResult.labels) if (label >= 0) clusterPointCounts[label]++;
+				const animationIndices = tracker.update(clusters, pairIndex);
+				const animationWeights = map(clusters, (_, ci) => animationIndices.has(ci) ? tracker.getAnimationWeight(ci, clusters) : 0);
+				const score = computeInformationGain(clusters, clusterPointCounts, imageArea, animationIndices, animationWeights);
+				logger.debug(`Edge ${frames[i].id}->${frames[i + 1].id} G(t)=${score.toFixed(6)}`);
+				edges.push({
+					sourceId: frames[i].id,
+					targetId: frames[i + 1].id,
+					score
+				});
+			} catch (err) {
+				logger.warn(`Frame pair analysis failed: ${String(err)}`);
+				failures++;
+				edges.push({
+					sourceId: frames[i].id,
+					targetId: frames[i + 1].id,
+					score: 0
+				});
+			} finally {
+				prev?.delete();
+				prev = next;
+				next = null;
 			}
-			const clusterPointCounts = new Array(clusters.length).fill(0);
-			for (const label of dbscanResult.labels) if (label >= 0) clusterPointCounts[label]++;
-			const animationIndices = tracker.update(clusters, pairIndex);
-			const animationWeights = map(clusters, (_, ci) => animationIndices.has(ci) ? tracker.getAnimationWeight(ci, clusters) : 0);
-			const score = computeInformationGain(clusters, clusterPointCounts, imageArea, animationIndices, animationWeights);
-			logger.debug(`Edge ${frames[i].id}->${frames[i + 1].id} G(t)=${score.toFixed(6)}`);
-			edges.push({
-				sourceId: frames[i].id,
-				targetId: frames[i + 1].id,
-				score
-			});
-		} catch (err) {
-			logger.debug(`Frame pair analysis failed: ${String(err)}`);
-			edges.push({
-				sourceId: frames[i].id,
-				targetId: frames[i + 1].id,
-				score: 0
-			});
 		}
+		const result = {
+			edges,
+			failures,
+			analysisResolution: {
+				width: imageWidth,
+				height: imageHeight
+			},
+			carry: prev ? {
+				preprocessed: preprocessed[preprocessed.length - 1],
+				features: prev
+			} : null
+		};
+		prev = null;
+		return result;
+	} finally {
+		prev?.delete();
+		next?.delete();
 	}
-	return edges;
 }
 /**
 * Analyze adjacent frame pairs to compute information gain scores (G(t)).
@@ -454,35 +530,121 @@ async function analyzeBatch(cvLib, frames, scale, tracker, pairOffset) {
 * 2. DBSCAN Spatial Clustering
 * 3. Spatio-temporal IoU Tracking
 * 4. G(t) Information Gain Scoring
+* @param ctx - Frames, analysis options, and the progress callback for this run.
+* @returns Adjacent scores and tracked animations in analysis coordinates.
+* @throws Propagates runtime errors and rejects total failure of two or more pairs after cleanup.
 */
 async function analyzeFrames(ctx) {
 	const { frames } = ctx;
 	if (frames.length < 2) return {
 		edges: [],
-		animations: []
+		animations: [],
+		analysisResolution: {
+			width: 0,
+			height: 0
+		}
 	};
 	logger.debug(`Analyzing ${frames.length} frames in batches of ${10}`);
 	const cvLib = await ensureOpenCV();
 	const edges = [];
-	const tracker = new IoUTracker(ctx.options.fps, ctx.options.iouThreshold, ctx.options.animationThreshold);
+	const tracker = new IoUTracker(ctx.effectiveFps ?? ctx.options.fps, ctx.options.iouThreshold, ctx.options.animationThreshold);
 	const scale = ctx.options.scale;
-	for (let i = 0; i < frames.length - 1; i += 10) {
-		const batchEnd = Math.min(i + 10 + 1, frames.length);
-		const batchEdges = await analyzeBatch(cvLib, frames.slice(i, batchEnd), scale, tracker, i);
-		edges.push(...batchEdges);
-		const progress = Math.min(100, (i + 10) / (frames.length - 1) * 100);
-		ctx.emitProgress(progress);
+	let akaze = null;
+	let carry = null;
+	let analysisResolution = {
+		width: 0,
+		height: 0
+	};
+	let failures = 0;
+	try {
+		akaze = new cvLib.AKAZE();
+		for (let i = 0; i < frames.length - 1; i += 10) {
+			const batch = [frames[i], ...frames.slice(i + 1, i + 1 + 10)];
+			const result = await analyzeBatch(cvLib, akaze, batch, carry, scale, tracker, i);
+			carry = result.carry;
+			failures += result.failures;
+			if (i === 0) analysisResolution = result.analysisResolution;
+			edges.push(...result.edges);
+			const progress = Math.min(100, (i + 10) / (frames.length - 1) * 100);
+			ctx.emitProgress(progress);
+		}
+	} finally {
+		carry?.features.delete();
+		akaze?.delete();
 	}
+	const pairs = frames.length - 1;
+	if (pairs >= 2 && failures === pairs) throw new Error(`All ${pairs} frame pairs failed analysis`);
 	const animations = tracker.flushAndGetAnimations();
 	logger.debug(`Computed ${edges.length} score edges and ${animations.length} animations`);
 	return {
 		edges,
-		animations
+		animations,
+		analysisResolution
+	};
+}
+
+//#endregion
+//#region src/core/utils/metadata/build-video-metadata.ts
+/**
+* Read output dimensions and build consistent video and animation metadata.
+* JPEG finalization does not resize, so the source dimensions match the output.
+* @param ctx Pipeline state with source duration, effective FPS and analysis-space animations.
+* @param selected Selected frames in output order; the first candidate is the fallback.
+* @param analysisResolution Analysis dimensions; absent or zero dimensions imply no scaling.
+* @returns Video metadata and new output-space animations, retaining zero-based frame IDs.
+* @throws If sharp cannot read the selected or fallback image. Empty input performs no image I/O.
+*/
+async function buildVideoMetadata(ctx, selected, analysisResolution) {
+	const firstFrame = selected[0] ?? ctx.frames[0];
+	const dimensions = firstFrame ? await sharp(firstFrame.extractPath).metadata() : void 0;
+	const width = dimensions?.width ?? 0;
+	const height = dimensions?.height ?? 0;
+	const sx = analysisResolution?.width ? width / analysisResolution.width : 1;
+	const sy = analysisResolution?.height ? height / analysisResolution.height : 1;
+	const lastTimestamp = ctx.frames[ctx.frames.length - 1]?.timestamp ?? 0;
+	const duration = ctx.options.mode === "frames" ? lastTimestamp : ctx.sourceDurationSec ?? lastTimestamp;
+	return {
+		video: {
+			originalDurationMs: Math.round(duration * 1e3),
+			fps: ctx.options.mode === "frames" ? 1 : ctx.effectiveFps ?? ctx.options.fps,
+			resolution: {
+				width,
+				height
+			}
+		},
+		animations: (ctx.animations ?? []).map((animation) => {
+			const box = animation.boundingBox;
+			const x = Math.max(0, Math.min(width, Math.round(box.x * sx)));
+			const y = Math.max(0, Math.min(height, Math.round(box.y * sy)));
+			return {
+				...animation,
+				boundingBox: {
+					x,
+					y,
+					width: Math.max(0, Math.min(width - x, Math.round(box.width * sx))),
+					height: Math.max(0, Math.min(height - y, Math.round(box.height * sy)))
+				}
+			};
+		})
 	};
 }
 
 //#endregion
-//#region src/utils/paths.ts
+//#region src/core/constants/workspace-layout.ts
+/**
+* Temp workspace naming and frame file layout for pipeline runs.
+*/
+const APP_NAME = "scene-sieve";
+const WORKSPACE_PREFIX = `${APP_NAME}-`;
+const TEMP_BASE_DIR = tmpdir();
+const FRAME_OUTPUT_EXTENSION = ".jpg";
+const FRAME_FILENAME_PATTERN = "frame_%06d.jpg";
+function getTempWorkspaceDir(sessionId) {
+	return join(TEMP_BASE_DIR, `${WORKSPACE_PREFIX}${sessionId}`);
+}
+
+//#endregion
+//#region src/core/utils/filesystem/paths.ts
 async function ensureDir(dirPath) {
 	await mkdir(dirPath, { recursive: true });
 }
@@ -520,13 +682,18 @@ function deriveOutputPath(inputPath) {
 }
 
 //#endregion
-//#region src/core/extractor.ts
+//#region src/core/extractor/extractor.ts
 /**
 * Extract frames from video/GIF using FFmpeg.
-* Always uses FPS-based extraction. For long videos, FPS is automatically
-* reduced to stay within maxFrames budget.
+* @param ctx Pipeline context; records effectiveFps and sourceDurationSec for video input.
+* @returns Extracted candidates, or the unchanged input array in frames mode.
+* @throws When the input is missing, metadata has no video stream, or FFmpeg fails.
 */
 async function extractFrames(ctx) {
+	if (ctx.options.mode === "frames") {
+		ctx.effectiveFps = 1;
+		return ctx.frames;
+	}
 	const framesDir = join(ctx.workspacePath, "frames");
 	const { inputPath, fps, maxFrames, scale } = ctx.options;
 	if (!inputPath) throw new Error("inputPath is required for frame extraction");
@@ -541,19 +708,30 @@ async function extractFrames(ctx) {
 	if (!(metadata.streams?.some((s) => s.codec_type === "video") ?? false)) throw new Error(`No video stream found in file: ${inputPath} (detected format: ${formatName})`);
 	logger.debug(`Detected format: ${formatName} (Duration: ${duration.toFixed(1)}s), path: ${inputPath}`);
 	await ensureDir(framesDir);
+	const frameLimit = Math.max(2, maxFrames);
 	let effectiveFps = fps;
 	if (duration > 0) {
-		const fpsCap = maxFrames / duration;
+		const fpsCap = frameLimit / duration;
 		effectiveFps = Math.min(fps, fpsCap);
-		effectiveFps = Math.max(.5, effectiveFps);
 		logger.debug(`FPS: ${fps} → effective: ${effectiveFps.toFixed(2)} (maxFrames: ${maxFrames})`);
 	}
-	const frames = await extractByFps(inputPath, framesDir, effectiveFps, scale, duration);
+	ctx.effectiveFps = effectiveFps;
+	ctx.sourceDurationSec = duration;
+	const frames = await extractByFps(inputPath, framesDir, effectiveFps, scale, frameLimit);
 	ctx.emitProgress(100);
 	logger.debug(`Extracted ${frames.length} frames`);
 	return frames;
 }
-async function extractByFps(inputPath, outputDir, fps, scale, duration) {
+/**
+* Write scaled JPEG candidates through the bundled FFmpeg runtime.
+* @param inputPath Readable video input.
+* @param outputDir Existing frame directory.
+* @param fps Positive effective sampling frequency.
+* @param scale Output image height.
+* @param frameLimit Maximum number of output frames.
+* @returns Candidates with local output-grid timestamps; rejects on extraction failure.
+*/
+async function extractByFps(inputPath, outputDir, fps, scale, frameLimit) {
 	const outputPattern = join(outputDir, FRAME_FILENAME_PATTERN);
 	await execa(ffmpegPath, [
 		"-i",
@@ -562,9 +740,11 @@ async function extractByFps(inputPath, outputDir, fps, scale, duration) {
 		`fps=${fps},scale=-1:${scale}`,
 		"-q:v",
 		"2",
+		"-frames:v",
+		String(frameLimit),
 		outputPattern
 	]);
-	return buildFrameList(outputDir, duration);
+	return buildFrameList(outputDir, fps);
 }
 async function getVideoMetadata(inputPath) {
 	const { stdout } = await execa(path, [
@@ -578,12 +758,18 @@ async function getVideoMetadata(inputPath) {
 	]);
 	return JSON.parse(stdout);
 }
-async function buildFrameList(framesDir, duration) {
+/**
+* Read sorted JPEG paths and attach local output-grid times.
+* @param framesDir Extracted frame directory; filesystem errors propagate.
+* @param effectiveFps Positive frequency used by the fps filter.
+* @returns Zero-based candidates without a segment seek offset.
+*/
+async function buildFrameList(framesDir, effectiveFps) {
 	const jpgFiles = filter(await readdir(framesDir), (f) => f.endsWith(".jpg")).sort();
 	if (jpgFiles.length === 0) return [];
 	return map(jpgFiles, (file, index) => ({
 		id: index,
-		timestamp: duration > 0 && jpgFiles.length > 1 ? duration * index / (jpgFiles.length - 1) : index,
+		timestamp: index / effectiveFps,
 		extractPath: join(framesDir, file)
 	}));
 }
@@ -597,9 +783,10 @@ async function buildFrameList(framesDir, duration) {
 * @param scale - Height scale for vision analysis
 * @param startTime - Start time in seconds
 * @param duration - Duration in seconds to extract
+* @param frameLimit - Positive output limit; defaults to the range's grid capacity
 * @returns Array of FrameNode with segment-local timestamps (starting from 0)
 */
-async function extractFramesForRange(inputPath, outputDir, fps, scale, startTime, duration) {
+async function extractFramesForRange(inputPath, outputDir, fps, scale, startTime, duration, frameLimit = Math.ceil(duration * fps)) {
 	const outputPattern = join(outputDir, FRAME_FILENAME_PATTERN);
 	await execa(ffmpegPath, [
 		"-ss",
@@ -612,13 +799,112 @@ async function extractFramesForRange(inputPath, outputDir, fps, scale, startTime
 		`fps=${fps},scale=-1:${scale}`,
 		"-q:v",
 		"2",
+		"-frames:v",
+		String(frameLimit),
 		outputPattern
 	]);
-	return buildFrameList(outputDir, duration);
+	return buildFrameList(outputDir, fps);
+}
+
+//#endregion
+//#region src/core/input-resolver/validation/validate-options.ts
+/**
+* Reject invalid numeric options before defaults or pipeline effects are applied.
+* @param options - Supplied options; omitted numeric fields use pipeline defaults.
+* @returns Nothing when all supplied numeric fields satisfy their contracts.
+* @throws An input error naming the invalid option and its received value.
+*/
+function validateOptions(options) {
+	for (const [name, min, max, integer, exclusiveMin, requirement] of [
+		[
+			"count",
+			1,
+			Infinity,
+			true,
+			false,
+			"an integer >= 1"
+		],
+		[
+			"threshold",
+			0,
+			1,
+			false,
+			true,
+			"in range (0, 1] and finite"
+		],
+		[
+			"fps",
+			0,
+			Infinity,
+			false,
+			true,
+			"finite and > 0"
+		],
+		[
+			"maxFrames",
+			2,
+			Infinity,
+			true,
+			false,
+			"an integer >= 2"
+		],
+		[
+			"scale",
+			16,
+			Infinity,
+			true,
+			false,
+			"an integer >= 16"
+		],
+		[
+			"quality",
+			1,
+			100,
+			true,
+			false,
+			"an integer in range [1, 100]"
+		],
+		[
+			"iouThreshold",
+			0,
+			1,
+			false,
+			false,
+			"finite and in range [0, 1]"
+		],
+		[
+			"animationThreshold",
+			1,
+			Infinity,
+			true,
+			false,
+			"an integer >= 1"
+		],
+		[
+			"maxSegmentDuration",
+			0,
+			Infinity,
+			false,
+			true,
+			"finite and > 0"
+		],
+		[
+			"concurrency",
+			1,
+			Infinity,
+			true,
+			false,
+			"an integer >= 1"
+		]
+	]) {
+		const value = options[name];
+		if (value === void 0) continue;
+		if (!Number.isFinite(value) || integer && !Number.isInteger(value) || (exclusiveMin ? value <= min : value < min) || value > max) throw new Error(`${name} must be ${requirement}, received: ${value}`);
+	}
 }
 
 //#endregion
-//#region src/core/workspace.ts
+//#region src/core/workspace/workspace.ts
 async function createWorkspace(sessionId) {
 	const workspacePath = getTempWorkspaceDir(sessionId);
 	await ensureDir(join(workspacePath, "frames"));
@@ -649,17 +935,11 @@ async function finalizeOutput(ctx, selectedFrames) {
 			timestampMs: Math.round(frame.timestamp * 1e3)
 		});
 	}
+	const { video, animations } = await buildVideoMetadata(ctx, selectedFrames, ctx.analysisResolution);
 	const metadata = {
-		video: {
-			originalDurationMs: Math.round((ctx.frames.length > 0 ? ctx.frames[ctx.frames.length - 1].timestamp : 0) * 1e3),
-			fps: ctx.options.fps,
-			resolution: {
-				width: ctx.options.scale,
-				height: Math.round(ctx.options.scale * 9 / 16)
-			}
-		},
+		video,
 		frames: framesMetadata,
-		animations: map(ctx.animations || [], (anim) => ({
+		animations: map(animations, (anim) => ({
 			...anim,
 			startFrameId: anim.startFrameId + 1,
 			endFrameId: anim.endFrameId + 1,
@@ -732,13 +1012,19 @@ async function readFramesAsBuffers(frameNodes, quality) {
 }
 
 //#endregion
-//#region src/core/input-resolver.ts
+//#region src/core/input-resolver/input-resolver.ts
+/**
+* Validate supplied options and resolve defaults and paths for the pipeline.
+* @param options - Mode-specific input and optional numeric settings.
+* @returns Complete pipeline settings with absolute file input paths.
+* @throws An input error if a supplied numeric setting is invalid.
+*/
 function resolveOptions(options) {
+	validateOptions(options);
 	const mode = options.mode;
 	const inputPath = mode === "file" ? resolveAbsolute(options.inputPath) : void 0;
 	const outputPath = options.outputPath ?? (inputPath ? deriveOutputPath(inputPath) : join(process.cwd(), "scene-sieve-output"));
 	const threshold = options.threshold ?? .5;
-	if (threshold <= 0 || threshold > 1) throw new Error(`threshold must be in range (0, 1], received: ${threshold}`);
 	return {
 		mode,
 		inputPath,
@@ -763,6 +1049,10 @@ function resolveOptions(options) {
 * - 'file'   mode: validate file exists and delegate to extractor (caller's responsibility)
 * - 'buffer' mode: write buffer as temp video file, return path via FrameNode trick (empty list)
 * - 'frames' mode: write frame buffers as JPGs, return FrameNode[]
+* @param options - Input source; encoded frames must have matching dimensions.
+* @param workspacePath - Workspace receiving temporary input files.
+* @returns Frame nodes or a resolved video path for extraction.
+* @throws Propagates metadata or write errors and rejects mismatched frame sizes.
 */
 async function resolveInput(options, workspacePath) {
 	if (options.mode === "file") return {
@@ -773,12 +1063,42 @@ async function resolveInput(options, workspacePath) {
 		frames: [],
 		resolvedInputPath: await writeInputBuffer(options.inputBuffer, workspacePath)
 	};
-	if (options.mode === "frames") return { frames: await writeInputFrames(options.inputFrames, workspacePath) };
+	if (options.mode === "frames") {
+		let dimensions;
+		for (const buffer of options.inputFrames) {
+			const { width, height } = await sharp(buffer).metadata();
+			if (dimensions && (width !== dimensions.width || height !== dimensions.height)) throw new Error(`inputFrames must be the same size (${dimensions.width}x${dimensions.height}), received: ${width}x${height}`);
+			dimensions = {
+				width,
+				height
+			};
+		}
+		return { frames: await writeInputFrames(options.inputFrames, workspacePath) };
+	}
 	throw new Error(`Unsupported input mode: ${options.mode}`);
 }
 
 //#endregion
-//#region src/utils/math.ts
+//#region src/core/pruner/scoring/normalize-scores.ts
+const NORMALIZATION_ALPHA = .4;
+const NORMALIZATION_MAD_COEFFICIENT = 1.4826;
+const NORMALIZATION_MIN_SAMPLE_SIZE = 10;
+/**
+* Find the first position whose score is at least the requested value.
+* @param sorted - Finite positive scores sorted in ascending order.
+* @param value - A finite positive score present in sorted.
+* @returns The first matching rank, including the first position of any tie.
+*/
+function lowerBound(sorted, value) {
+	let low = 0;
+	let high = sorted.length;
+	while (low < high) {
+		const mid = Math.floor((low + high) / 2);
+		if (sorted[mid] < value) low = mid + 1;
+		else high = mid;
+	}
+	return low;
+}
 /**
 * Normalize raw scores to [0, 1] range via Robust Hybrid Normalization.
 *
@@ -823,13 +1143,13 @@ function normalizeScores(items) {
 	});
 	const cdf = map(safeScores, (s) => {
 		if (s <= 0) return 0;
-		return sorted.findIndex((v) => v >= s) / sorted.length;
+		return lowerBound(sorted, s) / sorted.length;
 	});
 	return map(logisticZ, (z, i) => z * (1 - NORMALIZATION_ALPHA) + cdf[i] * NORMALIZATION_ALPHA);
 }
 
 //#endregion
-//#region src/utils/min-heap.ts
+//#region src/core/pruner/heap/min-heap.ts
 /**
 * Generic binary min-heap.
 *
@@ -880,7 +1200,7 @@ var MinHeap = class {
 };
 
 //#endregion
-//#region src/core/pruner.ts
+//#region src/core/pruner/pruner.ts
 /**
 * Edge-aware greedy merge with re-linking — O(N log N).
 *
@@ -994,7 +1314,7 @@ function suppressConsecutiveRuns(graph, passingIndices, normalizedScores) {
 	return result;
 }
 /**
-* Threshold-based pruning with NMS -- O(N).
+* Threshold-based pruning with NMS -- including normalization, O(N log N).
 *
 * 1. Scores are normalized to [0, 1] via percentile normalization.
 * 2. Edges with normalized score >= threshold are collected.
@@ -1059,7 +1379,7 @@ function pruneByThresholdWithCap(graph, frames, threshold, maxCount) {
 }
 
 //#endregion
-//#region src/utils/concurrency.ts
+//#region src/core/segmenter/scheduling/concurrency.ts
 /**
 * Creates a concurrency limiter that runs at most `limit` tasks in parallel.
 * Lightweight replacement for p-limit to avoid external dependency.
@@ -1081,7 +1401,7 @@ function concurrencyLimit(limit) {
 }
 
 //#endregion
-//#region src/core/segmenter.ts
+//#region src/core/segmenter/segmenter.ts
 /**
 * Determine whether segmentation should be used.
 * Returns false for frames mode and GIF files.
@@ -1095,53 +1415,62 @@ function shouldSegment(resolvedOptions, originalOptions) {
 	return true;
 }
 /**
-* 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)
+* Partition the global extraction grid into nonempty logical segments.
+* @param totalDuration Positive source duration in seconds.
+* @param maxSegmentDuration Positive logical segment width in seconds.
+* @param maxFrames Candidate budget, defensively raised to at least two.
+* @param fps Positive requested sampling frequency.
+* @returns Contiguous plan indices with grid-aligned seeks and overlap-inclusive limits.
 */
 function computeSegmentPlan(totalDuration, maxSegmentDuration, maxFrames, fps) {
-	const effectiveFps = Math.max(.5, Math.min(fps, maxFrames / totalDuration));
+	const frameLimit = Math.max(2, maxFrames);
+	const effectiveFps = Math.min(fps, frameLimit / totalDuration);
 	if (totalDuration <= maxSegmentDuration) return [{
 		index: 0,
 		startTime: 0,
 		endTime: totalDuration,
 		duration: totalDuration,
-		allocatedFrames: Math.min(Math.ceil(effectiveFps * totalDuration), maxFrames),
+		allocatedFrames: frameLimit,
 		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 extractDuration = Math.min(totalDuration, endTime + overlapAfter * overlapTime) - extractStartTime;
+	for (let slot = 0; slot < frameLimit; slot++) {
+		const timestamp = slot / effectiveFps;
+		if (timestamp >= totalDuration) break;
+		const startTime = Math.floor(timestamp / maxSegmentDuration) * maxSegmentDuration;
+		const previous = segments[segments.length - 1];
+		if (previous?.startTime === startTime) {
+			previous.allocatedFrames++;
+			continue;
+		}
+		const endTime = Math.min(startTime + maxSegmentDuration, totalDuration);
 		segments.push({
-			index: i,
+			index: segments.length,
 			startTime,
 			endTime,
-			duration,
-			allocatedFrames: Math.ceil(effectiveFps * duration),
+			duration: endTime - startTime,
+			allocatedFrames: 1,
 			effectiveFps,
-			overlapBefore,
-			overlapAfter,
-			extractStartTime,
-			extractDuration
+			overlapBefore: 0,
+			overlapAfter: 0,
+			extractStartTime: timestamp,
+			extractDuration: 0
 		});
 	}
-	const totalAllocated = segments.reduce((sum, s) => sum + s.allocatedFrames, 0);
-	if (totalAllocated > maxFrames) segments[segments.length - 1].allocatedFrames -= totalAllocated - maxFrames;
+	let firstSlot = 0;
+	for (const segment of segments) {
+		const nextSlot = firstSlot + segment.allocatedFrames;
+		segment.overlapBefore = segment.index > 0 ? 1 : 0;
+		segment.overlapAfter = segment.index < segments.length - 1 ? 1 : 0;
+		segment.extractStartTime = (firstSlot - segment.overlapBefore) / effectiveFps;
+		segment.extractDuration = (segment.overlapAfter ? Math.min(totalDuration, (nextSlot + 1) / effectiveFps) : totalDuration) - segment.extractStartTime;
+		segment.allocatedFrames += segment.overlapBefore + segment.overlapAfter;
+		firstSlot = nextSlot;
+	}
 	return segments;
 }
 /**
@@ -1160,44 +1489,58 @@ function collectAllFrames(segmentResults) {
 	return allFrames;
 }
 /**
-* Sort frames by timestamp then remove overlap duplicates.
-* Threshold: 1/(effectiveFps * 2) — adaptive to fps (Section 18 note 5).
-* Keeps the first occurrence (earlier segment).
+* Sort frames in place and alias overlap duplicates to the first survivor.
+* @param frames Collected entries whose segment index and local ID identify a frame.
+* @param effectiveFps Positive sampling frequency; half a frame interval is the threshold.
+* @returns Timestamp-ordered survivors and duplicate keys pointing directly to survivor keys.
 */
 function deduplicateFrames(frames, effectiveFps) {
 	frames.sort((a, b) => a.frame.timestamp - b.frame.timestamp);
 	const dupThreshold = 1 / (effectiveFps * 2);
 	const unique = [];
+	const aliases = /* @__PURE__ */ new Map();
 	for (const entry of frames) {
 		if (unique.length > 0) {
 			const last = unique[unique.length - 1];
-			if (Math.abs(entry.frame.timestamp - last.frame.timestamp) < dupThreshold) continue;
+			if (Math.abs(entry.frame.timestamp - last.frame.timestamp) < dupThreshold) {
+				aliases.set(`${entry.segmentIndex}:${entry.localId}`, `${last.segmentIndex}:${last.localId}`);
+				continue;
+			}
 		}
 		unique.push(entry);
 	}
-	return unique;
+	return {
+		unique,
+		aliases
+	};
 }
 /**
-* Assign sequential global IDs to deduplicated frames and build a lookup map.
-* Returns the remapped FrameNode array and the "segmentIndex:localId" -> globalId map.
+* Assign sequential global IDs and retain duplicate local IDs as aliases.
+* @param uniqueFrames Timestamp-ordered survivors with distinct segment/local keys.
+* @param aliases Duplicate keys pointing directly to keys in uniqueFrames.
+* @returns Remapped frames and a global ID lookup covering survivors and duplicates.
 */
-function remapFrameIds(uniqueFrames) {
+function remapFrameIds(uniqueFrames, aliases) {
 	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
+		};
+	});
+	for (const [alias, survivor] of aliases) globalIdMap.set(alias, globalIdMap.get(survivor));
 	return {
-		frames: uniqueFrames.map((entry, globalId) => {
-			globalIdMap.set(`${entry.segmentIndex}:${entry.localId}`, globalId);
-			return {
-				id: globalId,
-				timestamp: entry.frame.timestamp,
-				extractPath: entry.frame.extractPath
-			};
-		}),
+		frames,
 		globalIdMap
 	};
 }
 /**
-* Remap edge source/target IDs using the global ID map.
-* Duplicate edges (same source-target pair) retain the higher score.
+* Remap edges, dropping missing endpoints and self loops while keeping the highest pair score.
+* @param segmentResults Segment-local edges in encounter order.
+* @param globalIdMap Survivor and duplicate local keys mapped to global IDs.
+* @returns One edge per surviving directed pair without changing its score.
 */
 function remapEdges(segmentResults, globalIdMap) {
 	const edges = [];
@@ -1206,6 +1549,7 @@ function remapEdges(segmentResults, globalIdMap) {
 		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;
+		if (newSourceId === newTargetId) continue;
 		const edgeKey = `${newSourceId}-${newTargetId}`;
 		const existingIdx = edgeMap.get(edgeKey);
 		if (existingIdx !== void 0) {
@@ -1226,42 +1570,52 @@ function remapEdges(segmentResults, globalIdMap) {
 	return edges;
 }
 /**
-* Remap animation startFrameId/endFrameId using the global ID map.
-* Animations whose frame IDs were deduplicated (not in map) are dropped.
+* Remap animations, dropping missing or collapsed endpoints and retaining the first pair entry.
+* @param segmentResults Segment-local tracker entries in encounter order.
+* @param globalIdMap Survivor and duplicate local keys mapped to global IDs.
+* @returns One animation per directed pair with its original tracker duration and metadata.
 */
 function remapAnimations(segmentResults, globalIdMap) {
-	const animations = [];
+	const animations = /* @__PURE__ */ new Map();
 	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({
+		if (newStartId === newEndId) continue;
+		const animationKey = `${newStartId}-${newEndId}`;
+		if (animations.has(animationKey)) continue;
+		animations.set(animationKey, {
 			...anim,
 			startFrameId: newStartId,
 			endFrameId: newEndId
 		});
 	}
-	return animations;
+	return [...animations.values()];
 }
 /**
 * 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
+* @param segmentResults Local frames, edges and tracker entries with distinct segment indices.
+* @returns Global timestamp-ordered frames, aliased edges and animations without self loops.
+* Duplicate edges keep the higher score; duplicate animations keep the first tracker entry.
 */
 function mergeSegmentFrames(segmentResults) {
 	if (segmentResults.length === 0) return {
 		frames: [],
 		edges: [],
-		animations: []
+		animations: [],
+		analysisResolution: {
+			width: 0,
+			height: 0
+		}
 	};
 	const effectiveFps = segmentResults[0].segment.effectiveFps;
-	const { frames, globalIdMap } = remapFrameIds(deduplicateFrames(collectAllFrames(segmentResults), effectiveFps));
+	const { unique, aliases } = deduplicateFrames(collectAllFrames(segmentResults), effectiveFps);
+	const { frames, globalIdMap } = remapFrameIds(unique, aliases);
 	return {
 		frames,
 		edges: remapEdges(segmentResults, globalIdMap),
-		animations: remapAnimations(segmentResults, globalIdMap)
+		animations: remapAnimations(segmentResults, globalIdMap),
+		analysisResolution: segmentResults[0].analysisResolution
 	};
 }
 function buildSegmentContext(segment, frames, segmentWorkspacePath, resolvedOptions, onProgress) {
@@ -1272,6 +1626,7 @@ function buildSegmentContext(segment, frames, segmentWorkspacePath, resolvedOpti
 			maxFrames: segment.allocatedFrames
 		},
 		workspacePath: segmentWorkspacePath,
+		effectiveFps: segment.effectiveFps,
 		frames,
 		graph: [],
 		status: "ANALYZING",
@@ -1283,19 +1638,24 @@ function buildSegmentContext(segment, frames, segmentWorkspacePath, resolvedOpti
 * Each segment uses an isolated workspace directory.
 */
 async function processSegment(inputPath, segment, workspacePath, resolvedOptions, onProgress) {
-	const frames = await extractFramesForRange(inputPath, join(workspacePath, "frames"), segment.effectiveFps, resolvedOptions.scale, segment.extractStartTime, segment.extractDuration);
+	const frames = await extractFramesForRange(inputPath, join(workspacePath, "frames"), segment.effectiveFps, resolvedOptions.scale, segment.extractStartTime, segment.extractDuration, segment.allocatedFrames);
 	if (frames.length < 2) return {
 		segment,
 		frames,
 		edges: [],
-		animations: []
+		animations: [],
+		analysisResolution: {
+			width: 0,
+			height: 0
+		}
 	};
-	const { edges, animations } = await analyzeFrames(buildSegmentContext(segment, frames, workspacePath, resolvedOptions, onProgress));
+	const { edges, animations, analysisResolution } = await analyzeFrames(buildSegmentContext(segment, frames, workspacePath, resolvedOptions, onProgress));
 	return {
 		segment,
 		frames,
 		edges,
-		animations
+		animations,
+		analysisResolution
 	};
 }
 /**
@@ -1335,7 +1695,7 @@ async function runSegmentedPipeline(options, resolvedOptions) {
 			});
 		})));
 		options.onProgress?.("ANALYZING", 100);
-		const { frames, edges, animations } = mergeSegmentFrames(results);
+		const { frames, edges, animations, analysisResolution } = 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);
@@ -1344,6 +1704,9 @@ async function runSegmentedPipeline(options, resolvedOptions) {
 		options.onProgress?.("FINALIZING", 0);
 		const ctx = {
 			options: resolvedOptions,
+			effectiveFps: segments[0]?.effectiveFps,
+			sourceDurationSec: totalDuration,
+			analysisResolution,
 			workspacePath: mainWorkspace,
 			frames,
 			graph: edges,
@@ -1357,21 +1720,14 @@ async function runSegmentedPipeline(options, resolvedOptions) {
 		else outputFiles = await finalizeOutput(ctx, prunedFrames);
 		options.onProgress?.("FINALIZING", 100);
 		logger.success(`Segmented pipeline: ${prunedFrames.length} scenes from ${frames.length} frames (${segments.length} segments)`);
+		const outputMetadata = await buildVideoMetadata(ctx, prunedFrames, analysisResolution);
 		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)
-				}
-			},
+			...outputMetadata,
 			executionTimeMs: Date.now() - pipelineStart
 		};
 	} catch (error) {
@@ -1385,9 +1741,9 @@ async function runSegmentedPipeline(options, resolvedOptions) {
 }
 
 //#endregion
-//#region src/core/orchestrator.ts
+//#region src/core/orchestrator/orchestrator.ts
 async function runPipeline(options) {
-	if (options.debug ?? false) setDebugMode(true);
+	setDebugMode(options.debug ?? false);
 	const resolvedOptions = resolveOptions(options);
 	if (shouldSegment(resolvedOptions, options)) return runSegmentedPipeline(options, resolvedOptions);
 	const startTime = Date.now();
@@ -1407,19 +1763,27 @@ async function runPipeline(options) {
 		logger.debug(`Workspace created: ${ctx.workspacePath}`);
 		ctx.status = "EXTRACTING";
 		const { frames: resolvedFrames, resolvedInputPath } = await resolveInput(options, ctx.workspacePath);
-		if (resolvedOptions.mode === "frames") ctx.frames = resolvedFrames;
-		else ctx.frames = await extractFrames({
-			...ctx,
-			options: {
-				...resolvedOptions,
-				inputPath: resolvedInputPath
-			}
-		});
+		if (resolvedOptions.mode === "frames") {
+			ctx.frames = resolvedFrames;
+			ctx.effectiveFps = 1;
+		} else {
+			const extractCtx = {
+				...ctx,
+				options: {
+					...resolvedOptions,
+					inputPath: resolvedInputPath
+				}
+			};
+			ctx.frames = await extractFrames(extractCtx);
+			ctx.effectiveFps = extractCtx.effectiveFps;
+			ctx.sourceDurationSec = extractCtx.sourceDurationSec;
+		}
 		ctx.emitProgress(100);
 		ctx.status = "ANALYZING";
-		const { edges, animations } = await analyzeFrames(ctx);
+		const { edges, animations, analysisResolution } = await analyzeFrames(ctx);
 		ctx.graph = edges;
 		ctx.animations = animations;
+		ctx.analysisResolution = analysisResolution;
 		ctx.status = "PRUNING";
 		const survivingIds = pruneByThresholdWithCap(ctx.graph, ctx.frames, resolvedOptions.threshold, resolvedOptions.count);
 		const prunedFrames = filter(ctx.frames, (f) => survivingIds.has(f.id));
@@ -1436,21 +1800,14 @@ async function runPipeline(options) {
 		}
 		ctx.status = "SUCCESS";
 		logger.success(`Extracted ${prunedFrames.length} scenes from ${ctx.frames.length} frames`);
+		const metadata = await buildVideoMetadata(ctx, prunedFrames, analysisResolution);
 		return {
 			success: true,
 			originalFramesCount: ctx.frames.length,
 			prunedFramesCount: prunedFrames.length,
 			outputFiles,
 			outputBuffers,
-			animations: ctx.animations,
-			video: {
-				originalDurationMs: ctx.frames.length / ctx.options.fps * 1e3,
-				fps: ctx.options.fps,
-				resolution: {
-					width: ctx.options.scale,
-					height: Math.round(ctx.options.scale * 9 / 16)
-				}
-			},
+			...metadata,
 			executionTimeMs: Date.now() - startTime
 		};
 	} catch (error) {
@@ -1465,7 +1822,7 @@ async function runPipeline(options) {
 }
 
 //#endregion
-//#region src/core/pipeline-worker.ts
+//#region src/core/orchestrator/worker/pipeline-worker.ts
 runPipeline({
 	...workerData,
 	onProgress: (phase, percent) => {