muze 0.1.0

data/lib/muze/feature/chroma.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Muze
+  module Feature
+    module_function
+
+    # @param y [Numo::SFloat, Array<Float>, nil]
+    # @param sr [Integer]
+    # @param s [Numo::SFloat, nil]
+    # @param n_chroma [Integer]
+    # @param n_fft [Integer]
+    # @param hop_length [Integer]
+    # @param norm [Integer, nil]
+    # @return [Numo::SFloat] shape: [n_chroma, frames]
+    def chroma_stft(y: nil, sr: 22_050, s: nil, n_chroma: 12, n_fft: 2048, hop_length: 512, norm: 2)
+      spectrum = if s
+                   Numo::SFloat.cast(s)
+                 else
+                   stft_matrix = Muze.stft(y, n_fft:, hop_length:)
+                   magnitude, = Muze.magphase(stft_matrix)
+                   magnitude
+                 end
+
+      spectrum = spectrum.expand_dims(1) if spectrum.ndim == 1
+      filter_bank = Muze::Filters.chroma(sr:, n_fft:, n_chroma:)
+      chroma = matrix_multiply(filter_bank, spectrum)
+      normalize(chroma, norm:)
+    end
+
+    def matrix_multiply(left, right)
+      left_rows, left_cols = left.shape
+      right_rows, right_cols = right.shape
+      raise Muze::ParameterError, "Matrix dimensions do not align" unless left_cols == right_rows
+
+      output = Numo::SFloat.zeros(left_rows, right_cols)
+      left_rows.times do |row|
+        right_cols.times do |col|
+          sum = 0.0
+          left_cols.times { |idx| sum += left[row, idx] * right[idx, col] }
+          output[row, col] = sum
+        end
+      end
+
+      output
+    end
+    private_class_method :matrix_multiply
+
+    def normalize(chroma, norm:)
+      return chroma if norm.nil?
+
+      frames = chroma.shape[1]
+      frames.times do |frame_index|
+        vector = chroma[true, frame_index]
+        denominator = if norm == 1
+                        vector.abs.sum
+                      else
+                        Math.sqrt((vector**2).sum)
+                      end
+
+        next if denominator <= 1.0e-12
+
+        chroma[true, frame_index] = vector / denominator
+      end
+      chroma
+    end
+    private_class_method :normalize
+  end
+end

