dsprb 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f9551a9c99d503314354a81f6b445eef6c0c29181d55907581856bc1904c2494
+  data.tar.gz: ebd353edf01ff2a5f1e5694d74f781858a0f7640861e3cd502ce127e6e48b6b5
+SHA512:
+  metadata.gz: 3a33aeb3039a94a7edbbede3b95514cffca4e49612c1b1d6f241a1034a5ae5a558eead65f286cc58596466578baf18841b4bf703f027d379a01b96c52b7e39e7
+  data.tar.gz: 673fad7a2420db7c4463edd9b68dd776f8b955b3374a9586e721a993ba648e20df63bd1ac2b67228b1a0cd3a29b223ba1e6ab64b486ed14b7c139ca3eb4b0013

data/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## 1.0.0 — 2026-08-01
+
+Initial public release.
+
+- WAV decoding for 8, 16, 24 and 32 bit PCM and 32 and 64 bit IEEE float, including
+  WAVE_FORMAT_EXTENSIBLE, with channel downmixing (`DSP::Wav`, `DSP::Waveform`)
+- Radix-2 FFT with precomputed twiddle factors and power spectra (`DSP::Fourier`, `DSP::Spectrum`)
+- Generalized cosine windows: Hamming, Hann, Blackman, rectangular (`DSP::Window`)
+- Framing and first-order preemphasis (`DSP::Framing`)
+- Mel and semitone scales, mel filterbanks with vocal tract length warping, DCT-II and MFCC
+  (`DSP::Scales`, `DSP::MelFilterbank`, `DSP::Dct`, `DSP::Mfcc`)
+- YIN fundamental frequency estimation with parabolic period refinement (`DSP::Yin`,
+  `DSP::PitchTrack`)
+- Linear predictive coding by the Levinson-Durbin recursion, with the all-pole spectral envelope
+  and formant extraction (`DSP::Autocorrelation`, `DSP::Lpc`, `DSP::Formants`)
+- Spectral moments, short-term energy, zero crossing rate and decibel envelopes
+  (`DSP::SpectralMoments`, `DSP::Energy`)
+- Butterworth biquads and windowed-sinc decimation (`DSP::Biquad`, `DSP::Decimator`)
+- Linear contour resampling (`DSP::Curve`)
+- RBS signatures under `sig/`

data/LICENSE

@@ -0,0 +1,13 @@
+            DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
+                    Version 2, December 2004
+
+ Copyright (C) 2026 Den Patin <hi@dpat.in>
+
+ Everyone is permitted to copy and distribute verbatim or modified
+ copies of this license document, and changing it is allowed as long
+ as the name is changed.
+
+            DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
+   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+  0. You just DO WHAT THE FUCK YOU WANT TO.

data/README.md

