wavify 0.1.0 → 0.2.0

data/lib/wavify/dsp/effects/effect_base.rb

@@ -5,12 +5,14 @@ module Wavify
     module Effects
       # Base class for sample-by-sample effects with runtime channel state.
       class EffectBase
+        TAIL_CHUNK_FRAMES = DSP::Processor::TAIL_CHUNK_FRAMES
+
         # Applies the effect to a sample buffer.
         #
         # @param buffer [Wavify::Core::SampleBuffer]
         # @return [Wavify::Core::SampleBuffer]
         def apply(buffer)
-          process(buffer)
+          DSP::Processor.render(self, buffer)
         end
 
         def process(buffer)
@@ -27,12 +29,62 @@ module Wavify
           output = Array.new(float_buffer.samples.length)
           float_buffer.samples.each_with_index do |sample, sample_index|
             channel = sample_index % @runtime_channels
-            output[sample_index] = process_sample(sample, channel: channel, sample_rate: @runtime_sample_rate).clamp(-1.0, 1.0)
+            output[sample_index] = process_sample(sample, channel: channel, sample_rate: @runtime_sample_rate)
           end
 
           Core::SampleBuffer.new(output, float_format).convert(buffer.format)
         end
 
+        # Emits effect tail after input has ended.
+        #
+        # @param format [Wavify::Core::Format, nil] output format for tail chunks
+        # @return [Enumerator<Wavify::Core::SampleBuffer>, nil]
+        def flush(format: nil)
+          return nil unless runtime_prepared?
+
+          frames = tail_frame_count
+          return nil if frames.zero?
+
+          target_format = format || Core::Format.new(
+            channels: @runtime_channels,
+            sample_rate: @runtime_sample_rate,
+            bit_depth: 32,
+            sample_format: :float
+          )
+          runtime_format = Core::Format.new(
+            channels: @runtime_channels,
+            sample_rate: @runtime_sample_rate,
+            bit_depth: 32,
+            sample_format: :float
+          )
+          Enumerator.new do |yielder|
+            remaining = frames
+            while remaining.positive?
+              chunk_frames = [remaining, TAIL_CHUNK_FRAMES].min
+              silence = Core::SampleBuffer.new(Array.new(chunk_frames * @runtime_channels, 0.0), runtime_format)
+              yielder << process(silence).convert(target_format)
+              remaining -= chunk_frames
+            end
+          ensure
+            reset
+          end
+        end
+
+        # @return [Float] tail duration in seconds emitted by {#flush}
+        def tail_duration
+          0.0
+        end
+
+        # @return [Float] processing latency in seconds
+        def latency
+          0.0
+        end
+
+        # @return [Float] lookahead duration in seconds
+        def lookahead
+          0.0
+        end
+
         def process_sample(_sample, channel:, sample_rate:)
           raise NotImplementedError
         end
@@ -47,8 +99,23 @@ module Wavify
           self
         end
 
+        # Builds an independent runtime instance for offline rendering.
+        def build_runtime
+          dup.reset
+        end
+
         private
 
+        def runtime_prepared?
+          @runtime_sample_rate && @runtime_channels
+        end
+
+        def tail_frame_count
+          return 0 unless tail_duration.positive?
+
+          (@runtime_sample_rate * tail_duration).ceil
+        end
+
         def prepare_runtime_if_needed!(sample_rate:, channels:)
           return if @runtime_sample_rate == sample_rate && @runtime_channels == channels
 

