wavify 0.1.0 → 0.2.0

data/lib/wavify/dsp/automation.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Wavify
+  module DSP
+    # Linear automation curve for time-varying parameters.
+    class Automation
+      Point = Struct.new(:time, :value, keyword_init: true)
+
+      attr_reader :points
+
+      def initialize(points)
+        normalized = Array(points).map { |point| coerce_point(point) }.sort_by(&:time)
+        raise InvalidParameterError, "automation points must not be empty" if normalized.empty?
+
+        @points = normalized.freeze
+      end
+
+      def value_at(time)
+        seconds = validate_time!(time)
+        return @points.first.value if seconds <= @points.first.time
+        return @points.last.value if seconds >= @points.last.time
+
+        right_index = @points.bsearch_index { |point| point.time >= seconds }
+        left = @points.fetch(right_index - 1)
+        right = @points.fetch(right_index)
+        span = right.time - left.time
+        return right.value if span.zero?
+
+        ratio = (seconds - left.time) / span
+        left.value + ((right.value - left.value) * ratio)
+      end
+
+      def apply(buffer)
+        raise InvalidParameterError, "buffer must be Core::SampleBuffer" unless buffer.is_a?(Core::SampleBuffer)
+        raise InvalidParameterError, "automation apply requires a block" unless block_given?
+
+        format = buffer.format
+        point_index = 1
+        samples = []
+        buffer.samples.each_slice(format.channels).with_index do |frame, frame_index|
+          time = frame_index.to_f / format.sample_rate
+          point_index += 1 while point_index < @points.length && @points.fetch(point_index).time < time
+          value = value_between_points(time, point_index)
+          frame.each_with_index do |sample, channel|
+            samples << yield(sample, value, time, channel)
+          end
+        end
+        Core::SampleBuffer.new(samples, format)
+      end
+
+      def apply_gain(buffer, unit: :db)
+        mode = unit.to_sym
+        raise InvalidParameterError, "unit must be :db or :linear" unless %i[db linear].include?(mode)
+
+        float_format = buffer.format.with(sample_format: :float, bit_depth: 32)
+        processed = apply(buffer.convert(float_format)) do |sample, value, _time, _channel|
+          factor = mode == :db ? (10.0**(value / 20.0)) : value
+          sample * factor
+        end
+        processed.convert(buffer.format)
+      rescue NoMethodError
+        raise InvalidParameterError, "unit must be Symbol/String"
+      end
+
+      private
+
+      def value_between_points(time, right_index)
+        return @points.first.value if time <= @points.first.time
+        return @points.last.value if right_index >= @points.length
+
+        left = @points.fetch(right_index - 1)
+        right = @points.fetch(right_index)
+        span = right.time - left.time
+        return right.value if span.zero?
+
+        ratio = (time - left.time) / span
+        left.value + ((right.value - left.value) * ratio)
+      end
+
+      def coerce_point(point)
+        time, value = case point
+                      when Point
+                        [point.time, point.value]
+                      when Hash
+                        [point.fetch(:time), point.fetch(:value)]
+                      else
+                        point.to_a
+                      end
+        Point.new(time: validate_time!(time), value: validate_value!(value)).freeze
+      rescue KeyError, NoMethodError
+        raise InvalidParameterError, "automation point must provide time and value"
+      end
+
+      def validate_time!(time)
+        unless time.is_a?(Numeric) && time.respond_to?(:finite?) && time.finite? && time >= 0.0
+          raise InvalidParameterError, "automation time must be a non-negative finite Numeric"
+        end
+
+        time.to_f
+      end
+
+      def validate_value!(value)
+        raise InvalidParameterError, "automation value must be a finite Numeric" unless value.is_a?(Numeric) && value.respond_to?(:finite?) && value.finite?
+
+        value.to_f
+      end
+    end
+  end
+end

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

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Wavify
+  module DSP
+    module Effects
+      # Stereo sine-LFO auto-panner.
+      class AutoPan < EffectBase
+        def initialize(rate: 0.5, depth: 1.0)
+          super()
+          @rate = validate_positive!(rate, :rate)
+          @depth = validate_unit!(depth, :depth)
+          reset
+        end
+
+        # Processes a single sample for one stereo channel.
+        #
+        # @param sample [Numeric]
+        # @param channel [Integer]
+        # @param sample_rate [Integer]
+        # @return [Float]
+        def process_sample(sample, channel:, sample_rate:)
+          raise InvalidParameterError, "AutoPan requires stereo input" unless @runtime_channels == 2
+
+          position = Math.sin(@phase) * @depth
+          left_gain, right_gain = constant_power_pan_gains(position)
+          output = sample.to_f * (channel.zero? ? left_gain : right_gain)
+          advance_phase! if channel == 1
+          output
+        end
+
+        private
+
+        def prepare_runtime_state(sample_rate:, channels:)
+          @phase = 0.0
+          @phase_step = (2.0 * Math::PI * @rate) / sample_rate
+        end
+
+        def reset_runtime_state
+          @phase = 0.0
+          @phase_step = 0.0
+        end
+
+        def constant_power_pan_gains(position)
+          angle = (position + 1.0) * (Math::PI / 4.0)
+          [Math.cos(angle), Math.sin(angle)]
+        end
+
+        def advance_phase!
+          @phase += @phase_step
+          @phase -= (2.0 * Math::PI) while @phase >= (2.0 * Math::PI)
+        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
+      end
+    end
+  end
+end

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

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Wavify
+  module DSP
+    module Effects
+      # Bit-depth reduction and sample-rate hold effect.
+      class Bitcrusher < EffectBase
+        def initialize(bit_depth: 8, downsample: 1, mix: 1.0)
+          super()
+          @bit_depth = validate_bit_depth!(bit_depth)
+          @downsample = validate_downsample!(downsample)
+          @mix = validate_unit!(mix, :mix)
+          reset
+        end
+
+        # Processes a single sample for one channel.
+        #
+        # @param sample [Numeric]
+        # @param channel [Integer]
+        # @param sample_rate [Integer]
+        # @return [Float]
+        def process_sample(sample, channel:, sample_rate:)
+          dry = sample.to_f
+          if (@counters.fetch(channel) % @downsample).zero?
+            @held_samples[channel] = quantize(dry)
+          end
+          @counters[channel] += 1
+
+          wet = @held_samples.fetch(channel)
+          (dry * (1.0 - @mix)) + (wet * @mix)
+        end
+
+        private
+
+        def prepare_runtime_state(sample_rate:, channels:)
+          @held_samples = Array.new(channels, 0.0)
+          @counters = Array.new(channels, 0)
+          @quantization_steps = (2**@bit_depth) - 1
+        end
+
+        def reset_runtime_state
+          @held_samples = []
+          @counters = []
+          @quantization_steps = nil
+        end
+
+        def quantize(value)
+          normalized = ((value.clamp(-1.0, 1.0) + 1.0) / 2.0)
+          ((normalized * @quantization_steps).round / @quantization_steps.to_f * 2.0) - 1.0
+        end
+
+        def validate_bit_depth!(value)
+          raise InvalidParameterError, "bit_depth must be an Integer in 1..24" unless value.is_a?(Integer) && value.between?(1, 24)
+
+          value
+        end
+
+        def validate_downsample!(value)
+          raise InvalidParameterError, "downsample must be a positive Integer" unless value.is_a?(Integer) && value.positive?
+
+          value
+        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
+      end
+    end
+  end
+end

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

