sonus 0.1.0

data/lib/sonus.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+require_relative "sonus/version"
+require_relative "sonus/error"
+require_relative "sonus/dsp/windowing"
+require_relative "sonus/dsp/fft_backend/ruby"
+require_relative "sonus/dsp/fft_backend/fftw"
+require_relative "sonus/dsp/fft"
+require_relative "sonus/dsp/mel_filter_bank"
+require_relative "sonus/wav/format"
+require_relative "sonus/wav/reader"
+require_relative "sonus/features"
+require_relative "sonus/analyzer"
+
+module Sonus
+  DEFAULT_BUFFER_SIZE = 512
+  DEFAULT_SAMPLE_RATE = 44_100
+  DEFAULT_WINDOWING_FUNCTION = :hanning
+  DEFAULT_MFCC_COEFFICIENTS = 13
+  DEFAULT_MEL_FILTERS = 26
+  DEFAULT_CHROMA_BANDS = 12
+  DEFAULT_BARK_BANDS = 24
+
+  class << self
+    def extract(
+      signal,
+      features,
+      buffer_size: DEFAULT_BUFFER_SIZE,
+      sample_rate: DEFAULT_SAMPLE_RATE,
+      windowing_function: DEFAULT_WINDOWING_FUNCTION,
+      number_of_mfcc_coefficients: DEFAULT_MFCC_COEFFICIENTS,
+      number_of_mel_filters: DEFAULT_MEL_FILTERS,
+      mel_bands: nil,
+      number_of_chroma_bands: DEFAULT_CHROMA_BANDS,
+      chroma_bands: nil,
+      number_of_bark_bands: DEFAULT_BARK_BANDS,
+      previous_signal: nil,
+      prev_amplitude_spectrum: nil
+    )
+      result, = extract_with_cache(
+        signal,
+        features,
+        buffer_size: buffer_size,
+        sample_rate: sample_rate,
+        windowing_function: windowing_function,
+        number_of_mfcc_coefficients: number_of_mfcc_coefficients,
+        number_of_mel_filters: number_of_mel_filters,
+        mel_bands: mel_bands,
+        number_of_chroma_bands: number_of_chroma_bands,
+        chroma_bands: chroma_bands,
+        number_of_bark_bands: number_of_bark_bands,
+        previous_signal: previous_signal,
+        prev_amplitude_spectrum: prev_amplitude_spectrum
+      )
+      result
+    end
+
+    def extract_with_cache(
+      signal,
+      features,
+      buffer_size: DEFAULT_BUFFER_SIZE,
+      sample_rate: DEFAULT_SAMPLE_RATE,
+      windowing_function: DEFAULT_WINDOWING_FUNCTION,
+      number_of_mfcc_coefficients: DEFAULT_MFCC_COEFFICIENTS,
+      number_of_mel_filters: DEFAULT_MEL_FILTERS,
+      mel_bands: nil,
+      number_of_chroma_bands: DEFAULT_CHROMA_BANDS,
+      chroma_bands: nil,
+      number_of_bark_bands: DEFAULT_BARK_BANDS,
+      previous_signal: nil,
+      prev_amplitude_spectrum: nil
+    )
+      normalized_features = normalize_features(features)
+      normalized_buffer_size = Integer(buffer_size)
+      normalized_sample_rate = Float(sample_rate)
+      normalized_mel_filters = normalize_or_default(mel_bands, number_of_mel_filters)
+      normalized_chroma_bands = normalize_or_default(chroma_bands, number_of_chroma_bands)
+
+      validate_options!(
+        buffer_size: normalized_buffer_size,
+        sample_rate: normalized_sample_rate,
+        number_of_mfcc_coefficients: number_of_mfcc_coefficients,
+        number_of_mel_filters: normalized_mel_filters,
+        number_of_chroma_bands: normalized_chroma_bands,
+        number_of_bark_bands: number_of_bark_bands
+      )
+
+      validated_signal = validate_signal!(signal)
+      frame = normalize_signal_to_frame(validated_signal, normalized_buffer_size)
+      normalized_previous_signal = normalize_previous_signal(previous_signal, normalized_buffer_size)
+      previous_amplitude = resolve_previous_amplitude_spectrum(
+        prev_amplitude_spectrum: prev_amplitude_spectrum,
+        previous_signal: normalized_previous_signal,
+        windowing_function: windowing_function
+      )
+
+      context = {
+        buffer: frame,
+        buffer_size: normalized_buffer_size,
+        sample_rate: normalized_sample_rate,
+        windowing_function: windowing_function.to_sym,
+        number_of_mfcc_coefficients: Integer(number_of_mfcc_coefficients),
+        number_of_mel_filters: Integer(normalized_mel_filters),
+        number_of_chroma_bands: Integer(normalized_chroma_bands),
+        number_of_bark_bands: Integer(number_of_bark_bands),
+        previous_signal: normalized_previous_signal,
+        prev_amplitude_spectrum: previous_amplitude
+      }
+
+      Features.compute(normalized_features, context, return_cache: true)
+    end
+
+    def available_features
+      Features.public_feature_keys
+    end
+
+    def list_available_feature_extractors
+      available_features
+    end
+
+    def windowing(signal, function_name)
+      DSP::Windowing.apply(validate_signal!(signal), function_name)
+    end
+
+    private
+
+    def validate_options!(
+      buffer_size:,
+      sample_rate:,
+      number_of_mfcc_coefficients:,
+      number_of_mel_filters:,
+      number_of_chroma_bands:,
+      number_of_bark_bands:
+    )
+      raise ArgumentError, "buffer_size must be positive" unless buffer_size.positive?
+      raise ArgumentError, "sample_rate must be positive" unless sample_rate.positive?
+      raise ArgumentError, "number_of_mfcc_coefficients must be positive" unless Integer(number_of_mfcc_coefficients).positive?
+      raise ArgumentError, "number_of_mel_filters must be positive" unless Integer(number_of_mel_filters).positive?
+      raise ArgumentError, "number_of_chroma_bands must be positive" unless Integer(number_of_chroma_bands).positive?
+      raise ArgumentError, "number_of_bark_bands must be positive" unless Integer(number_of_bark_bands).positive?
+    end
+
+    def normalize_features(features)
+      feature_list = Array(features)
+      raise InvalidFeatureError, "At least one feature must be provided" if feature_list.empty?
+
+      feature_list.map do |feature|
+        feature.to_sym
+      rescue NoMethodError
+        raise InvalidFeatureError, "Feature names must be symbols or strings"
+      end.uniq
+    end
+
+    def validate_signal!(signal)
+      unless signal.is_a?(Array) || signal.respond_to?(:to_a)
+        raise InvalidSignalError, "Signal must be an Array of Numeric values"
+      end
+
+      signal_values = signal.to_a
+
+      if signal_values.empty?
+        raise InvalidSignalError, "Signal cannot be empty"
+      end
+
+      signal_values.each do |value|
+        unless value.is_a?(Numeric)
+          raise InvalidSignalError, "Signal contains a non-numeric value"
+        end
+
+        next if value.finite?
+
+        raise InvalidSignalError, "Signal contains NaN or Infinity"
+      end
+
+      signal_values.map(&:to_f)
+    end
+
+    def normalize_signal_to_frame(signal, buffer_size)
+      frame = signal.first(buffer_size)
+      return frame if frame.length == buffer_size
+
+      frame + Array.new(buffer_size - frame.length, 0.0)
+    end
+
+    def normalize_previous_signal(signal, buffer_size)
+      return nil if signal.nil?
+
+      normalized = validate_signal!(signal)
+      normalize_signal_to_frame(normalized, buffer_size)
+    end
+
+    def resolve_previous_amplitude_spectrum(prev_amplitude_spectrum:, previous_signal:, windowing_function:)
+      return prev_amplitude_spectrum.map(&:to_f) if prev_amplitude_spectrum
+      return nil unless previous_signal
+
+      windowed = DSP::Windowing.apply(previous_signal, windowing_function)
+      DSP::FFT.amplitude_spectrum(windowed)
+    end
+
+    def normalize_or_default(alias_value, default_value)
+      alias_value.nil? ? default_value : alias_value
+    end
+  end
+end

