muze 0.1.0 → 1.0.0

data/lib/muze/effects/time_stretch.rb

@@ -4,24 +4,35 @@ module Muze
   module Effects
     module_function
 
-    # Keep fast path for short clips where phase vocoder overhead dominates.
+    # Use smaller FFTs for short clips so phase vocoding remains practical.
     MIN_PHASE_VOCODER_SAMPLES = 32_768
+    MIN_TIME_STRETCH_RATE = 1.0 / 32.0
+    MAX_TIME_STRETCH_RATE = 32.0
 
     # @param y [Numo::SFloat, Array<Float>]
     # @param rate [Float]
     # @return [Numo::SFloat]
-    def time_stretch(y, rate: 1.0)
-      raise Muze::ParameterError, "rate must be positive" unless rate.positive?
+    def time_stretch(y, rate: 1.0, n_fft: nil, hop_length: nil, method: :phase_vocoder, phase_lock: false, force_phase_vocoder: false)
+      validate_positive_number!(rate, "rate")
+      unless rate.between?(MIN_TIME_STRETCH_RATE, MAX_TIME_STRETCH_RATE)
+        raise Muze::ParameterError, "rate must be between #{MIN_TIME_STRETCH_RATE} and #{MAX_TIME_STRETCH_RATE}"
+      end
+      validate_optional_positive_integer!(n_fft, "n_fft")
+      validate_optional_positive_integer!(hop_length, "hop_length")
+      raise Muze::ParameterError, "method must be :phase_vocoder, :ola, :wsola, or :linear" unless %i[phase_vocoder ola wsola linear].include?(method)
 
-      signal = y.is_a?(Numo::NArray) ? Numo::SFloat.cast(y) : Numo::SFloat.cast(Array(y))
+      signal = Muze::Core::Audio.validate_audio!(y, allow_empty: true)
+      return apply_channels(signal) { |channel| time_stretch(channel, rate:, n_fft:, hop_length:, method:, phase_lock:, force_phase_vocoder:) } if signal.ndim == 2
       return signal if signal.empty? || rate == 1.0
-      return linear_time_stretch(signal.to_a, rate) if signal.size < MIN_PHASE_VOCODER_SAMPLES
+      return linear_time_stretch(signal.to_a, rate) if method == :linear
+      return ola_time_stretch(signal.to_a, rate) if method == :ola
+      return wsola_time_stretch(signal.to_a, rate) if method == :wsola
 
-      n_fft = phase_vocoder_fft_size(signal.size)
-      hop_length = [n_fft / 4, 1].max
+      n_fft ||= phase_vocoder_fft_size(signal.size)
+      hop_length ||= [n_fft / 4, 1].max
 
       stft_matrix = Muze::Core::STFT.stft(signal, n_fft:, hop_length:, center: true)
-      stretched_stft = phase_vocoder(stft_matrix, rate:, hop_length:, n_fft:)
+      stretched_stft = phase_vocoder(stft_matrix, rate:, hop_length:, n_fft:, phase_lock:)
       target_length = [(signal.size / rate).round, 1].max
 
       Muze::Core::STFT.istft(stretched_stft, hop_length:, center: true, length: target_length)
@@ -31,16 +42,25 @@ module Muze
     # @param sr [Integer]
     # @param n_steps [Float]
     # @return [Numo::SFloat]
-    def pitch_shift(y, sr: 22_050, n_steps: 0)
-      _ = sr
-      signal = y.is_a?(Numo::NArray) ? y : Numo::SFloat.cast(y)
+    def pitch_shift(y, sr: 22_050, n_steps: 0, bins_per_octave: 12, res_type: :auto, normalize: false, clip: nil)
+      validate_positive_integer!(sr, "sr")
+      validate_positive_number!(bins_per_octave, "bins_per_octave")
+      raise Muze::ParameterError, "n_steps must be finite" unless n_steps.respond_to?(:finite?) && n_steps.finite?
+      raise Muze::ParameterError, "normalize must be true or false" unless [true, false].include?(normalize)
+      validate_positive_number!(clip, "clip") if clip
+
+      signal = Muze::Core::Audio.validate_audio!(y, allow_empty: true)
+      return apply_channels(signal) { |channel| pitch_shift(channel, sr:, n_steps:, bins_per_octave:, res_type:, normalize:, clip:) } if signal.ndim == 2
       return signal if n_steps.zero?
 
