dspx 1.2.4 → 1.3.1

package/src/native/DspPipeline.h

@@ -4,6 +4,7 @@
 #include <memory>
 #include <unordered_map>
 #include <functional>
+#include <atomic>
 #include "IDspStage.h"
 
 namespace dsp
@@ -23,6 +24,12 @@ namespace dsp
         // This is the async "process" method called by the TS processor
         Napi::Value ProcessAsync(const Napi::CallbackInfo &info);
 
+        // The Synchronous method for JS workers/clusters
+        Napi::Value ProcessSync(const Napi::CallbackInfo &info);
+
+        // Dispose method for explicit teardown
+        Napi::Value Dispose(const Napi::CallbackInfo &info);
+
         // State management methods (for Redis persistence from TypeScript)
         Napi::Value SaveState(const Napi::CallbackInfo &info);
         Napi::Value LoadState(const Napi::CallbackInfo &info);
@@ -40,6 +47,12 @@ namespace dsp
 
         // This is the "pipeline": a vector of our abstract filter stages
         std::vector<std::unique_ptr<IDspStage>> m_stages;
+
+        // uses shared_ptr so the lock survices if the JS object is GC'd early
+        std::shared_ptr<std::atomic<bool>> m_isBusy;
+
+        // Flag to track if pipeline has been disposed
+        bool m_disposed = false;
     };
 
 } // namespace dsp

package/src/native/FilterBankDesignBindings.cc