@@ -0,0 +1,193 @@
+# dsprb
+
+Speech signal processing and acoustic feature extraction in pure Ruby. No dependencies, no native
+extensions, no pseudo-random number generator anywhere.
+
+Extracted from [taiwancards](https://github.com/taiwancards/taiwancards), where it turns learner
+recordings into the feature sequences its pronunciation scorer compares.
+
+## The problem
+
+A waveform is a poor representation for comparison. Two recordings of the same syllable differ in
+amplitude, in microphone response, in speaking rate, and in every sample value, while agreeing on
+everything a listener perceives: the pitch contour, the resonances of the vocal tract, the noise
+spectrum of the fricatives.
+
+Extracting those invariants is the work of acoustic phonetics, and it decomposes into a small set
+of classical algorithms. This library implements them directly: framing and windowing, the discrete
+Fourier transform, mel filterbanks and the cepstrum, the YIN period estimator, linear prediction
+and its all-pole envelope, spectral moments, and the filters that condition a signal beforehand.
+
+## Install
+
+```ruby
+gem "dsprb"
+```
+
+## Waveforms
+
+`DSP::Wav` decodes 8, 16, 24 and 32 bit PCM as well as 32 and 64 bit IEEE float, including
+`WAVE_FORMAT_EXTENSIBLE`, and downmixes multi-channel streams to mono. Everything downstream takes
+a `DSP::Waveform`, so the sample rate travels with the samples and cannot be mismatched by accident.
+
+```ruby
+require "dsprb"
+
+signal = DSP.read("utterance.wav")
+
+signal.length       # => 16000
+signal.sample_rate  # => 16000.0
+signal.duration     # => 1.0
+signal.nyquist      # => 8000.0
+```
+
+Signals synthesized in memory are ordinary arrays:
+
+```ruby
+signal = DSP::Waveform.new(samples: samples, sample_rate: 16_000)
+```
+
+## Fundamental frequency
+
+`DSP::Yin` implements the YIN estimator: squared difference over lag, cumulative mean
+normalization, absolute-threshold period selection, and parabolic refinement of the chosen minimum.
+The signal is decimated to a working rate before the search, which is what makes an O(window × lag)
+method affordable in Ruby.
+
+```ruby
+track = DSP.pitch(signal)
+
+track.length        # => 120
+track.hop_seconds   # => 0.008
+track.voiced_ratio  # => 1.0
+track.voiced_f0     # => [196.08, ...]
+
+track.each_voiced { |frequency, time, confidence| ... }
+```
+
+Unvoiced frames report `0.0` rather than `nil`, so a track is always a dense numeric sequence.
+Confidence is `1 - d'(τ)`, the depth of the selected minimum.
+
+## Cepstral features
+
+`DSP::Mfcc` composes a power spectrum, a mel filterbank and a DCT-II. The filterbank supports
+vocal tract length warping, which rescales the band centers to compensate for speaker anatomy.
+
+```ruby
+frames = DSP.mfcc(signal)
+
+frames.length      # => 98
+frames.first.length # => 13
+```
+
+The pieces stay separately usable, so a log-mel spectrogram costs one call:
+
+```ruby
+spectrum = DSP::Spectrum.new(512)
+filterbank = DSP::MelFilterbank.new(sample_rate: 16_000, size: 512, filters: 26, warp: 1.05)
+
+log_mel = signal.frames(window: 400, hop: 160).map do |frame|
+  filterbank.log_energies(spectrum.power(DSP::Window.apply(frame, DSP::Window.hamming(400))))
+end
+```
+
+## Resonances
+
+`DSP::Lpc` fits an all-pole model by the Levinson-Durbin recursion and exposes the spectral
+envelope it implies. `DSP::Formants` picks the envelope maxima, refines them parabolically on the
+log magnitude, and merges peaks that a single resonance split in two.
+
+```ruby
+DSP.formants(vowel)
+# => [752.8, 2335.8, 3695.6, 5416.1]
+
+DSP::Formants.new.peaks(vowel).first.amplitude
+# => 2.91
+```
+
+The predictor itself is available when the envelope matters more than the peaks:
+
+```ruby
+model = DSP::Lpc.solve(frame, order: 10)
+
+model.order              # => 10
+model.error              # => residual energy of the prediction
+model.envelope(points: 512)
+```
+
+## Spectral moments
+
+Centroid, spread, skewness and excess kurtosis of the power spectrum over a chosen band. These are
+the standard descriptors of fricative noise, where place of articulation shifts the centroid.
+
+```ruby
+moments = DSP::SpectralMoments.of(power, sample_rate: 16_000, size: 1024, low: 500.0)
+
+moments.centroid  # => 4904.8
+moments.spread    # => 1064.8
+moments.skewness  # => 0.742
+moments.kurtosis  # => -0.708
+```
+
+## Energy, filters, resampling
+
+```ruby
+DSP::Energy.frame_db(frame)                                  # root mean square, in decibels
+DSP::Energy.zero_crossing_rate(frame)                        # crossings per sample interval
+DSP::Energy.envelope_db(samples, window: 400, hop: 160)      # sliding energy, one value per hop
+
+DSP.highpass(signal, cutoff: 60.0)                           # removes rumble and DC offset
+DSP.lowpass(signal, cutoff: 4000.0, sections: 2)             # cascaded Butterworth sections
+DSP.decimate(signal, 4)                                      # windowed-sinc anti-aliasing
+
+DSP::Curve.resample(contour, 16)                             # contours onto a common grid
+DSP::Scales.hz_to_semitones(392.0, reference: 196.0)         # => 12.0
+```
+
+## In practice
+
+[taiwancards](https://github.com/taiwancards/taiwancards) teaches Taiwanese Mandarin and scores
+learner recordings against native templates. Its analysis stage is a pipeline over this library.
+
+**Conditioning.** The recording is high-passed to strip rumble and any DC offset, then the energy
+envelope and zero crossing rate locate the speech boundaries and the syllable onsets.
+
+**Tone.** Mandarin lexical tone *is* the fundamental frequency contour, so `DSP.pitch` carries the
+primary signal rather than a secondary cue. The track is cleaned of octave errors, then
+`DSP::Curve.resample` brings contours of different duration onto a fixed 16-point grid where the
+four tones become comparable shapes.
+
+**Timbre.** Thirteen MFCC per frame describe the spectral envelope independently of pitch. Vocal
+tract length warping is set per speaker, so a child and an adult producing the same vowel land in
+the same region of the feature space.
+
+**Vowel quality.** The first two formants place a vowel on the F1/F2 plane, which is where the
+contrast between ㄧ, ㄩ and ㄨ actually lives.
+
+**Fricatives.** Spectral moments separate the sibilants: the retroflex ㄕ and the alveolar ㄙ differ
+mainly in centroid and skewness, not in duration or energy.
+
+The resulting sequences vary in length because speaking rate varies, so they are aligned and
+averaged with [dtwrb](https://github.com/taiwancards/dtwrb), the companion library for dynamic time
+warping and barycenter averaging.
+
+Speech is one application. Anything sampled as a numeric signal — vibration, biosignals, sonar,
+telemetry — uses the same spectral and predictive machinery.
+
+## Design
+
+Every stage is an object that precomputes what it can and then freezes: `DSP::Fourier::Radix2`
+caches its twiddle factors, `DSP::MelFilterbank` its triangular bands, `DSP::Decimator` its kernel.
+They hold no mutable state, share nothing globally, and are safe to reuse across threads. Build them
+once, outside the loop.
+
+Collaborators are injected rather than assumed: the transform behind a `DSP::Spectrum`, the window
+function of an MFCC sequence, the filterbank of a `DSP::Mfcc`. A different FFT backend needs only
+`#call(real, imaginary)` and `#size`.
+
+`DSP::Waveform`, `DSP::PitchTrack`, `DSP::SpectralMoments`, `DSP::Biquad`, `DSP::Lpc::Model` and
+`DSP::Formants::Peak` are `Data` value objects: frozen, compared by value, copied with `#with`.
+
+## License
+
+WTFPL — see [LICENSE](LICENSE).

data/lib/dsprb/autocorrelation.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module DSP
+  module Autocorrelation
+    module_function
+
+    # Unbiased-denominator-free autocorrelation r[k] = sum_i x[i] x[i + k], k = 0..order.
+    def call(frame, order)
+      raise ArgumentError, "order must be non-negative, got #{order}" if order.negative?
+
+      length = frame.length
+
+      Array.new(order + 1) do |lag|
+        total = 0.0
+        index = 0
+        limit = length - lag
+        while index < limit
+          total += frame[index] * frame[index + lag]
+          index += 1
+        end
+
+        total
+      end
+    end
+  end
+end

data/lib/dsprb/biquad.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module DSP
+  Biquad = Data.define(:b0, :b1, :b2, :a1, :a2) do
+    # Q of a Butterworth section: the maximally flat passband alignment.
+    BUTTERWORTH_Q = Math.sqrt(2.0) / 2.0
+
+    # Normalized cutoff bounds, keeping the design away from DC and Nyquist.
+    MINIMUM_NORMALIZED = 1e-4
+    MAXIMUM_NORMALIZED = 0.49
+
+    def self.lowpass(sample_rate:, cutoff:, q: BUTTERWORTH_Q) = design(sample_rate, cutoff, q, high: false)
+
+    def self.highpass(sample_rate:, cutoff:, q: BUTTERWORTH_Q) = design(sample_rate, cutoff, q, high: true)
+
+    def self.design(sample_rate, cutoff, q, high:)
+      omega = 2.0 * Math::PI * (cutoff.to_f / sample_rate).clamp(MINIMUM_NORMALIZED, MAXIMUM_NORMALIZED)
+      cosine = Math.cos(omega)
+      alpha = Math.sin(omega) / (2.0 * q)
+      scale = 1.0 + alpha
+
+      numerator = if high
+        [(1.0 + cosine) / 2.0, -(1.0 + cosine), (1.0 + cosine) / 2.0]
+      else
+        [(1.0 - cosine) / 2.0, 1.0 - cosine, (1.0 - cosine) / 2.0]
+      end
+
+      new(
+        b0: numerator[0] / scale,
+        b1: numerator[1] / scale,
+        b2: numerator[2] / scale,
+        a1: (-2.0 * cosine) / scale,
+        a2: (1.0 - alpha) / scale
+      )
+    end
+
+    private_class_method :design
+
+    # Direct form II transposed, which keeps the state to two accumulators.
+    def call(samples)
+      first = 0.0
+      second = 0.0
+      out = Array.new(samples.length, 0.0)
+
+      index = 0
+      while index < samples.length
+        input = samples[index]
+        output = (b0 * input) + first
+        first = (b1 * input) - (a1 * output) + second
+        second = (b2 * input) - (a2 * output)
+        out[index] = output
+        index += 1
+      end
+
+      out
+    end
+
+    # Cascading n identical sections yields a filter of order 2n.
+    def apply(samples, sections: 1)
+      raise ArgumentError, "sections must be positive, got #{sections}" unless sections.positive?
+
+      sections.times.reduce(samples) { |signal, _| call(signal) }
+    end
+  end
+end

data/lib/dsprb/curve.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module DSP
+  module Curve
+    module_function
+
+    # Linear interpolation onto a uniform grid of the requested length, used to
+    # bring contours of differing duration onto a common time base.
+    def resample(values, length)
+      raise ArgumentError, "length must be positive, got #{length}" unless length.positive?
+      return Array.new(length, 0.0) if values.empty?
+      return Array.new(length) { values.first.to_f } if values.length == 1 || length == 1
+
+      last = values.length - 1
+      span = length - 1
+
+      Array.new(length) do |index|
+        position = index.to_f * last / span
+        lower = position.floor
+        upper = [lower + 1, last].min
+        fraction = position - lower
+        (values[lower] * (1.0 - fraction)) + (values[upper] * fraction)
+      end
+    end
+  end
+end

data/lib/dsprb/dct.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module DSP
+  module Dct
+    module_function
+
+    # Unnormalized DCT-II: X[k] = sum_i x[i] cos(pi k (i + 1/2) / N).
+    def two(values, count)
+      length = values.length
+      raise ArgumentError, "count must be positive, got #{count}" unless count.positive?
+
+      Array.new(count) do |coefficient|
+        total = 0.0
+        index = 0
+        while index < length
+          total += values[index] * Math.cos(Math::PI * coefficient * (index + 0.5) / length)
+          index += 1
+        end
+
+        total
+      end
+    end
+  end
+end

data/lib/dsprb/decimator.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module DSP
+  class Decimator
+    # An odd tap count keeps the FIR linear phase, so decimation adds no group delay skew.
+    DEFAULT_TAPS = 31
+
+    # Cutoff as a fraction of the decimated sample rate, leaving a transition margin below Nyquist.
+    CUTOFF_RATIO = 0.45
+
+    attr_reader :factor, :taps, :kernel
+
+    def self.factor_for(sample_rate, target) = [(sample_rate / target).floor, 1].max
+
+    def initialize(factor, taps: DEFAULT_TAPS)
+      @factor = Integer(factor)
+      @taps = Integer(taps)
+
+      raise ArgumentError, "factor must be at least one, got #{@factor}" unless @factor >= 1
+      raise ArgumentError, "taps must be a positive odd number, got #{@taps}" unless @taps.positive? && @taps.odd?
+
+      @middle = (@taps - 1) / 2
+      @kernel = build_kernel.freeze
+      freeze
+    end
+
+    def call(waveform)
+      return waveform if @factor == 1
+
+      Waveform.new(samples: filter(waveform.samples), sample_rate: waveform.sample_rate / @factor)
+    end
+
+    private
+
+    def build_kernel
+      cutoff = CUTOFF_RATIO / @factor
+      taper = Window.hamming(@taps)
+
+      raw = Array.new(@taps) do |index|
+        offset = index - @middle
+        sinc = if offset.zero?
+          2.0 * cutoff
+        else
+          Math.sin(2.0 * Math::PI * cutoff * offset) / (Math::PI * offset)
+        end
+
+        sinc * taper[index]
+      end
+
+      total = raw.sum
+      raw.map { |value| value / total }
+    end
+
+    def filter(samples)
+      out = []
+      position = 0
+      while position < samples.length
+        total = 0.0
+        tap = 0
+        while tap < @taps
+          index = position + tap - @middle
+          total += @kernel[tap] * samples[index] if index >= 0 && index < samples.length
+          tap += 1
+        end
+
+        out << total
+        position += @factor
+      end
+
+      out
+    end
+  end
+end

data/lib/dsprb/energy.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module DSP
+  module Energy
+    # Keeps the logarithm of a silent frame finite, placing digital silence near -120 dB.
+    FLOOR = 1e-12
+
+    module_function
+
+    def frame_db(frame)
+      raise ArgumentError, "frame must not be empty" if frame.empty?
+
+      total = 0.0
+      index = 0
+      while index < frame.length
+        total += frame[index] * frame[index]
+        index += 1
+      end
+
+      to_db(total / frame.length)
+    end
+
+    def zero_crossing_rate(frame)
+      return 0.0 if frame.length < 2
+
+      crossings = 0
+      index = 1
+      while index < frame.length
+        crossings += 1 if frame[index].negative? != frame[index - 1].negative?
+        index += 1
+      end
+
+      crossings.to_f / (frame.length - 1)
+    end
+
+    def envelope_db(samples, window:, hop:)
+      raise ArgumentError, "window must be positive, got #{window}" unless window.positive?
+      raise ArgumentError, "hop must be positive, got #{hop}" unless hop.positive?
+      return [] if samples.length < window
+
+      running = 0.0
+      index = 0
+      while index < window
+        running += samples[index] * samples[index]
+        index += 1
+      end
+
+      out = [to_db(running / window)]
+      position = hop
+      while position + window <= samples.length
+        running = slide(samples, running, position, hop, window)
+        out << to_db([running, 0.0].max / window)
+        position += hop
+      end
+
+      out
+    end
+
+    def slide(samples, running, position, hop, window)
+      index = position - hop
+      while index < position
+        running -= samples[index] * samples[index]
+        running += samples[index + window] * samples[index + window]
+        index += 1
+      end
+
+      running
+    end
+
+    def to_db(power) = 10.0 * Math.log10(power + FLOOR)
+  end
+end

data/lib/dsprb/errors.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module DSP
+  Error = Class.new(StandardError)
+
+  FormatError = Class.new(Error)
+
+  UnknownStrategyError = Class.new(Error)
+end

data/lib/dsprb/formants.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module DSP
+  class Formants
+    Peak = Data.define(:frequency, :amplitude)
+
+    # Conventional ceiling for adult speech; the first four formants fall below it.
+    DEFAULT_MAXIMUM_HZ = 5500.0
+    DEFAULT_COUNT = 4
+
+    # Envelope samples taken over [0, Nyquist].
+    DEFAULT_RESOLUTION = 512
+
+    # One resonance can split into twin envelope peaks; peaks closer than this are merged.
+    DEFAULT_SEPARATION_HZ = 250.0
+
+    # Peaks pinned against the band edges are artifacts of the truncated envelope.
+    DEFAULT_EDGE_MARGIN_HZ = 150.0
+
+    # Below this the frame is too short to fit the predictor reliably.
+    MINIMUM_SAMPLES = 40
+
+    ENERGY_FLOOR = 1e-10
+    LOG_FLOOR = 1e-18
+
+    attr_reader :maximum_frequency, :count, :resolution, :separation, :edge_margin
+
+    def initialize(
+      maximum_frequency: DEFAULT_MAXIMUM_HZ,
+      count: DEFAULT_COUNT,
+      resolution: DEFAULT_RESOLUTION,
+      separation: DEFAULT_SEPARATION_HZ,
+      edge_margin: DEFAULT_EDGE_MARGIN_HZ
+    )
+      @maximum_frequency = Float(maximum_frequency)
+      @count = Integer(count)
+      @resolution = Integer(resolution)
+      @separation = Float(separation)
+      @edge_margin = Float(edge_margin)
+
+      raise ArgumentError, "count must be positive, got #{@count}" unless @count.positive?
+      raise ArgumentError, "resolution must be at least two, got #{@resolution}" unless @resolution >= 2
+
+      freeze
+    end
+
+    def call(waveform) = peaks(waveform).map(&:frequency)
+
+    def peaks(waveform)
+      reduced = reduce(waveform)
+      return [] if reduced.length < MINIMUM_SAMPLES
+
+      model = fit(reduced)
+      return [] if model.nil?
+
+      merge(extrema(model.envelope(points: @resolution), reduced.sample_rate)).first(@count)
+    end
+
+    private
+
+    def reduce(waveform)
+      Decimator.new(Decimator.factor_for(waveform.sample_rate, 2.0 * @maximum_frequency)).call(waveform)
+    end
+
+    def fit(waveform)
+      order = (2 * @count) + 2
+      windowed = Window.apply(waveform.samples, Window.hamming(waveform.length))
+      correlation = Autocorrelation.call(Framing.preemphasis(windowed), order)
+      return nil if correlation[0] <= ENERGY_FLOOR
+
+      Lpc.levinson(correlation, order)
+    end
+
+    def extrema(envelope, sample_rate)
+      nyquist = sample_rate / 2.0
+      span = envelope.length - 1
+      found = []
+
+      index = 1
+      while index < span
+        found << refine(envelope, index, nyquist, span) if rising?(envelope, index)
+        index += 1
+      end
+
+      found.compact
+    end
+
+    def rising?(envelope, index)
+      envelope[index] > envelope[index - 1] && envelope[index] >= envelope[index + 1]
+    end
+
+    def refine(envelope, index, nyquist, span)
+      previous = Math.log(envelope[index - 1] + LOG_FLOOR)
+      current = Math.log(envelope[index] + LOG_FLOOR)
+      following = Math.log(envelope[index + 1] + LOG_FLOOR)
+      frequency = nyquist * (index + Parabolic.vertex_offset(previous, current, following)) / span
+      return nil unless frequency > @edge_margin && frequency < nyquist - @edge_margin
+
+      Peak.new(frequency: frequency, amplitude: current)
+    end
+
+    def merge(found)
+      found.sort_by(&:frequency).each_with_object([]) do |peak, merged|
+        if merged.any? && (peak.frequency - merged.last.frequency) < @separation
+          merged[-1] = peak if peak.amplitude > merged.last.amplitude
+        else
+          merged << peak
+        end
+      end
+    end
+  end
+end