muze 0.1.0

data/examples/feature_report.rb

@@ -0,0 +1,37 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Usage: bundle exec ruby examples/feature_report.rb path/to/audio.wav
+
+require_relative "../lib/muze"
+
+input_path = ARGV[0]
+abort("Usage: bundle exec ruby examples/feature_report.rb path/to/audio.wav") unless input_path
+
+target_sr = 22_050
+n_fft = 1024
+hop_length = 256
+n_mfcc = 13
+n_mels = 40
+
+y, sr = Muze.load(input_path, sr: target_sr, mono: true)
+mfcc = Muze.mfcc(y:, sr:, n_mfcc:, n_fft:, hop_length:, n_mels:)
+delta = Muze.delta(mfcc, order: 1, width: 9)
+centroid = Muze.spectral_centroid(y:, sr:, n_fft:, hop_length:)
+bandwidth = Muze.spectral_bandwidth(y:, sr:, n_fft:, hop_length:)
+rolloff = Muze.spectral_rolloff(y:, sr:, n_fft:, hop_length:)
+flatness = Muze.spectral_flatness(y:, n_fft:, hop_length:)
+zcr = Muze.zero_crossing_rate(y, frame_length: n_fft, hop_length:)
+rms = Muze.rms(y:, frame_length: n_fft, hop_length:)
+
+puts "Input: #{input_path}"
+puts "Sample rate: #{sr} Hz"
+puts format("Duration: %.2f s", y.size.to_f / sr)
+puts "MFCC shape: #{mfcc.shape.join(' x ')}"
+puts "Delta shape: #{delta.shape.join(' x ')}"
+puts format("Mean spectral centroid: %.2f Hz", centroid.mean.to_f)
+puts format("Mean spectral bandwidth: %.2f Hz", bandwidth.mean.to_f)
+puts format("Mean spectral rolloff: %.2f Hz", rolloff.mean.to_f)
+puts format("Mean spectral flatness: %.4f", flatness.mean.to_f)
+puts format("Mean zero-crossing rate: %.4f", zcr.mean.to_f)
+puts format("Mean RMS: %.4f", rms.mean.to_f)

data/examples/hpss_demo.rb

@@ -0,0 +1,46 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Usage: bundle exec ruby examples/hpss_demo.rb path/to/audio.wav [output_prefix]
+
+require "fileutils"
+require_relative "../lib/muze"
+
+def render_mel(signal, sr:, hop_length:, output_path:)
+  mel = Muze.melspectrogram(y: signal, sr:, n_fft: 2048, hop_length:, n_mels: 128)
+  Muze.specshow(Muze.power_to_db(mel), sr:, hop_length:, y_axis: :mel, output: output_path)
+end
+
+input_path = ARGV[0]
+abort("Usage: bundle exec ruby examples/hpss_demo.rb path/to/audio.wav [output_prefix]") unless input_path
+
+sample_name = File.basename(input_path, ".*")
+output_prefix = ARGV[1] || File.expand_path("output/#{sample_name}", __dir__)
+FileUtils.mkdir_p(File.dirname(output_prefix))
+
+target_sr = 22_050
+hop_length = 512
+
+y, sr = Muze.load(input_path, sr: target_sr, mono: true)
+harmonic, percussive = Muze.hpss(y, kernel_size: 31, n_fft: 2048, hop_length:)
+
+harmonic_wave_path = "#{output_prefix}_harmonic_wave.svg"
+percussive_wave_path = "#{output_prefix}_percussive_wave.svg"
+harmonic_mel_path = "#{output_prefix}_harmonic_mel.svg"
+percussive_mel_path = "#{output_prefix}_percussive_mel.svg"
+
+Muze.waveshow(harmonic, sr:, output: harmonic_wave_path)
+Muze.waveshow(percussive, sr:, output: percussive_wave_path)
+render_mel(harmonic, sr:, hop_length:, output_path: harmonic_mel_path)
+render_mel(percussive, sr:, hop_length:, output_path: percussive_mel_path)
+
+harmonic_rms = Muze.rms(y: harmonic, frame_length: 2048, hop_length:).mean.to_f
+percussive_rms = Muze.rms(y: percussive, frame_length: 2048, hop_length:).mean.to_f
+
+puts "Input: #{input_path}"
+puts format("Harmonic RMS: %.4f", harmonic_rms)
+puts format("Percussive RMS: %.4f", percussive_rms)
+puts "Wrote: #{harmonic_wave_path}"
+puts "Wrote: #{percussive_wave_path}"
+puts "Wrote: #{harmonic_mel_path}"
+puts "Wrote: #{percussive_mel_path}"

data/examples/load_and_specshow.rb