@@ -0,0 +1,241 @@
+/**
+ * Filter Bank Design Bindings
+ *
+ * N-API bindings for filter bank design utilities.
+ * Exposes stateless filter bank generation to TypeScript.
+ */
+
+#include <napi.h>
+#include "core/FilterBankDesign.h"
+
+namespace dsp
+{
+    /**
+     * Design a filter bank (N-API binding)
+     *
+     * @param info[0] - Options object with:
+     *   - scale: 'linear' | 'log' | 'mel' | 'bark'
+     *   - type: 'butterworth' | 'chebyshev'
+     *   - count: number of bands
+     *   - sampleRate: sample rate in Hz
+     *   - frequencyRange: [minFreq, maxFreq]
+     *   - order: filter order (default: 2)
+     *   - rippleDb: Chebyshev ripple (default: 0.5)
+     *
+     * @return Array of { b: number[], a: number[] } coefficient objects
+     */
+    Napi::Value DesignFilterBank(const Napi::CallbackInfo &info)
+    {
+        Napi::Env env = info.Env();
+
+        // Validate input
+        if (info.Length() < 1 || !info[0].IsObject())
+        {
+            Napi::TypeError::New(env, "Options object required")
+                .ThrowAsJavaScriptException();
+            return env.Null();
+        }
+
+        Napi::Object options = info[0].As<Napi::Object>();
+
+        try
+        {
+            // Parse options
+            core::FilterBankDesign::DesignOptions opts;
+
+            // Parse scale
+            if (!options.Has("scale") || !options.Get("scale").IsString())
+            {
+                throw std::invalid_argument("scale (string) is required");
+            }
+            std::string scaleStr = options.Get("scale").As<Napi::String>().Utf8Value();
+
+            if (scaleStr == "mel")
+            {
+                opts.scale = core::FilterBankDesign::Scale::Mel;
+            }
+            else if (scaleStr == "bark")
+            {
+                opts.scale = core::FilterBankDesign::Scale::Bark;
+            }
+            else if (scaleStr == "log")
+            {
+                opts.scale = core::FilterBankDesign::Scale::Log;
+            }
+            else if (scaleStr == "linear")
+            {
+                opts.scale = core::FilterBankDesign::Scale::Linear;
+            }
+            else
+            {
+                throw std::invalid_argument("Invalid scale: must be 'linear', 'log', 'mel', or 'bark'");
+            }
+
+            // Parse type (optional, defaults to butterworth)
+            opts.type = core::FilterBankDesign::Type::Butterworth;
+            if (options.Has("type") && options.Get("type").IsString())
+            {
+                std::string typeStr = options.Get("type").As<Napi::String>().Utf8Value();
+                if (typeStr == "chebyshev" || typeStr == "chebyshev1")
+                {
+                    opts.type = core::FilterBankDesign::Type::Chebyshev1;
+                }
+                else if (typeStr != "butterworth")
+                {
+                    throw std::invalid_argument("Invalid type: must be 'butterworth' or 'chebyshev'");
+                }
+            }
+
+            // Parse count
+            if (!options.Has("count") || !options.Get("count").IsNumber())
+            {
+                throw std::invalid_argument("count (number) is required");
+            }
+            opts.count = options.Get("count").As<Napi::Number>().Int32Value();
+
+            // Parse sampleRate
+            if (!options.Has("sampleRate") || !options.Get("sampleRate").IsNumber())
+            {
+                throw std::invalid_argument("sampleRate (number) is required");
+            }
+            opts.sampleRate = options.Get("sampleRate").As<Napi::Number>().DoubleValue();
+
+            // Parse frequencyRange
+            if (!options.Has("frequencyRange") || !options.Get("frequencyRange").IsArray())
+            {
+                throw std::invalid_argument("frequencyRange ([min, max]) is required");
+            }
+            Napi::Array range = options.Get("frequencyRange").As<Napi::Array>();
+            if (range.Length() < 2)
+            {
+                throw std::invalid_argument("frequencyRange must have at least 2 elements");
+            }
+            opts.minFreq = range.Get((uint32_t)0).As<Napi::Number>().DoubleValue();
+            opts.maxFreq = range.Get((uint32_t)1).As<Napi::Number>().DoubleValue();
+
+            // Parse order (optional, defaults to 2)
+            opts.order = 2;
+            if (options.Has("order") && options.Get("order").IsNumber())
+            {
+                opts.order = options.Get("order").As<Napi::Number>().Int32Value();
+            }
+
+            // Parse rippleDb (optional, defaults to 0.5)
+            opts.rippleDb = 0.5;
+            if (options.Has("rippleDb") && options.Get("rippleDb").IsNumber())
+            {
+                opts.rippleDb = options.Get("rippleDb").As<Napi::Number>().DoubleValue();
+            }
+
+            // Design the filter bank
+            auto bank = core::FilterBankDesign::design(opts);
+
+            // Convert to JavaScript array
+            Napi::Array result = Napi::Array::New(env, bank.size());
+
+            for (size_t i = 0; i < bank.size(); ++i)
+            {
+                Napi::Object coeffs = Napi::Object::New(env);
+
+                // Convert b coefficients
+                Napi::Array b = Napi::Array::New(env, bank[i].b.size());
+                for (size_t j = 0; j < bank[i].b.size(); ++j)
+                {
+                    b.Set(j, Napi::Number::New(env, bank[i].b[j]));
+                }
+                coeffs.Set("b", b);
+
+                // Convert a coefficients
+                Napi::Array a = Napi::Array::New(env, bank[i].a.size());
+                for (size_t j = 0; j < bank[i].a.size(); ++j)
+                {
+                    a.Set(j, Napi::Number::New(env, bank[i].a[j]));
+                }
+                coeffs.Set("a", a);
+
+                result.Set(i, coeffs);
+            }
+
+            return result;
+        }
+        catch (const std::exception &e)
+        {
+            Napi::Error::New(env, std::string("Filter bank design failed: ") + e.what())
+                .ThrowAsJavaScriptException();
+            return env.Null();
+        }
+    }
+
+    /**
+     * Get filter bank frequency boundaries (N-API binding)
+     *
+     * Useful for visualization and debugging
+     *
+     * @param info[0] - Same options object as designFilterBank
+     * @return Array of boundary frequencies in Hz
+     */
+    Napi::Value GetFilterBankBoundaries(const Napi::CallbackInfo &info)
+    {
+        Napi::Env env = info.Env();
+
+        if (info.Length() < 1 || !info[0].IsObject())
+        {
+            Napi::TypeError::New(env, "Options object required")
+                .ThrowAsJavaScriptException();
+            return env.Null();
+        }
+
+        Napi::Object options = info[0].As<Napi::Object>();
+
+        try
+        {
+            // Parse options (same as DesignFilterBank)
+            core::FilterBankDesign::DesignOptions opts;
+
+            std::string scaleStr = options.Get("scale").As<Napi::String>().Utf8Value();
+            if (scaleStr == "mel")
+                opts.scale = core::FilterBankDesign::Scale::Mel;
+            else if (scaleStr == "bark")
+                opts.scale = core::FilterBankDesign::Scale::Bark;
+            else if (scaleStr == "log")
+                opts.scale = core::FilterBankDesign::Scale::Log;
+            else
+                opts.scale = core::FilterBankDesign::Scale::Linear;
+
+            opts.count = options.Get("count").As<Napi::Number>().Int32Value();
+
+            Napi::Array range = options.Get("frequencyRange").As<Napi::Array>();
+            opts.minFreq = range.Get((uint32_t)0).As<Napi::Number>().DoubleValue();
+            opts.maxFreq = range.Get((uint32_t)1).As<Napi::Number>().DoubleValue();
+
+            // Get boundaries
+            auto boundaries = core::FilterBankDesign::getBoundaries(opts);
+
+            // Convert to JavaScript array
+            Napi::Array result = Napi::Array::New(env, boundaries.size());
+            for (size_t i = 0; i < boundaries.size(); ++i)
+            {
+                result.Set(i, Napi::Number::New(env, boundaries[i]));
+            }
+
+            return result;
+        }
+        catch (const std::exception &e)
+        {
+            Napi::Error::New(env, std::string("Get boundaries failed: ") + e.what())
+                .ThrowAsJavaScriptException();
+            return env.Null();
+        }
+    }
+
+    /**
+     * Register filter bank design bindings
+     * Call this from your main addon Init function
+     */
+    void RegisterFilterBankDesignBindings(Napi::Env env, Napi::Object exports)
+    {
+        exports.Set("designFilterBank", Napi::Function::New(env, DesignFilterBank));
+        exports.Set("getFilterBankBoundaries", Napi::Function::New(env, GetFilterBankBoundaries));
+    }
+
+} // namespace dsp

