@doedja/scenecut 1.0.1 → 1.0.2

package/dist/keyframes.cjs.js

@@ -280,31 +280,66 @@ class RingBuffer {
         this.availableBytes += chunkSize;
     }
     /**
-     * Read data from the ring buffer
+     * Read data from the ring buffer (allocates new buffer)
      */
     read(size) {
         if (size > this.availableBytes) {
             throw new Error('RingBuffer underflow: not enough data available');
         }
         const result = Buffer.allocUnsafe(size);
+        this.readIntoBuffer(result, 0, size);
+        return result;
+    }
+    /**
+     * Read data directly into a pre-allocated Uint8Array (zero-allocation)
+     */
+    readInto(target, offset, size) {
+        if (size > this.availableBytes) {
+            throw new Error('RingBuffer underflow: not enough data available');
+        }
         const endSpace = this.capacity - this.readPos;
         if (size <= endSpace) {
             // No wrap-around needed
-            this.buffer.copy(result, 0, this.readPos, this.readPos + size);
+            for (let i = 0; i < size; i++) {
+                target[offset + i] = this.buffer[this.readPos + i];
+            }
             this.readPos += size;
         }
         else {
             // Wrap-around: split read
-            this.buffer.copy(result, 0, this.readPos, this.capacity);
-            this.buffer.copy(result, endSpace, 0, size - endSpace);
-            this.readPos = size - endSpace;
+            for (let i = 0; i < endSpace; i++) {
+                target[offset + i] = this.buffer[this.readPos + i];
+            }
+            const remaining = size - endSpace;
+            for (let i = 0; i < remaining; i++) {
+                target[offset + endSpace + i] = this.buffer[i];
+            }
+            this.readPos = remaining;
         }
         // Wrap read position if at end
         if (this.readPos >= this.capacity) {
             this.readPos = 0;
         }
         this.availableBytes -= size;
-        return result;
+    }
+    /**
+     * Internal: read into a Node.js Buffer
+     */
+    readIntoBuffer(result, offset, size) {
+        const endSpace = this.capacity - this.readPos;
+        if (size <= endSpace) {
+            this.buffer.copy(result, offset, this.readPos, this.readPos + size);
+            this.readPos += size;
+        }
+        else {
+            this.buffer.copy(result, offset, this.readPos, this.capacity);
+            this.buffer.copy(result, offset + endSpace, 0, size - endSpace);
+            this.readPos = size - endSpace;
+        }
+        if (this.readPos >= this.capacity) {
+            this.readPos = 0;
+        }
+        this.availableBytes -= size;
     }
     /**
      * Get number of bytes available to read
@@ -333,7 +368,7 @@ class FFmpegDecoder {
         this.frameBuffer = new FrameBuffer(this.options.maxBufferFrames);
     }
     /**
-     * Get video metadata
+     * Get video metadata (with richer codec/format info)
      */
     async getMetadata() {
         if (this.metadata) {
@@ -360,7 +395,10 @@ class FFmpegDecoder {
                     resolution: {
                         width: videoStream.width || 0,
                         height: videoStream.height || 0
-                    }
+                    },
+                    codec: videoStream.codec_name || undefined,
+                    pixelFormat: videoStream.pix_fmt || undefined,
+                    bitrate: metadata.format.bit_rate ? parseInt(String(metadata.format.bit_rate)) : undefined
                 };
                 resolve(this.metadata);
             });