@@ -0,0 +1,30 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Usage: bundle exec ruby examples/load_and_specshow.rb path/to/audio.wav [output.svg]
+
+require "fileutils"
+require_relative "../lib/muze"
+
+input_path = ARGV[0]
+abort("Usage: bundle exec ruby examples/load_and_specshow.rb path/to/audio.wav [output.svg]") unless input_path
+
+sample_name = File.basename(input_path, ".*")
+output_path = ARGV[1] || File.expand_path("output/#{sample_name}_mel_spectrogram.svg", __dir__)
+FileUtils.mkdir_p(File.dirname(output_path))
+
+target_sr = 22_050
+hop_length = 512
+n_fft = 2048
+n_mels = 128
+
+y, sr = Muze.load(input_path, sr: target_sr, mono: true)
+mel = Muze.melspectrogram(y:, sr:, n_fft:, hop_length:, n_mels:)
+mel_db = Muze.power_to_db(mel)
+Muze.specshow(mel_db, sr:, hop_length:, y_axis: :mel, output: output_path)
+
+puts "Input: #{input_path}"
+puts "Sample rate: #{sr} Hz"
+puts format("Duration: %.2f s", y.size.to_f / sr)
+puts "Mel shape: #{mel.shape.join(' x ')}"
+puts "Wrote: #{output_path}"

data/ext/muze/extconf.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require "mkmf"
+
+extension_name = "muze/muze_ext"
+create_makefile(extension_name)

data/ext/muze/muze_ext.c

@@ -0,0 +1,75 @@
+#include "ruby.h"
+
+static VALUE mMuze;
+static VALUE mNative;
+
+static VALUE native_frame_slices(VALUE self, VALUE rb_signal, VALUE rb_frame_length, VALUE rb_hop_length) {
+  Check_Type(rb_signal, T_ARRAY);
+  const long signal_length = RARRAY_LEN(rb_signal);
+  const long frame_length = NUM2LONG(rb_frame_length);
+  const long hop_length = NUM2LONG(rb_hop_length);
+
+  if (frame_length <= 0 || hop_length <= 0) {
+    rb_raise(rb_eArgError, "frame_length and hop_length must be positive");
+  }
+
+  if (signal_length <= frame_length) {
+    VALUE frame = rb_ary_new2(frame_length);
+    for (long i = 0; i < frame_length; i++) {
+      VALUE sample = i < signal_length ? rb_ary_entry(rb_signal, i) : DBL2NUM(0.0);
+      rb_ary_push(frame, sample);
+    }
+    VALUE single = rb_ary_new();
+    rb_ary_push(single, frame);
+    return single;
+  }
+
+  const long frame_count = ((signal_length - frame_length) / hop_length) + 1;
+  VALUE frames = rb_ary_new2(frame_count);
+
+  for (long frame_idx = 0; frame_idx < frame_count; frame_idx++) {
+    long start = frame_idx * hop_length;
+    VALUE frame = rb_ary_new2(frame_length);
+
+    for (long i = 0; i < frame_length; i++) {
+      rb_ary_push(frame, rb_ary_entry(rb_signal, start + i));
+    }
+
+    rb_ary_push(frames, frame);
+  }
+
+  return frames;
+}
+
+static int cmp_double(const void *a, const void *b) {
+  const double left = *(const double *)a;
+  const double right = *(const double *)b;
+  if (left < right) return -1;
+  if (left > right) return 1;
+  return 0;
+}
+
+static VALUE native_median1d(VALUE self, VALUE rb_values) {
+  Check_Type(rb_values, T_ARRAY);
+  const long count = RARRAY_LEN(rb_values);
+  if (count == 0) return DBL2NUM(0.0);
+
+  double *values = ALLOC_N(double, count);
+
+  for (long i = 0; i < count; i++) {
+    values[i] = NUM2DBL(rb_ary_entry(rb_values, i));
+  }
+
+  qsort(values, count, sizeof(double), cmp_double);
+  const double median = values[count / 2];
+  xfree(values);
+  return DBL2NUM(median);
+}
+
+void Init_muze_ext(void) {
+  mMuze = rb_define_module("Muze");
+  mNative = rb_define_module_under(mMuze, "Native");
+
+  rb_define_singleton_method(mNative, "frame_slices", native_frame_slices, 3);
+  rb_define_singleton_method(mNative, "median1d", native_median1d, 1);
+}

