Sonus

Sonus is a Ruby audio feature extraction library for in-memory signals and WAV files. It exposes a small public API around feature extraction, frame-based analysis, and WAV decoding.

Sonus always works with the built-in Ruby FFT backend, and automatically uses FFTW through fftw3-ruby when the system FFTW library is available.

• Ruby >= 3.1
• Single-frame extraction with Sonus.extract
• Cached extraction with Sonus.extract_with_cache
• Frame-by-frame WAV analysis with Sonus::Analyzer
• WAV decoding and inspection with Sonus::WAV::Reader
• Pure Ruby FFT fallback with optional FFTW acceleration

Install the gem:

gem install sonus

Or add it to your Gemfile:

gem "sonus"

fftw3-ruby is installed as a Sonus dependency. To enable the FFTW backend, install the native FFTW shared library on your system:

# macOS
brew install fftw

# Debian / Ubuntu
sudo apt-get install libfftw3-dev

You can inspect or force the backend at runtime:

require "sonus"

Sonus::DSP::FFT.backend
# => :ruby or :fftw

Sonus::DSP::FFT.backend = :ruby
Sonus::DSP::FFT.backend = :fftw

Setting :fftw raises Sonus::FFTBackendError when FFTW is unavailable.

Runnable scripts are available in examples/:

• examples/extract_basic.rb
• examples/extract_spectral_flux.rb
• examples/analyze_wav.rb
• examples/read_wav.rb

require "sonus"

sample_rate = 44_100
buffer_size = 512

signal = Array.new(buffer_size) do |index|
  Math.sin((2.0 * Math::PI * 440.0 * index) / sample_rate)
end

features = Sonus.extract(
  signal,
  %i[rms spectral_centroid mfcc],
  buffer_size: buffer_size,
  sample_rate: sample_rate
)

puts features[:rms]
puts features[:spectral_centroid]
puts features[:mfcc].length

require "sonus"

analyzer = Sonus::Analyzer.new(
  buffer_size: 1024,
  hop_size: 512,
  sample_rate: 44_100,
  features: %i[rms spectral_flux mfcc]
)

results = analyzer.analyze_file("audio.wav")
puts results.first[:rms]

analyzer.each_frame("audio.wav").first(3).each do |frame|
  puts frame[:spectral_flux]
end

require "sonus"

reader = Sonus::WAV::Reader.new("audio.wav")

puts reader.sample_rate
puts reader.channels
puts reader.bit_depth
puts reader.duration

samples = reader.frames
reader.close

Use Sonus.extract(signal, features, **options) for one analysis frame. It returns a hash containing only the requested public features.

Important behavior:

• signal must be an Array or respond to #to_a
• signal values must be finite numeric values
• shorter input is zero-padded to buffer_size
• longer input is truncated to the first buffer_size samples
• feature dependencies are resolved automatically
• features can be a symbol, string, or array of them

For previous-frame features such as :spectral_flux, pass either previous_signal or prev_amplitude_spectrum:

previous = Array.new(512, 0.0)
current = Array.new(512) { |i| Math.sin((2.0 * Math::PI * 440.0 * i) / 44_100.0) }

result = Sonus.extract(
  current,
  :spectral_flux,
  buffer_size: 512,
  sample_rate: 44_100,
  previous_signal: previous
)

puts result[:spectral_flux]

Use Sonus.extract_with_cache when you need both the requested result and intermediate feature values. It returns [result, cache], where result includes only requested public features and cache includes dependency outputs as well.

This is the API used internally by Sonus::Analyzer.

Use Sonus::Analyzer for repeated frame analysis with stable configuration.

analyzer = Sonus::Analyzer.new(
  buffer_size: 1024,
  hop_size: 512,
  sample_rate: 44_100,
  features: %i[rms spectral_centroid]
)

analyzer.analyze(Array.new(1024, 1.0))
analyzer.analyze_file("audio.wav")
analyzer.each_frame("audio.wav")

Important behavior:

• features: defaults to [:rms]
• hop_size defaults to buffer_size
• overlapping analysis is supported with hop_size < buffer_size
• each_frame(path) returns an enumerator when no block is given
• sample_rate must match the WAV file sample rate for analyze_file and each_frame
• previous-frame state is reset at the start of each each_frame run

Sonus::WAV::Reader accepts a filesystem path or an IO object that responds to #read and #seek.

Supported WAV input:

• PCM: 8-bit, 16-bit, 24-bit, 32-bit
• IEEE float: 32-bit, 64-bit
• mono and multi-channel files

Important behavior:

• frames returns normalized floats
• for multi-channel files, Sonus decodes the first channel of each frame
• each_buffer(size) returns an enumerator when no block is given
• each_buffer(size) zero-pads the final buffer

Inspect the public feature set at runtime:

Sonus.available_features
Sonus.list_available_feature_extractors

Current public features:

• :buffer
• :rms
• :zcr
• :energy
• :complex_spectrum
• :amplitude_spectrum
• :power_spectrum

• :spectral_centroid
• :spectral_flatness
• :spectral_flux
• :spectral_slope
• :spectral_rolloff
• :spectral_spread
• :spectral_skewness
• :spectral_kurtosis
• :spectral_crest
• :chroma
• :mel_bands
• :mfcc

• :loudness
• :perceptual_spread
• :perceptual_sharpness

Default values:

• buffer_size = 512
• sample_rate = 44_100
• windowing_function = :hanning
• number_of_mfcc_coefficients = 13
• number_of_mel_filters = 26
• number_of_chroma_bands = 12
• number_of_bark_bands = 24

Supported windowing functions:

• :rect
• :hann
• :hanning
• :hamming
• :blackman
• :sine

Supported aliases:

• mel_bands: for number_of_mel_filters:
• chroma_bands: for number_of_chroma_bands:

Sonus raises domain-specific errors for common failure cases:

• Sonus::InvalidSignalError
• Sonus::InvalidFeatureError
• Sonus::WAVFormatError
• Sonus::FFTBackendError

Install dependencies:

bundle install

Run tests:

bundle exec rspec
bundle exec rake

Run the benchmark:

bundle exec ruby benchmark/extract_all_features.rb

Pull requests and issue reports are welcome.

MIT License.