muze 0.1.0 → 1.0.0

data/lib/muze/feature/mfcc.rb

@@ -13,11 +13,27 @@ module Muze
     # @param n_mels [Integer]
     # @param fmin [Float]
     # @param fmax [Float, nil]
+    # @param power [Float]
+    # @param center [Boolean]
+    # @param window [Symbol]
+    # @param pad_mode [Symbol]
+    # @param norm [Symbol, 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)
+    def melspectrogram(y: nil, sr: 22_050, s: nil, n_fft: 2048, hop_length: 512, n_mels: 128, fmin: 0.0, fmax: nil, power: 2.0, center: true, window: :hann, pad_mode: :reflect, norm: nil, s_kind: :power)
+      raise Muze::ParameterError, "power must be positive" unless power.positive?
+      raise Muze::ParameterError, "s_kind must be :power or :magnitude" unless %i[power magnitude].include?(s_kind)
+
+      spectrum = if s
+                   provided = Numo::SFloat.cast(s)
+                   validate_finite_array!(provided.to_a.flatten, "s")
+                   raise Muze::ParameterError, "spectrogram input must be non-negative" if provided.to_a.flatten.any?(&:negative?)
+
+                   s_kind == :magnitude ? (provided**power).cast_to(Numo::SFloat) : provided
+                 else
+                   spectrogram(y, n_fft:, hop_length:, power:, center:, window:, pad_mode:)
+                 end
+      filter_bank = Muze::Filters.mel(sr:, n_fft:, n_mels:, fmin:, fmax:, norm:)
+      Muze::Core::Matrix.multiply(filter_bank, spectrum)
     end
 
     # @param y [Numo::SFloat, Array<Float>, nil]
@@ -29,19 +45,31 @@ module Muze
     # @param n_mels [Integer]
     # @param fmin [Float]
     # @param fmax [Float, nil]
+    # @param dct_type [Integer]
+    # @param lifter [Integer]
+    # @param norm [Symbol, 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)
+    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, dct_type: 2, lifter: 0, norm: :ortho, s_kind: :mel_power)
       raise Muze::ParameterError, "n_mfcc must be positive" unless n_mfcc.positive?
+      raise Muze::ParameterError, "lifter must be >= 0" if lifter.negative?
+      raise Muze::ParameterError, "s_kind must be :mel_power or :log_mel" unless %i[mel_power log_mel].include?(s_kind)
 
       mel_spec = if s
-                   Numo::SFloat.cast(s)
+                   provided = Numo::SFloat.cast(s)
+                   validate_finite_array!(provided.to_a.flatten, "s")
+                   if s_kind == :mel_power && provided.to_a.flatten.any?(&:negative?)
+                     raise Muze::ParameterError, "mel power spectrogram must be non-negative"
+                   end
+
+                   provided
                  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)
+      log_mel = s_kind == :log_mel ? mel_spec : Muze.power_to_db(mel_spec)
+      dct = Muze::Core::DCT.dct(log_mel, type: dct_type, axis: 0, norm:)
+      coeffs = dct[0...n_mfcc, true].cast_to(Numo::SFloat)
+      apply_lifter(coeffs, lifter:)
     end
 
     # @param data [Numo::SFloat]
@@ -52,23 +80,25 @@ module Muze
     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
+      raise Muze::ParameterError, "mode must be :interp, :nearest, :mirror, or :constant" unless %i[interp nearest mirror constant].include?(mode)
 
       result = Numo::SFloat.cast(data)
-      order.times { result = finite_difference(result, width) }
+      original_ndim = result.ndim
+      order.times { result = finite_difference(result, width, mode:) }
+      result = result[true, 0] if original_ndim == 1 && result.ndim == 2
       result
     end
 
-    def power_spectrogram(y, n_fft:, hop_length:)
+    def spectrogram(y, n_fft:, hop_length:, power:, center:, window:, pad_mode:)
       raise Muze::ParameterError, "y must be provided when s is nil" if y.nil?
 
-      stft_matrix = Muze.stft(y, n_fft:, hop_length:)
+      stft_matrix = Muze.stft(y, n_fft:, hop_length:, center:, window:, pad_mode:)
       magnitude, = Muze.magphase(stft_matrix)
-      (magnitude**2).cast_to(Numo::SFloat)
+      (magnitude**power).cast_to(Numo::SFloat)
     end
-    private_class_method :power_spectrogram
+    private_class_method :spectrogram
 