data/lib/wavify/dsp/effects/effect_chain.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Wavify
+  module DSP
+    module Effects
+      # Processor that applies a fixed list of effects in sequence.
+      class EffectChain
+        attr_reader :effects
+
+        # @param effects [Array<#process,#call,#apply>]
+        def initialize(effects)
+          raise InvalidParameterError, "effects must be an Array" unless effects.is_a?(Array)
+
+          @effects = effects.map { |effect| validate_effect!(effect) }.freeze
+        end
+
+        # @param buffer [Wavify::Core::SampleBuffer]
+        # @return [Wavify::Core::SampleBuffer]
+        def process(buffer)
+          raise InvalidParameterError, "buffer must be Core::SampleBuffer" unless buffer.is_a?(Core::SampleBuffer)
+
+          original_format = buffer.format
+          float_format = original_format.with(sample_format: :float, bit_depth: 32)
+          processed = @effects.reduce(buffer.convert(float_format)) { |current, effect| process_effect(effect, current) }
+          processed.convert(original_format)
+        end
+
+        # Applies every effect using its offline entrypoint when available.
+        def apply(buffer)
+          raise InvalidParameterError, "buffer must be Core::SampleBuffer" unless buffer.is_a?(Core::SampleBuffer)
+
+          DSP::Processor.render(self, buffer)
+        end
+
+        # Flushes effect tails through every downstream processor.
+        def flush(format: nil)
+          Enumerator.new do |yielder|
+            @effects.each_with_index do |effect, index|
+              DSP::Processor.flush(effect, format: format).each do |tail|
+                next unless tail.sample_frame_count.positive?
+
+                processed = @effects.drop(index + 1).reduce(tail) do |current, downstream|
+                  process_effect(downstream, current)
+                end
+                yielder << processed
+              end
+            end
+          end
+        end
+
+        # @return [EffectChain] self
+        def reset
+          @effects.each { |effect| effect.reset if effect.respond_to?(:reset) }
+          self
+        end
+
+        # Builds a chain whose processors do not share runtime state.
+        def build_runtime
+          runtime_effects = @effects.map { |effect| DSP::Processor.build_runtime(effect) }
+          runtime = dup
+          runtime.instance_variable_set(:@effects, runtime_effects.freeze)
+          runtime.reset
+        end
+
+        # @return [Float]
+        def latency
+          @effects.sum { |effect| DSP::Processor.duration(effect, :latency) }
+        end
+
+        # @return [Float]
+        def lookahead
+          @effects.sum { |effect| DSP::Processor.duration(effect, :lookahead) }
+        end
+
+        # @return [Float]
+        def tail_duration
+          @effects.sum { |effect| DSP::Processor.duration(effect, :tail_duration) }
+        end
+
+        private
+
+        def process_effect(effect, buffer)
+          DSP::Processor.process(effect, buffer)
+        end
+
+        def validate_effect!(effect)
+          return effect if effect.respond_to?(:process) || effect.respond_to?(:call) || effect.respond_to?(:apply)
+
+          raise InvalidParameterError, "chain effects must respond to :process, :call, or :apply"
+        end
+      end
+    end
+  end
+end

data/lib/wavify/dsp/effects/envelope_controlled_effect.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Wavify
+  module DSP
+    module Effects
+      # Peak envelope detector with attack, hold, and release timing.
+      class EnvelopeFollower
+        def initialize(attack:, hold:, release:)
+          @attack = validate_time!(attack, :attack)
+          @hold = validate_time!(hold, :hold)
+          @release = validate_time!(release, :release)
+          reset
+        end
+
+        def prepare(sample_rate)
+          @attack_coefficient = time_coefficient(@attack, sample_rate)
+          @release_coefficient = time_coefficient(@release, sample_rate)
+          @hold_frames = (@hold * sample_rate).round
+          reset
+        end
+
+        def follow(level)
+          if level > @envelope
+            @envelope = level + (@attack_coefficient * (@envelope - level))
+            @hold_remaining = @hold_frames
+          elsif @hold_remaining.positive?
+            @hold_remaining -= 1
+          else
+            @envelope = level + (@release_coefficient * (@envelope - level))
+          end
+          @envelope
+        end
+
+        def reset
+          @envelope = 0.0
+          @hold_remaining = 0
+          self
+        end
+
+        private
+
+        def time_coefficient(seconds, sample_rate)
+          return 0.0 if seconds.zero?
+
+          Math.exp(-1.0 / (seconds * sample_rate))
+        end
+
+        def validate_time!(value, name)
+          unless value.is_a?(Numeric) && value.respond_to?(:finite?) && value.finite? && value >= 0.0
+            raise InvalidParameterError, "#{name} must be a non-negative finite Numeric"
+          end
+
+          value.to_f
+        end
+      end
+      private_constant :EnvelopeFollower
+
+      # Shared frame-linked processing for gate and expansion effects.
+      module EnvelopeControlledEffect
+        def process(buffer)
+          raise InvalidParameterError, "buffer must be Core::SampleBuffer" unless buffer.is_a?(Core::SampleBuffer)
+
+          float_format = buffer.format.with(sample_format: :float, bit_depth: 32)
+          float_buffer = buffer.convert(float_format)
+          prepare_runtime_if_needed!(sample_rate: float_format.sample_rate, channels: float_format.channels)
+
+          output = []
+          float_buffer.samples.each_slice(@runtime_channels) do |frame|
+            envelope = @envelope_follower.follow(frame.reduce(0.0) { |peak, sample| [peak, sample.abs].max })
+            gain = gain_for_envelope(envelope)
+            output.concat(frame.map { |sample| sample * gain })
+          end
+          Core::SampleBuffer.new(output, float_format).convert(buffer.format)
+        end
+
+        def process_sample(_sample, channel:, sample_rate:)
+          raise NotImplementedError, "#{self.class} requires frame-aware #apply or #process"
+        end
+
+        private
+
+        def prepare_runtime_state(sample_rate:, channels:)
+          @envelope_follower.prepare(sample_rate)
+        end
+
+        def reset_runtime_state
+          @envelope_follower.reset
+        end
+      end
+      private_constant :EnvelopeControlledEffect
+    end
+  end
+end

