dspx 1.1.6 → 1.2.4

package/src/native/DspPipeline.cc

@@ -882,9 +882,30 @@ namespace dsp
                 throw std::invalid_argument("PeakDetection: requires 'threshold' parameter");
             }
 
+            if (!params.Has("mode"))
+            {
+                throw std::invalid_argument("PeakDetection: requires 'mode' parameter");
+            }
+
             float threshold = params.Get("threshold").As<Napi::Number>().FloatValue();
 
-            return std::make_unique<dsp::adapters::PeakDetectionStage>(threshold);
+            // Optional mode and domain parameters
+            std::string mode = params.Has("mode")
+                                   ? params.Get("mode").As<Napi::String>().Utf8Value()
+                                   : "moving";
+            std::string domain = params.Has("domain")
+                                     ? params.Get("domain").As<Napi::String>().Utf8Value()
+                                     : "time";
+
+            // Get new optional windowSize and minPeakDistance
+            int windowSize = params.Has("windowSize")
+                                 ? params.Get("windowSize").As<Napi::Number>().Int32Value()
+                                 : 3;
+            int minPeakDistance = params.Has("minPeakDistance")
+                                      ? params.Get("minPeakDistance").As<Napi::Number>().Int32Value()
+                                      : 1;
+
+            return std::make_unique<dsp::adapters::PeakDetectionStage>(threshold, mode, domain, windowSize, minPeakDistance);
         };
 
         // ===================================================================
@@ -931,6 +952,37 @@ namespace dsp
 
             return std::make_unique<dsp::adapters::SnrStage>(window_size);
         };