-    def finite_difference(data, width)
+    def finite_difference(data, width, mode:)
       matrix = Numo::SFloat.cast(data)
       matrix = matrix.expand_dims(1) if matrix.ndim == 1
 
@@ -81,40 +111,50 @@ module Muze
         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])
+            left = sample_with_mode(matrix, row, col - offset, cols, mode:)
+            right = sample_with_mode(matrix, row, col + offset, cols, mode:)
+            numerator += offset * (right - left)
           end
           output[row, col] = numerator / denominator
         end
       end
 
-      data.ndim == 1 ? output[true, 0] : output
+      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
+    def sample_with_mode(matrix, row, col, cols, mode:)
+      return matrix[row, col] if col.between?(0, cols - 1)
+
+      case mode
+      when :constant
+        0.0
+      when :mirror
+        matrix[row, mirror_index(col, cols)]
+      else
+        matrix[row, [[col, 0].max, cols - 1].min]
+      end
+    end
+    private_class_method :sample_with_mode
 
-      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
+    def mirror_index(index, length)
+      return 0 if length <= 1
 
-      output = Numo::SFloat.zeros(left_rows, right_cols)
+      period = (length - 1) * 2
+      mirrored = index % period
+      mirrored >= length ? period - mirrored : mirrored
+    end
+    private_class_method :mirror_index
 
-      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
+    def apply_lifter(coeffs, lifter:)
+      return coeffs if lifter.zero?
 
-      output
+      rows, = coeffs.shape
+      rows.times do |index|
+        coeffs[index, true] = coeffs[index, true] * (1.0 + ((lifter / 2.0) * Math.sin(Math::PI * (index + 1) / lifter)))
+      end
+      coeffs
     end
-    private_class_method :matrix_multiply
+    private_class_method :apply_lifter
   end
 end

data/lib/muze/feature/spectral.rb

@@ -10,8 +10,8 @@ module Muze
     # @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:)
+    def spectral_centroid(y: nil, s: nil, sr: 22_050, n_fft: 2048, hop_length: 512, center: true, pad_mode: :reflect, s_kind: :magnitude)
+      magnitude, frequencies = prepare_magnitude(y:, s:, sr:, n_fft:, hop_length:, center:, pad_mode:, s_kind:)
       _, frames = magnitude.shape
       output = Numo::SFloat.zeros(1, frames)
 
@@ -38,9 +38,11 @@ module Muze
     # @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:)
+    def spectral_bandwidth(y: nil, s: nil, sr: 22_050, n_fft: 2048, hop_length: 512, p: 2, center: true, pad_mode: :reflect, s_kind: :magnitude)
+      raise Muze::ParameterError, "p must be positive" unless p.positive?
+
+      magnitude, frequencies = prepare_magnitude(y:, s:, sr:, n_fft:, hop_length:, center:, pad_mode:, s_kind:)
+      centroids = spectral_centroid(y:, s: magnitude, sr:, n_fft:, hop_length:, center:, pad_mode:, s_kind: :magnitude)
       _, frames = magnitude.shape
       output = Numo::SFloat.zeros(1, frames)
 
@@ -71,8 +73,10 @@ module Muze
     # @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:)
+    def spectral_rolloff(y: nil, s: nil, sr: 22_050, n_fft: 2048, hop_length: 512, roll_percent: 0.85, center: true, pad_mode: :reflect, s_kind: :magnitude)
+      raise Muze::ParameterError, "roll_percent must satisfy 0 < roll_percent < 1" unless roll_percent.positive? && roll_percent < 1.0
+
+      magnitude, frequencies = prepare_magnitude(y:, s:, sr:, n_fft:, hop_length:, center:, pad_mode:, s_kind:)
       _, frames = magnitude.shape
       output = Numo::SFloat.zeros(1, frames)
 
@@ -100,8 +104,10 @@ module Muze
     # @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:)
+    def spectral_flatness(y: nil, s: nil, n_fft: 2048, hop_length: 512, amin: 1.0e-10, center: true, pad_mode: :reflect, s_kind: :magnitude)
+      raise Muze::ParameterError, "amin must be positive" unless amin.positive?
+
+      magnitude, = prepare_magnitude(y:, s:, sr: 22_050, n_fft:, hop_length:, center:, pad_mode:, s_kind:)
       _, frames = magnitude.shape
       output = Numo::SFloat.zeros(1, frames)
 
@@ -120,10 +126,14 @@ module Muze
     # @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:)
