muze 0.1.0 → 1.0.0

data/lib/muze/display/specshow.rb

@@ -11,41 +11,46 @@ module Muze
     # @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]
+    def specshow(data, sr: 22_050, hop_length: 512, x_axis: :time, y_axis: :linear, output: nil, width: 800, height: 400, cmap: :heat, vmin: nil, vmax: nil, fragment: false, render: :auto)
       validate_axis!(x_axis:, y_axis:)
+      raise Muze::ParameterError, "width and height must be positive" unless width.positive? && height.positive?
+      raise Muze::ParameterError, "sr and hop_length must be positive" unless sr.positive? && hop_length.positive?
+      raise Muze::ParameterError, "render must be :auto, :rects, or :image" unless %i[auto rects image].include?(render)
 
       matrix = Numo::SFloat.cast(data)
       matrix = matrix.expand_dims(1) if matrix.ndim == 1
+      validate_matrix!(matrix)
+      validate_color_bounds!(vmin:, vmax:)
+      render = image_render?(matrix, render:) ? :image : :rects
+      matrix = downsample_matrix(matrix, max_cells: 12_000) if render == :rects
       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
+      width = width.to_f
+      height = height.to_f
+      min = vmin || matrix.min
+      max = vmax || 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
+      content = render == :image ? image_element(matrix, width:, height:, min:, range:, cmap:) : rect_elements(matrix, rows:, cols:, width:, height:, min:, range:, cmap:, y_axis:, x_axis:, sr:, hop_length:)
 
-      svg = [
+      body = [
+        "<g data-x-axis='#{x_axis}' data-y-axis='#{y_axis}' data-sr='#{sr}' data-hop-length='#{hop_length}' data-render='#{render}'>",
+        content,
+        "</g>"
+      ].join
+
+      svg = if fragment
+              body
+            else
+              [
         "<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,
+        body,
         "</svg>"
-      ].join
+              ].join
+            end
 
-      File.write(output, svg) if output
+      write_output(output, svg) if output
       svg
     end
 
@@ -53,32 +58,68 @@ module Muze
     # @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
+    def waveshow(y, sr: 22_050, output: nil, width: 800, height: 240, normalize: true, channels: :overlay)
+      raise Muze::ParameterError, "width and height must be positive" unless width.positive? && height.positive?
+      raise Muze::ParameterError, "sr must be positive" unless sr.positive?
+      raise Muze::ParameterError, "normalize must be true or false" unless [true, false].include?(normalize)
+      raise Muze::ParameterError, "channels must be :overlay or :split" unless %i[overlay split].include?(channels)
+
+      signal = Muze::Core::Audio.validate_audio!(y, allow_empty: true).to_a
+      channel_data = signal.first.is_a?(Array) ? transpose_channels(signal) : [signal]
+      channel_data = channel_data.map { |channel| normalize ? normalize_wave(channel) : channel }
+      width = width.to_f
+      height = height.to_f
       middle = height / 2.0
-      step = [signal.length.to_f / width, 1.0].max
+      paths = channel_data.each_with_index.map do |channel, index|
+        top, lane_height = channel_lane(index, channel_data.length, height, channels:)
+        envelope_path(channel, width:, top:, height: lane_height)
+      end
 
