muze 0.1.0

data/lib/muze/core/stft.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+module Muze
+  module Core
+    # Short-time Fourier transform and related utilities.
+    module STFT
+      EPSILON = 1.0e-12
+      module_function
+
+      # @param y [Numo::SFloat, Array<Float>] waveform signal
+      # @param n_fft [Integer]
+      # @param hop_length [Integer]
+      # @param win_length [Integer, nil]
+      # @param window [Symbol]
+      # @param center [Boolean]
+      # @param pad_mode [Symbol]
+      # @return [Numo::DComplex] shape: [1 + n_fft/2, frames]
+      def stft(y, n_fft: 2048, hop_length: 512, win_length: nil, window: :hann, center: true, pad_mode: :reflect)
+        _ = pad_mode
+        win_length ||= n_fft
+        validate_stft_params!(n_fft:, hop_length:, win_length:)
+
+        signal = y.is_a?(Numo::NArray) ? y.to_a : Array(y)
+        signal = reflect_pad(signal, n_fft / 2) if center
+        signal = signal.empty? ? [0.0] : signal
+
+        frames = frame_signal(signal, n_fft, hop_length)
+        window_values = Muze::Core::Windows.resolve(window, win_length).to_a
+        window_offset = (n_fft - win_length) / 2
+
+        frequency_bins = (n_fft / 2) + 1
+        stft_matrix = Numo::DComplex.zeros(frequency_bins, frames.length)
+
+        frames.each_with_index do |frame, frame_index|
+          windowed = Array.new(n_fft, 0.0)
+          win_length.times do |index|
+            frame_index_in_window = index + window_offset
+            windowed[frame_index_in_window] = frame[frame_index_in_window] * window_values[index]
+          end
+
+          spectrum = fft_complex(windowed.map { |value| Complex(value, 0.0) })
+          frequency_bins.times { |bin| stft_matrix[bin, frame_index] = spectrum[bin] }
+        end
+
+        stft_matrix
+      end
+
+      # @param stft_matrix [Numo::DComplex]
+      # @param hop_length [Integer]
+      # @param win_length [Integer, nil]
+      # @param window [Symbol]
+      # @param center [Boolean]
+      # @param length [Integer, nil]
+      # @return [Numo::SFloat]
+      def istft(stft_matrix, hop_length: 512, win_length: nil, window: :hann, center: true, length: nil)
+        frequency_bins, frame_count = stft_matrix.shape
+        n_fft = (frequency_bins - 1) * 2
+        win_length ||= n_fft
+        validate_stft_params!(n_fft:, hop_length:, win_length:)
+
+        signal_length = n_fft + (hop_length * [frame_count - 1, 0].max)
+        output = Array.new(signal_length, 0.0)
+        window_sums = Array.new(signal_length, 0.0)
+        window_values = Muze::Core::Windows.resolve(window, win_length).to_a
+        window_offset = (n_fft - win_length) / 2
+
+        frame_count.times do |frame_index|
+          half_spectrum = Array.new(frequency_bins) { |bin| stft_matrix[bin, frame_index] }
+          mirrored = half_spectrum[1...-1].reverse.map(&:conj)
+          full_spectrum = half_spectrum + mirrored
+          time_domain = ifft_complex(full_spectrum).map(&:real)
+
+          win_length.times do |index|
+            output_index = (frame_index * hop_length) + index + window_offset
+            break if output_index >= signal_length
+
+            window_value = window_values[index]
+            frame_value = time_domain[index + window_offset]
+            output[output_index] += frame_value * window_value
+            window_sums[output_index] += window_value * window_value
+          end
+        end
+
+        output.map!.with_index do |value, index|
+          denominator = window_sums[index]
+          denominator > EPSILON ? (value / denominator) : value
+        end
+
+        if center
+          pad = n_fft / 2
+          output = output[pad...(output.length - pad)] || []
+        end
+
+        output = adjust_length(output, length) if length
+        Numo::SFloat.cast(output)
+      end
+
+      # @param stft_matrix [Numo::DComplex]
+      # @return [Array<Numo::SFloat, Numo::DComplex>]
+      def magphase(stft_matrix)
+        magnitude = stft_matrix.abs.cast_to(Numo::SFloat)
+        phase = stft_matrix / (magnitude + EPSILON)
+        [magnitude, phase]
+      end
+
+      # @param s [Numo::NArray]
+      # @param ref [Float, Symbol, Proc]
+      # @param amin [Float]
+      # @param top_db [Float, nil]
+      # @return [Numo::SFloat]
+      def amplitude_to_db(s, ref: 1.0, amin: 1.0e-5, top_db: 80.0)
+        magnitude = s.is_a?(Numo::DComplex) ? s.abs.cast_to(Numo::SFloat) : Numo::SFloat.cast(s)
+        log_scale(magnitude, ref:, amin:, top_db:, multiplier: 20.0)
+      end
+
+      # @param s [Numo::NArray]
+      # @param ref [Float, Symbol, Proc]
+      # @param amin [Float]
+      # @param top_db [Float, nil]
+      # @return [Numo::SFloat]
+      def power_to_db(s, ref: 1.0, amin: 1.0e-10, top_db: 80.0)
+        power = Numo::SFloat.cast(s)
+        log_scale(power, ref:, amin:, top_db:, multiplier: 10.0)
+      end
+
+      # @param s_db [Numo::NArray]
+      # @param ref [Float]
+      # @return [Numo::SFloat]
+      def db_to_amplitude(s_db, ref: 1.0)
+        Numo::SFloat.cast(ref.to_f * Numo::NMath.exp((Numo::SFloat.cast(s_db) / 20.0) * Math.log(10.0)))
+      end
+
+      # @param s_db [Numo::NArray]
+      # @param ref [Float]
+      # @return [Numo::SFloat]
+      def db_to_power(s_db, ref: 1.0)
+        Numo::SFloat.cast(ref.to_f * Numo::NMath.exp((Numo::SFloat.cast(s_db) / 10.0) * Math.log(10.0)))
+      end
+
+      def adjust_length(signal, length)
+        return signal[0, length] if signal.length >= length
+
+        signal + Array.new(length - signal.length, 0.0)
+      end
+      private_class_method :adjust_length
+
+      def log_scale(values, ref:, amin:, top_db:, multiplier:)
+        clipped = values.clip(amin, Float::INFINITY)
+        reference = reference_value(ref, clipped, amin)
+        base = multiplier * Math.log10(reference)
+        db = (multiplier * Numo::NMath.log10(clipped)) - base
+
+        return db.cast_to(Numo::SFloat) if top_db.nil?
+
+        floor = db.max - top_db
+        db.clip(floor, Float::INFINITY).cast_to(Numo::SFloat)
+      end
+      private_class_method :log_scale
+
+      def reference_value(ref, values, amin)
+        value = case ref
+                when :max then values.max
+                when Proc then ref.call(values)
+                else
+                  ref.to_f
+                end
+
+        [value, amin].max
+      end
+      private_class_method :reference_value
+
+      def validate_stft_params!(n_fft:, hop_length:, win_length:)
+        raise Muze::ParameterError, "n_fft must be positive" if n_fft <= 0
+        raise Muze::ParameterError, "n_fft must be a power of two" unless power_of_two?(n_fft)
+        raise Muze::ParameterError, "hop_length must be positive" if hop_length <= 0
+        raise Muze::ParameterError, "hop_length must be <= n_fft" if hop_length > n_fft
+        raise Muze::ParameterError, "win_length must be between 1 and n_fft" unless win_length.between?(1, n_fft)
+      end
+      private_class_method :validate_stft_params!
+
+      def power_of_two?(value)
+        (value & (value - 1)).zero?
+      end
+      private_class_method :power_of_two?
+
+      def frame_signal(signal, n_fft, hop_length)
+        Muze::Native.frame_slices(signal, n_fft, hop_length)
+      end
+      private_class_method :frame_signal
+
+      def reflect_pad(signal, pad)
+        return signal if pad <= 0 || signal.length <= 1
+
+        front = signal[1, pad].to_a.reverse
+        back = signal[-(pad + 1), pad].to_a.reverse
+        front + signal + back
+      end
+      private_class_method :reflect_pad
+
+      def fft_complex(values)
+        length = values.length
+        return values if length <= 1
+
+        raise Muze::ParameterError, "FFT length must be a power of two" unless power_of_two?(length)
+
+        even = fft_complex(values.values_at(*0.step(length - 1, 2)))
+        odd = fft_complex(values.values_at(*1.step(length - 1, 2)))
+
+        output = Array.new(length)
+        half = length / 2
+
+        half.times do |k|
+          twiddle = Complex.polar(1.0, -2.0 * Math::PI * k / length) * odd[k]
+          output[k] = even[k] + twiddle
+          output[k + half] = even[k] - twiddle
+        end
+
+        output
+      end
+      private_class_method :fft_complex
+
+      def ifft_complex(values)
+        conjugated = values.map(&:conj)
+        transformed = fft_complex(conjugated)
+        scale = values.length.to_f
+        transformed.map { |value| value.conj / scale }
+      end
+      private_class_method :ifft_complex
+    end
+  end
+end

