sonus 0.1.0

data/lib/sonus/dsp/fft.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Sonus
+  module DSP
+    module FFT
+      module_function
+
+      def fft(signal)
+        case backend
+        when :fftw
+          FFTBackend::FFTW.fft(signal)
+        when :ruby
+          FFTBackend::Ruby.fft(signal)
+        else
+          raise Sonus::FFTBackendError, "Unknown FFT backend: #{backend}"
+        end
+      end
+
+      def amplitude_spectrum(signal)
+        complex = fft(signal)
+        complex.first((complex.length / 2) + 1).map(&:abs)
+      end
+
+      def backend
+        @backend ||= autodetect_backend
+      end
+
+      def backend=(value)
+        normalized = value.to_sym
+
+        case normalized
+        when :ruby
+          @backend = :ruby
+        when :fftw
+          unless FFTBackend::FFTW.available?
+            raise Sonus::FFTBackendError, "FFTW backend requested but unavailable"
+          end
+
+          @backend = :fftw
+        else
+          raise ArgumentError, "Unsupported backend: #{value}"
+        end
+      end
+
+      def reset_backend!
+        remove_instance_variable(:@backend) if instance_variable_defined?(:@backend)
+      end
+
+      def autodetect_backend
+        FFTBackend::FFTW.available? ? :fftw : :ruby
+      end
+      private_class_method :autodetect_backend
+    end
+  end
+end

data/lib/sonus/dsp/fft_backend/fftw.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "thread"
+
+module Sonus
+  module DSP
+    module FFTBackend
+      module FFTW
+        DEFAULT_PRECISION = :double
+        PLAN_FLAGS = [:estimate].freeze
+
+        Context = Struct.new(:input, :output, :plan, keyword_init: true)
+
+        @mutex = Mutex.new
+        @contexts = {}
+
+        module_function
+
+        def available?
+          fftw3
+          ::FFTW3.double_available?
+        rescue LoadError, StandardError
+          false
+        end
+
+        def fft(signal)
+          raise Sonus::FFTBackendError, "FFTW backend is not available" unless available?
+
+          size = Sonus::DSP::FFTBackend::Ruby.next_power_of_two(signal.length)
+          return [] if size.zero?
+
+          context = context_for(size)
+          write_input(context.input, signal, size)
+          context.plan.execute
+          read_output(context.output, size)
+        rescue Sonus::FFTBackendError
+          raise
+        rescue StandardError => error
+          raise Sonus::FFTBackendError, "FFTW execution failed: #{error.message}"
+        end
+
+        def reset!
+          @mutex.synchronize do
+            @contexts.each_value do |context|
+              context.plan&.destroy!
+              context.input&.free!
+              context.output&.free!
+            end
+            @contexts.clear
+          end
+        end
+
+        def fftw3
+          require "fftw3" unless defined?(::FFTW3)
+          ::FFTW3
+        end
+
+        def context_for(size)
+          @mutex.synchronize do
+            @contexts[size] ||= build_context(size)
+          end
+        end
+
+        def build_context(size)
+          library = fftw3
+          input = library::AlignedMemory.new(size, type: :real, precision: DEFAULT_PRECISION)
+          output = library::AlignedMemory.new((size / 2) + 1, type: :complex, precision: DEFAULT_PRECISION)
+          plan = library::Plan.dft_r2c_1d(
+            size,
+            input,
+            output,
+            flags: PLAN_FLAGS,
+            precision: DEFAULT_PRECISION
+          )
+
+          Context.new(input: input, output: output, plan: plan)
+        rescue StandardError
+          input&.free!
+          output&.free!
+          raise
+        end
+
+        def write_input(buffer, signal, size)
+          padded = signal.first(size).map(&:to_f)
+          padded.fill(0.0, padded.length...size)
+          buffer.write(padded)
+        end
+
+        def read_output(buffer, size)
+          output = buffer.read
+          spectrum = Array.new(size) { Complex(0.0, 0.0) }
+          spectrum[0, output.length] = output
+
+          (1...(output.length - 1)).each do |index|
+            spectrum[size - index] = spectrum[index].conjugate
+          end
+
+          spectrum
+        end
+      end
+    end
+  end
+end

