dspx 1.2.3 → 1.3.0

package/src/native/core/CumulativeMovingAverageFilter.h

@@ -0,0 +1,123 @@
+#pragma once
+#include "Policies.h"
+#include <vector>
+#include <stdexcept>
+
+namespace dsp::core
+{
+    /**
+     * @brief Implements a Cumulative Moving Average (CMA) filter.
+     *
+     * CMA is the average of all samples seen since initialization.
+     * Formula: CMA(n) = (CMA(n-1) * (n-1) + value(n)) / n
+     *          or: CMA(n) = sum(values[1..n]) / n
+     *
+     * Unlike simple moving average (SMA), CMA considers ALL historical data:
+     * - SMA: Uses fixed window of recent N samples
+     * - CMA: Uses all samples from start to current
+     *
+     * Properties:
+     * - Memory-efficient: Only stores running sum and count
+     * - Stable convergence: Influence of new samples decreases over time
+     * - No window size needed: Adapts to any data length
+     *
+     * Use cases:
+     * - Long-term averages where all history matters
+     * - Baseline estimation from calibration data
+     * - Online mean estimation for statistics
+     *
+     * @tparam T The numeric type of the samples (e.g., float, double).
+     */
+    template <typename T>
+    class CumulativeMovingAverageFilter
+    {
+    public:
+        /**
+         * @brief Constructs a new CMA Filter.
+         */
+        CumulativeMovingAverageFilter()
+            : m_policy()
+        {
+        }
+
+        // Delete copy constructor and copy assignment
+        CumulativeMovingAverageFilter(const CumulativeMovingAverageFilter &) = delete;
+        CumulativeMovingAverageFilter &operator=(const CumulativeMovingAverageFilter &) = delete;
+
+        // Enable move semantics
+        CumulativeMovingAverageFilter(CumulativeMovingAverageFilter &&) noexcept = default;
+        CumulativeMovingAverageFilter &operator=(CumulativeMovingAverageFilter &&) noexcept = default;
+
+        /**
+         * @brief Adds a new sample and updates the CMA.
+         * @param newValue The new sample value.
+         * @return T The updated CMA value.
+         */
+        T addSample(T newValue)
+        {
+            m_policy.onAdd(newValue);
+            return m_policy.getResult(0); // Window count parameter unused for CMA
+        }
+
+        /**
+         * @brief Process array of samples in batch (optimized for throughput).
+         *
+         * @param input Input array of samples
+         * @param output Output array (same size as input)
+         * @param length Number of samples to process
+         */
+        void processArray(const T *input, T *output, size_t length)
+        {
+            for (size_t i = 0; i < length; ++i)
+            {
+                output[i] = addSample(input[i]);
+            }
+        }
+
+        /**
+         * @brief Gets the current CMA value.
+         * @return T The cumulative moving average.
+         */
+        T getCma() const { return m_policy.getResult(0); }
+
+        /**
+         * @brief Gets the number of samples processed.
+         * @return size_t The total count of samples.
+         */
+        size_t getCount() const { return m_policy.getCount(); }
+
+        /**
+         * @brief Clears the CMA state (resets to zero).
+         */
+        void clear() { m_policy.clear(); }
+
+        /**
+         * @brief Checks if any samples have been processed.
+         * @return true if count > 0, false otherwise.
+         */
+        bool hasData() const { return m_policy.getCount() > 0; }
+
+        /**
+         * @brief Exports the filter's internal state.
+         * @return A pair containing the running sum and sample count.
+         */
+        std::pair<T, size_t> getState() const
+        {
+            return m_policy.getState();
+        }
+
+        /**
+         * @brief Restores the filter's internal state.
+         * @param sum The running sum to restore.
+         * @param count The sample count to restore.
+         */
+        void setState(T sum, size_t count)
+        {
+            m_policy.setState(sum, count);
+        }
+
+    private:
+        CmaPolicy<T> m_policy;
+    };
+
+} // namespace dsp::core

package/src/native/core/ExponentialMovingAverageFilter.h