data/lib/muze/core/windows.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Muze
+  module Core
+    # Window function generators for short-time analysis.
+    module Windows
+      module_function
+
+      # @param n [Integer]
+      # @return [Numo::SFloat]
+      def hann(n)
+        raise Muze::ParameterError, "window length must be positive" if n <= 0
+        return Numo::SFloat[1.0] if n == 1
+
+        build_window(n) { |k, denom| 0.5 * (1.0 - Math.cos((2.0 * Math::PI * k) / denom)) }
+      end
+
+      # @param n [Integer]
+      # @return [Numo::SFloat]
+      def hamming(n)
+        raise Muze::ParameterError, "window length must be positive" if n <= 0
+        return Numo::SFloat[1.0] if n == 1
+
+        build_window(n) { |k, denom| 0.54 - (0.46 * Math.cos((2.0 * Math::PI * k) / denom)) }
+      end
+
+      # @param n [Integer]
+      # @return [Numo::SFloat]
+      def blackman(n)
+        raise Muze::ParameterError, "window length must be positive" if n <= 0
+        return Numo::SFloat[1.0] if n == 1
+
+        build_window(n) do |k, denom|
+          phase = (2.0 * Math::PI * k) / denom
+          0.42 - (0.5 * Math.cos(phase)) + (0.08 * Math.cos(2.0 * phase))
+        end
+      end
+
+      # @param n [Integer]
+      # @return [Numo::SFloat]
+      def ones(n)
+        raise Muze::ParameterError, "window length must be positive" if n <= 0
+
+        Numo::SFloat.ones(n)
+      end
+
+      # @param name [Symbol]
+      # @param n [Integer]
+      # @return [Numo::SFloat]
+      def resolve(name, n)
+        case name
+        when :hann then hann(n)
+        when :hamming then hamming(n)
+        when :blackman then blackman(n)
+        when :ones, :boxcar, :rect then ones(n)
+        else
+          raise Muze::ParameterError, "Unsupported window: #{name}"
+        end
+      end
+
+      def build_window(length)
+        denominator = length - 1
+        values = Array.new(length) { |k| yield(k, denominator).to_f }
+        Numo::SFloat.cast(values)
+      end
+      private_class_method :build_window
+    end
+  end
+end