data/lib/sonus/dsp/fft_backend/ruby.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Sonus
+  module DSP
+    module FFTBackend
+      module Ruby
+        module_function
+
+        def fft(signal)
+          padded = pad_to_power_of_two(signal)
+          size = padded.length
+          return [] if size.zero?
+
+          spectrum = padded.map { |value| Complex(value.to_f, 0.0) }
+          bit_reversal_permute!(spectrum)
+
+          half_size = 1
+          while half_size < size
+            phase_shift_step = Complex.polar(1.0, -Math::PI / half_size)
+            step = half_size * 2
+
+            (0...size).step(step) do |start|
+              phase_shift = Complex(1.0, 0.0)
+
+              half_size.times do |index|
+                even_index = start + index
+                odd_index = even_index + half_size
+
+                odd_value = phase_shift * spectrum[odd_index]
+                even_value = spectrum[even_index]
+
+                spectrum[even_index] = even_value + odd_value
+                spectrum[odd_index] = even_value - odd_value
+
+                phase_shift *= phase_shift_step
+              end
+            end
+
+            half_size = step
+          end
+
+          spectrum
+        end
+
+        def next_power_of_two(value)
+          return 1 if value <= 1
+
+          power = 1
+          power <<= 1 while power < value
+          power
+        end
+
+        def pad_to_power_of_two(signal)
+          return [] if signal.empty?
+
+          target_size = next_power_of_two(signal.length)
+          padded = signal.first(target_size).map(&:to_f)
+          padded.fill(0.0, padded.length...target_size)
+          padded
+        end
+
+        def bit_reversal_permute!(array)
+          size = array.length
+          j = 0
+
+          (1...(size - 1)).each do |index|
+            bit = size >> 1
+            while j >= bit
+              j -= bit
+              bit >>= 1
+            end
+            j += bit
+
+            array[index], array[j] = array[j], array[index] if index < j
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sonus/dsp/mel_filter_bank.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Sonus
+  module DSP
+    module MelFilterBank
+      @cache = {}
+
+      module_function
+
+      def hz_to_mel(hz)
+        2595.0 * Math.log10(1.0 + (hz.to_f / 700.0))
+      end
+
+      def mel_to_hz(mel)
+        700.0 * ((10**(mel.to_f / 2595.0)) - 1.0)
+      end
+
+      def create(num_filters:, fft_size:, sample_rate:, freq_min: 0.0, freq_max: nil)
+        normalized_num_filters = Integer(num_filters)
+        normalized_fft_size = Integer(fft_size)
+        normalized_sample_rate = Float(sample_rate)
+        normalized_freq_min = Float(freq_min)
+        normalized_freq_max = freq_max.nil? ? normalized_sample_rate / 2.0 : Float(freq_max)
+
+        if normalized_num_filters <= 0
+          raise ArgumentError, "num_filters must be positive"
+        end
+
+        if normalized_fft_size <= 0
+          raise ArgumentError, "fft_size must be positive"
+        end
+
+        key = [
+          normalized_num_filters,
+          normalized_fft_size,
+          normalized_sample_rate,
+          normalized_freq_min,
+          normalized_freq_max
+        ]
+
+        @cache[key] ||= build_filter_bank(
+          num_filters: normalized_num_filters,
+          fft_size: normalized_fft_size,
+          sample_rate: normalized_sample_rate,
+          freq_min: normalized_freq_min,
+          freq_max: normalized_freq_max
+        )
+      end
+
+      def build_filter_bank(num_filters:, fft_size:, sample_rate:, freq_min:, freq_max:)
+        mel_min = hz_to_mel(freq_min)
+        mel_max = hz_to_mel(freq_max)
+        mel_points = Array.new(num_filters + 2) do |index|
+          mel_min + ((mel_max - mel_min) * index / (num_filters + 1.0))
+        end
+        hz_points = mel_points.map { |mel| mel_to_hz(mel) }
+
+        max_bin = (fft_size / 2)
+        bin_points = hz_points.map do |hz|
+          bin = ((fft_size + 1) * hz / sample_rate).floor
+          [[bin, 0].max, max_bin].min
+        end
+
+        filters = Array.new(num_filters) { Array.new(max_bin + 1, 0.0) }
+
+        num_filters.times do |filter_index|
+          left = bin_points[filter_index]
+          center = bin_points[filter_index + 1]
+          right = bin_points[filter_index + 2]
+
+          fill_rising_slope(filters[filter_index], left, center)
+          fill_falling_slope(filters[filter_index], center, right)
+        end
+
+        filters
+      end
+      private_class_method :build_filter_bank
+
+      def fill_rising_slope(filter, left, center)
+        return if center <= left
+
+        (left...center).each do |bin|
+          filter[bin] = (bin - left).to_f / (center - left)
+        end
+      end
+      private_class_method :fill_rising_slope
+
+      def fill_falling_slope(filter, center, right)
+        return if right <= center
+
+        (center...right).each do |bin|
+          filter[bin] = (right - bin).to_f / (right - center)
+        end
+      end
+      private_class_method :fill_falling_slope
+    end
+  end
+end

