dsprb 1.0.0 → 2.0.0

checksums.yaml

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

data/CHANGELOG.md

@@ -1,5 +1,64 @@
 # Changelog
 
+## 2.0.0 — 2026-08-21
+
+Performance release. Every value the library produces is unchanged: across a battery of 34
+outputs measured against 1.0.0, twenty are bit-identical and the largest relative deviation
+anywhere is 1.7e-12, in the all-pole envelope.
+
+Median of three runs on Ruby 4.0 with YJIT, over a 400 sample frame at 16 kHz and a two
+second waveform:
+
+| Operation                         | 1.0.0    | 2.0.0    | Speedup |
+| --------------------------------- | -------- | -------- | ------- |
+| `Window.hamming(400)`             | 113.3 us | 0.4 us   | 266x    |
+| `Lpc::Envelope` over 512 points   | 216.3 us | 67.4 us  | 3.21x   |
+| `Dct.two(26 -> 13)`               | 9.7 us   | 3.3 us   | 2.98x   |
+| `Formants#call`                   | 411.2 us | 137.9 us | 2.98x   |
+| `Mfcc#call`                       | 176.1 us | 98.9 us  | 1.78x   |
+| `Spectrum#power`, size 512        | 164.9 us | 95.8 us  | 1.72x   |
+| `Spectrum#power`, size 1024       | 379.8 us | 238.1 us | 1.60x   |
+| `Decimator#call` over 32k samples | 7.1 ms   | 5.3 ms   | 1.35x   |
+| `Yin#call` over 2 s               | 63.8 ms  | 47.2 ms  | 1.35x   |
+
+### Breaking
+
+- `Window.hamming` and its siblings memoize by length and coefficients and return a **frozen**
+  array. Code that modified a window in place must copy it first.
+- `Spectrum` builds a `Fourier::Real` rather than a `Fourier::Radix2`, so `#transform` no longer
+  answers to a complex transform's interface. Injecting a `Radix2` explicitly still works.
+
+### Added
+
+- `DSP::Fourier::Real`, a transform for real-valued input. It packs the even and odd samples
+  into one complex sequence of half the length, so a real frame costs about half of the complex
+  transform. Returns the non-redundant bins `0..size/2`.
+- `DSP::Lpc::Envelope`, the all-pole spectral envelope on a fixed grid. Squaring the polynomial
+  first turns the sum over coefficients into a sum over their autocorrelation, which is real and
+  even, so only cosines remain and the grid precomputes once.
+- `DSP::Dct::Two`, the DCT-II on a fixed pair of lengths with a precomputed basis.
+- `DSP::Prepared`, the shared memoization used by `DSP::Window`, `DSP::Decimator.for`,
+  `DSP::Dct::Two.for` and `DSP::Lpc::Envelope.for` to hold one instance per parameter set.
+- `DSP::Check`, the argument validation the stages now share, so a rejected argument reports the
+  same way wherever it comes from.
+- `DSP::Decimator.to(waveform, target)`, which selects the factor and filters in one step.
+- `DSP::Yin.new(minimum_rms:)` reports frames quieter than the threshold as unvoiced without
+  running the lag search. Silence carries no pitch, and it is most of a short recording. The
+  default of zero leaves behavior unchanged.
+
+### Changed
+
+- `Formants` holds its envelope grid and reuses prepared decimators and windows instead of
+  rebuilding them on every frame, which is where most of its 2.98x comes from.
+- `Mfcc` holds its DCT basis.
+- `Decimator#filter` hoists the bounds test out of the interior of the convolution; only the
+  few output samples that reach past the signal pay for it. Output is bit-identical.
+- `Yin` accumulates lags in order and stops at the first dip that satisfies the absolute
+  threshold, rather than filling the whole difference function first. Output is bit-identical.
+- The radix-2 butterfly is inlined into the transform loop.
+- `Lpc::Envelope` computes the coefficient autocorrelation through `DSP::Autocorrelation` rather
+  than repeating it.
+
 ## 1.0.0 — 2026-08-01
 
 Initial public release.

data/README.md

@@ -68,6 +68,13 @@ 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.
 
+Silence carries no pitch and is most of a short recording, so `minimum_rms` skips the lag search on
+frames quieter than it and reports them unvoiced:
+
+```ruby
+DSP.pitch(signal, minimum_rms: 0.01)
+```
+
 ## Cepstral features
 
 `DSP::Mfcc` composes a power spectrum, a mel filterbank and a DCT-II. The filterbank supports
@@ -152,7 +159,7 @@ learner recordings against native templates. Its analysis stage is a pipeline ov
 **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
+**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.
@@ -177,13 +184,20 @@ 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.
+caches its twiddle factors, `DSP::MelFilterbank` its triangular bands, `DSP::Decimator` its kernel,
+`DSP::Lpc::Envelope` its cosine grid, `DSP::Dct::Two` its basis. They hold no mutable state and are
+safe to reuse across threads. Build them once, outside the loop.
+
+What depends on nothing but its own sizes is shared rather than rebuilt. Through `DSP::Prepared`,
+`DSP::Window.hamming`, `DSP::Decimator.for`, `DSP::Dct::Two.for` and `DSP::Lpc::Envelope.for` hand
+back one frozen instance per parameter set, so framing a signal does not pay to construct the same
+window on every frame. Argument validation is shared the same way through `DSP::Check`, so a
+rejected argument reports identically wherever it enters.
 
 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`.
+function of an MFCC sequence, the filterbank of a `DSP::Mfcc`. A spectrum uses `DSP::Fourier::Real`
+by default, which needs only `#power(frame)`; injecting a complex transform such as
+`DSP::Fourier::Radix2` needs `#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`.

