muze 0.1.0 → 1.0.0

data/lib/muze/io/audio_loader.rb

@@ -9,31 +9,40 @@ module Muze
     module AudioLoader
       module_function
 
-      SUPPORTED_FORMATS = %w[wav flac mp3 ogg].freeze
-
-      # @param path [String]
-      # @param sr [Integer] destination sample rate
-      # @param mono [Boolean]
+      BACKENDS = [
+        WavifyBackend,
+        FFMPEGBackend
+      ].freeze
+      SUPPORTED_FORMATS = BACKENDS.flat_map { |backend| backend::SUPPORTED_EXTENSIONS }.map { |ext| ext.delete_prefix(".") }.sort.freeze
+
+      # @param path [String, Pathname, IO]
+      # @param sr [Integer, nil] destination sample rate; nil preserves source rate
+      # @param mono [Boolean, Symbol]
       # @param offset [Float] seconds from start
       # @param duration [Float, nil] duration in seconds
+      # @param dtype [Class, Symbol]
+      # @param normalize [Boolean]
+      # @param format [Symbol, String, nil]
+      # @param weights [Array<Float>, nil]
+      # @param max_bytes [Integer, nil]
       # @return [Array(Numo::SFloat, Integer)] waveform and sample rate
-      def load(path, sr: 22_050, mono: true, offset: 0.0, duration: nil)
-        validate_args!(sr:, offset:, duration:)
-        raise Muze::AudioLoadError, "File not found: #{path}" unless File.exist?(path)
-
-        backend = select_backend(path)
-        raw_samples, source_sr, _channels = backend.read(path)
-        sliced = slice_by_time(raw_samples, source_sr, offset:, duration:)
-
-        signal = if mono
-                   downmix_to_mono(sliced)
-                 else
-                   sliced
-                 end
-
-        resampled = resample(signal, source_sr, sr)
-        [Numo::SFloat.cast(resampled), sr]
-      rescue Muze::AudioLoadError
+      def load(path, sr: 22_050, mono: true, offset: 0.0, duration: nil, dtype: Numo::SFloat, normalize: false, format: nil, weights: nil, max_bytes: nil)
+        source = resolve_source(path, format:)
+        validate_args!(sr:, mono:, offset:, duration:, dtype:, normalize:, weights:, max_bytes:)
+        validate_source_size!(source, max_bytes:)
+
+        backend = select_backend(source)
+        raw_samples, source_sr, _channels = backend.read(source.fetch(:input), offset:, duration:)
+        sliced = backend.applies_time_window? ? raw_samples : slice_by_time(raw_samples, source_sr, offset:, duration:)
+
+        signal = downmix(sliced, mono:, weights:)
+        target_sr = sr || source_sr
+
+        resampled = resample(signal, source_sr, target_sr)
+        output = cast_signal(resampled, dtype)
+        output = normalize_signal(output) if normalize
+        [output, target_sr]
+      rescue Muze::AudioLoadError, Muze::ParameterError
         raise
       rescue Muze::UnsupportedFormatError, Muze::DependencyError => e
         raise Muze::AudioLoadError, e.message
@@ -41,27 +50,110 @@ module Muze
         raise Muze::AudioLoadError, "Failed to load #{path}: #{e.message}"
       end
 
