wavify 0.1.0 → 0.2.0

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

@@ -0,0 +1,259 @@
+# frozen_string_literal: true
+
+module Wavify
+  module DSP
+    module Effects
+      # Stereo-linked lookahead peak limiter with attack and release smoothing.
+      class Limiter < EffectBase
+        MAX_LOOKAHEAD_SECONDS = 1.0
+
+        # FIFO with an amortized O(1) maximum for streaming lookahead detection.
+        class LookaheadQueue
+          def initialize
+            @incoming = []
+            @outgoing = []
+          end
+
+          def push(frame, detector_peak, current_peak)
+            maximum = [detector_peak, @incoming.last&.fetch(3) || 0.0].max
+            @incoming << [frame, current_peak, detector_peak, maximum]
+          end
+
+          def shift
+            refill_outgoing if @outgoing.empty?
+            entry = @outgoing.pop
+            [entry.fetch(0), entry.fetch(1)]
+          end
+
+          def maximum
+            [@incoming.last&.fetch(3) || 0.0, @outgoing.last&.fetch(3) || 0.0].max
+          end
+
+          def length
+            @incoming.length + @outgoing.length
+          end
+
+          def empty?
+            @incoming.empty? && @outgoing.empty?
+          end
+
+          private
+
+          def refill_outgoing
+            until @incoming.empty?
+              frame, current_peak, detector_peak = @incoming.pop.first(3)
+              maximum = [detector_peak, @outgoing.last&.fetch(3) || 0.0].max
+              @outgoing << [frame, current_peak, detector_peak, maximum]
+            end
+          end
+        end
+        private_constant :LookaheadQueue
+
+        def initialize(ceiling: -1.0, input_gain: 0.0, attack: 0.001, release: 0.05, lookahead: 0.005,
+                       oversampling: 1)
+          super()
+          @ceiling_db = validate_dbfs!(ceiling, :ceiling)
+          @input_gain_db = validate_finite_numeric!(input_gain, :input_gain).to_f
+          @attack = validate_time!(attack, :attack)
+          @release = validate_time!(release, :release)
+          @lookahead = validate_time!(lookahead, :lookahead)
+          @oversampling = validate_oversampling!(oversampling)
+          @ceiling = db_to_amplitude(@ceiling_db)
+          @input_gain = db_to_amplitude(@input_gain_db)
+          reset
+        end
+
+        # Applies the limiter on an isolated runtime without adding latency or
+        # changing any streaming state already held by this instance.
+        def apply(buffer)
+          build_runtime.send(:apply_offline, buffer)
+        end
+
+        # Processes a streaming chunk while preserving a lookahead delay.
+        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|
+            delayed_frame = frame.map { |sample| sample * @input_gain }
+            limited_frame = enqueue_and_limit(delayed_frame)
+            output.concat(limited_frame || Array.new(@runtime_channels, 0.0))
+          end
+          Core::SampleBuffer.new(output, float_format).convert(buffer.format)
+        end
+
+        # Emits samples retained by the lookahead delay.
+        def flush(format: nil)
+          return nil unless runtime_prepared? && @delay_frames && @lookahead_frames.positive?
+
+          runtime_format = Core::Format.new(
+            channels: @runtime_channels,
+            sample_rate: @runtime_sample_rate,
+            bit_depth: 32,
+            sample_format: :float
+          )
+          output = flush_limiter_frames.flatten(1)
+          target_format = format || runtime_format
+          Core::SampleBuffer.new(output, runtime_format).convert(target_format)
+        end
+
+        def latency
+          @lookahead
+        end
+
+        def lookahead
+          @lookahead
+        end
+
+        def tail_duration
+          @lookahead
+        end
+
+        def process_sample(_sample, channel:, sample_rate:)
+          raise NotImplementedError, "Limiter requires frame-aware #apply or #process"
+        end
+
+        private
+
+        def apply_offline(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)
+          reset_limiter_state
+
+          frames = float_buffer.samples.each_slice(float_format.channels).map do |frame|
+            frame.map { |sample| sample * @input_gain }
+          end
+          output = limit_offline_frames(frames).flatten(1)
+          Core::SampleBuffer.new(output, float_format).convert(buffer.format)
+        end
+
+        def limit_offline_frames(frames)
+          delayed = frames.map do |frame|
+            enqueue_and_limit(frame) || Array.new(@runtime_channels, 0.0)
+          end
+          delayed.concat(flush_limiter_frames).drop(@lookahead_frames).first(frames.length)
+        end
+
+        def enqueue_and_limit(frame)
+          current_peak = frame_peak(frame)
+          @delay_frames.push(frame, detector_peak(frame, current_peak: current_peak), current_peak)
+          if @delay_frames.length <= @lookahead_frames
+            update_gain(@delay_frames.maximum)
+            return nil
+          end
+
+          delayed_frame, delayed_peak = @delay_frames.shift
+          limit_frame(delayed_frame, @delay_frames.maximum, current_peak: delayed_peak)
+        end
+
+        def flush_limiter_frames
+          silence = Array.new(@runtime_channels, 0.0)
+          output = Array.new(@lookahead_frames) do
+            enqueue_and_limit(silence.dup) || silence.dup
+          end
+          reset_limiter_state
+          output
+        end
+
+        def limit_frame(frame, peak, current_peak: frame_peak(frame))
+          smoothed_gain = update_gain(peak)
+          required_gain = current_peak.positive? ? [@ceiling / current_peak, 1.0].min : 1.0
+          applied_gain = [smoothed_gain, required_gain].min
+          frame.map { |sample| (sample * applied_gain).clamp(-@ceiling, @ceiling) }
+        end
+
+        def update_gain(peak)
+          target = peak > @ceiling ? @ceiling / peak : 1.0
+          coefficient = target < @gain ? @attack_coefficient : @release_coefficient
+          @gain = target + (coefficient * (@gain - target))
+        end
+
+        def frame_peak(frame)
+          frame.reduce(0.0) { |peak, sample| [peak, sample.abs].max }
+        end
+
+        def prepare_runtime_state(sample_rate:, channels:)
+          @lookahead_frames = (@lookahead * sample_rate).round
+          @attack_coefficient = time_coefficient(@attack, sample_rate)
+          @release_coefficient = time_coefficient(@release, sample_rate)
+          reset_limiter_state
+        end
+
+        def reset_runtime_state
+          @lookahead_frames = 0
+          @attack_coefficient = nil
+          @release_coefficient = nil
+          reset_limiter_state
+        end
+
+        def reset_limiter_state
+          @delay_frames = LookaheadQueue.new
+          @gain = 1.0
+          @true_peak_history = []
+        end
+
+        def detector_peak(frame, current_peak:)
+          return current_peak if @oversampling == 1
+
+          @true_peak_history.concat(frame)
+          history_samples = DSP::LoudnessMeter::TRUE_PEAK_RADIUS * 2 * @runtime_channels
+          @true_peak_history.shift(@true_peak_history.length - history_samples) if @true_peak_history.length > history_samples
+          DSP::LoudnessMeter.true_peak(
+            @true_peak_history,
+            sample_rate: @runtime_sample_rate,
+            channels: @runtime_channels,
+            oversampling: @oversampling
+          )
+        end
+
+        def time_coefficient(seconds, sample_rate)
+          return 0.0 if seconds.zero?
+
+          Math.exp(-1.0 / (seconds * sample_rate))
+        end
+
+        def validate_dbfs!(value, name)
+          numeric = validate_finite_numeric!(value, name)
+          raise InvalidParameterError, "#{name} must be <= 0 dBFS" if numeric.positive?
+
+          numeric.to_f
+        end
+
+        def validate_time!(value, name)
+          numeric = validate_finite_numeric!(value, name)
+          raise InvalidParameterError, "#{name} must be non-negative" if numeric.negative?
+          if name == :lookahead && numeric > MAX_LOOKAHEAD_SECONDS
+            raise InvalidParameterError, "lookahead must be <= #{MAX_LOOKAHEAD_SECONDS} seconds"
+          end
+
+          numeric.to_f
+        end
+
+        def validate_finite_numeric!(value, name)
+          unless value.is_a?(Numeric) && value.respond_to?(:finite?) && value.finite?
+            raise InvalidParameterError, "#{name} must be a finite Numeric"
+          end
+
+          value
+        end
+
+        def validate_oversampling!(value)
+          return value if [1, 2, 4, 8].include?(value)
+
+          raise InvalidParameterError, "oversampling must be 1, 2, 4, or 8"
+        end
+
+        def db_to_amplitude(db)
+          10.0**(db / 20.0)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Wavify
+  module DSP
+    module Effects
+      # Small mastering-oriented preset chain.
+      class MasteringChain < EffectChain
+        # @param highpass [Numeric, nil]
+        # @param presence [Numeric, nil] peaking EQ gain in dB
+        # @param threshold [Numeric] compressor threshold in dBFS
+        # @param ratio [Numeric] compressor ratio
+        # @param ceiling [Numeric] limiter ceiling in dBFS
+        def initialize(highpass: 30.0, presence: 1.5, threshold: -18.0, ratio: 2.0, ceiling: -1.0)
+          super([
+            EQ.simple(highpass: highpass, presence: presence_filter(presence)),
+            Compressor.new(threshold: threshold, ratio: ratio, attack: 0.005, release: 0.08, makeup_gain: 1.5, knee: 6.0),
+            Limiter.new(ceiling: ceiling)
+          ])
+        end
+
+        private
+
+        def presence_filter(gain_db)
+          return nil unless gain_db
+
+          { cutoff: 3_500.0, q: 0.8, gain_db: gain_db }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Wavify
+  module DSP
+    module Effects
+      # Simple downward gate for suppressing low-level noise.
+      class NoiseGate < EffectBase
+        include EnvelopeControlledEffect
+
+        def initialize(threshold: -40.0, floor: -80.0, attack: 0.001, hold: 0.02, release: 0.05,
+                       gain_attack: attack, gain_release: release)
+          super()
+          @threshold_db = validate_dbfs!(threshold, :threshold)
+          @floor_db = validate_dbfs!(floor, :floor)
+          @threshold = db_to_amplitude(@threshold_db)
+          @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 = envelope < @threshold ? @floor_gain : 1.0
+          coefficient = target > @gain ? @gain_attack_coefficient : @gain_release_coefficient
+          @gain = target + (coefficient * (@gain - target))
+        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 = @floor_gain
+          @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_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/phaser.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Wavify
+  module DSP
+    module Effects
+      # Modulated all-pass phase shifting effect.
+      class Phaser < EffectBase
+        MAX_STAGES = 32
+        TAIL_AMPLITUDE = 1.0e-6
+        MAX_ALLPASS_COEFFICIENT = 0.9
+        REFERENCE_SAMPLE_RATE = 44_100.0
+
+        def initialize(rate: 0.5, depth: 0.7, feedback: 0.2, mix: 0.5, stages: 4)
+          super()
+          @rate = validate_positive!(rate, :rate)
+          @depth = validate_unit!(depth, :depth)
+          @feedback = validate_feedback!(feedback)
+          @mix = validate_unit!(mix, :mix)
+          @stages = validate_stages!(stages)
+          reset
+        end
+
+        def process_sample(sample, channel:, sample_rate:)
+          dry = sample.to_f
+          coefficient = modulated_coefficient(channel)
+          wet = process_allpass_chain(dry + (@feedback_samples.fetch(channel) * @feedback), channel, coefficient)
+          @feedback_samples[channel] = wet
+          @lfo.next_value if channel == (@runtime_channels - 1)
+
+          (dry * (1.0 - @mix)) + (wet * @mix)
+        end
+
+        def tail_duration
+          return 0.0 if @mix.zero?
+
+          pole = [MAX_ALLPASS_COEFFICIENT, @feedback.abs].max
+          decay_samples = (Math.log(TAIL_AMPLITUDE) / Math.log(pole)).ceil
+          (@stages * decay_samples) / REFERENCE_SAMPLE_RATE
+        end
+
+        private
+
+        def prepare_runtime_state(sample_rate:, channels:)
+          @lfo = DSP::LFO.new(rate: @rate, sample_rate: sample_rate)
+          @stage_states = Array.new(channels) { Array.new(@stages, 0.0) }
+          @feedback_samples = Array.new(channels, 0.0)
+        end
+
+        def reset_runtime_state
+          @lfo = nil
+          @stage_states = []
+          @feedback_samples = []
+        end
+
+        def modulated_coefficient(channel)
+          mod = (@lfo.value_at(channel_phase_offset(channel)) + 1.0) / 2.0
+          (0.08 + (0.82 * @depth * mod)).clamp(0.02, 0.9)
+        end
+
+        def process_allpass_chain(input, channel, coefficient)
+          output = input
+          states = @stage_states.fetch(channel)
+          states.each_index do |stage|
+            delayed = states.fetch(stage)
+            y = delayed - (coefficient * output)
+            states[stage] = output + (coefficient * y)
+            output = y
+          end
+          output
+        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
+
+        def validate_stages!(value)
+          unless value.is_a?(Integer) && value.between?(1, MAX_STAGES)
+            raise InvalidParameterError, "stages must be an Integer in 1..#{MAX_STAGES}"
+          end
+
+          value
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Wavify
+  module DSP
+    module Effects
+      # Speech-oriented cleanup preset for voice tracks.
+      class PodcastChain < EffectChain
+        # @param gate_threshold [Numeric] noise gate threshold in dBFS
+        # @param highpass [Numeric, nil]
+        # @param presence [Numeric, nil] peaking EQ gain in dB
+        # @param compression_threshold [Numeric] compressor threshold in dBFS
+        # @param ceiling [Numeric] limiter ceiling in dBFS
+        def initialize(gate_threshold: -45.0, highpass: 80.0, presence: 3.0, compression_threshold: -20.0, ceiling: -1.0)
+          super([
+            NoiseGate.new(threshold: gate_threshold, floor: -80.0),
+            EQ.simple(highpass: highpass, presence: presence_filter(presence)),
+            Compressor.new(threshold: compression_threshold, ratio: 3.0, attack: 0.003, release: 0.12, makeup_gain: 2.0, knee: 4.0),
+            Limiter.new(ceiling: ceiling)
+          ])
+        end
+
+        private
+
+        def presence_filter(gain_db)
+          return nil unless gain_db
+
+          { cutoff: 3_000.0, q: 0.9, gain_db: gain_db }
+        end
+      end
+    end
+  end
+end

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

