dspx 1.2.3 → 1.3.0

package/src/native/adapters/FilterBankStage.cc

@@ -0,0 +1,336 @@
+#include "FilterBankStage.h"
+#include <iostream>
+
+namespace dsp::adapters
+{
+
+    FilterBankStage::FilterBankStage(const std::vector<FilterDefinition> &definitions, int numInputChannels)
+        : m_definitions(definitions), m_numInputChannels(numInputChannels)
+    {
+        if (definitions.empty())
+        {
+            throw std::runtime_error("FilterBank: definitions cannot be empty");
+        }
+        if (numInputChannels <= 0)
+        {
+            throw std::runtime_error("FilterBank: Invalid channel count");
+        }
+
+        initializeFilters();
+    }
+    FilterBankStage::~FilterBankStage()
+    {
+        try
+        {
+            // Explicitly clear filters first to ensure IirFilter destructors run
+            // before scratch buffers are destroyed
+            for (size_t ch = 0; ch < m_filters.size(); ++ch)
+            {
+                m_filters[ch].clear(); // Destroys all unique_ptrs in this channel
+            }
+            m_filters.clear(); // Clear outer vector
+
+            // Clear scratch buffers
+            m_planarInput.clear();
+            m_planarOutput.clear();
+        }
+        catch (const std::exception &e)
+        {
+            std::cerr << "[FilterBankStage] ERROR in destructor: " << e.what() << std::endl;
+        }
+        catch (...)
+        {
+            std::cerr << "[FilterBankStage] UNKNOWN ERROR in destructor" << std::endl;
+        }
+    }
+
+    void FilterBankStage::processResizing(const float *inputBuffer, size_t inputSize,
+                                          float *outputBuffer, size_t &outputSize,
+                                          int numChannels, const float *timestamps)
+    {
+        if (numChannels != m_numInputChannels)
+        {
+            throw std::runtime_error("FilterBank: Input channel mismatch");
+        }
+
+        size_t samplesPerChannel = inputSize / numChannels;
+        size_t numBands = m_definitions.size();
+        size_t totalOutputChannels = numChannels * numBands;
+
+        outputSize = samplesPerChannel * totalOutputChannels;
+
+        ensureScratchSize(samplesPerChannel);
+
+        std::vector<float *> inputPtrs(numChannels);
+        for (int i = 0; i < numChannels; ++i)
+        {
+            inputPtrs[i] = m_planarInput[i].data();
+        }
+
+        if (numChannels == 2)
+        {
+            dsp::simd::deinterleave2Ch(inputBuffer, inputPtrs[0], inputPtrs[1], samplesPerChannel);
+        }
+        else
+        {
+            dsp::simd::deinterleaveNCh(inputBuffer, inputPtrs.data(), numChannels, samplesPerChannel);
+        }
+
+        for (int ch = 0; ch < numChannels; ++ch)
+        {
+            for (size_t band = 0; band < numBands; ++band)
+            {
+                int outChIndex = (ch * static_cast<int>(numBands)) + static_cast<int>(band);
+
+                m_filters[ch][band]->process(
+                    m_planarInput[ch].data(),
+                    m_planarOutput[outChIndex].data(),
+                    samplesPerChannel);
+            }
+        }
+
+        std::vector<const float *> outputPtrs(totalOutputChannels);
+        for (size_t i = 0; i < totalOutputChannels; ++i)
+        {
+            outputPtrs[i] = m_planarOutput[i].data();
+        }
+
+        dsp::simd::interleaveNCh(outputPtrs.data(), outputBuffer, static_cast<int>(totalOutputChannels), samplesPerChannel);
+    }
+
+    void FilterBankStage::initializeFilters()
+    {
+        m_filters.resize(m_numInputChannels);
+        for (int ch = 0; ch < m_numInputChannels; ++ch)
+        {
+            m_filters[ch].clear();
+            for (const auto &def : m_definitions)
+            {
+                // Convert double coefficients to float for IirFilter
+                std::vector<float> b_float(def.b.begin(), def.b.end());
+                std::vector<float> a_float(def.a.begin(), def.a.end());
+
+                // Create stateful IIR filter for each band
+                m_filters[ch].push_back(
+                    std::make_unique<dsp::core::IirFilter<float>>(b_float, a_float, true));
+            }
+        }
+    }
+
+    void FilterBankStage::ensureScratchSize(size_t samplesPerChannel)
+    {
+        if (m_planarInput.size() != static_cast<size_t>(m_numInputChannels))
+        {
+            m_planarInput.resize(m_numInputChannels);
+        }
+        for (size_t i = 0; i < m_planarInput.size(); ++i)
+        {
+            if (m_planarInput[i].size() < samplesPerChannel)
+            {
+                m_planarInput[i].resize(samplesPerChannel, 0.0f);
+            }
+        }
+
+        size_t numOut = m_numInputChannels * m_definitions.size();
+
+        if (m_planarOutput.size() != numOut)
+        {
+            m_planarOutput.resize(numOut);
+        }
+        for (size_t i = 0; i < m_planarOutput.size(); ++i)
+        {
+            if (m_planarOutput[i].size() < samplesPerChannel)
+            {
+                m_planarOutput[i].resize(samplesPerChannel, 0.0f);
+            }
+        }
+    }
+
+    void FilterBankStage::reset()
+    {
+        for (auto &ch : m_filters)
+        {
+            for (auto &filter : ch)
+            {
+                filter->reset();
+            }
+        }
+    }
+
+    Napi::Object FilterBankStage::serializeState(Napi::Env env) const
+    {
+        Napi::Object state = Napi::Object::New(env);
+        state.Set("type", getType());
+        state.Set("numInputChannels", m_numInputChannels);
+        state.Set("numBands", m_definitions.size());
+
+        // Serialize filter states as nested arrays: channels[bands[state]]
+        Napi::Array channels = Napi::Array::New(env, m_filters.size());
+        for (size_t ch = 0; ch < m_filters.size(); ++ch)
+        {
+            Napi::Array bands = Napi::Array::New(env, m_filters[ch].size());
+            for (size_t band = 0; band < m_filters[ch].size(); ++band)
+            {
+                const auto &filter = m_filters[ch][band];
+
+                Napi::Object filterState = Napi::Object::New(env);
+
+                // Get filter state (input and output history)
+                auto [inputHistory, outputHistory] = filter->getState();
+
+                // Serialize input history
+                Napi::Array inputArray = Napi::Array::New(env, inputHistory.size());
+                for (size_t i = 0; i < inputHistory.size(); ++i)
+                {
+                    inputArray.Set(i, inputHistory[i]);
+                }
+                filterState.Set("inputHistory", inputArray);
+
+                // Serialize output history
+                Napi::Array outputArray = Napi::Array::New(env, outputHistory.size());
+                for (size_t i = 0; i < outputHistory.size(); ++i)
+                {
+                    outputArray.Set(i, outputHistory[i]);
+                }
+                filterState.Set("outputHistory", outputArray);
+
+                bands.Set(band, filterState);
+            }
+            channels.Set(ch, bands);
+        }
+        state.Set("filterStates", channels);
+
+        return state;
+    }
+
+    void FilterBankStage::deserializeState(const Napi::Object &state)
+    {
+        if (!state.Has("filterStates"))
+        {
+            throw std::runtime_error("FilterBank: Missing filterStates in serialized data");
+        }
+
+        Napi::Array channels = state.Get("filterStates").As<Napi::Array>();
+        if (channels.Length() != m_filters.size())
+        {
+            throw std::runtime_error("FilterBank: Channel count mismatch in deserialization");
+        }
+
+        for (size_t ch = 0; ch < channels.Length(); ++ch)
+        {
+            Napi::Array bands = channels.Get(ch).As<Napi::Array>();
+            if (bands.Length() != m_filters[ch].size())
+            {
+                throw std::runtime_error("FilterBank: Band count mismatch in deserialization");
+            }
+
+            for (size_t band = 0; band < bands.Length(); ++band)
+            {
+                Napi::Object filterState = bands.Get(band).As<Napi::Object>();
+
+                // Deserialize input history
+                std::vector<float> inputHistory;
+                if (filterState.Has("inputHistory"))
+                {
+                    Napi::Array inputArray = filterState.Get("inputHistory").As<Napi::Array>();
+                    inputHistory.reserve(inputArray.Length());
+                    for (size_t i = 0; i < inputArray.Length(); ++i)
+                    {
+                        inputHistory.push_back(inputArray.Get(i).As<Napi::Number>().FloatValue());
+                    }
+                }
+
+                // Deserialize output history
+                std::vector<float> outputHistory;
+                if (filterState.Has("outputHistory"))
+                {
+                    Napi::Array outputArray = filterState.Get("outputHistory").As<Napi::Array>();
+                    outputHistory.reserve(outputArray.Length());
+                    for (size_t i = 0; i < outputArray.Length(); ++i)
+                    {
+                        outputHistory.push_back(outputArray.Get(i).As<Napi::Number>().FloatValue());
+                    }
+                }
+
+                // Restore filter state
+                m_filters[ch][band]->setState(inputHistory, outputHistory);
+            }
+        }
+    }
+
+    void FilterBankStage::serializeToon(toon::Serializer &serializer) const
+    {
+        // Serialize configuration
+        serializer.writeInt32(m_numInputChannels);
+        serializer.writeInt32(static_cast<int32_t>(m_definitions.size()));
+
+        // Serialize each filter's state
+        for (const auto &ch : m_filters)
+        {
+            for (const auto &filter : ch)
+            {
+                // Get filter state (input and output history)
+                auto [inputHistory, outputHistory] = filter->getState();
+
+                // Write input history
+                serializer.writeInt32(static_cast<int32_t>(inputHistory.size()));
+                for (float val : inputHistory)
+                {
+                    serializer.writeFloat(val);
+                }
+
+                // Write output history
+                serializer.writeInt32(static_cast<int32_t>(outputHistory.size()));
+                for (float val : outputHistory)
+                {
+                    serializer.writeFloat(val);
+                }
+            }
+        }
+    }
+
+    void FilterBankStage::deserializeToon(toon::Deserializer &deserializer)
+    {
+        // Read and validate configuration
+        int numChannels = deserializer.readInt32();
+        int32_t numBands = deserializer.readInt32();
+
+        if (numChannels != m_numInputChannels)
+        {
+            throw std::runtime_error("FilterBank TOON: Channel count mismatch");
+        }
+        if (static_cast<size_t>(numBands) != m_definitions.size())
+        {
+            throw std::runtime_error("FilterBank TOON: Band count mismatch");
+        }
+
+        // Restore each filter's state
+        for (auto &ch : m_filters)
+        {
+            for (auto &filter : ch)
+            {
+                // Read input history
+                int32_t inputSize = deserializer.readInt32();
+                std::vector<float> inputHistory;
+                inputHistory.reserve(inputSize);
+                for (int32_t i = 0; i < inputSize; ++i)
+                {
+                    inputHistory.push_back(deserializer.readFloat());
+                }
+
+                // Read output history
+                int32_t outputSize = deserializer.readInt32();
+                std::vector<float> outputHistory;
+                outputHistory.reserve(outputSize);
+                for (int32_t i = 0; i < outputSize; ++i)
+                {
+                    outputHistory.push_back(deserializer.readFloat());
+                }
+
+                // Restore filter state
+                filter->setState(inputHistory, outputHistory);
+            }
+        }
+    }
+
+} // namespace dsp::adapters

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
 {
@@ -153,6 +154,22 @@ namespace dsp::adapters
         Napi::Object state = Napi::Object::New(env);
         state.Set("filterType", m_isFir ? "fir" : "iir");
 
+        // --- SAVE COEFFICIENTS (New) ---
+        Napi::Array bArray = Napi::Array::New(env, m_bCoeffs.size());
+        for (size_t i = 0; i < m_bCoeffs.size(); ++i)
+        {
+            bArray.Set(i, Napi::Number::New(env, m_bCoeffs[i]));
+        }
+        state.Set("bCoeffs", bArray);
+
+        Napi::Array aArray = Napi::Array::New(env, m_aCoeffs.size());
+        for (size_t i = 0; i < m_aCoeffs.size(); ++i)
+        {
+            aArray.Set(i, Napi::Number::New(env, m_aCoeffs[i]));
+        }
+        state.Set("aCoeffs", aArray);
+        // --------------------------------
+
         if (m_isFir)
         {
             state.Set("numChannels", static_cast<uint32_t>(m_firFilters.size()));
@@ -287,4 +304,125 @@ namespace dsp::adapters
         }
     }
 
-} // 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);