-      def validate_args!(sr:, offset:, duration:)
-        raise Muze::ParameterError, "sr must be positive" unless sr.is_a?(Integer) && sr.positive?
+      # @param path [String, Pathname, IO]
+      # @param chunk_frames [Integer]
+      # @yieldparam chunk [Numo::SFloat, Numo::DFloat]
+      # @yieldparam sample_rate [Integer]
+      # @return [Enumerator, nil]
+      def load_stream(path, sr: nil, mono: true, offset: 0.0, duration: nil, dtype: Numo::SFloat, format: nil, weights: nil, max_bytes: nil, chunk_frames: 16_384)
+        return enum_for(__method__, path, sr:, mono:, offset:, duration:, dtype:, format:, weights:, max_bytes:, chunk_frames:) unless block_given?
+
+        source = resolve_source(path, format:)
+        validate_args!(sr:, mono:, offset:, duration:, dtype:, normalize: false, weights:, max_bytes:)
+        validate_stream_args!(chunk_frames:)
+        validate_source_size!(source, max_bytes:)
+
+        backend = select_backend(source)
+        backend.read_stream(source.fetch(:input), chunk_frames:, offset:, duration:) do |raw_samples, source_sr, _channels|
+          target_sr = sr || source_sr
+          signal = downmix(raw_samples, mono:, weights:)
+          resampled = resample(signal, source_sr, target_sr)
+          yield cast_signal(resampled, dtype), target_sr unless resampled.empty?
+        end
+        nil
+      rescue Muze::AudioLoadError, Muze::ParameterError
+        raise
+      rescue Muze::UnsupportedFormatError, Muze::DependencyError => e
+        raise Muze::AudioLoadError, e.message
+      rescue StandardError => e
+        raise Muze::AudioLoadError, "Failed to stream #{path}: #{e.message}"
+      end
+
+      # @param path [String, Pathname, IO]
+      # @return [Hash]
+      def info(path, format: nil)
+        source = resolve_source(path, format:)
+
+        select_backend(source).info(source.fetch(:input))
+      rescue Muze::AudioLoadError
+        raise
+      rescue Muze::UnsupportedFormatError, Muze::DependencyError => e
+        raise Muze::AudioLoadError, e.message
+      rescue StandardError => e
+        raise Muze::AudioLoadError, "Failed to inspect #{path}: #{e.message}"
+      end
+
+      def resolve_source(path, format:)
+        resolved = path.respond_to?(:to_path) ? path.to_path : path
+        if resolved.is_a?(String)
+          raise Muze::AudioLoadError, "File not found: #{resolved}" unless File.exist?(resolved)
+
+          return { input: resolved, extension: normalized_extension(format || File.extname(resolved)), path?: true }
+        end
+
+        return { input: resolved, extension: normalized_extension(format || :wav), path?: false } if resolved.respond_to?(:read)
+
+        raise Muze::AudioLoadError, "Audio source must be a String, Pathname, or IO-like object"
+      end
+      private_class_method :resolve_source
+
+      def normalized_extension(format)
+        extension = format.to_s
+        extension = ".#{extension}" unless extension.start_with?(".")
+        extension.downcase
+      end
+      private_class_method :normalized_extension
+
+      def validate_args!(sr:, mono:, offset:, duration:, dtype:, normalize:, weights:, max_bytes:)
+        raise Muze::ParameterError, "sr must be positive or nil" unless sr.nil? || (sr.is_a?(Integer) && sr.positive?)
+        raise Muze::ParameterError, "mono must be true, false, :mean, :left, :right, or :weighted" unless [true, false, :mean, :left, :right, :weighted].include?(mono)
         raise Muze::ParameterError, "offset must be >= 0" if offset.negative?
+        raise Muze::ParameterError, "normalize must be true or false" unless [true, false].include?(normalize)
+        raise Muze::ParameterError, "weights must be an Array when mono is :weighted" if mono == :weighted && !weights.is_a?(Array)
+        raise Muze::ParameterError, "max_bytes must be positive" if max_bytes && (!max_bytes.is_a?(Integer) || max_bytes <= 0)
+        dtype_class(dtype)
         return if duration.nil? || duration.positive?
 
         raise Muze::ParameterError, "duration must be positive"
       end
       private_class_method :validate_args!
 
-      def select_backend(path)
-        extension = File.extname(path).downcase
+      def validate_stream_args!(chunk_frames:)
+        return if chunk_frames.is_a?(Integer) && chunk_frames.positive?
 
-        if WavifyBackend.supported_extension?(extension)
-          WavifyBackend
-        elsif FFMPEGBackend.supported_extension?(extension)
-          raise Muze::DependencyError, FFMPEGBackend.installation_message(extension) unless FFMPEGBackend.available?
+        raise Muze::ParameterError, "chunk_frames must be a positive integer"
+      end
+      private_class_method :validate_stream_args!
 
-          FFMPEGBackend
-        else
-          raise Muze::UnsupportedFormatError, unsupported_format_message(extension)
+      def validate_source_size!(source, max_bytes:)
+        return unless max_bytes && source.fetch(:path?)
+
+        size = File.size(source.fetch(:input))
+        raise Muze::AudioLoadError, "Audio file is too large (#{size} bytes > #{max_bytes} bytes)" if size > max_bytes
+      end
+      private_class_method :validate_source_size!
+
+      def select_backend(source)
+        extension = source.fetch(:extension)
+        backend = BACKENDS.find { |candidate| candidate.supported_extension?(extension) }
+
+        raise Muze::UnsupportedFormatError, unsupported_format_message(extension) unless backend
+        if !source.fetch(:path?) && backend != WavifyBackend
+          raise Muze::UnsupportedFormatError, "IO/StringIO loading is currently supported for WAV input only"
         end