package/src/native/IDspStage.h

@@ -1,6 +1,7 @@
 #pragma once
 #include <napi.h>
 #include <cstring> // for std::memcpy
+#include "utils/Toon.h"
 
 namespace dsp
 {
@@ -98,6 +99,29 @@ namespace dsp
          */
         virtual void deserializeState(const Napi::Object &state) = 0;
 
+        /**
+         * @brief Serializes internal state to the efficient TOON binary format.
+         * Default implementation throws, forcing derived classes to implement it
+         * if TOON support is required.
+         *
+         * @param serializer The TOON serializer to write binary data to.
+         */
+        virtual void serializeToon(toon::Serializer &serializer) const
+        {
+            // Fallback: throw if not implemented for a specific stage
+            throw std::runtime_error("TOON serialization not implemented for this stage type");
+        }
+
+        /**
+         * @brief Deserializes internal state from TOON binary format.
+         *
+         * @param deserializer The TOON deserializer to read binary data from.
+         */
+        virtual void deserializeToon(toon::Deserializer &deserializer)
+        {
+            throw std::runtime_error("TOON deserialization not implemented for this stage type");
+        }
+
         /**
          * @brief Resets the stage's internal state to initial values.
          */

package/src/native/UtilityBindings.cc

@@ -203,6 +203,134 @@ namespace dsp
             return output;
         }
 