@@ -31,11 +31,18 @@ module Wavify
 
           line[write_index] = dry
           @write_indices[channel] = (write_index + 1) % line.length
-          advance_lfo!
+          advance_lfo! if channel == (@runtime_channels - 1)
 
           (dry * (1.0 - @mix)) + (wet * @mix)
         end
 
+        # @return [Float] maximum modulation delay emitted after input ends
+        def tail_duration
+          return 0.0 if @mix.zero?
+
+          0.03
+        end
+
         private
 
         def prepare_runtime_state(sample_rate:, channels:)
@@ -47,7 +54,7 @@ module Wavify
           @delay_lines = Array.new(channels) { Array.new(line_length, 0.0) }
           @write_indices = Array.new(channels, 0)
           @lfo_phase = 0.0
-          @lfo_step = (2.0 * Math::PI * @rate) / (sample_rate * channels)
+          @lfo_step = (2.0 * Math::PI * @rate) / sample_rate
         end
 
         def reset_runtime_state
@@ -82,13 +89,17 @@ module Wavify
         end
 
         def validate_positive!(value, name)
-          raise InvalidParameterError, "#{name} must be a positive Numeric" unless value.is_a?(Numeric) && value.positive?
+          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)
-          raise InvalidParameterError, "#{name} must be Numeric in 0.0..1.0" unless value.is_a?(Numeric) && value.between?(0.0, 1.0)
+          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

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