-      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
+      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' />",
+        "<g data-sr='#{sr}' data-channels='#{channels}' transform='translate(0 #{middle * 0.0})'>",
+        paths.join,
+        "</g>",
+        "</svg>"
+      ].join
+
+      write_output(output, svg) if output
+      svg
+    end
+
+    # @return [String] SVG content
+    def onsetshow(onset_envelope, sr: 22_050, hop_length: 512, output: nil, width: 800, height: 160, normalize: true)
+      raise Muze::ParameterError, "width and height must be positive" unless width.positive? && height.positive?
+      raise Muze::ParameterError, "sr and hop_length must be positive" unless sr.positive? && hop_length.positive?
+      raise Muze::ParameterError, "normalize must be true or false" unless [true, false].include?(normalize)
+
+      envelope = Numo::SFloat.cast(onset_envelope).to_a.flatten
+      raise Muze::ParameterError, "onset envelope must contain only finite values" unless envelope.all? { |value| value.respond_to?(:finite?) && value.finite? }
+
+      peak = envelope.map(&:abs).max.to_f
+      values = normalize && peak.positive? ? envelope.map { |value| value / peak } : envelope
+      width = width.to_f
+      height = height.to_f
+      bar_width = width / [values.length, 1].max
+      bars = values.each_with_index.map do |value, index|
+        scaled = [[value, 0.0].max, 1.0].min
+        bar_height = scaled * height
+        x = index * bar_width
+        y = height - bar_height
+        "<rect x='#{x.round(3)}' y='#{y.round(3)}' width='#{[bar_width, 0.1].max.round(3)}' height='#{bar_height.round(3)}' fill='#22d3ee' />"
       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(' ')}' />",
+        "<g data-kind='onset' data-sr='#{sr}' data-hop-length='#{hop_length}'>",
+        bars.join,
+        "</g>",
         "</svg>"
       ].join
 
-      File.write(output, svg) if output
+      write_output(output, svg) if output
       svg
     end
 
@@ -88,13 +129,238 @@ module Muze
     end
     private_class_method :validate_axis!
 
