wavify 0.1.0

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

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Wavify
+  module DSP
+    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)
+          super()
+          @threshold_db = validate_numeric!(threshold, :threshold).to_f
+          @ratio = validate_ratio!(ratio)
+          @attack = validate_time!(attack, :attack)
+          @release = validate_time!(release, :release)
+          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:)
+          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
+        end
+
+        private
+
+        def prepare_runtime_state(sample_rate:, channels:)
+          @envelopes = Array.new(channels, 0.0)
+          @threshold_linear = 10.0**(@threshold_db / 20.0)
+        end
+
+        def reset_runtime_state
+          @envelopes = []
+          @threshold_linear = nil
+        end
+
+        def gain_for_envelope(envelope)
+          return 1.0 if envelope <= 0.0 || envelope <= @threshold_linear
+
+          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)
+        end
+
+        def time_coefficient(seconds, sample_rate)
+          return 0.0 if seconds <= 0.0
+
+          Math.exp(-1.0 / (seconds * sample_rate))
+        end
+
+        def validate_numeric!(value, name)
+          raise InvalidParameterError, "#{name} must be Numeric" unless value.is_a?(Numeric)
+
+          value
+        end
+
+        def validate_ratio!(value)
+          raise InvalidParameterError, "ratio must be >= 1.0" unless value.is_a?(Numeric) && value >= 1.0
+
+          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
+
+          value.to_f
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Wavify
+  module DSP
+    module Effects
+      # Simple feedback delay effect.
+      class Delay < EffectBase
+        def initialize(time: 0.3, feedback: 0.5, mix: 0.3)
+          super()
+          @time = validate_time!(time)
+          @feedback = validate_ratio!(feedback, :feedback)
+          @mix = validate_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:)
+          line = @delay_lines.fetch(channel)
+          index = @write_indices.fetch(channel)
+          delayed = line[index]
+          dry = sample.to_f
+          wet = delayed
+
+          output = (dry * (1.0 - @mix)) + (wet * @mix)
+          line[index] = (dry + (wet * @feedback)).clamp(-1.0, 1.0)
+          @write_indices[channel] = (index + 1) % line.length
+
+          output
+        end
+
+        private
+
+        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) }
+          @write_indices = Array.new(channels, 0)
+        end
+
+        def reset_runtime_state
+          @delay_lines = []
+          @write_indices = []
+        end
+
+        def validate_time!(value)
+          raise InvalidParameterError, "time must be a positive Numeric" unless value.is_a?(Numeric) && value.positive?
+
+          value.to_f
+        end
+
+        def validate_ratio!(value, name)
+          raise InvalidParameterError, "#{name} must be in 0.0...1.0" unless value.is_a?(Numeric) && value >= 0.0 && value < 1.0
+
+          value.to_f
+        end
+
+        def validate_mix!(value)
+          raise InvalidParameterError, "mix must be Numeric in 0.0..1.0" unless value.is_a?(Numeric) && value.between?(0.0, 1.0)
+
+          value.to_f
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Wavify
+  module DSP
+    module Effects
+      # Soft-clipping distortion with tone shaping and dry/wet mix.
+      class Distortion < EffectBase
+        def initialize(drive: 0.5, tone: 0.5, mix: 1.0)
+          super()
+          @drive = validate_unit!(drive, :drive)
+          @tone = validate_unit!(tone, :tone)
+          @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
+          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))
+          @tone_state[channel] = filtered
+
+          (dry * (1.0 - @mix)) + (filtered * @mix)
+        end
+
+        private
+
+        def prepare_runtime_state(sample_rate:, channels:)
+          @tone_state = Array.new(channels, 0.0)
+        end
+
+        def reset_runtime_state
+          @tone_state = []
+        end
+
+        def pre_gain
+          1.0 + (@drive * 19.0)
+        end
+
+        def tone_coefficient(sample_rate)
+          cutoff = 500.0 + (@tone * 7_500.0)
+          rc = 1.0 / (2.0 * Math::PI * cutoff)
+          dt = 1.0 / sample_rate
+          dt / (rc + dt)
+        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)
+
+          value.to_f
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Wavify
+  module DSP
+    module Effects
+      # Base class for sample-by-sample effects with runtime channel state.
+      class EffectBase
+        # Applies the effect to a sample buffer.
+        #
+        # @param buffer [Wavify::Core::SampleBuffer]
+        # @return [Wavify::Core::SampleBuffer]
+        def apply(buffer)
+          process(buffer)
+        end
+
+        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 = 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)
+          end
+
+          Core::SampleBuffer.new(output, float_format).convert(buffer.format)
+        end
+
+        def process_sample(_sample, channel:, sample_rate:)
+          raise NotImplementedError
+        end
+
+        # Resets runtime state and cached channel/sample-rate information.
+        #
+        # @return [EffectBase] self
+        def reset
+          @runtime_sample_rate = nil
+          @runtime_channels = nil
+          reset_runtime_state
+          self
+        end
+
+        private
+
+        def prepare_runtime_if_needed!(sample_rate:, channels:)
+          return if @runtime_sample_rate == sample_rate && @runtime_channels == channels
+
+          @runtime_sample_rate = sample_rate
+          @runtime_channels = channels
+          reset_runtime_state
+          prepare_runtime_state(sample_rate: sample_rate, channels: channels)
+        end
+
+        def prepare_runtime_state(sample_rate:, channels:); end
+
+        def reset_runtime_state; end
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Wavify
+  module DSP
+    module Effects
+      # Lightweight Schroeder-style reverb effect.
+      class Reverb < EffectBase
+        COMB_TAPS_44K = [1116, 1188, 1277, 1356].freeze # :nodoc:
+        ALLPASS_TAPS_44K = [556, 441].freeze # :nodoc:
+
+        def initialize(room_size: 0.5, damping: 0.5, mix: 0.3)
+          super()
+          @room_size = validate_unit!(room_size, :room_size)
+          @damping = validate_unit!(damping, :damping)
+          @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
+          channel_state = @channels_state.fetch(channel)
+
+          comb_input = dry * @input_gain
+          comb_sum = 0.0
+          channel_state[:combs].each do |comb|
+            comb_sum += process_comb(comb, comb_input)
+          end
+
+          wet = comb_sum / channel_state[:combs].length
+          channel_state[:allpasses].each do |allpass|
+            wet = process_allpass(allpass, wet)
+          end
+
+          (dry * (1.0 - @mix)) + (wet * @mix)
+        end
+
+        private
+
+        def prepare_runtime_state(sample_rate:, channels:)
+          scale = sample_rate.to_f / 44_100.0
+          comb_feedback = 0.6 + (@room_size * 0.34)
+          damping = @damping
+
+          @input_gain = 0.35
+          @channels_state = Array.new(channels) do
+            combs = COMB_TAPS_44K.map do |tap|
+              length = [(tap * scale).round, 8].max
+              {
+                buffer: Array.new(length, 0.0),
+                index: 0,
+                feedback: comb_feedback,
+                damping: damping,
+                filter_store: 0.0
+              }
+            end
+            allpasses = ALLPASS_TAPS_44K.map do |tap|
+              length = [(tap * scale).round, 4].max
+              {
+                buffer: Array.new(length, 0.0),
+                index: 0,
+                feedback: 0.5
+              }
+            end
+            { combs: combs, allpasses: allpasses }
+          end
+        end
+
+        def reset_runtime_state
+          @channels_state = []
+          @input_gain = nil
+        end
+
+        def process_comb(comb, input_sample)
+          buffer = comb[:buffer]
+          index = comb[:index]
+          delayed = buffer[index]
+
+          filter_store = (delayed * (1.0 - comb[:damping])) + (comb[:filter_store] * comb[:damping])
+          comb[:filter_store] = filter_store
+          buffer[index] = (input_sample + (filter_store * comb[:feedback])).clamp(-1.0, 1.0)
+          comb[:index] = (index + 1) % buffer.length
+
+          delayed
+        end
+
+        def process_allpass(allpass, input_sample)
+          buffer = allpass[:buffer]
+          index = allpass[:index]
+          delayed = buffer[index]
+
+          output = delayed - input_sample
+          buffer[index] = input_sample + (delayed * allpass[:feedback])
+          allpass[:index] = (index + 1) % buffer.length
+
+          output
+        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)
+
+          value.to_f
+        end
+      end
+    end
+  end
+end