+    def spectral_contrast(y: nil, s: nil, sr: 22_050, n_fft: 2048, hop_length: 512, n_bands: 6, quantile: 0.02, fmin: 200.0, center: true, pad_mode: :reflect, s_kind: :magnitude)
+      raise Muze::ParameterError, "n_bands must be positive" unless n_bands.positive?
+      raise Muze::ParameterError, "quantile must satisfy 0 < quantile < 0.5" unless quantile.positive? && quantile < 0.5
+      raise Muze::ParameterError, "fmin must be positive" unless fmin.positive?
+
+      magnitude, frequencies = prepare_magnitude(y:, s:, sr:, n_fft:, hop_length:, center:, pad_mode:, s_kind:)
       bins, frames = magnitude.shape
-      edges = Array.new(n_bands + 2) { |idx| ((bins - 1) * idx / (n_bands + 1).to_f).round }
+      edges = spectral_contrast_edges(frequencies, n_bands:, fmin:, sr:)
       output = Numo::SFloat.zeros(n_bands + 1, frames)
 
       (n_bands + 1).times do |band|
@@ -145,20 +155,139 @@ module Muze
       output
     end
 
+    # @return [Array<Integer>]
+    def spectral_contrast_edges(frequencies, n_bands:, fmin:, sr:)
+      nyquist = sr / 2.0
+      hz_edges = [0.0, fmin]
+      n_bands.times { |band| hz_edges << [fmin * (2.0**(band + 1)), nyquist].min }
+      hz_edges << nyquist
+      hz_edges.map do |hz|
+        index = frequencies.each_index.min_by { |idx| (frequencies[idx] - hz).abs }
+        [[index, 0].max, frequencies.length - 1].min
+      end.each_cons(2).with_object([0]) do |(left, right), edges|
+        edges << [right, left + 1].max
+      end
+    end
+
+    # @return [Numo::SFloat] shape: [1, frames]
+    def spectral_flux(y: nil, s: nil, sr: 22_050, n_fft: 2048, hop_length: 512, center: true, pad_mode: :reflect, s_kind: :magnitude)
+      magnitude, = prepare_magnitude(y:, s:, sr:, n_fft:, hop_length:, center:, pad_mode:, s_kind:)
+      _, frames = magnitude.shape
+      output = Numo::SFloat.zeros(1, frames)
+
+      (1...frames).each do |frame_index|
+        diff = magnitude[true, frame_index] - magnitude[true, frame_index - 1]
+        output[0, frame_index] = Math.sqrt((diff * diff).sum)
+      end
+      output
+    end
+
+    # @return [Numo::SFloat] shape: [1, frames]
+    def spectral_entropy(y: nil, s: nil, sr: 22_050, n_fft: 2048, hop_length: 512, center: true, pad_mode: :reflect, s_kind: :magnitude)
+      magnitude, = prepare_magnitude(y:, s:, sr:, n_fft:, hop_length:, center:, pad_mode:, s_kind:)
+      _, frames = magnitude.shape
+      output = Numo::SFloat.zeros(1, frames)
+
+      frames.times do |frame_index|
+        spectrum = magnitude[true, frame_index]
+        total = spectrum.sum
+        next if total <= 0.0
+
+        probs = spectrum / total
+        entropy = probs.to_a.sum { |value| value.positive? ? -(value * Math.log2(value)) : 0.0 }
+        output[0, frame_index] = entropy / Math.log2([spectrum.size, 2].max)
+      end
+      output
+    end
+
+    # @return [Numo::SFloat] shape: [1, frames]
+    def spectral_crest(y: nil, s: nil, sr: 22_050, n_fft: 2048, hop_length: 512, center: true, pad_mode: :reflect, s_kind: :magnitude)
+      magnitude, = prepare_magnitude(y:, s:, sr:, n_fft:, hop_length:, center:, pad_mode:, s_kind:)
+      _, frames = magnitude.shape
+      output = Numo::SFloat.zeros(1, frames)
+
+      frames.times do |frame_index|
+        spectrum = magnitude[true, frame_index]
+        mean = spectrum.mean
+        output[0, frame_index] = mean <= 0.0 ? 0.0 : spectrum.max / mean
+      end
+      output
+    end
+
+    # @return [Numo::SFloat] shape: [1, frames]
+    def spectral_slope(y: nil, s: nil, sr: 22_050, n_fft: 2048, hop_length: 512, center: true, pad_mode: :reflect, s_kind: :magnitude)
+      magnitude, frequencies = prepare_magnitude(y:, s:, sr:, n_fft:, hop_length:, center:, pad_mode:, s_kind:)
+      mean_frequency = frequencies.sum / frequencies.length.to_f
+      frequency_variance = frequencies.sum { |frequency| (frequency - mean_frequency)**2 }
+      _, frames = magnitude.shape
+      output = Numo::SFloat.zeros(1, frames)
+
+      frames.times do |frame_index|
+        spectrum = magnitude[true, frame_index].to_a
+        mean_spectrum = spectrum.sum / spectrum.length.to_f
+        covariance = frequencies.each_with_index.sum { |frequency, idx| (frequency - mean_frequency) * (spectrum[idx] - mean_spectrum) }
+        output[0, frame_index] = frequency_variance.zero? ? 0.0 : covariance / frequency_variance
+      end
+      output
+    end
+
+    # @return [Numo::SFloat] shape: [1, frames]
+    def spectral_decrease(y: nil, s: nil, sr: 22_050, n_fft: 2048, hop_length: 512, center: true, pad_mode: :reflect, s_kind: :magnitude)
+      magnitude, = prepare_magnitude(y:, s:, sr:, n_fft:, hop_length:, center:, pad_mode:, s_kind:)
+      bins, frames = magnitude.shape
+      output = Numo::SFloat.zeros(1, frames)
+
+      frames.times do |frame_index|
+        first = magnitude[0, frame_index]
+        denominator = 0.0
+        numerator = 0.0
+        (1...bins).each do |bin|
+          value = magnitude[bin, frame_index]
+          numerator += (value - first) / bin
+          denominator += value
+        end
+        output[0, frame_index] = denominator <= 0.0 ? 0.0 : numerator / denominator
+      end
+      output
+    end
+
+    # @return [Numo::SFloat] shape: [order + 1, frames]
+    def poly_features(y: nil, s: nil, sr: 22_050, n_fft: 2048, hop_length: 512, order: 1, frequency: nil, center: true, pad_mode: :reflect, s_kind: :magnitude)
+      raise Muze::ParameterError, "order must be >= 0" unless order.is_a?(Integer) && order >= 0
+
+      magnitude, frequencies = prepare_magnitude(y:, s:, sr:, n_fft:, hop_length:, center:, pad_mode:, s_kind:)
+      bins, frames = magnitude.shape
+      x_values = frequency ? Numo::SFloat.cast(frequency).to_a.flatten : frequencies
+      raise Muze::ParameterError, "frequency length must match spectrum bins" unless x_values.length == bins
+
+      x_values = normalize_frequency_axis(x_values)
+      output = Numo::SFloat.zeros(order + 1, frames)
+      frames.times do |frame_index|
+        coefficients = polynomial_coefficients(x_values, magnitude[true, frame_index].to_a, order)
+        coefficients.each_with_index { |value, index| output[index, frame_index] = value }
+      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)
+    def zero_crossing_rate(y, frame_length: 2048, hop_length: 512, threshold: 0.0, center: false)
+      raise Muze::ParameterError, "threshold must be >= 0" if threshold.negative?
+
+      signal = mono_signal_to_a(y, "y")
+      signal = Array.new(frame_length / 2, 0.0) + signal + Array.new(frame_length / 2, 0.0) if center
+      frames = Muze::Core::Frames.slice(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) }
+        signs = frame.map { |value| value.abs <= threshold ? 0.0 : value }
+        (1...signs.length).each { |idx| crossings += 1 if (signs[idx - 1] >= 0) != (signs[idx] >= 0) }
         crossings.to_f / frame_length
       end
 
