wavify 0.1.0

data/lib/wavify/sequencer/note_sequence.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module Wavify
+  module Sequencer
+    # Note sequence parser for note/rest/MIDI token notation.
+    class NoteSequence
+      include Enumerable
+
+      # Note-name to semitone offset lookup table.
+      NOTE_OFFSETS = {
+        "C" => 0,
+        "C#" => 1,
+        "DB" => 1,
+        "D" => 2,
+        "D#" => 3,
+        "EB" => 3,
+        "E" => 4,
+        "F" => 5,
+        "F#" => 6,
+        "GB" => 6,
+        "G" => 7,
+        "G#" => 8,
+        "AB" => 8,
+        "A" => 9,
+        "A#" => 10,
+        "BB" => 10,
+        "B" => 11
+      }.freeze
+
+      # Parsed note event (`midi_note` is `nil` for rests).
+      Event = Struct.new(:index, :token, :midi_note, keyword_init: true) do
+        def rest?
+          midi_note.nil?
+        end
+      end
+
+      attr_reader :default_octave, :events, :notation
+
+      def initialize(notation, default_octave: 4)
+        @notation = notation
+        @default_octave = validate_default_octave!(default_octave)
+        @events = parse_events(notation).freeze
+      end
+
+      # Enumerates parsed events.
+      #
+      # @yield [event]
+      # @yieldparam event [Event]
+      # @return [Enumerator]
+      def each(&)
+        return enum_for(:each) unless block_given?
+
+        @events.each(&)
+      end
+
+      # Returns an event at the given index.
+      #
+      # @param index [Integer]
+      # @return [Event, nil]
+      def [](index)
+        @events[index]
+      end
+
+      # @return [Integer] number of parsed events
+      def length
+        @events.length
+      end
+
+      alias size length
+
+      # @return [Array<Integer, nil>] MIDI notes preserving rests as nil
+      def midi_notes
+        @events.map(&:midi_note)
+      end
+
+      # @return [Array<Event>] events excluding rests
+      def note_events
+        @events.reject(&:rest?)
+      end
+
+      private
+
+      def validate_default_octave!(value)
+        raise InvalidNoteError, "default_octave must be an Integer" unless value.is_a?(Integer)
+
+        value
+      end
+
+      def parse_events(notation)
+        raise InvalidNoteError, "note sequence notation must be String" unless notation.is_a?(String)
+
+        tokens = notation.split(/\s+/).reject(&:empty?)
+        raise InvalidNoteError, "note sequence notation must not be empty" if tokens.empty?
+
+        tokens.each_with_index.map do |token, index|
+          Event.new(index: index, token: token, midi_note: parse_token(token))
+        end
+      end
+
+      def parse_token(token)
+        return nil if token == "."
+
+        return parse_midi_number(token) if token.match?(/\A-?\d+\z/)
+
+        parse_note_name(token)
+      end
+
+      def parse_midi_number(token)
+        midi = token.to_i
+        raise InvalidNoteError, "MIDI note out of range (0..127): #{token}" unless midi.between?(0, 127)
+
+        midi
+      end
+
+      def parse_note_name(token)
+        match = token.match(/\A([A-Ga-g])([#b]?)(-?\d+)?\z/)
+        raise InvalidNoteError, "invalid note token: #{token.inspect}" unless match
+
+        note_name = "#{match[1].upcase}#{match[2]}".upcase
+        octave = match[3] ? match[3].to_i : @default_octave
+
+        semitone = NOTE_OFFSETS[note_name]
+        raise InvalidNoteError, "unsupported note token: #{token.inspect}" unless semitone
+
+        midi = ((octave + 1) * 12) + semitone
+        raise InvalidNoteError, "note out of MIDI range: #{token.inspect}" unless midi.between?(0, 127)
+
+        midi
+      end
+    end
+  end
+end

data/lib/wavify/sequencer/pattern.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Wavify
+  module Sequencer
+    # Step-pattern parser (`x`, `X`, `-`, `.`) for trigger sequencing.
+    class Pattern
+      include Enumerable
+
+      # Parsed pattern step value object.
+      Step = Struct.new(:index, :trigger, :accent, :symbol, :velocity, keyword_init: true) do
+        def rest?
+          !trigger
+        end
+
+        def trigger?
+          trigger
+        end
+
+        def accent?
+          accent
+        end
+      end
+
+      attr_reader :resolution, :steps, :notation
+
+      def initialize(notation, resolution: 16)
+        @notation = notation
+        @resolution = validate_resolution!(resolution)
+        @steps = parse_steps(notation).freeze
+      end
+
+      # Enumerates parsed steps.
+      #
+      # @yield [step]
+      # @yieldparam step [Step]
+      # @return [Enumerator]
+      def each(&)
+        return enum_for(:each) unless block_given?
+
+        @steps.each(&)
+      end
+
+      # Returns a step at the given index.
+      #
+      # @param index [Integer]
+      # @return [Step, nil]
+      def [](index)
+        @steps[index]
+      end
+
+      # @return [Integer] number of steps
+      def length
+        @steps.length
+      end
+
+      alias size length
+
+      # @return [Array<Integer>] indices for trigger steps
+      def trigger_indices
+        @steps.select(&:trigger?).map(&:index)
+      end
+
+      # @return [Array<Integer>] indices for accented trigger steps
+      def accented_indices
+        @steps.select(&:accent?).map(&:index)
+      end
+
+      # @return [Array<Step>] copy of parsed steps
+      def to_a
+        @steps.dup
+      end
+
+      private
+
+      def validate_resolution!(value)
+        raise InvalidPatternError, "resolution must be a positive Integer" unless value.is_a?(Integer) && value.positive?
+
+        value
+      end
+
+      def parse_steps(notation)
+        raise InvalidPatternError, "pattern notation must be String" unless notation.is_a?(String)
+
+        chars = notation.each_char.reject { |char| char =~ /\s/ || char == "|" }
+        raise InvalidPatternError, "pattern notation must not be empty" if chars.empty?
+
+        chars.each_with_index.map do |char, index|
+          case char
+          when "x"
+            Step.new(index: index, trigger: true, accent: false, symbol: char, velocity: 0.8)
+          when "X"
+            Step.new(index: index, trigger: true, accent: true, symbol: char, velocity: 1.0)
+          when "-", "."
+            Step.new(index: index, trigger: false, accent: false, symbol: char, velocity: 0.0)
+          else
+            raise InvalidPatternError, "invalid pattern symbol #{char.inspect} at step #{index}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/wavify/sequencer/track.rb

@@ -0,0 +1,298 @@
+# frozen_string_literal: true
+
+module Wavify
+  module Sequencer
+    # Immutable sequencer track definition consumed by {Engine}.
+    class Track
+      # Chord suffix to semitone interval mapping.
+      CHORD_INTERVALS = {
+        "" => [0, 4, 7],
+        "M" => [0, 4, 7],
+        "MAJ" => [0, 4, 7],
+        "MAJ7" => [0, 4, 7, 11],
+        "7" => [0, 4, 7, 10],
+        "M7" => [0, 3, 7, 10],
+        "MIN" => [0, 3, 7],
+        "MIN7" => [0, 3, 7, 10],
+        "MIN9" => [0, 3, 7, 10, 14],
+        "MINOR" => [0, 3, 7],
+        "M7B5" => [0, 3, 6, 10],
+        "M7-5" => [0, 3, 6, 10],
+        "DIM" => [0, 3, 6],
+        "DIM7" => [0, 3, 6, 9],
+        "AUG" => [0, 4, 8],
+        "SUS2" => [0, 2, 7],
+        "SUS4" => [0, 5, 7],
+        "MAJ9" => [0, 4, 7, 11, 14]
+      }.merge(
+        "m" => [0, 3, 7],
+        "m7" => [0, 3, 7, 10],
+        "m9" => [0, 3, 7, 10, 14],
+        "maj7" => [0, 4, 7, 11],
+        "maj9" => [0, 4, 7, 11, 14],
+        "sus2" => [0, 2, 7],
+        "sus4" => [0, 5, 7],
+        "dim" => [0, 3, 6],
+        "dim7" => [0, 3, 6, 9],
+        "aug" => [0, 4, 8]
+      ).freeze
+
+      attr_reader :name, :pattern, :note_sequence, :chord_progression, :waveform, :gain_db, :pan_position,
+                  :pattern_resolution, :note_resolution, :default_octave, :envelope, :effects
+
+      def initialize(name, **options)
+        @name = validate_name!(name)
+        pattern_resolution = options.fetch(:pattern_resolution, 16)
+        note_resolution = options.fetch(:note_resolution, 8)
+        default_octave = options.fetch(:default_octave, 4)
+
+        @pattern_resolution = validate_resolution!(pattern_resolution, :pattern_resolution)
+        @note_resolution = validate_resolution!(note_resolution, :note_resolution)
+        @default_octave = validate_default_octave!(default_octave)
+        @waveform = options.fetch(:waveform, :sine).to_sym
+        @gain_db = validate_numeric!(options.fetch(:gain_db, 0.0), :gain_db).to_f
+        @pan_position = validate_pan!(options.fetch(:pan_position, 0.0))
+        @envelope = validate_envelope!(options[:envelope])
+        @effects = validate_effects!(options.fetch(:effects, []))
+
+        @pattern = coerce_pattern(options[:pattern])
+        @note_sequence = coerce_note_sequence(options[:note_sequence])
+        @chord_progression = coerce_chord_progression(options[:chord_progression])
+      end
+
+      # Returns a copy with a new pattern.
+      #
+      # @param pattern [Pattern, String]
+      # @return [Track]
+      def with_pattern(pattern)
+        copy(pattern: pattern)
+      end
+
+      # Returns a copy with a new note sequence.
+      #
+      # @param notes [NoteSequence, String]
+      # @param default_octave [Integer]
+      # @return [Track]
+      def with_notes(notes, default_octave: @default_octave)
+        copy(note_sequence: notes, default_octave: default_octave)
+      end
+
+      # Returns a copy with a new chord progression.
+      #
+      # @param chords [String, Array<String>]
+      # @param default_octave [Integer]
+      # @return [Track]
+      def with_chords(chords, default_octave: @default_octave)
+        copy(chord_progression: chords, default_octave: default_octave)
+      end
+
+      # Returns a copy with a different oscillator waveform.
+      #
+      # @param waveform [Symbol, String]
+      # @return [Track]
+      def with_synth(waveform)
+        copy(waveform: waveform)
+      end
+
+      # Returns a copy with updated gain in dB.
+      #
+      # @param db [Numeric]
+      # @return [Track]
+      def with_gain(db)
+        copy(gain_db: db)
+      end
+
+      # Returns a copy with updated pan position.
+      #
+      # @param position [Numeric]
+      # @return [Track]
+      def with_pan(position)
+        copy(pan_position: position)
+      end
+
+      # Returns a copy with an envelope object.
+      #
+      # @param envelope [Wavify::DSP::Envelope, nil]
+      # @return [Track]
+      def with_envelope(envelope)
+        copy(envelope: envelope)
+      end
+
+      # Returns a copy with effect processors.
+      #
+      # @param effects [Array<Object>]
+      # @return [Track]
+      def with_effects(effects)
+        copy(effects: effects)
+      end
+
+      def event_sources?
+        pattern? || notes? || chords?
+      end
+
+      def pattern?
+        !@pattern.nil?
+      end
+
+      def notes?
+        !@note_sequence.nil?
+      end
+
+      def chords?
+        !@chord_progression.nil? && !@chord_progression.empty?
+      end
+
+      def effects?
+        !@effects.empty?
+      end
+
+      # Copy constructor used by immutable builder helpers.
+      #
+      # @return [Track]
+      def copy(**overrides)
+        self.class.new(
+          overrides.fetch(:name, @name),
+          pattern: overrides.fetch(:pattern, @pattern),
+          note_sequence: overrides.fetch(:note_sequence, @note_sequence),
+          chord_progression: overrides.fetch(:chord_progression, @chord_progression),
+          waveform: overrides.fetch(:waveform, @waveform),
+          gain_db: overrides.fetch(:gain_db, @gain_db),
+          pan_position: overrides.fetch(:pan_position, @pan_position),
+          pattern_resolution: overrides.fetch(:pattern_resolution, @pattern_resolution),
+          note_resolution: overrides.fetch(:note_resolution, @note_resolution),
+          default_octave: overrides.fetch(:default_octave, @default_octave),
+          envelope: overrides.fetch(:envelope, @envelope),
+          effects: overrides.fetch(:effects, @effects)
+        )
+      end
+
+      # Parses chord notation using this track's default octave.
+      #
+      # @param chords [String, Array<String>]
+      # @return [Array<Hash>]
+      def parse_chords(chords)
+        self.class.parse_chords(chords, default_octave: @default_octave)
+      end
+
+      def self.parse_chords(chords, default_octave: 4)
+        tokens = case chords
+                 when String
+                   chords.split(/\s+/)
+                 when Array
+                   chords.map(&:to_s)
+                 else
+                   raise InvalidNoteError, "chords must be String or Array"
+                 end.reject(&:empty?)
+
+        raise InvalidNoteError, "chords must not be empty" if tokens.empty?
+
+        tokens.map { |token| parse_chord_token(token, default_octave: default_octave) }
+      end
+
+      def self.parse_chord_token(token, default_octave:)
+        match = token.match(/\A([A-Ga-g])([#b]?)(.*)\z/)
+        raise InvalidNoteError, "invalid chord token: #{token.inspect}" unless match
+
+        root_name = "#{match[1].upcase}#{match[2]}"
+        suffix = match[3].to_s
+        suffix_key = normalize_chord_suffix(suffix)
+        intervals = CHORD_INTERVALS[suffix_key] || CHORD_INTERVALS[suffix]
+        raise InvalidNoteError, "unsupported chord quality: #{suffix.inspect}" unless intervals
+
+        root_midi = NoteSequence.new("#{root_name}#{default_octave}", default_octave: default_octave).midi_notes.first
+        {
+          token: token,
+          root_midi: root_midi,
+          midi_notes: intervals.map { |interval| root_midi + interval }
+        }
+      end
+
+      def self.normalize_chord_suffix(suffix)
+        value = suffix.to_s
+        return "" if value.empty?
+
+        if value.start_with?("m") && !value.start_with?("maj")
+          "m#{value[1..]}"
+        else
+          value.downcase
+        end
+      end
+
+      private_class_method :normalize_chord_suffix
+
+      private
+
+      def validate_name!(name)
+        value = name.to_sym
+        raise SequencerError, "track name must not be empty" if value.to_s.empty?
+
+        value
+      rescue NoMethodError
+        raise SequencerError, "track name must be Symbol/String: #{name.inspect}"
+      end
+
+      def validate_resolution!(value, name)
+        raise SequencerError, "#{name} must be a positive Integer" unless value.is_a?(Integer) && value.positive?
+
+        value
+      end
+
+      def validate_default_octave!(value)
+        raise SequencerError, "default_octave must be an Integer" unless value.is_a?(Integer)
+
+        value
+      end
+
+      def validate_numeric!(value, name)
+        raise SequencerError, "#{name} must be Numeric" unless value.is_a?(Numeric)
+
+        value
+      end
+
+      def validate_pan!(value)
+        raise SequencerError, "pan_position must be Numeric in -1.0..1.0" unless value.is_a?(Numeric) && value.between?(-1.0, 1.0)
+
+        value.to_f
+      end
+
+      def validate_envelope!(value)
+        return nil if value.nil?
+        raise SequencerError, "envelope must be a Wavify::DSP::Envelope" unless value.is_a?(Wavify::DSP::Envelope)
+
+        value
+      end
+
+      def validate_effects!(value)
+        effects = Array(value)
+        unless effects.all? { |effect| effect.respond_to?(:process) || effect.respond_to?(:apply) || effect.respond_to?(:call) }
+          raise SequencerError, "effects must respond to :process, :apply, or :call"
+        end
+
+        effects.freeze
+      end
+
+      def coerce_pattern(pattern)
+        return nil if pattern.nil?
+        return pattern if pattern.is_a?(Pattern)
+
+        Pattern.new(pattern, resolution: @pattern_resolution)
+      end
+
+      def coerce_note_sequence(note_sequence)
+        return nil if note_sequence.nil?
+        return note_sequence if note_sequence.is_a?(NoteSequence)
+
+        NoteSequence.new(note_sequence, default_octave: @default_octave)
+      end
+
+      def coerce_chord_progression(chord_progression)
+        return nil if chord_progression.nil?
+        if chord_progression.is_a?(Array) && chord_progression.all? { |item| item.is_a?(Hash) && item[:midi_notes] }
+          return chord_progression
+        end
+
+        self.class.parse_chords(chord_progression, default_octave: @default_octave)
+      end
+    end
+  end
+end

data/lib/wavify/sequencer.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "sequencer/pattern"
+require_relative "sequencer/note_sequence"
+require_relative "sequencer/track"
+require_relative "sequencer/engine"
+
+module Wavify
+  # Sequencer primitives for pattern/note/chord scheduling and rendering.
+  module Sequencer
+  end
+end

data/lib/wavify/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Wavify
+  # Gem version string (Semantic Versioning).
+  VERSION = "0.1.0"
+end

data/lib/wavify.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "wavify/version"
+require_relative "wavify/errors"
+require_relative "wavify/core/format"
+require_relative "wavify/core/duration"
+require_relative "wavify/core/sample_buffer"
+require_relative "wavify/core/stream"
+require_relative "wavify/codecs/base"
+require_relative "wavify/codecs/raw"
+require_relative "wavify/codecs/wav"
+require_relative "wavify/codecs/flac"
+require_relative "wavify/codecs/ogg_vorbis"
+require_relative "wavify/codecs/aiff"
+require_relative "wavify/codecs/registry"
+require_relative "wavify/dsp/oscillator"
+require_relative "wavify/dsp/envelope"
+require_relative "wavify/dsp/filter"
+require_relative "wavify/dsp/effects"
+require_relative "wavify/sequencer"
+require_relative "wavify/audio"
+require_relative "wavify/dsl"
+
+##
+# Wavify is a pure Ruby audio processing toolkit with immutable transforms,
+# multiple codecs, DSP primitives, and a small sequencing DSL.
+module Wavify
+end

data/tools/fixture_writer.rb

@@ -0,0 +1,85 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "fileutils"
+require "yaml"
+require "tempfile"
+
+require_relative "../lib/wavify"
+
+module Wavify
+  module Tools
+    class FixtureWriter
+      def initialize(yaml_dir:, audio_dir:)
+        @yaml_dir = yaml_dir
+        @audio_dir = audio_dir
+      end
+
+      def run
+        FileUtils.mkdir_p(@audio_dir)
+        yaml_files.each { |path| write_file(path) }
+      end
+
+      private
+
+      def yaml_files
+        Dir.glob(File.join(@yaml_dir, "*.yml")).sort
+      end
+
+      def write_file(path)
+        yaml = YAML.safe_load_file(path)
+        fixtures = yaml.fetch("fixtures")
+        fixtures.each { |fixture| write_fixture(fixture) }
+      end
+
+      def write_fixture(fixture)
+        name = fixture.fetch("name")
+        kind = fixture.fetch("kind", "valid")
+        output_path = File.join(@audio_dir, name)
+
+        case kind
+        when "valid"
+          write_valid_fixture(output_path, fixture)
+        when "invalid_no_riff"
+          File.binwrite(output_path, "BROKEN")
+        when "invalid_truncated"
+          write_truncated_fixture(output_path, fixture)
+        else
+          raise Wavify::InvalidParameterError, "unsupported fixture kind: #{kind.inspect}"
+        end
+      end
+
+      def write_valid_fixture(path, fixture)
+        format = build_format(fixture.fetch("format"))
+        samples = fixture.fetch("samples")
+        buffer = Wavify::Core::SampleBuffer.new(samples, format)
+        Wavify::Codecs::Wav.write(path, buffer)
+      end
+
+      def write_truncated_fixture(path, fixture)
+        Tempfile.create(["wavify_fixture", ".wav"]) do |tmp|
+          write_valid_fixture(tmp.path, fixture)
+          bytes = File.binread(tmp.path)
+          truncated = bytes[0, [bytes.bytesize / 2, 1].max]
+          File.binwrite(path, truncated)
+        end
+      end
+
+      def build_format(params)
+        Wavify::Core::Format.new(
+          channels: params.fetch("channels"),
+          sample_rate: params.fetch("sample_rate"),
+          bit_depth: params.fetch("bit_depth"),
+          sample_format: params.fetch("sample_format", "pcm").to_sym
+        )
+      end
+    end
+  end
+end
+
+root = File.expand_path("..", __dir__)
+writer = Wavify::Tools::FixtureWriter.new(
+  yaml_dir: File.join(root, "spec/fixtures/yaml"),
+  audio_dir: File.join(root, "spec/fixtures/audio")
+)
+writer.run