+        raise Muze::DependencyError, backend.installation_message(extension) unless backend.available?
+
+        backend
       end
       private_class_method :select_backend
 
@@ -85,6 +177,31 @@ module Muze
       end
       private_class_method :slice_by_time
 
+      def downmix(samples, mono:, weights:)
+        return samples if mono == false
+        return downmix_to_mono(samples) if mono == true || mono == :mean
+        return downmix_weighted(samples, weights) if mono == :weighted
+        return samples unless samples.first.is_a?(Array)
+
+        channel_index = mono == :left ? 0 : samples.first.length - 1
+        samples.map { |frame| frame.fetch(channel_index) }
+      end
+      private_class_method :downmix
+
+      def downmix_weighted(samples, weights)
+        return samples if samples.empty?
+        return samples unless samples.first.is_a?(Array)
+        raise Muze::ParameterError, "weights length must match channel count" unless weights.length == samples.first.length
+
+        weight_sum = weights.sum(0.0)
+        raise Muze::ParameterError, "weights must not sum to zero" if weight_sum.abs <= 1.0e-12
+
+        samples.map do |frame|
+          frame.each_with_index.sum { |sample, index| sample * weights[index] } / weight_sum
+        end
+      end
+      private_class_method :downmix_weighted
+
       def downmix_to_mono(samples)
         return samples if samples.empty?
         return samples unless samples.first.is_a?(Array)
@@ -94,24 +211,37 @@ module Muze
       private_class_method :downmix_to_mono
 
       def resample(samples, source_sr, target_sr)
-        if samples.empty?
-          []
-        elsif samples.first.is_a?(Array)
-          channel_count = samples.first.length
-          channels = Array.new(channel_count) { [] }
-          samples.each { |frame| frame.each_with_index { |sample, index| channels[index] << sample } }
-
-          resampled_channels = channels.map do |channel_data|
-            Muze::Core::Resample.resample(channel_data, orig_sr: source_sr, target_sr: target_sr, res_type: :sinc).to_a
-          end
-
-          target_length = resampled_channels.first.length
-          Array.new(target_length) { |idx| resampled_channels.map { |channel| channel[idx] } }
+        return [] if samples.empty?
+
+        Muze::Core::Resample.resample(samples, orig_sr: source_sr, target_sr: target_sr, res_type: :sinc)
+      end
+      private_class_method :resample
+
+      def cast_signal(signal, dtype)
+        dtype_class(dtype).cast(signal)
+      end
+      private_class_method :cast_signal
+
+      def dtype_class(dtype)
+        case dtype
+        when :sfloat, :float32 then Numo::SFloat
+        when :dfloat, :float64 then Numo::DFloat
         else
-          Muze::Core::Resample.resample(samples, orig_sr: source_sr, target_sr: target_sr, res_type: :sinc).to_a
+          return Numo::SFloat if dtype == Numo::SFloat
+          return Numo::DFloat if dtype == Numo::DFloat
+
+          raise Muze::ParameterError, "dtype must be :sfloat, :float32, :dfloat, :float64, Numo::SFloat, or Numo::DFloat"
         end
       end
-      private_class_method :resample
+      private_class_method :dtype_class
+
+      def normalize_signal(signal)
+        peak = signal.abs.max
+        return signal if peak <= 0.0
+
+        (signal / peak).cast_to(signal.class)
+      end
+      private_class_method :normalize_signal
     end
   end
 end