data/lib/muze/display/specshow.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Muze
+  module Display
+    module_function
+
+    # @param data [Numo::NArray]
+    # @param sr [Integer]
+    # @param hop_length [Integer]
+    # @param x_axis [Symbol]
+    # @param y_axis [Symbol]
+    # @param output [String, nil]
+    # @return [String] SVG content
+    def specshow(data, sr: 22_050, hop_length: 512, x_axis: :time, y_axis: :linear, output: nil)
+      _ = [sr, hop_length]
+      validate_axis!(x_axis:, y_axis:)
+
+      matrix = Numo::SFloat.cast(data)
+      matrix = matrix.expand_dims(1) if matrix.ndim == 1
+      rows, cols = matrix.shape
+
+      width = 800.0
+      height = 400.0
+      cell_width = width / [cols, 1].max
+      cell_height = height / [rows, 1].max
+      min = matrix.min
+      max = matrix.max
+      range = [max - min, 1.0e-12].max
+
+      rects = []
+      rows.times do |row|
+        cols.times do |col|
+          normalized = (matrix[row, col] - min) / range
+          color = heat_color(normalized)
+          x = col * cell_width
+          y = (rows - row - 1) * cell_height
+          rects << "<rect x='#{x.round(3)}' y='#{y.round(3)}' width='#{cell_width.round(3)}' height='#{cell_height.round(3)}' fill='#{color}' />"
+        end
+      end
+
+      svg = [
+        "<svg xmlns='http://www.w3.org/2000/svg' width='#{width.to_i}' height='#{height.to_i}' viewBox='0 0 #{width.to_i} #{height.to_i}'>",
+        "<rect width='100%' height='100%' fill='#0b132b' />",
+        rects.join,
+        "</svg>"
+      ].join
+
+      File.write(output, svg) if output
+      svg
+    end
+
+    # @param y [Numo::SFloat, Array<Float>]
+    # @param sr [Integer]
+    # @param output [String, nil]
+    # @return [String] SVG content
+    def waveshow(y, sr: 22_050, output: nil)
+      _ = sr
+      signal = y.is_a?(Numo::NArray) ? y.to_a : Array(y)
+      width = 800.0
+      height = 240.0
+      middle = height / 2.0
+      step = [signal.length.to_f / width, 1.0].max
+
+      points = []
+      x = 0
+      while x < width
+        sample_index = [((x * step).floor), signal.length - 1].min
+        value = signal[sample_index] || 0.0
+        y_pos = middle - (value * middle * 0.9)
+        points << "#{x.round(2)},#{y_pos.round(2)}"
+        x += 1
+      end
+
+      svg = [
+        "<svg xmlns='http://www.w3.org/2000/svg' width='#{width.to_i}' height='#{height.to_i}' viewBox='0 0 #{width.to_i} #{height.to_i}'>",
+        "<rect width='100%' height='100%' fill='#111827' />",
+        "<polyline fill='none' stroke='#22d3ee' stroke-width='1.5' points='#{points.join(' ')}' />",
+        "</svg>"
+      ].join
+
+      File.write(output, svg) if output
+      svg
+    end
+
+    def validate_axis!(x_axis:, y_axis:)
+      raise Muze::ParameterError, "unsupported x_axis" unless %i[time frames].include?(x_axis)
+      raise Muze::ParameterError, "unsupported y_axis" unless %i[linear log mel hz].include?(y_axis)
+    end
+    private_class_method :validate_axis!
+
+    def heat_color(value)
+      clamped = [[value, 0.0].max, 1.0].min
+      r = (255 * clamped).to_i
+      g = (255 * (1.0 - (clamped - 0.5).abs * 2.0)).to_i
+      b = (255 * (1.0 - clamped)).to_i
+      format("rgb(%<r>d,%<g>d,%<b>d)", r:, g: [g, 0].max, b:)
+    end
+    private_class_method :heat_color
+  end
+end