data/lib/wavify/dsp/effects/eq.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require_relative "../filter"
+
+module Wavify
+  module DSP
+    module Effects
+      # Ordered chain of biquad filters for simple EQ curves.
+      class EQ
+        def initialize(*filters)
+          @filters = filters.flatten
+          raise InvalidParameterError, "at least one filter is required" if @filters.empty?
+
+          @filters.each do |filter|
+            raise InvalidParameterError, "filters must respond to :apply or :process" unless filter.respond_to?(:apply) || filter.respond_to?(:process)
+          end
+          @runtime_format = nil
+        end
+
+        # Convenience constructor for common tone-shaping bands.
+        #
+        # @param highpass [Numeric, nil]
+        # @param lowpass [Numeric, nil]
+        # @param presence [Hash, nil] `{ cutoff:, q:, gain_db: }`
+        # @return [EQ]
+        def self.simple(highpass: nil, lowpass: nil, presence: nil)
+          filters = []
+          filters << Wavify::DSP::Filter.highpass(cutoff: highpass) if highpass
+          filters << Wavify::DSP::Filter.lowpass(cutoff: lowpass) if lowpass
+          filters << Wavify::DSP::Filter.peaking(**presence) if presence
+          new(filters)
+        end
+
+        # Applies all filters in order.
+        #
+        # @param buffer [Wavify::Core::SampleBuffer]
+        # @return [Wavify::Core::SampleBuffer]
+        def process(buffer)
+          raise InvalidParameterError, "buffer must be Core::SampleBuffer" unless buffer.is_a?(Core::SampleBuffer)
+
+          original_format = buffer.format
+          float_format = original_format.with(sample_format: :float, bit_depth: 32)
+          processed = @filters.reduce(buffer.convert(float_format)) do |current, filter|
+            DSP::Processor.process(filter, current)
+          end.convert(original_format)
+          @runtime_format = buffer.format
+          processed
+        end
+
+        def apply(buffer)
+          DSP::Processor.render(self, buffer)
+        end
+
+        # Resets stateful filters in the chain.
+        #
+        # @return [EQ] self
+        def reset
+          @filters.each { |filter| filter.reset if filter.respond_to?(:reset) }
+          @runtime_format = nil
+          self
+        end
+
+        def build_runtime
+          self.class.new(@filters.map { |filter| DSP::Processor.build_runtime(filter) })
+        end
+
+        # Drains the filters' IIR state through the complete EQ chain.
+        def flush(format: nil)
+          return nil unless @runtime_format
+
+          Enumerator.new do |yielder|
+            @filters.each_with_index do |filter, index|
+              DSP::Processor.flush(filter, format: format || @runtime_format).each do |tail|
+                processed = @filters.drop(index + 1).reduce(tail) do |current, downstream|
+                  DSP::Processor.process(downstream, current)
+                end
+                yielder << processed
+              end
+            end
+          ensure
+            @runtime_format = nil
+          end
+        end
+
+        # @return [Float]
+        def latency
+          @filters.sum { |filter| DSP::Processor.duration(filter, :latency) }
+        end
+
+        # @return [Float]
+        def lookahead
+          @filters.sum { |filter| DSP::Processor.duration(filter, :lookahead) }
+        end
+
+        # @return [Float]
+        def tail_duration
+          @filters.sum { |filter| DSP::Processor.duration(filter, :tail_duration) }
+        end
+      end
+    end
+  end
+end