data/lib/muze/beat/beat_track.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Muze
+  # Beat tracking functions.
+  module Beat
+    module_function
+
+    # @param y [Numo::SFloat, Array<Float>, nil]
+    # @param sr [Integer]
+    # @param onset_envelope [Numo::SFloat, Array<Float>, nil]
+    # @param hop_length [Integer]
+    # @param start_bpm [Float]
+    # @param tightness [Integer]
+    # @return [Array(Float, Array<Integer>)] estimated tempo and beat frames
+    def beat_track(y: nil, sr: 22_050, onset_envelope: nil, hop_length: 512, start_bpm: 120.0, tightness: 100)
+      envelope = if onset_envelope
+                   onset_envelope.is_a?(Numo::NArray) ? onset_envelope.to_a : Array(onset_envelope)
+                 else
+                   Muze::Onset.onset_strength(y:, sr:, hop_length:).to_a
+                 end
+
+      tempo = estimate_tempo(envelope, sr:, hop_length:, start_bpm:)
+      beats = track_beats(envelope, tempo:, sr:, hop_length:, tightness:)
+      [tempo, beats]
+    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)
+      Muze::Feature.tempogram(y:, onset_envelope:, sr:, hop_length:, win_length:)
+    end
+
+    def estimate_tempo(envelope, sr:, hop_length:, start_bpm:)
+      return start_bpm if envelope.length < 4
+
+      min_bpm = 30.0
+      max_bpm = 240.0
+      min_lag = [(sr * 60.0 / (hop_length * max_bpm)).round, 1].max
+      max_lag = [(sr * 60.0 / (hop_length * min_bpm)).round, envelope.length - 1].min
+      return start_bpm if min_lag >= max_lag
+
+      best_lag = min_lag
+      best_score = -Float::INFINITY
+
+      (min_lag..max_lag).each do |lag|
+        score = 0.0
+        (lag...envelope.length).each { |index| score += envelope[index] * envelope[index - lag] }
+        next unless score > best_score
+
+        best_score = score
+        best_lag = lag
+      end
+
+      60.0 * sr / (hop_length * best_lag)
+    end
+    private_class_method :estimate_tempo
+
+    def track_beats(envelope, tempo:, sr:, hop_length:, tightness:)
+      interval = [(60.0 * sr / (tempo * hop_length)).round, 1].max
+      peaks = Muze::Onset.onset_detect(onset_envelope: envelope, backtrack: false)
+      return [] if peaks.empty?
+
+      beats = [peaks.first]
+      target = peaks.first + interval
+
+      while target < envelope.length
+        candidates = peaks.select { |peak| (peak - target).abs <= search_radius(interval, tightness) }
+        beats << select_beat_candidate(candidates, target:, interval:, envelope:, tightness:)
+        target += interval
+      end
+
+      beats.uniq
+    end
+    private_class_method :track_beats
+
+    def search_radius(interval, tightness)
+      normalized = normalized_tightness(tightness)
+      radius_scale = 1.0 - (0.4 * normalized)
+      [(interval * radius_scale).round, 1].max
+    end
+    private_class_method :search_radius
+
+    def select_beat_candidate(candidates, target:, interval:, envelope:, tightness:)
+      return target unless candidates.any?
+
+      penalty_weight = 1.0 + (4.0 * normalized_tightness(tightness))
+      candidates.max_by do |candidate|
+        strength = envelope[candidate] || 0.0
+        normalized_distance = (candidate - target).abs / interval.to_f
+        strength - (penalty_weight * normalized_distance)
+      end
+    end
+    private_class_method :select_beat_candidate
+
+    def normalized_tightness(tightness)
+      value = tightness.to_f
+      return 0.0 if value <= 0.0
+
+      [value / 100.0, 4.0].min / 4.0
+    end
+    private_class_method :normalized_tightness
+  end
+end

data/lib/muze/core/dct.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Muze
+  module Core
+    # DCT utilities.
+    module DCT
+      module_function
+
+      # @param x [Numo::NArray]
+      # @param type [Integer]
+      # @param n [Integer, nil]
+      # @param axis [Integer]
+      # @param norm [Symbol, nil]
+      # @return [Numo::SFloat]
+      def dct(x, type: 2, n: nil, axis: 0, norm: :ortho)
+        raise Muze::ParameterError, "only DCT type 2 is supported" unless type == 2
+        raise Muze::ParameterError, "axis must be 0 or 1" unless [0, 1].include?(axis)
+
+        matrix = Numo::SFloat.cast(x)
+        matrix = matrix.expand_dims(1) if matrix.ndim == 1
+        matrix = matrix.transpose if axis == 1
+
+        rows, cols = matrix.shape
+        target_length = n || rows
+        result = Numo::SFloat.zeros(target_length, cols)
+
+        cols.times do |col|
+          signal = matrix[true, col].to_a
+          transformed = dct_vector(signal, target_length, norm:)
+          target_length.times { |idx| result[idx, col] = transformed[idx] }
+        end
+
+        axis == 1 ? result.transpose : result
+      end
+
+      def dct_vector(signal, n, norm:)
+        padded = if signal.length >= n
+                   signal[0, n]
+                 else
+                   signal + Array.new(n - signal.length, 0.0)
+                 end
+
+        Array.new(n) do |k|
+          sum = 0.0
+          n.times do |idx|
+            sum += padded[idx] * Math.cos(Math::PI * (idx + 0.5) * k / n)
+          end
+
+          normalize_dct(sum, k, n, norm)
+        end
+      end
+      private_class_method :dct_vector
+
+      def normalize_dct(value, index, length, norm)
+        return value * 2.0 unless norm == :ortho
+
+        scale = index.zero? ? Math.sqrt(1.0 / length) : Math.sqrt(2.0 / length)
+        value * scale
+      end
+      private_class_method :normalize_dct
+    end
+  end
+end

