muze 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 852274e098d5ea8d512680e8dbcf9962b8e380ce778c51912d5efa77cf5d4427
-  data.tar.gz: 4e49c534ea90ca6d01c1a3e37ca88e975db1a404a59b37288f8397642b71a7a5
+  metadata.gz: 01b14e94bc84cd5ca2437c37404f0344a084af15f185465687776997c135442a
+  data.tar.gz: '09d93556256984b96e283bcd3be6bd5c6d404130056f6822b9bf42757a43c394'
 SHA512:
-  metadata.gz: 874a8d2467e25523dd91361a41b299b7c8e9dfec8bd22def1f382795026ce28b7aa086f19eb8ffc7616c25f90e60471c909c2a777c3f4bc8fced6ba1fbf8c65a
-  data.tar.gz: c4d63ca9bd4a35ff74e34eec358a03e3c3c5dd15dd03589debbb00c97c02d1719849ca883149afd984f76065bed8377678af88e2297832eaddab43d8dad3b970
+  metadata.gz: 451d64a3392a7baa148808ccee159a03c2d20234b0bc39db5bdf92535f399467fed6eb8360498148a925c652f0d43afb6e05cc070aa7548a2e71373490e727cb
+  data.tar.gz: 2743e731b94df7d830f4deb497099d211828ad41d85436a5afcb4e25864bec32865040db402763fa10a413004c574a5c5b7a942cc7f54091bb5c0dd6ce8ced4b

data/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to this project are documented in this file.
 
+## [1.0.0] - 2026-05-25
+
+### Added
+
+- Added broader audio I/O: WAV writing, source-rate preserving loads, `Pathname` and WAV `IO` inputs, stereo output, configurable downmixing, file metadata via `Muze.info`, and chunked reads via `Muze.load_stream`.
+- Added streamed and long-file-friendly DSP APIs including `Muze.stft_stream`, `Muze.time_stretch_stream`, `Muze.pitch_shift_stream`, and `Muze.hpss_stream`.
+- Added more STFT and conversion controls: explicit pad modes, trailing frame padding, periodic windows, custom windows, non-power-of-two even FFT lengths, frame/time/sample helpers, FFT frequencies, and configurable dB conversion.
+- Added richer feature extraction: Slaney mel filters, mel frequencies, chroma tuning and octave weighting, MFCC liftering and input modes, delta edge modes, additional spectral descriptors, polynomial spectral features, tonnetz, beat-synchronous aggregation, and shared feature extraction via `Muze.feature_context` / `Muze.feature_stack`.
+- Added rhythm controls for onset strength, onset detection, tempo estimation, normalized tempograms, fixed-BPM beat tracking, tempo frequency helpers, and beat metadata output.
+- Added effects improvements: multi-channel processing, HPSS masks and margins, WSOLA/OLA time stretching, phase locking, pitch-shift controls, frame-energy trimming with interval units, and preemphasis/deemphasis.
+- Added lightweight visualization upgrades: `specshow` axes, dimensions, color maps, value bounds, fragment output, image rendering, waveform envelope rendering, stereo waveform layouts, and onset envelope rendering.
+
+### Changed
+
+- The optional native extension is now built during gem installation when supported, while retaining the pure Ruby fallback.
+- Audio loading now applies FFmpeg seek/duration controls before decoding and uses safer FFmpeg process handling.
+
 ## [0.1.0] - 2026-03-07
 
-- Initial release.
+- Initial release.

data/README.md

@@ -1,5 +1,10 @@
 # Muze
 
