dspx 0.1.1-alpha.0

package/src/native/adapters/MovingAverageStage.h

@@ -0,0 +1,306 @@
+#pragma once
+
+#include "../IDspStage.h"
+#include "../core/MovingAverageFilter.h"
+#include "../utils/SimdOps.h"
+#include <vector>
+#include <stdexcept>
+#include <cmath>
+#include <string>
+#include <algorithm>
+#include <numeric> // For std::accumulate
+
+namespace dsp::adapters
+{
+    enum class AverageMode
+    {
+        Batch,
+        Moving
+    };
+
+    class MovingAverageStage : public IDspStage
+    {
+    public:
+        /**
+         * @brief Constructs a new Moving Average Stage.
+         * @param mode The averaging mode (Batch or Moving).
+         * @param window_size The window size in samples (0 if using duration-based).
+         * @param window_duration_ms The window duration in milliseconds (0 if using size-based).
+         */
+        explicit MovingAverageStage(AverageMode mode, size_t window_size = 0, double window_duration_ms = 0.0)
+            : m_mode(mode),
+              m_window_size(window_size),
+              m_window_duration_ms(window_duration_ms),
+              m_is_initialized(window_size > 0) // Initialized if windowSize was provided
+        {
+            if (m_mode == AverageMode::Moving && window_size == 0 && window_duration_ms == 0.0)
+            {
+                throw std::invalid_argument("MovingAverage: either window size or window duration must be greater than 0 for 'moving' mode");
+            }
+        }
+
+        // Return the type identifier for this stage
+        const char *getType() const override
+        {
+            return "movingAverage";
+        }
+
+        // This is the implementation of the interface method
+        void process(float *buffer, size_t numSamples, int numChannels, const float *timestamps = nullptr) override
+        {
+            if (m_mode == AverageMode::Batch)
+            {
+                processBatch(buffer, numSamples, numChannels);
+            }
+            else // AverageMode::Moving
+            {
+                processMoving(buffer, numSamples, numChannels, timestamps);
+            }
+        }
+
+        // Serialize the stage's state to a Napi::Object
+        Napi::Object serializeState(Napi::Env env) const override
+        {
+            Napi::Object state = Napi::Object::New(env);
+            std::string modeStr = (m_mode == AverageMode::Moving) ? "moving" : "batch";
+            state.Set("mode", modeStr);
+
+            if (m_mode == AverageMode::Moving)
+            {
+                state.Set("windowSize", static_cast<uint32_t>(m_window_size));
+                state.Set("numChannels", static_cast<uint32_t>(m_filters.size()));
+
+                // Serialize each channel's filter state
+                Napi::Array channelsArray = Napi::Array::New(env, m_filters.size());
+                for (size_t i = 0; i < m_filters.size(); ++i)
+                {
+                    Napi::Object channelState = Napi::Object::New(env);
+
+                    // Get the filter's internal state
+                    auto [bufferData, runningSum] = m_filters[i].getState();
+
+                    // Convert buffer data to JavaScript array
+                    Napi::Array bufferArray = Napi::Array::New(env, bufferData.size());
+                    for (size_t j = 0; j < bufferData.size(); ++j)
+                    {
+                        bufferArray.Set(j, Napi::Number::New(env, bufferData[j]));
+                    }
+
+                    channelState.Set("buffer", bufferArray);
+                    channelState.Set("runningSum", Napi::Number::New(env, runningSum));
+
+                    channelsArray.Set(static_cast<uint32_t>(i), channelState);
+                }
+                state.Set("channels", channelsArray);
+            }
+
+            return state;
+        }
+
+        // Deserialize and restore the stage's state
+        void deserializeState(const Napi::Object &state) override
+        {
+            std::string modeStr = state.Get("mode").As<Napi::String>().Utf8Value();
+            AverageMode newMode = (modeStr == "moving") ? AverageMode::Moving : AverageMode::Batch;
+
+            if (newMode != m_mode)
+            {
+                throw std::runtime_error("MovingAverage mode mismatch during deserialization");
+            }
+
+            if (m_mode == AverageMode::Moving)
+            {
+                // Get window size and validate
+                size_t windowSize = state.Get("windowSize").As<Napi::Number>().Uint32Value();
+                if (windowSize != m_window_size)
+                {
+                    throw std::runtime_error("Window size mismatch during deserialization");
+                }
+
+                // Get number of channels
+                uint32_t numChannels = state.Get("channels").As<Napi::Array>().Length();
+
+                // Recreate filters
+                m_filters.clear();
+                for (uint32_t i = 0; i < numChannels; ++i)
+                {
+                    m_filters.emplace_back(m_window_size);
+                }
+
+                // Restore each channel's state
+                Napi::Array channelsArray = state.Get("channels").As<Napi::Array>();
+                for (uint32_t i = 0; i < numChannels; ++i)
+                {
+                    Napi::Object channelState = channelsArray.Get(i).As<Napi::Object>();
+
+                    // Get buffer data
+                    Napi::Array bufferArray = channelState.Get("buffer").As<Napi::Array>();
+                    std::vector<float> bufferData;
+                    bufferData.reserve(bufferArray.Length());
+                    for (uint32_t j = 0; j < bufferArray.Length(); ++j)
+                    {
+                        bufferData.push_back(bufferArray.Get(j).As<Napi::Number>().FloatValue());
+                    }
+
+                    // Get running sum
+                    float runningSum = channelState.Get("runningSum").As<Napi::Number>().FloatValue();
+
+                    // Validate that runningSum matches the actual sum of buffer values
+                    float actualSum = 0.0f;
+                    for (const auto &val : bufferData)
+                    {
+                        actualSum += val;
+                    }
+
+                    // Allow small floating-point tolerance
+                    const float tolerance = 0.0001f * std::max(1.0f, std::abs(actualSum));
+                    if (std::abs(runningSum - actualSum) > tolerance)
+                    {
+                        throw std::runtime_error(
+                            "Running sum validation failed: expected " +
+                            std::to_string(actualSum) + " but got " +
+                            std::to_string(runningSum));
+                    }
+
+                    // Restore the filter's state
+                    m_filters[i].setState(bufferData, runningSum);
+                }
+            }
+        }
+
+        // Reset all filters to initial state
+        void reset() override
+        {
+            for (auto &filter : m_filters)
+            {
+                filter.clear();
+            }
+        }
+
+    private:
+        /**
+         * @brief Statelessly calculates the average for each channel
+         * and overwrites all samples in that channel with the result.
+         * Uses SIMD-optimized summation for better performance.
+         */
+        void processBatch(float *buffer, size_t numSamples, int numChannels)
+        {
+            for (int c = 0; c < numChannels; ++c)
+            {
+                size_t numSamplesPerChannel = numSamples / numChannels;
+                if (numSamplesPerChannel == 0)
+                    continue;
+
+                double sum = 0.0;
+
+                // For single-channel or well-aligned data, use SIMD sum
+                if (numChannels == 1)
+                {
+                    // Fast path: contiguous memory
+                    sum = dsp::simd::sum(buffer, numSamples);
+                }
+                else
+                {
+                    // Multi-channel: strided access (compiler can still auto-vectorize)
+                    for (size_t i = c; i < numSamples; i += numChannels)
+                    {
+                        sum += static_cast<double>(buffer[i]);
+                    }
+                }
+
+                // Calculate average
+                float average = static_cast<float>(sum / numSamplesPerChannel);
+
+                // Fill this channel's buffer with the single average value
+                // For single channel, memset equivalent is very fast
+                for (size_t i = c; i < numSamples; i += numChannels)
+                {
+                    buffer[i] = average;
+                }
+            }
+        }
+
+        /**
+         * @brief Statefully processes samples using the moving average filters.
+         * @param buffer The interleaved audio buffer.
+         * @param numSamples The total number of samples.
+         * @param numChannels The number of channels.
+         * @param timestamps Optional timestamps for deriving sample rate on first call.
+         */
+        void processMoving(float *buffer, size_t numSamples, int numChannels, const float *timestamps)
+        {
+            // Determine if we're in time-aware mode (pure duration without size, or both)
+            bool useTimeAware = (m_window_duration_ms > 0.0) && timestamps != nullptr;
+
+            // Lazy initialization: convert windowDuration to windowSize if needed
+            if (!m_is_initialized && m_window_duration_ms > 0.0)
+            {
+                if (timestamps != nullptr && numSamples > 1)
+                {
+                    // Estimate sample rate from timestamps
+                    size_t samples_to_check = std::min(numSamples, size_t(10));
+                    double total_time_ms = timestamps[samples_to_check - 1] - timestamps[0];
+                    double avg_sample_period_ms = total_time_ms / (samples_to_check - 1);
+                    double estimated_sample_rate = 1000.0 / avg_sample_period_ms; // Hz
+
+                    // Calculate window size: (duration_ms / 1000) * sample_rate
+                    // For time-aware mode, use 3x the estimated size to ensure we never
+                    // run out of buffer space before time-based expiration happens
+                    size_t estimated_size = static_cast<size_t>((m_window_duration_ms / 1000.0) * estimated_sample_rate);
+                    m_window_size = std::max(size_t(1), estimated_size * 3);
+
+                    m_is_initialized = true;
+                }
+                else
+                {
+                    throw std::runtime_error("MovingAverage: windowDuration was set, but timestamps are not available to derive sample rate");
+                }
+            }
+
+            // Lazily initialize our filters, one for each channel
+            if (m_filters.size() != static_cast<size_t>(numChannels))
+            {
+                m_filters.clear();
+                for (int i = 0; i < numChannels; ++i)
+                {
+                    if (useTimeAware)
+                    {
+                        // Create time-aware filter
+                        m_filters.emplace_back(m_window_size, m_window_duration_ms);
+                    }
+                    else
+                    {
+                        // Create regular filter
+                        m_filters.emplace_back(m_window_size);
+                    }
+                }
+            }
+
+            // Process the buffer sample by sample, de-interleaving
+            for (size_t i = 0; i < numSamples; ++i)
+            {
+                int channel = i % numChannels;
+                size_t sample_index = i / numChannels;
+
+                if (useTimeAware)
+                {
+                    // Use time-aware processing
+                    buffer[i] = m_filters[channel].addSampleWithTimestamp(buffer[i], timestamps[sample_index]);
+                }
+                else
+                {
+                    // Use sample-count processing
+                    buffer[i] = m_filters[channel].addSample(buffer[i]);
+                }
+            }
+        }
+
+        AverageMode m_mode;
+        size_t m_window_size;
+        double m_window_duration_ms;
+        bool m_is_initialized;
+        // We need a separate filter instance for each channel's state
+        std::vector<dsp::core::MovingAverageFilter<float>> m_filters;
+    };
+
+} // namespace dsp::adapters