-      rate = 2.0**(-n_steps.to_f / 12.0)
+      rate = 2.0**(-n_steps.to_f / bins_per_octave)
       stretched = time_stretch(signal, rate:)
-      preferred_res_type = signal.size >= MIN_PHASE_VOCODER_SAMPLES ? :sinc : :linear
-      restored = resample_for_pitch_shift(stretched, target_size: signal.size, preferred_res_type:)
-      Numo::SFloat.cast(restored[0...signal.size])
+      effective_res_type = res_type == :auto ? (signal.size >= MIN_PHASE_VOCODER_SAMPLES ? :sinc : :linear) : res_type
+      restored = resample_for_pitch_shift(stretched, target_size: signal.size, sr:, rate:, res_type: effective_res_type)
+      output = Numo::SFloat.cast(restored[0...signal.size])
+      output = normalize_peak(output) if normalize
+      output = output.clip(-clip, clip) if clip
+      output
     end
 
     # @param y [Numo::SFloat, Array<Float>]
@@ -48,23 +68,70 @@ module Muze
     # @param frame_length [Integer]
     # @param hop_length [Integer]
     # @return [Array(Numo::SFloat, Array<Integer>)] trimmed signal and [start, end]
-    def trim(y, top_db: 60, frame_length: 2048, hop_length: 512)
-      _ = [frame_length, hop_length]
-      signal = y.is_a?(Numo::NArray) ? y : Numo::SFloat.cast(y)
-      abs_signal = signal.abs
-      threshold = [abs_signal.max, 1.0e-12].max * (10.0**(-top_db / 20.0))
-      indices = abs_signal.to_a.each_index.select { |index| abs_signal[index] >= threshold }
-      return [Numo::SFloat[], [0, 0]] if indices.empty?
+    def trim(y, top_db: 60, frame_length: 2048, hop_length: 512, ref: :max, aggregate: :mean, units: :samples, sr: nil)
+      raise Muze::ParameterError, "top_db must be non-negative" if top_db.negative?
+      raise Muze::ParameterError, "frame_length and hop_length must be positive" unless frame_length.positive? && hop_length.positive?
+      raise Muze::ParameterError, "aggregate must be :mean or :max" unless %i[mean max].include?(aggregate)
+      validate_trim_units!(units:, sr:, hop_length:)
+
+      signal = Muze::Core::Audio.validate_audio!(y, allow_empty: true)
+      amplitude = sample_amplitude(signal, aggregate:)
+      frames = Muze::Core::Frames.slice(amplitude, frame_length:, hop_length:, pad_end: true)
+      energies = frames.map do |frame|
+        values = frame.map { |value| value * value }
+        aggregate == :max ? Math.sqrt(values.max || 0.0) : Math.sqrt(values.sum(0.0) / frame.length)
+      end
+      reference = trim_reference(energies, ref:)
+      threshold = [reference, 1.0e-12].max * (10.0**(-top_db / 20.0))
+      active_frames = energies.each_index.select { |index| energies[index] >= threshold }
+      return [Numo::SFloat[], [0, 0]] if active_frames.empty?
+
+      search_start = active_frames.first * hop_length
+      sample_count = amplitude.length
+      search_end = [(active_frames.last * hop_length) + frame_length, sample_count].min
+      active_samples = (search_start...search_end).select { |index| amplitude[index] >= threshold }
+      empty = signal.ndim == 2 ? Numo::SFloat.zeros(0, signal.shape[1]) : Numo::SFloat[]
+      return [empty, [0, 0]] if active_samples.empty?
+
+      start_sample = active_samples.first
+      end_sample = active_samples.last + 1
+      trimmed = signal.ndim == 2 ? signal[start_sample...end_sample, true] : signal[start_sample...end_sample]
+      [trimmed, convert_trim_interval(start_sample, end_sample, units:, sr:, hop_length:)]
+    end
+
+    def preemphasis(y, coef: 0.97)
+      validate_finite_number!(coef, "coef")
+      matrix = Muze::Core::Audio.validate_audio!(y, allow_empty: true)
+      return apply_channels(matrix) { |channel| preemphasis(channel, coef:) } if matrix.ndim == 2
+
+      signal = matrix.to_a
+      return Numo::SFloat.cast(signal) if signal.empty?
 
