dspx 1.2.4 → 1.3.1

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;

package/src/native/utils/SimdOps.h

@@ -1362,4 +1362,71 @@ namespace dsp::simd
     }
 
     // SIMD_X86 removed since SIMD_SSE3 covers it for most of the modern devices
+    /**
+     * @brief Apply square (x^2) in-place.
+     * Essential for Pan-Tompkins QRS detection to amplify signal peaks.
+     * @param buffer Input/output buffer (modified in-place)
+     * @param size Number of elements
+     */
+    inline void square_inplace(float *buffer, size_t size)
+    {
+#if defined(SIMD_AVX2)
+        const size_t simd_width = 8;
+        const size_t simd_count = size / simd_width;
+        const size_t simd_end = simd_count * simd_width;
+
+        for (size_t i = 0; i < simd_end; i += simd_width)
+        {
+            __m256 values = _mm256_loadu_ps(&buffer[i]);
+            __m256 result = _mm256_mul_ps(values, values); // x * x
+            _mm256_storeu_ps(&buffer[i], result);
+        }
+
+        for (size_t i = simd_end; i < size; ++i)
+        {
+            buffer[i] = buffer[i] * buffer[i];
+        }
+
+#elif defined(SIMD_SSE2)
+        const size_t simd_width = 4;
+        const size_t simd_count = size / simd_width;
+        const size_t simd_end = simd_count * simd_width;
+
+        for (size_t i = 0; i < simd_end; i += simd_width)
+        {
+            __m128 values = _mm_loadu_ps(&buffer[i]);
+            __m128 result = _mm_mul_ps(values, values);
+            _mm_storeu_ps(&buffer[i], result);
+        }
+
+        for (size_t i = simd_end; i < size; ++i)
+        {
+            buffer[i] = buffer[i] * buffer[i];
+        }
+
+#elif defined(SIMD_NEON)
+        const size_t simd_width = 4;
+        const size_t simd_count = size / simd_width;
+        const size_t simd_end = simd_count * simd_width;
+
+        for (size_t i = 0; i < simd_end; i += simd_width)
+        {
+            float32x4_t values = vld1q_f32(&buffer[i]);
+            float32x4_t result = vmulq_f32(values, values);
+            vst1q_f32(&buffer[i], result);
+        }
+
+        for (size_t i = simd_end; i < size; ++i)
+        {
+            buffer[i] = buffer[i] * buffer[i];
+        }
+
+#else
+        // Scalar fallback
+        for (size_t i = 0; i < size; ++i)
+        {
+            buffer[i] = buffer[i] * buffer[i];
+        }
+#endif
+    }
 } // namespace dsp::simd

package/src/native/utils/Toon.h