-      Numo::SFloat[values]
+      Numo::SFloat[values].reshape(1, values.length)
     end
 
     # @param y [Numo::SFloat, Array<Float>, nil]
@@ -166,9 +295,10 @@ module Muze
     # @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)
+    def rms(y: nil, s: nil, frame_length: 2048, hop_length: 512, center: false)
       if s
         matrix = Numo::SFloat.cast(s)
+        validate_finite_array!(matrix.to_a.flatten, "s")
         matrix = matrix.expand_dims(1) if matrix.ndim == 1
         _, frames = matrix.shape
         values = Array.new(frames) do |frame_index|
@@ -176,16 +306,17 @@ module Muze
           Math.sqrt((frame**2).sum / frame.size)
         end
 
-        return Numo::SFloat[values]
+        return Numo::SFloat[values].reshape(1, values.length)
       end
 
-      signal = y.is_a?(Numo::NArray) ? y.to_a : Array(y)
-      frames = frame_signal(signal, frame_length, hop_length)
+      signal = mono_signal_to_a(y, "y")
+      signal = Array.new(frame_length / 2, 0.0) + signal + Array.new(frame_length / 2, 0.0) if center
+      frames = Muze::Core::Frames.slice(signal, frame_length:, hop_length:)
       values = frames.map do |frame|
         Math.sqrt(frame.sum { |value| value * value } / frame.length)
       end
 
