dsprb 1.0.0

data/lib/dsprb/fourier.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module DSP
+  module Fourier
+    class Radix2
+      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)
+
+        @stages = build_stages(@size)
+        freeze
+      end
+
+      def call(real, imaginary)
+        assert_size!(real, imaginary)
+        permute(real, imaginary)
+
+        span = 2
+        while span <= @size
+          cosines, sines = @stages[span]
+          half = span / 2
+          block = 0
+          while block < @size
+            index = 0
+            while index < half
+              butterfly(real, imaginary, block + index, half, cosines[index], sines[index])
+              index += 1
+            end
+
+            block += span
+          end
+
+          span <<= 1
+        end
+
+        [real, imaginary]
+      end
+
+      private
+
+      def power_of_two?(value) = value.positive? && (value & (value - 1)).zero?
+
+      def build_stages(size)
+        stages = {}
+        span = 2
+        while span <= size
+          half = span / 2
+          cosines = Array.new(half)
+          sines = Array.new(half)
+          index = 0
+          while index < half
+            angle = -2.0 * Math::PI * index / span
+            cosines[index] = Math.cos(angle)
+            sines[index] = Math.sin(angle)
+            index += 1
+          end
+
+          stages[span] = [cosines.freeze, sines.freeze]
+          span <<= 1
+        end
+
+        stages.freeze
+      end
+
+      def assert_size!(real, imaginary)
+        return if real.length == @size && imaginary.length == @size
+
+        raise ArgumentError, "expected two buffers of length #{@size}, got #{real.length} and #{imaginary.length}"
+      end
+
+      def permute(real, imaginary)
+        target = 0
+        source = 1
+        while source < @size
+          bit = @size >> 1
+          while (target & bit) != 0
+            target ^= bit
+            bit >>= 1
+          end
+
+          target |= bit
+          if source < target
+            real[source], real[target] = real[target], real[source]
+            imaginary[source], imaginary[target] = imaginary[target], imaginary[source]
+          end
+
+          source += 1
+        end
+      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
+      end
+    end
+  end
+end

data/lib/dsprb/framing.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module DSP
+  module Framing
+    # First-order high-pass that flattens the -6 dB/octave tilt of the glottal source.
+    DEFAULT_PREEMPHASIS = 0.97
+
+    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?
+
+      out = []
+      position = 0
+      while position + window <= samples.length
+        out << samples[position, window]
+        position += hop
+      end
+
+      out
+    end
+
+    def frame_count(length, window:, hop:)
+      return 0 if length < window
+
+      ((length - window) / hop) + 1
+    end
+
+    def preemphasis(samples, coefficient: DEFAULT_PREEMPHASIS)
+      return [] if samples.empty?
+
+      out = Array.new(samples.length)
+      out[0] = samples[0].to_f
+      index = 1
+      while index < samples.length
+        out[index] = samples[index] - (coefficient * samples[index - 1])
+        index += 1
+      end
+
+      out
+    end
+  end
+end

data/lib/dsprb/lpc.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+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
+
+        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
+        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
+        end
+
+        [real, imaginary]
+      end
+    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.
+    def levinson(autocorrelation, order)
+      coefficients = Array.new(order + 1, 0.0)
+      coefficients[0] = 1.0
+      error = autocorrelation[0].to_f
+      return Model.new(coefficients: coefficients, error: 0.0) unless error.positive?
+
+      (1..order).each do |step|
+        total = autocorrelation[step]
+        (1...step).each { |index| total += coefficients[index] * autocorrelation[step - index] }
+        reflection = -total / error
+        return Model.new(coefficients: coefficients, error: error) if reflection.abs >= 1.0
+
+        coefficients = advance(coefficients, step, reflection)
+        error *= 1.0 - (reflection * reflection)
+        return Model.new(coefficients: coefficients, error: error) unless error.positive?
+      end
+
+      Model.new(coefficients: coefficients, error: error)
+    end
+
+    def advance(coefficients, step, reflection)
+      updated = coefficients.dup
+      (1...step).each { |index| updated[index] = coefficients[index] + (reflection * coefficients[step - index]) }
+      updated[step] = reflection
+      updated
+    end
+  end
+end