@@ -0,0 +1,129 @@
+#pragma once
+#include "Policies.h"
+#include <vector>
+#include <stdexcept>
+
+namespace dsp::core
+{
+    /**
+     * @brief Implements an Exponential Moving Average (EMA) filter.
+     *
+     * EMA gives more weight to recent samples and exponentially decaying weight to older samples.
+     * Formula: EMA(t) = α * value(t) + (1 - α) * EMA(t-1)
+     *
+     * where α (alpha) is the smoothing factor:
+     * - α close to 1: Fast response to changes (less smoothing)
+     * - α close to 0: Slow response to changes (more smoothing)
+     *
+     * Common conversions:
+     * - From N-period SMA: α = 2 / (N + 1)
+     * - From time constant: α = 1 - exp(-Δt / τ)
+     *
+     * Unlike simple moving average, EMA does not require a fixed window size,
+     * making it memory-efficient for very long averaging periods.
+     *
+     * @tparam T The numeric type of the samples (e.g., float, double).
+     */
+    template <typename T>
+    class ExponentialMovingAverageFilter
+    {
+    public:
+        /**
+         * @brief Constructs a new EMA Filter with specified alpha.
+         * @param alpha The smoothing factor (0 < α ≤ 1).
+         * @throws std::invalid_argument if alpha is outside valid range.
+         */
+        explicit ExponentialMovingAverageFilter(T alpha)
+            : m_policy(alpha)
+        {
+            if (alpha <= 0 || alpha > 1)
+            {
+                throw std::invalid_argument("EMA alpha must be in range (0, 1]");
+            }
+        }
+
+        // Delete copy constructor and copy assignment
+        ExponentialMovingAverageFilter(const ExponentialMovingAverageFilter &) = delete;
+        ExponentialMovingAverageFilter &operator=(const ExponentialMovingAverageFilter &) = delete;
+
+        // Enable move semantics
+        ExponentialMovingAverageFilter(ExponentialMovingAverageFilter &&) noexcept = default;
+        ExponentialMovingAverageFilter &operator=(ExponentialMovingAverageFilter &&) noexcept = default;
+
+        /**
+         * @brief Adds a new sample and updates the EMA.
+         * @param newValue The new sample value.
+         * @return T The updated EMA value.
+         */
+        T addSample(T newValue)
+        {
+            m_policy.onAdd(newValue);
+            return m_policy.getResult(0); // Count parameter unused for EMA
+        }
+
+        /**
+         * @brief Process array of samples in batch (optimized for throughput).
+         *
+         * @param input Input array of samples
+         * @param output Output array (same size as input)
+         * @param length Number of samples to process
+         */
+        void processArray(const T *input, T *output, size_t length)
+        {
+            for (size_t i = 0; i < length; ++i)
+            {
+                output[i] = addSample(input[i]);
+            }
+        }
+
+        /**
+         * @brief Gets the current EMA value.
+         * @return T The current exponential moving average.
+         */
+        T getEma() const { return m_policy.getResult(0); }
+
+        /**
+         * @brief Gets the alpha (smoothing factor).
+         * @return T The alpha value.
+         */
+        T getAlpha() const { return m_policy.getAlpha(); }
+
+        /**
+         * @brief Clears the EMA state.
+         */
+        void clear() { m_policy.clear(); }
+
+        /**
+         * @brief Checks if the filter has been initialized with at least one sample.
+         * @return true if initialized, false otherwise.
+         */
+        bool isInitialized() const
+        {
+            auto [ema, initialized] = m_policy.getState();
+            return initialized;
+        }
+
+        /**
+         * @brief Exports the filter's internal state.
+         * @return A pair containing the current EMA value and initialization flag.
+         */
+        std::pair<T, bool> getState() const
+        {
+            return m_policy.getState();
+        }
+
+        /**
+         * @brief Restores the filter's internal state.
+         * @param ema The EMA value to restore.
+         * @param initialized The initialization flag to restore.
+         */
+        void setState(T ema, bool initialized)
+        {
+            m_policy.setState(ema, initialized);
+        }
+
+    private:
+        EmaPolicy<T> m_policy;
+    };
+
+} // namespace dsp::core

package/src/native/core/FilterBankDesign.h

