dsprb 1.0.0

data/lib/dsprb/wav.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module DSP
+  module Wav
+    PCM = 1
+    IEEE_FLOAT = 3
+
+    # WAVE_FORMAT_EXTENSIBLE stores the effective format in the first two bytes
+    # of its SubFormat GUID rather than in the format field itself.
+    EXTENSIBLE = 0xFFFE
+
+    HEADER_BYTES = 12
+    CHUNK_HEADER_BYTES = 8
+
+    # Unsigned 8-bit PCM is the one depth WAVE stores with a midpoint offset.
+    EIGHT_BIT_MIDPOINT = 128.0
+
+    module_function
+
+    def read(path) = decode(File.binread(path))
+
+    def decode(bytes)
+      assert_riff!(bytes)
+
+      format = nil
+      channels = nil
+      sample_rate = nil
+      bits = nil
+      data = nil
+      position = HEADER_BYTES
+
+      while position + CHUNK_HEADER_BYTES <= bytes.bytesize
+        identifier = bytes[position, 4]
+        size = bytes[position + 4, 4].unpack1("V")
+        body = bytes[position + CHUNK_HEADER_BYTES, size]
+
+        case identifier
+        when "fmt "
+          format, channels, sample_rate, _byte_rate, _align, bits = body.unpack("vvVVvv")
+          format = body[24, 2].unpack1("v") if format == EXTENSIBLE && body.bytesize >= 26
+        when "data"
+          data = body
+        end
+
+        position += CHUNK_HEADER_BYTES + size + (size.odd? ? 1 : 0)
+      end
+
+      raise FormatError, "no fmt chunk" if sample_rate.nil?
+      raise FormatError, "no data chunk" if data.nil?
+
+      Waveform.new(samples: downmix(decode_samples(data, format, bits), channels), sample_rate: sample_rate)
+    end
+
+    def assert_riff!(bytes)
+      return if bytes.bytesize >= HEADER_BYTES && bytes[0, 4] == "RIFF" && bytes[8, 4] == "WAVE"
+
+      raise FormatError, "not a RIFF/WAVE stream"
+    end
+
+    def decode_samples(data, format, bits)
+      case [format, bits]
+      in [PCM, 8]
+        data.unpack("C*").map { |value| (value - EIGHT_BIT_MIDPOINT) / EIGHT_BIT_MIDPOINT }
+      in [PCM, 16]
+        scale(data.unpack("s<*"), 15)
+      in [PCM, 24]
+        decode_packed_24(data)
+      in [PCM, 32]
+        scale(data.unpack("l<*"), 31)
+      in [IEEE_FLOAT, 32]
+        data.unpack("e*")
+      in [IEEE_FLOAT, 64]
+        data.unpack("E*")
+      else
+        raise FormatError, "unsupported encoding: format #{format.inspect}, #{bits.inspect} bit"
+      end
+    end
+
+    def scale(integers, magnitude_bits)
+      full_scale = (1 << magnitude_bits).to_f
+      integers.map { |value| value / full_scale }
+    end
+
+    def decode_packed_24(data)
+      sign_bit = 1 << 23
+      full_scale = sign_bit.to_f
+
+      data.unpack("C*").each_slice(3).filter_map do |low, middle, high|
+        next if high.nil?
+
+        value = (high << 16) | (middle << 8) | low
+        value -= sign_bit << 1 if value >= sign_bit
+        value / full_scale
+      end
+    end
+
+    def downmix(samples, channels)
+      return samples if channels.nil? || channels <= 1
+
+      Array.new(samples.length / channels) do |index|
+        offset = index * channels
+        total = 0.0
+        channel = 0
+        while channel < channels
+          total += samples[offset + channel]
+          channel += 1
+        end
+
+        total / channels
+      end
+    end
+  end
+end

data/lib/dsprb/waveform.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+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)
+    end
+
+    def length = samples.length
+
+    def duration = samples.length / sample_rate
+
+    def nyquist = sample_rate / 2.0
+
+    def empty? = samples.empty?
+
+    def frames(window:, hop:) = Framing.frames(samples, window: window, hop: hop)
+
+    def seconds_to_samples(seconds) = (seconds * sample_rate).round
+  end
+end

data/lib/dsprb/window.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module DSP
+  module Window
+    # Generalized cosine windows 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
+
+    module_function
+
+    def rectangular(length)
+      assert_length!(length)
+
+      Array.new(length, 1.0)
+    end
+
+    def hamming(length) = cosine_sum(length, HAMMING)
+
+    def hann(length) = cosine_sum(length, HANN)
+
+    def blackman(length) = cosine_sum(length, BLACKMAN)
+
+    def cosine_sum(length, coefficients)
+      assert_length!(length)
+      return [1.0] if length == 1
+
+      span = (length - 1).to_f
+
+      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) }
+      end
+    end
+
+    def apply(frame, window) = Array.new(frame.length) { |index| frame[index] * window[index] }
+
+    def assert_length!(length)
+      return if length.is_a?(Integer) && length.positive?
+
+      raise ArgumentError, "window length must be a positive Integer, got #{length.inspect}"
+    end
+
+    REGISTRY = {
+      rectangular: method(:rectangular),
+      hamming: method(:hamming),
+      hann: method(:hann),
+      blackman: method(:blackman)
+    }.freeze
+
+    DEFAULT = :hamming
+
+    def resolve(window) = Resolver.call(window, REGISTRY, "window")
+  end
+end