+        /**
+         * @brief Interleaves an array of planar Float32Arrays into a single Float32Array.
+         *
+         * Takes an array of Float32Arrays (one per channel) and combines them into a
+         * single interleaved buffer.
+         *
+         * @param info[0] - An array of Float32Array objects.
+         * @returns A new Float32Array containing the interleaved data.
+         */
+        Napi::Value Interleave(const Napi::CallbackInfo &info)
+        {
+            Napi::Env env = info.Env();
+
+            if (info.Length() < 1 || !info[0].IsArray())
+            {
+                Napi::TypeError::New(env, "Expected an array of Float32Arrays").ThrowAsJavaScriptException();
+                return env.Null();
+            }
+
+            Napi::Array planarArray = info[0].As<Napi::Array>();
+            uint32_t numChannels = planarArray.Length();
+
+            if (numChannels == 0)
+            {
+                return Napi::Float32Array::New(env, 0);
+            }
+
+            std::vector<Napi::Float32Array> channels;
+            size_t channelLength = 0;
+
+            for (uint32_t i = 0; i < numChannels; ++i)
+            {
+                Napi::Value val = planarArray.Get(i);
+                if (!val.IsTypedArray() || val.As<Napi::TypedArray>().TypedArrayType() != napi_float32_array)
+                {
+                    Napi::TypeError::New(env, "All elements in the array must be Float32Arrays").ThrowAsJavaScriptException();
+                    return env.Null();
+                }
+                Napi::Float32Array channel = val.As<Napi::Float32Array>();
+                if (i == 0)
+                {
+                    channelLength = channel.ElementLength();
+                }
+                else if (channel.ElementLength() != channelLength)
+                {
+                    Napi::TypeError::New(env, "All channels must have the same length").ThrowAsJavaScriptException();
+                    return env.Null();
+                }
+                channels.push_back(channel);
+            }
+
+            size_t interleavedLength = numChannels * channelLength;
+            Napi::Float32Array interleaved = Napi::Float32Array::New(env, interleavedLength);
+            float *outputData = interleaved.Data();
+
+            for (size_t i = 0; i < channelLength; ++i)
+            {
+                for (uint32_t c = 0; c < numChannels; ++c)
+                {
+                    outputData[i * numChannels + c] = channels[c].Data()[i];
+                }
+            }
+
+            return interleaved;
+        }
+
+        /**
+         * @brief Deinterleaves a single Float32Array into an array of planar Float32Arrays.
+         *
+         * Takes an interleaved Float32Array and a channel count, and separates them
+         * into an array of Float32Arrays (one per channel).
+         *
+         * @param info[0] - The interleaved Float32Array.
+         * @param info[1] - The number of channels.
+         * @returns An array of new Float32Arrays, one for each channel.
+         */
+        Napi::Value Deinterleave(const Napi::CallbackInfo &info)
+        {
+            Napi::Env env = info.Env();
+
+            if (info.Length() < 2 || !info[0].IsTypedArray() || !info[1].IsNumber())
+            {
+                Napi::TypeError::New(env, "Expected an interleaved Float32Array and a channel count").ThrowAsJavaScriptException();
+                return env.Null();
+            }
+
+            Napi::TypedArray typedArray = info[0].As<Napi::TypedArray>();
+            if (typedArray.TypedArrayType() != napi_float32_array)
+            {
+                Napi::TypeError::New(env, "Input must be a Float32Array").ThrowAsJavaScriptException();
+                return env.Null();
+            }
+
+            Napi::Float32Array interleaved = typedArray.As<Napi::Float32Array>();
+            int numChannels = info[1].As<Napi::Number>().Int32Value();
+
+            if (numChannels <= 0)
+            {
+                Napi::TypeError::New(env, "Number of channels must be positive").ThrowAsJavaScriptException();
+                return env.Null();
+            }
+
+            size_t interleavedLength = interleaved.ElementLength();
+            if (interleavedLength % numChannels != 0)
+            {
+                Napi::RangeError::New(env, "Interleaved length is not divisible by the number of channels").ThrowAsJavaScriptException();
+                return env.Null();
+            }
+
+            size_t channelLength = interleavedLength / numChannels;
+            const float *inputData = interleaved.Data();
+
+            Napi::Array planarArray = Napi::Array::New(env, numChannels);
+
+            for (int c = 0; c < numChannels; ++c)
+            {
+                Napi::Float32Array channel = Napi::Float32Array::New(env, channelLength);
+                float *channelData = channel.Data();
+                for (size_t i = 0; i < channelLength; ++i)
+                {
+                    channelData[i] = inputData[i * numChannels + c];
+                }
+                planarArray.Set(c, channel);
+            }
+
+            return planarArray;
+        }
+
         /**
          * @brief Initialize utility function bindings
          */
