wavify 0.1.0

data/lib/wavify/dsp/filter.rb

@@ -0,0 +1,271 @@
+# frozen_string_literal: true
+
+module Wavify
+  # Digital signal processing primitives.
+  module DSP
+    # Stateful biquad filter with common factory constructors.
+    class Filter
+      attr_reader :type, :cutoff, :q, :gain_db
+
+      # Builds a low-pass filter.
+      #
+      # @return [Filter]
+      def self.lowpass(cutoff:, q: 0.707)
+        new(:lowpass, cutoff: cutoff, q: q)
+      end
+
+      # Builds a high-pass filter.
+      #
+      # @return [Filter]
+      def self.highpass(cutoff:, q: 0.707)
+        new(:highpass, cutoff: cutoff, q: q)
+      end
+
+      def self.bandpass(center:, bandwidth:)
+        raise InvalidParameterError, "bandwidth must be positive" unless bandwidth.is_a?(Numeric) && bandwidth.positive?
+
+        new(:bandpass, cutoff: center, q: center.to_f / bandwidth)
+      end
+
+      # Builds a notch filter.
+      #
+      # @return [Filter]
+      def self.notch(cutoff:, q: 0.707)
+        new(:notch, cutoff: cutoff, q: q)
+      end
+
+      # Builds a peaking EQ filter.
+      #
+      # @return [Filter]
+      def self.peaking(cutoff:, q: 1.0, gain_db: 0.0)
+        new(:peaking, cutoff: cutoff, q: q, gain_db: gain_db)
+      end
+
+      # Builds a low-shelf EQ filter.
+      #
+      # @return [Filter]
+      def self.lowshelf(cutoff:, gain_db:)
+        new(:lowshelf, cutoff: cutoff, gain_db: gain_db)
+      end
+
+      # Builds a high-shelf EQ filter.
+      #
+      # @return [Filter]
+      def self.highshelf(cutoff:, gain_db:)
+        new(:highshelf, cutoff: cutoff, gain_db: gain_db)
+      end
+
+      def initialize(type, cutoff:, q: 0.707, gain_db: 0.0)
+        @type = validate_type!(type)
+        @cutoff = validate_cutoff!(cutoff)
+        @q = validate_q!(q)
+        @gain_db = validate_gain!(gain_db)
+
+        @coefficients = nil
+        @coeff_sample_rate = nil
+        @channel_states = []
+      end
+
+      def apply(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)
+        processed = process_interleaved(
+          float_buffer.samples,
+          sample_rate: float_format.sample_rate,
+          channels: float_format.channels
+        )
+
+        Core::SampleBuffer.new(processed, float_format).convert(buffer.format)
+      end
+
+      def process_sample(sample, sample_rate:, channel: 0)
+        raise InvalidParameterError, "sample must be Numeric" unless sample.is_a?(Numeric)
+        raise InvalidParameterError, "channel must be a non-negative Integer" unless channel.is_a?(Integer) && channel >= 0
+        raise InvalidParameterError, "sample_rate must be a positive Integer" unless sample_rate.is_a?(Integer) && sample_rate.positive?
+
+        update_coefficients!(sample_rate)
+        ensure_channel_states!(channel + 1)
+        state = @channel_states[channel]
+        x = sample.to_f
+        y = compute_biquad(state, x)
+        update_state!(state, x, y)
+        y
+      end
+
+      # Clears internal filter state for all channels.
+      #
+      # @return [void]
+      def reset
+        @channel_states = []
+      end
+
+      private
+
+      def process_interleaved(samples, sample_rate:, channels:)
+        update_coefficients!(sample_rate)
+        ensure_channel_states!(channels)
+
+        output = Array.new(samples.length)
+        samples.each_with_index do |sample, sample_index|
+          channel = sample_index % channels
+          state = @channel_states[channel]
+          x = sample.to_f
+          y = compute_biquad(state, x)
+          update_state!(state, x, y)
+          output[sample_index] = y
+        end
+        output
+      end
+
+      def update_coefficients!(sample_rate)
+        return if @coeff_sample_rate == sample_rate && @coefficients
+
+        @coefficients = coefficients_for(sample_rate)
+        @coeff_sample_rate = sample_rate
+        reset
+      end
+
+      def ensure_channel_states!(channels)
+        return if @channel_states.length == channels
+
+        @channel_states = Array.new(channels) { { x1: 0.0, x2: 0.0, y1: 0.0, y2: 0.0 } }
+      end
+
+      def compute_biquad(state, x)
+        b0, b1, b2, a1, a2 = @coefficients
+        (b0 * x) + (b1 * state[:x1]) + (b2 * state[:x2]) - (a1 * state[:y1]) - (a2 * state[:y2])
+      end
+
+      def update_state!(state, x, y)
+        state[:x2] = state[:x1]
+        state[:x1] = x
+        state[:y2] = state[:y1]
+        state[:y1] = y
+      end
+
+      def coefficients_for(sample_rate)
+        omega = 2.0 * Math::PI * @cutoff / sample_rate
+        cos_w = Math.cos(omega)
+        sin_w = Math.sin(omega)
+        alpha = sin_w / (2.0 * @q)
+        a = 10.0**(@gain_db / 40.0)
+
+        b0, b1, b2, a0, a1, a2 = case @type
+                                 when :lowpass
+                                   [
+                                     (1.0 - cos_w) / 2.0,
+                                     1.0 - cos_w,
+                                     (1.0 - cos_w) / 2.0,
+                                     1.0 + alpha,
+                                     -2.0 * cos_w,
+                                     1.0 - alpha
+                                   ]
+                                 when :highpass
+                                   [
+                                     (1.0 + cos_w) / 2.0,
+                                     -(1.0 + cos_w),
+                                     (1.0 + cos_w) / 2.0,
+                                     1.0 + alpha,
+                                     -2.0 * cos_w,
+                                     1.0 - alpha
+                                   ]
+                                 when :bandpass
+                                   [
+                                     alpha,
+                                     0.0,
+                                     -alpha,
+                                     1.0 + alpha,
+                                     -2.0 * cos_w,
+                                     1.0 - alpha
+                                   ]
+                                 when :notch
+                                   [
+                                     1.0,
+                                     -2.0 * cos_w,
+                                     1.0,
+                                     1.0 + alpha,
+                                     -2.0 * cos_w,
+                                     1.0 - alpha
+                                   ]
+                                 when :peaking
+                                   [
+                                     1.0 + (alpha * a),
+                                     -2.0 * cos_w,
+                                     1.0 - (alpha * a),
+                                     1.0 + (alpha / a),
+                                     -2.0 * cos_w,
+                                     1.0 - (alpha / a)
+                                   ]
+                                 when :lowshelf
+                                   shelf_coefficients(:low, cos_w, sin_w, a)
+                                 when :highshelf
+                                   shelf_coefficients(:high, cos_w, sin_w, a)
+                                 else
+                                   raise InvalidParameterError, "unsupported filter type: #{@type}"
+                                 end
+
+        [
+          b0 / a0,
+          b1 / a0,
+          b2 / a0,
+          a1 / a0,
+          a2 / a0
+        ]
+      end
+
+      def shelf_coefficients(mode, cos_w, sin_w, a)
+        sqrt_a = Math.sqrt(a)
+        two_sqrt_a_alpha = 2.0 * sqrt_a * (sin_w / 2.0)
+        if mode == :low
+          [
+            a * ((a + 1.0) - ((a - 1.0) * cos_w) + two_sqrt_a_alpha),
+            2.0 * a * ((a - 1.0) - ((a + 1.0) * cos_w)),
+            a * ((a + 1.0) - ((a - 1.0) * cos_w) - two_sqrt_a_alpha),
+            (a + 1.0) + ((a - 1.0) * cos_w) + two_sqrt_a_alpha,
+            -2.0 * ((a - 1.0) + ((a + 1.0) * cos_w)),
+            (a + 1.0) + ((a - 1.0) * cos_w) - two_sqrt_a_alpha
+          ]
+        else
+          [
+            a * ((a + 1.0) + ((a - 1.0) * cos_w) + two_sqrt_a_alpha),
+            -2.0 * a * ((a - 1.0) + ((a + 1.0) * cos_w)),
+            a * ((a + 1.0) + ((a - 1.0) * cos_w) - two_sqrt_a_alpha),
+            (a + 1.0) - ((a - 1.0) * cos_w) + two_sqrt_a_alpha,
+            2.0 * ((a - 1.0) - ((a + 1.0) * cos_w)),
+            (a + 1.0) - ((a - 1.0) * cos_w) - two_sqrt_a_alpha
+          ]
+        end
+      end
+
+      def validate_type!(type)
+        value = type.to_sym
+        supported = %i[lowpass highpass bandpass notch peaking lowshelf highshelf]
+        raise InvalidParameterError, "unsupported filter type: #{type.inspect}" unless supported.include?(value)
+
+        value
+      rescue NoMethodError
+        raise InvalidParameterError, "filter type must be Symbol/String: #{type.inspect}"
+      end
+
+      def validate_cutoff!(cutoff)
+        raise InvalidParameterError, "cutoff must be a positive Numeric" unless cutoff.is_a?(Numeric) && cutoff.positive?
+
+        cutoff.to_f
+      end
+
+      def validate_q!(q)
+        raise InvalidParameterError, "q must be a positive Numeric" unless q.is_a?(Numeric) && q.positive?
+
+        q.to_f
+      end
+
+      def validate_gain!(gain_db)
+        raise InvalidParameterError, "gain_db must be Numeric" unless gain_db.is_a?(Numeric)
+
+        gain_db.to_f
+      end
+    end
+  end
+end

