dspx 1.2.3 → 1.3.0

package/dist/bindings.js

@@ -4,6 +4,7 @@ import { dirname, join } from "node:path";
 import { CircularLogBuffer } from "./CircularLogBuffer.js";
 import { DriftDetector } from "./DriftDetector.js";
 import { FirFilter, IirFilter, } from "./filters.js";
+import { DspUtils } from "./utils.js";
 // Get the directory of the current file
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -166,6 +167,97 @@ class DspProcessor {
         this.stages.push(`movingAverage:${params.mode}`);
         return this;
     }
+    /**
+     * Add an Exponential Moving Average (EMA) stage to the pipeline
+     *
+     * EMA gives exponentially decaying weight to older samples, providing adaptive smoothing.
+     * Formula: EMA(t) = α * value(t) + (1 - α) * EMA(t-1)
+     *
+     * @param params - Configuration for the EMA filter
+     * @param params.mode - "batch" for stateless EMA (resets per chunk), "moving" for stateful with continuity
+     * @param params.alpha - Smoothing factor (0 < α ≤ 1)
+     *   - α close to 1: Fast response to changes (less smoothing)
+     *   - α close to 0: Slow response to changes (more smoothing)
+     *   - From N-period SMA: α = 2 / (N + 1)
+     * @returns this instance for method chaining
+     *
+     * @example
+     * // Batch mode: Reset EMA for each process() call
+     * pipeline.ExponentialMovingAverage({ mode: "batch", alpha: 0.3 });
+     *
+     * @example
+     * // Moving mode: EMA continues across process() calls
+     * pipeline.ExponentialMovingAverage({ mode: "moving", alpha: 0.1 });
+     *
+     * @example
+     * // Fast adaptive filter (equivalent to ~10-sample SMA)
+     * pipeline.ExponentialMovingAverage({ mode: "moving", alpha: 2 / (10 + 1) });
+     *
+     * @example
+     * // Chain with other stages for advanced processing
+     * pipeline
+     *   .ExponentialMovingAverage({ mode: "moving", alpha: 0.2 })
+     *   .Rectify({ mode: "full" })
+     *   .Rms({ mode: "moving", windowSize: 50 });
+     */
+    ExponentialMovingAverage(params) {
+        // Validate alpha parameter
+        if (params.alpha === undefined) {
+            throw new TypeError(`ExponentialMovingAverage: alpha is required`);
+        }
+        if (params.alpha <= 0 || params.alpha > 1) {
+            throw new TypeError(`ExponentialMovingAverage: alpha must be in range (0, 1], got ${params.alpha}`);
+        }
+        this.nativeInstance.addStage("exponentialMovingAverage", params);
+        this.stages.push(`exponentialMovingAverage:${params.mode}:α=${params.alpha}`);
+        return this;
+    }
+    /**
+     * Add a Cumulative Moving Average (CMA) stage to the pipeline
+     *
+     * CMA is the average of ALL samples seen since initialization (not just a window).
+     * Formula: CMA(n) = (sum of all values) / n
+     *
+     * Unlike simple moving average (SMA), CMA considers entire history:
+     * - SMA: Uses fixed window of recent N samples
+     * - CMA: Uses all samples from start to current
+     *
+     * Memory-efficient: only stores running sum and count.
+     *
+     * @param params - Configuration for the CMA filter
+     * @param params.mode - "batch" for stateless CMA (resets per chunk), "moving" for stateful with continuity
+     * @returns this instance for method chaining
+     *
+     * @example
+     * // Batch mode: CMA resets for each process() call
+     * pipeline.CumulativeMovingAverage({ mode: "batch" });
+     *
+     * @example
+     * // Moving mode: CMA accumulates across all process() calls
+     * pipeline.CumulativeMovingAverage({ mode: "moving" });
+     *
+     * @example
+     * // Use case: Long-term baseline estimation from calibration data
+     * const calibrationPipeline = createDspPipeline();
+     * calibrationPipeline.CumulativeMovingAverage({ mode: "moving" });
+     *
+     * // Process calibration chunks
+     * await calibrationPipeline.process(chunk1, { channels: 1 });
+     * await calibrationPipeline.process(chunk2, { channels: 1 });
+     * await calibrationPipeline.process(chunk3, { channels: 1 });
+     * // Final output contains cumulative average across all chunks
+     *
+     * @example
+     * // Chain with variance for online statistics
+     * pipeline
+     *   .CumulativeMovingAverage({ mode: "moving" })
+     *   .tap((samples) => console.log('Running mean:', samples[samples.length - 1]));
+     */
+    CumulativeMovingAverage(params) {
+        this.nativeInstance.addStage("cumulativeMovingAverage", params);
+        this.stages.push(`cumulativeMovingAverage:${params.mode}`);
+        return this;
+    }
     /**
      * Add a RMS (root mean square) stage to the pipeline
      * @param params - Configuration for the RMS filter
@@ -1244,6 +1336,70 @@ class DspProcessor {
         this.stages.push(`channelMerge:${params.numInputChannels}ch→${params.mapping.length}ch`);
         return this;
     }
+    /**
+     * Apply a bank of IIR filters to split each input channel into multiple frequency bands.
+     *
+     * Implements frequency decomposition for:
+     * - Speech recognition: Mel-scale filter banks (20-40 bands)
+     * - Audio compression: Bark-scale psychoacoustic analysis
+     * - Musical analysis: Octave bands (log scale)
+     * - Research: Linear-scale frequency analysis
+     *
+     * Architecture:
+     * - Input: N channels (interleaved)
+     * - Output: N × M channels (interleaved, channel-major layout)
+     * - Layout: All bands for channel 1, then all bands for channel 2, etc.
+     *
+     * @param params - Filter bank parameters
+     * @param params.definitions - Array of filter definitions (one per band)
+     * @param params.inputChannels - Number of input channels
+     * @returns this instance for method chaining
+     *
+     * @throws {TypeError} If definitions or inputChannels are missing
+     * @throws {RangeError} If inputChannels <= 0 or definitions is empty
+     *
+     * @example
+     * // Design a 24-band Mel-scale filter bank for speech
+     * import { FilterBankDesign } from 'dspx';
+     *
+     * const melBank = FilterBankDesign.createMel(24, 16000, [100, 8000]);
+     * pipeline.FilterBank({
+     *   definitions: melBank,
+     *   inputChannels: 1
+     * });
+     * // Output: 24 channels (one per Mel band)
+     *
+     * @example
+     * // Custom 10-band octave filter bank for stereo input
+     * const octaveBank = FilterBankDesign.createLog(10, 44100, [20, 20000]);
+     * pipeline.FilterBank({
+     *   definitions: octaveBank,
+     *   inputChannels: 2
+     * });
+     * // Output: 20 channels (10 bands × 2 input channels)
+     */
+    FilterBank(params) {
+        if (!Array.isArray(params.definitions) || params.definitions.length === 0) {
+            throw new TypeError("FilterBank: definitions must be a non-empty array");
+        }
+        if (!Number.isInteger(params.inputChannels) || params.inputChannels <= 0) {
+            throw new RangeError("FilterBank: inputChannels must be a positive integer");
+        }
+        // Validate each filter definition
+        for (let i = 0; i < params.definitions.length; i++) {
+            const def = params.definitions[i];
+            if (!Array.isArray(def.b) || def.b.length === 0) {
+                throw new TypeError(`FilterBank: definition[${i}].b must be a non-empty array`);
+            }
+            if (!Array.isArray(def.a) || def.a.length === 0) {
+                throw new TypeError(`FilterBank: definition[${i}].a must be a non-empty array`);
+            }
+        }
+        this.nativeInstance.addStage("filterBank", params);
+        const outputChannels = params.inputChannels * params.definitions.length;
+        this.stages.push(`filterBank:${params.definitions.length}bands×${params.inputChannels}ch=${outputChannels}ch`);
+        return this;
+    }
     /**
      * Detect clipping (signal saturation) in the input stream.
      *
@@ -2230,6 +2386,16 @@ class DspProcessor {
      * });
      *
      * @example
+     * // Generic IIR filter (uses Butterworth internally)
+     * pipeline.filter({
+     *   type: "iir",
+     *   mode: "highpass",
+     *   cutoffFrequency: 500,
+     *   sampleRate: 8000,
+     *   order: 2
+     * });
+     *
+     * @example
      * // Butterworth band-pass filter
      * pipeline.filter({
      *   type: "butterworth",
@@ -2292,8 +2458,10 @@ class DspProcessor {
                     filterInstance = this.createBiquadFilter(options);
                     break;
                 case "iir":
+                    filterInstance = this.createIirFilter(options);
+                    break;
                 default:
-                    throw new Error(`Filter type "${options.type}" not yet implemented for pipeline chaining. Use standalone filter methods instead.`);
+                    throw new Error(`Filter type not supported. Valid types: 'fir', 'iir', 'butterworth', 'chebyshev', 'biquad'`);
             }
         }
         catch (error) {
@@ -2438,6 +2606,76 @@ class DspProcessor {
                 throw new Error(`Unsupported Chebyshev filter mode: ${mode}`);
         }
     }
+    /**
+     * Helper to create generic IIR filter from options
+     * Uses first-order filters for order=1, Butterworth otherwise
+     */
+    createIirFilter(options) {
+        const { mode, cutoffFrequency, lowCutoffFrequency, highCutoffFrequency, order, } = options;
+        // Validate order
+        if (!order || order < 1) {
+            throw new Error("IIR filter requires order >= 1");
+        }
+        // For first-order filters, use optimized implementations
+        if (order === 1) {
+            switch (mode) {
+                case "lowpass":
+                    if (!cutoffFrequency) {
+                        throw new Error("cutoffFrequency required for lowpass filter");
+                    }
+                    return IirFilter.createFirstOrderLowPass({
+                        cutoffFrequency,
+                        sampleRate: options.sampleRate,
+                    });
+                case "highpass":
+                    if (!cutoffFrequency) {
+                        throw new Error("cutoffFrequency required for highpass filter");
+                    }
+                    return IirFilter.createFirstOrderHighPass({
+                        cutoffFrequency,
+                        sampleRate: options.sampleRate,
+                    });
+                default:
+                    throw new Error(`First-order IIR filter only supports lowpass and highpass modes. For ${mode}, use order > 1 or a different filter type.`);
+            }
+        }
+        // For higher-order filters, delegate to Butterworth (maximally flat response)
+        switch (mode) {
+            case "lowpass":
+                if (!cutoffFrequency) {
+                    throw new Error("cutoffFrequency required for lowpass filter");
+                }
+                return IirFilter.createButterworthLowPass({
+                    cutoffFrequency,
+                    sampleRate: options.sampleRate,
+                    order,
+                });
+            case "highpass":
+                if (!cutoffFrequency) {
+                    throw new Error("cutoffFrequency required for highpass filter");
+                }
+                return IirFilter.createButterworthHighPass({
+                    cutoffFrequency,
+                    sampleRate: options.sampleRate,
+                    order,
+                });
+            case "bandpass":
+                if (!lowCutoffFrequency || !highCutoffFrequency) {
+                    throw new Error("lowCutoffFrequency and highCutoffFrequency required for bandpass filter");
+                }
+                return IirFilter.createButterworthBandPass({
+                    lowCutoffFrequency,
+                    highCutoffFrequency,
+                    sampleRate: options.sampleRate,
+                    order,
+                });
+            case "bandstop":
+            case "notch":
+                throw new Error(`IIR bandstop/notch filters not yet implemented. Use 'butterworth' or 'chebyshev' type instead, or use biquad notch filter.`);
+            default:
+                throw new Error(`Unsupported IIR filter mode: ${mode}`);
+        }
+    }
     /**
      * Helper to create Biquad filter from options
      */