-    def heat_color(value)
+    def validate_matrix!(matrix)
+      return if matrix.to_a.flatten.all? { |value| value.respond_to?(:finite?) && value.finite? }
+
+      raise Muze::ParameterError, "data must contain only finite numeric values"
+    end
+    private_class_method :validate_matrix!
+
+    def validate_color_bounds!(vmin:, vmax:)
+      [[:vmin, vmin], [:vmax, vmax]].each do |name, value|
+        next if value.nil? || (value.respond_to?(:finite?) && value.finite?)
+
+        raise Muze::ParameterError, "#{name} must be finite"
+      end
+      return unless vmin && vmax && vmin > vmax
+
+      raise Muze::ParameterError, "vmin must be <= vmax"
+    end
+    private_class_method :validate_color_bounds!
+
+    def color_for(value, cmap:)
+      case cmap
+      when :heat then rgb_string(heat_rgb(value))
+      when :gray, :grey then rgb_string(gray_rgb(value))
+      when :magma then rgb_string(magma_rgb(value))
+      else
+        raise Muze::ParameterError, "unsupported cmap"
+      end
+    end
+    private_class_method :color_for
+
+    def color_tuple_for(value, cmap:)
+      case cmap
+      when :heat then heat_rgb(value)
+      when :gray, :grey then gray_rgb(value)
+      when :magma then magma_rgb(value)
+      else
+        raise Muze::ParameterError, "unsupported cmap"
+      end
+    end
+    private_class_method :color_tuple_for
+
+    def rgb_string(tuple)
+      format("rgb(%<r>d,%<g>d,%<b>d)", r: tuple[0], g: tuple[1], b: tuple[2])
+    end
+    private_class_method :rgb_string
+
+    def heat_rgb(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:)
+      [r, [g, 0].max, b]
+    end
+    private_class_method :heat_rgb
+
+    def gray_rgb(value)
+      level = (255 * [[value, 0.0].max, 1.0].min).to_i
+      [level, level, level]
+    end
+    private_class_method :gray_rgb
+
+    def magma_rgb(value)
+      clamped = [[value, 0.0].max, 1.0].min
+      r = (252 * clamped).to_i
+      g = (80 * (clamped**1.5)).to_i
+      b = (120 * (1.0 - clamped) + 40).to_i
+      [r, g, b]
+    end
+    private_class_method :magma_rgb
+
+    def rect_elements(matrix, rows:, cols:, width:, height:, min:, range:, cmap:, y_axis:, x_axis:, sr:, hop_length:)
+      rects = []
+      rows.times do |row|
+        y_top = y_position(row + 1, rows, height, y_axis:, sr:)
+        y_bottom = y_position(row, rows, height, y_axis:, sr:)
+        cell_height = [y_bottom - y_top, 0.1].max
+        cols.times do |col|
+          normalized = (matrix[row, col] - min) / range
+          color = color_for(normalized, cmap:)
+          x = x_position(col, cols, width, hop_length:, sr:, x_axis:)
+          next_x = x_position(col + 1, cols, width, hop_length:, sr:, x_axis:)
+          rect_width = [next_x - x, 0.1].max
+          rects << "<rect x='#{x.round(3)}' y='#{y_top.round(3)}' width='#{rect_width.round(3)}' height='#{cell_height.round(3)}' fill='#{color}' />"
+        end
+      end
+      rects.join
+    end
+    private_class_method :rect_elements
+
+    def image_render?(matrix, render:)
+      return true if render == :image
+      return false if render == :rects
+
+      matrix.shape.reduce(:*) > 12_000
+    end
+    private_class_method :image_render?
+
+    def image_element(matrix, width:, height:, min:, range:, cmap:)
+      rows, cols = matrix.shape
+      href = "data:image/bmp;base64,#{base64_encode(bmp_bytes(matrix, min:, range:, cmap:))}"
+      "<image x='0' y='0' width='#{width.to_i}' height='#{height.to_i}' preserveAspectRatio='none' href='#{href}' />"
+    end
+    private_class_method :image_element
+
+    def bmp_bytes(matrix, min:, range:, cmap:)
+      rows, cols = matrix.shape
+      row_stride = ((cols * 3) + 3) & ~3
+      pixel_bytes = row_stride * rows
+      file_size = 54 + pixel_bytes
+      header = +"BM".b
+      header << [file_size, 0, 54].pack("V V V")
+      header << [40, cols, rows, 1, 24, 0, pixel_bytes, 2835, 2835, 0, 0].pack("V V V v v V V V V V V")
+      padding = "\x00".b * (row_stride - (cols * 3))
+      pixels = +""
+
+      (rows - 1).downto(0) do |row|
+        cols.times do |col|
+          r, g, b = color_tuple_for((matrix[row, col] - min) / range, cmap:)
+          pixels << [b, g, r].pack("C3")
+        end
+        pixels << padding
+      end
+
+      header << pixels
+    end
+    private_class_method :bmp_bytes
+
+    BASE64_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"
+
+    def base64_encode(bytes)
+      binary = bytes.b
+      output = +""
+      index = 0
+      while index < binary.bytesize
+        chunk = binary.byteslice(index, 3).bytes
+        pad = 3 - chunk.length
+        chunk += [0] * pad
+        value = (chunk[0] << 16) | (chunk[1] << 8) | chunk[2]
+        output << BASE64_ALPHABET[(value >> 18) & 0x3f]
+        output << BASE64_ALPHABET[(value >> 12) & 0x3f]
+        output << (pad >= 2 ? "=" : BASE64_ALPHABET[(value >> 6) & 0x3f])
+        output << (pad >= 1 ? "=" : BASE64_ALPHABET[value & 0x3f])
+        index += 3
+      end
+      output
+    end
+    private_class_method :base64_encode
+
+    def x_position(col, cols, width, hop_length:, sr:, x_axis:)
+      return col * width / [cols, 1].max if x_axis == :frames
+
+      total_time = [cols * hop_length.to_f / sr, 1.0e-12].max
+      (col * hop_length.to_f / sr) * width / total_time
+    end
+    private_class_method :x_position
+
+    def y_position(row, rows, height, y_axis:, sr:)
+      normalized = case y_axis
+                   when :linear, :hz
+                     row.to_f / [rows, 1].max
+                   when :mel
+                     hz = row * (sr / 2.0) / [rows, 1].max
+                     Muze::Filters.hz_to_mel(hz) / Muze::Filters.hz_to_mel(sr / 2.0)
+                   when :log
+                     Math.log10(1.0 + (9.0 * row / [rows, 1].max.to_f))
+                   end
+      height - (normalized * height)
+    end
+    private_class_method :y_position
+
+    def downsample_matrix(matrix, max_cells:)
+      rows, cols = matrix.shape
+      return matrix if rows * cols <= max_cells
+
+      col_step = [(rows * cols / max_cells.to_f).ceil, 1].max
+      selected_cols = (0...cols).step(col_step).to_a
+      output = Numo::SFloat.zeros(rows, selected_cols.length)
+      selected_cols.each_with_index { |col, index| output[true, index] = matrix[true, col] }
+      output
+    end
+    private_class_method :downsample_matrix
+
+    def transpose_channels(samples)
+      channel_count = samples.first.length
+      Array.new(channel_count) { |channel| samples.map { |frame| frame[channel] } }
+    end
+    private_class_method :transpose_channels
+
+    def normalize_wave(channel)
+      peak = channel.map(&:abs).max || 0.0
+      return channel if peak <= 0.0
+
+      channel.map { |value| value / peak }
+    end
+    private_class_method :normalize_wave
+
+    def channel_lane(index, count, height, channels:)
+      return [0.0, height] if channels == :overlay
+
+      lane_height = height / count
+      [index * lane_height, lane_height]
+    end
+    private_class_method :channel_lane
+
+    def envelope_path(channel, width:, top:, height:)
+      middle = top + (height / 2.0)
+      step = [channel.length.to_f / width, 1.0].max
+      segments = []
+
+      x = 0
+      while x < width
+        start_index = (x * step).floor
+        end_index = [((x + 1) * step).ceil, channel.length].min
+        window = channel[start_index...end_index] || [0.0]
+        min = window.min || 0.0
+        max = window.max || 0.0
+        y_min = middle - (min * height * 0.45)
+        y_max = middle - (max * height * 0.45)
+        segments << "M #{x.round(2)} #{y_min.round(2)} L #{x.round(2)} #{y_max.round(2)}"
+        x += 1
+      end
+
+      "<path d='#{segments.join(' ')}' fill='none' stroke='#22d3ee' stroke-width='1.2' />"
+    end
+    private_class_method :envelope_path
+
+    def write_output(output, svg)
+      path = output.respond_to?(:to_path) ? output.to_path : output
+      File.write(path, svg)
+    rescue SystemCallError => e
+      raise Muze::Error, "Failed to write SVG output #{path}: #{e.message}"
     end
