dspx 1.2.4 → 1.3.0

package/README.md

@@ -5,7 +5,7 @@
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue)](https://www.typescriptlang.org/)
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue)](./LICENSE)
 
-> **A production-ready, high-performance DSP library with native C++ acceleration, Redis state persistence, and comprehensive time-series processing. Built for Node.js backends processing real-time biosignals, audio, and sensor data.**
+> **A high-performance DSP library with native C++ acceleration, Redis state persistence, and comprehensive time-series processing. Built for Node.js backends processing real-time biosignals, audio, and sensor data.**
 
 ** v1.0.0 Release** Fully tested (500+ tests passing), battle-tested architecture, comprehensive documentation. Ready for production workloads.
 
@@ -19,8 +19,7 @@ A modern DSP library built for Node.js backends processing real-time biosignals,
 - 🎯 **SIMD Acceleration** – AVX2/SSE2/NEON optimizations provide 2-8x speedup on batch operations and rectification
 - ⚡ **Optimal FIR Filters (NEW)** – Pre-computed Parks-McClellan coefficients ship with library (30-50% faster than window-based)
 - 🔧 **TypeScript-First** – Full type safety with excellent IntelliSense
-- 📡 **Redis State Persistence** – Fully implemented state serialization/deserialization including circular buffer contents and running sums
-- 🔥 **Kafka Streaming (Experimental)** – Real-time data ingestion and log streaming via Apache Kafka (testing in progress)
+- 📡 **Low state serialization overhead** – Less than 0.1ms latency for state save/load operations
 - ⏱️ **Time-Series Processing** – Support for irregular timestamps and time-based windows
 - 🔗 **Fluent Pipeline API** – Chain filter operations with method chaining
 - 🎯 **Zero-Copy Processing** – Direct TypedArray manipulation for minimal overhead
