dspx 1.2.4 → 1.3.1

package/src/native/adapters/FilterBankStage.h

@@ -0,0 +1,170 @@
+#pragma once
+#include "../IDspStage.h"
+#include "../core/IirFilter.h"
+#include "../utils/SimdOps.h"
+#include <vector>
+#include <memory>
+#include <stdexcept>
+
+namespace dsp::adapters
+{
+    /**
+     * @brief Lightweight struct to pass filter coefficients from JavaScript
+     */
+    struct FilterDefinition
+    {
+        std::vector<double> b; // Feedforward coefficients
+        std::vector<double> a; // Feedback coefficients
+    };
+
+    /**
+     * @brief Filter Bank Stage - Splits N input channels into N × M sub-bands
+     *
+     * Architecture:
+     * - Input: N channels (interleaved)
+     * - Output: N × M channels (interleaved, channel-major layout)
+     * - Layout: [ (Ch1_Band1, Ch1_Band2, ...), (Ch2_Band1, Ch2_Band2, ...) ]
+     *
+     * Optimization Strategy (Planar-Core):
+     * 1. De-interleave input to planar scratch buffers (cache-efficient)
+     * 2. Process filters on contiguous planar data (SIMD-friendly)
+     * 3. Interleave output back to standard format
+     *
+     * Use Cases:
+     * - Speech recognition: Mel-scale filter banks (20-40 bands)
+     * - Audio compression: Bark-scale for psychoacoustic analysis
+     * - Musical analysis: Octave bands (log scale)
+     * - Research: Linear-scale frequency analysis
+     *
+     * @example
+     * // 2 input channels → 20 output channels (10 bands per channel)
+     * // Input:  [L, R, L, R, ...]
+     * // Output: [L_B1, L_B2, ..., L_B10, R_B1, R_B2, ..., R_B10, ...]
+     */
+    class FilterBankStage : public dsp::IDspStage
+    {
+    public:
+        /**
+         * @brief Construct a filter bank stage
+         * @param bandDefinitions Array of filter coefficient definitions (one per band)
+         * @param numInputChannels Number of input channels
+         */
+        FilterBankStage(const std::vector<FilterDefinition> &bandDefinitions, int numInputChannels);
+
+        /**
+         * @brief Destructor - ensures proper cleanup of filters and scratch buffers
+         */
+        virtual ~FilterBankStage();
+
+        const char *getType() const override { return "filterBank"; }
+
+        /**
+         * @brief This stage expands the buffer size (N channels → N×M channels)
+         * @return Always true
+         */
+        bool isResizing() const override { return true; }
+
+        /**
+         * @brief Returns output channel count = inputChannels × numBands
+         * @return Output channel count
+         */
+        int getOutputChannels() const override
+        {
+            return m_numInputChannels * static_cast<int>(m_definitions.size());
+        }
+
+        /**
+         * @brief Calculate output buffer size for resizing
+         * @param inputSize Input buffer size in samples
+         * @return Output buffer size in samples
+         */
+        size_t calculateOutputSize(size_t inputSize) const override
+        {
+            return (inputSize / m_numInputChannels) * getOutputChannels();
+        }
+
+        /**
+         * @brief Standard process() throws because this stage requires resizing
+         */
+        void process(float *buffer, size_t numSamples, int numChannels, const float *timestamps) override
+        {
+            throw std::runtime_error("FilterBank requires processResizing");
+        }
+
+        /**
+         * @brief Process audio data with buffer resizing
+         *
+         * Algorithm:
+         * 1. De-interleave input to planar scratch buffers
+         * 2. Apply each band's filter to each input channel (planar processing)
+         * 3. Interleave results to output in channel-major order
+         *
+         * @param inputBuffer Source interleaved buffer
+         * @param inputSize Input size in samples
+         * @param outputBuffer Destination buffer (caller must allocate)
+         * @param outputSize Reference to store actual output size
+         * @param numChannels Number of input channels
+         * @param timestamps Optional timestamp array
+         */
+        void processResizing(const float *inputBuffer, size_t inputSize,
+                             float *outputBuffer, size_t &outputSize,
+                             int numChannels, const float *timestamps) override;
+
+        /**
+         * @brief Reset all filter states to initial conditions
+         */
+        void reset() override;
+
+        /**
+         * @brief Serialize filter bank state to JavaScript object
+         * @param env N-API environment
+         * @return Napi::Object containing all filter states
+         */
+        Napi::Object serializeState(Napi::Env env) const override;
+
+        /**
+         * @brief Restore filter bank state from JavaScript object
+         * @param state Napi::Object containing serialized filter states
+         */
+        void deserializeState(const Napi::Object &state) override;
+
+        /**
+         * @brief Serialize state to TOON binary format
+         * @param serializer TOON serializer instance
+         */
+        void serializeToon(toon::Serializer &serializer) const override;
+
+        /**
+         * @brief Deserialize state from TOON binary format
+         * @param deserializer TOON deserializer instance
+         */
+        void deserializeToon(toon::Deserializer &deserializer) override;
+
+    private:
+        /**
+         * @brief Initialize the 2D matrix of IIR filters [channel][band]
+         */
+        void initializeFilters();
+
+        /**
+         * @brief Ensure scratch buffers are allocated and sized correctly
+         * @param samplesPerChannel Number of samples per channel to process
+         */
+        void ensureScratchSize(size_t samplesPerChannel);
+
+        // Configuration
+        int m_numInputChannels;
+        std::vector<FilterDefinition> m_definitions;
+
+        // 2D Matrix of filters: m_filters[channelIndex][bandIndex]
+        std::vector<std::vector<std::unique_ptr<dsp::core::IirFilter<float>>>> m_filters;
+
+        // Optimization: Persistent scratch buffers in planar layout
+        // m_planarInput[channel][sample] - de-interleaved input
+        std::vector<std::vector<float>> m_planarInput;
+
+        // m_planarOutput[flatOutputChannelIndex][sample] - filtered planar data
+        std::vector<std::vector<float>> m_planarOutput;
+    };
+
+} // namespace dsp::adapters