-    private_class_method :heat_color
+    private_class_method :write_output
   end
 end

data/lib/muze/effects/harmonic_percussive.rb

@@ -11,8 +11,20 @@ module Muze
     # @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:)
+    def hpss(y, kernel_size: 31, power: 2.0, margin: 1.0, n_fft: 2048, hop_length: 512, return_masks: false)
+      validate_hpss_params!(kernel_size:, power:, margin:)
+      raise Muze::ParameterError, "return_masks must be true or false" unless [true, false].include?(return_masks)
+
+      signal = Muze::Core::Audio.validate_audio!(y, allow_empty: true)
+      return hpss_channels(signal, kernel_size:, power:, margin:, n_fft:, hop_length:, return_masks:) if signal.ndim == 2
+
+      hpss_mono(signal, kernel_size:, power:, margin:, n_fft:, hop_length:, return_masks:)
+    end
+
+    def hpss_mono(signal, kernel_size:, power:, margin:, n_fft:, hop_length:, return_masks:)
+      signal = Numo::SFloat.cast(signal)
+
+      stft_matrix = Muze.stft(signal, n_fft:, hop_length:)
       magnitude, = Muze.magphase(stft_matrix)
 
       harmonic_median = median_filter(magnitude, kernel_size, axis: 1)
@@ -20,43 +32,96 @@ module Muze
 
       harmonic_weight = harmonic_median**power
       percussive_weight = percussive_median**power