@@ -344,7 +343,7 @@ const output = await pipeline.process(input, {
 
 **SIMD Acceleration:** Batch operations and rectification are 2-8x faster with AVX2/SSE2/NEON on x86_64. See [SIMD_OPTIMIZATIONS.md](https://github.com/A-KGeorge/dspx/blob/main/docs/SIMD_OPTIMIZATIONS.md) for details.
 
-**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).
+**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 (Datadog, Loki).
 
 ### 🎯 FFT Performance Note
 
@@ -540,77 +539,57 @@ console.log(input); // [1, 2, 3, 4, 5] - unchanged
 console.log(output); // [1, 1.5, 2, 3, 4] - smoothed
 ```
 
-### With Redis State Persistence
+### Low state serialization overhead
 
 ```typescript
 import { createDspPipeline } from "dspx";
+import { v4 as uuidv4 } from "uuid";
 import { createClient } from "redis";
 
-const redis = await createClient({ url: "redis://localhost:6379" }).connect();
-
-// Create pipeline with Redis config
-const pipeline = createDspPipeline({
-  redisHost: "localhost",
-  redisPort: 6379,
-  stateKey: "dsp:user123:channel1",
-});
-
-pipeline.MovingAverage({ windowSize: 100 });
+let redis;
+let redisAvailable = false;
 
-// Try to restore previous state from Redis
-const savedState = await redis.get("dsp:user123:channel1");
-if (savedState) {
-  await pipeline.loadState(savedState);
-  console.log("State restored!");
-}
+try {
+  redis = createClient({ url: "redis://localhost:6379" });
+  await redis.connect();
+  await redis.ping();
+  redisAvailable = true;
+} catch {}
 
-// Process data - filter state is maintained
-await pipeline.process(chunk1, { sampleRate: 2000, channels: 1 });
+const stateKey = `dspx-state-${uuidv4()}`;
 
-// Save state to Redis (includes circular buffer contents!)
-const state = await pipeline.saveState();
-await redis.set("dsp:user123:channel1", state);
+const pipeline = createDspPipeline();
+pipeline
+  .MovingAverage({ mode: "batch", windowSize: 10, windowDuration: 2 })
+  .Rms({ mode: "batch", windowSize: 10, windowDuration: 2 })
+  .Rectify({ mode: "half" });
 
-// Continue processing - even after service restart!
-await pipeline.process(chunk2, { sampleRate: 2000, channels: 1 });
+await pipeline.process(new Float32Array([1, -1, 2, -2, 3, -3]), {
+  channels: 1,
+});
 
-// Clear state when starting fresh
-pipeline.clearState();
-```
+const serialized = await pipeline.saveState();
 
-### With Kafka Streaming (Experimental)
+if (redisAvailable) await redis.set(stateKey, serialized);
 
-> ⚠️ **Note:** Kafka integration is experimental and requires additional testing. See the [Contributing](#-contributing) section if you'd like to help!
+const pipeline2 = createDspPipeline();
+pipeline2
+  .MovingAverage({ mode: "batch", windowSize: 10, windowDuration: 2 })
+  .Rms({ mode: "batch", windowSize: 10, windowDuration: 2 })
+  .Rectify({ mode: "half" });
 
-```typescript
-import { createDspPipeline, createKafkaConsumer } from "dspx";
+await pipeline2.loadState(serialized);
 
-// Create DSP pipeline
-const pipeline = createDspPipeline();
-pipeline
-  .MovingAverage({ mode: "moving", windowSize: 10 })
-  .Rms({ mode: "moving", windowSize: 5 });
-
-// Consume sensor data from Kafka topic
-const consumer = await createKafkaConsumer({
-  brokers: ["localhost:9092"],
-  groupId: "dsp-processors",
-  topics: ["sensor-data"],
-  onMessage: async ({ value }) => {
-    const samples = new Float32Array(value.data);
-    const output = await pipeline.process(samples, {
-      channels: 1,
-      sampleRate: 44100,
-    });
-    console.log("Processed:", output[0]);
-  },
+const output = await pipeline2.process(new Float32Array([4, -4, 5, -5]), {
+  channels: 1,
 });
-
-await consumer.run();
+console.log(output);
+if (redisAvailable) {
+  redis.destroy();
+  console.log("\n✓ Disconnected from Redis");
+}
 ```
 
-**See [Kafka Integration Guide](https://github.com/A-KGeorge/dspx/blob/main/docs/KAFKA_INTEGRATION.md) for real-time streaming examples.**
-
 ### Multi-Channel Processing
 
 ```typescript
@@ -638,15 +617,7 @@ const output = await pipeline.process(fourChannelData, {
 ### Creating a Pipeline
 
 ```typescript
-import { createDspPipeline, type RedisConfig } from "dspx";
-
-interface RedisConfig {
-  redisHost?: string;   // Redis server hostname (optional)
-  redisPort?: number;   // Redis server port (optional)
-  stateKey?: string;    // Key prefix for state storage (optional)
-}
-
-const pipeline = createDspPipeline(config?: RedisConfig);
+const pipeline = createDspPipeline();
 ```
 
 ### Process Methods
@@ -1838,15 +1809,11 @@ import { createClient } from "redis";
 const redis = await createClient({ url: "redis://localhost:6379" }).connect();
 const stateKey = "dsp:stream:sensor01";
 
-const pipeline = createDspPipeline({
-  redisHost: "localhost",
-  redisPort: 6379,
-  stateKey,
-});
+const pipeline = createDspPipeline();
 
 pipeline.MovingAverage({ windowSize: 100 });
-
 // Restore state if processing was interrupted
+await redis.set(stateKey, savedState);
 const savedState = await redis.get(stateKey);
 if (savedState) {
   await pipeline.loadState(savedState);
@@ -2394,11 +2361,6 @@ All 500+ tests pass after these fixes. Run `npm test` to verify.
 
 We welcome contributions! Here are areas where help is particularly needed:
 
-### High Priority
-
-- **Kafka Integration Testing** – The Kafka streaming feature is experimental and needs comprehensive integration tests. Help us validate producer/consumer patterns, error handling, and performance under load.
-- **Additional Filters** – Implement new DSP filters (bandpass, highpass, lowpass, etc.) following the existing architecture patterns.
-
 ### How to Contribute
 
 1. Fork the repository

package/binding.gyp

@@ -19,6 +19,7 @@
         "src/native/core/IirFilter.cc",
         "src/native/FftBindings.cc",
         "src/native/FilterBindings.cc",
+        "src/native/FilterBankDesignBindings.cc",
         "src/native/MatrixBindings.cc",
         "src/native/UtilityBindings.cc",
         "src/native/utils/CircularBufferArray.cc",
@@ -27,6 +28,7 @@
         "src/native/utils/SlidingWindowFilter.cc",
         "src/native/utils/TimeSeriesBuffer.cc",
         "src/native/adapters/FilterStage.cc",
+        "src/native/adapters/FilterBankStage.cc",
         "src/native/adapters/FftStage.cc"
       ],
       "include_dirs": [
@@ -38,6 +40,14 @@
         "src/native/emg",
         "src/native/vendors/eigen-3.4.0"
       ],
+      "dependencies": [
+      ],
+      "libraries": [
+      ],
+      "sources!": [
+      ],
+      "sources+": [
+      ],
       "defines": [
         "NAPI_VERSION=8"
       ],

package/dist/FilterBankDesign.d.ts

@@ -0,0 +1,233 @@
+/**
+ * Filter Bank Design
+ *
+ * Utilities for designing psychoacoustic and mathematical filter banks.
+ * These are stateless functions that generate filter coefficients.
+ */
+/**
+ * Frequency spacing scale for filter bank
+ * - 'linear': Linear spacing in Hz (equal bandwidth)
+ * - 'log': Logarithmic spacing (constant Q)
+ * - 'mel': Mel scale (mimics human hearing perception)
+ * - 'bark': Bark scale (critical band rate)
+ */
+export type FilterScale = "linear" | "log" | "mel" | "bark";
+/**
+ * Filter topology type
+ * - 'butterworth': Maximally flat passband response
+ * - 'chebyshev': Equiripple passband response (steeper rolloff)
+ */
+export type FilterBankType = "butterworth" | "chebyshev";
+/**
+ * Options for filter bank design
+ */
+export interface FilterBankOptions {
+    /**
+     * Frequency spacing scale
+     * - 'mel': Recommended for speech/audio analysis (mimics human hearing)
+     * - 'bark': Alternative psychoacoustic scale
+     * - 'log': Constant-Q filter bank (octave bands)
+     * - 'linear': Equal bandwidth bands
+     */
+    scale: FilterScale;
+    /**
+     * Number of frequency bands
+     * Typical values:
+     * - Mel spectrograms: 20-40 bands
+     * - Audio analysis: 10-30 bands
+     * - Octave bands: 10 bands (use 'log' scale)
+     */
+    count: number;
+    /**
+     * Sample rate in Hz
+     */
+    sampleRate: number;
+    /**
+     * Frequency range [minFreq, maxFreq] in Hz
+     * @example [20, 8000] // 20 Hz to 8 kHz for speech
+     * @example [0, sampleRate/2] // Full spectrum
+     */
+    frequencyRange: [number, number];
+    /**
+     * Filter topology (optional, defaults to 'butterworth')
+     * - 'butterworth': Smoother response, more gradual rolloff
+     * - 'chebyshev': Steeper rolloff, slight passband ripple
+     */
+    type?: FilterBankType;
+    /**
+     * Filter order per band (optional, defaults to 2)
+     * Higher order = steeper slopes but more computation
+     * Typical range: 2-8
+     */
+    order?: number;
+    /**
+     * Passband ripple for Chebyshev filters in dB (optional, defaults to 0.5)
+     * Only used when type='chebyshev'
+     * Typical range: 0.1-1.0 dB
+     */
+    rippleDb?: number;
+}
+/**
+ * Filter coefficients for a single band
+ */
+export interface FilterCoefficients {
+    /** Numerator coefficients (feedforward) */
+    b: number[];
+    /** Denominator coefficients (feedback) */
+    a: number[];
+}
+/**
+ * Filter Bank Design Utilities
+ *
+ * Generates sets of bandpass filters covering a frequency range according to
+ * psychoacoustic (Mel, Bark) or mathematical (Linear, Log) scales.
+ *
+ * @example
+ * // Create 24-band Mel-spaced filter bank for speech analysis
+ * const melBank = FilterBankDesign.design({
+ *   scale: 'mel',
+ *   count: 24,
+ *   sampleRate: 16000,
+ *   frequencyRange: [100, 8000]
+ * });
+ *
+ * @example
+ * // Create octave-band filter bank
+ * const octaveBank = FilterBankDesign.design({
+ *   scale: 'log',
+ *   count: 10,
+ *   sampleRate: 44100,
+ *   frequencyRange: [20, 20000],
+ *   type: 'butterworth',
+ *   order: 4
+ * });
+ */
+export declare class FilterBankDesign {
+    /**
+     * Design a filter bank with specified options
+     *
+     * This is a stateless operation that returns filter coefficients
+     * ready to be used with IIR filter processors or pipelines.
+     *
+     * @param options - Filter bank design options
+     * @returns Array of filter coefficients (one per band)
+     *
+     * @throws Error if options are invalid:
+     * - count must be positive
+     * - frequency range must be valid
+     * - maxFreq must be less than Nyquist frequency
+     *
+     * @example
+     * // Design a Mel-spaced filter bank for speech
+     * const bank = FilterBankDesign.design({
+     *   scale: 'mel',
+     *   count: 24,
+     *   sampleRate: 16000,
+     *   frequencyRange: [100, 8000]
+     * });
+     *
+     * // Use the coefficients with an IIR filter
+     * const pipeline = createDspPipeline();
+     * bank.forEach((coeffs, i) => {
+     *   pipeline.filter({
+     *     type: 'iir',
+     *     b: coeffs.b,
+     *     a: coeffs.a
+     *   });
+     * });
+     */
+    static design(options: FilterBankOptions): FilterCoefficients[];
+    /**
+     * Create a Mel-scale filter bank (helper method)
+     *
+     * Mel scale mimics human auditory perception where equal distances
+     * on the Mel scale correspond to equal perceived pitch differences.
+     *
+     * Common for: Speech recognition, audio analysis, spectrograms
+     *
+     * @param count - Number of bands (typically 20-40)
+     * @param sampleRate - Sample rate in Hz
+     * @param range - Frequency range [min, max] in Hz (defaults to [0, Nyquist])
+     * @returns Array of filter coefficients
+     *
+     * @example
+     * // Standard 40-band Mel filter bank for speech recognition
+     * const melBank = FilterBankDesign.createMel(40, 16000, [100, 8000]);
+     */
+    static createMel(count: number, sampleRate: number, range?: [number, number]): FilterCoefficients[];
+    /**
+     * Create a Bark-scale filter bank (helper method)
+     *
+     * Bark scale represents critical band rate in human hearing.
+     * Each Bark corresponds to a critical band width.
+     *
+     * Common for: Psychoacoustic modeling, audio compression
+     *
+     * @param count - Number of bands (typically 20-30)
+     * @param sampleRate - Sample rate in Hz
+     * @param range - Frequency range [min, max] in Hz (defaults to [0, Nyquist])
+     * @returns Array of filter coefficients
+     *
+     * @example
+     * // 24-band Bark filter bank
+     * const barkBank = FilterBankDesign.createBark(24, 44100, [20, 20000]);
+     */
+    static createBark(count: number, sampleRate: number, range?: [number, number]): FilterCoefficients[];
+    /**
+     * Create a logarithmic (constant-Q) filter bank (helper method)
+     *
+     * Logarithmic spacing creates constant-Q bands where Q = f_center / bandwidth.
+     * This is common in musical applications (octave bands).
+     *
+     * Common for: Musical analysis, octave band analysis, EQ
+     *
+     * @param count - Number of bands (typically 10 for octave bands)
+     * @param sampleRate - Sample rate in Hz
+     * @param range - Frequency range [min, max] in Hz (defaults to [20, Nyquist])
+     * @returns Array of filter coefficients
+     *
+     * @example
+     * // Standard 10-band octave filter bank
+     * const octaveBank = FilterBankDesign.createLog(10, 44100, [20, 20000]);
+     */
+    static createLog(count: number, sampleRate: number, range?: [number, number]): FilterCoefficients[];
+    /**
+     * Create a linear filter bank (helper method)
+     *
+     * Linear spacing creates equal-bandwidth bands across the spectrum.
+     * Less perceptually relevant but mathematically simple.
+     *
+     * Common for: Analysis, research, testing
+     *
+     * @param count - Number of bands
+     * @param sampleRate - Sample rate in Hz
+     * @param range - Frequency range [min, max] in Hz (defaults to [0, Nyquist])
+     * @returns Array of filter coefficients
+     *
+     * @example
+     * // 20 equal-bandwidth bands
+     * const linearBank = FilterBankDesign.createLinear(20, 44100);
+     */
+    static createLinear(count: number, sampleRate: number, range?: [number, number]): FilterCoefficients[];
+    /**
+     * Get frequency boundaries for a filter bank design
+     *
+     * Returns the boundary frequencies without actually designing the filters.
+     * Useful for visualization and planning.
+     *
+     * @param options - Filter bank design options (same as design())
+     * @returns Array of boundary frequencies in Hz (length = count + 1)
+     *
+     * @example
+     * const boundaries = FilterBankDesign.getBoundaries({
+     *   scale: 'mel',
+     *   count: 24,
+     *   sampleRate: 16000,
+     *   frequencyRange: [100, 8000]
+     * });
+     * console.log('Band edges:', boundaries);
+     * // [100, 145.2, 195.8, ..., 8000]
+     */
+    static getBoundaries(options: FilterBankOptions): number[];
+}
+//# sourceMappingURL=FilterBankDesign.d.ts.map

package/dist/FilterBankDesign.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FilterBankDesign.d.ts","sourceRoot":"","sources":["../src/ts/FilterBankDesign.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA0BH;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,CAAC;AAC5D;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,aAAa,GAAG,WAAW,CAAC;AAEzD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;;OAMG;IACH,KAAK,EAAE,WAAW,CAAC;IAEnB;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;;;OAIG;IACH,cAAc,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEjC;;;;OAIG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;IAEtB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,2CAA2C;IAC3C,CAAC,EAAE,MAAM,EAAE,CAAC;IACZ,0CAA0C;IAC1C,CAAC,EAAE,MAAM,EAAE,CAAC;CACb;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,gBAAgB;IAC3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACH,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,iBAAiB,GAAG,kBAAkB,EAAE;IAwB/D;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,SAAS,CACd,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,EAClB,KAAK,GAAE,CAAC,MAAM,EAAE,MAAM,CAAuB,GAC5C,kBAAkB,EAAE;IAWvB;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,UAAU,CACf,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,EAClB,KAAK,GAAE,CAAC,MAAM,EAAE,MAAM,CAAuB,GAC5C,kBAAkB,EAAE;IAWvB;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,SAAS,CACd,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,EAClB,KAAK,GAAE,CAAC,MAAM,EAAE,MAAM,CAAwB,GAC7C,kBAAkB,EAAE;IAWvB;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,YAAY,CACjB,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,EAClB,KAAK,GAAE,CAAC,MAAM,EAAE,MAAM,CAAuB,GAC5C,kBAAkB,EAAE;IAWvB;;;;;;;;;;;;;;;;;;OAkBG;IACH,MAAM,CAAC,aAAa,CAAC,OAAO,EAAE,iBAAiB,GAAG,MAAM,EAAE;CAS3D"}