data/lib/sonus/dsp/windowing.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Sonus
+  module DSP
+    module Windowing
+      module_function
+
+      def apply(signal, type = :hanning)
+        signal = signal.map(&:to_f)
+        size = signal.length
+        return signal.dup if size <= 1
+
+        case type.to_sym
+        when :rect
+          signal.dup
+        when :hanning, :hann
+          signal.each_with_index.map { |value, index| value * hanning(size, index) }
+        when :hamming
+          signal.each_with_index.map { |value, index| value * hamming(size, index) }
+        when :blackman
+          signal.each_with_index.map { |value, index| value * blackman(size, index) }
+        when :sine
+          signal.each_with_index.map { |value, index| value * sine(size, index) }
+        else
+          raise ArgumentError, "Unsupported windowing function: #{type}"
+        end
+      end
+
+      def hanning(size, index)
+        0.5 * (1.0 - Math.cos((2.0 * Math::PI * index) / (size - 1)))
+      end
+
+      def hamming(size, index)
+        0.54 - (0.46 * Math.cos((2.0 * Math::PI * index) / (size - 1)))
+      end
+
+      def blackman(size, index)
+        ratio = (2.0 * Math::PI * index) / (size - 1)
+        0.42 - (0.5 * Math.cos(ratio)) + (0.08 * Math.cos(2.0 * ratio))
+      end
+
+      def sine(size, index)
+        Math.sin((Math::PI * index) / (size - 1))
+      end
+    end
+  end
+end

data/lib/sonus/error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Sonus
+  class Error < StandardError; end
+  class InvalidSignalError < Error; end
+  class InvalidFeatureError < Error; end
+  class WAVFormatError < Error; end
+  class FFTBackendError < Error; end
+end

data/lib/sonus/features/amplitude_spectrum.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Sonus
+  module Features
+    class AmplitudeSpectrum < Base
+      feature :amplitude_spectrum, dependencies: [:complex_spectrum]
+
+      def self.extract(context)
+        spectrum = context[:cache].fetch(:complex_spectrum)
+        spectrum.first((spectrum.length / 2) + 1).map(&:abs)
+      end
+    end
+  end
+end