@@ -379,16 +417,26 @@ class FFmpegDecoder {
     /**
      * Extract frames as grayscale data
      *
+     * Uses pre-allocated alternating buffers to eliminate double allocation.
+     * Auto-sizes ring buffer based on video resolution.
+     *
      * @param onFrame Callback for each frame
      * @param onProgress Optional progress callback
+     * @param signal Optional AbortSignal for cancellation
      */
-    async extractFrames(onFrame, onProgress) {
+    async extractFrames(onFrame, onProgress, signal) {
         const metadata = await this.getMetadata();
         const { width, height } = metadata.resolution;
         return new Promise((resolve, reject) => {
             let frameNumber = 0;
-            const ringBuffer = new RingBuffer(); // 8MB ring buffer
             const frameSize = width * height; // Grayscale: 1 byte per pixel
+            // Auto-size ring buffer based on resolution (min 4MB, fits 3 frames)
+            const ringBufferSize = Math.max(4 * 1024 * 1024, frameSize * 3);
+            const ringBuffer = new RingBuffer(ringBufferSize);
+            // Pre-allocate two alternating frame buffers (eliminates double allocation)
+            const frameBufferA = new Uint8Array(frameSize);
+            const frameBufferB = new Uint8Array(frameSize);
+            let useBufferA = true;
             const command = ffmpeg__namespace.default(this.videoPath)
                 .outputOptions([
                 '-f', 'image2pipe',
@@ -402,20 +450,38 @@ class FFmpegDecoder {
                 resolve();
             });
             const stream = command.pipe();
+            // Listen for abort signal
+            if (signal) {
+                const onAbort = () => {
+                    stream.destroy();
+                    reject(new Error('Detection aborted'));
+                };
+                if (signal.aborted) {
+                    stream.destroy();
+                    reject(new Error('Detection aborted'));
+                    return;
+                }
+                signal.addEventListener('abort', onAbort, { once: true });
+            }
             stream.on('data', async (chunk) => {
-                // Write chunk to ring buffer (no allocation, no copying)
+                // Write chunk to ring buffer
                 ringBuffer.write(chunk);
                 // Process complete frames
                 while (ringBuffer.available() >= frameSize) {
-                    const frameData = ringBuffer.read(frameSize);
                     // Skip frames if requested
                     if (this.options.skipFrames > 0 && frameNumber % (this.options.skipFrames + 1) !== 0) {
+                        // Still need to consume the data from the ring buffer
+                        ringBuffer.read(frameSize);
                         frameNumber++;
                         continue;
                     }
-                    // Create RawFrame
+                    // Read directly into pre-allocated buffer (zero-allocation)
+                    const targetBuffer = useBufferA ? frameBufferA : frameBufferB;
+                    ringBuffer.readInto(targetBuffer, 0, frameSize);
+                    useBufferA = !useBufferA;
+                    // Create RawFrame (reuses the pre-allocated buffer - no copy)
                     const frame = {
-                        data: new Uint8Array(frameData),
+                        data: targetBuffer,
                         width,
                         height,
                         stride: width,
@@ -485,6 +551,59 @@ class FFmpegDecoder {
             });
         });
     }
+    /**
+     * Extract multiple frame images in a single FFmpeg invocation
+     * Uses FFmpeg's select filter to avoid N+1 process spawning
+     *
+     * @param frameNumbers Array of frame numbers to extract
+     * @param options Image extraction options
+     */
+    async extractFrameImages(frameNumbers, options) {
+        const metadata = await this.getMetadata();
+        // Ensure output directory exists
+        if (!fs__namespace.existsSync(options.outputDir)) {
+            fs__namespace.mkdirSync(options.outputDir, { recursive: true });
+        }
+        const format = options.format || 'jpg';
+        const quality = options.quality || 85;
+        const template = options.filenameTemplate || 'scene_{frame}';
+        // Build FFmpeg select filter expression
+        // select='eq(n,100)+eq(n,200)+eq(n,300)'
+        const selectExpr = frameNumbers.map(n => `eq(n\\,${n})`).join('+');
+        return new Promise((resolve, reject) => {
+            const outputPaths = [];
+            // Generate output filenames
+            for (const frameNum of frameNumbers) {
+                const timestamp = frameNum / metadata.fps;
+                const filename = template
+                    .replace('{frame}', String(frameNum))
+                    .replace('{timestamp}', timestamp.toFixed(3));
+                outputPaths.push(path__namespace.join(options.outputDir, `${filename}.${format}`));
+            }
+            // Use FFmpeg with select filter and output pattern
+            const outputPattern = path__namespace.join(options.outputDir, `${template.replace('{frame}', '%d').replace('{timestamp}', '%d')}.${format}`);
+            const outputOptions = [
+                '-vf', `select='${selectExpr}',setpts=N/TB`,
+                '-vsync', 'vfr'
+            ];
+            if (format === 'jpg') {
+                outputOptions.push('-qscale:v', String(Math.round((100 - quality) / 3.33)));
+            }
+            if (options.width) {
+                outputOptions.push('-vf', `select='${selectExpr}',scale=${options.width}:-1,setpts=N/TB`);
+            }
+            ffmpeg__namespace.default(this.videoPath)
+                .outputOptions(outputOptions)
+                .output(outputPattern)
+                .on('error', (err) => {
+                reject(new Error(`FFmpeg frame extraction error: ${err.message}`));
+            })
+                .on('end', () => {
+                resolve(outputPaths);
+            })
+                .run();
+        });
+    }
     /**
      * Get the frame buffer
      */
@@ -507,19 +626,27 @@ class FFmpegDecoder {
  * - Memory allocation and management
  * - Calling WASM functions
  * - Data marshalling between JS and WASM
+ * - Double-buffering to avoid redundant frame copies
  */
 class WasmBridge {
     constructor() {
         this.module = null;
         this.initialized = false;
-        // Pre-allocated WASM buffers for frame processing
-        this.prevFramePtr = 0; // Raw previous frame
-        this.curFramePtr = 0; // Raw current frame
-        this.prevPaddedPtr = 0; // Padded previous frame
-        this.curPaddedPtr = 0; // Padded current frame
-        this.allocatedFrameSize = 0; // Size of raw frame buffers
-        this.allocatedPaddedSize = 0; // Size of padded frame buffers
+        // Double-buffered WASM pointers for frame processing
+        // Slot A and Slot B raw frame buffers
+        this.slotARawPtr = 0;
+        this.slotBRawPtr = 0;
+        // Slot A and Slot B padded frame buffers
+        this.slotAPaddedPtr = 0;
+        this.slotBPaddedPtr = 0;
+        // Which slot currently holds the "previous" frame (true = A, false = B)
+        this.prevIsSlotA = true;
+        // Whether the previous slot has valid padded data
+        this.prevSlotPadded = false;
+        this.allocatedFrameSize = 0;
+        this.allocatedPaddedSize = 0;
     }
+    // Frame dimensions (reserved for future use in validation/resizing)
     /**
      * Initialize the WASM module
      */
@@ -552,11 +679,8 @@ class WasmBridge {
         }
     }
     /**
-     * Pre-allocate WASM buffers for frame processing
-     * This eliminates per-frame allocation overhead and reduces memory copies
-     *
-     * @param width Frame width
-     * @param height Frame height
+     * Pre-allocate WASM buffers for frame processing.
+     * Allocates double-buffered raw + padded slots and pre-allocates the MB array.
      */
     allocateBuffers(width, height) {
         this.ensureInitialized();
@@ -564,63 +688,104 @@ class WasmBridge {
         const paddedSize = this.module._calculate_padded_size(width, height);
         // Allocate or re-allocate raw frame buffers if size changed
         if (frameSize !== this.allocatedFrameSize) {
-            if (this.prevFramePtr)
-                this.module._free(this.prevFramePtr);
-            if (this.curFramePtr)
-                this.module._free(this.curFramePtr);
-            this.prevFramePtr = this.module._malloc(frameSize);
-            this.curFramePtr = this.module._malloc(frameSize);
+            if (this.slotARawPtr)
+                this.module._free(this.slotARawPtr);
+            if (this.slotBRawPtr)
+                this.module._free(this.slotBRawPtr);
+            this.slotARawPtr = this.module._malloc(frameSize);
+            this.slotBRawPtr = this.module._malloc(frameSize);
             this.allocatedFrameSize = frameSize;
         }
         // Allocate or re-allocate padded frame buffers if size changed
         if (paddedSize !== this.allocatedPaddedSize) {
-            if (this.prevPaddedPtr)
-                this.module._free(this.prevPaddedPtr);
-            if (this.curPaddedPtr)
-                this.module._free(this.curPaddedPtr);
-            this.prevPaddedPtr = this.module._malloc(paddedSize);
-            this.curPaddedPtr = this.module._malloc(paddedSize);
+            if (this.slotAPaddedPtr)
+                this.module._free(this.slotAPaddedPtr);
+            if (this.slotBPaddedPtr)
+                this.module._free(this.slotBPaddedPtr);
+            this.slotAPaddedPtr = this.module._malloc(paddedSize);
+            this.slotBPaddedPtr = this.module._malloc(paddedSize);
             this.allocatedPaddedSize = paddedSize;
         }
+        // Reset double-buffer state
+        this.prevIsSlotA = true;
+        this.prevSlotPadded = false;
+        // Pre-allocate macroblock array in WASM
+        const mbResult = this.module._allocate_mb_array(width, height);
+        if (mbResult === 0) {
+            throw new Error('Failed to pre-allocate macroblock array in WASM');
+        }
     }
     /**
-     * Detect scene change between two frames
+     * Detect scene change between two frames using double-buffering.
      *
-     * Uses pre-allocated WASM buffers to eliminate per-frame allocation
-     * and reduce memory copies from 3 to 1 per frame.
+     * On first call, both frames are copied and padded.
+     * On subsequent calls, only the new current frame is copied and padded;
+     * the previous frame is already in WASM memory from the last call.
      *
      * @param prevFrame Previous frame
      * @param curFrame Current frame
      * @param intraCount Number of consecutive non-scene-change frames
-     * @param fcode Motion search range parameter (default: 4 = 256 pixels)
-     * @returns true if scene change detected, false otherwise
+     * @param fcode Motion search range parameter
+     * @param intraThresh Primary intra threshold
+     * @param intraThresh2 Secondary intra threshold (sSAD comparison)
+     * @returns Scene change result with confidence score
      */
-    detectSceneChange(prevFrame, curFrame, intraCount, fcode = 4) {
+    detectSceneChange(prevFrame, curFrame, intraCount, fcode = 4, intraThresh = 2000, intraThresh2 = 90) {
         this.ensureInitialized();
         // Validate inputs
         if (prevFrame.width !== curFrame.width || prevFrame.height !== curFrame.height) {
             throw new Error('Frame dimensions must match');
         }
-        // Ensure buffers are allocated (should be done once at start)
-        if (!this.prevFramePtr || this.allocatedFrameSize !== prevFrame.data.length) {
+        // Ensure buffers are allocated
+        if (!this.slotARawPtr || this.allocatedFrameSize !== prevFrame.data.length) {
             this.allocateBuffers(prevFrame.width, prevFrame.height);
         }
-        // Single copy: Raw frames -> WASM memory (eliminates 2 extra copies)
-        this.module.HEAPU8.set(prevFrame.data, this.prevFramePtr);
-        this.module.HEAPU8.set(curFrame.data, this.curFramePtr);
-        // Pad frames in-place in WASM (no copy back to JS)
-        this.module._pad_frame(this.prevFramePtr, this.prevPaddedPtr, prevFrame.width, prevFrame.height);
-        this.module._pad_frame(this.curFramePtr, this.curPaddedPtr, curFrame.width, curFrame.height);
-        // Run motion estimation on pre-padded buffers
-        const result = this.module._MEanalysis_js(this.prevPaddedPtr, this.curPaddedPtr, prevFrame.width, prevFrame.height, intraCount, fcode);
-        return result === 1;
+        // Determine which slot is "prev" and which is "cur"
+        const prevRawPtr = this.prevIsSlotA ? this.slotARawPtr : this.slotBRawPtr;
+        const prevPaddedPtr = this.prevIsSlotA ? this.slotAPaddedPtr : this.slotBPaddedPtr;
+        const curRawPtr = this.prevIsSlotA ? this.slotBRawPtr : this.slotARawPtr;
+        const curPaddedPtr = this.prevIsSlotA ? this.slotBPaddedPtr : this.slotAPaddedPtr;
+        // Copy and pad previous frame only if not already valid in WASM
+        if (!this.prevSlotPadded) {
+            this.module.HEAPU8.set(prevFrame.data, prevRawPtr);
+            this.module._pad_frame(prevRawPtr, prevPaddedPtr, prevFrame.width, prevFrame.height);
+        }
+        // Always copy and pad the new current frame
+        this.module.HEAPU8.set(curFrame.data, curRawPtr);
+        this.module._pad_frame(curRawPtr, curPaddedPtr, curFrame.width, curFrame.height);
+        // Run motion estimation with parameterized thresholds
+        const rawScore = this.module._MEanalysis_js(prevPaddedPtr, curPaddedPtr, prevFrame.width, prevFrame.height, intraCount, fcode, intraThresh, intraThresh2);
+        // Check for WASM error
+        if (rawScore === -1) {
+            throw new Error('WASM memory allocation failed during scene detection. ' +
+                `Frame size: ${prevFrame.width}x${prevFrame.height}. ` +
+                'The video resolution may be too high for available WASM memory.');
+        }
+        // Swap roles: current slot becomes previous for next call
+        this.prevIsSlotA = !this.prevIsSlotA;
+        this.prevSlotPadded = true;
+        // Determine scene change and confidence
+        const isSceneChange = rawScore >= intraThresh2;
+        // Normalize confidence: 0 when at threshold, 1 at 2x threshold
+        // For non-scene-changes, confidence represents "how close" (0 = very far from threshold)
+        let confidence;
+        if (isSceneChange) {
+            confidence = Math.min(1.0, rawScore / (intraThresh2 * 2));
+        }
+        else {
+            confidence = intraThresh2 > 0 ? Math.min(1.0, rawScore / intraThresh2) : 0;
+        }
+        return { isSceneChange, confidence };
+    }
+    /**
+     * Reset double-buffer state (e.g., after a seek or when starting fresh)
+     */
+    resetBufferState() {
+        this.prevIsSlotA = true;
+        this.prevSlotPadded = false;
     }
     /**
      * Calculate required buffer size for a padded frame
-     *
-     * @param width Original frame width
-     * @param height Original frame height
-     * @returns Required buffer size in bytes
      */
     calculatePaddedSize(width, height) {
         this.ensureInitialized();
@@ -628,10 +793,6 @@ class WasmBridge {
     }
     /**
      * Get macroblock parameters for a given frame size
-     *
-     * @param width Frame width
-     * @param height Frame height
-     * @returns Macroblock parameters
      */
     getMBParam(width, height) {
         const mb_width = Math.ceil(width / 16);
@@ -657,28 +818,119 @@ class WasmBridge {
      * Clean up resources
      */
     destroy() {
-        // Free pre-allocated WASM buffers
         if (this.module) {
-            if (this.prevFramePtr)
-                this.module._free(this.prevFramePtr);
-            if (this.curFramePtr)
-                this.module._free(this.curFramePtr);
-            if (this.prevPaddedPtr)
-                this.module._free(this.prevPaddedPtr);
-            if (this.curPaddedPtr)
-                this.module._free(this.curPaddedPtr);
-        }
-        this.prevFramePtr = 0;
-        this.curFramePtr = 0;
-        this.prevPaddedPtr = 0;
-        this.curPaddedPtr = 0;
+            // Free pre-allocated macroblock array
+            this.module._free_mb_array();
+            // Free double-buffered WASM frame buffers
+            if (this.slotARawPtr)
+                this.module._free(this.slotARawPtr);
+            if (this.slotBRawPtr)
+                this.module._free(this.slotBRawPtr);
+            if (this.slotAPaddedPtr)
+                this.module._free(this.slotAPaddedPtr);
+            if (this.slotBPaddedPtr)
+                this.module._free(this.slotBPaddedPtr);
+        }
+        this.slotARawPtr = 0;
+        this.slotBRawPtr = 0;
+        this.slotAPaddedPtr = 0;
+        this.slotBPaddedPtr = 0;
         this.allocatedFrameSize = 0;
         this.allocatedPaddedSize = 0;
+        this.prevSlotPadded = false;
         this.module = null;
         this.initialized = false;
     }
 }
 
+/**
+ * Temporal Smoother - Sliding window filter to reduce false positives
+ *
+ * Three rules:
+ * 1. Minimum gap: Suppress detections within minConsecutive frames of each other (keep highest confidence)
+ * 2. Flash suppression: Isolated single-frame detections with low confidence are suppressed
+ * 3. Cluster merging: Consecutive triggered frames (common in dissolves) keep only highest-confidence one
+ */
+class TemporalSmoother {
+    constructor(config) {
+        // Sliding window of recent detections
+        this.recentDetections = [];
+        // Last confirmed scene change frame
+        this.lastConfirmedFrame = 0;
+        // Buffer for cluster detection
+        this.pendingCluster = [];
+        this.nonDetectionCount = 0;
+        // Flash suppression: minimum confidence for isolated detections
+        this.flashConfidenceThreshold = 0.4;
+        this.windowSize = config.windowSize;
+        this.minConsecutive = config.minConsecutive;
+    }
+    /**
+     * Process a frame's detection result through temporal smoothing
+     */
+    process(frameNumber, rawIsSceneChange, rawConfidence) {
+        // If no detection, track gap and possibly flush pending cluster
+        if (!rawIsSceneChange) {
+            this.nonDetectionCount++;
+            // If we had a pending cluster and enough non-detections have passed,
+            // emit the best detection from the cluster
+            if (this.pendingCluster.length > 0 && this.nonDetectionCount >= 2) {
+                const best = this.flushCluster();
+                if (best) {
+                    return best;
+                }
+            }
+            return { isSceneChange: false, confidence: 0 };
+        }
+        // We have a detection
+        this.nonDetectionCount = 0;
+        // Rule 1: Minimum gap enforcement
+        if (frameNumber - this.lastConfirmedFrame < this.minConsecutive) {
+            // Too close to last confirmed scene change
+            // If this has higher confidence, replace pending, but don't emit yet
+            if (this.pendingCluster.length > 0) {
+                const best = this.pendingCluster.reduce((a, b) => a.confidence > b.confidence ? a : b);
+                if (rawConfidence > best.confidence) {
+                    // Replace entire cluster with this better detection
+                    this.pendingCluster = [{ frameNumber, confidence: rawConfidence }];
+                }
+            }
+            return { isSceneChange: false, confidence: 0 };
+        }
+        // Rule 3: Cluster merging - add to pending cluster
+        this.pendingCluster.push({ frameNumber, confidence: rawConfidence });
+        // Don't emit immediately; wait to see if more consecutive detections follow
+        return { isSceneChange: false, confidence: 0 };
+    }
+    /**
+     * Flush the pending cluster, emitting the highest-confidence detection
+     */
+    flushCluster() {
+        if (this.pendingCluster.length === 0) {
+            return null;
+        }
+        // Find the detection with highest confidence
+        const best = this.pendingCluster.reduce((a, b) => a.confidence > b.confidence ? a : b);
+        // Rule 2: Flash suppression - isolated single-frame detections with low confidence
+        if (this.pendingCluster.length === 1 && best.confidence < this.flashConfidenceThreshold) {
+            this.pendingCluster = [];
+            return null;
+        }
+        // Confirm this detection
+        this.lastConfirmedFrame = best.frameNumber;
+        this.recentDetections.push(best);
+        // Keep sliding window bounded
+        while (this.recentDetections.length > this.windowSize) {
+            this.recentDetections.shift();
+        }
+        this.pendingCluster = [];
+        return {
+            isSceneChange: true,
+            confidence: best.confidence
+        };
+    }
+}
+
 /**
  * Frame Processor - Utilities for frame preprocessing
  */
@@ -798,16 +1050,17 @@ class SceneDetector {
     constructor(options = {}) {
         // Set default options
         this.options = {
-            sensitivity: options.sensitivity || 'medium',
+            sensitivity: options.sensitivity || 'low',
             customThresholds: options.customThresholds || { intraThresh: 2000, intraThresh2: 90 },
             searchRange: options.searchRange || 'medium',
-            workers: options.workers || 1, // Multi-threading not implemented yet
+            workers: options.workers || 1,
             progressive: options.progressive || { enabled: false, initialStep: 1, refinementSteps: [] },
             temporalSmoothing: options.temporalSmoothing || { enabled: false, windowSize: 5, minConsecutive: 2 },
             frameExtraction: options.frameExtraction || { pixelFormat: 'gray', maxBufferFrames: 2 },
             onProgress: options.onProgress || (() => { }),
             onScene: options.onScene || (() => { }),
-            format: options.format || 'json'
+            format: options.format || 'json',
+            signal: options.signal || undefined
         };
         this.wasmBridge = new WasmBridge();
         // Initialize detection state
@@ -834,65 +1087,180 @@ class SceneDetector {
         const metadata = await decoder.getMetadata();
         // Calculate fcode from search range
         this.state.fcode = calculateFcode(this.options.searchRange, metadata.resolution.width, metadata.resolution.height);
-        // Pre-allocate WASM buffers (eliminates per-frame allocation overhead)
+        // Calculate thresholds from sensitivity
+        let thresholds;
+        if (this.options.sensitivity === 'custom') {
+            thresholds = this.options.customThresholds;
+        }
+        else {
+            thresholds = calculateThresholds(this.options.sensitivity);
+        }
+        // Pre-allocate WASM buffers
         this.wasmBridge.allocateBuffers(metadata.resolution.width, metadata.resolution.height);
+        // Initialize temporal smoother if enabled
+        let temporalSmoother = null;
+        if (this.options.temporalSmoothing.enabled) {
+            temporalSmoother = new TemporalSmoother(this.options.temporalSmoothing);
+        }
         // Initialize scene list (frame 0 is always a scene change)
         const scenes = [
             {
                 frameNumber: 0,
                 timestamp: 0,
-                timecode: '00:00:00.000'
+                timecode: '00:00:00.000',
+                confidence: 1.0
             }
         ];
         // Processing statistics
         const startTime = Date.now();
         let processedFrames = 0;
+        let firstFrameValidated = false;
+        // Rolling FPS window for accurate speed metrics (3-second window)
+        const fpsWindow = [];
+        // Fade/dissolve detection state
+        let keyframeData = null;
+        const driftThresholdFactor = 0.6; // Re-run detection at 60% of base thresholds
+        // Quick-reject sampling interval
+        const quickRejectStep = 64;
+        const quickRejectThreshold = 5;
+        // AbortSignal check
+        const signal = this.options.signal;
         // Process frames
         await decoder.extractFrames(async (frame) => {
-            validateFrame(frame);
+            // Check abort signal
+            if (signal && signal.aborted) {
+                throw new Error('Detection aborted');
+            }
+            // Validate only the first frame (dimensions never change within a video)
+            if (!firstFrameValidated) {
+                validateFrame(frame);
+                firstFrameValidated = true;
+            }
             // Update current frame
             this.state.curFrame = frame;
             // Need at least 2 frames to detect scene change
             if (this.state.prevFrame) {
-                const isSceneChange = this.wasmBridge.detectSceneChange(this.state.prevFrame, this.state.curFrame, this.state.intraCount, this.state.fcode);
+                let isSceneChange = false;
+                let confidence = 0;
+                // Quick-reject: sampled MAD between prev and cur frame
+                const prevData = this.state.prevFrame.data;
+                const curData = this.state.curFrame.data;
+                let sampledDiff = 0;
+                let sampleCount = 0;
+                for (let i = 0; i < curData.length; i += quickRejectStep) {
+                    sampledDiff += Math.abs(curData[i] - prevData[i]);
+                    sampleCount++;
+                }
+                const avgDiff = sampledDiff / sampleCount;
+                if (avgDiff >= quickRejectThreshold) {
+                    // Frame differs enough, run full WASM detection
+                    const result = this.wasmBridge.detectSceneChange(this.state.prevFrame, this.state.curFrame, this.state.intraCount, this.state.fcode, thresholds.intraThresh, thresholds.intraThresh2);
+                    isSceneChange = result.isSceneChange;
+                    confidence = result.confidence;
+                    // Fade/dissolve detection: if not detected as scene change,
+                    // check drift from last keyframe
+                    if (!isSceneChange && keyframeData) {
+                        let driftSum = 0;
+                        let driftCount = 0;
+                        // Sample every 4th pixel for speed
+                        for (let i = 0; i < curData.length; i += 4) {
+                            driftSum += Math.abs(curData[i] - keyframeData[i]);
+                            driftCount++;
+                        }
+                        const driftAvg = driftSum / driftCount;
+                        // If cumulative drift is high but per-frame SAD didn't trigger,
+                        // re-run with lowered thresholds
+                        if (driftAvg > 30) {
+                            const fadeResult = this.wasmBridge.detectSceneChange(this.state.prevFrame, this.state.curFrame, this.state.intraCount, this.state.fcode, Math.round(thresholds.intraThresh * driftThresholdFactor), Math.round(thresholds.intraThresh2 * driftThresholdFactor));
+                            if (fadeResult.isSceneChange) {
+                                isSceneChange = true;
+                                confidence = fadeResult.confidence;
+                            }
+                        }
+                    }
+                }
+                // else: quick-reject - frames are nearly identical, skip WASM call
+                // Apply temporal smoothing if enabled
+                if (temporalSmoother) {
+                    const smoothed = temporalSmoother.process(frame.frameNumber, isSceneChange, confidence);
+                    isSceneChange = smoothed.isSceneChange;
+                    confidence = smoothed.confidence;
+                }
                 if (isSceneChange) {
                     const scene = {
                         frameNumber: frame.frameNumber,
                         timestamp: frame.pts,
-                        timecode: formatTimecode(frame.pts)
+                        timecode: formatTimecode(frame.pts),
+                        confidence
                     };
                     scenes.push(scene);
                     // Call scene callback
                     this.options.onScene(scene);
                     // Reset intraCount
                     this.state.intraCount = 1;
+                    // Update keyframe for drift detection
+                    keyframeData = new Uint8Array(curData);
                 }
                 else {
-                    // Increment intraCount
                     this.state.intraCount++;
                 }
             }
+            else {
+                // First frame is the initial keyframe for drift detection
+                keyframeData = new Uint8Array(frame.data);
+            }
             // Move current frame to previous
             this.state.prevFrame = this.state.curFrame;
             processedFrames++;
         }, (current, total) => {
-            // Progress callback
+            // Enhanced progress with rolling FPS window
+            const now = Date.now();
+            const elapsed = (now - startTime) / 1000;
+            // Add to rolling window
+            fpsWindow.push({ time: now, frame: current });
+            // Remove samples older than 3 seconds
+            while (fpsWindow.length > 1 && (now - fpsWindow[0].time) > 3000) {
+                fpsWindow.shift();
+            }
+            // Calculate instantaneous FPS from rolling window
+            let currentFps = 0;
+            if (fpsWindow.length >= 2) {
+                const oldest = fpsWindow[0];
+                const newest = fpsWindow[fpsWindow.length - 1];
+                const dt = (newest.time - oldest.time) / 1000;
+                if (dt > 0) {
+                    currentFps = (newest.frame - oldest.frame) / dt;
+                }
+            }
+            // Calculate ETA from instantaneous FPS
+            const remaining = currentFps > 0 ? (total - current) / currentFps : undefined;
             const progress = {
                 currentFrame: current,
                 totalFrames: total,
-                percent: Math.round((current / total) * 100)
+                percent: Math.round((current / total) * 100),
+                eta: remaining,
+                fps: currentFps,
+                elapsed,
+                scenesDetected: scenes.length
             };
-            // Calculate ETA
-            const elapsed = (Date.now() - startTime) / 1000;
-            const fps = current / elapsed;
-            const remaining = (total - current) / fps;
-            progress.eta = remaining;
             this.options.onProgress(progress);
         });
         // Calculate statistics
         const endTime = Date.now();
         const processingTime = (endTime - startTime) / 1000;
         const framesPerSecond = processedFrames / processingTime;
+        // Post-process: compute scene durations
+        for (let i = 0; i < scenes.length; i++) {
+            if (i < scenes.length - 1) {
+                scenes[i].duration = scenes[i + 1].timestamp - scenes[i].timestamp;
+                scenes[i].frameCount = scenes[i + 1].frameNumber - scenes[i].frameNumber;
+            }
+            else {
+                // Last scene: duration until end of video
+                scenes[i].duration = metadata.duration - scenes[i].timestamp;
+                scenes[i].frameCount = metadata.totalFrames - scenes[i].frameNumber;
+            }
+        }
         // Clean up
         decoder.destroy();
         return {
@@ -935,7 +1303,7 @@ class SceneDetector {
  * console.log(`Found ${results.scenes.length} scenes`);
  *
  * results.scenes.forEach(scene => {
- *   console.log(`Scene at ${scene.timecode}`);
+ *   console.log(`Scene at ${scene.timecode} (confidence: ${scene.confidence})`);
  * });
  * ```
  */
@@ -949,6 +1317,30 @@ async function detectSceneChanges(videoPath, options) {
         detector.destroy();
     }
 }
+/**
+ * Extract scene thumbnail images from a video
+ *
+ * @param videoPath Path to video file
+ * @param options Detection options
+ * @param imageOptions Image extraction options
+ * @returns Detection results (images are written to disk)
+ */
+async function extractSceneImages(videoPath, options, imageOptions) {
+    const detector = new SceneDetector(options);
+    try {
+        const results = await detector.detect(videoPath);
+        if (imageOptions) {
+            const decoder = new FFmpegDecoder(videoPath);
+            const frameNumbers = results.scenes.map(s => s.frameNumber);
+            await decoder.extractFrameImages(frameNumbers, imageOptions);
+            decoder.destroy();
+        }
+        return results;
+    }
+    finally {
+        detector.destroy();
+    }
+}
 /**
  * Version information
  */
@@ -973,6 +1365,7 @@ exports.BufferPool = BufferPool;
 exports.FFmpegDecoder = FFmpegDecoder;
 exports.FrameBuffer = FrameBuffer;
 exports.SceneDetector = SceneDetector;
+exports.TemporalSmoother = TemporalSmoother;
 exports.WasmBridge = WasmBridge;
 exports.calculateFcode = calculateFcode;
 exports.calculateFrameMemory = calculateFrameMemory;
@@ -980,6 +1373,7 @@ exports.calculateMBParam = calculateMBParam;
 exports.calculateThresholds = calculateThresholds;
 exports.detectSceneChanges = detectSceneChanges;
 exports.estimateProcessingTime = estimateProcessingTime;
+exports.extractSceneImages = extractSceneImages;
 exports.formatTimecode = formatTimecode;
 exports.info = info;
 exports.validateFrame = validateFrame;