data/lib/dsprb/mel_filterbank.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module DSP
+  class MelFilterbank
+    Band = Data.define(:offset, :weights) do
+      def length = weights.length
+    end
+
+    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.
+    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)
+      @filters = Integer(filters)
+      @low = Float(low)
+      @high = Float(high || (@sample_rate / 2.0))
+      @warp = Float(warp)
+
+      validate!
+      @bands = build_bands.freeze
+      freeze
+    end
+
+    def energies(power)
+      @bands.map do |band|
+        weights = band.weights
+        offset = band.offset
+        total = 0.0
+        index = 0
+        while index < weights.length
+          total += weights[index] * power[offset + index]
+          index += 1
+        end
+
+        total
+      end
+    end
+
+    def log_energies(power) = energies(power).map { |value| Math.log([value, ENERGY_FLOOR].max) }
+
+    def center_frequencies = @centers
+
+    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
+    end
+
+    def build_bands
+      edges = mel_spaced_edges
+      @centers = edges[1..-2].freeze
+      bins = edges.map { |frequency| ((@size + 1) * frequency / @sample_rate).floor }
+      highest = (@size / 2)
+
+      (0...@filters).map do |filter|
+        left = [bins[filter], 0].max
+        right = [bins[filter + 2], highest].min
+        center = bins[filter + 1].clamp(left + 1, [right - 1, left + 1].max)
+
+        Band.new(offset: left, weights: triangle(left, center, right).freeze)
+      end
+    end
+
+    def mel_spaced_edges
+      low_mel = Scales.hz_to_mel(@low)
+      high_mel = Scales.hz_to_mel(@high)
+      span = high_mel - low_mel
+
+      Array.new(@filters + 2) do |index|
+        Scales.mel_to_hz(low_mel + (span * index / (@filters + 1).to_f)) * @warp
+      end
+    end
+
+    def triangle(left, center, right)
+      (left..right).map do |bin|
+        if bin < center
+          (bin - left).to_f / [center - left, 1].max
+        elsif bin == center
+          1.0
+        else
+          (right - bin).to_f / [right - center, 1].max
+        end
+      end
+    end
+  end
+end

data/lib/dsprb/mfcc.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module DSP
+  class Mfcc
+    DEFAULT_COEFFICIENTS = 13
+    DEFAULT_SIZE = 512
+    DEFAULT_WINDOW_SECONDS = 0.025
+    DEFAULT_HOP_SECONDS = 0.010
+
+    attr_reader :filterbank, :spectrum, :coefficients
+
+    def self.for(sample_rate:, size: DEFAULT_SIZE, coefficients: DEFAULT_COEFFICIENTS, **options)
+      new(
+        filterbank: MelFilterbank.new(sample_rate: sample_rate, size: size, **options),
+        coefficients: coefficients
+      )
+    end
+
+    def initialize(filterbank:, coefficients: DEFAULT_COEFFICIENTS, spectrum: nil)
+      @filterbank = filterbank
+      @coefficients = Integer(coefficients)
+      @spectrum = spectrum || Spectrum.new(filterbank.size)
+
+      raise ArgumentError, "coefficients must be positive, got #{@coefficients}" unless @coefficients.positive?
+
+      freeze
+    end
+
+    def call(power) = Dct.two(@filterbank.log_energies(power), @coefficients)
+
+    def sequence(
+      waveform,
+      window_seconds: DEFAULT_WINDOW_SECONDS,
+      hop_seconds: DEFAULT_HOP_SECONDS,
+      window: Window::DEFAULT,
+      preemphasis: Framing::DEFAULT_PREEMPHASIS
+    )
+      assert_rate!(waveform)
+
+      length = waveform.seconds_to_samples(window_seconds)
+      taper = Window.resolve(window).call(length)
+      emphasized = preemphasis ? Framing.preemphasis(waveform.samples, coefficient: preemphasis) : waveform.samples
+
+      Framing
+        .frames(emphasized, window: length, hop: waveform.seconds_to_samples(hop_seconds))
+        .map { |frame| call(@spectrum.power(Window.apply(frame, taper))) }
+    end
+
+    private
+
+    def assert_rate!(waveform)
+      return if waveform.sample_rate == @filterbank.sample_rate
+
+      raise(
+        ArgumentError,
+        "waveform sample rate #{waveform.sample_rate} does not match the filterbank rate #{@filterbank.sample_rate}"
+      )
+    end
+  end
+end

data/lib/dsprb/parabolic.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module DSP
+  module Parabolic
+    FLAT_TOLERANCE = 1e-12
+
+    module_function
+
+    # Offset in samples of the vertex of the parabola through three equally
+    # spaced points, used to refine a discrete extremum to sub-sample accuracy.
+    def vertex_offset(previous, current, following)
+      curvature = (2.0 * current) - previous - following
+      return 0.0 if curvature.abs < FLAT_TOLERANCE
+
+      0.5 * (following - previous) / curvature
+    end
+  end
+end

data/lib/dsprb/pitch_track.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module DSP
+  PitchTrack = Data.define(:f0, :confidence, :times, :hop_seconds) do
+    def length = f0.length
+
+    def empty? = f0.empty?
+
+    def voiced_frames = f0.count(&:positive?)
+
+    def voiced_ratio = f0.empty? ? 0.0 : voiced_frames.to_f / f0.length
+
+    def voiced_f0 = f0.select(&:positive?)
+
+    def each_voiced
+      return enum_for(:each_voiced) unless block_given?
+
+      f0.each_with_index do |frequency, index|
+        yield(frequency, times[index], confidence[index]) if frequency.positive?
+      end
+    end
+  end
+end