data/lib/muze/feature/mfcc.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Muze
+  # Feature extraction methods.
+  module Feature
+    module_function
+
+    # @param y [Numo::SFloat, Array<Float>, nil]
+    # @param sr [Integer]
+    # @param s [Numo::SFloat, nil]
+    # @param n_fft [Integer]
+    # @param hop_length [Integer]
+    # @param n_mels [Integer]
+    # @param fmin [Float]
+    # @param fmax [Float, nil]
+    # @return [Numo::SFloat]
+    def melspectrogram(y: nil, sr: 22_050, s: nil, n_fft: 2048, hop_length: 512, n_mels: 128, fmin: 0.0, fmax: nil)
+      power_spectrum = s ? Numo::SFloat.cast(s) : power_spectrogram(y, n_fft:, hop_length:)
+      filter_bank = Muze::Filters.mel(sr:, n_fft:, n_mels:, fmin:, fmax:)
+      matrix_multiply(filter_bank, power_spectrum)
+    end
+
+    # @param y [Numo::SFloat, Array<Float>, nil]
+    # @param sr [Integer]
+    # @param s [Numo::SFloat, nil]
+    # @param n_mfcc [Integer]
+    # @param n_fft [Integer]
+    # @param hop_length [Integer]
+    # @param n_mels [Integer]
+    # @param fmin [Float]
+    # @param fmax [Float, nil]
+    # @return [Numo::SFloat]
+    def mfcc(y: nil, sr: 22_050, s: nil, n_mfcc: 20, n_fft: 2048, hop_length: 512, n_mels: 128, fmin: 0.0, fmax: nil)
+      raise Muze::ParameterError, "n_mfcc must be positive" unless n_mfcc.positive?
+
+      mel_spec = if s
+                   Numo::SFloat.cast(s)
+                 else
+                   melspectrogram(y:, sr:, n_fft:, hop_length:, n_mels:, fmin:, fmax:)
+                 end
+
+      log_mel = Muze.power_to_db(mel_spec)
+      dct = Muze::Core::DCT.dct(log_mel, axis: 0, norm: :ortho)
+      dct[0...n_mfcc, true].cast_to(Numo::SFloat)
+    end
+
+    # @param data [Numo::SFloat]
+    # @param order [Integer]
+    # @param width [Integer]
+    # @param mode [Symbol]
+    # @return [Numo::SFloat]
+    def delta(data, order: 1, width: 9, mode: :interp)
+      raise Muze::ParameterError, "order must be >= 1" unless order >= 1
+      raise Muze::ParameterError, "width must be odd and >= 3" unless width.odd? && width >= 3
+      raise Muze::ParameterError, "mode must be :interp" unless mode == :interp
+
+      result = Numo::SFloat.cast(data)
+      order.times { result = finite_difference(result, width) }
+      result
+    end
+
+    def power_spectrogram(y, n_fft:, hop_length:)
+      raise Muze::ParameterError, "y must be provided when s is nil" if y.nil?
+
+      stft_matrix = Muze.stft(y, n_fft:, hop_length:)
+      magnitude, = Muze.magphase(stft_matrix)
+      (magnitude**2).cast_to(Numo::SFloat)
+    end
+    private_class_method :power_spectrogram
+
+    def finite_difference(data, width)
+      matrix = Numo::SFloat.cast(data)
+      matrix = matrix.expand_dims(1) if matrix.ndim == 1
+
+      rows, cols = matrix.shape
+      half = width / 2
+      denominator = (1..half).sum { |idx| 2.0 * (idx * idx) }
+      output = Numo::SFloat.zeros(rows, cols)
+
+      rows.times do |row|
+        cols.times do |col|
+          numerator = 0.0
+          (1..half).each do |offset|
+            left = [[col - offset, 0].max, cols - 1].min
+            right = [[col + offset, 0].max, cols - 1].min
+            numerator += offset * (matrix[row, right] - matrix[row, left])
+          end
+          output[row, col] = numerator / denominator
+        end
+      end
+
+      data.ndim == 1 ? output[true, 0] : output
+    end
+    private_class_method :finite_difference
+
+    def matrix_multiply(left, right)
+      left_matrix = Numo::SFloat.cast(left)
+      right_matrix = Numo::SFloat.cast(right)
+      left_matrix = left_matrix.expand_dims(1) if left_matrix.ndim == 1
+      right_matrix = right_matrix.expand_dims(1) if right_matrix.ndim == 1
+
+      left_rows, left_cols = left_matrix.shape
+      right_rows, right_cols = right_matrix.shape
+      raise Muze::ParameterError, "Matrix dimensions do not align" unless left_cols == right_rows
+
+      output = Numo::SFloat.zeros(left_rows, right_cols)
+
+      left_rows.times do |row|
+        right_cols.times do |col|
+          sum = 0.0
+          left_cols.times { |idx| sum += left_matrix[row, idx] * right_matrix[idx, col] }
+          output[row, col] = sum
+        end
+      end
+
+      output
+    end
+    private_class_method :matrix_multiply
+  end
+end

data/lib/muze/feature/spectral.rb