@@ -8,14 +8,47 @@ module Wavify
         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)
+        def initialize(room_size: 0.5, damping: 0.5, mix: 0.3, pre_delay: 0.0, width: 1.0)
           super()
           @room_size = validate_unit!(room_size, :room_size)
           @damping = validate_unit!(damping, :damping)
           @mix = validate_unit!(mix, :mix)
+          @pre_delay = validate_time!(pre_delay, :pre_delay)
+          @width = validate_width!(width)
           reset
         end
 
+        # Processes a sample buffer.
+        #
+        # Stereo buffers apply `width:` to the wet signal before mixing it with
+        # the dry input. Mono and multichannel buffers keep per-channel wet paths.
+        #
+        # @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)
+
+          float_format = buffer.format.with(sample_format: :float, bit_depth: 32)
+          float_buffer = buffer.convert(float_format)
+          channels = float_buffer.format.channels
+          prepare_runtime_if_needed!(sample_rate: float_format.sample_rate, channels: channels)
+
+          output = Array.new(float_buffer.samples.length)
+          float_buffer.samples.each_slice(channels).with_index do |frame, frame_index|
+            wet_frame = frame.each_with_index.map do |sample, channel|
+              wet_sample_for(@channels_state.fetch(channel), sample.to_f)
+            end
+            wet_frame = apply_stereo_width(wet_frame) if channels == 2
+
+            base = frame_index * channels
+            frame.each_with_index do |dry, channel|
+              output[base + channel] = mix_dry_wet(dry.to_f, wet_frame.fetch(channel))
+            end
+          end
+
+          Core::SampleBuffer.new(output, float_format).convert(buffer.format)
+        end
+
         # Processes a single sample for one channel.
         #
         # @param sample [Numeric]