data/lib/wavify/dsp/oscillator.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Wavify
+  module DSP
+    # Oscillator and noise source generator.
+    class Oscillator
+      # Supported waveform symbols.
+      WAVEFORMS = %i[sine square sawtooth triangle white_noise pink_noise].freeze
+
+      def initialize(waveform:, frequency:, amplitude: 1.0, phase: 0.0, random: Random.new)
+        @waveform = validate_waveform!(waveform)
+        @frequency = validate_frequency!(frequency)
+        @amplitude = validate_amplitude!(amplitude)
+        @phase = phase.to_f
+        @random = random
+        reset_pink_noise!
+      end
+
+      # Generates a finite sample buffer in the requested format.
+      #
+      # @param duration_seconds [Numeric]
+      # @param format [Wavify::Core::Format]
+      # @return [Wavify::Core::SampleBuffer]
+      def generate(duration_seconds, format:)
+        validate_format!(format)
+        unless duration_seconds.is_a?(Numeric) && duration_seconds >= 0
+          raise InvalidParameterError, "duration_seconds must be a non-negative Numeric"
+        end
+
+        sample_frames = (duration_seconds.to_f * format.sample_rate).round
+        samples = Array.new(sample_frames * format.channels)
+
+        sample_frames.times do |frame_index|
+          value = sample_at(frame_index, format.sample_rate)
+          base_index = frame_index * format.channels
+          format.channels.times { |channel| samples[base_index + channel] = value }
+        end
+
+        Core::SampleBuffer.new(samples, format)
+      end
+
+      # Returns an infinite enumerator of mono sample values.
+      #
+      # @param format [Wavify::Core::Format]
+      # @return [Enumerator<Float>]
+      def each_sample(format:)
+        validate_format!(format)
+
+        Enumerator.new do |yielder|
+          index = 0
+          loop do
+            yielder << sample_at(index, format.sample_rate)
+            index += 1
+          end
+        end
+      end
+
+      private
+
+      def validate_waveform!(waveform)
+        value = waveform.to_sym
+        raise InvalidParameterError, "unsupported waveform: #{waveform.inspect}" unless WAVEFORMS.include?(value)
+
+        value
+      rescue NoMethodError
+        raise InvalidParameterError, "waveform must be Symbol/String: #{waveform.inspect}"
+      end
+
+      def validate_frequency!(frequency)
+        raise InvalidParameterError, "frequency must be a positive Numeric" unless frequency.is_a?(Numeric) && frequency.positive?
+
+        frequency.to_f
+      end
+
+      def validate_amplitude!(amplitude)
+        raise InvalidParameterError, "amplitude must be Numeric in 0.0..1.0" unless amplitude.is_a?(Numeric) && amplitude.between?(0.0, 1.0)
+
+        amplitude.to_f
+      end
+
+      def validate_format!(format)
+        raise InvalidParameterError, "format must be Core::Format" unless format.is_a?(Core::Format)
+      end
+
+      def sample_at(index, sample_rate)
+        t = @phase + (index.to_f / sample_rate)
+        raw = case @waveform
+              when :sine then Math.sin(2.0 * Math::PI * @frequency * t)
+              when :square then Math.sin(2.0 * Math::PI * @frequency * t) >= 0 ? 1.0 : -1.0
+              when :sawtooth then (2.0 * ((@frequency * t) % 1.0)) - 1.0
+              when :triangle then (2.0 * ((2.0 * ((@frequency * t) % 1.0)) - 1.0).abs) - 1.0
+              when :white_noise then @random.rand(-1.0..1.0)
+              when :pink_noise then next_pink_noise
+              end
+        (raw * @amplitude).clamp(-1.0, 1.0)
+      end
+
+      # Lightweight pink-noise approximation (Paul Kellet filter).
+      def next_pink_noise
+        white = @random.rand(-1.0..1.0)
+
+        @pink_b0 = (0.99765 * @pink_b0) + (white * 0.0990460)
+        @pink_b1 = (0.96300 * @pink_b1) + (white * 0.2965164)
+        @pink_b2 = (0.57000 * @pink_b2) + (white * 1.0526913)
+        @pink_b3 = (0.7616 * @pink_b3) - (white * 0.5511934)
+        @pink_b4 = (0.8500 * @pink_b4) - (white * 0.7616)
+        @pink_b5 = white * 0.115926
+
+        @pink_b0 + @pink_b1 + @pink_b2 + @pink_b3 + @pink_b4 + @pink_b5 + (white * 0.5362)
+      end
+
+      def reset_pink_noise!
+        @pink_b0 = 0.0
+        @pink_b1 = 0.0
+        @pink_b2 = 0.0
+        @pink_b3 = 0.0
+        @pink_b4 = 0.0
+        @pink_b5 = 0.0
+      end
+
+    end
+  end
+end