@@ -0,0 +1,266 @@
+# frozen_string_literal: true
+
+module Muze
+  module Feature
+    module_function
+
+    # @param y [Numo::SFloat, Array<Float>, nil]
+    # @param s [Numo::SFloat, nil]
+    # @param sr [Integer]
+    # @param n_fft [Integer]
+    # @param hop_length [Integer]
+    # @return [Numo::SFloat] shape: [1, frames]
+    def spectral_centroid(y: nil, s: nil, sr: 22_050, n_fft: 2048, hop_length: 512)
+      magnitude, frequencies = prepare_magnitude(y:, s:, sr:, n_fft:, hop_length:)
+      _, frames = magnitude.shape
+      output = Numo::SFloat.zeros(1, frames)
+
+      frames.times do |frame_index|
+        spectrum = magnitude[true, frame_index]
+        denominator = spectrum.sum
+        if denominator <= 0.0
+          output[0, frame_index] = 0.0
+          next
+        end
+
+        numerator = 0.0
+        frequencies.length.times { |bin| numerator += frequencies[bin] * spectrum[bin] }
+        output[0, frame_index] = numerator / denominator
+      end
+
+      output
+    end
+
+    # @param y [Numo::SFloat, Array<Float>, nil]
+    # @param s [Numo::SFloat, nil]
+    # @param sr [Integer]
+    # @param n_fft [Integer]
+    # @param hop_length [Integer]
+    # @param p [Integer]
+    # @return [Numo::SFloat] shape: [1, frames]
+    def spectral_bandwidth(y: nil, s: nil, sr: 22_050, n_fft: 2048, hop_length: 512, p: 2)
+      magnitude, frequencies = prepare_magnitude(y:, s:, sr:, n_fft:, hop_length:)
+      centroids = spectral_centroid(y:, s: magnitude, sr:, n_fft:, hop_length:)
+      _, frames = magnitude.shape
+      output = Numo::SFloat.zeros(1, frames)
+
+      frames.times do |frame_index|
+        spectrum = magnitude[true, frame_index]
+        denominator = spectrum.sum
+        if denominator <= 0.0
+          output[0, frame_index] = 0.0
+          next
+        end
+
+        sum = 0.0
+        frequencies.length.times do |bin|
+          distance = (frequencies[bin] - centroids[0, frame_index]).abs
+          sum += spectrum[bin] * (distance**p)
+        end
+
+        output[0, frame_index] = (sum / denominator)**(1.0 / p)
+      end
+
+      output
+    end
+
+    # @param y [Numo::SFloat, Array<Float>, nil]
+    # @param s [Numo::SFloat, nil]
+    # @param sr [Integer]
+    # @param n_fft [Integer]
+    # @param hop_length [Integer]
+    # @param roll_percent [Float]
+    # @return [Numo::SFloat] shape: [1, frames]
+    def spectral_rolloff(y: nil, s: nil, sr: 22_050, n_fft: 2048, hop_length: 512, roll_percent: 0.85)
+      magnitude, frequencies = prepare_magnitude(y:, s:, sr:, n_fft:, hop_length:)
+      _, frames = magnitude.shape
+      output = Numo::SFloat.zeros(1, frames)
+
+      frames.times do |frame_index|
+        spectrum = magnitude[true, frame_index]
+        threshold = spectrum.sum * roll_percent
+        cumulative = 0.0
+        rolloff_frequency = frequencies.last
+
+        frequencies.length.times do |bin|
+          cumulative += spectrum[bin]
+          if cumulative >= threshold
+            rolloff_frequency = frequencies[bin]
+            break
+          end
+        end
+
+        output[0, frame_index] = rolloff_frequency
+      end
+
+      output
+    end
+
+    # @param y [Numo::SFloat, Array<Float>, nil]
+    # @param s [Numo::SFloat, nil]
+    # @param amin [Float]
+    # @return [Numo::SFloat] shape: [1, frames]
+    def spectral_flatness(y: nil, s: nil, n_fft: 2048, hop_length: 512, amin: 1.0e-10)
+      magnitude, = prepare_magnitude(y:, s:, sr: 22_050, n_fft:, hop_length:)
+      _, frames = magnitude.shape
+      output = Numo::SFloat.zeros(1, frames)
+
+      frames.times do |frame_index|
+        spectrum = magnitude[true, frame_index].to_a.map { |value| [value, amin].max }
+        geometric = Math.exp(spectrum.sum { |value| Math.log(value) } / spectrum.length)
+        arithmetic = spectrum.sum(0.0) / spectrum.length
+        output[0, frame_index] = geometric / arithmetic
+      end
+
+      output
+    end
+
+    # @param y [Numo::SFloat, Array<Float>, nil]
+    # @param s [Numo::SFloat, nil]
+    # @param n_bands [Integer]
+    # @param quantile [Float]
+    # @return [Numo::SFloat] shape: [n_bands + 1, frames]
+    def spectral_contrast(y: nil, s: nil, n_fft: 2048, hop_length: 512, n_bands: 6, quantile: 0.02)
+      magnitude, = prepare_magnitude(y:, s:, sr: 22_050, n_fft:, hop_length:)
+      bins, frames = magnitude.shape
+      edges = Array.new(n_bands + 2) { |idx| ((bins - 1) * idx / (n_bands + 1).to_f).round }
+      output = Numo::SFloat.zeros(n_bands + 1, frames)
+
+      (n_bands + 1).times do |band|
+        lower = edges[band]
+        upper = [edges[band + 1], lower + 1].max
+
+        frames.times do |frame_index|
+          segment = magnitude[lower...upper, frame_index].to_a.sort
+          next if segment.empty?
+
+          low_idx = [(segment.length * quantile).floor, segment.length - 1].min
+          high_idx = [(segment.length * (1.0 - quantile)).floor, segment.length - 1].min
+          valley = [segment[low_idx], 1.0e-10].max
+          peak = [segment[high_idx], 1.0e-10].max
+          output[band, frame_index] = 10.0 * Math.log10(peak / valley)
+        end
+      end
+
+      output
+    end
+
+    # @param y [Numo::SFloat, Array<Float>]
+    # @param frame_length [Integer]
+    # @param hop_length [Integer]
+    # @return [Numo::SFloat] shape: [1, frames]
+    def zero_crossing_rate(y, frame_length: 2048, hop_length: 512)
+      signal = y.is_a?(Numo::NArray) ? y.to_a : Array(y)
+      frames = frame_signal(signal, frame_length, hop_length)
+      values = frames.map do |frame|
+        crossings = 0
+        (1...frame.length).each { |idx| crossings += 1 if (frame[idx - 1] >= 0) != (frame[idx] >= 0) }
+        crossings.to_f / frame_length
+      end
+
+      Numo::SFloat[values]
+    end
+
+    # @param y [Numo::SFloat, Array<Float>, nil]
+    # @param s [Numo::SFloat, nil]
+    # @param frame_length [Integer]
+    # @param hop_length [Integer]
+    # @return [Numo::SFloat] shape: [1, frames]
+    def rms(y: nil, s: nil, frame_length: 2048, hop_length: 512)
+      if s
+        matrix = Numo::SFloat.cast(s)
+        matrix = matrix.expand_dims(1) if matrix.ndim == 1
+        _, frames = matrix.shape
+        values = Array.new(frames) do |frame_index|
+          frame = matrix[true, frame_index]
+          Math.sqrt((frame**2).sum / frame.size)
+        end
+
+        return Numo::SFloat[values]
+      end
+
+      signal = y.is_a?(Numo::NArray) ? y.to_a : Array(y)
+      frames = frame_signal(signal, frame_length, hop_length)
+      values = frames.map do |frame|
+        Math.sqrt(frame.sum { |value| value * value } / frame.length)
+      end
+
+      Numo::SFloat[values]
+    end
+
+    # @param y [Numo::SFloat, Array<Float>, nil]
+    # @param onset_envelope [Numo::SFloat, Array<Float>, nil]
+    # @param sr [Integer]
+    # @param hop_length [Integer]
+    # @param win_length [Integer]
+    # @return [Numo::SFloat]
+    def tempogram(y: nil, onset_envelope: nil, sr: 22_050, hop_length: 512, win_length: 384)
+      envelope = if onset_envelope
+                   onset_envelope.is_a?(Numo::NArray) ? onset_envelope.to_a : Array(onset_envelope)
+                 else
+                   onset_env_from_signal(y, sr:, hop_length:)
+                 end
+
+      frames = envelope.length
+      tempogram = Numo::SFloat.zeros(win_length, frames)
+
+      frames.times do |frame_index|
+        window_start = [0, frame_index - win_length + 1].max
+        segment = envelope[window_start..frame_index]
+        win_length.times do |lag|
+          break if lag >= segment.length
+
+          value = 0.0
+          (lag...segment.length).each do |offset|
+            value += segment[offset] * segment[offset - lag]
+          end
+          tempogram[lag, frame_index] = value
+        end
+      end
+
+      tempogram
+    end
+
+    def prepare_magnitude(y:, s:, sr:, n_fft:, hop_length:)
+      spectrum = if s
+                   Numo::SFloat.cast(s)
+                 else
+                   stft_matrix = Muze.stft(y, n_fft:, hop_length:)
+                   magnitude, = Muze.magphase(stft_matrix)
+                   magnitude
+                 end
+
+      spectrum = spectrum.expand_dims(1) if spectrum.ndim == 1
+      bins, = spectrum.shape
+      fft_size = n_fft || ((bins - 1) * 2)
+      frequencies = Array.new(bins) { |index| index * sr.to_f / fft_size }
+      [spectrum, frequencies]
+    end
+    private_class_method :prepare_magnitude
+
+    def frame_signal(signal, frame_length, hop_length)
+      return [signal + Array.new(frame_length - signal.length, 0.0)] if signal.length <= frame_length
+
+      frame_count = ((signal.length - frame_length) / hop_length) + 1
+      Array.new(frame_count) do |index|
+        start = index * hop_length
+        signal[start, frame_length]
+      end
+    end
+    private_class_method :frame_signal
+
+    def onset_env_from_signal(y, sr:, hop_length:)
+      mel_spec = melspectrogram(y:, sr:, n_fft: 1024, hop_length:, n_mels: 40)
+      _, frames = mel_spec.shape
+      onset = Array.new(frames, 0.0)
+      frames.times do |frame_index|
+        next if frame_index.zero?
+
+        diff = mel_spec[true, frame_index] - mel_spec[true, frame_index - 1]
+        onset[frame_index] = diff.clip(0.0, Float::INFINITY).sum
+      end
+      onset
+    end
+    private_class_method :onset_env_from_signal
+  end
+end