-      Numo::SFloat[values]
+      Numo::SFloat[values].reshape(1, values.length)
     end
 
     # @param y [Numo::SFloat, Array<Float>, nil]
@@ -194,12 +325,18 @@ module Muze
     # @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)
+    def tempogram(y: nil, onset_envelope: nil, sr: 22_050, hop_length: 512, win_length: 384, normalize: false)
+      raise Muze::ParameterError, "sr must be a positive integer" unless sr.is_a?(Integer) && sr.positive?
+      raise Muze::ParameterError, "hop_length must be a positive integer" unless hop_length.is_a?(Integer) && hop_length.positive?
+      raise Muze::ParameterError, "win_length must be a positive integer" unless win_length.is_a?(Integer) && win_length.positive?
+      raise Muze::ParameterError, "normalize must be true or false" unless [true, false].include?(normalize)
+
       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
+      validate_finite_array!(envelope, "onset_envelope")
 
       frames = envelope.length
       tempogram = Numo::SFloat.zeros(win_length, frames)
@@ -214,41 +351,41 @@ module Muze
           (lag...segment.length).each do |offset|
             value += segment[offset] * segment[offset - lag]
           end
-          tempogram[lag, frame_index] = value
+          tempogram[lag, frame_index] = normalize ? normalized_autocorrelation(segment, lag, value) : value
         end
       end
 
       tempogram
     end
 
-    def prepare_magnitude(y:, s:, sr:, n_fft:, hop_length:)
+    def prepare_magnitude(y:, s:, sr:, n_fft:, hop_length:, center: true, pad_mode: :reflect, s_kind: :magnitude)
+      raise Muze::ParameterError, "s_kind must be :magnitude or :power" unless %i[magnitude power].include?(s_kind)
+
       spectrum = if s
-                   Numo::SFloat.cast(s)
+                   provided = Numo::SFloat.cast(s)
+                   validate_finite_array!(provided.to_a.flatten, "s")
+                   if s_kind == :power
+                     raise Muze::ParameterError, "power spectrogram must be non-negative" if provided.to_a.flatten.any?(&:negative?)
+
+                     Numo::NMath.sqrt(provided).cast_to(Numo::SFloat)
+                   else
+                     provided
+                   end
                  else
-                   stft_matrix = Muze.stft(y, n_fft:, hop_length:)
+                   stft_matrix = Muze.stft(y, n_fft:, hop_length:, center:, pad_mode:)
                    magnitude, = Muze.magphase(stft_matrix)
                    magnitude
                  end
 
       spectrum = spectrum.expand_dims(1) if spectrum.ndim == 1
+      validate_finite_array!(spectrum.to_a.flatten, "spectrum")
       bins, = spectrum.shape
       fft_size = n_fft || ((bins - 1) * 2)