data/lib/dsprb/autocorrelation.rb

@@ -4,9 +4,9 @@ module DSP
   module Autocorrelation
     module_function
 
-    # Unbiased-denominator-free autocorrelation r[k] = sum_i x[i] x[i + k], k = 0..order.
+    # r[k] = sum_i x[i] x[i + k], k = 0..order, without a denominator.
     def call(frame, order)
-      raise ArgumentError, "order must be non-negative, got #{order}" if order.negative?
+      Check.non_negative!(order, "order")
 
       length = frame.length
 

data/lib/dsprb/biquad.rb

@@ -2,10 +2,9 @@
 
 module DSP
   Biquad = Data.define(:b0, :b1, :b2, :a1, :a2) do
-    # Q of a Butterworth section: the maximally flat passband alignment.
+    # 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
 
@@ -36,7 +35,7 @@ module DSP
 
     private_class_method :design
 
-    # Direct form II transposed, which keeps the state to two accumulators.
+    # Direct form II transposed: two accumulators of state.
     def call(samples)
       first = 0.0
       second = 0.0
@@ -57,7 +56,7 @@ module DSP
 
     # 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?
+      Check.positive!(sections, "sections")
 
       sections.times.reduce(samples) { |signal, _| call(signal) }
     end

data/lib/dsprb/check.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module DSP
+  module Check
+    module_function
+
+    def positive!(value, name)
+      return value if value.positive?
+
+      raise ArgumentError, "#{name} must be positive, got #{value}"
+    end
+
+    def non_negative!(value, name)
+      return value unless value.negative?
+
+      raise ArgumentError, "#{name} must be non-negative, got #{value}"
+    end
+
+    def at_least!(value, minimum, name)
+      return value if value >= minimum
+
+      raise ArgumentError, "#{name} must be at least #{minimum}, got #{value}"
+    end
+
+    def power_of_two!(value, name)
+      return value if value.positive? && (value & (value - 1)).zero?
+
+      raise ArgumentError, "#{name} must be a positive power of two, got #{value}"
+    end
+
+    def below!(value, limit, name, limit_name)
+      return value if value < limit
+
+      raise ArgumentError, "#{name} must be below #{limit_name}, got #{value} and #{limit}"
+    end
+
+    def present!(collection, name)
+      return collection unless collection.empty?
+
+      raise ArgumentError, "#{name} must not be empty"
+    end
+  end
+end

data/lib/dsprb/curve.rb

@@ -4,10 +4,10 @@ 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.
+    # Linear interpolation onto a uniform grid, bringing contours of differing
+    # duration onto a common time base.
     def resample(values, length)
-      raise ArgumentError, "length must be positive, got #{length}" unless length.positive?
+      Check.positive!(length, "length")
       return Array.new(length, 0.0) if values.empty?
       return Array.new(length) { values.first.to_f } if values.length == 1 || length == 1
 

data/lib/dsprb/dct.rb

@@ -2,23 +2,43 @@
 
 module DSP
   module Dct
-    module_function
+    # X[k] = sum_i x[i] cos(pi k (i + 1/2) / N), unnormalized DCT-II.
+    class Two
+      extend Prepared
 
-    # 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
+      attr_reader :length, :count
+
+      def self.for(length, count) = prepared([length, count]) { new(length, count) }
 
-        total
+      def initialize(length, count)
+        @length = Check.positive!(Integer(length), "length")
+        @count = Check.positive!(Integer(count), "count")
+
+        @basis = Array
+          .new(@count) do |coefficient|
+            Array.new(@length) { |index| Math.cos(Math::PI * coefficient * (index + 0.5) / @length) }.freeze
+          end
+          .freeze
+        freeze
+      end
+
+      def call(values)
+        Array.new(@count) do |coefficient|
+          row = @basis[coefficient]
+          total = 0.0
+          index = 0
+          while index < @length
+            total += values[index] * row[index]
+            index += 1
+          end
+
+          total
+        end
       end
     end
+
+    module_function
+
+    def two(values, count) = Two.for(values.length, count).call(values)
   end
 end

data/lib/dsprb/decimator.rb

@@ -5,18 +5,25 @@ module DSP
     # 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 as a fraction of the decimated rate, leaving a transition margin below Nyquist.
     CUTOFF_RATIO = 0.45
 
+    extend Prepared
+
     attr_reader :factor, :taps, :kernel
 
     def self.factor_for(sample_rate, target) = [(sample_rate / target).floor, 1].max
 
+    def self.for(factor, taps: DEFAULT_TAPS) = prepared([factor, taps]) { new(factor, taps: taps) }
+
+    def self.to(waveform, target, taps: DEFAULT_TAPS)
+      self.for(factor_for(waveform.sample_rate, target), taps: taps).call(waveform)
+    end
+
     def initialize(factor, taps: DEFAULT_TAPS)