+
+        // ===================================================================
+        // GENERIC FILTER RESTORATION (FIR & IIR)
+        // ===================================================================
+        auto filterFactory = [](const Napi::Object &params)
+        {
+            if (!params.Has("bCoeffs") || !params.Has("aCoeffs"))
+            {
+                throw std::invalid_argument("FilterStage: State missing 'bCoeffs' or 'aCoeffs'. Cannot reconstruct.");
+            }
+
+            Napi::Array bArray = params.Get("bCoeffs").As<Napi::Array>();
+            Napi::Array aArray = params.Get("aCoeffs").As<Napi::Array>();
+
+            std::vector<double> bCoeffs(bArray.Length());
+            for (uint32_t i = 0; i < bArray.Length(); ++i)
+            {
+                bCoeffs[i] = bArray.Get(i).As<Napi::Number>().DoubleValue();
+            }
+
+            std::vector<double> aCoeffs(aArray.Length());
+            for (uint32_t i = 0; i < aArray.Length(); ++i)
+            {
+                aCoeffs[i] = aArray.Get(i).As<Napi::Number>().DoubleValue();
+            }
+
+            return std::make_unique<dsp::adapters::FilterStage>(bCoeffs, aCoeffs);
+        };
+
+        m_stageFactories["filter:fir"] = filterFactory;
+        m_stageFactories["filter:iir"] = filterFactory;
     }
 
     /**
@@ -1319,18 +1371,21 @@ namespace dsp
         Napi::Function stringify = JSON.Get("stringify").As<Napi::Function>();
         return stringify.Call(JSON, {stateObj});
     }
-
     /**
-     * Load pipeline state from JSON string
-     * TypeScript retrieves this from Redis and passes it here
-     *
-     * Accepts: JSON string with pipeline configuration
+     * Load pipeline state from JSON string with Smart Merge Strategy.
+     * * Logic:
+     * 1. Iterate through the saved state history.
+     * 2. If a saved stage matches the current pipeline's next stage (by type),
+     * restore the state into the existing stage instance.
+     * 3. If there is a mismatch (e.g. saved has 'Rectify' but current has 'Filter'),
+     * dynamically create the 'Rectify' stage using the factory and insert it.
+     * 4. Finally, append any remaining stages from the current pipeline definition.
+     * * Result: The pipeline becomes a fusion of [Restorable Saved Stages] + [Current Stages]
      */
     Napi::Value DspPipeline::LoadState(const Napi::CallbackInfo &info)
     {
         Napi::Env env = info.Env();
 
-        // Validate input
         if (info.Length() < 1 || !info[0].IsString())
         {
             Napi::TypeError::New(env, "Expected state JSON string as first argument")
@@ -1342,12 +1397,10 @@ namespace dsp
 
         try
         {
-            // Parse JSON string using JavaScript's JSON.parse
             Napi::Object JSON = env.Global().Get("JSON").As<Napi::Object>();
             Napi::Function parse = JSON.Get("parse").As<Napi::Function>();
             Napi::Object stateObj = parse.Call(JSON, {Napi::String::New(env, stateJson)}).As<Napi::Object>();
 
-            // Validate state object has required fields
             if (!stateObj.Has("stages"))
             {
                 Napi::Error::New(env, "Invalid state: missing 'stages' field")
@@ -1355,34 +1408,86 @@ namespace dsp
                 return Napi::Boolean::New(env, false);
             }
 
-            // Get stages array
             Napi::Array stagesArray = stateObj.Get("stages").As<Napi::Array>();
-            uint32_t stageCount = stagesArray.Length();
+            uint32_t savedStageCount = stagesArray.Length();
 
-            // Validate stage count matches
-            if (stageCount != m_stages.size())
-            {
-                Napi::Error::New(env, "Stage count mismatch: expected " +
-                                          std::to_string(m_stages.size()) + " but got " + std::to_string(stageCount))
-                    .ThrowAsJavaScriptException();
-                return Napi::Boolean::New(env, false);
-            }
+            // Temporary container for the new merged pipeline structure
+            std::vector<std::unique_ptr<IDspStage>> newStages;
 
-            // Log restoration
-            std::cout << "Restoring pipeline state with " << stageCount << " stages" << std::endl;
+            // Index to track our position in the *current* pipeline (m_stages)
+            size_t currentIdx = 0;
 
-            // Restore each stage's state
-            for (uint32_t i = 0; i < stageCount; ++i)
+            for (uint32_t i = 0; i < savedStageCount; ++i)
             {
                 Napi::Object stageConfig = stagesArray.Get(i).As<Napi::Object>();
-                if (stageConfig.Has("state"))
+
+                if (!stageConfig.Has("type") || !stageConfig.Has("state"))
+                {
+                    continue;
+                }
+
+                std::string savedType = stageConfig.Get("type").As<Napi::String>().Utf8Value();
+                Napi::Object stageState = stageConfig.Get("state").As<Napi::Object>();
+
+                // 1. Try to match with the current pipeline stage
+                bool matched = false;
+                if (currentIdx < m_stages.size())
+                {
+                    // Check if types match (e.g. both are "movingAverage")
+                    if (std::string(m_stages[currentIdx]->getType()) == savedType)
+                    {
+                        // MATCH: Restore state into the existing stage instance
+                        // This preserves any specific config the user might have set on the current stage
+                        m_stages[currentIdx]->deserializeState(stageState);
+                        newStages.push_back(std::move(m_stages[currentIdx]));
+                        currentIdx++;
+                        matched = true;
+                    }
+                }
+
+                // 2. If mismatch, try to reconstruct the stage from the saved state
+                if (!matched)
                 {
-                    Napi::Object stageState = stageConfig.Get("state").As<Napi::Object>();
-                    m_stages[i]->deserializeState(stageState);
+                    auto it = m_stageFactories.find(savedType);
+                    if (it != m_stageFactories.end())
+                    {
+                        try
+                        {
+                            // Attempt to create stage using the state object as the config params.
+                            // (Assumes the state object contains necessary constructor args like 'windowSize')
+                            auto newStage = it->second(stageState);
+
+                            // Restore the full internal buffer state
+                            newStage->deserializeState(stageState);
+
+                            // Add to our new pipeline
+                            newStages.push_back(std::move(newStage));
+                        }
+                        catch (const std::exception &e)
+                        {
+                            // If reconstruction fails (e.g. missing params), log warning and skip
+                            std::cerr << "Warning: Failed to reconstruct stage " << savedType
+                                      << ": " << e.what() << std::endl;
+                        }
+                    }
+                    else
+                    {
+                        // Factory not found (e.g. generic FilterStage 'filter:fir' which requires explicit coefficients)
+                        std::cerr << "Warning: Unknown stage type '" << savedType
+                                  << "' in saved state (no factory available). Skipping." << std::endl;
+                    }
                 }
             }
 
-            std::cout << "State restoration complete!" << std::endl;
+            // 3. Append any remaining stages from the user's current pipeline definition
+            while (currentIdx < m_stages.size())
+            {
+                newStages.push_back(std::move(m_stages[currentIdx]));
+                currentIdx++;
+            }
+
+            // Replace the pipeline with the new merged structure
+            m_stages = std::move(newStages);
 
             return Napi::Boolean::New(env, true);
         }

package/src/native/adapters/FilterStage.cc

@@ -153,6 +153,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 +303,4 @@ namespace dsp::adapters
         }
     }
 