data/lib/wavify/errors.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Wavify
+  # Base error class for all Wavify-specific exceptions.
+  class Error < StandardError; end
+
+  # Base class for format and codec-related errors.
+  class FormatError < Error; end
+  # Raised when input/output data is malformed for a supported format.
+  class InvalidFormatError < FormatError; end
+  # Raised when a format is recognized but not supported by the implementation.
+  class UnsupportedFormatError < FormatError; end
+  # Raised when no codec can be selected for an input/output target.
+  class CodecNotFoundError < FormatError; end
+
+  # Base class for processing pipeline failures.
+  class ProcessingError < Error; end
+  # Raised when sample buffer conversion fails.
+  class BufferConversionError < ProcessingError; end
+  # Raised when a streaming operation cannot proceed.
+  class StreamError < ProcessingError; end
+
+  # Base class for DSP parameter/processing errors.
+  class DSPError < Error; end
+  # Raised when method parameters are invalid.
+  class InvalidParameterError < DSPError; end
+
+  # Base class for sequencer and DSL-related errors.
+  class SequencerError < Error; end
+  # Raised when rhythmic pattern notation is invalid.
+  class InvalidPatternError < SequencerError; end
+  # Raised when note/chord notation is invalid.
+  class InvalidNoteError < SequencerError; end
+end