data/lib/sonus/features/base.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Sonus
+  module Features
+    class Base
+      class << self
+        attr_reader :feature_key, :dependencies
+
+        def feature(key, dependencies: [], public_feature: true)
+          @feature_key = key.to_sym
+          @dependencies = dependencies.map(&:to_sym)
+          @public_feature = public_feature
+
+          Sonus::Features.register(self)
+        end
+
+        def public_feature?
+          @public_feature != false
+        end
+
+        def extract(_context)
+          raise NotImplementedError, "Feature extract must be implemented"
+        end
+      end
+    end
+  end
+end

data/lib/sonus/features/buffer.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Sonus
+  module Features
+    class Buffer < Base
+      feature :buffer
+
+      def self.extract(context)
+        context.fetch(:buffer)
+      end
+    end
+  end
+end

data/lib/sonus/features/chroma.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Sonus
+  module Features
+    class Chroma < Base
+      feature :chroma, dependencies: [:amplitude_spectrum]
+
+      def self.extract(context)
+        amplitudes = context[:cache].fetch(:amplitude_spectrum)
+        chroma_bands = Integer(context.fetch(:number_of_chroma_bands, 12))
+        return Array.new(chroma_bands, 0.0) if amplitudes.empty?
+
+        fft_size = [(amplitudes.length - 1) * 2, 1].max
+        sample_rate = context.fetch(:sample_rate).to_f
+
+        chroma = Array.new(chroma_bands, 0.0)
+
+        amplitudes.each_with_index do |amplitude, index|
+          frequency = (index * sample_rate) / fft_size
+          next if frequency <= 0.0
+
+          midi_note = 69.0 + (12.0 * Math.log2(frequency / 440.0))
+          base_chroma = midi_note.round % 12
+          band_index = ((base_chroma / 12.0) * chroma_bands).floor % chroma_bands
+          chroma[band_index] += amplitude
+        end
+
+        total = chroma.sum
+        return chroma if total.zero?
+
+        chroma.map { |value| value / total }
+      end
+    end
+  end
+end

data/lib/sonus/features/complex_spectrum.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Sonus
+  module Features
+    class ComplexSpectrum < Base
+      feature :complex_spectrum, dependencies: [:windowed_signal]
+
+      def self.extract(context)
+        Sonus::DSP::FFT.fft(context[:cache].fetch(:windowed_signal))
+      end
+    end
+  end
+end

data/lib/sonus/features/energy.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Sonus
+  module Features
+    class Energy < Base
+      feature :energy, dependencies: [:buffer]
+
+      def self.extract(context)
+        context[:cache].fetch(:buffer).sum { |sample| sample * sample }
+      end
+    end
+  end
+end

data/lib/sonus/features/loudness.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Sonus
+  module Features
+    class Loudness < Base
+      feature :loudness, dependencies: [:amplitude_spectrum]
+
+      def self.extract(context)
+        amplitudes = context[:cache].fetch(:amplitude_spectrum)
+        return { specific: [], total: 0.0 } if amplitudes.empty?
+
+        bark_bands = Integer(context.fetch(:number_of_bark_bands, Sonus::DEFAULT_BARK_BANDS))
+        bark_scale = create_bark_scale(amplitudes.length, context.fetch(:sample_rate))
+        limits = bark_band_limits(bark_scale, bark_bands)
+
+        specific = Array.new(bark_bands, 0.0)
+        bark_bands.times do |index|
+          sum = 0.0
+          (limits[index]...limits[index + 1]).each { |bin| sum += amplitudes[bin] }
+          specific[index] = sum**0.23
+        end
+
+        { specific: specific, total: specific.sum }
+      end
+
+      def self.create_bark_scale(length, sample_rate)
+        fft_size = [(length - 1) * 2, 1].max
+        frequency_step = sample_rate.to_f / fft_size
+
+        Array.new(length) do |index|
+          frequency = index * frequency_step
+          (13.0 * Math.atan(0.00076 * frequency)) + (3.5 * Math.atan((frequency / 7500.0)**2))
+        end
+      end
+      private_class_method :create_bark_scale
+
+      def self.bark_band_limits(bark_scale, bark_bands)
+        limits = Array.new(bark_bands + 1, 0)
+        current_band = 1
+        max_bark = bark_scale.last
+        current_band_end = max_bark / bark_bands
+
+        bark_scale.each_with_index do |value, index|
+          while value > current_band_end && current_band < bark_bands
+            limits[current_band] = index
+            current_band += 1
+            current_band_end = (current_band * max_bark) / bark_bands
+          end
+        end
+
+        limits[bark_bands] = bark_scale.length - 1
+        limits
+      end
+      private_class_method :bark_band_limits
+    end
+  end
+end