@@ -5,55 +5,116 @@ module Wavify
     module Effects
       # Peak compressor with threshold, ratio, attack, and release controls.
       class Compressor < EffectBase
-        def initialize(threshold: -10, ratio: 4, attack: 0.01, release: 0.1)
+        def initialize(threshold: -10, ratio: 4, attack: 0.01, release: 0.1, makeup_gain: 0.0, knee: 0.0,
+                       sidechain: nil, sidechain_end: :silence)
           super()
           @threshold_db = validate_numeric!(threshold, :threshold).to_f
           @ratio = validate_ratio!(ratio)
           @attack = validate_time!(attack, :attack)
           @release = validate_time!(release, :release)
+          @makeup_gain_db = validate_numeric!(makeup_gain, :makeup_gain).to_f
+          @knee_db = validate_knee!(knee)
+          @sidechain = validate_sidechain!(sidechain)
+          @sidechain_end = validate_sidechain_end!(sidechain_end)
           reset
         end
 
-        # Processes a single sample for one channel.
+        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_buffer.format.channels
+          )
+
+          output = []
+          float_buffer.samples.each_slice(@runtime_channels) do |frame|
+            detector_level = @sidechain ? next_sidechain_level : frame.map(&:abs).max
+            gain = gain_for_detector_level(detector_level)
+            output.concat(frame.map { |sample| sample * gain })
+          end
+
+          Core::SampleBuffer.new(output, float_format).convert(buffer.format)
+        end
+
+        # Compression requires a complete frame so the detector can remain
+        # stereo-linked. Use #process with a SampleBuffer.
         #
         # @param sample [Numeric]
         # @param channel [Integer]
         # @param sample_rate [Integer]
         # @return [Float]
         def process_sample(sample, channel:, sample_rate:)
-          x = sample.to_f
-          level = x.abs
-
-          attack_coeff = time_coefficient(@attack, sample_rate)
-          release_coeff = time_coefficient(@release, sample_rate)
-          envelope = @envelopes.fetch(channel)
-          coeff = level > envelope ? attack_coeff : release_coeff
-          envelope += (1.0 - coeff) * (level - envelope)
-          @envelopes[channel] = envelope
-
-          gain = gain_for_envelope(envelope)
-          x * gain
+          raise NotImplementedError, "Compressor requires frame-aware #apply or #process"
         end
 
         private
 
+        def gain_for_detector_level(level)
+          coeff = level > @envelope ? @attack_coefficient : @release_coefficient
+          @envelope += (1.0 - coeff) * (level - @envelope)
+
+          gain_for_envelope(@envelope)
+        end
+
         def prepare_runtime_state(sample_rate:, channels:)
-          @envelopes = Array.new(channels, 0.0)
+          @envelope = 0.0
           @threshold_linear = 10.0**(@threshold_db / 20.0)
+          @attack_coefficient = time_coefficient(@attack, sample_rate)
+          @release_coefficient = time_coefficient(@release, sample_rate)
+          @sidechain_cursor = 0
+          @sidechain_runtime = if @sidechain
+                                 format = Core::Format.new(
+                                   channels: channels,
+                                   sample_rate: sample_rate,
+                                   bit_depth: 32,
+                                   sample_format: :float
+                                 )
+                                 @sidechain.convert(format)
+                               end
         end
 
         def reset_runtime_state
