sonus 0.1.0

data/lib/sonus/features/rms.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Sonus
+  module Features
+    class RMS < Base
+      feature :rms, dependencies: [:buffer]
+
+      def self.extract(context)
+        buffer = context[:cache].fetch(:buffer)
+        return 0.0 if buffer.empty?
+
+        Math.sqrt(buffer.sum { |sample| sample * sample } / buffer.length.to_f)
+      end
+    end
+  end
+end

data/lib/sonus/features/spectral_centroid.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Sonus
+  module Features
+    class SpectralCentroid < Base
+      feature :spectral_centroid, dependencies: [:amplitude_spectrum]
+
+      def self.extract(context)
+        amplitudes = context[:cache].fetch(:amplitude_spectrum)
+        total_amplitude = amplitudes.sum
+        return 0.0 if total_amplitude.zero?
+
+        frequency_step = frequency_step_for(amplitudes.length, context.fetch(:sample_rate))
+        weighted_sum = amplitudes.each_with_index.sum do |amplitude, index|
+          amplitude * index * frequency_step
+        end
+
+        weighted_sum / total_amplitude
+      end
+
+      def self.frequency_step_for(length, sample_rate)
+        return 0.0 if length <= 1
+
+        fft_size = (length - 1) * 2
+        sample_rate.to_f / fft_size
+      end
+      private_class_method :frequency_step_for
+    end
+  end
+end

data/lib/sonus/features/spectral_crest.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Sonus
+  module Features
+    class SpectralCrest < Base
+      feature :spectral_crest, dependencies: [:amplitude_spectrum]
+
+      def self.extract(context)
+        amplitudes = context[:cache].fetch(:amplitude_spectrum)
+        return 0.0 if amplitudes.empty?
+
+        rms = Math.sqrt(amplitudes.sum { |value| value * value } / amplitudes.length.to_f)
+        return 0.0 if rms.zero?
+
+        amplitudes.max / rms
+      end
+    end
+  end
+end

data/lib/sonus/features/spectral_flatness.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Sonus
+  module Features
+    class SpectralFlatness < Base
+      EPSILON = 1e-12
+
+      feature :spectral_flatness, dependencies: [:amplitude_spectrum]
+
+      def self.extract(context)
+        amplitudes = context[:cache].fetch(:amplitude_spectrum)
+        return 0.0 if amplitudes.empty?
+
+        arithmetic_mean = amplitudes.sum / amplitudes.length.to_f
+        return 0.0 if arithmetic_mean.zero?
+
+        geometric_mean = Math.exp(amplitudes.sum { |value| Math.log(value + EPSILON) } / amplitudes.length)
+        geometric_mean / arithmetic_mean
+      end
+    end
+  end
+end

data/lib/sonus/features/spectral_flux.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Sonus
+  module Features
+    class SpectralFlux < Base
+      feature :spectral_flux, dependencies: [:amplitude_spectrum]
+
+      def self.extract(context)
+        current = context[:cache].fetch(:amplitude_spectrum)
+        previous = context[:prev_amplitude_spectrum]
+        return 0.0 unless previous
+
+        length = [current.length, previous.length].max
+
+        length.times.sum do |index|
+          current_value = current[index] || 0.0
+          previous_value = previous[index] || 0.0
+          delta = current_value - previous_value
+          delta * delta
+        end
+      end
+    end
+  end
+end

data/lib/sonus/features/spectral_kurtosis.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Sonus
+  module Features
+    class SpectralKurtosis < Base
+      feature :spectral_kurtosis, dependencies: [:amplitude_spectrum, :spectral_centroid, :spectral_spread]
+
+      def self.extract(context)
+        amplitudes = context[:cache].fetch(:amplitude_spectrum)
+        centroid = context[:cache].fetch(:spectral_centroid)
+        spread = context[:cache].fetch(:spectral_spread)
+        total_amplitude = amplitudes.sum
+        return 0.0 if total_amplitude.zero? || spread.zero?
+
+        frequency_step = frequency_step_for(amplitudes.length, context.fetch(:sample_rate))
+
+        numerator = amplitudes.each_with_index.sum do |amplitude, index|
+          frequency = index * frequency_step
+          amplitude * ((frequency - centroid)**4)
+        end
+
+        numerator / (total_amplitude * (spread**4))
+      end
+
+      def self.frequency_step_for(length, sample_rate)
+        return 0.0 if length <= 1
+
+        fft_size = (length - 1) * 2
+        sample_rate.to_f / fft_size
+      end
+      private_class_method :frequency_step_for
+    end
+  end
+end