@@ -2552,38 +2790,42 @@ class DspProcessor {
      * @returns Promise that resolves to the processed Float32Array (same reference as input)
      */
     async process(input, timestampsOrOptions, optionsIfTimestamps) {
+        let bufferToProcess;
+        let inferredChannels;
+        if (Array.isArray(input)) {
+            inferredChannels = input.length;
+            bufferToProcess = DspUtils.interleave(input);
+        }
+        else {
+            bufferToProcess = input;
+        }
         let timestamps;
         let options;
+        if (!(bufferToProcess instanceof Float32Array)) {
+            throw new TypeError(`Input samples must be a Float32Array, got ${typeof input}`);
+        }
         // Detect which overload was called
         if (timestampsOrOptions instanceof Float32Array) {
             // Time-based mode: process(samples, timestamps, options)
             timestamps = timestampsOrOptions;
             options = { channels: 1, ...optionsIfTimestamps };
-            if (timestamps.length !== input.length) {
-                throw new Error(`Timestamps length (${timestamps.length}) must match samples length (${input.length})`);
+            if (timestamps.length !== bufferToProcess.length) {
+                throw new Error(`Timestamps length (${timestamps.length}) must match samples length (${bufferToProcess.length})`);
             }
         }
         else {
-            // Sample-based mode or auto-timestamps: process(samples, options)
-            options = { channels: 1, ...timestampsOrOptions };
-            if (options.sampleRate) {
-                // Legacy sample-based mode: auto-generate timestamps from sampleRate
-                const dt = 1000 / options.sampleRate; // milliseconds per sample
-                timestamps = new Float32Array(input.length);
-                for (let i = 0; i < input.length; i++) {
-                    timestamps[i] = i * dt;
-                }
-            }
-            else {
-                // Auto-generate sequential timestamps [0, 1, 2, ...]
-                timestamps = new Float32Array(input.length);
-                for (let i = 0; i < input.length; i++) {
-                    timestamps[i] = i;
-                }
-            }
+            // Sample-based mode: process(samples, options)
+            // Fix: ensure options is correctly formed even if arg is undefined/null
+            options = { channels: 1, ...(timestampsOrOptions || {}) };
+            // Optimization: Pass undefined timestamps, let C++ generate them
+        }
+        // If using planar input, ensure channels option is set correctly
+        if (inferredChannels && options.channels === 1) {
+            options.channels = inferredChannels;
         }
         const startTime = performance.now();
         // Initialize drift detection if enabled
+        // Note: If timestamps are implicit (undefined), drift is 0 by definition, so we skip this.
         if (options.enableDriftDetection && timestamps && options.sampleRate) {
             if (!this.driftDetector ||
                 this.driftDetector.getExpectedSampleRate() !== options.sampleRate) {
@@ -2600,14 +2842,22 @@ class DspProcessor {
         try {
             // Pool the start log
             this.poolLog("debug", "Starting pipeline processing", {
-                sampleCount: input.length,
+                sampleCount: bufferToProcess.length,
                 channels: options.channels,
                 stages: this.stages.length,
                 mode: options.sampleRate ? "sample-based" : "time-based",
             });
             // Call native process with timestamps
             // Note: The input buffer is modified in-place for zero-copy performance
-            const result = await this.nativeInstance.process(input, timestamps, options);
+            let result;
+            if (timestamps) {
+                // Explicit timestamps provided
+                result = await this.nativeInstance.process(bufferToProcess, timestamps, options);
+            }
+            else {
+                // Implicit timestamps -> C++ generates them
+                result = await this.nativeInstance.process(bufferToProcess, options);
+            }
             // Execute tap callbacks for debugging/inspection
             if (this.tapCallbacks.length > 0) {
                 for (const { stageName, callback } of this.tapCallbacks) {
@@ -2673,10 +2923,10 @@ class DspProcessor {
         }
     }
     /**
-     * Process a copy of the audio data through the DSP pipeline
+     * Process a copy of the input data through the DSP pipeline
      * This method creates a copy of the input, so the original is preserved
      *
-     * @param input - Float32Array containing interleaved audio samples (original is preserved)
+     * @param input - Float32Array containing interleaved input samples (original is preserved)
      * @param timestampsOrOptions - Either timestamps array or processing options (sample rate and channel count)
      * @param optionsIfTimestamps - Processing options if timestamps were provided in second parameter
      * @returns Promise that resolves to a new Float32Array with the processed data
@@ -2691,7 +2941,9 @@ class DspProcessor {
      */
     async processCopy(input, timestampsOrOptions, optionsIfTimestamps) {
         // Create a copy to preserve the original
-        const copy = new Float32Array(input);
+        const copy = Array.isArray(input)
+            ? DspUtils.interleave(input)
+            : new Float32Array(input);
         // Handle both overloaded signatures by delegating to process()
         if (timestampsOrOptions instanceof Float32Array) {
             // Time-based mode: process(samples, timestamps, options)
@@ -2704,33 +2956,245 @@ class DspProcessor {
         }
     }
     /**
-     * Save the current pipeline state as a JSON string
-     * TypeScript can then store this in Redis or other persistent storage
+     * Process data synchronously (BLOCKING).
+     * * ⚠️ PERFORMANCE WARNING:
+     * Only use this method inside Worker Threads or Cluster Workers.
+     * Using this on the Main Thread of a server will block the Event Loop.
+     * * This method bypasses the libuv thread pool, running DSP logic directly
+     * on the calling thread. Ideal for high-frequency real-time audio loops.
+     * * @param input - Float32Array containing samples (modified in-place if no resizing)
+     * @param timestampsOrOptions - Timestamps array or options object
+     * @param optionsIfTimestamps - Options object if timestamps provided
+     */
+    processSync(input, timestampsOrOptions, optionsIfTimestamps) {
+        let bufferToProcess;
+        let inferredChannels;
+        if (Array.isArray(input)) {
+            inferredChannels = input.length;
+            bufferToProcess = DspUtils.interleave(input);
+        }
+        else {
+            bufferToProcess = input;
+        }
+        let timestamps;
+        let options;
+        if (!(bufferToProcess instanceof Float32Array)) {
+            throw new TypeError(`Input samples must be a Float32Array, got ${typeof input}`);
+        }
+        // Detect which overload was called
+        if (timestampsOrOptions instanceof Float32Array) {
+            // Time-based mode: process(samples, timestamps, options)
+            timestamps = timestampsOrOptions;
+            options = { channels: 1, ...optionsIfTimestamps };
+            if (timestamps.length !== bufferToProcess.length) {
+                throw new Error(`Timestamps length (${timestamps.length}) must match samples length (${bufferToProcess.length})`);
+            }
+        }
+        else {
+            // Sample-based mode: process(samples, options)
+            // Fix: ensure options is correctly formed even if arg is undefined/null
+            options = { channels: 1, ...(timestampsOrOptions || {}) };
+            // Optimization: Pass undefined timestamps, let C++ generate them
+        }
+        // If using planar input, ensure channels option is set correctly
+        if (inferredChannels && options.channels === 1) {
+            options.channels = inferredChannels;
+        }
+        const startTime = performance.now();
+        // Initialize drift detection if enabled
+        // Note: If timestamps are implicit (undefined), drift is 0 by definition, so we skip this.
+        if (options.enableDriftDetection && timestamps && options.sampleRate) {
+            if (!this.driftDetector ||
+                this.driftDetector.getExpectedSampleRate() !== options.sampleRate) {
+                // Create new detector if it doesn't exist or sample rate changed
+                this.driftDetector = new DriftDetector({
+                    expectedSampleRate: options.sampleRate,
+                    driftThreshold: options.driftThreshold ?? 10,
+                    onDriftDetected: options.onDriftDetected,
+                });
+            }
+            // Process timestamps to detect drift
+            this.driftDetector.processBatch(timestamps);
+        }
+        try {
+            // Pool the start log
+            this.poolLog("debug", "Starting pipeline processing", {
+                sampleCount: input.length,
+                channels: options.channels,
+                stages: this.stages.length,
+                mode: options.sampleRate ? "sample-based" : "time-based",
+            });
+            // Call native process with timestamps
+            // Note: The input buffer is modified in-place for zero-copy performance
+            let result;
+            if (timestamps) {
+                // Explicit timestamps provided
+                result = this.nativeInstance.processSync(bufferToProcess, timestamps, options);
+            }
+            else {
+                // Implicit timestamps -> C++ generates them
+                result = this.nativeInstance.processSync(bufferToProcess, options);
+            }
+            // Execute tap callbacks for debugging/inspection
+            if (this.tapCallbacks.length > 0) {
+                for (const { stageName, callback } of this.tapCallbacks) {
+                    try {
+                        callback(result, stageName);
+                    }
+                    catch (tapError) {
+                        // Don't let tap errors break the pipeline
+                        console.error(`Tap callback error at ${stageName}:`, tapError);
+                    }
+                }
+            }
+            // Execute onBatch callback (efficient - one call per process)
+            if (this.callbacks?.onBatch) {
+                const stageName = this.stages.join(" → ") || "pipeline";
+                const batch = {
+                    stage: stageName,
+                    samples: result,
+                    startIndex: 0,
+                    count: result.length,
+                };
+                this.callbacks.onBatch(batch);
+            }
+            // Execute onSample callbacks if provided (LEGACY - expensive)
+            // WARNING: This can be expensive for large buffers
+            if (this.callbacks?.onSample) {
+                const stageName = this.stages.join(" → ") || "pipeline";
+                for (let i = 0; i < result.length; i++) {
+                    this.callbacks.onSample(result[i], i, stageName);
+                }
+            }
+            // Execute onStageComplete callback
+            if (this.callbacks?.onStageComplete) {
+                const duration = performance.now() - startTime;
+                const pipelineName = this.stages.join(" → ") || "pipeline";
+                this.callbacks.onStageComplete(pipelineName, duration);
+            }
+            // Pool the completion log
+            const duration = performance.now() - startTime;
+            this.poolLog("info", "Pipeline processing completed", {
+                durationMs: duration,
+                sampleCount: result.length,
+            });
+            // Flush all pooled logs at the end
+            this.flushLogs();
+            return result;
+        }
+        catch (error) {
+            const err = error;
+            // Execute onError callback
+            if (this.callbacks?.onError) {
+                const pipelineName = this.stages.join(" → ") || "pipeline";
+                this.callbacks.onError(pipelineName, err);
+            }
+            // Pool the error log
+            this.poolLog("error", "Pipeline processing failed", {
+                error: err.message,
+                stack: err.stack,
+            });
+            // Flush logs even on error
+            this.flushLogs();
+            throw error;
+        }
+    }
+    /**
+     * Process a copy of the input data through the DSP pipeline
+     * This method creates a copy of the input, so the original is preserved
+     * * ⚠️ PERFORMANCE WARNING:
+     * Only use this method inside Worker Threads or Cluster Workers.
+     * Using this on the Main Thread of a server will block the Event Loop.
+     * * This method bypasses the libuv thread pool, running DSP logic directly
+     * on the calling thread. Ideal for high-frequency real-time audio loops.
+     * @param input - Float32Array containing interleaved input samples (original is preserved)
+     * @param timestampsOrOptions - Either timestamps array or processing options (sample rate and channel count)
+     * @param optionsIfTimestamps - Processing options if timestamps were provided in second parameter
+     * @returns Promise that resolves to a new Float32Array with the processed data
+     *
+     * @example
+     * // Legacy sample-based (original preserved)
+     * const output = await pipeline.processSyncCopy(samples, { sampleRate: 100, channels: 1 });
+     *
+     * @example
+     * // Time-based with explicit timestamps (original preserved)
+     * const output = await pipeline.processSyncCopy(samples, timestamps, { channels: 1 });
+     */
+    processSyncCopy(input, timestampsOrOptions, optionsIfTimestamps) {
+        const copy = Array.isArray(input)
+            ? DspUtils.interleave(input)
+            : new Float32Array(input);
+        // Handle both overloaded signatures by delegating to process()
+        if (timestampsOrOptions instanceof Float32Array) {
+            // Time-based mode: process(samples, timestamps, options)
+            const timestampsCopy = new Float32Array(timestampsOrOptions);
+            return this.processSync(copy, timestampsCopy, optionsIfTimestamps);
+        }
+        else {
+            // Legacy mode: process(samples, options)
+            return this.processSync(copy, timestampsOrOptions);
+        }
+    }
+    /**
+     * @brief Dispose of the DSP pipeline and free native resources
+     * After calling this method, the instance should not be used again
+     *
+     * @example
+     * const pipeline = createDspPipeline()
+     *   .MovingAverage({ mode: "moving", windowSize: 100 })
+     *   .Rectify({ mode: 'full' })
+     * const output = await pipeline.process(samples, { sampleRate: 1000, channels: 1 });
+     * pipeline.dispose();
+     * // Free resources when done, pipeline cannot be used after this for processing the input signal since the stages have been disposed
+     */
+    dispose() {
+        this.nativeInstance.dispose();
+    }
+    /**
+     * Save the current pipeline state
+     * Supports two formats:
+     * - JSON (default): Returns a string for text-based storage
+     * - TOON: Returns a Buffer for binary serialization (60-70% smaller, faster)
      *
-     * @returns JSON string containing the pipeline state
+     * @param options - Optional configuration with format: 'json' | 'toon'
+     * @returns JSON string (default) or Buffer (if format: 'toon')
      *
      * @example
+     * // Default JSON format
      * const stateJson = await pipeline.saveState();
      * await redis.set('dsp:state', stateJson);
+     *
+     * @example
+     * // TOON binary format (smaller, faster)
+     * const stateBinary = await pipeline.saveState({ format: 'toon' });
+     * await redis.set('dsp:state', stateBinary);
      */
-    async saveState() {
-        return this.nativeInstance.saveState();
+    async saveState(options) {
+        return this.nativeInstance.saveState(options);
     }
     /**
-     * Load pipeline state from a JSON string
-     * TypeScript retrieves this from Redis and passes it to restore state
+     * Load pipeline state from JSON string or TOON binary Buffer
+     * Auto-detects format: Buffer → TOON, string → JSON
      *
-     * @param stateJson - JSON string containing the pipeline state
+     * @param state - JSON string or TOON Buffer containing the pipeline state
      * @returns Promise that resolves to true if successful
      *
      * @example
+     * // Load JSON state
      * const stateJson = await redis.get('dsp:state');
      * if (stateJson) {
      *   await pipeline.loadState(stateJson);
      * }
+     *
+     * @example
+     * // Load TOON binary state (auto-detected)
+     * const stateBinary = await redis.getBuffer('dsp:state');
+     * if (stateBinary) {
+     *   await pipeline.loadState(stateBinary);
+     * }
      */
-    async loadState(stateJson) {
-        return this.nativeInstance.loadState(stateJson);
+    async loadState(state) {
+        return this.nativeInstance.loadState(state);
     }
     /**
      * Clear all pipeline state (reset all filters to initial state)
@@ -2778,18 +3242,14 @@ class DspProcessor {
  *
  * @example
  * // Create pipeline with Redis state persistence
- * const pipeline = createDspPipeline({
- *   redisHost: 'localhost',
- *   redisPort: 6379,
- *   stateKey: 'dsp:channel1'
- * });
+ * const pipeline = createDspPipeline();
  *
  * @example
  * // Create pipeline without Redis (state is not persisted)
  * const pipeline = createDspPipeline();
  */
-export function createDspPipeline(config) {
-    const nativeInstance = new DspAddon.DspPipeline(config);
+export function createDspPipeline() {
+    const nativeInstance = new DspAddon.DspPipeline();
     return new DspProcessor(nativeInstance);
 }
 export { DspProcessor };
@@ -3215,4 +3675,5 @@ export function calculateCommonSpatialPatterns(dataClass1, dataClass2, numChanne
     }
     return DspAddon.calculateCommonSpatialPatterns(dataClass1, dataClass2, numChannels, numFilters);
 }
+export { FilterBankDesign } from "./FilterBankDesign.js";
 //# sourceMappingURL=bindings.js.map