-          @envelopes = []
+          @envelope = 0.0
           @threshold_linear = nil
+          @attack_coefficient = nil
+          @release_coefficient = nil
+          @sidechain_cursor = 0
+          @sidechain_runtime = nil
         end
 
         def gain_for_envelope(envelope)
-          return 1.0 if envelope <= 0.0 || envelope <= @threshold_linear
+          return makeup_gain if envelope <= 0.0
 
           input_db = 20.0 * Math.log10(envelope)
-          output_db = @threshold_db + ((input_db - @threshold_db) / @ratio)
-          gain_db = output_db - input_db
-          10.0**(gain_db / 20.0)
+          gain_reduction_db = compression_gain_reduction_db(input_db)
+          10.0**((gain_reduction_db + @makeup_gain_db) / 20.0)
+        end
+
+        def compression_gain_reduction_db(input_db)
+          over_threshold = input_db - @threshold_db
+          if @knee_db.positive?
+            half_knee = @knee_db / 2.0
+            return 0.0 if over_threshold <= -half_knee
+            return hard_knee_gain_reduction_db(over_threshold) if over_threshold >= half_knee
+
+            knee_position = over_threshold + half_knee
+            ((1.0 / @ratio) - 1.0) * (knee_position * knee_position) / (2.0 * @knee_db)
+          else
+            hard_knee_gain_reduction_db(over_threshold)
+          end
+        end
+
+        def hard_knee_gain_reduction_db(over_threshold)
+          return 0.0 unless over_threshold.positive?
+
+          (over_threshold / @ratio) - over_threshold
+        end
+
+        def makeup_gain
+          10.0**(@makeup_gain_db / 20.0)
         end
 
         def time_coefficient(seconds, sample_rate)
@@ -63,22 +124,71 @@ module Wavify
         end
 
         def validate_numeric!(value, name)
-          raise InvalidParameterError, "#{name} must be Numeric" unless value.is_a?(Numeric)
+          raise InvalidParameterError, "#{name} must be a finite Numeric" unless value.is_a?(Numeric) && value.respond_to?(:finite?) && value.finite?
 
           value
         end
 
         def validate_ratio!(value)
-          raise InvalidParameterError, "ratio must be >= 1.0" unless value.is_a?(Numeric) && value >= 1.0
+          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)
-          raise InvalidParameterError, "#{name} must be a non-negative Numeric" unless value.is_a?(Numeric) && value >= 0.0
+          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 validate_knee!(value)
+          unless value.is_a?(Numeric) && value.respond_to?(:finite?) && value.finite? && value >= 0.0
+            raise InvalidParameterError, "knee must be a non-negative finite Numeric"
+          end
+
+          value.to_f
+        end
+
+        def validate_sidechain!(value)
+          return nil if value.nil?
+          return value.buffer if defined?(Wavify::Audio) && value.is_a?(Wavify::Audio)
+          return value if value.is_a?(Core::SampleBuffer)
+
+          raise InvalidParameterError, "sidechain must be Audio or Core::SampleBuffer"
+        end
+
+        def validate_sidechain_end!(value)
+          normalized = value.to_sym if value.respond_to?(:to_sym)
+          return normalized if %i[silence hold loop].include?(normalized)
+
+          raise InvalidParameterError, "sidechain_end must be :silence, :hold, or :loop"
+        end
+
+        def next_sidechain_level
+          frame_count = @sidechain_runtime.sample_frame_count
+          frame_index = sidechain_frame_index(frame_count)
+          @sidechain_cursor += 1
+          return 0.0 unless frame_index
+
+          start_index = frame_index * @runtime_channels
+          frame = @sidechain_runtime.samples.slice(start_index, @runtime_channels) || []
+          frame.map(&:abs).max || 0.0
+        end
+
+        def sidechain_frame_index(frame_count)
+          return nil if frame_count.zero?
+          return @sidechain_cursor if @sidechain_cursor < frame_count
+
+          case @sidechain_end
+          when :silence then nil
+          when :hold then frame_count - 1
+          when :loop then @sidechain_cursor % frame_count
+          end
+        end
       end
     end
   end

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