package/src/native/adapters/RectifyStage.h

@@ -0,0 +1,88 @@
+#pragma once
+#include "../IDspStage.h"
+#include "../utils/SimdOps.h"
+#include <cmath>
+#include <stdexcept>
+
+namespace dsp::adapters
+{
+    enum class RectifyMode
+    {
+        FullWave,
+        HalfWave
+    };
+
+    class RectifyStage : public IDspStage
+    {
+    public:
+        /**
+         * @brief Constructs a new Rectify Stage.
+         * @param mode The rectification mode (FULL_WAVE or HALF_WAVE).
+         */
+        explicit RectifyStage(RectifyMode mode = RectifyMode::FullWave)
+            : m_mode(mode) {}
+
+        // Delete copy/move semantics
+        RectifyStage(const RectifyStage &) = delete;
+        RectifyStage &operator=(const RectifyStage &) = delete;
+        RectifyStage(RectifyStage &&) noexcept = delete;
+        RectifyStage &operator=(RectifyStage &&) noexcept = delete;
+
+        /**
+         * @brief Returns the type identifier of this stage.
+         * @return A string identifying the stage type ("rectify").
+         */
+        const char *getType() const override
+        {
+            return "rectify";
+        }
+
+        /**
+         * @brief Applies in-place rectification based on the configured mode.
+         * Uses SIMD-optimized operations for better performance.
+         */
+        void process(float *buffer, size_t numSamples, int /*numChannels*/, const float * /*timestamps*/ = nullptr) override
+        {
+            // Use SIMD-optimized operations for best performance
+            switch (m_mode)
+            {
+            case RectifyMode::FullWave:
+                dsp::simd::abs_inplace(buffer, numSamples);
+                break;
+            case RectifyMode::HalfWave:
+                dsp::simd::max_zero_inplace(buffer, numSamples);
+                break;
+            }
+        }
+
+        /**
+         * @brief Serializes the stage's configured mode.
+         */
+        Napi::Object serializeState(Napi::Env env) const override
+        {
+            Napi::Object state = Napi::Object::New(env);
+            state.Set("type", "rectify");
+            state.Set("mode", m_mode == RectifyMode::FullWave ? "full" : "half");
+            return state;
+        }
+
+        /**
+         * @brief Deserializes and restores the stage's configured mode.
+         */
+        void deserializeState(const Napi::Object &state) override
+        {
+            std::string mode = state.Get("mode").As<Napi::String>().Utf8Value();
+            if (mode == "full")
+                m_mode = RectifyMode::FullWave;
+            else if (mode == "half")
+                m_mode = RectifyMode::HalfWave;
+            else
+                throw std::runtime_error("Invalid rectify mode");
+        }
+
+        void reset() override {} // No internal buffers
+
+    private:
+        RectifyMode m_mode;
+    };
+} // namespace dsp::adapters