package/src/native/adapters/FilterStage.cc

@@ -1,5 +1,6 @@
 #include "FilterStage.h"
 #include <stdexcept>
+#include <iostream> // For optional debug logging
 
 namespace dsp::adapters
 {
@@ -303,4 +304,125 @@ namespace dsp::adapters
         }
     }
 
+    void FilterStage::serializeToon(dsp::toon::Serializer &s) const
+    {
+        // Serialize filter type
+        s.writeString(m_isFir ? "fir" : "iir");
+
+        // Serialize coefficients
+        s.writeInt32(static_cast<int32_t>(m_bCoeffs.size()));
+        for (double coeff : m_bCoeffs)
+        {
+            s.writeDouble(coeff);
+        }
+
+        s.writeInt32(static_cast<int32_t>(m_aCoeffs.size()));
+        for (double coeff : m_aCoeffs)
+        {
+            s.writeDouble(coeff);
+        }
+
+        // Serialize filter states
+        if (m_isFir)
+        {
+            s.writeInt32(static_cast<int32_t>(m_firFilters.size()));
+            for (const auto &filter : m_firFilters)
+            {
+                if (filter)
+                {
+                    auto [stateBuffer, stateIndex] = filter->getState();
+                    s.writeFloatArray(stateBuffer);
+                    s.writeInt32(static_cast<int32_t>(stateIndex));
+                }
+                else
+                {
+                    s.writeInt32(0); // Empty state buffer size
+                    s.writeInt32(0); // stateIndex
+                }
+            }
+        }
+        else // IIR
+        {
+            s.writeInt32(static_cast<int32_t>(m_iirFilters.size()));
+            for (const auto &filter : m_iirFilters)
+            {
+                if (filter)
+                {
+                    auto [xState, yState] = filter->getState();
+                    s.writeFloatArray(xState);
+                    s.writeFloatArray(yState);
+                }
+                else
+                {
+                    s.writeInt32(0); // Empty xState size
+                    s.writeInt32(0); // Empty yState size
+                }
+            }
+        }
+    }
+
+    void FilterStage::deserializeToon(dsp::toon::Deserializer &d)
+    {
+        // Deserialize filter type
+        std::string filterType = d.readString();
+        bool isFir = (filterType == "fir");
+
+        if (isFir != m_isFir)
+        {
+            throw std::runtime_error("FilterStage TOON load: filter type mismatch");
+        }
+
+        // Deserialize and validate coefficients
+        int32_t bSize = d.readInt32();
+        if (bSize != static_cast<int32_t>(m_bCoeffs.size()))
+        {
+            throw std::runtime_error("FilterStage TOON load: bCoeffs size mismatch");
+        }
+        for (int32_t i = 0; i < bSize; ++i)
+        {
+            d.readDouble(); // Skip validation for now
+        }
+
+        int32_t aSize = d.readInt32();
+        if (aSize != static_cast<int32_t>(m_aCoeffs.size()))
+        {
+            throw std::runtime_error("FilterStage TOON load: aCoeffs size mismatch");
+        }
+        for (int32_t i = 0; i < aSize; ++i)
+        {
+            d.readDouble(); // Skip validation for now
+        }
+
+        // Deserialize filter states
+        int32_t numChannels = d.readInt32();
+        initializeFilters(numChannels);
+
+        if (m_isFir)
+        {
+            for (int32_t i = 0; i < numChannels && i < static_cast<int32_t>(m_firFilters.size()); ++i)
+            {
+                std::vector<float> stateBuffer = d.readFloatArray();
+                int32_t stateIndex = d.readInt32();
+
+                if (m_firFilters[i] && !stateBuffer.empty())
+                {
+                    m_firFilters[i]->setState(stateBuffer, static_cast<size_t>(stateIndex));
+                }
+            }
+        }
+        else // IIR
+        {
+            for (int32_t i = 0; i < numChannels && i < static_cast<int32_t>(m_iirFilters.size()); ++i)
+            {
+                std::vector<float> xState = d.readFloatArray();
+                std::vector<float> yState = d.readFloatArray();
+
+                if (m_iirFilters[i] && !xState.empty())
+                {
+                    m_iirFilters[i]->setState(xState, yState);
+                }
+            }
+        }
+    }
+
 } // namespace dsp::adapters