data/lib/wavify/dsp/effects.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative "effects/effect_base"
+require_relative "effects/delay"
+require_relative "effects/reverb"
+require_relative "effects/chorus"
+require_relative "effects/distortion"
+require_relative "effects/compressor"
+
+module Wavify
+  module DSP
+    # Built-in audio effects namespace.
+    module Effects
+    end
+  end
+end
+
+module Wavify
+  # Convenience alias for {Wavify::DSP::Effects}.
+  Effects = DSP::Effects unless const_defined?(:Effects)
+end

data/lib/wavify/dsp/envelope.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Wavify
+  module DSP
+    # ADSR envelope generator and buffer processor.
+    class Envelope
+      attr_reader :attack, :decay, :sustain, :release
+
+      def initialize(attack:, decay:, sustain:, release:)
+        @attack = validate_time!(attack, :attack)
+        @decay = validate_time!(decay, :decay)
+        @sustain = validate_sustain!(sustain)
+        @release = validate_time!(release, :release)
+      end
+
+      # Computes envelope gain at a given playback time.
+      #
+      # @param time [Numeric]
+      # @param note_on_duration [Numeric]
+      # @return [Float]
+      def gain_at(time, note_on_duration:)
+        raise InvalidParameterError, "time must be a non-negative Numeric" unless time.is_a?(Numeric) && time >= 0
+        unless note_on_duration.is_a?(Numeric) && note_on_duration >= 0
+          raise InvalidParameterError, "note_on_duration must be a non-negative Numeric"
+        end
+
+        return attack_gain(time) if time < @attack
+        return decay_gain(time) if time < (@attack + @decay)
+        return @sustain if time < note_on_duration
+
+        release_time = time - note_on_duration
+        release_gain(release_time)
+      end
+
+      # Applies the envelope to a sample buffer.
+      #
+      # @param buffer [Wavify::Core::SampleBuffer]
+      # @param note_on_duration [Numeric]
+      # @return [Wavify::Core::SampleBuffer]
+      def apply(buffer, note_on_duration:)
+        raise InvalidParameterError, "buffer must be Core::SampleBuffer" unless buffer.is_a?(Core::SampleBuffer)
+        unless note_on_duration.is_a?(Numeric) && note_on_duration >= 0
+          raise InvalidParameterError, "note_on_duration must be a non-negative Numeric"
+        end
+
+        float_format = buffer.format.with(sample_format: :float, bit_depth: 32)
+        float_buffer = buffer.convert(float_format)
+        channels = float_format.channels
+        sample_rate = float_format.sample_rate
+
+        processed = float_buffer.samples.dup
+        processed.each_slice(channels).with_index do |frame, frame_index|
+          gain = gain_at(frame_index.to_f / sample_rate, note_on_duration: note_on_duration)
+          base = frame_index * channels
+          frame.each_index do |channel_index|
+            processed[base + channel_index] = frame[channel_index] * gain
+          end
+        end
+
+        Core::SampleBuffer.new(processed, float_format).convert(buffer.format)
+      end
+
+      private
+
+      def attack_gain(time)
+        return 1.0 if @attack.zero?
+
+        time / @attack
+      end
+
+      def decay_gain(time)
+        return @sustain if @decay.zero?
+
+        elapsed = time - @attack
+        1.0 - ((1.0 - @sustain) * (elapsed / @decay))
+      end
+
+      def release_gain(release_time)
+        return 0.0 if @release.zero?
+
+        @sustain * (1.0 - [release_time / @release, 1.0].min)
+      end
+
+      def validate_time!(value, name)
+        raise InvalidParameterError, "#{name} must be a non-negative Numeric" unless value.is_a?(Numeric) && value >= 0
+
+        value.to_f
+      end
+
+      def validate_sustain!(value)
+        raise InvalidParameterError, "sustain must be Numeric in 0.0..1.0" unless value.is_a?(Numeric) && value.between?(0.0, 1.0)
+
+        value.to_f
+      end
+    end
+  end
+end