@@ -25,19 +58,14 @@ module Wavify
         def process_sample(sample, channel:, sample_rate:)
           dry = sample.to_f
           channel_state = @channels_state.fetch(channel)
+          mix_dry_wet(dry, wet_sample_for(channel_state, dry))
+        end
 
-          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
+        # @return [Float] estimated reverb tail duration in seconds
+        def tail_duration
+          return 0.0 if @mix.zero?
 
-          (dry * (1.0 - @mix)) + (wet * @mix)
+          @pre_delay + 0.25 + (@room_size * 2.5)
         end
 
         private
@@ -48,6 +76,7 @@ module Wavify
           damping = @damping
 
           @input_gain = 0.35
+          pre_delay_frames = (@pre_delay * sample_rate).round
           @channels_state = Array.new(channels) do
             combs = COMB_TAPS_44K.map do |tap|
               length = [(tap * scale).round, 8].max
@@ -67,7 +96,12 @@ module Wavify
                 feedback: 0.5
               }
             end
-            { combs: combs, allpasses: allpasses }
+            {
+              combs: combs,
+              allpasses: allpasses,
+              pre_delay_buffer: Array.new(pre_delay_frames, 0.0),
+              pre_delay_index: 0
+            }
           end
         end
 
@@ -76,6 +110,42 @@ module Wavify
           @input_gain = nil
         end
 
