outro_rails 0.1.0

data/lib/outro_rails/theory/chord_vocabulary.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+module OutroRails
+  module Theory
+    # The chord vocabulary including which qualities exist, which
+    # extensions/alterations/added tones apply to them, the intervals they
+    # contribute, and how the combinations are symbolized.
+    module ChordVocabulary
+      # Qualities mapped to their intervals.
+      QUALITIES = {
+        major:       [ 0, 4, 7 ],
+        minor:       [ 0, 3, 7 ],
+        diminished:  [ 0, 3, 6 ],
+        augmented:   [ 0, 4, 8 ],
+        suspended_2: [ 0, 2, 7 ],
+        suspended_4: [ 0, 5, 7 ],
+        power:       [ 0, 7 ]
+      }.freeze
+
+      # Which extensions are valid on which qualities, and the intervals
+      # they add.
+      #
+      # "Extension" here means anything appended to a bare triad symbol as
+      # one lookup axis - so it deliberately includes '6' (strictly an
+      # added tone) and 'dim7' (strictly part of the quality) alongside
+      # true extensions like '7'/'9'/'11'/'13'.
+      EXTENSIONS = {
+        '6':    {
+                  add: [ 9 ],
+                  qualities: %i[major minor]
+                },
+        '7':    {
+                  add: [ 10 ],
+                  qualities: %i[major minor diminished suspended_2 suspended_4]
+                },
+        'maj7': {
+                  add: [ 11 ],
+                  qualities: %i[major minor augmented]
+                },
+        'dim7': {
+                  add: [ 9 ],
+                  qualities: %i[diminished]
+                },
+        '9':    {
+                  add: [ 10, 14 ],
+                  qualities: %i[major minor suspended_4]
+                },
+        '11':   {
+                  add: [ 10, 14, 17 ],
+                  qualities: %i[major minor]
+                },
+        '13':   {
+                  add: [ 10, 14, 21 ],
+                  qualities: %i[major minor suspended_4]
+                }
+      }.freeze
+
+      # How each quality + extension pair is symbolized. :base is the bare
+      # chord.
+      SYMBOLS = {
+        major:        {
+                        base:   "",
+                        '6':    "6",
+                        '7':    "7",
+                        'maj7': "maj7",
+                        '9':    "9",
+                        '11':   "11",
+                        '13':   "13"
+                      },
+        minor:        {
+                        base:   "m",
+                        '6':    "m6",
+                        '7':    "m7",
+                        'maj7': "m(maj7)",
+                        '9':    "m9",
+                        '11':   "m11",
+                        '13':   "m13"
+                      },
+        diminished:   {
+                        base:   "dim",
+                        '7':    "m7b5",
+                        'dim7': "dim7"
+                      },
+        augmented:    {
+                        base:   "aug",
+                        "maj7": "maj7#5"
+                      },
+        suspended_2:  {
+                        base: "sus2",
+                        '7':  "7sus2"
+                      },
+        suspended_4:  {
+                        base: "sus4",
+                        '7':  "7sus4",
+                        '9':  "9sus4",
+                        '13': "13sus4"
+                      },
+        power:        {
+                        base: "5"
+                      }
+      }.freeze
+
+      # natural: the diatonic interval the alteration replaces (if present)
+      # altered: the interval it becomes/adds.
+      ALTERATIONS = {
+        'b5':  { natural: 7,  altered: 6 },
+        '#5':  { natural: 7,  altered: 8 },
+        'b9':  { natural: 14, altered: 13 },
+        '#9':  { natural: 14, altered: 15 },
+        '#11': { natural: 17, altered: 18 },
+        'b13': { natural: 21, altered: 20 }
+      }.freeze
+
+      # Mapping of added-tone names to the intervals (in semitones) they
+      # contribute above the root.
+      ADDED_TONE_INTERVALS = {
+        add2:  2,
+        add4:  5,
+        add6:  9,
+        add9:  14,
+        add11: 17,
+        add13: 21
+      }.freeze
+
+      module_function
+
+      # "Cmaj7", "F#m7b5", "Bbsus4" - the canonical symbol for a
+      # root/quality/extension/etc. combination.
+      def symbol(root_name:,
+                 quality:,
+                 extension: nil,
+                 alterations: [],
+                 added_tones: [])
+        "#{root_name}" \
+          "#{SYMBOLS.fetch(quality.to_sym).fetch(extension&.to_sym || :base)}" \
+          "#{alterations.join}#{added_tones.join}"
+      end
+
+      # URL/file slug for a chord or voicing symbol:
+      # 'F#m7b5' => 'fsharpm7flat5', 'A/C#' => 'aslashcsharp'
+      def slug(symbol)
+        symbol
+          .gsub("b", "flat")
+          .gsub("#", "sharp")
+          .gsub("(", "-")
+          .gsub(")", "-")
+          .gsub("/", "slash")
+          .delete_suffix("-")
+          .downcase
+      end
+
+      # The intervals for a quality with an extension merged in (drops
+      # duplicated pitch classes, e.g. the 11th on a sus4 chord).
+      def intervals(quality:, extension: nil)
+        base = QUALITIES.fetch(quality.to_sym)
+        return base unless extension
+
+        merge(base, EXTENSIONS.fetch(extension.to_sym).fetch(:add))
+      end
+
+      # Apply interval alterations by replacing natural intervals with their
+      # altered equivalents, then return the intervals in ascending order.
+      def apply_alterations(base, alterations)
+        intervals = base.dup
+
+        alterations.each do |alteration|
+          spec = ALTERATIONS.fetch(alteration.to_sym)
+          intervals.delete(spec[:natural])
+          intervals << spec[:altered]
+        end
+
+        intervals.sort
+      end
+
+      # Interval-set helpers used by the builders above; public because
+      # chord-construction code elsewhere composes with them too.
+
+      # Merge added intervals into a base set; drops any interval whose
+      # pitch class is already present.
+      def merge(base, additions)
+        pcs = pitch_classes(base)
+
+        (
+          base +
+          additions.reject do |i|
+            pcs.include?(i % Interval::SEMITONES_PER_OCTAVE)
+          end
+        ).sort
+      end
+
+      # Reduce intervals to pitch classes (modulo 12), discarding octave
+      # information.
+      def pitch_classes(intervals)
+        intervals.map { |i| i % Interval::SEMITONES_PER_OCTAVE }
+      end
+    end
+  end
+end