-} // namespace dsp::adapters
+} // namespace dsp::adapters

package/src/native/adapters/PeakDetectionStage.h

@@ -1,6 +1,7 @@
 #pragma once
 
 #include "../IDspStage.h"
+#include "../core/PeakDetection.h"
 #include <cmath>
 #include <stdexcept>
 #include <string>
@@ -11,34 +12,52 @@ namespace dsp::adapters
     /**
      * @brief Peak Detection Stage - Detects local maxima in a signal.
      *
-     * This stage identifies peaks (local maxima) in the input signal using a simple
-     * three-point comparison method. A peak is detected when:
-     * 1. The previous sample is greater than the sample before it
-     * 2. The previous sample is greater than the current sample
-     * 3. The previous sample exceeds the threshold
+     * ... (docs updated) ...
      *
-     * **Use Cases:**
-     * - Heart rate detection (R-peaks in ECG)
-     * - Event detection in sensor data
-     * - Tempo detection in audio
-     * - Spike detection in neural recordings
-     *
-     * **Output:**
-     * - 1.0 at peak locations
-     * - 0.0 elsewhere
-     *
-     * **State:** Maintains 2 previous samples per channel for continuity
+     * **Parameters:**
+     * - threshold: Minimum value for a peak.
+     * - mode: 'moving' (stateful) or 'batch' (stateless).
+     * - domain: 'time' or 'frequency'.
+     * - windowSize: (Batch mode only) Local neighborhood size (odd, >= 3). Default 3.
+     * - minPeakDistance: Minimum samples between peaks. Default 1.
      */
     class PeakDetectionStage : public IDspStage
     {
     public:
-        explicit PeakDetectionStage(float threshold)
-            : m_threshold(threshold), m_num_channels(0)
+        explicit PeakDetectionStage(float threshold, std::string mode = "moving", std::string domain = "time", int windowSize = 3, int minPeakDistance = 1)
+            : m_threshold(threshold),
+              m_mode(std::move(mode)),
+              m_domain(std::move(domain)),
+              m_windowSize(windowSize),
+              m_minPeakDistance(minPeakDistance),
+              m_num_channels(0)
         {
             if (threshold < 0.0f)
             {
                 throw std::invalid_argument("PeakDetection: threshold must be >= 0");
             }
+            if (m_mode != "moving" && m_mode != "batch")
+            {
+                throw std::invalid_argument("PeakDetection: mode must be 'moving' or 'batch'");
+            }
+            if (m_domain != "time" && m_domain != "frequency")
+            {
+                throw std::invalid_argument("PeakDetection: domain must be 'time' or 'frequency'");
+            }
+            if (windowSize < 3 || windowSize % 2 == 0)
+            {
+                throw std::invalid_argument("PeakDetection: windowSize must be an odd number >= 3");
+            }
+            if (minPeakDistance < 1)
+            {
+                throw std::invalid_argument("PeakDetection: minPeakDistance must be >= 1");
+            }
+
+            // In moving mode, we only support the 3-point window
+            if (m_mode == "moving")
+            {
+                m_windowSize = 3;
+            }
         }
 
         const char *getType() const override
@@ -48,77 +67,43 @@ namespace dsp::adapters
 
         void process(float *buffer, size_t numSamples, int numChannels, const float *timestamps = nullptr) override
         {
-            if (m_num_channels != numChannels || m_prev_sample.empty())
+            if (m_mode == "moving")
             {
-                m_num_channels = numChannels;
-                m_prev_sample.resize(numChannels, 0.0f);
-                m_prev_prev_sample.resize(numChannels, 0.0f);
+                // Note: processMoving implicitly uses m_windowSize = 3
+                processMoving(buffer, numSamples, numChannels);
             }
-
-            size_t samplesPerChannel = numSamples / numChannels;
-
-            for (int ch = 0; ch < numChannels; ++ch)
+            else // m_mode == "batch"
             {
-                float prev_prev = m_prev_prev_sample[ch];
-                float prev = m_prev_sample[ch];
-
-                for (size_t i = 0; i < samplesPerChannel; ++i)
-                {
-                    size_t idx = i * numChannels + ch;
-                    float current = buffer[idx];
-
-                    // Check if `prev` (the previous sample) was a peak
-                    // We can now confirm this since we have the current sample
-                    bool prev_is_peak = (prev > prev_prev) && (prev > current) && (prev >= m_threshold);
-
-                    if (i > 0)
-                    {
-                        // Write peak marker BACK to the previous sample's position
-                        buffer[idx - numChannels] = prev_is_peak ? 1.0f : 0.0f;
-                    }
-                    else
-                    {
-                        // For the first sample, we mark it if the prev (from previous process call) was a peak
-                        buffer[idx] = prev_is_peak ? 1.0f : 0.0f;
-                    }
-
-                    // Shift history forward
-                    prev_prev = prev;
-                    prev = current;
-                }
-
-                // The last sample in the buffer can't be confirmed as a peak yet
-                // (we need to see the next sample), so set it to 0
-                // BUT: Don't overwrite if there's only 1 sample and we just wrote the pending result at i==0
-                if (samplesPerChannel > 1)
-                {
-                    buffer[(samplesPerChannel - 1) * numChannels + ch] = 0.0f;
-                }
-
-                // Save state for next process call
-                m_prev_prev_sample[ch] = prev_prev;
-                m_prev_sample[ch] = prev;
+                processBatch(buffer, numSamples, numChannels);
             }
         }
+
         Napi::Object serializeState(Napi::Env env) const override
         {
             Napi::Object state = Napi::Object::New(env);
             state.Set("threshold", m_threshold);
             state.Set("numChannels", m_num_channels);
+            state.Set("mode", m_mode);
+            state.Set("domain", m_domain);
+            state.Set("windowSize", m_windowSize);
+            state.Set("minPeakDistance", m_minPeakDistance);
 
-            if (!m_prev_sample.empty())
+            if (m_mode == "moving" && !m_prev_sample.empty())
             {
                 Napi::Array prevArray = Napi::Array::New(env, m_prev_sample.size());
                 Napi::Array prevPrevArray = Napi::Array::New(env, m_prev_prev_sample.size());
+                Napi::Array cooldownArray = Napi::Array::New(env, m_peakCooldown.size());
 
                 for (size_t i = 0; i < m_prev_sample.size(); ++i)
                 {
                     prevArray.Set(i, m_prev_sample[i]);
                     prevPrevArray.Set(i, m_prev_prev_sample[i]);
+                    cooldownArray.Set(i, m_peakCooldown[i]);
                 }
 
                 state.Set("prevSample", prevArray);
                 state.Set("prevPrevSample", prevPrevArray);
+                state.Set("peakCooldown", cooldownArray);
             }
 
             return state;
@@ -130,19 +115,30 @@ namespace dsp::adapters
                 m_threshold = state.Get("threshold").As<Napi::Number>().FloatValue();
             if (state.Has("numChannels"))
                 m_num_channels = state.Get("numChannels").As<Napi::Number>().Int32Value();
+            if (state.Has("mode"))
+                m_mode = state.Get("mode").As<Napi::String>().Utf8Value();
+            if (state.Has("domain"))
+                m_domain = state.Get("domain").As<Napi::String>().Utf8Value();
+            if (state.Has("windowSize"))
+                m_windowSize = state.Get("windowSize").As<Napi::Number>().Int32Value();
+            if (state.Has("minPeakDistance"))
+                m_minPeakDistance = state.Get("minPeakDistance").As<Napi::Number>().Int32Value();
 
-            if (state.Has("prevSample"))
+            if (m_mode == "moving" && state.Has("prevSample"))
             {
                 Napi::Array prevArray = state.Get("prevSample").As<Napi::Array>();
                 Napi::Array prevPrevArray = state.Get("prevPrevSample").As<Napi::Array>();
+                Napi::Array cooldownArray = state.Get("peakCooldown").As<Napi::Array>();
 
                 m_prev_sample.clear();
                 m_prev_prev_sample.clear();
+                m_peakCooldown.clear();
 
                 for (size_t i = 0; i < prevArray.Length(); ++i)
                 {
                     m_prev_sample.push_back(prevArray.Get(i).As<Napi::Number>().FloatValue());
                     m_prev_prev_sample.push_back(prevPrevArray.Get(i).As<Napi::Number>().FloatValue());
+                    m_peakCooldown.push_back(cooldownArray.Get(i).As<Napi::Number>().Int32Value());
                 }
             }
         }
@@ -151,15 +147,132 @@ namespace dsp::adapters
         {
             std::fill(m_prev_sample.begin(), m_prev_sample.end(), 0.0f);
             std::fill(m_prev_prev_sample.begin(), m_prev_prev_sample.end(), 0.0f);
+            std::fill(m_peakCooldown.begin(), m_peakCooldown.end(), 0);
         }
 
         bool isResizing() const override { return false; }
 
     private:
+        /**
+         * @brief Stateful ("moving") peak detection processing (WindowSize = 3 only).
+         */
+        void processMoving(float *buffer, size_t numSamples, int numChannels)
+        {
+            if (m_num_channels != numChannels || m_prev_sample.empty())
+            {
+                m_num_channels = numChannels;
+                m_prev_sample.resize(numChannels, 0.0f);
+                m_prev_prev_sample.resize(numChannels, 0.0f);
+                m_peakCooldown.resize(numChannels, 0); // Resize cooldown state
+            }
+
+            size_t samplesPerChannel = numSamples / numChannels;
+
+            for (int ch = 0; ch < numChannels; ++ch)
+            {
+                float prev_prev = m_prev_prev_sample[ch];
+                float prev = m_prev_sample[ch];
+                int &cooldown = m_peakCooldown[ch]; // Get reference to cooldown counter
+
+                for (size_t i = 0; i < samplesPerChannel; ++i)
+                {
+                    size_t idx = i * numChannels + ch;
+                    float current = buffer[idx];
+
+                    // Decrement cooldown if active
+                    if (cooldown > 0)
+                    {
+                        cooldown--;
+                    }
+
+                    // Check if `prev` (the previous sample) was a peak
+                    bool prev_is_peak = (cooldown == 0) && // Must not be in cooldown
+                                        (prev > prev_prev) &&
+                                        (prev > current) &&
+                                        (prev >= m_threshold);
+
+                    if (i > 0)
+                    {
+                        buffer[idx - numChannels] = prev_is_peak ? 1.0f : 0.0f;
+                    }
+                    else
+                    {
+                        buffer[idx] = prev_is_peak ? 1.0f : 0.0f;
+                    }
+
+                    // If we found a peak, reset the cooldown
+                    if (prev_is_peak)
+                    {
+                        cooldown = m_minPeakDistance - 1;
+                    }
+
+                    // Shift history forward
+                    prev_prev = prev;
+                    prev = current;
+                }
+
+                if (samplesPerChannel > 1)
+                {
+                    buffer[(samplesPerChannel - 1) * numChannels + ch] = 0.0f;
+                }
+
+                m_prev_prev_sample[ch] = prev_prev;
+                m_prev_sample[ch] = prev;
+            }
+        }
+
+        /**
+         * @brief Stateless ("batch") peak detection processing.
+         */
+        void processBatch(float *buffer, size_t numSamples, int numChannels)
+        {
+            if (m_planar_input.size() < numSamples / numChannels)
+            {
+                m_planar_input.resize(numSamples / numChannels);
+                m_planar_output.resize(numSamples / numChannels);
+            }
+
+            size_t samplesPerChannel = numSamples / numChannels;
+
+            // Select the correct core function
+            void (*peak_func)(const float *, float *, size_t, float, int, int) =
+                (m_domain == "frequency")
+                    ? dsp::core::find_freq_peaks_batch
+                    : dsp::core::find_peaks_batch_delayed;
+
+            for (int ch = 0; ch < numChannels; ++ch)
+            {
+                for (size_t i = 0; i < samplesPerChannel; ++i)
+                {
+                    m_planar_input[i] = buffer[i * numChannels + ch];
+                }
+
+                // Process using the core function, passing all parameters
+                peak_func(m_planar_input.data(), m_planar_output.data(), samplesPerChannel, m_threshold, m_windowSize, m_minPeakDistance);
+
+                for (size_t i = 0; i < samplesPerChannel; ++i)
+                {
+                    buffer[i * numChannels + ch] = m_planar_output[i];
+                }
+            }
+        }
+
+        // --- Member Variables ---
         float m_threshold;
+        std::string m_mode;
+        std::string m_domain;
+        int m_windowSize;
+        int m_minPeakDistance;
         int m_num_channels;
+
+        // State for "moving" mode
         std::vector<float> m_prev_sample;
         std::vector<float> m_prev_prev_sample;
+        std::vector<int> m_peakCooldown; // Cooldown counter per channel
+
+        // Temporary planar buffers for "batch" mode
+        std::vector<float> m_planar_input;
+        std::vector<float> m_planar_output;
     };
 