data/lib/muze/filters/chroma_filter.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Muze
+  module Filters
+    module_function
+
+    # @param sr [Integer]
+    # @param n_fft [Integer]
+    # @param n_chroma [Integer]
+    # @param tuning [Float]
+    # @return [Numo::SFloat] shape: [n_chroma, 1 + n_fft/2]
+    def chroma(sr:, n_fft:, n_chroma: 12, tuning: 0.0)
+      raise Muze::ParameterError, "sr must be positive" unless sr.positive?
+      raise Muze::ParameterError, "n_fft must be positive" unless n_fft.positive?
+      raise Muze::ParameterError, "n_chroma must be positive" unless n_chroma.positive?
+
+      bins = (n_fft / 2) + 1
+      matrix = Numo::SFloat.zeros(n_chroma, bins)
+
+      bins.times do |bin|
+        frequency = (bin * sr.to_f) / n_fft
+        next if frequency <= 0.0
+
+        midi = 69.0 + (12.0 * Math.log2(frequency / 440.0)) - tuning
+        chroma_position = midi % n_chroma
+
+        n_chroma.times do |chroma_index|
+          distance = circular_distance(chroma_index, chroma_position, n_chroma)
+          matrix[chroma_index, bin] = Math.exp(-(distance**2) / 2.0)
+        end
+      end
+
+      normalize_columns(matrix)
+    end
+
+    def circular_distance(a, b, modulo)
+      direct = (a - b).abs
+      [direct, modulo - direct].min
+    end
+    private_class_method :circular_distance
+
+    def normalize_columns(matrix)
+      cols = matrix.shape[1]
+      cols.times do |col|
+        sum = matrix[true, col].sum
+        next if sum <= 0.0
+
+        matrix[true, col] = matrix[true, col] / sum
+      end
+      matrix
+    end
+    private_class_method :normalize_columns
+  end
+end