-      frequencies = Array.new(bins) { |index| index * sr.to_f / fft_size }
+      frequencies = Muze.fft_frequencies(sr:, n_fft: fft_size).to_a[0...bins]
       [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
@@ -262,5 +399,87 @@ module Muze
       onset
     end
     private_class_method :onset_env_from_signal
+
+    def normalized_autocorrelation(segment, lag, value)
+      left_energy = 0.0
+      right_energy = 0.0
+      (lag...segment.length).each do |offset|
+        left = segment[offset]
+        right = segment[offset - lag]
+        left_energy += left * left
+        right_energy += right * right
+      end
+      denominator = Math.sqrt(left_energy * right_energy)
+      denominator <= 1.0e-12 ? 0.0 : value / denominator
+    end
+    private_class_method :normalized_autocorrelation
+
+    def normalize_frequency_axis(values)
+      min = values.min
+      max = values.max
+      return Array.new(values.length, 0.0) if (max - min).abs <= 1.0e-12
+
+      values.map { |value| (2.0 * (value - min) / (max - min)) - 1.0 }
+    end
+    private_class_method :normalize_frequency_axis
+
+    def polynomial_coefficients(x_values, y_values, order)
+      size = order + 1
+      normal = Array.new(size) { Array.new(size, 0.0) }
+      rhs = Array.new(size, 0.0)
+
+      x_values.each_with_index do |x_value, index|
+        powers = Array.new((2 * order) + 1, 1.0)
+        (1...powers.length).each { |power| powers[power] = powers[power - 1] * x_value }
+        size.times do |row|
+          rhs[row] += y_values[index] * powers[row]
+          size.times { |col| normal[row][col] += powers[row + col] }
+        end
+      end
+
+      solve_linear_system(normal, rhs)
+    end
+    private_class_method :polynomial_coefficients
+
+    def solve_linear_system(matrix, rhs)
+      size = rhs.length
+      size.times do |pivot|
+        best = (pivot...size).max_by { |row| matrix[row][pivot].abs }
+        return Array.new(size, 0.0) if matrix[best][pivot].abs <= 1.0e-12
+
+        matrix[pivot], matrix[best] = matrix[best], matrix[pivot]
+        rhs[pivot], rhs[best] = rhs[best], rhs[pivot]
+
+        divisor = matrix[pivot][pivot]
+        pivot.upto(size - 1) { |col| matrix[pivot][col] /= divisor }
+        rhs[pivot] /= divisor
+
+        size.times do |row|
+          next if row == pivot
+
+          factor = matrix[row][pivot]
+          pivot.upto(size - 1) { |col| matrix[row][col] -= factor * matrix[pivot][col] }
+          rhs[row] -= factor * rhs[pivot]
+        end
+      end
+
+      rhs
+    end
+    private_class_method :solve_linear_system
+
+    def validate_finite_array!(values, label)
+      return if values.all? { |value| value.respond_to?(:finite?) && value.finite? }
+
+      raise Muze::ParameterError, "#{label} must contain only finite numeric values"
+    end
+    private_class_method :validate_finite_array!
+
+    def mono_signal_to_a(value, label)
+      signal = Muze::Core::Audio.validate_audio!(value, allow_empty: true)
+      raise Muze::ParameterError, "#{label} must be mono audio" if signal.ndim == 2
+
+      signal.to_a
+    end
+    private_class_method :mono_signal_to_a
   end
 end

data/lib/muze/filters/chroma_filter.rb

@@ -3,19 +3,29 @@
 module Muze
   module Filters
     module_function
+    CHROMA_CACHE = Muze::Core::BoundedCache.new(max_size: 64)
 
     # @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)
+    def chroma(sr:, n_fft:, n_chroma: 12, tuning: 0.0, ctroct: nil, octwidth: nil)
+      key = [sr, n_fft, n_chroma, tuning, ctroct, octwidth]
+      CHROMA_CACHE.fetch(key) { build_chroma(sr:, n_fft:, n_chroma:, tuning:, ctroct:, octwidth:) }.dup
+    end
+
+    def build_chroma(sr:, n_fft:, n_chroma:, tuning:, ctroct:, octwidth:)
       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?
+      raise Muze::ParameterError, "tuning must be finite" unless tuning.respond_to?(:finite?) && tuning.finite?
+      raise Muze::ParameterError, "ctroct must be finite" if ctroct && !(ctroct.respond_to?(:finite?) && ctroct.finite?)
+      raise Muze::ParameterError, "octwidth must be positive" if octwidth && !(octwidth.respond_to?(:positive?) && octwidth.positive?)
 
       bins = (n_fft / 2) + 1
       matrix = Numo::SFloat.zeros(n_chroma, bins)
+      center_octave = ctroct || 5.0
 
       bins.times do |bin|
         frequency = (bin * sr.to_f) / n_fft
@@ -26,12 +36,13 @@ module Muze
 
         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)
+          matrix[chroma_index, bin] = Math.exp(-(distance**2) / 2.0) * octave_weight(frequency, center_octave:, octwidth:)
         end
       end
 
       normalize_columns(matrix)
     end
+    private_class_method :build_chroma
 
     def circular_distance(a, b, modulo)
       direct = (a - b).abs
@@ -39,6 +50,14 @@ module Muze
     end
     private_class_method :circular_distance
 
+    def octave_weight(frequency, center_octave:, octwidth:)
+      return 1.0 unless octwidth
+
+      octave = Math.log2(frequency / 16.351597831287414)
+      Math.exp(-0.5 * (((octave - center_octave) / octwidth)**2))
+    end
+    private_class_method :octave_weight
+
     def normalize_columns(matrix)
       cols = matrix.shape[1]
       cols.times do |col|