data/lib/wavify/sequencer/engine.rb

@@ -0,0 +1,278 @@
+# frozen_string_literal: true
+
+module Wavify
+  module Sequencer
+    # Schedules sequencer tracks and renders them into audio.
+    class Engine
+      # Default beats-per-bar value used when omitted.
+      DEFAULT_BEATS_PER_BAR = 4
+
+      attr_reader :tempo, :format, :beats_per_bar
+
+      def initialize(tempo:, format: Wavify::Core::Format::CD_QUALITY, beats_per_bar: DEFAULT_BEATS_PER_BAR)
+        @tempo = validate_tempo!(tempo)
+        @format = validate_format!(format)
+        @beats_per_bar = validate_beats_per_bar!(beats_per_bar)
+      end
+
+      # @return [Float] seconds per beat at the current tempo
+      def seconds_per_beat
+        60.0 / @tempo
+      end
+
+      # @return [Float] duration of one bar in seconds
+      def bar_duration_seconds
+        seconds_per_beat * @beats_per_bar
+      end
+
+      def step_duration_seconds(resolution)
+        raise SequencerError, "resolution must be a positive Integer" unless resolution.is_a?(Integer) && resolution.positive?
+
+        bar_duration_seconds / resolution.to_f
+      end
+
+      def timeline_for_track(track, bars:, start_bar: 0)
+        raise SequencerError, "track must be a Sequencer::Track" unless track.is_a?(Track)
+        raise SequencerError, "bars must be a positive Integer" unless bars.is_a?(Integer) && bars.positive?
+        raise SequencerError, "start_bar must be a non-negative Integer" unless start_bar.is_a?(Integer) && start_bar >= 0
+
+        events = []
+        events.concat(schedule_pattern_events(track, bars: bars, start_bar: start_bar)) if track.pattern?
+        events.concat(schedule_note_events(track, bars: bars, start_bar: start_bar)) if track.notes?
+        events.concat(schedule_chord_events(track, bars: bars, start_bar: start_bar)) if track.chords?
+        events.sort_by { |event| [event[:start_time], event[:kind].to_s] }
+      end
+
+      # Builds a combined event timeline for tracks and optional arrangement.
+      #
+      # @param tracks [Array<Wavify::Sequencer::Track>]
+      # @param arrangement [Array<Hash>, nil]
+      # @param default_bars [Integer]
+      # @return [Array<Hash>]
+      def build_timeline(tracks:, arrangement: nil, default_bars: 1)
+        track_map = normalize_tracks(tracks)
+
+        if arrangement
+          build_arranged_timeline(track_map, arrangement)
+        else
+          raise SequencerError, "default_bars must be a positive Integer" unless default_bars.is_a?(Integer) && default_bars.positive?
+
+          events = track_map.values.flat_map do |track|
+            timeline_for_track(track, bars: default_bars)
+          end
+          events.sort_by { |event| [event[:start_time], event[:track].to_s] }
+        end
+      end
+
+      # Renders tracks into a mixed audio object.
+      #
+      # @param tracks [Array<Wavify::Sequencer::Track>]
+      # @param arrangement [Array<Hash>, nil]
+      # @param default_bars [Integer]
+      # @return [Wavify::Audio]
+      def render(tracks:, arrangement: nil, default_bars: 1)
+        track_map = normalize_tracks(tracks)
+        sections = arrangement ? normalize_arrangement(arrangement, track_map) : nil
+
+        rendered_audios = if sections
+                            render_arranged_tracks(track_map, sections)
+                          else
+                            track_map.values.filter_map { |track| render_track_audio(track, bars: default_bars) }
+                          end
+
+        return Wavify::Audio.silence(0.0, format: @format) if rendered_audios.empty?
+
+        Wavify::Audio.mix(*rendered_audios)
+      end
+
+      private
+
+      def normalize_tracks(tracks)
+        list = tracks.is_a?(Array) ? tracks : Array(tracks)
+        raise SequencerError, "tracks must not be empty" if list.empty?
+
+        list.each_with_object({}) do |track, map|
+          raise SequencerError, "track must be a Sequencer::Track" unless track.is_a?(Track)
+
+          map[track.name] = track
+        end
+      end
+
+      def normalize_arrangement(arrangement, track_map)
+        raise SequencerError, "arrangement must be an Array" unless arrangement.is_a?(Array)
+
+        cursor_bar = 0
+        arrangement.map do |section|
+          raise SequencerError, "section must be a Hash" unless section.is_a?(Hash)
+
+          name = section.fetch(:name, "section_#{cursor_bar}").to_sym
+          bars = section.fetch(:bars)
+          raise SequencerError, "section bars must be a positive Integer" unless bars.is_a?(Integer) && bars.positive?
+
+          track_names = Array(section.fetch(:tracks)).map(&:to_sym)
+          raise SequencerError, "section tracks must not be empty" if track_names.empty?
+
+          unknown = track_names - track_map.keys
+          raise SequencerError, "unknown tracks in section #{name}: #{unknown.join(', ')}" unless unknown.empty?
+
+          normalized = { name: name, bars: bars, tracks: track_names, start_bar: cursor_bar }
+          cursor_bar += bars
+          normalized
+        end
+      end
+
+      def build_arranged_timeline(track_map, arrangement)
+        sections = normalize_arrangement(arrangement, track_map)
+        events = sections.flat_map do |section|
+          section[:tracks].flat_map do |track_name|
+            timeline_for_track(track_map.fetch(track_name), bars: section[:bars], start_bar: section[:start_bar])
+          end
+        end
+        events.sort_by { |event| [event[:start_time], event[:track].to_s] }
+      end
+
+      def render_arranged_tracks(track_map, sections)
+        sections.flat_map do |section|
+          section[:tracks].filter_map do |track_name|
+            render_track_audio(track_map.fetch(track_name), bars: section[:bars], start_bar: section[:start_bar])
+          end
+        end
+      end
+
+      def render_track_audio(track, bars:, start_bar: 0)
+        events = timeline_for_track(track, bars: bars, start_bar: start_bar)
+        note_events = events.select { |event| %i[note chord].include?(event[:kind]) }
+        return nil if note_events.empty?
+
+        track_format = @format.channels == 2 ? @format : @format.with(channels: 2)
+        total_end_time = note_events.map { |event| event[:start_time] + event[:duration] }.max || 0.0
+        audio = Wavify::Audio.silence(total_end_time, format: track_format.with(sample_format: :float, bit_depth: 32))
+        mixed = audio.buffer.samples.dup
+
+        note_events.each do |event|
+          frequencies = event[:midi_notes].map { |midi| midi_to_frequency(midi) }
+          note_audio = render_chord_tone(frequencies, event[:duration], track, track_format.with(sample_format: :float, bit_depth: 32))
+          start_frame = (event[:start_time] * track_format.sample_rate).round
+          start_index = start_frame * track_format.channels
+
+          note_audio.buffer.samples.each_with_index do |sample, index|
+            target_index = start_index + index
+            break if target_index >= mixed.length
+
+            mixed[target_index] += sample
+          end
+        end
+
+        mixed.map! { |sample| sample.clamp(-1.0, 1.0) }
+        rendered = Wavify::Audio.new(Wavify::Core::SampleBuffer.new(mixed, track_format.with(sample_format: :float, bit_depth: 32)))
+        rendered = rendered.gain(track.gain_db) if track.gain_db != 0.0
+        rendered = rendered.pan(track.pan_position) if track.pan_position != 0.0
+        rendered = apply_track_effects(rendered, track.effects) if track.effects?
+        rendered.convert(@format)
+      end
+
+      def render_chord_tone(frequencies, duration, track, format)
+        note_audios = frequencies.map do |frequency|
+          tone = Wavify::Audio.tone(frequency: frequency, duration: duration, format: format, waveform: track.waveform)
+          if track.envelope
+            tone.apply(lambda do |buffer|
+              track.envelope.apply(buffer, note_on_duration: duration)
+            end)
+          else
+            tone
+          end
+        end
+
+        Wavify::Audio.mix(*note_audios)
+      end
+
+      def schedule_pattern_events(track, bars:, start_bar:)
+        step_duration = step_duration_seconds(track.pattern.length)
+
+        (0...bars).flat_map do |bar_offset|
+          track.pattern.filter(&:trigger?).map do |step|
+            absolute_bar = start_bar + bar_offset
+            start_time = (absolute_bar * bar_duration_seconds) + (step.index * step_duration)
+            {
+              kind: :trigger,
+              track: track.name,
+              bar: absolute_bar,
+              step_index: step.index,
+              start_time: start_time,
+              duration: step_duration,
+              velocity: step.velocity
+            }
+          end
+        end
+      end
+
+      def schedule_note_events(track, bars:, start_bar:)
+        base_step_duration = step_duration_seconds(track.note_resolution)
+
+        (0...bars).flat_map do |bar_offset|
+          track.note_sequence.each_with_object([]) do |event, result|
+            next if event.rest?
+
+            absolute_bar = start_bar + bar_offset
+            start_time = (absolute_bar * bar_duration_seconds) + (event.index * base_step_duration)
+            result << {
+              kind: :note,
+              track: track.name,
+              bar: absolute_bar,
+              step_index: event.index,
+              start_time: start_time,
+              duration: base_step_duration,
+              midi_notes: [event.midi_note]
+            }
+          end
+        end
+      end
+
+      def schedule_chord_events(track, bars:, start_bar:)
+        progression = track.chord_progression
+        return [] unless progression
+
+        (0...bars).map do |bar_offset|
+          chord = progression[bar_offset % progression.length]
+          absolute_bar = start_bar + bar_offset
+          {
+            kind: :chord,
+            track: track.name,
+            bar: absolute_bar,
+            step_index: 0,
+            start_time: absolute_bar * bar_duration_seconds,
+            duration: bar_duration_seconds,
+            midi_notes: chord.fetch(:midi_notes),
+            chord: chord.fetch(:token)
+          }
+        end
+      end
+
+      def midi_to_frequency(midi_note)
+        440.0 * (2.0**((midi_note - 69) / 12.0))
+      end
+
+      def apply_track_effects(audio, effects)
+        effects.reduce(audio) { |current, effect| current.apply(effect) }
+      end
+
+      def validate_tempo!(tempo)
+        raise SequencerError, "tempo must be a positive Numeric" unless tempo.is_a?(Numeric) && tempo.positive?
+
+        tempo.to_f
+      end
+
+      def validate_format!(format)
+        raise SequencerError, "format must be a Core::Format" unless format.is_a?(Wavify::Core::Format)
+
+        format
+      end
+
+      def validate_beats_per_bar!(beats_per_bar)
+        raise SequencerError, "beats_per_bar must be a positive Integer" unless beats_per_bar.is_a?(Integer) && beats_per_bar.positive?
+
+        beats_per_bar
+      end
+    end
+  end
+end