@@ -0,0 +1,195 @@
+#pragma once
+#include <vector>
+#include <cstring>
+#include <string>
+#include <stdexcept>
+
+namespace dsp
+{
+    namespace toon
+    {
+
+        // TOON Protocol Tokens
+        enum Token : uint8_t
+        {
+            T_NULL = 0x00,
+            T_INT32 = 0x01,
+            T_FLOAT = 0x02,
+            T_STRING = 0x03,
+            T_FLOAT_ARRAY = 0x04, // Optimized for DSP buffers
+            T_OBJECT_START = 0x10,
+            T_OBJECT_END = 0x11,
+            T_ARRAY_START = 0x12,
+            T_ARRAY_END = 0x13,
+            T_BOOL = 0x14,
+            T_DOUBLE = 0x15
+        };
+
+        class Serializer
+        {
+        public:
+            std::vector<uint8_t> buffer;
+
+            void writeTag(Token tag)
+            {
+                buffer.push_back(static_cast<uint8_t>(tag));
+            }
+
+            void writeInt32(int32_t val)
+            {
+                writeTag(T_INT32);
+                appendRaw(&val, sizeof(val));
+            }
+
+            void writeFloat(float val)
+            {
+                writeTag(T_FLOAT);
+                appendRaw(&val, sizeof(val));
+            }
+
+            void writeDouble(double val)
+            {
+                writeTag(T_DOUBLE);
+                appendRaw(&val, sizeof(val));
+            }
+
+            void writeBool(bool val)
+            {
+                writeTag(T_BOOL);
+                uint8_t byte = val ? 1 : 0;
+                buffer.push_back(byte);
+            }
+
+            void writeString(const std::string &val)
+            {
+                writeTag(T_STRING);
+                int32_t len = static_cast<int32_t>(val.length());
+                appendRaw(&len, sizeof(len)); // Length prefix
+                appendRaw(val.data(), len);
+            }
+
+            // Critical Optimization: Zero-copy-like write for DSP buffers
+            void writeFloatArray(const std::vector<float> &data)
+            {
+                writeTag(T_FLOAT_ARRAY);
+                int32_t count = static_cast<int32_t>(data.size());
+                appendRaw(&count, sizeof(count));
+                if (count > 0)
+                {
+                    appendRaw(data.data(), count * sizeof(float));
+                }
+            }
+
+            void startObject() { writeTag(T_OBJECT_START); }
+            void endObject() { writeTag(T_OBJECT_END); }
+            void startArray() { writeTag(T_ARRAY_START); }
+            void endArray() { writeTag(T_ARRAY_END); }
+
+        private:
+            void appendRaw(const void *ptr, size_t size)
+            {
+                const uint8_t *bytes = static_cast<const uint8_t *>(ptr);
+                buffer.insert(buffer.end(), bytes, bytes + size);
+            }
+        };
+
+        class Deserializer
+        {
+        public:
+            const uint8_t *data;
+            size_t size;
+            size_t pos;
+
+            Deserializer(const uint8_t *d, size_t s) : data(d), size(s), pos(0) {}
+
+            Token peekToken()
+            {
+                if (pos >= size)
+                    return T_NULL;
+                return static_cast<Token>(data[pos]);
+            }
+
+            Token readToken()
+            {
+                if (pos >= size)
+                    throw std::runtime_error("TOON: Unexpected EOF");
+                return static_cast<Token>(data[pos++]);
+            }
+
+            int32_t readInt32()
+            {
+                consumeToken(T_INT32);
+                return readRaw<int32_t>();
+            }
+
+            float readFloat()
+            {
+                consumeToken(T_FLOAT);
+                return readRaw<float>();
+            }
+
+            double readDouble()
+            {
+                consumeToken(T_DOUBLE);
+                return readRaw<double>();
+            }
+
+            bool readBool()
+            {
+                consumeToken(T_BOOL);
+                if (pos >= size)
+                    throw std::runtime_error("TOON: EOF reading bool");
+                return data[pos++] != 0;
+            }
+
+            std::string readString()
+            {
+                consumeToken(T_STRING);
+                int32_t len = readRaw<int32_t>();
+                if (pos + len > size)
+                    throw std::runtime_error("TOON: String out of bounds");
+                std::string s(reinterpret_cast<const char *>(data + pos), len);
+                pos += len;
+                return s;
+            }
+
+            std::vector<float> readFloatArray()
+            {
+                consumeToken(T_FLOAT_ARRAY);
+                int32_t count = readRaw<int32_t>();
+                if (count < 0)
+                    throw std::runtime_error("TOON: Invalid array count");
+                if (pos + count * sizeof(float) > size)
+                    throw std::runtime_error("TOON: Array out of bounds");
+
+                std::vector<float> vec(count);
+                if (count > 0)
+                {
+                    std::memcpy(vec.data(), data + pos, count * sizeof(float));
+                    pos += count * sizeof(float);
+                }
+                return vec;
+            }
+
+            void consumeToken(Token expected)
+            {
+                Token actual = readToken();
+                if (actual != expected)
+                    throw std::runtime_error("TOON: Type mismatch");
+            }
+
+        private:
+            template <typename T>
+            T readRaw()
+            {
+                if (pos + sizeof(T) > size)
+                    throw std::runtime_error("TOON: EOF reading value");
+                T val;
+                std::memcpy(&val, data + pos, sizeof(T));
+                pos += sizeof(T);
+                return val;
+            }
+        };
+
+    } // namespace toon
+} // namespace dsp