data/lib/sonus/features/mel_bands.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Sonus
+  module Features
+    class MelBands < Base
+      feature :mel_bands, dependencies: [:power_spectrum]
+
+      def self.extract(context)
+        power_spectrum = context[:cache].fetch(:power_spectrum)
+        return [] if power_spectrum.empty?
+
+        mel_filters = Sonus::DSP::MelFilterBank.create(
+          num_filters: context.fetch(:number_of_mel_filters, Sonus::DEFAULT_MEL_FILTERS),
+          fft_size: [(power_spectrum.length - 1) * 2, 1].max,
+          sample_rate: context.fetch(:sample_rate)
+        )
+
+        mel_filters.map do |filter|
+          energy = power_spectrum.each_with_index.sum do |value, index|
+            value * (filter[index] || 0.0)
+          end
+          Math.log(energy + 1.0)
+        end
+      end
+    end
+  end
+end

data/lib/sonus/features/mfcc.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Sonus
+  module Features
+    class MFCC < Base
+      feature :mfcc, dependencies: [:mel_bands]
+
+      def self.extract(context)
+        mel_bands = context[:cache].fetch(:mel_bands)
+        return [] if mel_bands.empty?
+
+        requested = Integer(context.fetch(:number_of_mfcc_coefficients, Sonus::DEFAULT_MFCC_COEFFICIENTS))
+        coefficient_count = [[requested, 1].max, 40].min
+        dct(mel_bands, coefficient_count)
+      end
+
+      def self.dct(values, coefficient_count)
+        length = values.length
+        return [] if length.zero?
+
+        Array.new(coefficient_count) do |k|
+          values.each_with_index.sum do |value, index|
+            value * Math.cos((Math::PI / length) * (index + 0.5) * k)
+          end
+        end
+      end
+      private_class_method :dct
+    end
+  end
+end

data/lib/sonus/features/perceptual_sharpness.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Sonus
+  module Features
+    class PerceptualSharpness < Base
+      feature :perceptual_sharpness, dependencies: [:loudness]
+
+      def self.extract(context)
+        loudness = context[:cache].fetch(:loudness)
+        specific = loudness.fetch(:specific)
+        total = loudness.fetch(:total)
+        return 0.0 if total.zero?
+
+        output = specific.each_index.sum do |index|
+          if index < 15
+            (index + 1) * (specific[index + 1] || 0.0)
+          else
+            0.066 * Math.exp(0.171 * (index + 1))
+          end
+        end
+
+        output * (0.11 / total)
+      end
+    end
+  end
+end

data/lib/sonus/features/perceptual_spread.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Sonus
+  module Features
+    class PerceptualSpread < Base
+      feature :perceptual_spread, dependencies: [:loudness]
+
+      def self.extract(context)
+        loudness = context[:cache].fetch(:loudness)
+        total = loudness.fetch(:total)
+        return 0.0 if total.zero?
+
+        spread = (total - loudness.fetch(:specific).max) / total
+        spread * spread
+      end
+    end
+  end
+end

data/lib/sonus/features/power_spectrum.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Sonus
+  module Features
+    class PowerSpectrum < Base
+      feature :power_spectrum, dependencies: [:amplitude_spectrum]
+
+      def self.extract(context)
+        context[:cache].fetch(:amplitude_spectrum).map { |value| value * value }
+      end
+    end
+  end
+end