outro_rails 0.1.0

data/lib/outro_rails/generators/chord_seed_generator.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+require "outro_rails/theory"
+
+module OutroRails
+  # Generates seed data for OutroRails::Chord for a given root.
+  class ChordSeedGenerator
+    # Shorthand for the theory vocabulary used to build intervals and symbols
+    Vocabulary = Theory::ChordVocabulary
+
+    # Alterations on dominant chords to generate
+    ALTERED_DOMINANTS = {
+      '7':  [
+              %i[b5],
+              %i[#5],
+              %i[b9],
+              %i[#9],
+              %i[#11],
+              %i[b13],
+              %i[b5 b9],
+              %i[b5 #9],
+              %i[#5 b9],
+              %i[#5 #9],
+              %i[b9 b13],
+              %i[#9 b13],
+              %i[b9 #11]
+            ],
+      '9':  [
+              %i[#11],
+              %i[b13]
+            ],
+      '13': [
+              %i[b9],
+              %i[#9],
+              %i[#11]
+            ]
+    }.freeze
+
+    # Added tones to generate { quality: { extension: [added_tone] } }
+    ADDED_TONE_POLICY = {
+      major:  {
+                base: %i[add2 add4 add9 add11 add13]
+              },
+      minor:  {
+                base: %i[add2 add4 add9 add11 add13],
+                '7':  %i[add11]
+              }
+    }.freeze
+
+    # The parsed Theory::NoteName every generated chord is built from
+    attr_reader :root
+
+    # Parses the root note name, optionally verifying it against an expected
+    # pitch class. Raises ArgumentError when the two disagree.
+    def initialize(root_name:, root_pitch_class: nil)
+      @root = Theory::NoteName.parse(root_name)
+
+      if root_pitch_class && Integer(root_pitch_class) != @root.pitch_class
+        raise ArgumentError,
+              "#{root} has pitch class #{root.pitch_class}, " \
+              "specified #{root_pitch_class}"
+      end
+    end
+
+    # The root spelled as written, e.g. "Bb"
+    def root_name
+      root.to_s
+    end
+
+    # The root's pitch class, 0-11
+    def root_pitch_class
+      root.pitch_class
+    end
+
+    # Builds every chord row for this root: each base quality, its permitted
+    # extensions, the altered dominants, and the allowed added tones.
+    # Raises if the result contains duplicate symbols or interval sets.
+    def chords
+      rows = []
+
+      Vocabulary::QUALITIES.each do |quality, base|
+        rows << build(quality, nil, [], [], base)
+
+        Vocabulary::EXTENSIONS.each do |extension, spec|
+          next unless spec[:qualities].include?(quality)
+
+          rows << build(quality,
+                        extension,
+                        [],
+                        [],
+                        Vocabulary.merge(base, spec[:add]))
+        end
+      end
+
+      ALTERED_DOMINANTS.each do |extension, alteration_sets|
+        base = Vocabulary.intervals(quality: :major, extension: extension)
+
+        alteration_sets.each do |alterations|
+          rows << build(:major,
+                        extension,
+                        alterations,
+                        [],
+                        Vocabulary.apply_alterations(base, alterations))
+        end
+      end
+
+      ADDED_TONE_POLICY.each do |quality, by_extension|
+        by_extension.each do |extension_key, tones|
+          extension = extension_key == :base ? nil : extension_key
+          base = Vocabulary.intervals(quality: quality, extension: extension)
+
+          tones.each do |tone|
+            interval = Vocabulary::ADDED_TONE_INTERVALS.fetch(tone)
+            pitch_classes = Vocabulary.pitch_classes(base)
+
+            next if pitch_classes.include?(
+              interval % Theory::Interval::SEMITONES_PER_OCTAVE
+            )
+
+            rows << build(
+              quality,
+              extension,
+              [],
+              [ tone ],
+              (base + [interval]).sort
+            )
+          end
+        end
+      end
+
+      assert_no_duplicates!(rows)
+      rows
+    end
+
+    # Renders all chords as a YAML fixture fragment
+    def to_yaml
+      chords.map { |chord| entry_yaml(chord) }.join("\n")
+    end
+
+    private
+
+    # Assembles a single chord row, deriving its symbol and slug from the
+    # quality, extension, alterations and added tones
+    def build(quality, extension, alterations, added_tones, intervals)
+      symbol = Vocabulary.symbol(
+        root_name: root_name,
+        quality: quality,
+        extension: extension,
+        alterations: alterations,
+        added_tones: added_tones
+      )
+
+      {
+        symbol:      symbol,
+        slug:        Vocabulary.slug(symbol),
+        quality:     quality,
+        extension:   extension,
+        alterations: alterations,
+        added_tones: added_tones,
+        intervals:   intervals
+      }
+    end
+
+    # Raises if two rows share a symbol, or if two differently named rows
+    # spell the same set of intervals
+    def assert_no_duplicates!(rows)
+      dupe_symbols = rows
+        .group_by { |chord| chord[:symbol] }
+        .select { |_, group| group.size > 1 }
+        .keys
+
+      if dupe_symbols.any?
+        raise "Duplicate symbols generated: #{dupe_symbols.join(', ')}"
+      end
+
+      dupe_intervals = rows
+        .group_by { |chord| chord[:intervals] }
+        .select { |_, group| group.size > 1 }
+        .values
+        .map do |group|
+          group
+            .map { |chord| chord[:symbol] }
+            .join(" = ")
+        end
+
+      if dupe_intervals.any?
+        raise "Chords with identical intervals: #{dupe_intervals.join('; ')}"
+      end
+    end
+
+    # Renders one chord row as a YAML list entry, omitting empty optional keys
+    def entry_yaml(chord)
+      lines = ["- symbol: '#{chord[:symbol]}'"]
+      lines << "  slug: '#{chord[:slug]}'"
+      lines << "  root_name: '#{root_name}'"
+      lines << "  root_pitch_class: #{root_pitch_class}"
+      lines << "  quality: #{chord[:quality]}"
+      lines << "  extension: '#{chord[:extension]}'" if chord[:extension]
+
+      if chord[:alterations].any?
+        alterations = chord[:alterations]
+          .map { |alteration| "'#{alteration}'" }
+          .join(", ")
+
+        lines << "  alterations: [#{alterations}]"
+      end
+
+      if chord[:added_tones].any?
+        added_tones = chord[:added_tones].join(", ")
+        lines << "  added_tones: [#{added_tones}]"
+      end
+
+      intervals = chord[:intervals].join(", ")
+      lines << "  intervals: [#{intervals}]"
+
+      lines.join("\n") + "\n"
+    end
+  end
+end

data/lib/outro_rails/generators/guitar_voicing_generator.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+require "outro_rails/theory"
+require "outro_rails/instruments/guitar"
+require "outro_rails/instruments/guitar/chord_shapes"
+require "outro_rails/generators/voicing_seed_writer"
+
+module OutroRails
+  # Generates complete guitar voicing seed entries for a chord entry
+  # (a hash loaded from db/seeds/chords/*.yml), using the shape library in
+  # Instruments::Guitar::ChordShapes.
+  #
+  # Voicings are ordered from the top of the neck down:
+  #
+  #   1. the open chord, when one exists for this root
+  #   2. its bass extensions - slash voicings that walk the shape down
+  #      toward string 6
+  #   3. every movable shape, sorted by starting fret
+  #
+  # Chords with no shapes defined (or with alterations/added tones) are
+  # reported as unsupported so callers can fall back to stubs.
+  class GuitarVoicingGenerator
+    include VoicingSeedWriter
+
+    # Shorthand for the guitar shape library this generator draws grips from
+    Shapes = Instruments::Guitar::ChordShapes
+
+    # A five-fret display window, like the hand position it represents.
+    FRET_WINDOW = 4
+
+    # Sort ranks within a starting fret: open grips first, then their
+    # slash extensions, then barred shapes.
+    OPEN_RANK = 0
+    EXTENSION_RANK = 1
+    MOVABLE_RANK = 2
+
+    # One candidate grip: its { string => fret } map plus the rank and
+    # tie-breaking order used to sort voicings within a starting fret.
+    Voicing = Struct.new(:frets, :rank, :order, keyword_init: true)
+
+    # The instrument supplying string count and tuning
+    attr_reader :guitar
+
+    # Takes a chord seed hash and the instrument to voice it on
+    def initialize(chord, guitar: Instruments::Guitar.new)
+      @chord = chord
+      @guitar = guitar
+    end
+
+    # True when shapes exist for this chord. Altered and added-tone chords
+    # are out of scope for the shape library.
+    def supported?
+      Array(chord["alterations"]).empty? &&
+        Array(chord["added_tones"]).empty? &&
+        !shapes.nil?
+    end
+
+    # Renders every voicing as a YAML fixture fragment, numbering positions
+    # from 1. Raises unless the chord is supported.
+    def to_yaml
+      raise ArgumentError,
+            "no guitar shapes defined for #{symbol}" unless supported?
+
+      voicings
+        .each_with_index
+        .map { |voicing, index| entry_yaml(voicing, index + 1) }
+        .join("\n")
+    end
+
+    private
+
+    # The shape definitions for this chord's quality and extension, or nil
+    def shapes
+      Shapes.for(quality: chord.fetch("quality"), extension: chord["extension"])
+    end
+
+    # Power chords have no third, so they get no slash extensions
+    def power_chord?
+      chord.fetch("quality").to_sym == :power
+    end
+
+    # Chord-tone NoteNames keyed by pitch class, spelled from the root.
+    def names_by_pitch_class
+      @names_by_pitch_class ||= chord.fetch("intervals").to_h do |interval|
+        pitch_class =
+          (root.pitch_class + interval) % Theory::Interval::SEMITONES_PER_OCTAVE
+
+        [ pitch_class, root.at_interval(interval) ]
+      end
+    end
+
+    # Every distinct voicing for this chord, ordered up the neck and then by
+    # rank (open, extension, movable)
+    def voicings
+      list = shapes.flat_map { |shape| voicings_for(shape) }
+
+      list
+        .uniq { |voicing| voicing.frets }
+        .sort_by do |voicing|
+          [
+            start_fret(voicing.frets),
+            voicing.rank,
+            voicing.order
+          ]
+        end
+    end
+
+    # The voicings one shape yields on this root: shifting and string
+    # dropping are ChordShapes' job (#positions); this class only ranks the
+    # result and grows open grips downward.
+    def voicings_for(shape)
+      frets = Shapes.positions(shape, root, guitar: guitar).to_h
+
+      if Shapes.root_offset(shape, root, guitar: guitar).zero?
+        open = Voicing.new(frets: frets, rank: OPEN_RANK, order: 0)
+        extensions = power_chord? ? [] : bass_extensions(frets)
+        [ open, *extensions ]
+      else
+        [ Voicing.new(frets: frets, rank: MOVABLE_RANK, order: 0) ]
+      end
+    end
+
+    # Slash voicings for an open chord that doesn't reach string 6: extend
+    # the shape one lower string at a time with chord tones playable in the
+    # open position, e.g. open D => D/A (5 strings) => D/F# (6 strings).
+    def bass_extensions(open_frets)
+      extensions = []
+      frontier = [ open_frets ]
+
+      ((open_frets.keys.max + 1)..guitar.string_count).each do |string|
+        basses = (0..Shapes::OPEN_BASS_MAX_FRET).select do |fret|
+          names_by_pitch_class.key?(guitar.pitch_class_at(string, fret))
+        end
+        break if basses.empty?
+
+        frontier = basses.flat_map do |fret|
+          frontier.map do |frets|
+            frets.merge(string => fret)
+          end
+        end
+        extensions.concat(frontier)
+      end
+
+      extensions
+        .uniq { |frets| bass_pitch_class(frets) }
+        .each_with_index.map do |frets, index|
+          Voicing.new(frets: frets, rank: EXTENSION_RANK, order: index)
+        end
+    end
+
+    # Pitch class of the lowest sounding string, i.e. the slash bass
+    def bass_pitch_class(frets)
+      string, fret = fret_pairs(frets).first
+      guitar.pitch_class_at(string, fret)
+    end
+
+    # Frets as [string, fret] pairs, low string (6) to high (1).
+    def fret_pairs(frets)
+      frets.sort_by { |string, _| -string }
+    end
+
+    # 0 means an open string, matching the MIDI convention: an open-string
+    # voicing's window starts at the nut (0), not fret 1.
+    def start_fret(frets)
+      frets.values.min
+    end
+
+    # Renders one voicing as a seed entry: its notes low to high plus the
+    # fret window and highlighted positions for the diagram.
+    def entry_yaml(voicing, position)
+      pairs = fret_pairs(voicing.frets)
+      names = pairs.map do |string, fret|
+                names_by_pitch_class.fetch(
+                  guitar.pitch_class_at(string, fret)
+                )
+              end
+      start = start_fret(voicing.frets)
+
+      highlight_frets = pairs
+        .map { |string, fret| "[#{string}, #{fret}]" }
+        .join(", ")
+
+      voicing_entry_yaml(
+        instrument: :guitar,
+        bass_name: names.first,
+        position: position,
+        notes: names,
+        display_lines: [
+          "    start_fret: #{start}",
+          "    end_fret: #{start + FRET_WINDOW}",
+          "    highlight_frets: [#{highlight_frets}]"
+        ]
+      )
+    end
+  end
+end

data/lib/outro_rails/generators/voicing_seed_entry.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module OutroRails
+  # Whether a voicing seed entry (a hash loaded from
+  # db/seeds/chord_voicings/*.yml) is complete enough to become a
+  # ChordVoicing record. Stub files intentionally ship with blank fields
+  # for a human to fill in by hand - see VoicingStubGenerator - and those
+  # blanks must not reach the database as nil columns.
+  #
+  # Only guitar entries can be incomplete this way: piano stubs are always
+  # fully computed.
+  module VoicingSeedEntry
+    module_function
+
+    # True when the entry is safe to load. Non-guitar instruments pass
+    # straight through; guitar entries are checked for filled-in diagram data.
+    def complete?(entry)
+      return true unless entry["instrument"].to_s == "guitar"
+
+      guitar_display_data_complete?(entry["display_data"])
+    end
+
+    # A guitar diagram is complete only with both fret bounds and at least
+    # one highlight, each a fully populated [string, fret] pair.
+    def guitar_display_data_complete?(display_data)
+      return false if display_data.nil?
+
+      frets = display_data["highlight_frets"]
+      return false if display_data["start_fret"].nil?
+      return false if display_data["end_fret"].nil?
+      return false if frets.nil? || frets.empty?
+
+      frets.all? do |pair|
+        valid_pair = pair.is_a?(Array) && pair.size == 2
+        valid_pair && !pair[0].nil? && !pair[1].nil?
+      end
+    end
+
+    # Internal helper - the public surface is #complete?.
+    private_class_method :guitar_display_data_complete?
+  end
+end

data/lib/outro_rails/generators/voicing_seed_writer.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "outro_rails/theory"
+
+module OutroRails
+  # Shared behavior for generators that write chord-voicing seed YAML from
+  # a chord entry (a hash loaded from db/seeds/chords/*.yml): the chord
+  # readers, the slash-symbol rule, and the entry envelope every voicing
+  # shares. Including classes set @chord and supply the instrument-specific
+  # display_data lines.
+  module VoicingSeedWriter
+    # The chord seed entry the including class was built from
+    attr_reader :chord
+
+    # The chord's symbol as spelled in the seed data, e.g. "Cmaj7"
+    def symbol
+      chord.fetch("symbol")
+    end
+
+    # The chord's root as a Theory::NoteName, parsed once and memoized
+    def root
+      @root ||= Theory::NoteName.parse(chord.fetch("root_name"))
+    end
+
+    private
+
+    # "C" when the bass is the root, "C/E" otherwise.
+    def voicing_symbol(bass_name)
+      bass_name == root ? symbol : "#{symbol}/#{bass_name}"
+    end
+
+    # One seed entry: the fields every voicing carries, then the
+    # instrument-specific display_data lines supplied by the caller.
+    def voicing_entry_yaml(instrument:,
+                           bass_name:,
+                           position:,
+                           notes:,
+                           display_lines:)
+      lines = [
+        "- chord_symbol: '#{symbol}'",
+        "  instrument: #{instrument}",
+        "  symbol: '#{voicing_symbol(bass_name)}'",
+        "  bass_name: '#{bass_name}'",
+        "  bass_pitch_class: #{bass_name.pitch_class}",
+        "  position: #{position}",
+        "  notes: [#{notes.join(', ')}]",
+        "  display_data:"
+      ]
+      lines.concat(display_lines)
+      lines.join("\n") + "\n"
+    end
+  end
+end

data/lib/outro_rails/generators/voicing_stub_generator.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require "outro_rails/theory"
+require "outro_rails/instruments/guitar"
+require "outro_rails/instruments/piano"
+require "outro_rails/generators/voicing_seed_writer"
+
+module OutroRails
+  # Builds stub voicing seed files for a chord entry
+  # (a hash loaded from db/seeds/chords/*.yml).
+  class VoicingStubGenerator
+    include VoicingSeedWriter
+
+    # The instruments stubs can be generated for, as symbols - the rake
+    # task iterates this list and branches on `instrument == :guitar`.
+    INSTRUMENTS = OutroRails::Instruments::ENUM_VALUES.keys
+
+    # Piano stubs place the first note in the octave above this pitch.
+    LOWEST_C_MIDI = Theory::Pitch.parse("C3").midi
+
+    # Takes the chord seed entry to generate stubs for
+    def initialize(chord)
+      @chord = chord
+    end
+
+    # Seed filename for one instrument, e.g. "c-major-7-piano.yml"
+    def filename(instrument)
+      "#{chord.fetch('slug')}-#{instrument}.yml"
+    end
+
+    # That filename under the root's directory, e.g. "c/c-major-7-piano.yml"
+    def relative_path(instrument)
+      File.join(root.path_slug, filename(instrument))
+    end
+
+    # Normalized chord tones, e.g. E7#9 => [E, G#, B, D, F##->G]
+    def note_names
+      chord.fetch("intervals").map { |interval| root.at_interval(interval) }
+    end
+
+    # Piano: one entry per inversion
+    # Guitar: a single root-position stub to fill in manually
+    def stub_yaml(instrument)
+      instrument = instrument.to_sym
+      unless INSTRUMENTS.include?(instrument)
+        raise ArgumentError,
+              "unknown instrument #{instrument.inspect} " \
+              "(expected #{INSTRUMENTS.join(' or ')})"
+      end
+
+      case instrument
+      when :piano
+        chord_tones.each_index.map do |position|
+          entry_yaml(instrument, chord_tones.rotate(position), position + 1)
+        end.join("\n")
+      when :guitar
+        entry_yaml(instrument, chord_tones)
+      end
+    end
+
+    private
+
+    # [NoteName, interval] pairs in chord order.
+    def chord_tones
+      @chord_tones ||= note_names.zip(chord.fetch("intervals"))
+    end
+
+    # Renders one voicing entry, taking its bass from the first tone
+    def entry_yaml(instrument, tones, position = 1)
+      voicing_entry_yaml(
+        instrument: instrument,
+        bass_name: tones.first.first,
+        position: position,
+        notes: tones.map(&:first),
+        display_lines: display_data_lines(instrument, tones)
+      )
+    end
+
+    # The display_data block for one voicing: a computed keyboard range and
+    # note list for piano, or blank fret fields for a human to fill in.
+    def display_data_lines(instrument, tones)
+      case instrument
+      when :piano
+        pitched = pitched_tones(tones)
+        low, high = Instruments::Piano.display_range(
+          pitched.map(&:last), prefer: preferred_accidentals(tones)
+        )
+
+        lines = [ "    range: [#{low}, #{high}]" ]
+        lines << "    notes: [#{pitched.map(&:first).join(', ')}]"
+        lines << "    note: '#{display_note}'" if display_note
+        lines
+      when :guitar
+        [
+          "    start_fret: ",
+          "    end_fret: ",
+          "    highlight_frets: [[6, ], [5, ], [4, ], [3, ], [2, ], [1, ]]"
+        ]
+      end
+    end
+
+    # Assigns octaves to notes so the voicing starts in the octave above
+    # LOWEST_C_MIDI, stacking each tone in the first octave above the last.
+    # Returns [written Pitch, sounding Pitch] pairs, e.g. [Cb4, B3].
+    def pitched_tones(tones)
+      midi = nil
+
+      tones.map do |name, interval|
+        pitch_class =
+          (root.pitch_class + interval) % Theory::Interval::SEMITONES_PER_OCTAVE
+
+        midi =
+          if midi.nil?
+            LOWEST_C_MIDI + pitch_class
+          else
+            step =
+              (pitch_class - midi) % Theory::Interval::SEMITONES_PER_OCTAVE
+
+            midi + (
+              step.zero? ? Theory::Interval::OCTAVE : step
+            )
+          end
+
+        sounding_pitch = Theory::Pitch.sounding(name, midi)
+        written_pitch = Theory::Pitch.from_midi(midi)
+
+        [ sounding_pitch, written_pitch ]
+      end
+    end
+
+    # Playing advice for the crowded extensions: which tones are usually
+    # dropped from an 11th or 13th chord. Nil when there's nothing to say.
+    def display_note
+      case chord["extension"]
+      when "11"
+        third = note_for_interval(4, 3)
+        "To avoid dissonance the third (#{third}) is normally omitted." if third
+      when "13"
+        omittable = {
+          fifth: 7,
+          ninth: 14,
+          eleventh: 17
+        }.filter_map do |degree, interval|
+          name = note_for_interval(interval)
+
+          "#{degree} (#{name})" if name
+        end
+
+        if omittable.any?
+          "Some notes (#{join_and_or(omittable)}) can be omitted."
+        end
+      end
+    end
+
+    # The chord tone at the first of the candidate intervals present.
+    def note_for_interval(*candidates)
+      candidates.each do |interval|
+        tone = chord_tones.find { |_, i| i == interval }
+        return tone.first if tone
+      end
+      nil
+    end
+
+    # Joins a list into prose, e.g. "a, b and/or c"
+    def join_and_or(parts)
+      return parts.first if parts.size == 1
+
+      "#{parts[0..-2].join(', ')} and/or #{parts.last}"
+    end
+
+    # Spells the keyboard range with sharps if the chord uses any, else flats
+    def preferred_accidentals(tones)
+      Theory::NoteName.preferred_accidentals(tones.map(&:first))
+    end
+  end
+end