-      start_sample = indices.first
-      end_sample = indices.last + 1
-      [signal[start_sample...end_sample], [start_sample, end_sample]]
+      output = Array.new(signal.length, 0.0)
+      output[0] = signal[0]
+      (1...signal.length).each { |index| output[index] = signal[index] - (coef * signal[index - 1]) }
+      Numo::SFloat.cast(output)
+    end
+
+    def deemphasis(y, coef: 0.97)
+      validate_finite_number!(coef, "coef")
+      matrix = Muze::Core::Audio.validate_audio!(y, allow_empty: true)
+      return apply_channels(matrix) { |channel| deemphasis(channel, coef:) } if matrix.ndim == 2
+
+      signal = matrix.to_a
+      return Numo::SFloat.cast(signal) if signal.empty?
+
+      output = Array.new(signal.length, 0.0)
+      output[0] = signal[0]
+      (1...signal.length).each { |index| output[index] = signal[index] + (coef * output[index - 1]) }
+      Numo::SFloat.cast(output)
     end
 
     # @param signal_length [Integer]
     # @return [Integer]
     def phase_vocoder_fft_size(signal_length)
-      max_fft = [signal_length, 2048].min
+      max_allowed = signal_length < MIN_PHASE_VOCODER_SAMPLES ? 512 : 2048
+      max_fft = [signal_length, max_allowed].min
       fft_size = 1
       fft_size *= 2 while (fft_size * 2) <= max_fft
       [fft_size, 32].max
@@ -76,7 +143,7 @@ module Muze
     # @param hop_length [Integer]
     # @param n_fft [Integer]
     # @return [Numo::DComplex]
-    def phase_vocoder(stft_matrix, rate:, hop_length:, n_fft:)
+    def phase_vocoder(stft_matrix, rate:, hop_length:, n_fft:, phase_lock: false)
       frequency_bins, frame_count = stft_matrix.shape
       return stft_matrix if frame_count <= 1
 
@@ -115,10 +182,32 @@ module Muze
         end
       end
 
-      stretched
+      phase_lock ? phase_lock_spectrum(stretched) : stretched
     end
     private_class_method :phase_vocoder
 
+    def phase_lock_spectrum(stft_matrix)
+      rows, cols = stft_matrix.shape
+      output = stft_matrix.dup
+      cols.times do |col|
+        peak_bins = local_peak_bins(stft_matrix[true, col])
+        next if peak_bins.empty?
+
+        rows.times do |row|
+          peak = peak_bins.min_by { |candidate| (candidate - row).abs }
+          output[row, col] = Complex.polar(stft_matrix[row, col].abs, phase_of(stft_matrix[peak, col]))
+        end
+      end
+      output
+    end
+    private_class_method :phase_lock_spectrum
+
+    def local_peak_bins(spectrum)
+      values = spectrum.abs.to_a
+      (1...(values.length - 1)).select { |index| values[index] >= values[index - 1] && values[index] >= values[index + 1] }
+    end
+    private_class_method :local_peak_bins
+
     # @param complex_number [Complex]
     # @return [Float]
     def phase_of(complex_number)