@@ -210,6 +338,8 @@ namespace dsp
         {
             exports.Set("dotProduct", Napi::Function::New(env, DotProduct));
             exports.Set("detrend", Napi::Function::New(env, Detrend));
+            exports.Set("interleave", Napi::Function::New(env, Interleave));
+            exports.Set("deinterleave", Napi::Function::New(env, Deinterleave));
             return exports;
         }
 

package/src/native/adapters/AmplifyStage.h

@@ -0,0 +1,148 @@
+#ifndef DSP_ADAPTERS_AMPLIFYSTAGE_H
+#define DSP_ADAPTERS_AMPLIFYSTAGE_H
+
+#include "IDspStage.h"
+#include "../utils/SimdOps.h"
+#include <cstring>
+
+// Platform detection for SIMD
+#if defined(__AVX2__)
+#include <immintrin.h>
+#elif defined(__SSE2__) || defined(_M_X64) || (defined(_M_IX86_FP) && _M_IX86_FP >= 2)
+#include <emmintrin.h>
+#elif defined(__ARM_NEON) || defined(__aarch64__)
+#include <arm_neon.h>
+#endif
+
+namespace dsp
+{
+    namespace adapters
+    {
+        /**
+         * Amplify (Gain) Stage
+         * Multiplies all samples by a constant gain factor.
+         * SIMD-optimized for maximum throughput (AVX2/SSE2/NEON).
+         * Useful for scaling signals to appropriate amplitude ranges.
+         */
+        class AmplifyStage : public IDspStage
+        {
+        public:
+            explicit AmplifyStage(float gain = 1.0f)
+                : m_gain(gain)
+            {
+            }
+
+            void process(float *data, size_t numSamples, int channels, const float *timestamps = nullptr) override
+            {
+                // SIMD-optimized gain multiplication
+#if defined(__AVX2__)
+                // AVX2: Process 8 floats at a time
+                const size_t simd_width = 8;
+                const size_t simd_count = numSamples / simd_width;
+                const size_t simd_end = simd_count * simd_width;
+
+                const __m256 gain_vec = _mm256_set1_ps(m_gain);
+
+                for (size_t i = 0; i < simd_end; i += simd_width)
+                {
+                    __m256 samples = _mm256_loadu_ps(&data[i]);
+                    samples = _mm256_mul_ps(samples, gain_vec);
+                    _mm256_storeu_ps(&data[i], samples);
+                }
+
+                // Handle remainder
+                for (size_t i = simd_end; i < numSamples; ++i)
+                {
+                    data[i] *= m_gain;
+                }
+
+#elif defined(__SSE2__) || defined(_M_X64) || (defined(_M_IX86_FP) && _M_IX86_FP >= 2)
+                // SSE2: Process 4 floats at a time
+                const size_t simd_width = 4;
+                const size_t simd_count = numSamples / simd_width;
+                const size_t simd_end = simd_count * simd_width;
+
+                const __m128 gain_vec = _mm_set1_ps(m_gain);
+
+                for (size_t i = 0; i < simd_end; i += simd_width)
+                {
+                    __m128 samples = _mm_loadu_ps(&data[i]);
+                    samples = _mm_mul_ps(samples, gain_vec);
+                    _mm_storeu_ps(&data[i], samples);
+                }
+
+                // Handle remainder
+                for (size_t i = simd_end; i < numSamples; ++i)
+                {
+                    data[i] *= m_gain;
+                }
+
+#elif defined(__ARM_NEON) || defined(__aarch64__)
+                // ARM NEON: Process 4 floats at a time
+                const size_t simd_width = 4;
+                const size_t simd_count = numSamples / simd_width;
+                const size_t simd_end = simd_count * simd_width;
+
+                const float32x4_t gain_vec = vdupq_n_f32(m_gain);
+
+                for (size_t i = 0; i < simd_end; i += simd_width)
+                {
+                    float32x4_t samples = vld1q_f32(&data[i]);
+                    samples = vmulq_f32(samples, gain_vec);
+                    vst1q_f32(&data[i], samples);
+                }
+
+                // Handle remainder
+                for (size_t i = simd_end; i < numSamples; ++i)
+                {
+                    data[i] *= m_gain;
+                }
+
+#else
+                // Scalar fallback (compiler may auto-vectorize)
+                for (size_t i = 0; i < numSamples; ++i)
+                {
+                    data[i] *= m_gain;
+                }
+#endif
+            }
+
+            const char *getType() const override
+            {
+                return "amplify";
+            }
+
+            Napi::Object serializeState(Napi::Env env) const override
+            {
+                // Stateless - return empty object
+                return Napi::Object::New(env);
+            }
+
+            void deserializeState(const Napi::Object &state) override
+            {
+                // Stateless - nothing to restore
+            }
+
+            // Serialization
+            void serializeToon(dsp::toon::Serializer &s) const override
+            {
+                // Stateless - no data to serialize
+            }
+
+            void deserializeToon(dsp::toon::Deserializer &d) override
+            {
+                // Stateless - no data to deserialize
+            }
+
+            void reset() override
+            {
+                // Stateless - no internal state to reset
+            }
+
+        private:
+            float m_gain;
+        };
+    } // namespace adapters
+} // namespace dsp
+
+#endif // DSP_ADAPTERS_AMPLIFYSTAGE_H