data/lib/muze/io/audio_writer.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "wavify/core/format"
+require "wavify/core/sample_buffer"
+require "wavify/codecs/base"
+require "wavify/codecs/wav"
+
+module Muze
+  module IO
+    # WAV writer for lightweight effects/analysis result inspection.
+    module AudioWriter
+      module_function
+
+      def write(path, y, sr:, normalize: false, format: :wav)
+        raise Muze::ParameterError, "sr must be positive" unless sr.is_a?(Integer) && sr.positive?
+        raise Muze::ParameterError, "normalize must be true or false" unless [true, false].include?(normalize)
+
+        format_label = format.to_s.downcase.to_sym
+        raise Muze::UnsupportedFormatError, "only WAV output is supported" unless %i[wav wave].include?(format_label)
+
+        signal = Muze::Core::Audio.validate_audio!(y, allow_empty: true)
+        signal = Muze::Core::Audio.normalize(signal) if normalize
+        channels = signal.ndim == 2 ? signal.shape[1] : 1
+        samples = flatten_samples(signal)
+        sample_format = Wavify::Core::Format.new(channels:, sample_rate: sr, bit_depth: 32, sample_format: :float)
+        buffer = Wavify::Core::SampleBuffer.new(samples, sample_format)
+        Wavify::Codecs::Wav.write(output_target(path), buffer)
+        path
+      rescue Muze::Error
+        raise
+      rescue SystemCallError, Wavify::Error => e
+        raise Muze::AudioLoadError, "Failed to write WAV output #{path}: #{e.message}"
+      end
+
+      def flatten_samples(signal)
+        return signal.to_a if signal.ndim == 1
+
+        signal.to_a.flat_map { |frame| frame.respond_to?(:to_a) ? frame.to_a : Array(frame) }
+      end
+      private_class_method :flatten_samples
+
+      def output_target(path)
+        path.respond_to?(:to_path) ? path.to_path : path
+      end
+      private_class_method :output_target
+    end
+  end
+end

data/lib/muze/native.rb

@@ -5,12 +5,16 @@ module Muze
   module Native
     module_function
 
-    begin
-      require "muze/muze_ext"
-      EXTENSION_LOADED = true
-    rescue LoadError
-      EXTENSION_LOADED = false
-    end
+    EXTENSION_LOADED = if ENV.fetch("MUZE_DISABLE_NATIVE", "0") == "1"
+                         false
+                       else
+                         begin
+                           require "muze/muze_ext"
+                           true
+                         rescue LoadError
+                           false
+                         end
+                       end
 
     # @return [Boolean]
     def extension_loaded?
@@ -23,6 +27,11 @@ module Muze
       # @param hop_length [Integer]
       # @return [Array<Array<Float>>]
       def frame_slices(signal, frame_length, hop_length)
+        raise Muze::ParameterError, "signal must be an Array" unless signal.is_a?(Array)
+        unless frame_length.is_a?(Integer) && hop_length.is_a?(Integer) && frame_length.positive? && hop_length.positive?
+          raise Muze::ParameterError, "frame_length and hop_length must be positive"
+        end
+
         if signal.length <= frame_length
           return [signal + Array.new(frame_length - signal.length, 0.0)]
         end
@@ -37,9 +46,83 @@ module Muze
       # @param values [Array<Float>]
       # @return [Float]
       def median1d(values)
-        sorted = values.sort
-        sorted[sorted.length / 2] || 0.0
+        raise Muze::ParameterError, "values must be an Array" unless values.is_a?(Array)
+        return 0.0 if values.empty?
+
+        copy = values.map(&:to_f)
+        quickselect!(copy, copy.length / 2)
+      end
+
+      # @param values [Array<Float>]
+      # @param half [Integer]
+      # @return [Array<Float>]
+      def median_filter1d(values, half)
+        raise Muze::ParameterError, "values must be an Array" unless values.is_a?(Array)
+        raise Muze::ParameterError, "half must be non-negative" unless half.is_a?(Integer) && half >= 0
+        return [] if values.empty?
+
+        window = []
+        output = Array.new(values.length, 0.0)
+        values.length.times do |index|
+          remove_sorted_value(window, values[index - half - 1]) if index > half
+          entering = index + half
+          insert_sorted_value(window, values[entering]) if entering < values.length
+          output[index] = window[window.length / 2].to_f
+        end
+
+        output
+      end
+
+      def quickselect!(values, target)
+        left = 0
+        right = values.length - 1
+
+        loop do
+          return values[left] if left == right
+
+          pivot_index = partition!(values, left, right, (left + right) / 2)
+          if target == pivot_index
+            return values[target]
+          elsif target < pivot_index
+            right = pivot_index - 1
+          else
+            left = pivot_index + 1
+          end
+        end
+      end
+      private_class_method :quickselect!
+
+      def partition!(values, left, right, pivot_index)
+        pivot = values[pivot_index]
+        values[pivot_index], values[right] = values[right], values[pivot_index]
+        store_index = left
+
+        (left...right).each do |index|
+          next unless values[index] < pivot
+
+          values[store_index], values[index] = values[index], values[store_index]
+          store_index += 1
+        end
+
+        values[right], values[store_index] = values[store_index], values[right]
+        store_index
+      end
+      private_class_method :partition!
+
+      def insert_sorted_value(sorted, value)
+        index = sorted.bsearch_index { |item| item > value } || sorted.length
+        sorted.insert(index, value)
+      end
+      private_class_method :insert_sorted_value
+
+      def remove_sorted_value(sorted, value)
+        index = sorted.bsearch_index { |item| item >= value }
+        return unless index
+
+        index += 1 while index < sorted.length && sorted[index] != value
+        sorted.delete_at(index) if index < sorted.length
       end