@@ -0,0 +1,266 @@
+#pragma once
+
+#include "IirFilter.h"
+#include <vector>
+#include <string>
+#include <cmath>
+#include <stdexcept>
+#include <algorithm>
+
+namespace dsp
+{
+    namespace core
+    {
+        /**
+         * Filter coefficients structure for a single filter
+         */
+        struct FilterCoefficients
+        {
+            std::vector<float> b; // Numerator coefficients
+            std::vector<float> a; // Denominator coefficients
+        };
+
+        /**
+         * Filter Bank Design Engine
+         *
+         * Generates sets of bandpass filters covering a frequency range according to
+         * psychoacoustic (Mel, Bark) or mathematical (Linear, Log) scales.
+         *
+         * This is a stateless utility that performs frequency warping and filter design
+         * without maintaining any processing state.
+         */
+        class FilterBankDesign
+        {
+        public:
+            enum class Scale
+            {
+                Linear, // Linear spacing in Hz
+                Log,    // Logarithmic spacing
+                Mel,    // Mel scale (mimics human hearing)
+                Bark    // Bark scale (critical band rate)
+            };
+
+            enum class Type
+            {
+                Butterworth, // Maximally flat passband
+                Chebyshev1   // Equiripple passband
+            };
+
+            /**
+             * Filter bank design options
+             */
+            struct DesignOptions
+            {
+                Scale scale;           // Frequency spacing scale
+                Type type;             // Filter topology
+                int count;             // Number of bands
+                double sampleRate;     // Sample rate in Hz
+                double minFreq;        // Minimum frequency in Hz
+                double maxFreq;        // Maximum frequency in Hz
+                int order;             // Filter order per band (steepness)
+                double rippleDb = 0.5; // Passband ripple for Chebyshev (dB)
+            };
+
+            /**
+             * Design a filter bank with specified options
+             *
+             * @param opts Design options including scale, count, frequency range
+             * @return Vector of filter coefficients (one per band)
+             *
+             * @throws std::invalid_argument if options are invalid
+             *
+             * @example
+             * // Create 24-band Mel-spaced filter bank for speech analysis
+             * DesignOptions opts;
+             * opts.scale = Scale::Mel;
+             * opts.type = Type::Butterworth;
+             * opts.count = 24;
+             * opts.sampleRate = 44100;
+             * opts.minFreq = 20;
+             * opts.maxFreq = 8000;
+             * opts.order = 2;
+             * auto bank = FilterBankDesign::design(opts);
+             */
+            static std::vector<FilterCoefficients> design(const DesignOptions &opts)
+            {
+                // Validate inputs
+                if (opts.count <= 0)
+                {
+                    throw std::invalid_argument("Band count must be positive");
+                }
+                if (opts.minFreq < 0)
+                {
+                    throw std::invalid_argument("Minimum frequency cannot be negative");
+                }
+                if (opts.minFreq >= opts.maxFreq)
+                {
+                    throw std::invalid_argument("Invalid frequency range: minFreq must be < maxFreq");
+                }
+                if (opts.maxFreq > opts.sampleRate / 2.0)
+                {
+                    throw std::invalid_argument("Maximum frequency must be <= Nyquist frequency");
+                }
+                if (opts.order <= 0)
+                {
+                    throw std::invalid_argument("Filter order must be positive");
+                }
+                if (opts.sampleRate <= 0)
+                {
+                    throw std::invalid_argument("Sample rate must be positive");
+                }
+
+                // Step 1: Convert frequency boundaries to target scale
+                double minVal = toScale(opts.minFreq, opts.scale);
+                double maxVal = toScale(opts.maxFreq, opts.scale);
+                double step = (maxVal - minVal) / opts.count;
+
+                // Step 2: Generate band edges in target scale, then convert back to Hz
+                std::vector<double> boundaries;
+                boundaries.reserve(opts.count + 1);
+
+                for (int i = 0; i <= opts.count; ++i)
+                {
+                    double val = minVal + (i * step);
+                    double hz = fromScale(val, opts.scale);
+                    boundaries.push_back(hz);
+                }
+
+                // Step 3: Create filters for each band
+                std::vector<FilterCoefficients> bank;
+                bank.reserve(opts.count);
+
+                for (int i = 0; i < opts.count; ++i)
+                {
+                    double fLow = boundaries[i];
+                    double fHigh = boundaries[i + 1];
+
+                    // For the first band starting at 0 Hz, use a small positive value
+                    // to avoid DC (bandpass filters can't have 0 Hz as lower bound)
+                    if (fLow == 0.0)
+                    {
+                        fLow = 1.0; // 1 Hz minimum
+                    }
+
+                    // Normalize frequencies to [0, 0.5] range (0.5 = Nyquist)
+                    double nLow = fLow / opts.sampleRate;
+                    double nHigh = fHigh / opts.sampleRate;
+
+                    // Safety clamping to avoid numerical issues
+                    nLow = std::max(0.0001, std::min(nLow, 0.4999));
+                    nHigh = std::max(0.0001, std::min(nHigh, 0.4999));
+
+                    // Ensure proper ordering after clamping
+                    if (nLow >= nHigh)
+                    {
+                        nHigh = nLow + 0.0001;
+                    }
+
+                    // Design bandpass filter using existing IirFilter factory
+                    IirFilter<float> filter = (opts.type == Type::Chebyshev1)
+                                                  ? IirFilter<float>::createChebyshevBandPass(
+                                                        nLow, nHigh, opts.order, opts.rippleDb)
+                                                  : IirFilter<float>::createButterworthBandPass(
+                                                        nLow, nHigh, opts.order);
+
+                    // Extract coefficients
+                    FilterCoefficients coeffs;
+                    coeffs.b = filter.getBCoefficients();
+                    coeffs.a = filter.getACoefficients();
+
+                    bank.push_back(coeffs);
+                }
+
+                return bank;
+            }
+
+            /**
+             * Get frequency boundaries for a filter bank design
+             * Useful for visualization and debugging
+             *
+             * @param opts Design options
+             * @return Vector of boundary frequencies in Hz
+             */
+            static std::vector<double> getBoundaries(const DesignOptions &opts)
+            {
+                if (opts.count <= 0)
+                {
+                    throw std::invalid_argument("Band count must be positive");
+                }
+
+                double minVal = toScale(opts.minFreq, opts.scale);
+                double maxVal = toScale(opts.maxFreq, opts.scale);
+                double step = (maxVal - minVal) / opts.count;
+
+                std::vector<double> boundaries;
+                boundaries.reserve(opts.count + 1);
+
+                for (int i = 0; i <= opts.count; ++i)
+                {
+                    double val = minVal + (i * step);
+                    boundaries.push_back(fromScale(val, opts.scale));
+                }
+
+                return boundaries;
+            }
+
+        private:
+            /**
+             * Convert frequency from Hz to target scale
+             */
+            static double toScale(double hz, Scale scale)
+            {
+                switch (scale)
+                {
+                case Scale::Linear:
+                    return hz;
+
+                case Scale::Log:
+                    return std::log10(hz);
+
+                case Scale::Mel:
+                    // Mel scale: f_mel = 2595 * log10(1 + f_hz / 700)
+                    return 2595.0 * std::log10(1.0 + hz / 700.0);
+
+                case Scale::Bark:
+                    // Bark scale (Traunmüller 1990)
+                    // z = 26.81 * f / (1960 + f) - 0.53
+                    return 26.81 * hz / (1960.0 + hz) - 0.53;
+
+                default:
+                    return hz;
+                }
+            }
+
+            /**
+             * Convert from scale back to Hz
+             */
+            static double fromScale(double val, Scale scale)
+            {
+                switch (scale)
+                {
+                case Scale::Linear:
+                    return val;
+
+                case Scale::Log:
+                    return std::pow(10.0, val);
+
+                case Scale::Mel:
+                    // Inverse Mel: f_hz = 700 * (10^(f_mel / 2595) - 1)
+                    return 700.0 * (std::pow(10.0, val / 2595.0) - 1.0);
+
+                case Scale::Bark:
+                    // Inverse Bark (Traunmüller 1990)
+                    // f = 1960 * (z + 0.53) / (26.81 - (z + 0.53))
+                    {
+                        double adjusted = val + 0.53;
+                        return 1960.0 * adjusted / (26.81 - adjusted);
+                    }
+
+                default:
+                    return val;
+                }
+            }
+        };
+
+    } // namespace core
+} // namespace dsp