data/lib/outro_rails/theory/interval.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module OutroRails
+  module Theory
+    # Intervals measured in semitones above a root.
+    module Interval
+      # Index = interval in semitones, value = scale-letter steps above the
+      # root letter (e.g. any kind of third is 2 letters up). nil = an
+      # interval the app never spells (e.g. 12 = a plain octave duplicate).
+      #
+      # Where two spellings exist, the chord vocabulary's usage wins:
+      # 6 semitones is a diminished fifth (dim triads, b5 alterations), so
+      # C + 6 spells Gb, not F#; 8 semitones is an augmented fifth (aug
+      # triads, #5), so C + 8 spells G#, not Ab.
+      LETTER_STEPS = [ 0, nil, 1, 2, 2, 3, 4, 4, 4, 5, 6, 6,
+                      nil, 1, 1, 1, nil, 3, 3, nil, 5, 5 ].freeze
+
+      # Names for common intervals (semitones).
+      UNISON         = 0
+      MINOR_SECOND   = 1
+      MAJOR_SECOND   = 2
+      MINOR_THIRD    = 3
+      MAJOR_THIRD    = 4
+      PERFECT_FOURTH = 5
+      TRITONE        = 6
+      PERFECT_FIFTH  = 7
+      MINOR_SIXTH    = 8
+      MAJOR_SIXTH    = 9
+      MINOR_SEVENTH  = 10
+      MAJOR_SEVENTH  = 11
+      OCTAVE         = 12
+
+      # How LETTER_STEPS actually spells 6 and 8 semitones (see above);
+      # prefer these names in chord contexts, where TRITONE/MINOR_SIXTH
+      # would misdescribe the resulting spelling.
+      DIMINISHED_FIFTH = TRITONE
+      AUGMENTED_FIFTH  = MINOR_SIXTH
+
+      # Semitones per octave.
+      SEMITONES_PER_OCTAVE = 12
+
+      module_function
+
+      # Letter steps a spelled interval spans, or nil when the interval has
+      # no conventional chord-tone spelling.
+      def letter_steps(semitones)
+        LETTER_STEPS[semitones]
+      end
+
+      # Letter steps a spelled interval spans; raises if no conventional
+      # chord-tone spelling exists for the interval.
+      def letter_steps!(semitones)
+        letter_steps(semitones) ||
+          raise(ArgumentError,
+                "no letter step defined for interval #{semitones}")
+      end
+    end
+  end
+end

