sonus 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e8a628675bd2e5a3487629fefb877e0abbc037989f5deb2f0203be6b9c63d6ee
+  data.tar.gz: 915f50ac06a681866e77fbb74a08db79829f72625e7eb888de85c0aa7b9bdeaa
+SHA512:
+  metadata.gz: 504fbab955ddef73e4f39b789edfea5ccd52fbf00061f1bc12b796560cde37911b5c10e223d7a736b8d38f55025ee0d1434f2b1e0798a3197ecded6273d9a0c0
+  data.tar.gz: 8fbc1a63264627458b5e18a5227b22ef998818e3da52edf92cbf3c40e1d20b26b551570fae7c1b4b12d3d272329074e09f10e05c28d1f618f674c0d8667d4e3b

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## [0.1.0] - 2026-03-07
+
+- Initial release.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,314 @@
+# 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.
+
+## Highlights
+
+- 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
+
+## Installation
+
+Install the gem:
+
+```bash
+gem install sonus
+```
+
+Or add it to your Gemfile:
+
+```ruby
+gem "sonus"
+```
+
+### Optional FFTW acceleration
+
+`fftw3-ruby` is installed as a Sonus dependency.
+To enable the FFTW backend, install the native FFTW shared library on your system:
+
+```bash
+# macOS
+brew install fftw
+
+# Debian / Ubuntu
+sudo apt-get install libfftw3-dev
+```
+
+You can inspect or force the backend at runtime:
+
+```ruby
+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.
+
+## Quick Start
+
+Runnable scripts are available in `examples/`:
+
+- `examples/extract_basic.rb`
+- `examples/extract_spectral_flux.rb`
+- `examples/analyze_wav.rb`
+- `examples/read_wav.rb`
+
+### Single-frame extraction
+
+```ruby
+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
+```
+
+### Frame-based WAV analysis
+
+```ruby
+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
+```
+
+### WAV reading
+
+```ruby
+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
+```
+
+## Public API
+
+### `Sonus.extract`
+
+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`:
+
+```ruby
+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]
+```
+
+### `Sonus.extract_with_cache`
+
+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`.
+
+### `Sonus::Analyzer`
+
+Use `Sonus::Analyzer` for repeated frame analysis with stable configuration.
+
+```ruby
+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`
+
+`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
+
+## Features
+
+Inspect the public feature set at runtime:
+
+```ruby
+Sonus.available_features
+Sonus.list_available_feature_extractors
+```
+
+Current public features:
+
+### Time-domain and raw outputs
+
+- `:buffer`
+- `:rms`
+- `:zcr`
+- `:energy`
+- `:complex_spectrum`
+- `:amplitude_spectrum`
+- `:power_spectrum`
+
+### Spectral features
+
+- `:spectral_centroid`
+- `:spectral_flatness`
+- `:spectral_flux`
+- `:spectral_slope`
+- `:spectral_rolloff`
+- `:spectral_spread`
+- `:spectral_skewness`
+- `:spectral_kurtosis`
+- `:spectral_crest`
+- `:chroma`
+- `:mel_bands`
+- `:mfcc`
+
+### Perceptual features
+
+- `:loudness`
+- `:perceptual_spread`
+- `:perceptual_sharpness`
+
+## Configuration
+
+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:`
+
+## Errors
+
+Sonus raises domain-specific errors for common failure cases:
+
+- `Sonus::InvalidSignalError`
+- `Sonus::InvalidFeatureError`
+- `Sonus::WAVFormatError`
+- `Sonus::FFTBackendError`
+
+## Development
+
+Install dependencies:
+
+```bash
+bundle install
+```
+
+Run tests:
+
+```bash
+bundle exec rspec
+bundle exec rake
+```
+
+Run the benchmark:
+
+```bash
+bundle exec ruby benchmark/extract_all_features.rb
+```
+
+## Contributing
+
+Pull requests and issue reports are welcome.
+
+## License
+
+MIT License.

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/benchmark/extract_all_features.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "benchmark/ips"
+require "sonus"
+
+sample_rate = 44_100
+buffer = Array.new(1024) { |i| Math.sin((2.0 * Math::PI * 440.0 * i) / sample_rate) }
+features = Sonus.available_features
+
+Benchmark.ips do |x|
+  x.report("extract_all_features") do
+    Sonus.extract(buffer, features, buffer_size: 1024, sample_rate: sample_rate)
+  end
+
+  x.compare!
+end

data/examples/analyze_wav.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "example_helper"
+
+wav_path = ExampleHelper.mono_wav_path
+
+analyzer = Sonus::Analyzer.new(
+  buffer_size: 1024,
+  hop_size: 512,
+  sample_rate: 44_100,
+  features: %i[rms spectral_centroid spectral_flux]
+)
+
+results = analyzer.analyze_file(wav_path)
+first_frame = results.first
+
+puts "analyze_file_frame_count: #{results.length}"
+puts "first_frame_rms: #{format("%.6f", first_frame[:rms])}"
+puts "first_frame_centroid_hz: #{format("%.2f", first_frame[:spectral_centroid])}"
+puts "first_frame_flux: #{format("%.6f", first_frame[:spectral_flux])}"
+
+puts "first_three_rms_from_each_frame:"
+analyzer.each_frame(wav_path).first(3).each_with_index do |frame, index|
+  puts "  frame_#{index}: #{format("%.6f", frame[:rms])}"
+end

data/examples/example_helper.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "tempfile"
+
+begin
+  require "bundler/setup"
+rescue LoadError
+  nil
+end
+
+begin
+  require "sonus"
+rescue LoadError
+  require_relative "../lib/sonus"
+end
+
+module ExampleHelper
+  module_function
+
+  TEMPFILES = []
+
+  def fixture_path(name)
+    File.expand_path("../spec/fixtures/#{name}", __dir__)
+  end
+
+  def mono_wav_path
+    wav_path("sine_440hz_16bit.wav", channels: 1)
+  end
+
+  def stereo_wav_path
+    wav_path("stereo_16bit.wav", channels: 2)
+  end
+
+  def wav_path(name, channels:)
+    path = fixture_path(name)
+    return path if File.exist?(path)
+
+    generate_wav(name, channels: channels)
+  end
+
+  def generate_wav(name, channels:, sample_rate: 44_100, frame_count: 44_100, frequency: 440.0)
+    tempfile = Tempfile.new([File.basename(name, ".wav"), ".wav"])
+    tempfile.binmode
+
+    data = Array.new(frame_count) do |index|
+      sample = Math.sin((2.0 * Math::PI * frequency * index) / sample_rate)
+      frame_bytes(sample, channels)
+    end.join
+
+    tempfile.write(wav_bytes(data, channels: channels, sample_rate: sample_rate))
+    tempfile.flush
+    TEMPFILES << tempfile
+    tempfile.path
+  end
+
+  def frame_bytes(sample, channels)
+    left = pcm16_bytes(sample)
+    return left if channels == 1
+
+    right = pcm16_bytes(sample * 0.5)
+    left + right
+  end
+
+  def pcm16_bytes(sample)
+    clipped = [[sample, -1.0].max, 1.0].min
+    [(clipped * 32_767).round].pack("s<")
+  end
+
+  def wav_bytes(data, channels:, sample_rate:)
+    bits_per_sample = 16
+    block_align = channels * (bits_per_sample / 8)
+    byte_rate = sample_rate * block_align
+    riff_size = 36 + data.bytesize
+
+    +"RIFF" \
+      << [riff_size].pack("V") \
+      << "WAVE" \
+      << "fmt " \
+      << [16, 1, channels, sample_rate, byte_rate, block_align, bits_per_sample].pack("VvvVVvv") \
+      << "data" \
+      << [data.bytesize].pack("V") \
+      << data
+  end
+end

data/examples/extract_basic.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative "example_helper"
+
+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,
+  number_of_mfcc_coefficients: 13
+)
+
+puts "rms: #{format("%.6f", features[:rms])}"
+puts "spectral_centroid_hz: #{format("%.2f", features[:spectral_centroid])}"
+puts "mfcc_count: #{features[:mfcc].length}"
+puts "mfcc_first_3: #{features[:mfcc].first(3).map { |value| format("%.4f", value) }.join(", ")}"

data/examples/extract_spectral_flux.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "example_helper"
+
+sample_rate = 44_100
+buffer_size = 512
+
+previous_signal = Array.new(buffer_size, 0.0)
+current_signal = Array.new(buffer_size) do |index|
+  Math.sin((2.0 * Math::PI * 440.0 * index) / sample_rate)
+end
+
+from_previous_signal = Sonus.extract(
+  current_signal,
+  :spectral_flux,
+  buffer_size: buffer_size,
+  sample_rate: sample_rate,
+  previous_signal: previous_signal
+)
+
+previous_spectrum = Sonus.extract(
+  previous_signal,
+  :amplitude_spectrum,
+  buffer_size: buffer_size,
+  sample_rate: sample_rate
+)
+
+from_previous_spectrum = Sonus.extract(
+  current_signal,
+  :spectral_flux,
+  buffer_size: buffer_size,
+  sample_rate: sample_rate,
+  prev_amplitude_spectrum: previous_spectrum[:amplitude_spectrum]
+)
+
+puts "spectral_flux_from_previous_signal: #{format("%.6f", from_previous_signal[:spectral_flux])}"
+puts "spectral_flux_from_previous_spectrum: #{format("%.6f", from_previous_spectrum[:spectral_flux])}"

data/examples/read_wav.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative "example_helper"
+
+wav_path = ExampleHelper.stereo_wav_path
+reader = Sonus::WAV::Reader.new(wav_path)
+
+begin
+  first_buffer = reader.each_buffer(2048).first
+
+  puts "sample_rate: #{reader.sample_rate}"
+  puts "channels: #{reader.channels}"
+  puts "bit_depth: #{reader.bit_depth}"
+  puts "duration_seconds: #{format("%.3f", reader.duration)}"
+  puts "decoded_frame_count: #{reader.frames.length}"
+  puts "first_buffer_first_5: #{first_buffer.first(5).map { |value| format("%.4f", value) }.join(", ")}"
+ensure
+  reader.close
+end

data/lib/sonus/analyzer.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Sonus
+  class Analyzer
+    attr_reader :buffer_size, :sample_rate, :features, :hop_size, :windowing_function
+
+    def initialize(
+      buffer_size: Sonus::DEFAULT_BUFFER_SIZE,
+      sample_rate: Sonus::DEFAULT_SAMPLE_RATE,
+      features: [:rms],
+      hop_size: nil,
+      windowing_function: Sonus::DEFAULT_WINDOWING_FUNCTION,
+      number_of_mfcc_coefficients: Sonus::DEFAULT_MFCC_COEFFICIENTS,
+      number_of_mel_filters: Sonus::DEFAULT_MEL_FILTERS,
+      mel_bands: nil,
+      number_of_chroma_bands: Sonus::DEFAULT_CHROMA_BANDS,
+      chroma_bands: nil,
+      number_of_bark_bands: Sonus::DEFAULT_BARK_BANDS
+    )
+      @buffer_size = Integer(buffer_size)
+      @sample_rate = Float(sample_rate)
+      @features = Array(features).map(&:to_sym)
+      @hop_size = hop_size ? Integer(hop_size) : @buffer_size
+      @windowing_function = windowing_function.to_sym
+      @number_of_mfcc_coefficients = Integer(number_of_mfcc_coefficients)
+      @number_of_mel_filters = Integer(mel_bands || number_of_mel_filters)
+      @number_of_chroma_bands = Integer(chroma_bands || number_of_chroma_bands)
+      @number_of_bark_bands = Integer(number_of_bark_bands)
+      @prev_amplitude_spectrum = nil
+
+      raise ArgumentError, "buffer_size must be positive" unless @buffer_size.positive?
+      raise ArgumentError, "hop_size must be positive" unless @hop_size.positive?
+
+      preload_mel_filter_bank
+    end
+
+    def analyze(buffer)
+      result, cache = Sonus.extract_with_cache(
+        buffer,
+        @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,
+        number_of_chroma_bands: @number_of_chroma_bands,
+        number_of_bark_bands: @number_of_bark_bands,
+        prev_amplitude_spectrum: @prev_amplitude_spectrum
+      )
+
+      @prev_amplitude_spectrum = cache[:amplitude_spectrum] if cache.key?(:amplitude_spectrum)
+      result
+    end
+
+    def analyze_file(path)
+      frames = []
+      each_frame(path) { |features| frames << features }
+      frames
+    end
+
+    def each_frame(path)
+      return enum_for(:each_frame, path) unless block_given?
+
+      reader = Sonus::WAV::Reader.new(path)
+      begin
+        @prev_amplitude_spectrum = nil
+        validate_reader_sample_rate!(reader)
+        signal = reader.frames
+        each_signal_frame(signal) { |buffer| yield analyze(buffer) }
+      ensure
+        reader.close
+      end
+
+      nil
+    end
+
+    private
+
+    def each_signal_frame(signal)
+      total_samples = signal.length
+      frame_count = if total_samples <= @buffer_size
+                      1
+                    else
+                      ((total_samples - @buffer_size).fdiv(@hop_size).ceil) + 1
+                    end
+
+      frame_count.times do |frame_index|
+        start_index = frame_index * @hop_size
+        frame = signal.slice(start_index, @buffer_size) || []
+        frame += Array.new(@buffer_size - frame.length, 0.0) if frame.length < @buffer_size
+        yield frame
+      end
+    end
+
+    def validate_reader_sample_rate!(reader)
+      return if reader.sample_rate.to_f == @sample_rate
+
+      raise ArgumentError, "Analyzer sample_rate (#{@sample_rate}) does not match WAV sample_rate (#{reader.sample_rate})"
+    end
+
+    def preload_mel_filter_bank
+      Sonus::DSP::MelFilterBank.create(
+        num_filters: @number_of_mel_filters,
+        fft_size: @buffer_size,
+        sample_rate: @sample_rate
+      )
+    end
+  end
+end