data/lib/muze/effects/harmonic_percussive.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Muze
+  module Effects
+    module_function
+
+    # @param y [Numo::SFloat, Array<Float>]
+    # @param kernel_size [Integer]
+    # @param power [Float]
+    # @param margin [Float]
+    # @param n_fft [Integer]
+    # @param hop_length [Integer]
+    # @return [Array(Numo::SFloat, Numo::SFloat)] harmonic and percussive waveforms
+    def hpss(y, kernel_size: 31, power: 2.0, margin: 1.0, n_fft: 2048, hop_length: 512)
+      stft_matrix = Muze.stft(y, n_fft:, hop_length:)
+      magnitude, = Muze.magphase(stft_matrix)
+
+      harmonic_median = median_filter(magnitude, kernel_size, axis: 1)
+      percussive_median = median_filter(magnitude, kernel_size, axis: 0)
+
+      harmonic_weight = harmonic_median**power
+      percussive_weight = percussive_median**power
+
+      harmonic_mask = harmonic_weight / (harmonic_weight + (margin * percussive_weight) + 1.0e-12)
+      percussive_mask = percussive_weight / (percussive_weight + (margin * harmonic_weight) + 1.0e-12)
+
+      harmonic_stft = stft_matrix * harmonic_mask
+      percussive_stft = stft_matrix * percussive_mask
+
+      signal = y.is_a?(Numo::NArray) ? y : Numo::SFloat.cast(y)
+      harmonic = Muze.istft(harmonic_stft, hop_length:, length: signal.size)
+      percussive = Muze.istft(percussive_stft, hop_length:, length: signal.size)
+      [harmonic, percussive]
+    end
+
+    def median_filter(matrix, kernel_size, axis:)
+      half = kernel_size / 2
+      rows, cols = matrix.shape
+      output = Numo::SFloat.zeros(rows, cols)
+
+      rows.times do |row|
+        cols.times do |col|
+          values = []
+          if axis == 1
+            start_col = [col - half, 0].max
+            end_col = [col + half, cols - 1].min
+            (start_col..end_col).each { |index| values << matrix[row, index] }
+          else
+            start_row = [row - half, 0].max
+            end_row = [row + half, rows - 1].min
+            (start_row..end_row).each { |index| values << matrix[index, col] }
+          end
+
+          output[row, col] = Muze::Native.median1d(values)
+        end
+      end
+
+      output
+    end
+    private_class_method :median_filter
+  end
+end