data/lib/dsprb/resolver.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module DSP
+  module Resolver
+    module_function
+
+    def call(value, registry, kind)
+      return value if value.respond_to?(:call)
+
+      registry.fetch(value) do
+        raise(
+          UnknownStrategyError,
+          "unknown #{kind} #{value.inspect}: expected one of #{registry.keys.join(", ")} " \
+            "or an object responding to #call"
+        )
+      end
+    end
+  end
+end

data/lib/dsprb/scales.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module DSP
+  module Scales
+    # O'Shaughnessy's mel scale, m = 2595 log10(1 + f / 700).
+    MEL_SCALE = 2595.0
+    MEL_BREAK_HZ = 700.0
+
+    SEMITONES_PER_OCTAVE = 12.0
+
+    module_function
+
+    def hz_to_mel(hz) = MEL_SCALE * Math.log10(1.0 + (hz / MEL_BREAK_HZ))
+
+    def mel_to_hz(mel) = MEL_BREAK_HZ * ((10.0 ** (mel / MEL_SCALE)) - 1.0)
+
+    def hz_to_semitones(hz, reference:) = SEMITONES_PER_OCTAVE * Math.log2(hz / reference)
+
+    def semitones_to_hz(semitones, reference:) = reference * (2.0 ** (semitones / SEMITONES_PER_OCTAVE))
+  end
+end

data/lib/dsprb/spectral_moments.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module DSP
+  SpectralMoments = Data.define(:centroid, :spread, :skewness, :kurtosis) do
+    # Below this the band carries no measurable energy and the moments are undefined.
+    ENERGY_FLOOR = 1e-12
+    VARIANCE_FLOOR = 1e-12
+
+    # Fricative energy sits well above the voiced band, so the default window starts high.
+    DEFAULT_LOW_HZ = 500.0
+
+    # Keeps the anti-aliasing roll-off out of the measured band.
+    HIGH_MARGIN_HZ = 200.0
+
+    def self.zero = new(centroid: 0.0, spread: 0.0, skewness: 0.0, kurtosis: 0.0)
+
+    def self.of(power, sample_rate:, size:, low: DEFAULT_LOW_HZ, high: nil)
+      ceiling = high || ((sample_rate / 2.0) - HIGH_MARGIN_HZ)
+      frequencies, weights, total = collect(power, sample_rate, size, low, ceiling)
+      return zero if total <= ENERGY_FLOOR
+
+      centroid = frequencies.each_with_index.sum { |frequency, index| frequency * weights[index] } / total
+      from_central_moments(centroid, central_moments(frequencies, weights, centroid, total))
+    end
+
+    def self.collect(power, sample_rate, size, low, high)
+      frequencies = []
+      weights = []
+      total = 0.0
+
+      index = 0
+      while index < power.length
+        frequency = index * sample_rate / size.to_f
+        if frequency >= low && frequency <= high
+          frequencies << frequency
+          weights << power[index]
+          total += power[index]
+        end
+
+        index += 1
+      end
+
+      [frequencies, weights, total]
+    end
+
+    def self.central_moments(frequencies, weights, centroid, total)
+      second = 0.0
+      third = 0.0
+      fourth = 0.0
+
+      index = 0
+      while index < frequencies.length
+        deviation = frequencies[index] - centroid
+        squared = deviation * deviation
+        weight = weights[index]
+        second += weight * squared
+        third += weight * squared * deviation
+        fourth += weight * squared * squared
+        index += 1
+      end
+
+      [second / total, third / total, fourth / total]
+    end
+
+    # Kurtosis is reported in excess form, so a Gaussian spectrum yields zero.
+    def self.from_central_moments(centroid, moments)
+      second, third, fourth = moments
+      deviation = Math.sqrt([second, VARIANCE_FLOOR].max)
+
+      new(
+        centroid: centroid,
+        spread: deviation,
+        skewness: third / (deviation ** 3),
+        kurtosis: (fourth / (deviation ** 4)) - 3.0
+      )
+    end
+
+    private_class_method :collect, :central_moments, :from_central_moments
+  end
+end

data/lib/dsprb/spectrum.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module DSP
+  class Spectrum
+    attr_reader :size, :bins, :transform
+
+    def initialize(size, transform: nil)
+      @size = Integer(size)
+      @transform = transform || Fourier::Radix2.new(@size)
+      @bins = (@size / 2) + 1
+      freeze
+    end
+
+    def power(frame)
+      real = Array.new(@size, 0.0)
+      imaginary = Array.new(@size, 0.0)
+      limit = [frame.length, @size].min
+      index = 0
+      while index < limit
+        real[index] = frame[index].to_f
+        index += 1
+      end
+
+      @transform.call(real, imaginary)
+
+      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

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