+[![Gem Version](https://img.shields.io/gem/v/muze.svg)](https://rubygems.org/gems/muze)
+[![CI](https://github.com/ydah/muze/actions/workflows/ci.yml/badge.svg)](https://github.com/ydah/muze/actions/workflows/ci.yml)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.1-red.svg)](https://www.ruby-lang.org/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE.txt)
+
 Muze is a Ruby audio feature extraction library that provides a full pipeline from audio loading to spectral analysis, feature extraction, rhythm analysis, effects, and lightweight visualization.
 
 ![Image](https://github.com/user-attachments/assets/1e88395b-c715-4c9a-b458-d1cb9fceb848)

data/Rakefile

@@ -7,6 +7,9 @@ require_relative "benchmarks/quality_metrics"
 
 RSpec::Core::RakeTask.new(:spec)
 
+CLEAN.include("ext/muze/*.o", "ext/muze/mkmf.log")
+CLOBBER.include("ext/muze/Makefile", "ext/muze/*.bundle", "ext/muze/*.dSYM")
+
 directory "ext/muze"
 
 desc "Compile optional C extension"

data/ext/muze/muze_ext.c

@@ -1,16 +1,30 @@
 #include "ruby.h"
+#include "ruby/thread.h"
+#include <string.h>
 
 static VALUE mMuze;
 static VALUE mNative;
 
+static VALUE muze_parameter_error(void) {
+  ID id = rb_intern("ParameterError");
+  if (rb_const_defined(mMuze, id)) {
+    return rb_const_get(mMuze, id);
+  }
+
+  return rb_eArgError;
+}
+
 static VALUE native_frame_slices(VALUE self, VALUE rb_signal, VALUE rb_frame_length, VALUE rb_hop_length) {
-  Check_Type(rb_signal, T_ARRAY);
+  if (!RB_TYPE_P(rb_signal, T_ARRAY)) {
+    rb_raise(muze_parameter_error(), "signal must be an 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");
+    rb_raise(muze_parameter_error(), "frame_length and hop_length must be positive");
   }
 
   if (signal_length <= frame_length) {
@@ -41,16 +55,66 @@ static VALUE native_frame_slices(VALUE self, VALUE rb_signal, VALUE rb_frame_len
   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 void swap_double(double *values, long left, long right) {
+  const double tmp = values[left];
+  values[left] = values[right];
+  values[right] = tmp;
+}
+
+static long partition_double(double *values, long left, long right, long pivot_index) {
+  const double pivot = values[pivot_index];
+  long store_index = left;
+
+  swap_double(values, pivot_index, right);
+
+  for (long i = left; i < right; i++) {
+    if (values[i] < pivot) {
+      swap_double(values, store_index, i);
+      store_index++;
+    }
+  }
+
+  swap_double(values, right, store_index);
+  return store_index;
+}
+
+static double quickselect_double(double *values, long count, long target) {
+  long left = 0;
+  long right = count - 1;
+
+  while (1) {
+    if (left == right) return values[left];
+
+    const long pivot_index = partition_double(values, left, right, left + ((right - left) / 2));
+
+    if (target == pivot_index) {
+      return values[target];
+    } else if (target < pivot_index) {
+      right = pivot_index - 1;
+    } else {
+      left = pivot_index + 1;
+    }
+  }
+}
+
+struct median_args {
+  double *values;
+  long count;
+  long target;
+  double result;
+};
+
+static void *median_without_gvl(void *ptr) {
+  struct median_args *args = (struct median_args *)ptr;
+  args->result = quickselect_double(args->values, args->count, args->target);
+  return NULL;
 }
 
 static VALUE native_median1d(VALUE self, VALUE rb_values) {
-  Check_Type(rb_values, T_ARRAY);
+  if (!RB_TYPE_P(rb_values, T_ARRAY)) {
+    rb_raise(muze_parameter_error(), "values must be an Array");
+  }
+
   const long count = RARRAY_LEN(rb_values);
   if (count == 0) return DBL2NUM(0.0);
 
@@ -60,10 +124,62 @@ static VALUE native_median1d(VALUE self, VALUE rb_values) {
     values[i] = NUM2DBL(rb_ary_entry(rb_values, i));
   }
 
-  qsort(values, count, sizeof(double), cmp_double);
-  const double median = values[count / 2];
+  struct median_args args = { values, count, count / 2, 0.0 };
+  rb_thread_call_without_gvl(median_without_gvl, &args, NULL, NULL);
   xfree(values);
-  return DBL2NUM(median);
+  return DBL2NUM(args.result);
+}
+
+static void insert_sorted_double(double *values, long *length, double value) {
+  long index = 0;
+  while (index < *length && values[index] <= value) index++;
+  memmove(values + index + 1, values + index, sizeof(double) * (*length - index));
+  values[index] = value;
+  (*length)++;
+}
+
+static void remove_sorted_double(double *values, long *length, double value) {
+  long index = 0;
+  while (index < *length && values[index] < value) index++;
+  while (index < *length && values[index] != value) index++;
+  if (index >= *length) return;
+
+  memmove(values + index, values + index + 1, sizeof(double) * (*length - index - 1));
+  (*length)--;
+}
+
+static VALUE native_median_filter1d(VALUE self, VALUE rb_values, VALUE rb_half) {
+  if (!RB_TYPE_P(rb_values, T_ARRAY)) {
+    rb_raise(muze_parameter_error(), "values must be an Array");
+  }
+
+  const long count = RARRAY_LEN(rb_values);
+  const long half = NUM2LONG(rb_half);
+  if (half < 0) {
+    rb_raise(muze_parameter_error(), "half must be non-negative");
+  }
+
+  VALUE output = rb_ary_new2(count);
+  if (count == 0) return output;
+
+  double *window = ALLOC_N(double, count);
+  long window_length = 0;
+
+  for (long index = 0; index < count; index++) {
+    if (index > half) {
+      remove_sorted_double(window, &window_length, NUM2DBL(rb_ary_entry(rb_values, index - half - 1)));
+    }
+
+    const long entering = index + half;
+    if (entering < count) {
+      insert_sorted_double(window, &window_length, NUM2DBL(rb_ary_entry(rb_values, entering)));
+    }
+
+    rb_ary_push(output, DBL2NUM(window_length == 0 ? 0.0 : window[window_length / 2]));
+  }
+
+  xfree(window);
+  return output;
 }
 
 void Init_muze_ext(void) {
@@ -72,4 +188,5 @@ void Init_muze_ext(void) {
 
   rb_define_singleton_method(mNative, "frame_slices", native_frame_slices, 3);
   rb_define_singleton_method(mNative, "median1d", native_median1d, 1);
+  rb_define_singleton_method(mNative, "median_filter1d", native_median_filter1d, 2);
 }

data/lib/muze/beat/beat_track.rb

@@ -12,15 +12,36 @@ module Muze
     # @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)
+    def beat_track(y: nil, sr: 22_050, onset_envelope: nil, hop_length: 512, start_bpm: 120.0, tightness: 100, min_bpm: 30.0, max_bpm: 240.0, bpm: nil, fill_missing: true, return_metadata: false)
+      validate_beat_params!(
+        sr:,
+        hop_length:,
+        start_bpm:,
+        tightness:,
+        min_bpm:,
+        max_bpm:,
+        bpm:,
+        fill_missing:,
+        return_metadata:
+      )
+
       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
+      validate_finite_array!(envelope, "onset_envelope")
+
+      if envelope.empty? || envelope.max.to_f <= 1.0e-12
+        result = { tempo: nil, beats: [], confidence: 0.0 }
+        return return_metadata ? result : [nil, []]
+      end
+
+      tempo = bpm || estimate_tempo(envelope, sr:, hop_length:, start_bpm:, min_bpm:, max_bpm:, tightness:)
+      beats = track_beats(envelope, tempo:, sr:, hop_length:, tightness:, fill_missing:)
+      confidence = beat_confidence(envelope, beats)
+      return { tempo:, beats:, confidence: } if return_metadata
 
-      tempo = estimate_tempo(envelope, sr:, hop_length:, start_bpm:)
-      beats = track_beats(envelope, tempo:, sr:, hop_length:, tightness:)
       [tempo, beats]
     end
 
@@ -30,25 +51,40 @@ 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)
-      Muze::Feature.tempogram(y:, onset_envelope:, sr:, hop_length:, win_length:)
+    def tempogram(y: nil, onset_envelope: nil, sr: 22_050, hop_length: 512, win_length: 384, normalize: false)
+      validate_positive_integer!(sr, "sr")
+      validate_positive_integer!(hop_length, "hop_length")
+      Muze::Feature.tempogram(y:, onset_envelope:, sr:, hop_length:, win_length:, normalize:)
+    end
+
+    def tempo_frequencies(sr: 22_050, hop_length: 512, win_length: 384)
+      validate_positive_integer!(sr, "sr")
+      validate_positive_integer!(hop_length, "hop_length")
+      raise Muze::ParameterError, "win_length must be positive" unless win_length.positive?
+
+      Numo::SFloat.cast(Array.new(win_length) do |lag|
+        lag.zero? ? 0.0 : 60.0 * sr / (hop_length * lag)
+      end)
     end
 
-    def estimate_tempo(envelope, sr:, hop_length:, start_bpm:)
+    def estimate_tempo(envelope, sr:, hop_length:, start_bpm:, min_bpm:, max_bpm:, tightness:)
       return start_bpm if envelope.length < 4
 
-      min_bpm = 30.0
-      max_bpm = 240.0
+      raise Muze::ParameterError, "min_bpm must be positive" unless min_bpm.positive?
+      raise Muze::ParameterError, "max_bpm must be greater than min_bpm" unless max_bpm > min_bpm
+
       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
 
+      prior_lag = sr * 60.0 / (hop_length * start_bpm)
       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] }
+        score -= normalized_tightness(tightness) * ((lag - prior_lag).abs / prior_lag) * score.abs
         next unless score > best_score
 
         best_score = score
@@ -59,7 +95,7 @@ module Muze
     end
     private_class_method :estimate_tempo
 
-    def track_beats(envelope, tempo:, sr:, hop_length:, tightness:)
+    def track_beats(envelope, tempo:, sr:, hop_length:, tightness:, fill_missing:)
       interval = [(60.0 * sr / (tempo * hop_length)).round, 1].max
       peaks = Muze::Onset.onset_detect(onset_envelope: envelope, backtrack: false)
       return [] if peaks.empty?
@@ -69,7 +105,8 @@ module Muze
 
       while target < envelope.length
         candidates = peaks.select { |peak| (peak - target).abs <= search_radius(interval, tightness) }
-        beats << select_beat_candidate(candidates, target:, interval:, envelope:, tightness:)
+        candidate = select_beat_candidate(candidates, target:, interval:, envelope:, tightness:)
+        beats << (candidate || target) if fill_missing || candidate
         target += interval
       end
 
@@ -85,7 +122,7 @@ module Muze
     private_class_method :search_radius
 
     def select_beat_candidate(candidates, target:, interval:, envelope:, tightness:)
-      return target unless candidates.any?
+      return nil unless candidates.any?
 
       penalty_weight = 1.0 + (4.0 * normalized_tightness(tightness))
       candidates.max_by do |candidate|
@@ -96,6 +133,16 @@ module Muze
     end
     private_class_method :select_beat_candidate
 
+    def beat_confidence(envelope, beats)
+      return 0.0 if beats.empty?
+
+      peak = envelope.max.to_f
+      return 0.0 if peak <= 0.0
+
+      beats.sum { |beat| envelope[beat].to_f } / (beats.length * peak)
+    end
+    private_class_method :beat_confidence
+
     def normalized_tightness(tightness)
       value = tightness.to_f
       return 0.0 if value <= 0.0
@@ -103,5 +150,40 @@ module Muze
       [value / 100.0, 4.0].min / 4.0
     end
     private_class_method :normalized_tightness
+
+    def validate_beat_params!(sr:, hop_length:, start_bpm:, tightness:, min_bpm:, max_bpm:, bpm:, fill_missing:, return_metadata:)
+      validate_positive_integer!(sr, "sr")
+      validate_positive_integer!(hop_length, "hop_length")
+      validate_positive_number!(start_bpm, "start_bpm")
+      raise Muze::ParameterError, "tightness must be finite" unless tightness.respond_to?(:finite?) && tightness.finite?
+      validate_positive_number!(min_bpm, "min_bpm")
+      validate_positive_number!(max_bpm, "max_bpm")
+      raise Muze::ParameterError, "max_bpm must be greater than min_bpm" unless max_bpm > min_bpm
+      validate_positive_number!(bpm, "bpm") if bpm
+      raise Muze::ParameterError, "fill_missing must be true or false" unless [true, false].include?(fill_missing)
+      raise Muze::ParameterError, "return_metadata must be true or false" unless [true, false].include?(return_metadata)
+    end
+    private_class_method :validate_beat_params!
+
+    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_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_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!
   end
 end

data/lib/muze/core/audio.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Muze
+  module Core
+    # Small audio-array helpers shared by public convenience APIs.
+    module Audio
+      module_function
+
+      def validate_audio!(y, allow_empty: false)
+        raise Muze::ParameterError, "audio must not be nil" if y.nil?
+
+        signal = Numo::SFloat.cast(y)
+        raise Muze::ParameterError, "audio must be one- or two-dimensional" unless [1, 2].include?(signal.ndim)
+        raise Muze::ParameterError, "audio must not be empty" if !allow_empty && signal.empty?
+        raise Muze::ParameterError, "audio must contain only finite numeric values" unless finite_values?(signal)
+        raise Muze::ParameterError, "audio channel count must be positive" if signal.ndim == 2 && signal.shape[1].zero?
+
+        signal
+      rescue NoMethodError, TypeError, ArgumentError => e
+        raise Muze::ParameterError, "audio must be Array<Float> or Numo::NArray: #{e.message}"
+      end
+
+      def valid_audio?(y, allow_empty: false)
+        validate_audio!(y, allow_empty:)
+        true
+      rescue Muze::ParameterError
+        false
+      end
+
+      def normalize(y, peak: 1.0, axis: nil)
+        raise Muze::ParameterError, "peak must be positive" unless peak.respond_to?(:positive?) && peak.positive?
+        raise Muze::ParameterError, "axis must be nil or :channels" unless axis.nil? || axis == :channels
+
+        signal = validate_audio!(y, allow_empty: true)
+        return signal if signal.empty?
+
+        return normalize_channels(signal, peak:) if axis == :channels && signal.ndim == 2
+
+        current_peak = signal.abs.max.to_f
+        return signal if current_peak <= 0.0
+
+        (signal * (peak.to_f / current_peak)).cast_to(Numo::SFloat)
+      end
+
+      def remix(y, intervals, units: :samples, sr: nil, hop_length: 512)
+        signal = validate_audio!(y, allow_empty: true)
+        raw_intervals = intervals.respond_to?(:to_a) ? intervals.to_a : Array(intervals)
+        raw_intervals = [raw_intervals] if raw_intervals.length == 2 && !raw_intervals.first.respond_to?(:to_a)
+
+        sample_ranges = raw_intervals.map do |interval|
+          raise Muze::ParameterError, "intervals must contain [start, end] pairs" unless interval.respond_to?(:to_a) && interval.to_a.length == 2
+
+          start_sample = convert_position(interval.to_a[0], units:, sr:, hop_length:)
+          end_sample = convert_position(interval.to_a[1], units:, sr:, hop_length:)
+          raise Muze::ParameterError, "interval end must be >= start" if end_sample < start_sample
+
+          [start_sample, end_sample]
+        end
+
+        chunks = sample_ranges.map { |start_sample, end_sample| slice_samples(signal, start_sample, end_sample) }
+        concatenate_chunks(chunks, channel_count: signal.ndim == 2 ? signal.shape[1] : nil)
+      end
+
+      def finite_values?(signal)
+        signal.to_a.flatten.all? { |value| value.respond_to?(:finite?) && value.finite? }
+      end
+      private_class_method :finite_values?
+
+      def normalize_channels(signal, peak:)
+        frames, channels = signal.shape
+        output = Numo::SFloat.zeros(frames, channels)
+        channels.times do |channel|
+          values = signal[true, channel]
+          current_peak = values.abs.max.to_f
+          output[true, channel] = current_peak <= 0.0 ? values : values * (peak.to_f / current_peak)
+        end
+        output
+      end
+      private_class_method :normalize_channels
+
+      def convert_position(position, units:, sr:, hop_length:)
+        case units
+        when :samples
+          position.to_i
+        when :frames
+          raise Muze::ParameterError, "hop_length must be positive" unless hop_length.positive?
+
+          (position.to_i * hop_length).to_i
+        when :time
+          raise Muze::ParameterError, "sr must be positive for time units" unless sr&.positive?
+
+          (position.to_f * sr).round
+        else
+          raise Muze::ParameterError, "units must be :samples, :frames, or :time"
+        end
+      end
+      private_class_method :convert_position
+
+      def slice_samples(signal, start_sample, end_sample)
+        start_index = [[start_sample, 0].max, signal.shape[0]].min
+        end_index = [[end_sample, 0].max, signal.shape[0]].min
+        return signal.ndim == 2 ? Numo::SFloat.zeros(0, signal.shape[1]) : Numo::SFloat[] if end_index <= start_index
+
+        signal.ndim == 2 ? signal[start_index...end_index, true] : signal[start_index...end_index]
+      end
+      private_class_method :slice_samples
+
+      def concatenate_chunks(chunks, channel_count:)
+        return channel_count ? Numo::SFloat.zeros(0, channel_count) : Numo::SFloat[] if chunks.empty?
+
+        total = chunks.sum { |chunk| channel_count ? chunk.shape[0] : chunk.size }
+        if channel_count
+          output = Numo::SFloat.zeros(total, channel_count)
+          offset = 0
+          chunks.each do |chunk|
+            next if chunk.shape[0].zero?
+
+            output[offset...(offset + chunk.shape[0]), true] = chunk
+            offset += chunk.shape[0]
+          end
+          return output
+        end
+
+        Numo::SFloat.cast(chunks.flat_map(&:to_a))
+      end
+      private_class_method :concatenate_chunks
+    end
+  end
+end

data/lib/muze/core/cache.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Muze
+  module Core
+    # Tiny bounded LRU cache for generated DSP lookup tables.
+    class BoundedCache
+      def initialize(max_size:)
+        raise Muze::ParameterError, "max_size must be positive" unless max_size.is_a?(Integer) && max_size.positive?
+
+        @max_size = max_size
+        @entries = {}
+        @mutex = Mutex.new
+      end
+
+      def fetch(key)
+        @mutex.synchronize do
+          if @entries.key?(key)
+            value = @entries.delete(key)
+            @entries[key] = value
+            return value
+          end
+
+          value = yield
+          @entries.shift while @entries.size >= @max_size
+          @entries[key] = value
+        end
+      end
+
+      def clear
+        @mutex.synchronize { @entries.clear }
+      end
+
+      def size
+        @mutex.synchronize { @entries.size }
+      end
+    end
+  end
+end

data/lib/muze/core/dct.rb

@@ -4,6 +4,7 @@ module Muze
   module Core
     # DCT utilities.
     module DCT
+      BASIS_CACHE = Muze::Core::BoundedCache.new(max_size: 64)
       module_function
 
       # @param x [Numo::NArray]
@@ -22,34 +23,36 @@ module Muze
 
         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
+        working = adjust_rows(matrix, target_length)
+        result = basis_matrix(rows: target_length, cols: target_length, norm:).dot(working).cast_to(Numo::SFloat)
 
         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
+      def adjust_rows(matrix, target_length)
+        rows, cols = matrix.shape
+        return matrix[0...target_length, true] if rows >= target_length
 
-          normalize_dct(sum, k, n, norm)
+        output = Numo::SFloat.zeros(target_length, cols)
+        output[0...rows, true] = matrix
+        output
+      end
+      private_class_method :adjust_rows
+
+      def basis_matrix(rows:, cols:, norm:)
+        key = [rows, cols, norm]
+        BASIS_CACHE.fetch(key) do
+          matrix = Numo::SFloat.zeros(rows, cols)
+          rows.times do |row|
+            cols.times do |col|
+              value = Math.cos(Math::PI * (col + 0.5) * row / cols)
+              matrix[row, col] = normalize_dct(value, row, cols, norm)
+            end
+          end
+          matrix
         end
       end
-      private_class_method :dct_vector
+      private_class_method :basis_matrix
 
       def normalize_dct(value, index, length, norm)
         return value * 2.0 unless norm == :ortho

data/lib/muze/core/frames.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Muze
+  module Core
+    # Shared fixed-size frame slicing for analysis and effects code.
+    module Frames
+      module_function
+
+      def slice(signal, frame_length:, hop_length:, pad_end: false)
+        raise Muze::ParameterError, "frame_length and hop_length must be positive" unless frame_length.positive? && hop_length.positive?
+
+        values = signal.is_a?(Numo::NArray) ? signal.to_a : Array(signal)
+        return [pad_frame(values, frame_length)] if values.length <= frame_length
+        return Muze::Native.frame_slices(values, frame_length, hop_length) unless pad_end
+
+        frame_count = ((values.length - frame_length).to_f / hop_length).ceil + 1
+        Array.new(frame_count) do |index|
+          start = index * hop_length
+          pad_frame(values[start, frame_length] || [], frame_length)
+        end
+      end
+
+      def pad_frame(frame, frame_length)
+        return frame if frame.length >= frame_length
+
+        frame + Array.new(frame_length - frame.length, 0.0)
+      end
+      private_class_method :pad_frame
+    end
+  end
+end