data/lib/sonus/features/spectral_rolloff.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Sonus
+  module Features
+    class SpectralRolloff < Base
+      feature :spectral_rolloff, dependencies: [:amplitude_spectrum]
+
+      def self.extract(context)
+        amplitudes = context[:cache].fetch(:amplitude_spectrum)
+        total_amplitude = amplitudes.sum
+        return 0.0 if total_amplitude.zero?
+
+        threshold = total_amplitude * 0.99
+        cumulative = 0.0
+
+        rolloff_index = amplitudes.each_with_index.find do |amplitude, _index|
+          cumulative += amplitude
+          cumulative >= threshold
+        end&.last || 0
+
+        fft_size = [(amplitudes.length - 1) * 2, 1].max
+        (rolloff_index * context.fetch(:sample_rate).to_f) / fft_size
+      end
+    end
+  end
+end

data/lib/sonus/features/spectral_skewness.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Sonus
+  module Features
+    class SpectralSkewness < Base
+      feature :spectral_skewness, dependencies: [:amplitude_spectrum, :spectral_centroid, :spectral_spread]
+
+      def self.extract(context)
+        amplitudes = context[:cache].fetch(:amplitude_spectrum)
+        centroid = context[:cache].fetch(:spectral_centroid)
+        spread = context[:cache].fetch(:spectral_spread)
+        total_amplitude = amplitudes.sum
+        return 0.0 if total_amplitude.zero? || spread.zero?
+
+        frequency_step = frequency_step_for(amplitudes.length, context.fetch(:sample_rate))
+
+        numerator = amplitudes.each_with_index.sum do |amplitude, index|
+          frequency = index * frequency_step
+          amplitude * ((frequency - centroid)**3)
+        end
+
+        numerator / (total_amplitude * (spread**3))
+      end
+
+      def self.frequency_step_for(length, sample_rate)
+        return 0.0 if length <= 1
+
+        fft_size = (length - 1) * 2
+        sample_rate.to_f / fft_size
+      end
+      private_class_method :frequency_step_for
+    end
+  end
+end

data/lib/sonus/features/spectral_slope.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Sonus
+  module Features
+    class SpectralSlope < Base
+      feature :spectral_slope, dependencies: [:amplitude_spectrum]
+
+      def self.extract(context)
+        amplitudes = context[:cache].fetch(:amplitude_spectrum)
+        sample_count = amplitudes.length
+        return 0.0 if sample_count <= 1
+
+        sum_x = (0...sample_count).sum
+        sum_y = amplitudes.sum
+        sum_xy = amplitudes.each_with_index.sum { |value, index| index * value }
+        sum_x2 = (0...sample_count).sum { |index| index * index }
+
+        denominator = (sample_count * sum_x2) - (sum_x * sum_x)
+        return 0.0 if denominator.zero?
+
+        ((sample_count * sum_xy) - (sum_x * sum_y)) / denominator.to_f
+      end
+    end
+  end
+end

data/lib/sonus/features/spectral_spread.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Sonus
+  module Features
+    class SpectralSpread < Base
+      feature :spectral_spread, dependencies: [:amplitude_spectrum, :spectral_centroid]
+
+      def self.extract(context)
+        amplitudes = context[:cache].fetch(:amplitude_spectrum)
+        centroid = context[:cache].fetch(:spectral_centroid)
+        total_amplitude = amplitudes.sum
+        return 0.0 if total_amplitude.zero?
+
+        frequency_step = frequency_step_for(amplitudes.length, context.fetch(:sample_rate))
+        weighted_variance = amplitudes.each_with_index.sum do |amplitude, index|
+          frequency = index * frequency_step
+          amplitude * ((frequency - centroid)**2)
+        end
+
+        Math.sqrt(weighted_variance / total_amplitude)
+      end
+
+      def self.frequency_step_for(length, sample_rate)
+        return 0.0 if length <= 1
+
+        fft_size = (length - 1) * 2
+        sample_rate.to_f / fft_size
+      end
+      private_class_method :frequency_step_for
+    end
+  end
+end

data/lib/sonus/features/windowed_signal.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Sonus
+  module Features
+    class WindowedSignal < Base
+      feature :windowed_signal, dependencies: [:buffer], public_feature: false
+
+      def self.extract(context)
+        Sonus::DSP::Windowing.apply(
+          context[:cache].fetch(:buffer),
+          context.fetch(:windowing_function)
+        )
+      end
+    end
+  end
+end

data/lib/sonus/features/zcr.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Sonus
+  module Features
+    class ZCR < Base
+      feature :zcr, dependencies: [:buffer]
+
+      def self.extract(context)
+        buffer = context[:cache].fetch(:buffer)
+
+        buffer.each_cons(2).count do |left, right|
+          (left >= 0.0 && right < 0.0) || (left < 0.0 && right >= 0.0)
+        end
+      end
+    end
+  end
+end