@@ -152,20 +241,248 @@ module Muze
     end
     private_class_method :linear_time_stretch
 
+    def ola_time_stretch(signal, rate)
+      frame_length = [[next_power_of_two([signal.length / 8, 256].max), 2048].min, 32].max
+      analysis_hop = [frame_length / 2, 1].max
+      synthesis_hop = [(analysis_hop / rate).round, 1].max
+      frame_count = signal.length <= frame_length ? 1 : (((signal.length - frame_length).to_f / analysis_hop).ceil + 1)
+      target_length = [(signal.length / rate).round, 1].max
+      output = Array.new(target_length + frame_length, 0.0)
+      window_sums = Array.new(output.length, 0.0)
+      window = Muze::Core::Windows.hann(frame_length).to_a
+
+      frame_count.times do |frame_index|
+        source_start = frame_index * analysis_hop
+        target_start = frame_index * synthesis_hop
+        frame_length.times do |offset|
+          source_index = source_start + offset
+          target_index = target_start + offset
+          break if target_index >= output.length
+
+          value = source_index < signal.length ? signal[source_index] : 0.0
+          weight = window[offset]
+          output[target_index] += value * weight
+          window_sums[target_index] += weight * weight
+        end
+      end
+
+      output.map!.with_index do |value, index|
+        denominator = window_sums[index]
+        denominator > 1.0e-3 ? value / denominator : 0.0
+      end
+      Numo::SFloat.cast(limit_peak(output[0, target_length], signal.map(&:abs).max.to_f))
+    end
+    private_class_method :ola_time_stretch
+
+    def wsola_time_stretch(signal, rate)
+      frame_length = [[next_power_of_two([signal.length / 8, 256].max), 2048].min, 32].max
+      analysis_hop = [frame_length / 2, 1].max
+      synthesis_hop = [(analysis_hop / rate).round, 1].max
+      target_length = [(signal.length / rate).round, 1].max
+      output = Array.new(target_length + frame_length, 0.0)
+      window_sums = Array.new(output.length, 0.0)
+      window = Muze::Core::Windows.hann(frame_length).to_a
+      overlap = [[frame_length - synthesis_hop, 0].max, frame_length / 2].min
+      search_radius = [[analysis_hop / 2, 8].max, frame_length].min
+
+      target_start = 0
+      source_start = 0
+      first_frame = true
+
+      while target_start < target_length
+        expected_source = (target_start * rate).round
+        source_start = if first_frame || overlap.zero?
+                         [[expected_source, 0].max, signal.length - 1].min
+                       else
+                         best_wsola_source_start(signal, output, target_start, expected_source, frame_length, overlap, search_radius)
+                       end
+
+        overlap_add_frame(signal, output, window_sums, window, source_start:, target_start:, frame_length:)
+        first_frame = false
+        target_start += synthesis_hop
+      end
+
+      output.map!.with_index do |value, index|
+        denominator = window_sums[index]
+        denominator > 1.0e-3 ? value / denominator : 0.0
+      end
+      Numo::SFloat.cast(limit_peak(output[0, target_length], signal.map(&:abs).max.to_f))
+    end
+    private_class_method :wsola_time_stretch
+
+    def best_wsola_source_start(signal, output, target_start, expected_source, frame_length, overlap, search_radius)
+      lower = [expected_source - search_radius, 0].max
+      upper = [expected_source + search_radius, [signal.length - 1, 0].max].min
+      best_start = lower
+      best_score = -Float::INFINITY
+
+      (lower..upper).each do |candidate|
+        score = overlap_correlation(signal, output, candidate, target_start, overlap)
+        next unless score > best_score
+
+        best_score = score
+        best_start = candidate
+      end
+
+      [best_start, [signal.length - frame_length, 0].max].min
+    end
+    private_class_method :best_wsola_source_start
+
+    def overlap_correlation(signal, output, source_start, target_start, overlap)
+      numerator = 0.0
+      source_energy = 0.0
+      output_energy = 0.0
+
+      overlap.times do |offset|
+        source_index = source_start + offset
+        target_index = target_start + offset
+        break if source_index >= signal.length || target_index >= output.length
+
+        source_value = signal[source_index]
+        output_value = output[target_index]
+        numerator += source_value * output_value
+        source_energy += source_value * source_value
+        output_energy += output_value * output_value
+      end
+
+      denominator = Math.sqrt(source_energy * output_energy)
+      denominator <= 1.0e-12 ? 0.0 : numerator / denominator
+    end
+    private_class_method :overlap_correlation
+
+    def overlap_add_frame(signal, output, window_sums, window, source_start:, target_start:, frame_length:)
+      frame_length.times do |offset|
+        source_index = source_start + offset
+        target_index = target_start + offset
+        break if target_index >= output.length
+
+        value = source_index < signal.length ? signal[source_index] : 0.0
+        weight = window[offset]
+        output[target_index] += value * weight
+        window_sums[target_index] += weight * weight
+      end
+    end
+    private_class_method :overlap_add_frame
+
+    def limit_peak(values, target_peak)
+      peak = values.map(&:abs).max.to_f
+      return values if target_peak <= 0.0 || peak <= target_peak
+
+      scale = target_peak / peak
+      values.map { |value| value * scale }
+    end
+    private_class_method :limit_peak
+
+    def next_power_of_two(value)
+      power = 1
+      power *= 2 while power < value
+      power
+    end
+    private_class_method :next_power_of_two
+
     # Prefer sinc-quality resampling, then fall back to linear on failure.
     # @param stretched [Numo::SFloat]
     # @param target_size [Integer]