package/src/native/adapters/ResamplerStage.h

@@ -0,0 +1,238 @@
+/**
+ * ResamplerStage.h
+ *
+ * Rational resampling by factor L/M for arbitrary sample rate conversion.
+ * Combines interpolation (upsample by L) and decimation (downsample by M)
+ * using efficient polyphase FIR filtering.
+ *
+ * Algorithm:
+ * 1. Upsample by L (insert zeros)
+ * 2. Apply single combined anti-aliasing/anti-imaging filter
+ * 3. Downsample by M (keep every M-th sample)
+ *
+ * The filter cutoff is min(π/L, π/M) to satisfy both requirements.
+ *
+ * Example: Resample from 44.1 kHz to 48 kHz
+ * - L/M = 48000/44100 = 160/147 (after GCD reduction)
+ * - Upsample by 160, downsample by 147
+ */
+
+#pragma once
+
+#include "../IDspStage.h"
+#include "../core/FirFilter.h"
+#include <algorithm>
+#include <cmath>
+#include <numeric>
+#include <stdexcept>
+#include <vector>
+
+namespace dsp
+{
+
+    /**
+     * Resampler stage: Change sample rate by rational factor L/M
+     * Output rate = Input rate * (L/M)
+     */
+    class ResamplerStage : public IDspStage
+    {
+    public:
+        /**
+         * Construct resampler
+         * @param upFactor Interpolation factor L
+         * @param downFactor Decimation factor M
+         * @param order FIR filter order (must be odd)
+         * @param sampleRate Input sample rate in Hz
+         */
+        ResamplerStage(int upFactor, int downFactor, int order, double sampleRate)
+            : L_(upFactor), M_(downFactor), filterOrder_(order), inputSampleRate_(sampleRate), phaseAccumulator_(0)
+        {
+            if (upFactor < 1)
+            {
+                throw std::invalid_argument("Interpolation factor L must be >= 1");
+            }
+            if (downFactor < 1)
+            {
+                throw std::invalid_argument("Decimation factor M must be >= 1");
+            }
+            if (order < 3 || order % 2 == 0)
+            {
+                throw std::invalid_argument("Filter order must be odd and >= 3");
+            }
+
+            // Reduce L/M to simplest form
+            int gcd = std::gcd(L_, M_);
+            L_ /= gcd;
+            M_ /= gcd;
+
+            // Calculate intermediate and output sample rates
+            intermediateSampleRate_ = inputSampleRate_ * L_;
+            outputSampleRate_ = inputSampleRate_ * L_ / M_;
+
+            // Design combined anti-aliasing/anti-imaging filter
+            // Cutoff at min(Fs_in/2, Fs_out/2) to prevent both aliasing and imaging
+            double cutoffFreq = std::min(inputSampleRate_ / 2.0, outputSampleRate_ / 2.0);
+
+            // Create polyphase filter bank
+            designPolyphaseFilter(cutoffFreq);
+
+            // State buffer for filtering
+            stateBuffer_.resize(filterOrder_, 0.0f);
+            stateIndex_ = 0;
+        }
+
+        /**
+         * Process input samples and produce resampled output
+         * Output size ≈ input size * (L/M)
+         */
+        void process(const float *input, size_t inputSize,
+                     float *output, size_t &outputSize) override
+        {
+            outputSize = 0;
+
+            if (inputSize == 0)
+            {
+                return;
+            }
+
+            // Process each input sample
+            for (size_t i = 0; i < inputSize; ++i)
+            {
+                // Add input sample to state buffer
+                stateBuffer_[stateIndex_] = input[i];
+                stateIndex_ = (stateIndex_ + 1) % filterOrder_;
+
+                // Advance phase accumulator
+                phaseAccumulator_ += L_;
+
+                // Generate output samples when phase crosses M boundaries
+                while (phaseAccumulator_ >= M_)
+                {
+                    // Calculate which polyphase filter to use
+                    int phase = (phaseAccumulator_ - M_) % L_;
+
+                    // Apply polyphase filter
+                    float sum = 0.0f;
+                    for (int tap = 0; tap < filterOrder_; ++tap)
+                    {
+                        int bufferIdx = (stateIndex_ - 1 - tap + filterOrder_) % filterOrder_;
+                        int coeffIdx = phase + tap * L_;
+
+                        if (coeffIdx < static_cast<int>(polyphaseCoeffs_.size()))
+                        {
+                            sum += stateBuffer_[bufferIdx] * polyphaseCoeffs_[coeffIdx];
+                        }
+                    }
+
+                    output[outputSize++] = sum * L_; // Gain correction for interpolation
+                    phaseAccumulator_ -= M_;
+                }
+            }
+        }
+
+        void reset() override
+        {
+            std::fill(stateBuffer_.begin(), stateBuffer_.end(), 0.0f);
+            stateIndex_ = 0;
+            phaseAccumulator_ = 0;
+        }
+
+        std::string getName() const override
+        {
+            return "Resampler(L=" + std::to_string(L_) + ",M=" + std::to_string(M_) + ")";
+        }
+
+        /**
+         * Get interpolation factor (reduced)
+         */
+        int getUpFactor() const
+        {
+            return L_;
+        }
+
+        /**
+         * Get decimation factor (reduced)
+         */
+        int getDownFactor() const
+        {
+            return M_;
+        }
+
+        /**
+         * Get output sample rate
+         */
+        double getOutputSampleRate() const
+        {
+            return outputSampleRate_;
+        }
+
+        /**
+         * Get conversion ratio L/M
+         */
+        double getRatio() const
+        {
+            return static_cast<double>(L_) / static_cast<double>(M_);
+        }
+
+    private:
+        /**
+         * Design polyphase filter bank for combined resampling
+         */
+        void designPolyphaseFilter(double cutoffFreq)
+        {
+            const int M = filterOrder_;
+            const int totalTaps = M * L_;
+
+            polyphaseCoeffs_.resize(totalTaps);
+
+            const int center = totalTaps / 2;
+            const double fc = cutoffFreq / intermediateSampleRate_;
+            const double omega_c = 2.0 * M_PI * fc;
+
+            // Design prototype filter at intermediate rate
+            for (int n = 0; n < totalTaps; ++n)
+            {
+                // Sinc function
+                double t = n - center;
+                double sinc_val;
+                if (std::abs(t) < 1e-10)
+                {
+                    sinc_val = omega_c / M_PI;
+                }
+                else
+                {
+                    sinc_val = std::sin(omega_c * t) / (M_PI * t);
+                }
+
+                // Hamming window
+                double window = 0.54 - 0.46 * std::cos(2.0 * M_PI * n / (totalTaps - 1));
+
+                polyphaseCoeffs_[n] = static_cast<float>(sinc_val * window);
+            }
+
+            // Normalize coefficients
+            float sum = 0.0f;
+            for (float c : polyphaseCoeffs_)
+            {
+                sum += c;
+            }
+            for (float &c : polyphaseCoeffs_)
+            {
+                c /= sum;
+            }
+        }
+
+        int L_; // Interpolation factor (reduced)
+        int M_; // Decimation factor (reduced)
+        int filterOrder_;
+        double inputSampleRate_;
+        double intermediateSampleRate_;
+        double outputSampleRate_;
+
+        std::vector<float> stateBuffer_;
+        std::vector<float> polyphaseCoeffs_;
+        size_t stateIndex_;
+        int phaseAccumulator_; // Tracks position in resampling cycle
+    };
+
+} // namespace dsp