data/lib/sonus/features.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Sonus
+  module Features
+    @registry = {}
+
+    class << self
+      attr_reader :registry
+
+      def register(klass)
+        key = klass.feature_key
+        return if key.nil?
+
+        @registry[key] = klass
+      end
+
+      def public_feature_keys
+        @registry.each_with_object([]) do |(key, klass), features|
+          features << key if klass.public_feature?
+        end.sort
+      end
+
+      def compute(feature_keys, context, return_cache: false)
+        requested = normalize_feature_keys(feature_keys)
+        order = resolve_order(requested)
+
+        cache = {}
+        order.each do |key|
+          cache[key] = @registry.fetch(key).extract(context.merge(cache: cache))
+        end
+
+        result = requested.each_with_object({}) { |key, hash| hash[key] = cache[key] }
+        return [result, cache] if return_cache
+
+        result
+      end
+
+      def resolve_order(feature_keys)
+        state = {}
+        order = []
+
+        feature_keys.each do |key|
+          dfs_visit(key, state, order)
+        end
+
+        order
+      end
+
+      private
+
+      def normalize_feature_keys(feature_keys)
+        feature_keys.map do |feature_key|
+          normalized = feature_key.to_sym
+          next normalized if @registry.key?(normalized)
+
+          raise Sonus::InvalidFeatureError, "Unsupported feature: #{feature_key}"
+        end
+      end
+
+      def dfs_visit(feature_key, state, order)
+        case state[feature_key]
+        when :done
+          return
+        when :visiting
+          raise Sonus::InvalidFeatureError, "Circular dependency detected at #{feature_key}"
+        end
+
+        state[feature_key] = :visiting
+
+        klass = @registry[feature_key]
+        unless klass
+          raise Sonus::InvalidFeatureError, "Unsupported feature: #{feature_key}"
+        end
+
+        klass.dependencies.each do |dependency|
+          dfs_visit(dependency, state, order)
+        end
+
+        state[feature_key] = :done
+        order << feature_key
+      end
+    end
+  end
+end
+
+require_relative "features/base"
+require_relative "features/buffer"
+require_relative "features/windowed_signal"
+require_relative "features/complex_spectrum"
+require_relative "features/rms"
+require_relative "features/zcr"
+require_relative "features/energy"
+require_relative "features/amplitude_spectrum"
+require_relative "features/power_spectrum"
+require_relative "features/spectral_centroid"
+require_relative "features/spectral_flatness"
+require_relative "features/spectral_flux"
+require_relative "features/spectral_slope"
+require_relative "features/spectral_rolloff"
+require_relative "features/spectral_spread"
+require_relative "features/spectral_skewness"
+require_relative "features/spectral_kurtosis"
+require_relative "features/spectral_crest"
+require_relative "features/chroma"
+require_relative "features/loudness"
+require_relative "features/perceptual_spread"
+require_relative "features/perceptual_sharpness"
+require_relative "features/mfcc"
+require_relative "features/mel_bands"

data/lib/sonus/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Sonus
+  VERSION = "0.1.0"
+end

data/lib/sonus/wav/format.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Sonus
+  module WAV
+    Format = Struct.new(
+      :audio_format,
+      :channels,
+      :sample_rate,
+      :byte_rate,
+      :block_align,
+      :bit_depth,
+      keyword_init: true
+    )
+  end
+end