-    # @param preferred_res_type [Symbol]
+    # @param sr [Integer]
+    # @param rate [Float]
+    # @param res_type [Symbol]
     # @return [Numo::SFloat]
-    def resample_for_pitch_shift(stretched, target_size:, preferred_res_type:)
-      if preferred_res_type == :sinc
-        return Muze::Core::Resample.resample(stretched, orig_sr: stretched.size, target_sr: target_size, res_type: :sinc)
+    def resample_for_pitch_shift(stretched, target_size:, sr:, rate:, res_type:)
+      target_sr = [(sr * rate).round, 1].max
+      Muze::Core::Resample.resample(stretched, orig_sr: sr, target_sr:, res_type:, target_length: target_size)
+    rescue Muze::ParameterError
+      Muze::Core::Resample.resample(stretched, orig_sr: stretched.size, target_sr: target_size, res_type: :linear, target_length: target_size)
+    end
+    private_class_method :resample_for_pitch_shift
+
+    def trim_reference(energies, ref:)
+      case ref
+      when :max then energies.max || 0.0
+      when Numeric then ref.to_f
+      when Proc then ref.call(energies)
+      else
+        raise Muze::ParameterError, "ref must be :max, numeric, or a Proc"
       end
+    end
+    private_class_method :trim_reference
 
-      Muze::Core::Resample.resample(stretched, orig_sr: stretched.size, target_sr: target_size, res_type: :linear)
-    rescue Muze::Error, StandardError
-      Muze::Core::Resample.resample(stretched, orig_sr: stretched.size, target_sr: target_size, res_type: :linear)
+    def validate_trim_units!(units:, sr:, hop_length:)
+      raise Muze::ParameterError, "units must be :samples, :frames, or :time" unless %i[samples frames time].include?(units)
+      raise Muze::ParameterError, "sr must be positive for time units" if units == :time && !(sr.is_a?(Integer) && sr.positive?)
+      raise Muze::ParameterError, "hop_length must be positive for frame units" if units == :frames && !(hop_length.is_a?(Integer) && hop_length.positive?)
     end