+      harmonic_margin, percussive_margin = Array(margin)
+      harmonic_margin ||= margin
+      percussive_margin ||= harmonic_margin
 
-      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_mask = soft_mask(harmonic_weight, harmonic_weight + (harmonic_margin * percussive_weight), power: 1.0)
+      percussive_mask = soft_mask(percussive_weight, percussive_weight + (percussive_margin * harmonic_weight), power: 1.0)
 
       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)
+      return [harmonic, percussive, harmonic_mask, percussive_mask] if return_masks
+
+      [harmonic, percussive]
+    end
+    private_class_method :hpss_mono
+
+    def hpss_channels(signal, kernel_size:, power:, margin:, n_fft:, hop_length:, return_masks:)
+      frames, channels = signal.shape
+      harmonic = Numo::SFloat.zeros(frames, channels)
+      percussive = Numo::SFloat.zeros(frames, channels)
+      harmonic_masks = []
+      percussive_masks = []
+
+      channels.times do |channel|
+        result = hpss_mono(
+          signal[true, channel],
+          kernel_size:,
+          power:,
+          margin:,
+          n_fft:,
+          hop_length:,
+          return_masks: true
+        )
+        harmonic[true, channel] = result[0]
+        percussive[true, channel] = result[1]
+        harmonic_masks << result[2]
+        percussive_masks << result[3]
+      end
+
+      return [harmonic, percussive, harmonic_masks, percussive_masks] if return_masks
+
       [harmonic, percussive]
     end
+    private_class_method :hpss_channels
+
+    def validate_hpss_params!(kernel_size:, power:, margin:)
+      raise Muze::ParameterError, "kernel_size must be a positive odd integer" unless kernel_size.is_a?(Integer) && kernel_size.positive? && kernel_size.odd?
+      raise Muze::ParameterError, "power must be positive" unless power.positive?
+
+      margins = Array(margin)
+      raise Muze::ParameterError, "margin must be positive or [harmonic_margin, percussive_margin]" unless [1, 2].include?(margins.length)
+      return if margins.all? { |value| value.respond_to?(:positive?) && value.positive? }
+
+      raise Muze::ParameterError, "margin must be positive"
+    end
+    private_class_method :validate_hpss_params!
+
+    def soft_mask(numerator, denominator, power:)
+      powered_numerator = numerator**power
+      powered_denominator = denominator**power
+      powered_numerator / (powered_denominator + 1.0e-12)
+    end
+    private_class_method :soft_mask
 
     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|
+      if axis == 1
+        rows.times do |row|
+          values = cols.times.map { |col| matrix[row, col] }
+          sliding_median(values, half).each_with_index { |value, col| output[row, col] = value }
+        end
+      else
         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)
+          values = rows.times.map { |row| matrix[row, col] }
+          sliding_median(values, half).each_with_index { |value, row| output[row, col] = value }
         end
       end
 
       output
     end
     private_class_method :median_filter
+
+    def sliding_median(values, half)
+      Muze::Native.median_filter1d(values, half)
+    end
+    private_class_method :sliding_median
   end
 end