-} // namespace dsp::adapters
+} // namespace dsp::adapters

package/src/native/adapters/RmsStage.h

@@ -152,7 +152,7 @@ namespace dsp::adapters
                     {
                         actualSumOfSquares += val * val;
                     }
-                    const float tolerance = 0.0001f * std::max(1.0f, std::abs(actualSumOfSquares));
+                    const float tolerance = 0.001f * std::max(1.0f, std::abs(actualSumOfSquares));
                     if (std::abs(runningSumOfSquares - actualSumOfSquares) > tolerance)
                     {
                         throw std::runtime_error(

package/src/native/adapters/VarianceStage.h

@@ -165,7 +165,7 @@ namespace dsp::adapters
                             std::to_string(runningSum));
                     }
 
-                    const float toleranceSq = 0.0001f * std::max(1.0f, std::abs(actualSumOfSquares));
+                    const float toleranceSq = 0.001f * std::max(1.0f, std::abs(actualSumOfSquares));
                     if (std::abs(runningSumOfSquares - actualSumOfSquares) > toleranceSq)
                     {
                         throw std::runtime_error(

package/src/native/adapters/ZScoreNormalizeStage.h

@@ -170,7 +170,7 @@ namespace dsp::adapters
                             std::to_string(runningSum));
                     }
 
-                    const float toleranceSq = 0.0001f * std::max(1.0f, std::abs(actualSumOfSquares));
+                    const float toleranceSq = 0.001f * std::max(1.0f, std::abs(actualSumOfSquares));
                     if (std::abs(runningSumOfSquares - actualSumOfSquares) > toleranceSq)
                     {
                         throw std::runtime_error(