-    private_class_method :resample_for_pitch_shift
+    private_class_method :validate_trim_units!
+
+    def convert_trim_interval(start_sample, end_sample, units:, sr:, hop_length:)
+      case units
+      when :samples
+        [start_sample, end_sample]
+      when :frames
+        [start_sample, end_sample].map { |sample| (sample / hop_length.to_f).floor }
+      when :time
+        [start_sample, end_sample].map { |sample| sample.to_f / sr }
+      end
+    end
+    private_class_method :convert_trim_interval
+
+    def apply_channels(matrix)
+      frames, channels = matrix.shape
+      processed = channels.times.map { |channel| yield(matrix[true, channel]) }
+      output_length = processed.map(&:size).max || frames
+      output = Numo::SFloat.zeros(output_length, channels)
+      channels.times do |channel|
+        values = processed[channel]
+        output[0...values.size, channel] = values
+      end
+      output
+    end
+    private_class_method :apply_channels
+
+    def sample_amplitude(signal, aggregate:)
+      return signal.abs.to_a unless signal.ndim == 2
+
+      frames, channels = signal.shape
+      Array.new(frames) do |frame|
+        values = Array.new(channels) { |channel| signal[frame, channel].abs }
+        aggregate == :max ? values.max : values.sum(0.0) / channels
+      end
+    end
+    private_class_method :sample_amplitude
+
+    def normalize_peak(signal)
+      peak = signal.abs.max
+      return signal if peak <= 0.0
+
+      signal / peak
+    end
+    private_class_method :normalize_peak
+
+    def validate_positive_integer!(value, label)
+      return if value.is_a?(Integer) && value.positive?
+
+      raise Muze::ParameterError, "#{label} must be a positive integer"
+    end
+    private_class_method :validate_positive_integer!
+
+    def validate_optional_positive_integer!(value, label)
+      return if value.nil?
+
+      validate_positive_integer!(value, label)
+    end
+    private_class_method :validate_optional_positive_integer!
+
+    def validate_positive_number!(value, label)
+      return if value.respond_to?(:finite?) && value.finite? && value.positive?
+
+      raise Muze::ParameterError, "#{label} must be positive"
+    end
+    private_class_method :validate_positive_number!
+
+    def validate_finite_number!(value, label)
+      return if value.respond_to?(:finite?) && value.finite?
+
+      raise Muze::ParameterError, "#{label} must be finite"
+    end
+    private_class_method :validate_finite_number!
   end
 end

data/lib/muze/feature/aggregation.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Muze
+  module Feature
+    module_function
+
+    # Beat-synchronous aggregation over the frame axis.
+    def beat_sync(data, beats:, aggregate: :mean)
+      raise Muze::ParameterError, "aggregate must be :mean, :median, or :max" unless %i[mean median max].include?(aggregate)
+
+      matrix = Numo::SFloat.cast(data)
+      matrix = matrix.expand_dims(0) if matrix.ndim == 1
+      raise Muze::ParameterError, "data must be one- or two-dimensional" unless [1, 2].include?(matrix.ndim)
+
+      rows, frames = matrix.shape
+      boundaries = beat_boundaries(beats, frames)
+      output = Numo::SFloat.zeros(rows, boundaries.length - 1)
+
+      boundaries.each_cons(2).with_index do |(left, right), segment_index|
+        rows.times do |row|
+          values = matrix[row, left...right].to_a
+          output[row, segment_index] = aggregate_values(values, aggregate:)
+        end
+      end
+
+      output
+    end
+
+    def beat_boundaries(beats, frames)
+      points = Array(beats).map(&:to_i).select { |beat| beat.between?(0, frames) }
+      ([0] + points + [frames]).uniq.sort
+    end
+    private_class_method :beat_boundaries
+
+    def aggregate_values(values, aggregate:)
+      return 0.0 if values.empty?
+
+      case aggregate
+      when :mean
+        values.sum(0.0) / values.length
+      when :median
+        Muze::Native.median1d(values)
+      when :max
+        values.max
+      end
+    end
+    private_class_method :aggregate_values
+  end
+end