data/lib/dsprb/yin.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module DSP
+  class Yin
+    DEFAULT_MINIMUM_HZ = 70.0
+    DEFAULT_MAXIMUM_HZ = 500.0
+    DEFAULT_HOP_SECONDS = 0.008
+
+    # Absolute threshold of the YIN paper: the first dip of the cumulative mean
+    # normalized difference below it is taken as the period.
+    DEFAULT_THRESHOLD = 0.15
+
+    # 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.
+    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
+
+    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
+    )
+      @minimum_frequency = Float(minimum_frequency)
+      @maximum_frequency = Float(maximum_frequency)
+      @hop_seconds = Float(hop_seconds)
+      @threshold = Float(threshold)
+      @voiced_threshold = Float(voiced_threshold)
+      @working_rate = Float(working_rate)
+
+      validate!
+      freeze
+    end
+
+    def call(waveform)
+      reduced = Decimator.new(Decimator.factor_for(waveform.sample_rate, @working_rate)).call(waveform)
+      rate = reduced.sample_rate
+      shortest = (rate / @maximum_frequency).floor.clamp(2, MAXIMUM_LAG)
+      longest = (rate / @minimum_frequency).ceil.clamp(shortest + 2, MAXIMUM_LAG)
+      window = longest * 2
+      hop = [(rate * @hop_seconds).round, 1].max
+
+      track(reduced.samples, rate: rate, window: window, hop: hop, shortest: shortest, longest: longest)
+    end
+
+    private
+
+    def validate!
+      unless @minimum_frequency.positive? && @minimum_frequency < @maximum_frequency
+        raise(
+          ArgumentError,
+          "expected 0 < minimum_frequency < maximum_frequency, " \
+            "got #{@minimum_frequency} and #{@maximum_frequency}"
+        )
+      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?
+    end
+
+    def track(samples, rate:, window:, hop:, shortest:, longest:)
+      f0 = []
+      confidence = []
+      times = []
+
+      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
+        times << (position / rate)
+        position += hop
+      end
+
+      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
+
+      lag = shortest
+      while lag <= longest
+        running += raw[lag]
+        normalized[lag] = running.zero? ? 1.0 : raw[lag] * (lag - shortest + 1) / running
+        lag += 1
+      end
+
+      normalized
+    end
+
+    def squared_difference(samples, position, window, shortest, longest)
+      raw = Array.new(longest + 1, 0.0)
+
+      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
+    end
+
+    def select_lag(normalized, shortest, longest)
+      lag = shortest + 1
+      while lag < longest
+        return lag if normalized[lag] < @threshold && normalized[lag] <= normalized[lag + 1]
+
+        lag += 1
+      end
+
+      global_minimum(normalized, shortest, longest)
+    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
+      end
+
+      best
+    end
+
+    def evaluate(normalized, lag, shortest, longest, rate)
+      return [0.0, 0.0] unless lag > shortest && lag < longest
+
+      offset = Parabolic.vertex_offset(normalized[lag - 1], normalized[lag], normalized[lag + 1])
+      frequency = rate / (lag + offset)
+      dip = normalized[lag]
+      return [0.0, 0.0] unless dip < @voiced_threshold && frequency.between?(@minimum_frequency, @maximum_frequency)
+
+      [frequency, (1.0 - dip).clamp(0.0, 1.0)]
+    end
+  end
+end

data/lib/dsprb.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require_relative "dsprb/version"
+require_relative "dsprb/errors"
+require_relative "dsprb/resolver"
+require_relative "dsprb/parabolic"
+require_relative "dsprb/waveform"
+require_relative "dsprb/wav"
+require_relative "dsprb/window"
+require_relative "dsprb/framing"
+require_relative "dsprb/fourier"
+require_relative "dsprb/spectrum"
+require_relative "dsprb/scales"
+require_relative "dsprb/mel_filterbank"
+require_relative "dsprb/dct"
+require_relative "dsprb/mfcc"
+require_relative "dsprb/decimator"
+require_relative "dsprb/autocorrelation"
+require_relative "dsprb/lpc"
+require_relative "dsprb/formants"
+require_relative "dsprb/pitch_track"
+require_relative "dsprb/yin"
+require_relative "dsprb/spectral_moments"
+require_relative "dsprb/energy"
+require_relative "dsprb/biquad"
+require_relative "dsprb/curve"
+
+module DSP
+  module_function
+
+  def read(path) = Wav.read(path)
+
+  def decode(bytes) = Wav.decode(bytes)
+
+  def pitch(waveform, **options) = Yin.new(**options).call(waveform)
+
+  def formants(waveform, **options) = Formants.new(**options).call(waveform)
+
+  def mfcc(
+    waveform,
+    size: Mfcc::DEFAULT_SIZE,
+    coefficients: Mfcc::DEFAULT_COEFFICIENTS,
+    window_seconds: Mfcc::DEFAULT_WINDOW_SECONDS,
+    hop_seconds: Mfcc::DEFAULT_HOP_SECONDS,
+    **options
+  )
+    Mfcc
+      .for(sample_rate: waveform.sample_rate, size: size, coefficients: coefficients, **options)
+      .sequence(waveform, window_seconds: window_seconds, hop_seconds: hop_seconds)
+  end
+
+  def decimate(waveform, factor) = Decimator.new(factor).call(waveform)
+
+  def lowpass(waveform, cutoff:, sections: 2)
+    filter(waveform, Biquad.lowpass(sample_rate: waveform.sample_rate, cutoff: cutoff), sections)
+  end
+
+  def highpass(waveform, cutoff:, sections: 2)
+    filter(waveform, Biquad.highpass(sample_rate: waveform.sample_rate, cutoff: cutoff), sections)
+  end
+
+  def filter(waveform, biquad, sections)
+    waveform.with(samples: biquad.apply(waveform.samples, sections: sections))
+  end
+end