wavify 0.1.0 → 0.2.0

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Wavify
+  module DSP
+    module Effects
+      # Soft-knee peak limiter for taming overs without a hard flat top.
+      class SoftLimiter < EffectBase
+        def initialize(threshold: 0.8, ceiling: 1.0, drive: 1.0)
+          super()
+          @threshold = validate_unit!(threshold, :threshold)
+          @ceiling = validate_unit!(ceiling, :ceiling)
+          raise InvalidParameterError, "ceiling must be greater than threshold" unless @ceiling > @threshold
+
+          @drive = validate_positive!(drive, :drive)
+          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:)
+          value = sample.to_f
+          magnitude = value.abs
+          return value if magnitude <= @threshold
+
+          range = @ceiling - @threshold
+          sign = value.negative? ? -1.0 : 1.0
+          limited = @threshold + (range * (1.0 - Math.exp(-((magnitude - @threshold) * @drive) / range)))
+          sign * limited.clamp(@threshold, @ceiling)
+        end
+
+        private
+
+        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_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
+      end
+    end
+  end
+end

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

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Wavify
+  module DSP
+    module Effects
+      # Mid/side stereo width processor.
+      class StereoWidener
+        def initialize(width: 1.25)
+          @width = validate_width!(width)
+        end
+
+        # Applies mid/side width adjustment to a stereo buffer.
+        #
+        # @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)
+          raise InvalidParameterError, "StereoWidener requires stereo input" unless buffer.format.channels == 2
+
+          float_format = buffer.format.with(sample_format: :float, bit_depth: 32)
+          float_buffer = buffer.convert(float_format)
+          widened = float_buffer.samples.each_slice(2).flat_map do |left, right|
+            mid = (left + right) / 2.0
+            side = ((left - right) / 2.0) * @width
+            [mid + side, mid - side]
+          end
+
+          Wavify::Core::SampleBuffer.new(widened, float_format).convert(buffer.format)
+        end
+
+        def apply(buffer)
+          DSP::Processor.render(self, buffer)
+        end
+
+        def build_runtime
+          dup.reset
+        end
+
+        # Stateless processor API compatibility.
+        #
+        # @return [StereoWidener] self
+        def reset
+          self
+        end
+
+        # @return [Float]
+        def latency
+          0.0
+        end
+
+        # @return [Float]
+        def lookahead
+          0.0
+        end
+
+        # @return [Float]
+        def tail_duration
+          0.0
+        end
+
+        private
+
+        def validate_width!(value)
+          unless value.is_a?(Numeric) && value.respond_to?(:finite?) && value.finite? && value >= 0.0
+            raise InvalidParameterError, "width must be a non-negative finite Numeric"
+          end
+
+          value.to_f
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Wavify
+  module DSP
+    module Effects
+      # Amplitude modulation effect using a sine LFO.
+      class Tremolo < EffectBase
+        def initialize(rate: 5.0, depth: 0.5, mix: 1.0)
+          super()
+          @rate = validate_positive!(rate, :rate)
+          @depth = validate_unit!(depth, :depth)
+          @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
+          mod = 1.0 - (@depth * ((Math.sin(@phase) + 1.0) / 2.0))
+          wet = dry * mod
+          advance_phase! if channel == (@runtime_channels - 1)
+
+          (dry * (1.0 - @mix)) + (wet * @mix)
+        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 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/vibrato.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Wavify
+  module DSP
+    module Effects
+      # Pitch modulation effect using a short modulated delay line.
+      class Vibrato < EffectBase
+        BASE_DELAY_SECONDS = 0.006
+        DEPTH_DELAY_SECONDS = 0.004
+
+        def initialize(rate: 5.0, depth: 0.5, mix: 1.0)
+          super()
+          @rate = validate_positive!(rate, :rate)
+          @depth = validate_unit!(depth, :depth)
+          @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
+          @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?
+
+          maximum_delay
+        end
+
+        def latency
+          @mix >= 1.0 ? maximum_delay : 0.0
+        end
+
+        private
+
+        def prepare_runtime_state(sample_rate:, channels:)
+          @base_delay_samples = [(sample_rate * BASE_DELAY_SECONDS).round, 1].max
+          @depth_delay_samples = (sample_rate * DEPTH_DELAY_SECONDS * @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 maximum_delay
+          BASE_DELAY_SECONDS + (DEPTH_DELAY_SECONDS * @depth)
+        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.rb

@@ -1,16 +1,122 @@
 # frozen_string_literal: true
 
 require_relative "effects/effect_base"
+require_relative "effects/envelope_controlled_effect"
 require_relative "effects/delay"
 require_relative "effects/reverb"
 require_relative "effects/chorus"
 require_relative "effects/distortion"
 require_relative "effects/compressor"
+require_relative "effects/limiter"
+require_relative "effects/soft_limiter"
+require_relative "effects/noise_gate"
+require_relative "effects/tremolo"
+require_relative "effects/vibrato"
+require_relative "effects/flanger"
+require_relative "effects/phaser"
+require_relative "effects/bitcrusher"
+require_relative "effects/expander"
+require_relative "effects/auto_pan"
+require_relative "effects/stereo_widener"
+require_relative "effects/eq"
+require_relative "effects/effect_chain"
+require_relative "effects/mastering_chain"
+require_relative "effects/podcast_chain"
 
 module Wavify
   module DSP
     # Built-in audio effects namespace.
     module Effects
+      BUILTIN_EFFECTS = {
+        delay: Delay,
+        reverb: Reverb,
+        chorus: Chorus,
+        distortion: Distortion,
+        compressor: Compressor,
+        limiter: Limiter,
+        soft_limiter: SoftLimiter,
+        noise_gate: NoiseGate,
+        tremolo: Tremolo,
+        vibrato: Vibrato,
+        flanger: Flanger,
+        phaser: Phaser,
+        bitcrusher: Bitcrusher,
+        expander: Expander,
+        auto_pan: AutoPan,
+        stereo_widener: StereoWidener,
+        eq: EQ,
+        mastering_chain: MasteringChain,
+        podcast_chain: PodcastChain
+      }.freeze
+
+      class << self
+        # Registers an effect class or factory under a DSL-friendly name.
+        #
+        # @param name [Symbol, String]
+        # @param factory [Class, #call]
+        # @return [Class, #call]
+        def register(name, factory = nil, &block)
+          key = normalize_effect_name!(name)
+          value = factory || block
+          raise InvalidParameterError, "effect factory must be a Class or callable object" unless effect_factory?(value)
+
+          registry_mutex.synchronize { registry[key] = value }
+        end
+
+        # Removes a custom effect or restores a built-in implementation.
+        def unregister(name)
+          key = normalize_effect_name!(name)
+          registry_mutex.synchronize do
+            previous = registry[key]
+            if BUILTIN_EFFECTS.key?(key)
+              registry[key] = BUILTIN_EFFECTS.fetch(key)
+            else
+              registry.delete(key)
+            end
+            previous
+          end
+        end
+
+        # Builds a registered effect instance.
+        #
+        # @param name [Symbol, String]
+        # @return [Object]
+        def build(name, **params)
+          key = normalize_effect_name!(name)
+          factory = registry_mutex.synchronize { registry[key] }
+          raise InvalidParameterError, "unsupported effect: #{key}" unless factory
+
+          effect = factory.is_a?(Class) ? factory.new(**params) : factory.call(**params)
+          return effect if effect.respond_to?(:process) || effect.respond_to?(:call) || effect.respond_to?(:apply)
+
+          raise InvalidParameterError, "registered effect #{key} must build a processor"
+        end
+
+        # @return [Hash<Symbol, Object>]
+        def registered_effects
+          registry_mutex.synchronize { registry.dup.freeze }
+        end
+
+        private
+
+        def registry
+          @registry ||= BUILTIN_EFFECTS.dup
+        end
+
+        def registry_mutex
+          @registry_mutex ||= Mutex.new
+        end
+
+        def normalize_effect_name!(name)
+          raise InvalidParameterError, "effect name must be Symbol or String" unless name.is_a?(Symbol) || name.is_a?(String)
+
+          name.to_sym
+        end
+
+        def effect_factory?(value)
+          value.is_a?(Class) || value.respond_to?(:call)
+        end
+      end
     end
   end
 end

data/lib/wavify/dsp/envelope.rb

@@ -2,15 +2,19 @@
 
 module Wavify
   module DSP
-    # ADSR envelope generator and buffer processor.
+    # AHDSR envelope generator and buffer processor.
     class Envelope
-      attr_reader :attack, :decay, :sustain, :release
+      CURVES = %i[linear exp log].freeze # :nodoc:
 
-      def initialize(attack:, decay:, sustain:, release:)
+      attr_reader :attack, :hold, :decay, :sustain, :release, :curve
+
+      def initialize(attack:, decay:, sustain:, release:, hold: 0.0, curve: :linear)
         @attack = validate_time!(attack, :attack)
+        @hold = validate_time!(hold, :hold)
         @decay = validate_time!(decay, :decay)
         @sustain = validate_sustain!(sustain)
         @release = validate_time!(release, :release)
+        @curve = validate_curve!(curve)
       end
 
       # Computes envelope gain at a given playback time.
@@ -19,17 +23,17 @@ module Wavify
       # @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"
+        unless finite_nonnegative?(time)
+          raise InvalidParameterError, "time must be a non-negative finite Numeric"
+        end
+        unless finite_nonnegative?(note_on_duration)
+          raise InvalidParameterError, "note_on_duration must be a non-negative finite Numeric"
         end
 
-        return attack_gain(time) if time < @attack
-        return decay_gain(time) if time < (@attack + @decay)
-        return @sustain if time < note_on_duration
+        return sustain_stage_gain(time) if time < note_on_duration
 
         release_time = time - note_on_duration
-        release_gain(release_time)
+        release_gain(release_time, start_gain: sustain_stage_gain(note_on_duration))
       end
 
       # Applies the envelope to a sample buffer.
@@ -39,8 +43,8 @@ module Wavify
       # @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"
+        unless finite_nonnegative?(note_on_duration)
+          raise InvalidParameterError, "note_on_duration must be a non-negative finite Numeric"
         end
 
         float_format = buffer.format.with(sample_format: :float, bit_depth: 32)
@@ -60,38 +64,105 @@ module Wavify
         Core::SampleBuffer.new(processed, float_format).convert(buffer.format)
       end
 
+      # Applies the envelope and extends a short source through the release.
+      # The terminal source frame is held when more source audio is required.
+      def render_with_tail(buffer, note_on_duration:)
+        raise InvalidParameterError, "buffer must be Core::SampleBuffer" unless buffer.is_a?(Core::SampleBuffer)
+        unless finite_nonnegative?(note_on_duration)
+          raise InvalidParameterError, "note_on_duration must be a non-negative finite Numeric"
+        end
+
+        target_frames = ((note_on_duration + @release) * buffer.format.sample_rate).ceil
+        return apply(buffer, note_on_duration: note_on_duration) if buffer.sample_frame_count >= target_frames
+
+        channels = buffer.format.channels
+        terminal_frame = buffer.samples.last(channels)
+        terminal_frame = Array.new(channels, 0) if terminal_frame.empty?
+        missing_frames = target_frames - buffer.sample_frame_count
+        extended = buffer.concat(Core::SampleBuffer.new(terminal_frame * missing_frames, buffer.format))
+        apply(extended, note_on_duration: note_on_duration)
+      end
+
+      def tail_duration
+        @release
+      end
+
+      def latency
+        0.0
+      end
+
+      def lookahead
+        0.0
+      end
+
       private
 
       def attack_gain(time)
         return 1.0 if @attack.zero?
 
-        time / @attack
+        curve_factor(time / @attack)
       end
 
       def decay_gain(time)
         return @sustain if @decay.zero?
 
-        elapsed = time - @attack
-        1.0 - ((1.0 - @sustain) * (elapsed / @decay))
+        elapsed = time - @attack - @hold
+        progress = curve_factor(elapsed / @decay)
+        1.0 - ((1.0 - @sustain) * progress)
       end
 
-      def release_gain(release_time)
+      def release_gain(release_time, start_gain:)
         return 0.0 if @release.zero?
 
-        @sustain * (1.0 - [release_time / @release, 1.0].min)
+        start_gain * (1.0 - curve_factor(release_time / @release))
+      end
+
+      def sustain_stage_gain(time)
+        return attack_gain(time) if time < @attack
+        return 1.0 if time < (@attack + @hold)
+        return decay_gain(time) if time < (@attack + @hold + @decay)
+
+        @sustain
+      end
+
+      def curve_factor(value)
+        progress = value.clamp(0.0, 1.0)
+        case @curve
+        when :linear
+          progress
+        when :exp
+          progress * progress
+        when :log
+          Math.log10(1.0 + (9.0 * progress))
+        end
       end
 
       def validate_time!(value, name)
-        raise InvalidParameterError, "#{name} must be a non-negative Numeric" unless value.is_a?(Numeric) && value >= 0
+        unless value.is_a?(Numeric) && value.respond_to?(:finite?) && value.finite? && value >= 0
+          raise InvalidParameterError, "#{name} must be a non-negative finite Numeric"
+        end
 
         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)
+        unless value.is_a?(Numeric) && value.respond_to?(:finite?) && value.finite? && value.between?(0.0, 1.0)
+          raise InvalidParameterError, "sustain must be a finite Numeric in 0.0..1.0"
+        end
 
         value.to_f
       end
+
+      def validate_curve!(value)
+        normalized = value.to_sym if value.respond_to?(:to_sym)
+        return normalized if CURVES.include?(normalized)
+
+        raise InvalidParameterError, "curve must be one of: #{CURVES.join(', ')}"
+      end
+
+      def finite_nonnegative?(value)
+        value.is_a?(Numeric) && value.respond_to?(:finite?) && value.finite? && value >= 0.0
+      end
     end
   end
 end