package/src/native/adapters/FilterStage.h

@@ -3,6 +3,7 @@
 #include "../IDspStage.h"
 #include "../core/IirFilter.h"
 #include "../core/FirFilter.h"
+#include "../utils/Toon.h"
 #include <memory>
 #include <vector>
 #include <string>
@@ -23,6 +24,9 @@ namespace dsp::adapters
         Napi::Object serializeState(Napi::Env env) const override;
         void deserializeState(const Napi::Object &state) override;
 
+        void serializeToon(dsp::toon::Serializer &serializer) const override;
+        void deserializeToon(dsp::toon::Deserializer &deserializer) override;
+
     private:
         void initializeFilters(int numChannels);
 

package/src/native/adapters/HilbertEnvelopeStage.h

@@ -31,6 +31,7 @@
 #include "../core/FftEngine.h"
 #include "../utils/CircularBufferArray.h"
 #include "../utils/SimdOps.h"
+#include "../utils/Toon.h"
 #include <vector>
 #include <complex>
 #include <memory>
@@ -199,6 +200,60 @@ namespace dsp::adapters
             }
         }
 
+        inline void serializeToon(dsp::toon::Serializer &s) const override
+        {
+            // Write configuration
+            s.writeInt32(static_cast<int32_t>(m_window_size));
+            s.writeInt32(static_cast<int32_t>(m_hop_size));
+            s.writeInt32(static_cast<int32_t>(m_channel_buffers.size()));
+
+            // Write per-channel state
+            for (size_t i = 0; i < m_channel_buffers.size(); ++i)
+            {
+                std::vector<float> buffer_data = m_channel_buffers[i].toVector();
+                s.writeFloatArray(buffer_data);
+                s.writeInt32(static_cast<int32_t>(m_samples_since_output[i]));
+            }
+        }
+
+        inline void deserializeToon(dsp::toon::Deserializer &d) override
+        {
+            // Read configuration
+            int32_t window_size = d.readInt32();
+            int32_t hop_size = d.readInt32();
+
+            if (window_size <= 0 || hop_size <= 0)
+                throw std::runtime_error("Invalid window/hop size in HilbertEnvelopeStage deserialization");
+
+            if (static_cast<size_t>(window_size) != m_window_size || static_cast<size_t>(hop_size) != m_hop_size)
+                throw std::runtime_error("Window/hop size mismatch in HilbertEnvelopeStage deserialization");
+
+            int32_t num_channels = d.readInt32();
+            if (num_channels < 0)
+                throw std::runtime_error("Invalid num_channels in HilbertEnvelopeStage deserialization");
+
+            // Recreate channel buffers
+            m_channel_buffers.clear();
+            m_samples_since_output.clear();
+
+            for (int32_t i = 0; i < num_channels; ++i)
+            {
+                m_channel_buffers.emplace_back(m_window_size);
+                m_samples_since_output.push_back(0);
+            }
+
+            // Restore per-channel state
+            for (int32_t i = 0; i < num_channels; ++i)
+            {
+                std::vector<float> buffer_data = d.readFloatArray();
+                for (float value : buffer_data)
+                {
+                    m_channel_buffers[i].push(value);
+                }
+                m_samples_since_output[i] = static_cast<size_t>(d.readInt32());
+            }
+        }
+
         void reset() override
         {
             for (auto &buffer : m_channel_buffers)

package/src/native/adapters/IntegratorStage.h

@@ -2,6 +2,7 @@
 #define INTEGRATOR_STAGE_H
 
 #include "../IDspStage.h"
+#include "../utils/Toon.h"
 #include <vector>
 #include <cmath>
 #include <stdexcept>
@@ -129,6 +130,20 @@ namespace dsp::adapters
             std::fill(m_prev_output.begin(), m_prev_output.end(), 0.0f);
         }
 