data/lib/muze/effects/time_stretch.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module Muze
+  module Effects
+    module_function
+
+    # Keep fast path for short clips where phase vocoder overhead dominates.
+    MIN_PHASE_VOCODER_SAMPLES = 32_768
+
+    # @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?
+
+      signal = y.is_a?(Numo::NArray) ? Numo::SFloat.cast(y) : Numo::SFloat.cast(Array(y))
+      return signal if signal.empty? || rate == 1.0
+      return linear_time_stretch(signal.to_a, rate) if signal.size < MIN_PHASE_VOCODER_SAMPLES
+
+      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:)
+      target_length = [(signal.size / rate).round, 1].max
+
+      Muze::Core::STFT.istft(stretched_stft, hop_length:, center: true, length: target_length)
+    end
+
+    # @param y [Numo::SFloat, Array<Float>]
+    # @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)
+      return signal if n_steps.zero?
+
+      rate = 2.0**(-n_steps.to_f / 12.0)
+      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])
+    end
+
+    # @param y [Numo::SFloat, Array<Float>]
+    # @param top_db [Float]
+    # @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?
+
+      start_sample = indices.first
+      end_sample = indices.last + 1
+      [signal[start_sample...end_sample], [start_sample, end_sample]]
+    end
+
+    # @param signal_length [Integer]
+    # @return [Integer]
+    def phase_vocoder_fft_size(signal_length)
+      max_fft = [signal_length, 2048].min
+      fft_size = 1
+      fft_size *= 2 while (fft_size * 2) <= max_fft
+      [fft_size, 32].max
+    end
+    private_class_method :phase_vocoder_fft_size
+
+    # @param stft_matrix [Numo::DComplex]
+    # @param rate [Float]
+    # @param hop_length [Integer]
+    # @param n_fft [Integer]
+    # @return [Numo::DComplex]
+    def phase_vocoder(stft_matrix, rate:, hop_length:, n_fft:)
+      frequency_bins, frame_count = stft_matrix.shape
+      return stft_matrix if frame_count <= 1
+
+      time_steps = []
+      position = 0.0
+      max_frame = frame_count - 1
+      while position <= max_frame
+        time_steps << position
+        position += rate
+      end
+
+      stretched = Numo::DComplex.zeros(frequency_bins, time_steps.length)
+      phase_advance = Array.new(frequency_bins) { |bin| (2.0 * Math::PI * hop_length * bin) / n_fft }
+      phase_accumulator = Array.new(frequency_bins) { |bin| phase_of(stft_matrix[bin, 0]) }
+
+      time_steps.each_with_index do |step, output_index|
+        if output_index.zero?
+          frequency_bins.times { |bin| stretched[bin, output_index] = stft_matrix[bin, 0] }
+          next
+        end
+
+        frame_index = step.floor
+        next_frame_index = [frame_index + 1, frame_count - 1].min
+        alpha = step - frame_index
+
+        frequency_bins.times do |bin|
+          current = stft_matrix[bin, frame_index]
+          following = stft_matrix[bin, next_frame_index]
+          magnitude = ((1.0 - alpha) * current.abs) + (alpha * following.abs)
+
+          phase_delta = phase_of(following) - phase_of(current) - phase_advance[bin]
+          phase_delta = wrap_phase(phase_delta)
+          phase_accumulator[bin] += phase_advance[bin] + phase_delta
+
+          stretched[bin, output_index] = Complex.polar(magnitude, phase_accumulator[bin])
+        end
+      end
+
+      stretched
+    end
+    private_class_method :phase_vocoder
+
+    # @param complex_number [Complex]
+    # @return [Float]
+    def phase_of(complex_number)
+      Math.atan2(complex_number.imag, complex_number.real)
+    end
+    private_class_method :phase_of
+
+    # @param phase [Float]
+    # @return [Float]
+    def wrap_phase(phase)
+      ((phase + Math::PI) % (2.0 * Math::PI)) - Math::PI
+    end
+    private_class_method :wrap_phase
+
+    # @param signal [Array<Float>]
+    # @param rate [Float]
+    # @return [Numo::SFloat]
+    def linear_time_stretch(signal, rate)
+      target_length = [(signal.length / rate).round, 1].max
+      stretched = Array.new(target_length, 0.0)
+
+      target_length.times do |index|
+        source_position = index * rate
+        left = source_position.floor
+        right = [left + 1, signal.length - 1].min
+        alpha = source_position - left
+        stretched[index] = ((1.0 - alpha) * signal[left]) + (alpha * signal[right])
+      end
+
+      Numo::SFloat.cast(stretched)
+    end
+    private_class_method :linear_time_stretch
+
+    # Prefer sinc-quality resampling, then fall back to linear on failure.
+    # @param stretched [Numo::SFloat]
+    # @param target_size [Integer]
+    # @param preferred_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)
+      end
+
+      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)
+    end
+    private_class_method :resample_for_pitch_shift
+  end
+end

data/lib/muze/errors.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Muze
+  # Base error for all Muze failures.
+  class Error < StandardError; end
+
+  # Raised when audio file loading fails.
+  class AudioLoadError < Error; end
+
+  # Raised when unsupported audio format is used.
+  class UnsupportedFormatError < Error; end
+
+  # Raised when method parameters are invalid.
+  class ParameterError < Error; end
+
+  # Raised when optional runtime dependency is unavailable.
+  class DependencyError < Error; end
+end