data/lib/wavify/dsp/effects/expander.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Wavify
+  module DSP
+    module Effects
+      # Downward expander that reduces low-level material below a threshold.
+      class Expander < EffectBase
+        include EnvelopeControlledEffect
+
+        def initialize(threshold: -40.0, ratio: 2.0, floor: -80.0, attack: 0.001, hold: 0.02, release: 0.05,
+                       gain_attack: 0.001, gain_release: 0.05)
+          super()
+          @threshold_db = validate_dbfs!(threshold, :threshold)
+          @ratio = validate_ratio!(ratio)
+          @floor_db = validate_dbfs!(floor, :floor)
+          @floor_gain = db_to_amplitude(@floor_db)
+          @gain_attack = validate_time!(gain_attack, :gain_attack)
+          @gain_release = validate_time!(gain_release, :gain_release)
+          @envelope_follower = EnvelopeFollower.new(attack: attack, hold: hold, release: release)
+          reset
+        end
+
+        private
+
+        def gain_for_envelope(envelope)
+          target = target_gain_for_envelope(envelope)
+          coefficient = target > @gain ? @gain_attack_coefficient : @gain_release_coefficient
+          @gain = target + (coefficient * (@gain - target))
+        end
+
+        def target_gain_for_envelope(envelope)
+          return 1.0 if envelope <= 0.0
+
+          input_db = 20.0 * Math.log10(envelope)
+          return 1.0 if input_db >= @threshold_db
+
+          gain_reduction_db = (@threshold_db - input_db) * (@ratio - 1.0)
+          [db_to_amplitude(-gain_reduction_db), @floor_gain].max
+        end
+
+        def prepare_runtime_state(sample_rate:, channels:)
+          super
+          @gain_attack_coefficient = time_coefficient(@gain_attack, sample_rate)
+          @gain_release_coefficient = time_coefficient(@gain_release, sample_rate)
+        end
+
+        def reset_runtime_state
+          super
+          @gain = 1.0
+          @gain_attack_coefficient = nil
+          @gain_release_coefficient = nil
+        end
+
+        def validate_dbfs!(value, name)
+          unless value.is_a?(Numeric) && value.respond_to?(:finite?) && value.finite? && value <= 0.0
+            raise InvalidParameterError, "#{name} must be a finite Numeric <= 0 dBFS"
+          end
+
+          value.to_f
+        end
+
+        def validate_ratio!(value)
+          unless value.is_a?(Numeric) && value.respond_to?(:finite?) && value.finite? && value >= 1.0
+            raise InvalidParameterError, "ratio must be a finite Numeric >= 1.0"
+          end
+
+          value.to_f
+        end
+
+        def validate_time!(value, name)
+          unless value.is_a?(Numeric) && value.respond_to?(:finite?) && value.finite? && value >= 0.0
+            raise InvalidParameterError, "#{name} must be a non-negative finite Numeric"
+          end
+
+          value.to_f
+        end
+
+        def time_coefficient(seconds, sample_rate)
+          return 0.0 if seconds.zero?
+
+          Math.exp(-1.0 / (seconds * sample_rate))
+        end
+
+        def db_to_amplitude(db)
+          10.0**(db / 20.0)
+        end
+      end
+    end
+  end
+end