data/lib/muze/effects/streaming.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Muze
+  module Effects
+    module_function
+
+    def time_stretch_stream(chunks, rate: 1.0, n_fft: nil, hop_length: nil, method: :phase_vocoder, phase_lock: false, force_phase_vocoder: false, overlap: 2048)
+      return enum_for(__method__, chunks, rate:, n_fft:, hop_length:, method:, phase_lock:, force_phase_vocoder:, overlap:) unless block_given?
+
+      validate_positive_number!(rate, "rate")
+      validate_stream_overlap!(overlap)
+      stream_effect_chunks(chunks, overlap:) do |working, prefix_frames|
+        stretched = time_stretch(working, rate:, n_fft:, hop_length:, method:, phase_lock:, force_phase_vocoder:)
+        drop = [(prefix_frames / rate).round, audio_frame_count(stretched)].min
+        yield drop_audio_frames(stretched, drop)
+      end
+      nil
+    end
+
+    def pitch_shift_stream(chunks, sr: 22_050, n_steps: 0, bins_per_octave: 12, res_type: :auto, normalize: false, clip: nil, overlap: 2048)
+      return enum_for(__method__, chunks, sr:, n_steps:, bins_per_octave:, res_type:, normalize:, clip:, overlap:) unless block_given?
+
+      validate_stream_overlap!(overlap)
+      stream_effect_chunks(chunks, overlap:) do |working, prefix_frames|
+        shifted = pitch_shift(working, sr:, n_steps:, bins_per_octave:, res_type:, normalize:, clip:)
+        yield drop_audio_frames(shifted, prefix_frames)
+      end
+      nil
+    end
+
+    def hpss_stream(chunks, kernel_size: 31, power: 2.0, margin: 1.0, n_fft: 2048, hop_length: 512, overlap: n_fft)
+      return enum_for(__method__, chunks, kernel_size:, power:, margin:, n_fft:, hop_length:, overlap:) unless block_given?
+
+      validate_stream_overlap!(overlap)
+      stream_effect_chunks(chunks, overlap:) do |working, prefix_frames|
+        harmonic, percussive = hpss(working, kernel_size:, power:, margin:, n_fft:, hop_length:)
+        yield drop_audio_frames(harmonic, prefix_frames), drop_audio_frames(percussive, prefix_frames)
+      end
+      nil
+    end
+
+    def stream_effect_chunks(chunks, overlap:)
+      tail = nil
+      chunks.each do |chunk|
+        signal = Muze::Core::Audio.validate_audio!(chunk, allow_empty: true)
+        next if signal.empty?
+
+        working = tail ? concat_audio(tail, signal) : signal
+        prefix_frames = tail ? audio_frame_count(tail) : 0
+        yield working, prefix_frames
+        tail = overlap.positive? ? take_audio_tail(working, overlap) : nil
+      end
+    end
+    private_class_method :stream_effect_chunks
+
+    def audio_frame_count(signal)
+      signal.ndim == 2 ? signal.shape[0] : signal.size
+    end
+    private_class_method :audio_frame_count
+
+    def concat_audio(left, right)
+      return right if left.nil? || left.empty?
+      return left if right.empty?
+
+      if left.ndim == 2 || right.ndim == 2
+        raise Muze::ParameterError, "chunk channel counts must match" unless left.ndim == 2 && right.ndim == 2 && left.shape[1] == right.shape[1]
+
+        output = Numo::SFloat.zeros(left.shape[0] + right.shape[0], left.shape[1])
+        output[0...left.shape[0], true] = left
+        output[left.shape[0]...(left.shape[0] + right.shape[0]), true] = right
+        return output
+      end
+
+      Numo::SFloat.cast(left.to_a + right.to_a)
+    end
+    private_class_method :concat_audio
+
+    def take_audio_tail(signal, count)
+      frames = audio_frame_count(signal)
+      start = [frames - count, 0].max
+      drop_audio_frames(signal, start)
+    end
+    private_class_method :take_audio_tail
+
+    def drop_audio_frames(signal, count)
+      frames = audio_frame_count(signal)
+      start = [[count, 0].max, frames].min
+      return signal[start...frames, true] if signal.ndim == 2
+
+      signal[start...frames]
+    end
+    private_class_method :drop_audio_frames
+
+    def validate_stream_overlap!(overlap)
+      return if overlap.is_a?(Integer) && overlap >= 0
+
+      raise Muze::ParameterError, "overlap must be a non-negative integer"
+    end
+    private_class_method :validate_stream_overlap!
+  end
+end