+        void serializeToon(dsp::toon::Serializer &s) const override
+        {
+            s.writeFloat(m_alpha);
+            s.writeInt32(m_num_channels);
+            s.writeFloatArray(m_prev_output);
+        }
+
+        void deserializeToon(dsp::toon::Deserializer &d) override
+        {
+            m_alpha = d.readFloat();
+            m_num_channels = d.readInt32();
+            m_prev_output = d.readFloatArray();
+        }
+
         bool isResizing() const override
         {
             return false;

package/src/native/adapters/InterpolatorStage.h

@@ -8,6 +8,7 @@
 #pragma once
 
 #include "../IDspStage.h"
+#include "../utils/Toon.h"
 #include <vector>
 #include <cmath>
 #include <stdexcept>
@@ -154,6 +155,56 @@ namespace dsp
             }
         }
 
+        void serializeToon(dsp::toon::Serializer &s) const override
+        {
+            s.writeInt32(interpolationFactor_);
+            s.writeInt32(filterOrder_);
+            s.writeDouble(sampleRate_);
+            s.writeInt32(numChannels_);
+
+            // Serialize state buffers for each channel
+            for (const auto &buf : stateBuffers_)
+            {
+                s.writeFloatArray(buf);
+            }
+
+            // Serialize state indices
+            for (size_t idx : stateIndices_)
+            {
+                s.writeInt32(static_cast<int32_t>(idx));
+            }
+        }
+
+        void deserializeToon(dsp::toon::Deserializer &d) override
+        {
+            int32_t factor = d.readInt32();
+            int32_t order = d.readInt32();
+            double sr = d.readDouble();
+            int32_t nCh = d.readInt32();
+
+            if (factor != interpolationFactor_ || order != filterOrder_)
+            {
+                throw std::runtime_error("Interpolator TOON: parameter mismatch");
+            }
+
+            if (nCh != numChannels_)
+            {
+                initializeStateBuffers(nCh);
+            }
+
+            // Deserialize state buffers
+            for (auto &buf : stateBuffers_)
+            {
+                buf = d.readFloatArray();
+            }
+
+            // Deserialize state indices
+            for (size_t &idx : stateIndices_)
+            {
+                idx = static_cast<size_t>(d.readInt32());
+            }
+        }
+
     private:
         int interpolationFactor_;
         int filterOrder_;

package/src/native/adapters/LinearRegressionStage.h