metadata

@@ -0,0 +1,160 @@
+--- !ruby/object:Gem::Specification
+name: sonus
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Yudai Takada
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: fftw3-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+- !ruby/object:Gem::Dependency
+  name: benchmark-ips
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.12'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: Sonus extracts time-domain, spectral, and perceptual audio features in
+  pure Ruby with optional FFTW acceleration.
+email:
+- t.yudai92@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- benchmark/extract_all_features.rb
+- examples/analyze_wav.rb
+- examples/example_helper.rb
+- examples/extract_basic.rb
+- examples/extract_spectral_flux.rb
+- examples/read_wav.rb
+- lib/sonus.rb
+- lib/sonus/analyzer.rb
+- lib/sonus/dsp/fft.rb
+- lib/sonus/dsp/fft_backend/fftw.rb
+- lib/sonus/dsp/fft_backend/ruby.rb
+- lib/sonus/dsp/mel_filter_bank.rb
+- lib/sonus/dsp/windowing.rb
+- lib/sonus/error.rb
+- lib/sonus/features.rb
+- lib/sonus/features/amplitude_spectrum.rb
+- lib/sonus/features/base.rb
+- lib/sonus/features/buffer.rb
+- lib/sonus/features/chroma.rb
+- lib/sonus/features/complex_spectrum.rb
+- lib/sonus/features/energy.rb
+- lib/sonus/features/loudness.rb
+- lib/sonus/features/mel_bands.rb
+- lib/sonus/features/mfcc.rb
+- lib/sonus/features/perceptual_sharpness.rb
+- lib/sonus/features/perceptual_spread.rb
+- lib/sonus/features/power_spectrum.rb
+- lib/sonus/features/rms.rb
+- lib/sonus/features/spectral_centroid.rb
+- lib/sonus/features/spectral_crest.rb
+- lib/sonus/features/spectral_flatness.rb
+- lib/sonus/features/spectral_flux.rb
+- lib/sonus/features/spectral_kurtosis.rb
+- lib/sonus/features/spectral_rolloff.rb
+- lib/sonus/features/spectral_skewness.rb
+- lib/sonus/features/spectral_slope.rb
+- lib/sonus/features/spectral_spread.rb
+- lib/sonus/features/windowed_signal.rb
+- lib/sonus/features/zcr.rb
+- lib/sonus/version.rb
+- lib/sonus/wav/format.rb
+- lib/sonus/wav/reader.rb
+homepage: https://github.com/ydah/sonus
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/ydah/sonus
+  source_code_uri: https://github.com/ydah/sonus/tree/main
+  changelog_uri: https://github.com/ydah/sonus/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.6
+specification_version: 4
+summary: Audio feature extraction library for Ruby
+test_files: []