data/lib/muze/feature/chroma.rb

@@ -11,42 +11,59 @@ module Muze
     # @param n_fft [Integer]
     # @param hop_length [Integer]
     # @param norm [Integer, nil]
+    # @param tuning [Float]
     # @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)
+    def chroma_stft(y: nil, sr: 22_050, s: nil, n_chroma: 12, n_fft: 2048, hop_length: 512, norm: 2, tuning: 0.0, ctroct: nil, octwidth: nil)
       spectrum = if s
-                   Numo::SFloat.cast(s)
+                   provided = Numo::SFloat.cast(s)
+                   validate_spectrum!(provided)
+                   provided
                  else
                    stft_matrix = Muze.stft(y, n_fft:, hop_length:)
                    magnitude, = Muze.magphase(stft_matrix)
                    magnitude
-                 end
+      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)
+      filter_bank = Muze::Filters.chroma(sr:, n_fft:, n_chroma:, tuning:, ctroct:, octwidth:)
+      chroma = Muze::Core::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
+    # @return [Numo::SFloat] shape: [6, frames]
+    def tonnetz(y: nil, chroma: nil, sr: 22_050, n_fft: 2048, hop_length: 512)
+      chroma_matrix = chroma ? Numo::SFloat.cast(chroma) : chroma_stft(y:, sr:, n_fft:, hop_length:)
+      chroma_matrix = chroma_matrix.expand_dims(1) if chroma_matrix.ndim == 1
+      validate_spectrum!(chroma_matrix)
+      raise Muze::ParameterError, "tonnetz requires 12-bin chroma" unless chroma_matrix.shape[0] == 12
+
+      frames = chroma_matrix.shape[1]
+      output = Numo::SFloat.zeros(6, frames)
+      intervals = [7, 7, 3, 3, 4, 4]
+      phases = [0.0, Math::PI / 2.0, 0.0, Math::PI / 2.0, 0.0, Math::PI / 2.0]
 
-      output = Numo::SFloat.zeros(left_rows, right_cols)
-      left_rows.times do |row|
-        right_cols.times do |col|
+      frames.times do |frame|
+        vector = chroma_matrix[true, frame]
+        total = vector.sum
+        next if total <= 0.0
+
+        normalized = vector / total
+        6.times do |dimension|
           sum = 0.0
-          left_cols.times { |idx| sum += left[row, idx] * right[idx, col] }
-          output[row, col] = sum
+          12.times do |chroma_index|
+            angle = ((Math::PI * intervals[dimension] * chroma_index) / 6.0) + phases[dimension]
+            sum += normalized[chroma_index] * Math.cos(angle)
+          end
+          output[dimension, frame] = sum
         end
       end
 
       output
     end
-    private_class_method :matrix_multiply
 
     def normalize(chroma, norm:)
       return chroma if norm.nil?
+      raise Muze::ParameterError, "norm must be nil, 1, or 2" unless [1, 2].include?(norm)
 
       frames = chroma.shape[1]
       frames.times do |frame_index|
@@ -64,5 +81,16 @@ module Muze
       chroma
     end
     private_class_method :normalize
+
+    def validate_spectrum!(spectrum)
+      values = spectrum.to_a.flatten
+      unless values.all? { |value| value.respond_to?(:finite?) && value.finite? }
+        raise Muze::ParameterError, "s must contain only finite numeric values"
+      end
+      return unless values.any?(&:negative?)
+
+      raise Muze::ParameterError, "spectrogram input must be non-negative"
+    end
+    private_class_method :validate_spectrum!
   end
 end