data/lib/outro_rails/theory/key.rb

@@ -0,0 +1,249 @@
+# frozen_string_literal: true
+
+module OutroRails
+  module Theory
+    # A key: a tonic NoteName plus a mode. Not persisted.
+    # This object can transpose and turn Nashville numbers into chords.
+    #
+    #   key = Theory::Key.new('G')
+    #   key.note_names.map(&:to_s)     # => ['G', 'A', 'B', 'C', 'D', 'E', 'F#']
+    #   key.transpose_to('Bb')         # semitone/spelling aware
+    #   key.nashville('2m')            # => { root: A, quality: :minor, ... }
+    class Key
+      MODES = { major: :major, minor: :natural_minor }.freeze
+
+      # Tonics conventionally used for each mode (the circle of fifths,
+      # flattened). Used to pick spellings when transposing.
+      MAJOR_TONICS = %w[C G D A E B F# Gb Db Ab Eb Bb F].freeze
+      MINOR_TONICS = %w[A E B F# C# G# Eb Bb F C G D].freeze
+
+      # One wedge of the circle-of-fifths wheel: the major key(s) at a
+      # position (two spellings at the enharmonic seam, F#/Gb) and their
+      # relative minors, kept in matching order (F# => D#m, Gb => Ebm).
+      CirclePosition = Struct.new(:majors, :minors, keyword_init: true) do
+        def pitch_class
+          majors.first.tonic.pitch_class
+        end
+
+        def major_label
+          majors.map(&:to_s).join("/")
+        end
+
+        def minor_label
+          minors.map(&:to_s).join("/")
+        end
+      end
+
+      attr_reader :tonic, :mode
+
+      # Parses a key from a string or returns the key unchanged if already
+      # a Key. Strings ending in "m", "min", or "minor" become minor keys;
+      # everything else is treated as major.
+      def self.parse(value)
+        return value if value.is_a?(self)
+
+        text = value.to_s.strip
+        pattern =
+          /\A([A-Ga-g](?:#{NoteName::ACCIDENTAL_PATTERN})?)\s*(m|min|minor)\z/i
+
+        if (match = text.match(pattern))
+          new(match[1], :minor)
+        else
+          new(text, :major)
+        end
+      end
+
+      # One key of the given mode per canonical root spelling - the keys
+      # the UI offers wherever a key is picked (chart forms, transposer).
+      def self.canonical(mode = :major)
+        NoteName::CANONICAL_ROOTS.map { |root| new(root, mode) }
+      end
+
+      # The 12 wheel positions in circle order starting at C (clockwise:
+      # C G D A E B F#/Gb Db Ab Eb Bb F), pairing each major with its
+      # relative minor and merging enharmonic spellings into one position.
+      def self.circle_positions
+        MAJOR_TONICS.each_with_object([]) do |tonic, positions|
+          key = new(tonic, :major)
+
+          if positions.any? &&
+             positions.last.pitch_class == key.tonic.pitch_class
+             positions.last.majors << key
+             positions.last.minors << key.relative
+          else
+            positions << CirclePosition.new(
+              majors: [ key ],
+              minors: [ key.relative ]
+            )
+          end
+        end
+      end
+
+      # Creates an immutable key from a tonic and mode.
+      def initialize(tonic, mode = :major)
+        @tonic = NoteName.parse(tonic)
+        @mode = mode.to_sym
+        MODES.fetch(@mode) { raise ArgumentError,
+                                   "unknown mode #{mode.inspect}" }
+        freeze
+      end
+
+      # True if this is a major key.
+      def major?
+        mode == :major
+      end
+
+      # True if this is a minor key.
+      def minor?
+        mode == :minor
+      end
+
+      # The scale corresponding to this key and mode.
+      def scale
+        Scale.new(tonic, MODES.fetch(mode))
+      end
+
+      # The seven note names of the key's diatonic scale.
+      def note_names
+        scale.note_names
+      end
+
+      # Positive = sharps, negative = flats, 0 = C major / A minor.
+      def signature
+        scale.net_accidentals
+      end
+
+      # True if the key signature contains sharps.
+      def sharps?
+        signature.positive?
+      end
+
+      # True if the key signature contains flats.
+      def flats?
+        signature.negative?
+      end
+
+      # The relative major or minor key.
+      def relative
+        if major?
+          self.class.new(scale.degree(6), :minor)
+        else
+          self.class.new(scale.degree(3), :major)
+        end
+      end
+
+      # The parallel major or minor key, sharing the same tonic.
+      def parallel
+        self.class.new(tonic, major? ? :minor : :major)
+      end
+
+      # 1-based degree with an optional accidental adjustment, spelled the
+      # way the key would spell it (b7 in C major => Bb).
+      def note_for_degree(number, accidental_offset = 0)
+        note = scale.degree(number)
+        return note if accidental_offset.zero?
+
+        NoteName.new(
+          note.letter,
+          NoteName::ACCIDENTALS_BY_OFFSET.fetch(
+            note.accidental_offset + accidental_offset
+          )
+        )
+      end
+
+      # Inverse of #note_for_degree: [degree, accidental_offset] locating a
+      # note relative to this key by letter. Bb in C major => [7, -1];
+      # F# in C major => [4, 1].
+      def degree_of(note)
+        note = NoteName.parse(note)
+        index = note_names.index { |name| name.letter == note.letter }
+
+        [
+          index + 1,
+          note.accidental_offset - note_names[index].accidental_offset
+        ]
+      end
+
+      # Semitones from this key up to another (0..11).
+      def interval_to(other)
+        other = self.class.parse(other)
+        semitones = other.tonic.pitch_class - tonic.pitch_class
+
+        semitones % Interval::SEMITONES_PER_OCTAVE
+      end
+
+      # Returns a new key with the same mode and a different tonic.
+      def transpose_to(new_tonic)
+        self.class.new(new_tonic, mode)
+      end
+
+      # Transposes any note, respelled for the destination key: the note's
+      # position relative to this key is preserved. Moving F# (the 7th of
+      # G major) to the key of Bb yields A, and Bb's b7 yields Ab, not G#.
+      def transpose_note(note, to:)
+        destination = self.class.parse(to)
+        degree, accidental_offset = degree_of(note)
+
+        destination.note_for_degree(degree, accidental_offset)
+      end
+
+      # Resolves a Nashville number (or roman numeral) to the attributes
+      # needed to find or build a chord in this key:
+      #
+      #   Key.new('G').nashville('4')
+      #     => { root_name: "C", quality: :major, ... }
+      #   Key.new('G').nashville('2m7')
+      #     => { root_name: "A", quality: :minor, extension: "7" }
+      #   Key.new('C').nashville('bVII')
+      #     => { root_name: "Bb", quality: :major, ... }
+      #
+      # The result maps directly onto OutroRails::Chord columns, so the
+      # lookup is `Chord.find_by(root_name:, quality:, extension:)` - and
+      # "the musician flipped the minor 2 to a major 2" is just a different
+      # quality in the same lookup.
+      def nashville(input)
+        number = NashvilleNumber.parse(input)
+        root = note_for_degree(number.degree, number.accidental_offset)
+        quality = number.quality || default_quality_for(number)
+
+        {
+          root_name: root.to_s,
+          root_pitch_class: root.pitch_class,
+          quality: quality,
+          extension: number.extension,
+          symbol: ChordVocabulary.symbol(
+            root_name: root, quality: quality, extension: number.extension
+          )
+        }
+      end
+
+      # Every key of this mode in circle-of-fifths order, starting from
+      # this key's position. Major yields 13 keys, not 12 - F# and Gb both
+      # appear at the enharmonic seam (see MAJOR_TONICS).
+      def circle_of_fifths
+        tonics = major? ? MAJOR_TONICS : MINOR_TONICS
+        keys = tonics.map { |t| self.class.new(t, mode) }
+        start = keys.index { |k| k.tonic.pitch_class == tonic.pitch_class } || 0
+        keys.rotate(start)
+      end
+
+      # String representation using conventional notation ("C", "F#", "Am").
+      def to_s
+        major? ? tonic.to_s : "#{tonic}m"
+      end
+
+      private
+
+      # Unaltered, quality-less numbers take the diatonic triad quality
+      # (2 in a major key is minor); altered ones default to major, which
+      # matches Nashville convention (b7 => bVII major).
+      def default_quality_for(number)
+        if number.accidental_offset.zero?
+          scale.diatonic_quality(number.degree)
+        else
+          :major
+        end
+      end
+    end
+  end
+end

data/lib/outro_rails/theory/nashville_number.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module OutroRails
+  module Theory
+    # Parses Nashville numbers ("1", "4", "2m", "b7", and with extensions
+    # riding along: "2m7", "57" is 5 with a dominant 7) and roman numerals
+    # ("IV", "ii", "V7", "bVII", "vii°"). The result is key-agnostic;
+    # Theory::Key#nashville resolves it to a chord.
+    class NashvilleNumber
+      # Uppercase numerals in scale-degree order, indexed by degree - 1.
+      ROMAN_NUMERALS = %w[I II III IV V VI VII].freeze
+
+      # Lowercase numeral => degree, derived so the two tables can't drift.
+      ROMAN_DEGREES =
+          ROMAN_NUMERALS
+            .each_with_index
+            .to_h { |numeral, index| [ numeral.downcase, index + 1 ] }
+            .freeze
+
+      # Every accepted spelling of a quality suffix. "" maps to nil so the
+      # caller can fall back to the quality implied by numeral case.
+      QUALITY_SUFFIXES = {
+        ""     => nil,
+        "m"    => :minor,
+        "min"  => :minor,
+        "-"    => :minor,
+        "maj"  => :major,
+        "dim"  => :diminished,
+        "\u00B0"    => :diminished,
+        "o"    => :diminished,
+        "aug"  => :augmented,
+        "+"    => :augmented,
+        "sus2" => :suspended_2,
+        "sus4" => :suspended_4,
+        "sus"  => :suspended_4,
+        "5"    => :power
+      }.freeze
+
+      # Extensions recognized after the degree/quality, matching
+      # ChordVocabulary::EXTENSIONS keys.
+      EXTENSION_SUFFIXES = %w[maj7 dim7 6 7 9 11 13].freeze
+
+      # Splits a symbol into optional accidental, degree, and the suffix
+      # carrying quality and extension - arabic ("b7m") and roman ("bviim").
+      ARABIC_PATTERN = /\A(?<accidental>[b#]?)(?<degree>[1-7])(?<rest>.*)\z/
+      ROMAN_PATTERN  = /\A(?<accidental>[b#]?)(?<numeral>[ivIV]+)(?<rest>.*)\z/
+
+      # Display suffix per quality for arabic Nashville numbers; qualities
+      # not listed fall back to their name.
+      QUALITY_DISPLAY = {
+        major:      "",
+        minor:      "m",
+        diminished: "\u00B0",
+        augmented:  "+"
+      }.freeze
+
+      # Semitone offset => the accidental that writes it.
+      ACCIDENTAL_DISPLAY = { -1 => "b", 0 => "", 1 => "#" }.freeze
+
+      # Inverse of ACCIDENTAL_DISPLAY, for parsing.
+      ACCIDENTAL_OFFSETS = ACCIDENTAL_DISPLAY.invert.freeze
+
+      # A parsed symbol: scale degree 1-7, its chromatic offset, and the
+      # quality and extension, either of which may be nil.
+      ParseResult = Struct.new(:degree,
+                               :accidental_offset,
+                               :quality,
+                               :extension,
+                               keyword_init: true)
+
+      # Parses either notation into a ParseResult, trying arabic first.
+      # Raises ArgumentError on anything unrecognized.
+      def self.parse(input)
+        text = input.to_s.strip
+        raise ArgumentError, "blank Nashville number" if text.empty?
+
+        if (match = text.match(ARABIC_PATTERN))
+          from_match(match,
+                     degree: Integer(match[:degree]),
+                     explicit_quality: nil)
+        elsif (match = text.match(ROMAN_PATTERN))
+          numeral = match[:numeral]
+          degree = ROMAN_DEGREES.fetch(numeral.downcase) do
+            raise ArgumentError, "unknown roman numeral #{numeral.inspect}"
+          end
+          # Case carries quality: IV is major, iv is minor.
+          explicit_quality = numeral == numeral.downcase ? :minor : :major
+          from_match(match, degree: degree, explicit_quality: explicit_quality)
+        else
+          raise ArgumentError, "cannot parse Nashville number #{input.inspect}"
+        end
+      end
+
+      # Formats a degree + quality as an arabic Nashville number, parseable
+      # back by .parse: (2, :minor) => "2m", (7, :diminished) => "7°".
+      def self.format(degree:, quality: :major, accidental_offset: 0)
+        "#{ACCIDENTAL_DISPLAY.fetch(accidental_offset)}#{degree}" \
+          "#{QUALITY_DISPLAY.fetch(quality) { quality.to_s }}"
+      end
+
+      # The same chord as a roman numeral, case carrying the quality:
+      # (2, :minor) => "ii", (5, :major) => "V", (7, :diminished) => "vii°".
+      def self.roman(degree:, quality: :major, accidental_offset: 0)
+        numeral = ROMAN_NUMERALS.fetch(degree - 1)
+        accidental = ACCIDENTAL_DISPLAY.fetch(accidental_offset)
+
+        case quality
+        when :minor      then "#{accidental}#{numeral.downcase}"
+        when :diminished then "#{accidental}#{numeral.downcase}°"
+        when :augmented  then "#{accidental}#{numeral}+"
+        else                  "#{accidental}#{numeral}"
+        end
+      end
+
+      # Builds the ParseResult from a pattern match, once the caller has
+      # resolved the degree and any quality implied by numeral case.
+      def self.from_match(match, degree:, explicit_quality:)
+        accidental_offset = ACCIDENTAL_OFFSETS.fetch(match[:accidental])
+        quality, extension = parse_suffix(match[:rest], explicit_quality)
+
+        ParseResult.new(
+          degree: degree,
+          accidental_offset: accidental_offset,
+          quality: quality,
+          extension: extension
+        )
+      end
+      private_class_method :from_match
+
+      # Splits the trailing suffix into [quality, extension]: the extension
+      # is peeled off the end first, and what remains must be a known
+      # quality. An explicit suffix beats the quality implied by case.
+      def self.parse_suffix(rest, explicit_quality)
+        rest = rest.to_s.strip
+
+        extension = EXTENSION_SUFFIXES.find { |ext| rest.end_with?(ext) }
+        rest = rest.delete_suffix(extension) if extension
+
+        quality = QUALITY_SUFFIXES.fetch(rest) do
+          raise ArgumentError, "unknown chord quality #{rest.inspect}"
+        end
+        quality ||= explicit_quality
+
+        # "vii°7" / "7°7": a 7 on a diminished symbol conventionally means
+        # the *fully* diminished seventh, so promote it to dim7 here
+        # (half-diminished is written ø or m7b5, not °7).
+        extension = "dim7" if quality == :diminished && extension == "7"
+
+        [ quality, extension ]
+      end
+      private_class_method :parse_suffix
+    end
+  end
+end