data/lib/muze/filters/mel.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Muze
+  # Filterbank generation utilities.
+  module Filters
+    module_function
+
+    # @param sr [Integer]
+    # @param n_fft [Integer]
+    # @param n_mels [Integer]
+    # @param fmin [Float]
+    # @param fmax [Float, nil]
+    # @param htk [Boolean]
+    # @return [Numo::SFloat] shape: [n_mels, 1 + n_fft/2]
+    def mel(sr: 22_050, n_fft: 2048, n_mels: 128, fmin: 0.0, fmax: nil, htk: false)
+      raise Muze::ParameterError, "sr must be positive" unless sr.positive?
+      raise Muze::ParameterError, "n_fft must be positive" unless n_fft.positive?
+      raise Muze::ParameterError, "n_mels must be positive" unless n_mels.positive?
+
+      fmax ||= sr / 2.0
+      mel_min = hz_to_mel(fmin, htk:)
+      mel_max = hz_to_mel(fmax, htk:)
+
+      mel_points = Array.new(n_mels + 2) do |idx|
+        mel_min + ((mel_max - mel_min) * idx / (n_mels + 1).to_f)
+      end
+      hz_points = mel_points.map { |mel_value| mel_to_hz(mel_value, htk:) }
+      fft_bins = hz_points.map { |hz| ((n_fft + 1) * hz / sr).floor }
+
+      matrix = Numo::SFloat.zeros(n_mels, (n_fft / 2) + 1)
+
+      n_mels.times do |mel_index|
+        left = fft_bins[mel_index]
+        center = fft_bins[mel_index + 1]
+        right = fft_bins[mel_index + 2]
+
+        next if center <= left || right <= center
+
+        (left...center).each do |bin|
+          next unless bin.between?(0, (n_fft / 2))
+
+          matrix[mel_index, bin] = (bin - left).to_f / (center - left)
+        end
+
+        (center...right).each do |bin|
+          next unless bin.between?(0, (n_fft / 2))
+
+          matrix[mel_index, bin] = (right - bin).to_f / (right - center)
+        end
+      end
+
+      matrix
+    end
+
+    # @param hz [Float]
+    # @param htk [Boolean]
+    # @return [Float]
+    def hz_to_mel(hz, htk: false)
+      return 2595.0 * Math.log10(1.0 + (hz / 700.0)) if htk
+
+      f_sp = 200.0 / 3.0
+      min_log_hz = 1000.0
+      min_log_mel = min_log_hz / f_sp
+      log_step = Math.log(6.4) / 27.0
+
+      if hz < min_log_hz
+        hz / f_sp
+      else
+        min_log_mel + (Math.log(hz / min_log_hz) / log_step)
+      end
+    end
+
+    # @param mel_value [Float]
+    # @param htk [Boolean]
+    # @return [Float]
+    def mel_to_hz(mel_value, htk: false)
+      return 700.0 * ((10.0**(mel_value / 2595.0)) - 1.0) if htk
+
+      f_sp = 200.0 / 3.0
+      min_log_hz = 1000.0
+      min_log_mel = min_log_hz / f_sp
+      log_step = Math.log(6.4) / 27.0
+
+      if mel_value < min_log_mel
+        mel_value * f_sp
+      else
+        min_log_hz * Math.exp(log_step * (mel_value - min_log_mel))
+      end
+    end
+  end
+end