data/lib/muze/core/resample.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Muze
+  module Core
+    # Resampling utilities.
+    module Resample
+      EPSILON = 1.0e-12
+      module_function
+
+      # @param y [Numo::SFloat, Array<Float>] waveform signal
+      # @param orig_sr [Integer] source sampling rate
+      # @param target_sr [Integer] destination sampling rate
+      # @param res_type [Symbol] :linear or :sinc
+      # @return [Numo::SFloat] resampled waveform
+      def resample(y, orig_sr:, target_sr:, res_type: :sinc)
+        validate_sample_rates!(orig_sr, target_sr)
+        signal = y.is_a?(Numo::NArray) ? y.to_a : Array(y)
+        return Numo::SFloat.cast(signal) if signal.empty? || orig_sr == target_sr
+
+        case res_type
+        when :linear then linear_resample(signal, orig_sr, target_sr)
+        when :sinc then sinc_resample(signal, orig_sr, target_sr)
+        else
+          raise Muze::ParameterError, "Unsupported res_type: #{res_type}"
+        end
+      end
+
+      def validate_sample_rates!(orig_sr, target_sr)
+        return if orig_sr.is_a?(Integer) && target_sr.is_a?(Integer) && orig_sr.positive? && target_sr.positive?
+
+        raise Muze::ParameterError, "orig_sr and target_sr must be positive integers"
+      end
+      private_class_method :validate_sample_rates!
+
+      def linear_resample(signal, orig_sr, target_sr)
+        source_length = signal.length
+        return Numo::SFloat.cast(signal) if source_length <= 1
+
+        target_length = [(source_length * target_sr.to_f / orig_sr).round, 1].max
+        return Numo::SFloat.cast(signal[0, target_length]) if target_length <= 1
+
+        scale = (source_length - 1).to_f / (target_length - 1)
+        output = Array.new(target_length, 0.0)
+
+        target_length.times do |index|
+          source_position = index * scale
+          left = source_position.floor
+          right = [left + 1, source_length - 1].min
+          alpha = source_position - left
+          output[index] = ((1.0 - alpha) * signal[left]) + (alpha * signal[right])
+        end
+
+        Numo::SFloat.cast(output)
+      end
+      private_class_method :linear_resample
+
+      def sinc_resample(signal, orig_sr, target_sr)
+        ratio = target_sr.to_f / orig_sr
+        target_length = [(signal.length * ratio).round, 1].max
+        taps = 16
+        beta = 8.6
+        cutoff = [ratio, 1.0].min
+
+        i0_beta = bessel_i0(beta)
+        output = Array.new(target_length, 0.0)
+
+        target_length.times do |index|
+          source_position = index / ratio
+          left = source_position.floor - taps + 1
+          right = source_position.floor + taps
+
+          sum = 0.0
+          weight_sum = 0.0
+
+          (left..right).each do |sample_index|
+            next if sample_index.negative? || sample_index >= signal.length
+
+            distance = source_position - sample_index
+            normalized = distance / taps.to_f
+            next if normalized.abs > 1.0
+
+            window = bessel_i0(beta * Math.sqrt(1.0 - (normalized * normalized))) / i0_beta
+            weight = cutoff * sinc(cutoff * distance) * window
+            sum += signal[sample_index] * weight
+            weight_sum += weight
+          end
+
+          output[index] = weight_sum.abs > EPSILON ? (sum / weight_sum) : 0.0
+        end
+
+        Numo::SFloat.cast(output)
+      end
+      private_class_method :sinc_resample
+
+      def sinc(value)
+        return 1.0 if value.abs < EPSILON
+
+        x = Math::PI * value
+        Math.sin(x) / x
+      end
+      private_class_method :sinc
+
+      # Approximation of modified Bessel function I0.
+      def bessel_i0(value)
+        sum = 1.0
+        term = 1.0
+        k = 1
+
+        loop do
+          term *= ((value / 2.0)**2) / (k * k)
+          sum += term
+          break if term < 1.0e-12
+
+          k += 1
+        end
+
+        sum
+      end
+      private_class_method :bessel_i0
+    end
+  end
+end