data/lib/sonus/wav/reader.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+module Sonus
+  module WAV
+    class Reader
+      attr_reader :format, :data_size
+
+      def initialize(path_or_io)
+        @io, @close_io = io_for(path_or_io)
+        @format, @data_offset, @data_size = parse_header
+        @frames = nil
+      rescue StandardError
+        close
+        raise
+      end
+
+      def sample_rate
+        @format.sample_rate
+      end
+
+      def channels
+        @format.channels
+      end
+
+      def bit_depth
+        @format.bit_depth
+      end
+
+      def duration
+        return 0.0 if sample_rate.zero?
+
+        frames.length / sample_rate.to_f
+      end
+
+      def frames
+        return @frames if @frames
+
+        @io.seek(@data_offset, IO::SEEK_SET)
+        data = @io.read(@data_size)
+        @frames = decode_frames(data)
+      end
+
+      def each_buffer(size)
+        raise ArgumentError, "size must be positive" unless size.to_i.positive?
+
+        return enum_for(:each_buffer, size) unless block_given?
+
+        current = 0
+        data = frames
+
+        while current < data.length
+          buffer = data.slice(current, size)
+          if buffer.length < size
+            buffer = buffer + Array.new(size - buffer.length, 0.0)
+          end
+
+          yield buffer
+          current += size
+        end
+      end
+
+      def close
+        return unless @close_io
+
+        @io.close unless @io.closed?
+      end
+
+      private
+
+      def io_for(path_or_io)
+        if path_or_io.respond_to?(:read) && path_or_io.respond_to?(:seek)
+          [path_or_io, false]
+        else
+          [File.open(path_or_io, "rb"), true]
+        end
+      end
+
+      def parse_header
+        @io.seek(0, IO::SEEK_SET)
+
+        riff = @io.read(4)
+        _riff_size = read_uint32
+        wave = @io.read(4)
+
+        unless riff == "RIFF" && wave == "WAVE"
+          raise Sonus::WAVFormatError, "Invalid WAV header"
+        end
+
+        format = nil
+        data_offset = nil
+        data_size = nil
+
+        until @io.eof?
+          chunk_id = @io.read(4)
+          break unless chunk_id && chunk_id.length == 4
+
+          chunk_size = read_uint32
+          chunk_start = @io.pos
+
+          case chunk_id
+          when "fmt "
+            format = parse_fmt_chunk(chunk_size)
+          when "data"
+            data_offset = @io.pos
+            data_size = chunk_size
+          else
+            @io.seek(chunk_size, IO::SEEK_CUR)
+          end
+
+          @io.seek(chunk_start + chunk_size + (chunk_size % 2), IO::SEEK_SET)
+        end
+
+        unless format
+          raise Sonus::WAVFormatError, "Missing fmt chunk"
+        end
+
+        unless data_offset && data_size
+          raise Sonus::WAVFormatError, "Missing data chunk"
+        end
+
+        [format, data_offset, data_size]
+      end
+
+      def parse_fmt_chunk(chunk_size)
+        raw = @io.read(chunk_size)
+        if raw.nil? || raw.length < 16
+          raise Sonus::WAVFormatError, "fmt chunk is too short"
+        end
+
+        audio_format, channels, sample_rate, byte_rate, block_align, bit_depth = raw.unpack("v v V V v v")
+
+        unless [1, 3].include?(audio_format)
+          raise Sonus::WAVFormatError, "Unsupported WAV audio format: #{audio_format}"
+        end
+
+        validate_bit_depth!(audio_format, bit_depth)
+
+        Sonus::WAV::Format.new(
+          audio_format: audio_format,
+          channels: channels,
+          sample_rate: sample_rate,
+          byte_rate: byte_rate,
+          block_align: block_align,
+          bit_depth: bit_depth
+        )
+      end
+
+      def validate_bit_depth!(audio_format, bit_depth)
+        supported = if audio_format == 1
+                      [8, 16, 24, 32]
+                    else
+                      [32, 64]
+                    end
+
+        return if supported.include?(bit_depth)
+
+        raise Sonus::WAVFormatError, "Unsupported bit depth #{bit_depth} for audio format #{audio_format}"
+      end
+
+      def decode_frames(data)
+        bytes_per_sample = @format.bit_depth / 8
+        frame_size = bytes_per_sample * @format.channels
+        frame_count = data.length / frame_size
+
+        Array.new(frame_count) do |index|
+          sample_offset = index * frame_size
+          sample_bytes = data.byteslice(sample_offset, bytes_per_sample)
+          decode_sample(sample_bytes)
+        end
+      end
+
+      def decode_sample(bytes)
+        case @format.audio_format
+        when 1
+          decode_pcm_sample(bytes)
+        when 3
+          decode_float_sample(bytes)
+        else
+          raise Sonus::WAVFormatError, "Unsupported audio format #{@format.audio_format}"
+        end
+      end
+
+      def decode_pcm_sample(bytes)
+        case @format.bit_depth
+        when 8
+          (bytes.unpack1("C") - 128) / 128.0
+        when 16
+          bytes.unpack1("s<") / 32_768.0
+        when 24
+          decode_int24(bytes) / 8_388_608.0
+        when 32
+          bytes.unpack1("l<") / 2_147_483_648.0
+        else
+          raise Sonus::WAVFormatError, "Unsupported PCM bit depth #{@format.bit_depth}"
+        end
+      end
+
+      def decode_float_sample(bytes)
+        case @format.bit_depth
+        when 32
+          bytes.unpack1("e")
+        when 64
+          bytes.unpack1("E")
+        else
+          raise Sonus::WAVFormatError, "Unsupported float bit depth #{@format.bit_depth}"
+        end
+      end
+
+      def decode_int24(bytes)
+        byte0, byte1, byte2 = bytes.unpack("C3")
+        value = byte0 | (byte1 << 8) | (byte2 << 16)
+        value -= 1 << 24 if (value & (1 << 23)) != 0
+        value
+      end
+
+      def read_uint32
+        bytes = @io.read(4)
+        raise Sonus::WAVFormatError, "Unexpected EOF while reading chunk size" unless bytes && bytes.length == 4
+
+        bytes.unpack1("V")
+      end
+    end
+  end
+end