data/lib/muze/feature/context.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Muze
+  module Feature
+    # Lightweight cache for feature extractors that share the same STFT.
+    class Context
+      DEFAULT_FEATURES = %i[
+        melspectrogram
+        chroma_stft
+        spectral_centroid
+        spectral_bandwidth
+        spectral_rolloff
+        spectral_flatness
+        rms
+        zero_crossing_rate
+      ].freeze
+
+      attr_reader :y, :sr, :n_fft, :hop_length, :center, :pad_mode
+
+      def initialize(y:, sr: 22_050, n_fft: 2048, hop_length: 512, center: true, pad_mode: :reflect)
+        @y = y
+        @sr = sr
+        @n_fft = n_fft
+        @hop_length = hop_length
+        @center = center
+        @pad_mode = pad_mode
+        @cache = {}
+      end
+
+      def stft
+        @cache[:stft] ||= Muze.stft(y, n_fft:, hop_length:, center:, pad_mode:)
+      end
+
+      def magnitude
+        @cache[:magnitude] ||= Muze.magphase(stft).first
+      end
+
+      def power
+        @cache[:power] ||= (magnitude**2).cast_to(Numo::SFloat)
+      end
+
+      def extract(features: DEFAULT_FEATURES)
+        features.each_with_object({}) do |feature, results|
+          results[feature] = fetch(feature)
+        end
+      end
+
+      def fetch(feature)
+        @cache[feature] ||= case feature
+                            when :melspectrogram then Muze::Feature.melspectrogram(sr:, s: power, n_fft:, hop_length:)
+                            when :chroma_stft then Muze::Feature.chroma_stft(sr:, s: magnitude, n_fft:, hop_length:)
+                            when :spectral_centroid then Muze::Feature.spectral_centroid(s: magnitude, sr:, n_fft:, hop_length:)
+                            when :spectral_bandwidth then Muze::Feature.spectral_bandwidth(s: magnitude, sr:, n_fft:, hop_length:)
+                            when :spectral_rolloff then Muze::Feature.spectral_rolloff(s: magnitude, sr:, n_fft:, hop_length:)
+                            when :spectral_flatness then Muze::Feature.spectral_flatness(s: magnitude, n_fft:, hop_length:)
+                            when :spectral_flux then Muze::Feature.spectral_flux(s: magnitude, sr:, n_fft:, hop_length:)
+                            when :spectral_entropy then Muze::Feature.spectral_entropy(s: magnitude, sr:, n_fft:, hop_length:)
+                            when :spectral_crest then Muze::Feature.spectral_crest(s: magnitude, sr:, n_fft:, hop_length:)
+                            when :spectral_slope then Muze::Feature.spectral_slope(s: magnitude, sr:, n_fft:, hop_length:)
+                            when :spectral_decrease then Muze::Feature.spectral_decrease(s: magnitude, sr:, n_fft:, hop_length:)
+                            when :poly_features then Muze::Feature.poly_features(s: magnitude, sr:, n_fft:, hop_length:)
+                            when :tonnetz then Muze::Feature.tonnetz(chroma: fetch(:chroma_stft), sr:, n_fft:, hop_length:)
+                            when :rms then Muze::Feature.rms(s: magnitude)
+                            when :zero_crossing_rate then Muze::Feature.zero_crossing_rate(y, frame_length: n_fft, hop_length:)
+                            else
+                              raise Muze::ParameterError, "Unsupported feature: #{feature}"
+                            end
+      end
+    end
+
+    module_function
+
+    def context(y:, sr: 22_050, n_fft: 2048, hop_length: 512, center: true, pad_mode: :reflect)
+      Context.new(y:, sr:, n_fft:, hop_length:, center:, pad_mode:)
+    end
+
+    def extract(y:, sr: 22_050, features: Context::DEFAULT_FEATURES, n_fft: 2048, hop_length: 512, center: true, pad_mode: :reflect)
+      context(y:, sr:, n_fft:, hop_length:, center:, pad_mode:).extract(features:)
+    end
+  end
+end