@@ -3,6 +3,7 @@
 
 #include "../IDspStage.h"
 #include "../utils/SimdOps.h"
+#include "../utils/Toon.h"
 #include <vector>
 #include <cmath>
 #include <stdexcept>
@@ -321,6 +322,45 @@ namespace dsp
                 }
             }
 
+            inline void serializeToon(dsp::toon::Serializer &s) const override
+            {
+                // Write configuration
+                s.writeInt32(static_cast<int32_t>(m_windowSize));
+                s.writeInt32(static_cast<int32_t>(m_numChannels));
+
+                // Write per-channel state
+                for (size_t ch = 0; ch < m_numChannels; ++ch)
+                {
+                    s.writeFloatArray(m_buffers[ch]);
+                    s.writeInt32(static_cast<int32_t>(m_writeIndices[ch]));
+                    s.writeInt32(static_cast<int32_t>(m_sampleCounts[ch]));
+                }
+            }
+
+            inline void deserializeToon(dsp::toon::Deserializer &d) override
+            {
+                // Read configuration
+                int32_t windowSize = d.readInt32();
+                if (windowSize < 2)
+                    throw std::runtime_error("Invalid windowSize in LinearRegressionStage deserialization");
+                if (static_cast<size_t>(windowSize) != m_windowSize)
+                    throw std::runtime_error("Window size mismatch in LinearRegressionStage deserialization");
+
+                int32_t numChannels = d.readInt32();
+                if (numChannels < 0)
+                    throw std::runtime_error("Invalid numChannels in LinearRegressionStage deserialization");
+
+                init(static_cast<size_t>(numChannels));
+
+                // Read per-channel state
+                for (size_t ch = 0; ch < m_numChannels; ++ch)
+                {
+                    m_buffers[ch] = d.readFloatArray();
+                    m_writeIndices[ch] = static_cast<size_t>(d.readInt32());
+                    m_sampleCounts[ch] = static_cast<size_t>(d.readInt32());
+                }
+            }
+
             void reset() override
             {
                 for (size_t ch = 0; ch < m_numChannels; ++ch)

package/src/native/adapters/LmsStage.h

@@ -176,6 +176,69 @@ namespace dsp
             }
         }
 
+        void serializeToon(dsp::toon::Serializer &s) const override
+        {
+            s.startObject();
+
+            s.writeString("numTaps");
+            s.writeInt32(static_cast<int32_t>(m_numTaps));
+
+            s.writeString("learningRate");
+            s.writeFloat(m_learningRate);
+
+            s.writeString("normalized");
+            s.writeBool(m_normalized);
+
+            s.writeString("lambda");
+            s.writeFloat(m_lambda);
+
+            s.writeString("initialized");
+            s.writeBool(m_initialized);
+
+            if (m_initialized)
+            {
+                auto weights = m_filter->getWeights(0);
+                s.writeString("weights");
+                s.writeFloatArray(weights);
+            }
+
+            s.endObject();
+        }
+
+        void deserializeToon(dsp::toon::Deserializer &d) override
+        {
+            d.consumeToken(dsp::toon::T_OBJECT_START);
+
+            std::string key = d.readString(); // "numTaps"
+            m_numTaps = d.readInt32();
+
+            key = d.readString(); // "learningRate"
+            m_learningRate = d.readFloat();
+
+            key = d.readString(); // "normalized"
+            m_normalized = d.readBool();
+
+            key = d.readString(); // "lambda"
+            m_lambda = d.readFloat();
+
+            key = d.readString(); // "initialized"
+            m_initialized = d.readBool();
+
+            // Recreate filter with restored parameters
+            m_filter = std::make_unique<dsp::core::DifferentiableFilter<float>>(m_numTaps, m_learningRate, m_lambda, m_normalized);
+
+            if (m_initialized)
+            {
+                m_filter->init(1); // Reinitialize filter
+
+                key = d.readString(); // "weights"
+                std::vector<float> weights = d.readFloatArray();
+                m_filter->setWeights(0, weights);
+            }
+
+            d.consumeToken(dsp::toon::T_OBJECT_END);
+        }
+
     private:
         void ensureScratchBuffers(size_t samplesPerChannel)
         {