dspx 1.1.4 → 1.1.6

package/README.md

@@ -346,6 +346,37 @@ const output = await pipeline.process(input, {
 
 **Recommendation:** Use batched callbacks in production. Individual callbacks benchmark faster but block the Node.js event loop and can't integrate with real telemetry systems (Kafka, Datadog, Loki).
 
+### 🎯 FFT Performance Note
+
+**Pipeline vs Direct Processing:**
+
+The DSP pipeline adds ~0.3-0.4ms overhead per operation for:
+
+- Channel management and stage chaining
+- N-API boundary crossings
+- Output buffer allocation
+
+For **maximum FFT performance** (when you don't need multi-stage processing or Redis persistence), use the direct `FftProcessor`:
+
+```javascript
+// ⚡ FASTER: Direct FFT (no pipeline overhead)
+import { FftProcessor } from "dspx";
+const processor = new FftProcessor(1024);
+const output = processor.rfft(signal); // ~4-14x faster than fft.js
+
+// 🔧 FLEXIBLE: Pipeline FFT (with overhead)
+const pipeline = createDspPipeline();
+pipeline.fft({ size: 1024, type: "rfft" });
+const result = pipeline.process(signal); // Still faster than pure JS, but ~0.3ms overhead
+```
+
+**When to use each:**
+
+- **FftProcessor**: Single FFT operations, maximum speed, batch processing
+- **Pipeline**: Multi-stage processing (filter→FFT→analysis), Redis state, complex workflows
+
+With recent optimizations (loop unrolling, memcpy, single-channel fast paths), dspx FFT is now **4-14x faster than fft.js** across all sizes when measured correctly. See [FFT_BENCHMARK_FIX.md](docs/FFT_BENCHMARK_FIX.md) for benchmark methodology.
+
 ### ⚠️ ARM/Mobile Platform Notice
 
 **ARM NEON optimizations are experimental.** Mobile/ARM devices face unique challenges:

package/dist/bindings.d.ts

@@ -281,15 +281,37 @@ declare class DspProcessor {
     Resample(params: ResampleParams): this;
     /**
      * Add a convolution stage to the pipeline
-     * Applies a custom 1D kernel to the signal using either direct or FFT-based convolution
+     * Applies a 1D kernel to the signal using either direct or FFT-based convolution
+     *
+     * **Two Processing Modes:**
+     * 1. **Batch mode** (stateless): Standard convolution, output length = N - M + 1
+     * 2. **Moving mode** (stateful): Streaming convolution, maintains buffer, output length = N
      *
      * @param params - Convolution parameters
+     * @param params.kernel - 1D filter kernel (time-domain)
+     * @param params.mode - 'batch' (stateless, valid convolution) or 'moving' (stateful, streaming) [default: 'moving']
+     * @param params.method - 'auto' (smart selection), 'direct' (time-domain), or 'fft' (frequency-domain) [default: 'auto']
      * @returns this instance for method chaining
      *
      * @example
+     * // BATCH MODE: Standard convolution (output length = N - M + 1)
+     * const input = new Float32Array([1, 2, 3, 4, 5]);
+     * const kernel = new Float32Array([1, 0, -1]);
+     * pipeline.convolution({ kernel, mode: "batch" });
+     * const output = await pipeline.process(input, { channels: 1 });
+     * // output: [-2, -2, -2] (length = 5 - 3 + 1 = 3)
+     *
+     * @example
+     * // MOVING MODE: Streaming convolution (output length = N)
+     * pipeline.convolution({ kernel: mySmoothingKernel, mode: "moving" });
+     * const chunk1 = await pipeline.process(data1, { channels: 1 });
+     * const chunk2 = await pipeline.process(data2, { channels: 1 });
+     * // State maintained between chunks, same length as input
+     *
+     * @example
      * // Simple smoothing kernel
      * const smoothKernel = new Float32Array([0.2, 0.6, 0.2]);
-     * pipeline.convolution({ kernel: smoothKernel });
+     * pipeline.convolution({ kernel: smoothKernel, mode: "batch" });
      *
      * @example
      * // Gaussian kernel with explicit method
@@ -311,11 +333,11 @@ declare class DspProcessor {
      * @example
      * // Multi-channel EMG grid with custom kernel
      * const emgGrid = new Float32Array(80000); // 10x8 grid, 1000 samples
-     * pipeline.convolution({ kernel: mySmoothingKernel });
+     * pipeline.convolution({ kernel: mySmoothingKernel, mode: "batch" });
      * const output = await pipeline.process(emgGrid, {
      *   sampleRate: 2000,
      *   channels: 80 // 10 * 8 sensors
-     * });\
+     * });
      */
     convolution(params: ConvolutionParams): this;
     /**
@@ -1038,46 +1060,53 @@ declare class DspProcessor {
      * Transforms time-domain signal to frequency domain or vice versa.
      * Supports both fast (radix-2) and direct (any size) transforms.
      *
+     * **Two Processing Modes:**
+     * 1. **Batch mode** (default): Stateless FFT over entire input buffer
+     * 2. **Moving mode**: Stateful sliding-window FFT (STFT) with overlap
+     *
      * **Transform Types:**
-     * - `fft`: Complex FFT (O(N log N), requires power-of-2 size)
+     * - `rfft`: Real FFT (O(N log N), requires power-of-2 size) [MOST COMMON]
+     * - `fft`: Complex FFT (O(N log N), requires power-of-2)
+     * - `rdft`: Real DFT (O(N²), works with any size)
      * - `dft`: Complex DFT (O(N²), works with any size)
-     * - `rfft`: Real FFT for real signals (O(N log N), outputs N/2+1 bins)
-     * - `rdft`: Real DFT for real signals (O(N²), outputs N/2+1 bins)
      *
      * **Output Formats:**
-     * - `complex`: Returns interleaved [real0, imag0, real1, imag1, ...]
-     * - `magnitude`: Returns |X[k]| = sqrt(real² + imag²)
-     * - `power`: Returns |X[k]|² = real² + imag²
-     * - `phase`: Returns ∠X[k] = atan2(imag, real)
+     * - `magnitude`: |X[k]| = sqrt(real² + imag²) [DEFAULT]
+     * - `power`: |X[k]|² = real² + imag²
+     * - `phase`: ∠X[k] = atan2(imag, real)
+     * - `complex`: Interleaved [real0, imag0, real1, imag1, ...]
+     *
+     * **Moving Mode Details:**
+     * - Internally delegates to `stft()` with Hann windowing
+     * - Uses CircularBufferArray for efficient buffering
+     * - Default hopSize = size/2 (50% overlap)
+     * - Better for time-varying signals (audio, EEG)
      *
      * @param params - FFT configuration
+     * @param params.mode - 'batch' (stateless) or 'moving' (sliding window) [default: 'batch']
      * @param params.size - FFT size (power of 2 for FFT/RFFT, any size for DFT/RDFT)
-     * @param params.type - Transform type (default: 'rfft' for real signals)
-     * @param params.forward - Forward (time→freq) or inverse (freq→time) (default: true)
-     * @param params.output - Output format (default: 'magnitude')
+     * @param params.hopSize - Window stride for 'moving' mode [default: size/2]
+     * @param params.type - Transform type [default: 'rfft']
+     * @param params.forward - Forward (time→freq) or inverse (freq→time) [default: true]
+     * @param params.output - Output format [default: 'magnitude']
      * @returns this instance for method chaining
      *
      * @example
-     * // Spectral analysis with magnitude output
+     * // Batch mode: Single FFT of entire buffer
      * pipeline.fft({
+     *   mode: 'batch',
      *   size: 1024,
      *   type: 'rfft',
      *   output: 'magnitude'
      * });
      *
      * @example
-     * // Power spectrum for energy analysis
-     * pipeline.fft({
-     *   size: 2048,
-     *   output: 'power'
-     * });
-     *
-     * @example
-     * // Complex FFT for phase information
+     * // Moving mode: STFT with 50% overlap
      * pipeline.fft({
+     *   mode: 'moving',
      *   size: 512,
-     *   type: 'fft',
-     *   output: 'complex'
+     *   hopSize: 256,  // 50% overlap
+     *   output: 'power'
      * });
      *
      * @example
@@ -1087,6 +1116,14 @@ declare class DspProcessor {
      *   type: 'rdft',
      *   output: 'magnitude'
      * });
+     *
+     * @example
+     * // Complex FFT for phase analysis
+     * pipeline.fft({
+     *   size: 512,
+     *   type: 'fft',
+     *   output: 'complex'
+     * });
      */
     fft(params: fftParams): this;
     /**

package/dist/bindings.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bindings.d.ts","sourceRoot":"","sources":["../src/ts/bindings.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"bindings.d.ts","sourceRoot":"","sources":["../src/ts/bindings.ts"],"names":[],"mappings":"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"}

package/dist/bindings.js

@@ -534,15 +534,37 @@ class DspProcessor {
     }
     /**
      * Add a convolution stage to the pipeline
-     * Applies a custom 1D kernel to the signal using either direct or FFT-based convolution
+     * Applies a 1D kernel to the signal using either direct or FFT-based convolution
+     *
+     * **Two Processing Modes:**
+     * 1. **Batch mode** (stateless): Standard convolution, output length = N - M + 1
+     * 2. **Moving mode** (stateful): Streaming convolution, maintains buffer, output length = N
      *
      * @param params - Convolution parameters
+     * @param params.kernel - 1D filter kernel (time-domain)
+     * @param params.mode - 'batch' (stateless, valid convolution) or 'moving' (stateful, streaming) [default: 'moving']
+     * @param params.method - 'auto' (smart selection), 'direct' (time-domain), or 'fft' (frequency-domain) [default: 'auto']
      * @returns this instance for method chaining
      *
      * @example
+     * // BATCH MODE: Standard convolution (output length = N - M + 1)
+     * const input = new Float32Array([1, 2, 3, 4, 5]);
+     * const kernel = new Float32Array([1, 0, -1]);
+     * pipeline.convolution({ kernel, mode: "batch" });
+     * const output = await pipeline.process(input, { channels: 1 });
+     * // output: [-2, -2, -2] (length = 5 - 3 + 1 = 3)
+     *
+     * @example
+     * // MOVING MODE: Streaming convolution (output length = N)
+     * pipeline.convolution({ kernel: mySmoothingKernel, mode: "moving" });
+     * const chunk1 = await pipeline.process(data1, { channels: 1 });
+     * const chunk2 = await pipeline.process(data2, { channels: 1 });
+     * // State maintained between chunks, same length as input
+     *
+     * @example
      * // Simple smoothing kernel
      * const smoothKernel = new Float32Array([0.2, 0.6, 0.2]);
-     * pipeline.convolution({ kernel: smoothKernel });
+     * pipeline.convolution({ kernel: smoothKernel, mode: "batch" });
      *
      * @example
      * // Gaussian kernel with explicit method
@@ -564,11 +586,11 @@ class DspProcessor {
      * @example
      * // Multi-channel EMG grid with custom kernel
      * const emgGrid = new Float32Array(80000); // 10x8 grid, 1000 samples
-     * pipeline.convolution({ kernel: mySmoothingKernel });
+     * pipeline.convolution({ kernel: mySmoothingKernel, mode: "batch" });
      * const output = await pipeline.process(emgGrid, {
      *   sampleRate: 2000,
      *   channels: 80 // 10 * 8 sensors
-     * });\
+     * });
      */
     convolution(params) {
         if (!params.kernel || params.kernel.length === 0) {
@@ -1643,46 +1665,53 @@ class DspProcessor {
      * Transforms time-domain signal to frequency domain or vice versa.
      * Supports both fast (radix-2) and direct (any size) transforms.
      *
+     * **Two Processing Modes:**
+     * 1. **Batch mode** (default): Stateless FFT over entire input buffer
+     * 2. **Moving mode**: Stateful sliding-window FFT (STFT) with overlap
+     *
      * **Transform Types:**
-     * - `fft`: Complex FFT (O(N log N), requires power-of-2 size)
+     * - `rfft`: Real FFT (O(N log N), requires power-of-2 size) [MOST COMMON]
+     * - `fft`: Complex FFT (O(N log N), requires power-of-2)
+     * - `rdft`: Real DFT (O(N²), works with any size)
      * - `dft`: Complex DFT (O(N²), works with any size)
-     * - `rfft`: Real FFT for real signals (O(N log N), outputs N/2+1 bins)
-     * - `rdft`: Real DFT for real signals (O(N²), outputs N/2+1 bins)
      *
      * **Output Formats:**
-     * - `complex`: Returns interleaved [real0, imag0, real1, imag1, ...]
-     * - `magnitude`: Returns |X[k]| = sqrt(real² + imag²)
-     * - `power`: Returns |X[k]|² = real² + imag²
-     * - `phase`: Returns ∠X[k] = atan2(imag, real)
+     * - `magnitude`: |X[k]| = sqrt(real² + imag²) [DEFAULT]
+     * - `power`: |X[k]|² = real² + imag²
+     * - `phase`: ∠X[k] = atan2(imag, real)
+     * - `complex`: Interleaved [real0, imag0, real1, imag1, ...]
+     *
+     * **Moving Mode Details:**
+     * - Internally delegates to `stft()` with Hann windowing
+     * - Uses CircularBufferArray for efficient buffering
+     * - Default hopSize = size/2 (50% overlap)
+     * - Better for time-varying signals (audio, EEG)
      *
      * @param params - FFT configuration
+     * @param params.mode - 'batch' (stateless) or 'moving' (sliding window) [default: 'batch']
      * @param params.size - FFT size (power of 2 for FFT/RFFT, any size for DFT/RDFT)
-     * @param params.type - Transform type (default: 'rfft' for real signals)
-     * @param params.forward - Forward (time→freq) or inverse (freq→time) (default: true)
-     * @param params.output - Output format (default: 'magnitude')
+     * @param params.hopSize - Window stride for 'moving' mode [default: size/2]
+     * @param params.type - Transform type [default: 'rfft']
+     * @param params.forward - Forward (time→freq) or inverse (freq→time) [default: true]
+     * @param params.output - Output format [default: 'magnitude']
      * @returns this instance for method chaining
      *
      * @example
-     * // Spectral analysis with magnitude output
+     * // Batch mode: Single FFT of entire buffer
      * pipeline.fft({
+     *   mode: 'batch',
      *   size: 1024,
      *   type: 'rfft',
      *   output: 'magnitude'
      * });
      *
      * @example
-     * // Power spectrum for energy analysis
-     * pipeline.fft({
-     *   size: 2048,
-     *   output: 'power'
-     * });
-     *
-     * @example
-     * // Complex FFT for phase information
+     * // Moving mode: STFT with 50% overlap
      * pipeline.fft({
+     *   mode: 'moving',
      *   size: 512,
-     *   type: 'fft',
-     *   output: 'complex'
+     *   hopSize: 256,  // 50% overlap
+     *   output: 'power'
      * });
      *
      * @example
@@ -1692,14 +1721,37 @@ class DspProcessor {
      *   type: 'rdft',
      *   output: 'magnitude'
      * });
+     *
+     * @example
+     * // Complex FFT for phase analysis
+     * pipeline.fft({
+     *   size: 512,
+     *   type: 'fft',
+     *   output: 'complex'
+     * });
      */
     fft(params) {
         if (!params.size || params.size <= 0 || !Number.isInteger(params.size)) {
             throw new TypeError(`Fft: size must be a positive integer, got ${params.size}`);
         }
+        const mode = params.mode || "batch";
         const type = params.type || "rfft";
         const forward = params.forward ?? true;
         const output = params.output || "magnitude";
+        const hopSize = params.hopSize ?? Math.floor(params.size / 2);
+        // Validate mode
+        if (mode !== "batch" && mode !== "moving") {
+            throw new TypeError(`Fft: mode must be 'batch' or 'moving', got '${mode}'`);
+        }
+        // Validate hopSize for moving mode
+        if (mode === "moving") {
+            if (hopSize <= 0 || !Number.isInteger(hopSize)) {
+                throw new TypeError(`Fft: hopSize must be a positive integer, got ${hopSize}`);
+            }
+            if (hopSize > params.size) {
+                throw new TypeError(`Fft: hopSize (${hopSize}) cannot exceed size (${params.size})`);
+            }
+        }
         // Validate type
         const validTypes = ["fft", "dft", "rfft", "rdft"];
         if (!validTypes.includes(type)) {
@@ -1715,14 +1767,32 @@ class DspProcessor {
             !this.isPowerOfTwo(params.size)) {
             throw new TypeError(`Fft: ${type} requires power-of-2 size. Got ${params.size}. Use 'dft' or 'rdft' for arbitrary sizes.`);
         }
+        // MOVING MODE: Delegate to STFT (which uses MovingFftFilter internally)
+        if (mode === "moving") {
+            // Map FFT parameters to STFT parameters
+            const stftMethod = type === "fft" || type === "rfft" ? "fft" : "dft";
+            const stftType = type.includes("r") ? "real" : "complex";
+            return this.stft({
+                windowSize: params.size,
+                hopSize: hopSize,
+                method: stftMethod,
+                type: stftType,
+                forward: forward,
+                output: output,
+                window: "hann", // Default window for moving mode (better spectral leakage control)
+            });
+        }
+        // BATCH MODE: Use stateless FftStage
         this.nativeInstance.addStage("fft", {
+            mode,
             size: params.size,
+            hopSize,
             type,
             forward,
             output,
         });
         const direction = forward ? "forward" : "inverse";
-        this.stages.push(`fft:${type}:${params.size}:${direction}:${output}`);
+        this.stages.push(`fft:${type}:${params.size}:batch:${direction}:${output}`);
         return this;
     }
     /**