@@ -5,6 +5,34 @@ module Wavify
     module Effects
       # Simple feedback delay effect.
       class Delay < EffectBase
+        NOTE_MULTIPLIERS = {
+          whole: 4.0,
+          half: 2.0,
+          quarter: 1.0,
+          eighth: 0.5,
+          sixteenth: 0.25,
+          thirty_second: 0.125
+        }.freeze
+
+        # Builds a tempo-synced delay.
+        #
+        # @param note [Symbol, String] note value such as `:quarter` or `:eighth`
+        # @param tempo [Numeric] beats per minute
+        # @param dotted [Boolean] multiply by 1.5
+        # @param triplet [Boolean] multiply by 2/3
+        # @return [Delay]
+        def self.beat(note, tempo:, dotted: false, triplet: false, feedback: 0.5, mix: 0.3)
+          multiplier = note_multiplier!(note)
+          unless tempo.is_a?(Numeric) && tempo.respond_to?(:finite?) && tempo.finite? && tempo.positive?
+            raise InvalidParameterError, "tempo must be a positive finite Numeric"
+          end
+          raise InvalidParameterError, "dotted and triplet cannot both be true" if dotted && triplet
+
+          multiplier *= 1.5 if dotted
+          multiplier *= (2.0 / 3.0) if triplet
+          new(time: (60.0 / tempo.to_f) * multiplier, feedback: feedback, mix: mix)
+        end
+
         def initialize(time: 0.3, feedback: 0.5, mix: 0.3)
           super()
           @time = validate_time!(time)
@@ -27,14 +55,31 @@ module Wavify
           wet = delayed
 
           output = (dry * (1.0 - @mix)) + (wet * @mix)
-          line[index] = (dry + (wet * @feedback)).clamp(-1.0, 1.0)
+          line[index] = dry + (wet * @feedback)
           @write_indices[channel] = (index + 1) % line.length
 
           output
         end
 
+        # @return [Float] estimated feedback tail duration in seconds
+        def tail_duration
+          return 0.0 if @mix.zero?
+          return @time if @feedback.zero?
+
+          repeats = (Math.log(0.001) / Math.log(@feedback)).ceil
+          @time * [[repeats, 1].max, 32].min
+        end
+
         private
 
+        def self.note_multiplier!(note)
+          normalized = note.to_sym if note.respond_to?(:to_sym)
+          return NOTE_MULTIPLIERS.fetch(normalized) if NOTE_MULTIPLIERS.key?(normalized)
+
+          raise InvalidParameterError, "note must be one of: #{NOTE_MULTIPLIERS.keys.join(', ')}"
+        end
+        private_class_method :note_multiplier!
+
         def prepare_runtime_state(sample_rate:, channels:)
           delay_samples = [(sample_rate * @time).round, 1].max
           @delay_lines = Array.new(channels) { Array.new(delay_samples, 0.0) }

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

@@ -24,9 +24,8 @@ module Wavify
           wet = Math.tanh(dry * pre_gain)
 
           # One-pole low-pass on the distorted signal for tone shaping.
-          coeff = tone_coefficient(sample_rate)
           previous = @tone_state.fetch(channel)
-          filtered = previous + (coeff * (wet - previous))
+          filtered = previous + (@tone_coefficient * (wet - previous))
           @tone_state[channel] = filtered
 
           (dry * (1.0 - @mix)) + (filtered * @mix)
@@ -36,10 +35,12 @@ module Wavify
 
         def prepare_runtime_state(sample_rate:, channels:)
           @tone_state = Array.new(channels, 0.0)
+          @tone_coefficient = tone_coefficient(sample_rate)
         end
 
         def reset_runtime_state
           @tone_state = []
+          @tone_coefficient = nil
         end
 
         def pre_gain