package/src/native/core/Policies.h

@@ -349,4 +349,128 @@ namespace dsp::core
         void setCoefficients(const std::vector<T> &coeffs) { m_coefficients = coeffs; }
     };
 
+    /**
+     * @brief Policy for Exponential Moving Average (EMA).
+     *
+     * Implements EMA: EMA(t) = α * value(t) + (1 - α) * EMA(t-1)
+     * where α (alpha) is the smoothing factor (0 < α ≤ 1).
+     *
+     * This policy is optimized for scalar operations and can be SIMD-accelerated
+     * in batch processing contexts.
+     */
+    template <typename T>
+    struct EmaPolicy
+    {
+        T m_ema = 0; // Current EMA value
+        T m_alpha;   // Smoothing factor
+        bool m_initialized = false;
+
+        explicit EmaPolicy(T alpha)
+            : m_alpha(alpha)
+        {
+            if (alpha <= 0 || alpha > 1)
+            {
+                throw std::invalid_argument("EMA alpha must be in range (0, 1]");
+            }
+        }
+
+        void onAdd(T val)
+        {
+            if (!m_initialized)
+            {
+                // Initialize with first value
+                m_ema = val;
+                m_initialized = true;
+            }
+            else
+            {
+                // EMA formula: EMA(t) = α * value(t) + (1 - α) * EMA(t-1)
+                m_ema = m_alpha * val + (static_cast<T>(1) - m_alpha) * m_ema;
+            }
+        }
+
+        void onRemove(T val)
+        {
+            // EMA doesn't support removal in sliding window context
+            // This should not be called in typical EMA usage
+        }
+
+        void clear()
+        {
+            m_ema = 0;
+            m_initialized = false;
+        }
+
+        T getResult(size_t count) const
+        {
+            return m_ema;
+        }
+
+        // For state serialization
+        std::pair<T, bool> getState() const { return {m_ema, m_initialized}; }
+        void setState(T ema, bool initialized)
+        {
+            m_ema = ema;
+            m_initialized = initialized;
+        }
+
+        T getAlpha() const { return m_alpha; }
+    };
+
+    /**
+     * @brief Policy for Cumulative Moving Average (CMA).
+     *
+     * Implements CMA: CMA(n) = (CMA(n-1) * (n-1) + value(n)) / n
+     *
+     * Maintains the cumulative average over all samples seen since initialization.
+     * More efficient than recalculating from scratch each time.
+     */
+    template <typename T>
+    struct CmaPolicy
+    {
+        T m_sum = 0;        // Running sum of all values
+        size_t m_count = 0; // Total number of samples seen
+
+        void onAdd(T val)
+        {
+            m_sum += val;
+            m_count++;
+        }
+
+        void onRemove(T val)
+        {
+            // CMA doesn't support removal in typical usage
+            // If called, decrement count and sum
+            if (m_count > 0)
+            {
+                m_sum -= val;
+                m_count--;
+            }
+        }
+
+        void clear()
+        {
+            m_sum = 0;
+            m_count = 0;
+        }
+
+        T getResult(size_t windowCount) const
+        {
+            // Use the policy's internal count, not the window count
+            if (m_count == 0)
+                return 0;
+            return m_sum / static_cast<T>(m_count);
+        }
+
+        // For state serialization
+        std::pair<T, size_t> getState() const { return {m_sum, m_count}; }
+        void setState(T sum, size_t count)
+        {
+            m_sum = sum;
+            m_count = count;
+        }
+
+        size_t getCount() const { return m_count; }
+    };
+
 } // namespace dsp::core

package/src/native/utils/CircularBufferArray.cc

@@ -240,7 +240,8 @@ size_t CircularBufferArray<T>::expireOld(double currentTimestamp)
     double cutoff_time = currentTimestamp - windowDuration_ms;
 
     // Remove samples from tail while they're older than cutoff
-    while (count > 0 && timestamps[tail] < cutoff_time)
+    // FIX: changed < to <= to correctly expire samples at the cutoff and avoid an additional windowduration delay
+    while (count > 0 && timestamps[tail] <= cutoff_time)
     {
         tail = (tail + 1) % capacity;
         --count;