+      private_class_method :remove_sorted_value
     end
   end
 end

data/lib/muze/onset/onset_detect.rb

@@ -11,24 +11,38 @@ module Muze
     # @param hop_length [Integer]
     # @param n_fft [Integer]
     # @return [Numo::SFloat] onset envelope per frame
-    def onset_strength(y: nil, sr: 22_050, s: nil, hop_length: 512, n_fft: 2048)
+    def onset_strength(y: nil, sr: 22_050, s: nil, hop_length: 512, n_fft: 2048, lag: 1, log: false, max_size: 1, normalize: false)
+      validate_positive_integer!(sr, "sr")
+      validate_positive_integer!(hop_length, "hop_length")
+      validate_positive_integer!(n_fft, "n_fft")
+      validate_positive_integer!(lag, "lag")
+      validate_positive_integer!(max_size, "max_size")
+      raise Muze::ParameterError, "log must be true or false" unless [true, false].include?(log)
+      raise Muze::ParameterError, "normalize must be true or false" unless [true, false].include?(normalize)
+
       spectrum = if s
-                   Numo::SFloat.cast(s)
+                   provided = Numo::SFloat.cast(s)
+                   validate_finite_array!(provided.to_a.flatten, "s")
+                   provided
                  else
                    Muze::Feature.melspectrogram(y:, sr:, n_fft:, hop_length:, n_mels: 40)
                  end
 
       spectrum = spectrum.expand_dims(1) if spectrum.ndim == 1
+      spectrum = Muze.power_to_db(spectrum, ref: :max) if log
+      spectrum = local_max_filter(spectrum, max_size:) if max_size > 1
       _, frames = spectrum.shape
       envelope = Numo::SFloat.zeros(frames)
 
       frames.times do |frame_index|
-        next if frame_index.zero?
+        next if frame_index < lag
 
-        delta = spectrum[true, frame_index] - spectrum[true, frame_index - 1]
+        delta = spectrum[true, frame_index] - spectrum[true, frame_index - lag]
         envelope[frame_index] = delta.clip(0.0, Float::INFINITY).sum
       end
 
+      peak = envelope.max
+      envelope = envelope / peak if normalize && peak.positive?
       envelope
     end
 
@@ -39,29 +53,31 @@ module Muze
     # @param backtrack [Boolean]
     # @param units [Symbol] :frames, :samples, or :time
     # @return [Array<Integer, Float>]
-    def onset_detect(y: nil, sr: 22_050, onset_envelope: nil, hop_length: 512, backtrack: false, units: :frames)
+    def onset_detect(y: nil, sr: 22_050, onset_envelope: nil, hop_length: 512, backtrack: false, units: :frames, pre_max: 1, post_max: 1, pre_avg: 1, post_avg: 1, delta: nil, wait: 0, adaptive: false, energy: nil)
+      validate_positive_integer!(sr, "sr")
+      validate_positive_integer!(hop_length, "hop_length")
+      validate_peak_picker_args!(pre_max:, post_max:, pre_avg:, post_avg:, wait:, delta:)
+      raise Muze::ParameterError, "backtrack must be true or false" unless [true, false].include?(backtrack)
+      raise Muze::ParameterError, "adaptive must be true or false" unless [true, false].include?(adaptive)
+
       envelope = if onset_envelope
                    onset_envelope.is_a?(Numo::NArray) ? onset_envelope.to_a : Array(onset_envelope)
                  else