-      @factor = Integer(factor)
+      @factor = Check.at_least!(Integer(factor), 1, "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
@@ -38,12 +45,7 @@ module DSP
 
       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 = offset.zero? ? 2.0 * cutoff : Math.sin(2.0 * Math::PI * cutoff * offset) / (Math::PI * offset)
         sinc * taper[index]
       end
 
@@ -51,19 +53,36 @@ module DSP
       raw.map { |value| value / total }
     end
 
+    # Only the first and last few outputs reach past the signal, so the bound
+    # test is hoisted out of the interior and paid for by those alone.
     def filter(samples)
-      out = []
+      length = samples.length
+      kernel = @kernel
+      taps = @taps
+      out = Array.new((length + @factor - 1) / @factor)
+
+      cursor = 0
       position = 0
-      while position < samples.length
+      while position < length
+        first = position - @middle
         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
+        if first >= 0 && first + taps <= length
+          tap = 0
+          while tap < taps
+            total += kernel[tap] * samples[first + tap]
+            tap += 1
+          end
+        else
+          tap = 0
+          while tap < taps
+            index = first + tap
+            total += kernel[tap] * samples[index] if index >= 0 && index < length
+            tap += 1
+          end
         end
 
-        out << total
+        out[cursor] = total
+        cursor += 1
         position += @factor
       end
 

data/lib/dsprb/energy.rb

@@ -2,13 +2,13 @@
 
 module DSP
   module Energy
-    # Keeps the logarithm of a silent frame finite, placing digital silence near -120 dB.
+    # Places digital silence near -120 dB instead of negative infinity.
     FLOOR = 1e-12
 
     module_function
 
     def frame_db(frame)
-      raise ArgumentError, "frame must not be empty" if frame.empty?
+      Check.present!(frame, "frame")
 
       total = 0.0
       index = 0
@@ -34,8 +34,8 @@ module DSP
     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?
+      Check.positive!(window, "window")
+      Check.positive!(hop, "hop")
       return [] if samples.length < window
 
       running = 0.0

data/lib/dsprb/formants.rb

@@ -7,23 +7,20 @@ module DSP
     # 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.
+    # One resonance can split into twin envelope peaks; closer pairs 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
+    attr_reader :maximum_frequency, :count, :resolution, :separation, :edge_margin, :order
 
     def initialize(
       maximum_frequency: DEFAULT_MAXIMUM_HZ,
@@ -38,9 +35,11 @@ module DSP
       @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
+      Check.positive!(@count, "count")
+      Check.at_least!(@resolution, 2, "resolution")
 
+      @order = (2 * @count) + 2
+      @envelope = Lpc::Envelope.for(points: @resolution, order: @order)
       freeze
     end
 
@@ -53,22 +52,19 @@ module DSP
       model = fit(reduced)
       return [] if model.nil?
 
-      merge(extrema(model.envelope(points: @resolution), reduced.sample_rate)).first(@count)
+      merge(extrema(@envelope.call(model.coefficients), 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 reduce(waveform) = Decimator.to(waveform, 2.0 * @maximum_frequency)
 
     def fit(waveform)
-      order = (2 * @count) + 2
       windowed = Window.apply(waveform.samples, Window.hamming(waveform.length))
-      correlation = Autocorrelation.call(Framing.preemphasis(windowed), order)
+      correlation = Autocorrelation.call(Framing.preemphasis(windowed), @order)
       return nil if correlation[0] <= ENERGY_FLOOR
 
-      Lpc.levinson(correlation, order)
+      Lpc.levinson(correlation, @order)
     end
 
     def extrema(envelope, sample_rate)

data/lib/dsprb/fourier.rb

@@ -6,9 +6,7 @@ module DSP
       attr_reader :size
 
       def initialize(size)
-        @size = Integer(size)
-        raise ArgumentError, "FFT size must be a positive power of two, got #{@size}" unless power_of_two?(@size)
-
+        @size = Check.power_of_two!(Integer(size), "FFT size")
         @stages = build_stages(@size)
         freeze
       end
@@ -25,7 +23,19 @@ module DSP
           while block < @size
             index = 0
             while index < half
-              butterfly(real, imaginary, block + index, half, cosines[index], sines[index])
+              top = block + index
+              bottom = top + half
+              cosine = cosines[index]
+              sine = sines[index]
+              real_bottom = real[bottom]
+              imaginary_bottom = imaginary[bottom]
+              rotated_real = (real_bottom * cosine) - (imaginary_bottom * sine)
+              rotated_imaginary = (real_bottom * sine) + (imaginary_bottom * cosine)
+
+              real[bottom] = real[top] - rotated_real
+              imaginary[bottom] = imaginary[top] - rotated_imaginary
+              real[top] += rotated_real
+              imaginary[top] += rotated_imaginary
               index += 1
             end
 
@@ -40,8 +50,6 @@ module DSP
 
       private
 
-      def power_of_two?(value) = value.positive? && (value & (value - 1)).zero?
-
       def build_stages(size)
         stages = {}
         span = 2
@@ -89,18 +97,84 @@ module DSP
           source += 1
         end
       end
+    end
+
+    # Transform of a real signal. The even and odd samples are packed into one
+    # complex sequence of half the length and untangled afterwards, so a real
+    # frame costs about half of the complex transform.
+    class Real
+      MINIMUM_SIZE = 4
+
+      attr_reader :size, :bins
+
+      def initialize(size)
+        @size = Check.at_least!(Integer(size), MINIMUM_SIZE, "size")
+        @half = @size / 2
+        @inner = Radix2.new(@half)
+        @bins = @half + 1
+        @cosines = Array.new(@half) { |bin| Math.cos(-Math::PI * bin / @half) }.freeze
+        @sines = Array.new(@half) { |bin| Math.sin(-Math::PI * bin / @half) }.freeze
+        freeze
+      end
+
+      # Bins 0..size/2, the non-redundant half. The frame is read up to size
+      # samples and zero padded.
+      def call(frame)
+        real, imaginary = pack(frame)
+        @inner.call(real, imaginary)
+        untangle(real, imaginary)
+      end
+
+      def power(frame)
+        real, imaginary = call(frame)
+
+        Array.new(@bins) { |bin| (real[bin] * real[bin]) + (imaginary[bin] * imaginary[bin]) }
+      end
+
+      private
+
+      def pack(frame)
+        real = Array.new(@half, 0.0)
+        imaginary = Array.new(@half, 0.0)
+        limit = frame.length < @size ? frame.length : @size
+        index = 0
+        while index < limit
+          if index.even?
+            real[index >> 1] = frame[index].to_f
+          else
+            imaginary[index >> 1] = frame[index].to_f
+          end
+
+          index += 1
+        end
+
+        [real, imaginary]
+      end
+
+      def untangle(real, imaginary)
+        out_real = Array.new(@bins)
+        out_imaginary = Array.new(@bins)
+
+        bin = 0
+        while bin <= @half
+          low = bin == @half ? 0 : bin
+          high = (@half - bin) % @half
+
+          even_real = (real[low] + real[high]) * 0.5
+          even_imaginary = (imaginary[low] - imaginary[high]) * 0.5
+          odd_real = (imaginary[low] + imaginary[high]) * 0.5
+          odd_imaginary = (real[high] - real[low]) * 0.5
+
+          # The Nyquist twiddle is -1, which a half length table cannot hold.
+          cosine = bin == @half ? -1.0 : @cosines[bin]
+          sine = bin == @half ? 0.0 : @sines[bin]
+
+          out_real[bin] = even_real + ((odd_real * cosine) - (odd_imaginary * sine))
+          out_imaginary[bin] = even_imaginary + ((odd_real * sine) + (odd_imaginary * cosine))
+          bin += 1
+        end
 
-      def butterfly(real, imaginary, top, half, cosine, sine)
-        bottom = top + half
-        real_bottom = real[bottom]
-        imaginary_bottom = imaginary[bottom]
-        rotated_real = (real_bottom * cosine) - (imaginary_bottom * sine)
-        rotated_imaginary = (real_bottom * sine) + (imaginary_bottom * cosine)
-
-        real[bottom] = real[top] - rotated_real
-        imaginary[bottom] = imaginary[top] - rotated_imaginary
-        real[top] += rotated_real
-        imaginary[top] += rotated_imaginary
+        [out_real, out_imaginary]
       end
     end
   end

data/lib/dsprb/framing.rb

@@ -8,8 +8,8 @@ module DSP
     module_function
 
     def frames(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?
+      Check.positive!(window, "window")
+      Check.positive!(hop, "hop")
 
       out = []
       position = 0

data/lib/dsprb/lpc.rb

@@ -2,51 +2,73 @@
 
 module DSP
   module Lpc
-    # Below this the all-pole denominator is treated as a pole on the unit circle.
     DENOMINATOR_FLOOR = 1e-18
-
     UNBOUNDED_MAGNITUDE = 1e9
 
-    Model = Data.define(:coefficients, :error) do
-      def order = coefficients.length - 1
-
-      # Magnitude of the all-pole transfer function 1 / |A(e^{i w})|^2 sampled
-      # over [0, pi], the spectral envelope the predictor implies.
-      def envelope(points:)
-        raise ArgumentError, "points must be at least two, got #{points}" unless points >= 2
-
-        span = points - 1
+    # Samples 1 / |A(e^{i w})|^2 over [0, pi] on a fixed grid. Squaring the
+    # polynomial first leaves a sum over its autocorrelation, which is real and
+    # even, so only cosines remain and the grid precomputes once:
+    #
+    #   |A(w)|^2 = c[0] + 2 sum_{m=1..order} c[m] cos(w m)
+    class Envelope
+      extend Prepared
+
+      attr_reader :points, :order
+
+      def self.for(points:, order:) = prepared([points, order]) { new(points: points, order: order) }
+
+      def initialize(points:, order:)
+        @points = Check.at_least!(Integer(points), 2, "points")
+        @order = Check.non_negative!(Integer(order), "order")
+
+        span = (@points - 1).to_f
+        @cosines = Array
+          .new(@points) do |point|
+            Array.new(@order + 1) { |lag| Math.cos(Math::PI * point * lag / span) }.freeze
+          end
+          .freeze
+        freeze
+      end
 
-        Array.new(points) do |index|
-          real, imaginary = response(Math::PI * index / span)
-          denominator = (real * real) + (imaginary * imaginary)
-          denominator < DENOMINATOR_FLOOR ? UNBOUNDED_MAGNITUDE : 1.0 / denominator
+      def call(coefficients)
+        highest = coefficients.length - 1
+        if highest > @order
+          raise ArgumentError, "expected at most #{@order + 1} coefficients, got #{coefficients.length}"
         end
-      end
 
-      private
-
-      def response(omega)
-        real = 0.0
-        imaginary = 0.0
-        index = 0
-        while index < coefficients.length
-          angle = -omega * index
-          real += coefficients[index] * Math.cos(angle)
-          imaginary += coefficients[index] * Math.sin(angle)
-          index += 1
+        correlation = Autocorrelation.call(coefficients, highest)
+        out = Array.new(@points)
+
+        point = 0
+        while point < @points
+          row = @cosines[point]
+          total = correlation[0]
+          lag = 1
+          while lag <= highest
+            total += 2.0 * correlation[lag] * row[lag]
+            lag += 1
+          end
+
+          out[point] = total < DENOMINATOR_FLOOR ? UNBOUNDED_MAGNITUDE : 1.0 / total
+          point += 1
         end
 
-        [real, imaginary]
+        out
       end
     end
 
+    Model = Data.define(:coefficients, :error) do
+      def order = coefficients.length - 1
+
+      def envelope(points:) = Envelope.for(points: points, order: order).call(coefficients)
+    end
+
     module_function
 
     def solve(frame, order:) = levinson(Autocorrelation.call(frame, order), order)
 
-    # Levinson-Durbin recursion: solves the Yule-Walker system in O(order^2),
-    # stopping early when a reflection coefficient leaves the unit circle.
+    # Levinson-Durbin recursion, O(order^2), stopping early when a reflection
+    # coefficient leaves the unit circle.
     def levinson(autocorrelation, order)
       coefficients = Array.new(order + 1, 0.0)
       coefficients[0] = 1.0

data/lib/dsprb/mel_filterbank.rb

@@ -9,13 +9,12 @@ module DSP
     DEFAULT_FILTERS = 26
     DEFAULT_LOW_HZ = 50.0
 
-    # Keeps the logarithm of a band that collected no energy finite.
     ENERGY_FLOOR = 1e-12
 
     attr_reader :sample_rate, :size, :filters, :low, :high, :warp, :bands
 
-    # warp rescales the band centers for vocal tract length normalization:
-    # values above 1 shift the bank upwards, suiting shorter vocal tracts.
+    # warp rescales the band centers for vocal tract length normalization;
+    # above 1 the bank shifts upwards, suiting shorter vocal tracts.
     def initialize(sample_rate:, size:, filters: DEFAULT_FILTERS, low: DEFAULT_LOW_HZ, high: nil, warp: 1.0)
       @sample_rate = Float(sample_rate)
       @size = Integer(size)
@@ -51,9 +50,9 @@ module DSP
     private
 
     def validate!
-      raise ArgumentError, "filters must be positive, got #{@filters}" unless @filters.positive?
-      raise ArgumentError, "warp must be positive, got #{@warp}" unless @warp.positive?
-      raise ArgumentError, "low must be below high, got #{@low} and #{@high}" unless @low < @high
+      Check.positive!(@filters, "filters")
+      Check.positive!(@warp, "warp")
+      Check.below!(@low, @high, "low", "high")
     end
 
     def build_bands

data/lib/dsprb/mfcc.rb

@@ -21,12 +21,12 @@ module DSP
       @coefficients = Integer(coefficients)
       @spectrum = spectrum || Spectrum.new(filterbank.size)
 
-      raise ArgumentError, "coefficients must be positive, got #{@coefficients}" unless @coefficients.positive?
-
+      Check.positive!(@coefficients, "coefficients")
+      @dct = Dct::Two.for(@filterbank.filters, @coefficients)
       freeze
     end
 
-    def call(power) = Dct.two(@filterbank.log_energies(power), @coefficients)
+    def call(power) = @dct.call(@filterbank.log_energies(power))
 
     def sequence(
       waveform,

data/lib/dsprb/prepared.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module DSP
+  # Shares one instance per parameter set. What a stage precomputes depends on
+  # nothing but its own sizes, so framing a signal need not rebuild it per frame.
+  module Prepared
+    def self.extended(base)
+      base.instance_variable_set(:@prepared, {})
+      base.instance_variable_set(:@prepared_mutex, Mutex.new)
+    end
+
+    def prepared(key)
+      found = @prepared[key]
+      return found unless found.nil?
+
+      @prepared_mutex.synchronize { @prepared[key] ||= yield }
+    end
+
+    def prepared_count = @prepared.size
+  end
+end

data/lib/dsprb/spectrum.rb

@@ -4,17 +4,30 @@ module DSP
   class Spectrum
     attr_reader :size, :bins, :transform
 
+    # Defaults to the real-input transform; a complex one such as
+    # Fourier::Radix2 may be injected instead.
     def initialize(size, transform: nil)
       @size = Integer(size)
-      @transform = transform || Fourier::Radix2.new(@size)
       @bins = (@size / 2) + 1
+      @transform = transform || Fourier::Real.new(@size)
+      @real_input = @transform.respond_to?(:power)
       freeze
     end
 
-    def power(frame)
+    def power(frame) = @real_input ? @transform.power(frame) : complex_power(frame)
+
+    def magnitude(frame) = power(frame).map { |value| Math.sqrt(value) }
+
+    def frequencies(sample_rate) = Array.new(@bins) { |bin| bin * sample_rate / @size.to_f }
+
+    def bin_of(frequency, sample_rate) = (frequency * @size / sample_rate.to_f).round
+
+    private
+
+    def complex_power(frame)
       real = Array.new(@size, 0.0)
       imaginary = Array.new(@size, 0.0)
-      limit = [frame.length, @size].min
+      limit = frame.length < @size ? frame.length : @size
       index = 0
       while index < limit
         real[index] = frame[index].to_f
@@ -25,11 +38,5 @@ module DSP
 
       Array.new(@bins) { |bin| (real[bin] * real[bin]) + (imaginary[bin] * imaginary[bin]) }
     end
-
-    def magnitude(frame) = power(frame).map { |value| Math.sqrt(value) }
-
-    def frequencies(sample_rate) = Array.new(@bins) { |bin| bin * sample_rate / @size.to_f }
-
-    def bin_of(frequency, sample_rate) = (frequency * @size / sample_rate.to_f).round
   end
 end

data/lib/dsprb/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DSP
-  VERSION = "1.0.0"
+  VERSION = "2.0.0"
 end

data/lib/dsprb/wav.rb

@@ -12,7 +12,7 @@ module DSP
     HEADER_BYTES = 12
     CHUNK_HEADER_BYTES = 8
 
-    # Unsigned 8-bit PCM is the one depth WAVE stores with a midpoint offset.
+    # Unsigned 8-bit is the one depth WAVE stores with a midpoint offset.
     EIGHT_BIT_MIDPOINT = 128.0
 
     module_function

data/lib/dsprb/waveform.rb

@@ -3,10 +3,7 @@
 module DSP
   Waveform = Data.define(:samples, :sample_rate) do
     def initialize(samples:, sample_rate:)
-      rate = Float(sample_rate)
-      raise ArgumentError, "sample rate must be positive, got #{rate}" unless rate.positive?
-
-      super(samples: samples, sample_rate: rate)
+      super(samples: samples, sample_rate: Check.positive!(Float(sample_rate), "sample rate"))
     end
 
     def length = samples.length

data/lib/dsprb/window.rb

@@ -2,17 +2,19 @@
 
 module DSP
   module Window
-    # Generalized cosine windows w[i] = sum_k (-1)^k a_k cos(2 pi k i / (N - 1)).
+    # w[i] = sum_k (-1)^k a_k cos(2 pi k i / (N - 1)).
     HAMMING = [0.54, 0.46].freeze
     HANN = [0.5, 0.5].freeze
     BLACKMAN = [0.42, 0.5, 0.08].freeze
 
+    extend Prepared
+
     module_function
 
     def rectangular(length)
       assert_length!(length)
 
-      Array.new(length, 1.0)
+      Window.prepared([:rectangular, length]) { Array.new(length, 1.0).freeze }
     end
 
     def hamming(length) = cosine_sum(length, HAMMING)
@@ -23,13 +25,26 @@ module DSP
 
     def cosine_sum(length, coefficients)
       assert_length!(length)
+
+      Window.prepared([:cosine_sum, length, coefficients]) { build_cosine_sum(length, coefficients).freeze }
+    end
+
+    def build_cosine_sum(length, coefficients)
       return [1.0] if length == 1
 
       span = (length - 1).to_f
+      terms = coefficients.length
 
       Array.new(length) do |index|
         phase = 2.0 * Math::PI * index / span
-        coefficients.each_with_index.sum { |weight, term| (term.even? ? weight : -weight) * Math.cos(term * phase) }
+        total = 0.0
+        term = 0
+        while term < terms
+          total += (term.even? ? coefficients[term] : -coefficients[term]) * Math.cos(term * phase)
+          term += 1
+        end
+
+        total
       end
     end
 

data/lib/dsprb/yin.rb

@@ -13,22 +13,31 @@ module DSP
     # A global minimum above this is too shallow to call the frame voiced.
     DEFAULT_VOICED_THRESHOLD = 0.35
 
-    # Decimation target, an order above twice the highest tracked f0, so that
-    # periodicity survives while the O(window * lags) search stays cheap.
+    # An order above twice the highest tracked f0, so periodicity survives while
+    # the O(window * lags) search stays cheap.
     DEFAULT_WORKING_RATE = 5512.5
 
-    # Bounds the lag search for pathological rate and frequency combinations.
     MAXIMUM_LAG = 10_000
 
-    attr_reader :minimum_frequency, :maximum_frequency, :hop_seconds, :threshold, :voiced_threshold, :working_rate
+    attr_reader(
+      :minimum_frequency,
+      :maximum_frequency,
+      :hop_seconds,
+      :threshold,
+      :voiced_threshold,
+      :working_rate,
+      :minimum_rms
+    )
 
+    # minimum_rms reports frames quieter than it unvoiced without searching.
     def initialize(
       minimum_frequency: DEFAULT_MINIMUM_HZ,
       maximum_frequency: DEFAULT_MAXIMUM_HZ,
       hop_seconds: DEFAULT_HOP_SECONDS,
       threshold: DEFAULT_THRESHOLD,
       voiced_threshold: DEFAULT_VOICED_THRESHOLD,
-      working_rate: DEFAULT_WORKING_RATE
+      working_rate: DEFAULT_WORKING_RATE,
+      minimum_rms: 0.0
     )
       @minimum_frequency = Float(minimum_frequency)
       @maximum_frequency = Float(maximum_frequency)
@@ -36,13 +45,14 @@ module DSP
       @threshold = Float(threshold)
       @voiced_threshold = Float(voiced_threshold)
       @working_rate = Float(working_rate)
+      @minimum_rms = Float(minimum_rms)
 
       validate!
       freeze
     end
 
     def call(waveform)
-      reduced = Decimator.new(Decimator.factor_for(waveform.sample_rate, @working_rate)).call(waveform)
+      reduced = Decimator.to(waveform, @working_rate)
       rate = reduced.sample_rate
       shortest = (rate / @maximum_frequency).floor.clamp(2, MAXIMUM_LAG)
       longest = (rate / @minimum_frequency).ceil.clamp(shortest + 2, MAXIMUM_LAG)
@@ -63,8 +73,9 @@ module DSP
         )
       end
 
-      raise ArgumentError, "hop_seconds must be positive, got #{@hop_seconds}" unless @hop_seconds.positive?
-      raise ArgumentError, "working_rate must be positive, got #{@working_rate}" unless @working_rate.positive?
+      Check.positive!(@hop_seconds, "hop_seconds")
+      Check.positive!(@working_rate, "working_rate")
+      Check.non_negative!(@minimum_rms, "minimum_rms")
     end
 
     def track(samples, rate:, window:, hop:, shortest:, longest:)
@@ -74,10 +85,16 @@ module DSP
 
       position = 0
       while position + window + longest <= samples.length
-        normalized = cumulative_mean_difference(samples, position, window, shortest, longest)
-        frequency, weight = evaluate(normalized, select_lag(normalized, shortest, longest), shortest, longest, rate)
-        f0 << frequency
-        confidence << weight
+        if quiet?(samples, position, window)
+          f0 << 0.0
+          confidence << 0.0
+        else
+          normalized, lag = search(samples, position, window, shortest, longest)
+          frequency, weight = evaluate(normalized, lag, shortest, longest, rate)
+          f0 << frequency
+          confidence << weight
+        end
+
         times << (position / rate)
         position += hop
       end
@@ -85,67 +102,68 @@ module DSP
       PitchTrack.new(f0: f0, confidence: confidence, times: times, hop_seconds: hop / rate)
     end
 
-    def cumulative_mean_difference(samples, position, window, shortest, longest)
-      raw = squared_difference(samples, position, window, shortest, longest)
-      normalized = Array.new(longest + 1, 1.0)
-      running = 0.0
+    def quiet?(samples, position, window)
+      return false unless @minimum_rms.positive?
 
-      lag = shortest
-      while lag <= longest
-        running += raw[lag]
-        normalized[lag] = running.zero? ? 1.0 : raw[lag] * (lag - shortest + 1) / running
-        lag += 1
+      total = 0.0
+      index = 0
+      while index < window
+        value = samples[position + index]
+        total += value * value
+        index += 1
       end
 
-      normalized
+      Math.sqrt(total / window) < @minimum_rms
     end
 
-    def squared_difference(samples, position, window, shortest, longest)
-      raw = Array.new(longest + 1, 0.0)
+    # The cumulative mean normalization only looks back, so lags accumulate in
+    # order and the walk stops at the first qualifying dip. A frame without one
+    # has filled the whole array by the end, which the global minimum needs.
+    def search(samples, position, window, shortest, longest)
+      normalized = Array.new(longest + 1, 1.0)
+      running = 0.0
+      best = shortest
+      lowest = Float::INFINITY
+      chosen = nil
 
       lag = shortest
       while lag <= longest
-        total = 0.0
-        index = 0
-        while index < window
-          delta = samples[position + index] - samples[position + index + lag]
-          total += delta * delta
-          index += 1
-        end
-
-        raw[lag] = total
-        lag += 1
-      end
+        raw = difference(samples, position, window, lag)
+        running += raw
+        value = running.zero? ? 1.0 : raw * (lag - shortest + 1) / running
+        normalized[lag] = value
 
-      raw
-    end
+        if value < lowest
+          lowest = value
+          best = lag
+        end
 
-    def select_lag(normalized, shortest, longest)
-      lag = shortest + 1
-      while lag < longest
-        return lag if normalized[lag] < @threshold && normalized[lag] <= normalized[lag + 1]
+        previous = lag - 1
+        if chosen.nil? &&
+            previous > shortest &&
+            previous < longest &&
+            normalized[previous] < @threshold &&
+            normalized[previous] <= value
+          chosen = previous
+          break
+        end
 
         lag += 1
       end
 
-      global_minimum(normalized, shortest, longest)
+      [normalized, chosen || best]
     end
 
-    def global_minimum(normalized, shortest, longest)
-      best = shortest
-      lowest = normalized[shortest]
-
-      lag = shortest + 1
-      while lag <= longest
-        if normalized[lag] < lowest
-          lowest = normalized[lag]
-          best = lag
-        end
-
-        lag += 1
+    def difference(samples, position, window, lag)
+      total = 0.0
+      index = 0
+      while index < window
+        delta = samples[position + index] - samples[position + index + lag]
+        total += delta * delta
+        index += 1
       end
 
-      best
+      total
     end
 
     def evaluate(normalized, lag, shortest, longest, rate)

data/lib/dsprb.rb

@@ -2,6 +2,8 @@
 
 require_relative "dsprb/version"
 require_relative "dsprb/errors"
+require_relative "dsprb/check"
+require_relative "dsprb/prepared"
 require_relative "dsprb/resolver"
 require_relative "dsprb/parabolic"
 require_relative "dsprb/waveform"

data/sig/dsprb.rbs

@@ -43,6 +43,30 @@ module DSP
     **untyped
   ) -> ::Array[::Array[::Float]]
 
+  module Check
+    def self.positive!: [T < _Positive] (T, ::String) -> T
+    def self.non_negative!: [T < _Negative] (T, ::String) -> T
+    def self.at_least!: [T < ::Comparable] (T, T, ::String) -> T
+    def self.power_of_two!: (::Integer, ::String) -> ::Integer
+    def self.below!: [T < ::Comparable] (T, T, ::String, ::String) -> T
+    def self.present!: [T] (T, ::String) -> T
+  end
+
+  interface _Positive
+    def positive?: () -> bool
+  end
+
+  interface _Negative
+    def negative?: () -> bool
+  end
+
+  module Prepared
+    def self.extended: (untyped) -> void
+
+    def prepared: [T] (untyped) { () -> T } -> T
+    def prepared_count: () -> ::Integer
+  end
+
   module Resolver
     def self.call: (untyped, ::Hash[::Symbol, untyped], ::String) -> untyped
   end
@@ -86,6 +110,8 @@ module DSP
   end
 
   module Window
+    extend Prepared
+
     HAMMING: ::Array[::Float]
     HANN: ::Array[::Float]
     BLACKMAN: ::Array[::Float]
@@ -97,6 +123,7 @@ module DSP
     def self.hann: (::Integer) -> ::Array[::Float]
     def self.blackman: (::Integer) -> ::Array[::Float]
     def self.cosine_sum: (::Integer, ::Array[::Float]) -> ::Array[::Float]
+    def self.build_cosine_sum: (::Integer, ::Array[::Float]) -> ::Array[::Float]
     def self.apply: (frame, ::Array[::Float]) -> ::Array[::Float]
     def self.assert_length!: (untyped) -> void
     def self.resolve: (window) -> _WindowFunction
@@ -117,6 +144,17 @@ module DSP
       def initialize: (::Integer) -> void
       def call: (::Array[::Float], ::Array[::Float]) -> [::Array[::Float], ::Array[::Float]]
     end
+
+    class Real
+      MINIMUM_SIZE: ::Integer
+
+      attr_reader size: ::Integer
+      attr_reader bins: ::Integer
+
+      def initialize: (::Integer) -> void
+      def call: (frame) -> [::Array[::Float], ::Array[::Float]]
+      def power: (frame) -> spectrum
+    end
   end
 
   class Spectrum
@@ -178,6 +216,17 @@ module DSP
   end
 
   module Dct
+    class Two
+      extend Prepared
+
+      attr_reader length: ::Integer
+      attr_reader count: ::Integer
+
+      def self.for: (::Integer, ::Integer) -> Two
+      def initialize: (::Integer, ::Integer) -> void
+      def call: (::Array[::Numeric]) -> ::Array[::Float]
+    end
+
     def self.two: (::Array[::Numeric], ::Integer) -> ::Array[::Float]
   end
 
@@ -205,6 +254,8 @@ module DSP
   end
 
   class Decimator
+    extend Prepared
+
     DEFAULT_TAPS: ::Integer
     CUTOFF_RATIO: ::Float
 
@@ -213,6 +264,8 @@ module DSP
     attr_reader kernel: ::Array[::Float]
 
     def self.factor_for: (::Numeric, ::Numeric) -> ::Integer
+    def self.for: (::Integer, ?taps: ::Integer) -> Decimator
+    def self.to: (Waveform, ::Numeric, ?taps: ::Integer) -> Waveform
     def initialize: (::Integer, ?taps: ::Integer) -> void
     def call: (Waveform) -> Waveform
   end
@@ -225,6 +278,17 @@ module DSP
     DENOMINATOR_FLOOR: ::Float
     UNBOUNDED_MAGNITUDE: ::Float
 
+    class Envelope
+      extend Prepared
+
+      attr_reader points: ::Integer
+      attr_reader order: ::Integer
+
+      def self.for: (points: ::Integer, order: ::Integer) -> Envelope
+      def initialize: (points: ::Integer, order: ::Integer) -> void
+      def call: (::Array[::Float]) -> ::Array[::Float]
+    end
+
     class Model
       attr_reader coefficients: ::Array[::Float]
       attr_reader error: ::Float
@@ -261,6 +325,7 @@ module DSP
     attr_reader resolution: ::Integer
     attr_reader separation: ::Float
     attr_reader edge_margin: ::Float
+    attr_reader order: ::Integer
 
     def initialize: (
       ?maximum_frequency: ::Numeric,
@@ -311,6 +376,7 @@ module DSP
     attr_reader threshold: ::Float
     attr_reader voiced_threshold: ::Float
     attr_reader working_rate: ::Float
+    attr_reader minimum_rms: ::Float
 
     def initialize: (
       ?minimum_frequency: ::Numeric,
@@ -318,6 +384,7 @@ module DSP
       ?hop_seconds: ::Numeric,
       ?threshold: ::Numeric,
       ?voiced_threshold: ::Numeric,
+      ?minimum_rms: ::Numeric,
       ?working_rate: ::Numeric
     ) -> void
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dsprb
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Den Patin
@@ -68,6 +68,7 @@ files:
 - lib/dsprb.rb
 - lib/dsprb/autocorrelation.rb
 - lib/dsprb/biquad.rb
+- lib/dsprb/check.rb
 - lib/dsprb/curve.rb
 - lib/dsprb/dct.rb
 - lib/dsprb/decimator.rb
@@ -81,6 +82,7 @@ files:
 - lib/dsprb/mfcc.rb
 - lib/dsprb/parabolic.rb
 - lib/dsprb/pitch_track.rb
+- lib/dsprb/prepared.rb
 - lib/dsprb/resolver.rb
 - lib/dsprb/scales.rb
 - lib/dsprb/spectral_moments.rb
@@ -113,7 +115,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.17
 specification_version: 4
 summary: Speech signal processing and acoustic feature extraction for numeric signals
 test_files: []