data/lib/wavify/dsp/effects/flanger.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Wavify
+  module DSP
+    module Effects
+      # Short modulated comb delay effect.
+      class Flanger < EffectBase
+        MAX_DELAY_SECONDS = 0.006
+        TAIL_AMPLITUDE = 1.0e-6
+
+        def initialize(rate: 0.5, depth: 0.7, feedback: 0.35, mix: 0.5)
+          super()
+          @rate = validate_positive!(rate, :rate)
+          @depth = validate_unit!(depth, :depth)
+          @feedback = validate_feedback!(feedback)
+          @mix = validate_unit!(mix, :mix)
+          reset
+        end
+
+        def process_sample(sample, channel:, sample_rate:)
+          dry = sample.to_f
+          line = @delay_lines.fetch(channel)
+          write_index = @write_indices.fetch(channel)
+
+          mod = @lfo.value_at(channel_phase_offset(channel))
+          delay_samples = @base_delay_samples + (@depth_delay_samples * ((mod + 1.0) / 2.0))
+          wet = read_fractional_delay(line, write_index, delay_samples)
+
+          line[write_index] = dry + (wet * @feedback)
+          @write_indices[channel] = (write_index + 1) % line.length
+          @lfo.next_value if channel == (@runtime_channels - 1)
+
+          (dry * (1.0 - @mix)) + (wet * @mix)
+        end
+
+        def tail_duration
+          return 0.0 if @mix.zero?
+
+          repetitions = if @feedback.zero?
+                          1
+                        else
+                          (Math.log(TAIL_AMPLITUDE) / Math.log(@feedback.abs)).ceil
+                        end
+          MAX_DELAY_SECONDS * [repetitions, 1].max
+        end
+
+        def latency
+          @mix >= 1.0 ? MAX_DELAY_SECONDS : 0.0
+        end
+
+        private
+
+        def prepare_runtime_state(sample_rate:, channels:)
+          @base_delay_samples = [(sample_rate * 0.0015).round, 1].max
+          @depth_delay_samples = (sample_rate * (MAX_DELAY_SECONDS - 0.0015) * @depth).to_f
+          line_length = [(@base_delay_samples + @depth_delay_samples.ceil + 3), 8].max
+          @delay_lines = Array.new(channels) { Array.new(line_length, 0.0) }
+          @write_indices = Array.new(channels, 0)
+          @lfo = DSP::LFO.new(rate: @rate, sample_rate: sample_rate)
+        end
+
+        def reset_runtime_state
+          @delay_lines = []
+          @write_indices = []
+          @base_delay_samples = nil
+          @depth_delay_samples = nil
+          @lfo = nil
+        end
+
+        def read_fractional_delay(line, write_index, delay_samples)
+          integer = delay_samples.floor
+          fraction = delay_samples - integer
+          idx_a = (write_index - integer - 1) % line.length
+          idx_b = (idx_a - 1) % line.length
+          a = line[idx_a]
+          b = line[idx_b]
+          a + ((b - a) * fraction)
+        end
+
+        def channel_phase_offset(channel)
+          return 0.0 if @runtime_channels.nil? || @runtime_channels <= 1
+
+          channel.to_f / @runtime_channels
+        end
+
+        def validate_positive!(value, name)
+          unless value.is_a?(Numeric) && value.respond_to?(:finite?) && value.finite? && value.positive?
+            raise InvalidParameterError, "#{name} must be a positive finite Numeric"
+          end
+
+          value.to_f
+        end
+
+        def validate_unit!(value, name)
+          unless value.is_a?(Numeric) && value.respond_to?(:finite?) && value.finite? && value.between?(0.0, 1.0)
+            raise InvalidParameterError, "#{name} must be a finite Numeric in 0.0..1.0"
+          end
+
+          value.to_f
+        end
+
+        def validate_feedback!(value)
+          unless value.is_a?(Numeric) && value.respond_to?(:finite?) && value.finite? && value.between?(-0.95, 0.95)
+            raise InvalidParameterError, "feedback must be a finite Numeric in -0.95..0.95"
+          end
+
+          value.to_f
+        end
+      end
+    end
+  end
+end