-                   onset_strength(y:, sr:, hop_length:).to_a
+                  onset_strength(y:, sr:, hop_length:).to_a
                  end
+      validate_finite_array!(envelope, "onset_envelope")
 
       return [] if envelope.length < 3
 
-      threshold = detection_threshold(envelope)
-      peaks = detect_peaks(envelope, threshold)
-      peaks = backtrack_onsets(envelope, peaks) if backtrack
-
-      case units
-      when :frames
-        peaks
-      when :samples
-        peaks.map { |frame| frame * hop_length }
-      when :time
-        peaks.map { |frame| frame * hop_length.to_f / sr }
-      else
-        raise Muze::ParameterError, "units must be :frames, :samples, or :time"
+      threshold = delta || detection_threshold(envelope)
+      peaks = detect_peaks(envelope, threshold, pre_max:, post_max:, pre_avg:, post_avg:, wait:, adaptive:)
+      if backtrack
+        energy_curve = energy ? Array(energy) : envelope
+        validate_finite_array!(energy_curve, "energy")
+        peaks = backtrack_onsets(energy_curve, peaks)
       end
+
+      convert_units(peaks, units:, sr:, hop_length:)
     end
 
     def detection_threshold(envelope)
@@ -71,14 +87,22 @@ module Muze
     end
     private_class_method :detection_threshold
 
-    def detect_peaks(envelope, threshold)
+    def detect_peaks(envelope, threshold, pre_max:, post_max:, pre_avg:, post_avg:, wait:, adaptive:)
       peaks = []
+      last_peak = -Float::INFINITY
       (1...(envelope.length - 1)).each do |index|
-        next unless envelope[index] >= threshold
-        next unless envelope[index] > envelope[index - 1]
-        next unless envelope[index] >= envelope[index + 1]
+        local_max_start = [index - pre_max, 0].max
+        local_max_end = [index + post_max, envelope.length - 1].min
+        local_avg_start = [index - pre_avg, 0].max
+        local_avg_end = [index + post_avg, envelope.length - 1].min
+        local_threshold = adaptive ? average(envelope[local_avg_start..local_avg_end]) + threshold : threshold
+
+        next unless envelope[index] >= local_threshold
+        next unless envelope[index] >= envelope[local_max_start..local_max_end].max
+        next if index <= last_peak + wait
 
         peaks << index
+        last_peak = index
       end
       peaks
     end
@@ -93,5 +117,72 @@ module Muze
       end.uniq
     end
     private_class_method :backtrack_onsets
+
+    def convert_units(peaks, units:, sr:, hop_length:)
+      case units
+      when :frames
+        peaks
+      when :samples
+        peaks.map { |frame| frame * hop_length }
+      when :time
+        peaks.map { |frame| frame * hop_length.to_f / sr }
+      else
+        raise Muze::ParameterError, "units must be :frames, :samples, or :time"
+      end
+    end
+    private_class_method :convert_units
+
+    def local_max_filter(spectrum, max_size:)
+      rows, cols = spectrum.shape
+      half = max_size / 2
+      output = Numo::SFloat.zeros(rows, cols)
+
+      rows.times do |row|
+        cols.times do |col|
+          start_col = [col - half, 0].max
+          end_col = [col + half, cols - 1].min
+          output[row, col] = spectrum[row, start_col..end_col].max
+        end
+      end
+      output
+    end
+    private_class_method :local_max_filter
+
+    def average(values)
+      values.sum(0.0) / values.length
+    end
+    private_class_method :average
+
+    def validate_peak_picker_args!(pre_max:, post_max:, pre_avg:, post_avg:, wait:, delta:)
+      {
+        pre_max: pre_max,
+        post_max: post_max,
+        pre_avg: pre_avg,
+        post_avg: post_avg,
+        wait: wait
+      }.each do |label, value|
+        next if value.is_a?(Integer) && !value.negative?
+
+        raise Muze::ParameterError, "#{label} must be a non-negative integer"
+      end
+      return if delta.nil? || (delta.respond_to?(:finite?) && delta.finite? && !delta.negative?)
+
+      raise Muze::ParameterError, "delta must be non-negative"
+    end
+    private_class_method :validate_peak_picker_args!
+
+    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_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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Muze
-  VERSION = "0.1.0"
+  VERSION = "1.0.0"
 end