+        def pre_delay_sample(channel_state, input_sample)
+          buffer = channel_state[:pre_delay_buffer]
+          return input_sample if buffer.empty?
+
+          index = channel_state[:pre_delay_index]
+          delayed = buffer[index]
+          buffer[index] = input_sample
+          channel_state[:pre_delay_index] = (index + 1) % buffer.length
+          delayed
+        end
+
+        def wet_sample_for(channel_state, dry)
+          comb_input = pre_delay_sample(channel_state, 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
+          wet
+        end
+
+        def apply_stereo_width(wet_frame)
+          left, right = wet_frame
+          mid = (left + right) * 0.5
+          side = ((left - right) * 0.5) * @width
+          [mid + side, mid - side]
+        end
+
+        def mix_dry_wet(dry, wet)
+          (dry * (1.0 - @mix)) + (wet * @mix)
+        end
+
         def process_comb(comb, input_sample)
           buffer = comb[:buffer]
           index = comb[:index]
@@ -83,7 +153,7 @@ module Wavify
 
           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)
+          buffer[index] = input_sample + (filter_store * comb[:feedback])
           comb[:index] = (index + 1) % buffer.length
 
           delayed
@@ -106,6 +176,22 @@ module Wavify
 
           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 validate_width!(value)
+          unless value.is_a?(Numeric) && value.respond_to?(:finite?) && value.finite? && value.between?(0.0, 2.0)
+            raise InvalidParameterError, "width must be a finite Numeric in 0.0..2.0"
+          end
+
+          value.to_f
+        end
       end
     end
   end