package/src/native/adapters/ClipDetectionStage.h

@@ -1,6 +1,7 @@
 #pragma once
 
 #include "../IDspStage.h"
+#include "../utils/Toon.h"
 #include <cmath>
 #include <stdexcept>
 #include <string>
@@ -9,19 +10,19 @@ namespace dsp::adapters
 {
     /**
      * @brief Clip Detection Stage - Detects when samples exceed a threshold.
-     * 
+     *
      * This stage analyzes the input signal and outputs a binary (0.0 or 1.0) indicator
      * showing where clipping occurs. This is useful for:
      * - Audio clipping detection (overload prevention)
      * - Saturation detection in ADC signals
      * - Quality control in data acquisition
-     * 
+     *
      * **Output:**
      * - 1.0 when |sample| >= threshold (clipping detected)
      * - 0.0 when |sample| < threshold (no clipping)
-     * 
+     *
      * **Processing:** Stateless, processes each sample independently
-     * 
+     *
      * @example
      * ```cpp
      * // Detect audio clipping at 0.95 (5% headroom)
@@ -77,6 +78,16 @@ namespace dsp::adapters
             }
         }
 
+        inline void serializeToon(dsp::toon::Serializer &s) const override
+        {
+            s.writeFloat(m_threshold);
+        }
+
+        inline void deserializeToon(dsp::toon::Deserializer &d) override
+        {
+            m_threshold = d.readFloat();
+        }
+
         void reset() override
         {
             // No state to reset (stateless stage)