head_music 8.3.0 → 11.0.0

data/lib/head_music/rudiment/alteration.rb

@@ -1,86 +1,64 @@
-require "head_music/rudiment/musical_symbol"
-
 # A module for music rudiments
 module HeadMusic::Rudiment; end
 
 # An Alteration is a symbol that modifies pitch, such as a sharp, flat, or natural.
 # In French, sharps and flats in the key signature are called "altérations".
-class HeadMusic::Rudiment::Alteration
+class HeadMusic::Rudiment::Alteration < HeadMusic::Rudiment::Base
   include Comparable
+  include HeadMusic::Named
 
-  attr_reader :identifier, :cents, :musical_symbols
+  attr_reader :identifier, :semitones, :musical_symbols
 
   delegate :ascii, :unicode, :html_entity, to: :musical_symbol
 
-  ALTERATION_RECORDS = [
-    {
-      identifier: :sharp, cents: 100,
-      symbols: [{ascii: "#", unicode: "♯", html_entity: "&#9839;"}]
-    },
-    {
-      identifier: :flat, cents: -100,
-      symbols: [{ascii: "b", unicode: "♭", html_entity: "&#9837;"}]
-    },
-    {
-      identifier: :natural, cents: 0,
-      symbols: [{ascii: "", unicode: "♮", html_entity: "&#9838;"}]
-    },
-    {
-      identifier: :double_sharp, cents: 200,
-      symbols: [{ascii: "x", unicode: "𝄪", html_entity: "&#119082;"}]
-    },
-    {
-      identifier: :double_flat, cents: -200,
-      symbols: [{ascii: "bb", unicode: "𝄫", html_entity: "&#119083;"}]
-    }
-  ].freeze
-
-  ALTERATION_IDENTIFIERS = ALTERATION_RECORDS.map { |attributes| attributes[:identifier] }.freeze
+  ALTERATION_RECORDS =
+    YAML.load_file(File.expand_path("alterations.yml", __dir__), symbolize_names: true)[:alterations].freeze
+
+  ALTERATION_IDENTIFIERS = ALTERATION_RECORDS.keys.freeze
+  SYMBOLS = ALTERATION_RECORDS.map { |key, attributes| attributes[:symbols].map { |symbol| [symbol[:unicode], symbol[:ascii]] } }.flatten.reject { |s| s.nil? || s.empty? }.freeze
+  PATTERN = Regexp.union(SYMBOLS)
+  MATCHER = PATTERN
 
   def self.all
-    ALTERATION_RECORDS.map { |attributes| new(attributes) }
+    @all ||= ALTERATION_RECORDS.map { |key, attributes| new(key, attributes) }
   end
 
   def self.symbols
     @symbols ||= all.map { |alteration| [alteration.ascii, alteration.unicode] }.flatten.reject { |s| s.nil? || s.empty? }
   end
 
-  def self.matcher
-    @matcher ||= Regexp.new symbols.join("|")
-  end
-
   def self.symbol?(candidate)
-    candidate =~ /^(#{matcher})$/
+    SYMBOLS.include?(candidate)
   end
 
   def self.get(identifier)
     return identifier if identifier.is_a?(HeadMusic::Rudiment::Alteration)
 
     all.detect do |alteration|
-      alteration.representions.include?(identifier)
+      alteration.representations.include?(identifier)
     end
   end
 
   def self.by(key, value)
     all.detect do |alteration|
-      alteration.send(key) == value if %i[cents semitones].include?(key.to_sym)
+      alteration.send(key) == value if %i[semitones].include?(key.to_sym)
     end
   end
 
-  def name
-    identifier.to_s.tr("_", " ")
+  def self.get_by_name(name)
+    all.detect { |alteration| alteration.name == name.to_s }
   end
 
-  def representions
-    [identifier, identifier.to_s, name, ascii, unicode, html_entity]
-      .reject { |representation| representation.to_s.strip == "" }
+  def name(locale_code: I18n.locale)
+    super || identifier.to_s.tr("_", " ")
   end
 
-  def semitones
-    cents / 100.0
+  def representations
+    [identifier, identifier.to_s, name, ascii, unicode, html_entity]
+      .reject { |representation| representation.to_s.strip == "" }
   end
 
-  ALTERATION_IDENTIFIERS.each do |key|
+  ALTERATION_RECORDS.keys.each do |key|
     define_method(:"#{key}?") { identifier == key }
   end
 
@@ -90,7 +68,7 @@ class HeadMusic::Rudiment::Alteration
 
   def <=>(other)
     other = HeadMusic::Rudiment::Alteration.get(other)
-    cents <=> other.cents
+    semitones <=> other.semitones
   end
 
   def musical_symbol
@@ -99,15 +77,22 @@ class HeadMusic::Rudiment::Alteration
 
   private
 
-  def initialize(attributes)
-    @identifier = attributes[:identifier]
-    @cents = attributes[:cents]
+  def initialize(key, attributes)
+    @identifier = key
+    @semitones = attributes[:semitones]
     initialize_musical_symbols(attributes[:symbols])
+    initialize_localized_names
+  end
+
+  def initialize_localized_names
+    # Initialize default English names
+    ensure_localized_name(name: identifier.to_s.tr("_", " "), locale_code: :en)
+    # Additional localized names will be loaded from locale files
   end
 
   def initialize_musical_symbols(list)
     @musical_symbols = (list || []).map do |record|
-      HeadMusic::Rudiment::MusicalSymbol.new(
+      HeadMusic::Notation::MusicalSymbol.new(
         unicode: record[:unicode],
         ascii: record[:ascii],
         html_entity: record[:html_entity]

data/lib/head_music/rudiment/alterations.yml

@@ -0,0 +1,32 @@
+alterations:
+  double_flat:
+    semitones: -2
+    symbols:
+      - ascii: "bb"
+        unicode: "𝄫"
+        html_entity: "𝄫"
+  flat:
+    semitones: -1
+    symbols:
+      - ascii: "b"
+        unicode: "♭"
+        html_entity: "♭"
+  natural:
+    cents: 0
+    semitones: 0
+    symbols:
+      - ascii: ""
+        unicode: "♮"
+        html_entity: "♮"
+  sharp:
+    semitones: 1
+    symbols:
+      - ascii: "#"
+        unicode: "♯"
+        html_entity: "♯"
+  double_sharp:
+    semitones: 2
+    symbols:
+      - ascii: "x"
+        unicode: "𝄪"
+        html_entity: "𝄪"

data/lib/head_music/rudiment/base.rb

@@ -0,0 +1,9 @@
+module HeadMusic::Rudiment; end
+
+class HeadMusic::Rudiment::Base
+  private
+
+  def initialize
+    raise NotImplementedError, "Cannot instantiate abstract rudiment base class"
+  end
+end

data/lib/head_music/rudiment/chromatic_interval.rb

@@ -2,7 +2,7 @@
 module HeadMusic::Rudiment; end
 
 # A chromatic interval is the distance between two pitches measured in half-steps.
-class HeadMusic::Rudiment::ChromaticInterval
+class HeadMusic::Rudiment::ChromaticInterval < HeadMusic::Rudiment::Base
   include Comparable
   include HeadMusic::Named
 
@@ -17,17 +17,14 @@ class HeadMusic::Rudiment::ChromaticInterval
 
   def self.get(identifier)
     @intervals ||= {}
-    candidate = identifier.to_s.downcase.gsub(/\W+/, "_")
+    candidate = HeadMusic::Utilities::Case.to_snake_case(identifier)
     semitones = NAMES.index(candidate) || identifier.to_i
     @intervals[semitones] ||= new(semitones.to_i)
   end
 
   def initialize(identifier)
-    if /^\D/i.match?(identifier.to_s.strip)
-      candidate = identifier.to_s.downcase.gsub(/\W+/, "_")
-      semitones = NAMES.index(candidate) || identifier.to_i
-    end
-    @semitones = semitones || identifier.to_i
+    candidate = HeadMusic::Utilities::HashKey.for(identifier).to_s
+    @semitones = NAMES.index(candidate) || identifier.to_i
     set_name
   end
 

data/lib/head_music/rudiment/clef.rb

@@ -4,7 +4,7 @@ require "yaml"
 module HeadMusic::Rudiment; end
 
 # A clef assigns pitches to the lines and spaces of a staff.
-class HeadMusic::Rudiment::Clef
+class HeadMusic::Rudiment::Clef < HeadMusic::Rudiment::Base
   include HeadMusic::Named
 
   RECORDS = YAML.load_file(File.expand_path("clefs.yml", __dir__)).freeze
@@ -98,7 +98,7 @@ class HeadMusic::Rudiment::Clef
 
   def initialize_musical_symbols(list)
     @musical_symbols = (list || []).map do |symbol_data|
-      HeadMusic::Rudiment::MusicalSymbol.new(**symbol_data.slice(:ascii, :html_entity, :unicode))
+      HeadMusic::Notation::MusicalSymbol.new(**symbol_data.slice(:ascii, :html_entity, :unicode))
     end
   end
 end

data/lib/head_music/rudiment/consonance.rb

@@ -1,13 +1,31 @@
 # A module for music rudiments
 module HeadMusic::Rudiment; end
 
-# Consonance describes a category or degree of harmonic pleasantness: perfect, imperfect, or dissonant
-class HeadMusic::Rudiment::Consonance
-  LEVELS = %w[perfect imperfect dissonant].freeze
+# Consonance describes a category or degree of harmonic pleasantness
+class HeadMusic::Rudiment::Consonance < HeadMusic::Rudiment::Base
+  PERFECT_CONSONANCE = :perfect_consonance
+  IMPERFECT_CONSONANCE = :imperfect_consonance
+  CONTEXTUAL = :contextual
+  MILD_DISSONANCE = :mild_dissonance
+  HARSH_DISSONANCE = :harsh_dissonance
+  DISSONANCE = :dissonance
+
+  LEVELS = [
+    PERFECT_CONSONANCE,
+    IMPERFECT_CONSONANCE,
+    CONTEXTUAL,
+    MILD_DISSONANCE,
+    HARSH_DISSONANCE,
+    DISSONANCE
+  ].freeze
 
   def self.get(name)
+    return name if name.is_a?(self)
+    return nil if name.nil?
+
     @consonances ||= {}
-    @consonances[name.to_sym] ||= new(name) if LEVELS.include?(name.to_s)
+    name_sym = name.to_sym
+    @consonances[name_sym] ||= new(name) if LEVELS.include?(name_sym)
   end
 
   attr_reader :name
@@ -22,7 +40,23 @@ class HeadMusic::Rudiment::Consonance
     to_s == other.to_s
   end
 
+  # Check if this represents a consonance (perfect or imperfect)
+  def consonant?
+    [PERFECT_CONSONANCE, IMPERFECT_CONSONANCE].include?(name)
+  end
+
+  # Check if this represents any form of dissonance
+  def dissonant?
+    [MILD_DISSONANCE, HARSH_DISSONANCE, DISSONANCE].include?(name)
+  end
+
+  # Contextual is special - neither strictly consonant nor dissonant
+  def contextual?
+    name == CONTEXTUAL
+  end
+
+  # Predicate methods for each level
   LEVELS.each do |method_name|
-    define_method(:"#{method_name}?") { to_s == method_name }
+    define_method(:"#{method_name}?") { to_s == method_name.to_s }
   end
 end

data/lib/head_music/rudiment/diatonic_context.rb

@@ -0,0 +1,25 @@
+# A module for music rudiments
+module HeadMusic::Rudiment; end
+
+# Abstract class representing a diatonic tonal context (7-note scale system)
+class HeadMusic::Rudiment::DiatonicContext < HeadMusic::Rudiment::TonalContext
+  def scale_type
+    raise NotImplementedError, "Subclasses must implement #scale_type"
+  end
+
+  def scale
+    @scale ||= HeadMusic::Rudiment::Scale.get(tonic_spelling, scale_type)
+  end
+
+  def key_signature
+    @key_signature ||= HeadMusic::Rudiment::KeySignature.from_scale(scale)
+  end
+
+  def relative
+    raise NotImplementedError, "Subclasses must implement #relative"
+  end
+
+  def parallel
+    raise NotImplementedError, "Subclasses must implement #parallel"
+  end
+end

data/lib/head_music/rudiment/key.rb

@@ -0,0 +1,77 @@
+# A module for music rudiments
+module HeadMusic::Rudiment; end
+
+# Represents a musical key (major or minor)
+class HeadMusic::Rudiment::Key < HeadMusic::Rudiment::DiatonicContext
+  include HeadMusic::Named
+
+  QUALITIES = %i[major minor].freeze
+
+  attr_reader :quality
+
+  def self.get(identifier)
+    return identifier if identifier.is_a?(HeadMusic::Rudiment::Key)
+
+    @keys ||= {}
+    tonic_spelling, quality_name = parse_identifier(identifier)
+    hash_key = HeadMusic::Utilities::HashKey.for(identifier)
+    @keys[hash_key] ||= new(tonic_spelling, quality_name)
+  end
+
+  def self.parse_identifier(identifier)
+    tonic_spelling, quality_name = identifier.to_s.strip.split(/\s+/)
+    quality_name ||= "major"
+    [tonic_spelling, quality_name]
+  end
+
+  def initialize(tonic_spelling, quality = :major)
+    super(tonic_spelling)
+    @quality = quality.to_s.downcase.to_sym
+    raise ArgumentError, "Quality must be :major or :minor" unless QUALITIES.include?(@quality)
+  end
+
+  def scale_type
+    @scale_type ||= HeadMusic::Rudiment::ScaleType.get(quality)
+  end
+
+  def major?
+    quality == :major
+  end
+
+  def minor?
+    quality == :minor
+  end
+
+  def relative
+    if major?
+      # Major to relative minor: down a minor third (3 semitones)
+      relative_pitch = tonic_pitch + -3
+      self.class.get("#{relative_pitch.spelling} minor")
+    else
+      # Minor to relative major: up a minor third (3 semitones)
+      relative_pitch = tonic_pitch + 3
+      self.class.get("#{relative_pitch.spelling} major")
+    end
+  end
+
+  def parallel
+    if major?
+      self.class.get("#{tonic_spelling} minor")
+    else
+      self.class.get("#{tonic_spelling} major")
+    end
+  end
+
+  def name
+    "#{tonic_spelling} #{quality}"
+  end
+
+  def to_s
+    name
+  end
+
+  def ==(other)
+    other = self.class.get(other)
+    tonic_spelling == other.tonic_spelling && quality == other.quality
+  end
+end

data/lib/head_music/rudiment/key_signature/enharmonic_equivalence.rb

@@ -1,4 +1,4 @@
-# Key signatures are enharmonic when all pitch classes in one are respellings of the pitch classes in the other.
+# Key signatures are enharmonic when they represent the same set of altered pitch classes but with different spellings.
 class HeadMusic::Rudiment::KeySignature::EnharmonicEquivalence
   attr_reader :key_signature
 

data/lib/head_music/rudiment/key_signature.rb

@@ -1,10 +1,9 @@
 # A module for music rudiments
 module HeadMusic::Rudiment; end
 
-# Represents a key signature.
-class HeadMusic::Rudiment::KeySignature
-  attr_reader :tonic_spelling, :scale_type, :scale
-
+# Represents a key signature (traditionally associated with a key)
+# This class maintains backward compatibility while delegating to Key/Mode internally
+class HeadMusic::Rudiment::KeySignature < HeadMusic::Rudiment::Base
   ORDERED_LETTER_NAMES_OF_SHARPS = %w[F C G D A E B].freeze
   ORDERED_LETTER_NAMES_OF_FLATS = ORDERED_LETTER_NAMES_OF_SHARPS.reverse.freeze
 
@@ -16,14 +15,28 @@ class HeadMusic::Rudiment::KeySignature
     return identifier if identifier.is_a?(HeadMusic::Rudiment::KeySignature)
 
     @key_signatures ||= {}
-    tonic_spelling, scale_type_name = identifier.strip.split(/\s/)
-    hash_key = HeadMusic::Utilities::HashKey.for(identifier.gsub(/#|♯/, " sharp").gsub(/(\w)[b♭]/, '\\1 flat'))
-    @key_signatures[hash_key] ||= new(tonic_spelling, scale_type_name)
+
+    if identifier.is_a?(String)
+      tonic_spelling, scale_type_name = identifier.strip.split(/\s/)
+      hash_key = HeadMusic::Utilities::HashKey.for(identifier.gsub(/#|♯/, " sharp").gsub(/(\w)[b♭]/, '\\1 flat'))
+      @key_signatures[hash_key] ||= new(tonic_spelling, scale_type_name)
+    elsif identifier.is_a?(HeadMusic::Rudiment::DiatonicContext)
+      identifier.key_signature
+    end
+  end
+
+  def self.from_scale(scale)
+    # Find a key or mode that uses this scale
+    tonic = scale.root_pitch.spelling
+    scale_type = scale.scale_type
+    new(tonic, scale_type)
   end
 
+  attr_reader :tonic_spelling, :scale_type, :scale
+
   delegate :pitch_class, to: :tonic_spelling, prefix: :tonic
-  delegate :to_s, to: :name
   delegate :pitches, :pitch_classes, to: :scale
+  delegate :to_s, to: :name
 
   def initialize(tonic_spelling, scale_type = nil)
     @tonic_spelling = HeadMusic::Rudiment::Spelling.get(tonic_spelling)

data/lib/head_music/rudiment/letter_name.rb

@@ -2,8 +2,10 @@
 module HeadMusic::Rudiment; end
 
 # Music has seven lette names that are used to identify pitches and pitch classes.
-class HeadMusic::Rudiment::LetterName
+class HeadMusic::Rudiment::LetterName < HeadMusic::Rudiment::Base
   NAMES = %w[C D E F G A B].freeze
+  PATTERN = /[A-Ga-g]/
+  MATCHER = /^#{PATTERN}$/
 
   NATURAL_PITCH_CLASS_NUMBERS = {
     "C" => 0,
@@ -96,6 +98,4 @@ class HeadMusic::Rudiment::LetterName
       series
     end
   end
-
-  private_class_method :new
 end

data/lib/head_music/rudiment/meter.rb

@@ -2,7 +2,7 @@
 module HeadMusic::Rudiment; end
 
 # Meter is the rhythmic size of a measure, such as 4/4 or 6/8
-class HeadMusic::Rudiment::Meter
+class HeadMusic::Rudiment::Meter < HeadMusic::Rudiment::Base
   attr_reader :top_number, :bottom_number
 
   NAMED = {
@@ -15,7 +15,7 @@ class HeadMusic::Rudiment::Meter
     hash_key = HeadMusic::Utilities::HashKey.for(identifier)
     time_signature_string = NAMED[hash_key] || identifier
     @meters ||= {}
-    @meters[hash_key] ||= new(*time_signature_string.split("/").map(&:to_i))
+    @meters[hash_key] ||= new(*time_signature_string.split("/"))
   end
 
   def self.default
@@ -31,8 +31,8 @@ class HeadMusic::Rudiment::Meter
   end
 
   def initialize(top_number, bottom_number)
-    @top_number = top_number
-    @bottom_number = bottom_number
+    @top_number = top_number.to_i
+    @bottom_number = bottom_number.to_i
   end
 
   def simple?
@@ -63,6 +63,10 @@ class HeadMusic::Rudiment::Meter
     top_number
   end
 
+  def counts_per_quarter_note
+    0.25 / count_unit.relative_value
+  end
+
   def beat_strength(count, tick: 0)
     return 100 if downbeat?(count, tick)
     return 80 if strong_beat?(count, tick)
@@ -76,19 +80,25 @@ class HeadMusic::Rudiment::Meter
     @ticks_per_count ||= count_unit.ticks
   end
 
+  # The rhythmic unit for the count (bottom number).
+  # This unit is also used as "beats" in a sequencer context
+  #   For example, "1:3:000"
   def count_unit
     HeadMusic::Rudiment::RhythmicUnit.for_denominator_value(bottom_number)
   end
 
-  def beat_unit
-    @beat_unit ||=
+  def beat_value
+    @beat_value ||=
       if compound?
-        HeadMusic::Content::RhythmicValue.new(HeadMusic::Rudiment::RhythmicUnit.for_denominator_value(bottom_number / 2), dots: 1)
+        HeadMusic::Rudiment::RhythmicValue.new(HeadMusic::Rudiment::RhythmicUnit.for_denominator_value(bottom_number / 2), dots: 1)
       else
-        HeadMusic::Content::RhythmicValue.new(count_unit)
+        HeadMusic::Rudiment::RhythmicValue.new(count_unit)
       end
   end
 
+  # for consistency with conversational usage
+  alias_method :beat_unit, :beat_value
+
   def to_s
     [top_number, bottom_number].join("/")
   end
@@ -133,6 +143,6 @@ class HeadMusic::Rudiment::Meter
   end
 
   def beat?(tick)
-    tick.zero?
+    tick.to_i.zero?
   end
 end

data/lib/head_music/rudiment/mode.rb

@@ -0,0 +1,92 @@
+# A module for music rudiments
+module HeadMusic::Rudiment; end
+
+# Represents a musical mode (church modes)
+class HeadMusic::Rudiment::Mode < HeadMusic::Rudiment::DiatonicContext
+  include HeadMusic::Named
+
+  MODES = %i[ionian dorian phrygian lydian mixolydian aeolian locrian].freeze
+
+  attr_reader :mode_name
+
+  def self.get(identifier)
+    return identifier if identifier.is_a?(HeadMusic::Rudiment::Mode)
+
+    @modes ||= {}
+    tonic_spelling, mode_name = parse_identifier(identifier)
+    hash_key = HeadMusic::Utilities::HashKey.for(identifier)
+    @modes[hash_key] ||= new(tonic_spelling, mode_name)
+  end
+
+  def self.parse_identifier(identifier)
+    identifier = identifier.to_s.strip
+    parts = identifier.split(/\s+/)
+    tonic_spelling = parts[0]
+    mode_name = parts[1] || "ionian"
+    [tonic_spelling, mode_name]
+  end
+
+  def initialize(tonic_spelling, mode_name = :ionian)
+    super(tonic_spelling)
+    @mode_name = mode_name.to_s.downcase.to_sym
+    raise ArgumentError, "Mode must be one of: #{MODES.join(", ")}" unless MODES.include?(@mode_name)
+  end
+
+  def scale_type
+    @scale_type ||= HeadMusic::Rudiment::ScaleType.get(mode_name)
+  end
+
+  def relative_major
+    case mode_name
+    when :ionian
+      return HeadMusic::Rudiment::Key.get("#{tonic_spelling} major")
+    when :dorian
+      relative_pitch = tonic_pitch + -2
+    when :phrygian
+      relative_pitch = tonic_pitch + -4
+    when :lydian
+      relative_pitch = tonic_pitch + -5
+    when :mixolydian
+      relative_pitch = tonic_pitch + -7
+    when :aeolian
+      relative_pitch = tonic_pitch + -9
+    when :locrian
+      relative_pitch = tonic_pitch + -11
+    end
+
+    HeadMusic::Rudiment::Key.get("#{relative_pitch.spelling} major")
+  end
+
+  def relative
+    relative_major
+  end
+
+  def parallel
+    # Return the parallel major or minor key
+    case mode_name
+    when :ionian
+      HeadMusic::Rudiment::Key.get("#{tonic_spelling} major")
+    when :aeolian
+      HeadMusic::Rudiment::Key.get("#{tonic_spelling} minor")
+    when :dorian, :phrygian
+      HeadMusic::Rudiment::Key.get("#{tonic_spelling} minor")
+    when :lydian, :mixolydian
+      HeadMusic::Rudiment::Key.get("#{tonic_spelling} major")
+    when :locrian
+      HeadMusic::Rudiment::Key.get("#{tonic_spelling} minor")
+    end
+  end
+
+  def name
+    "#{tonic_spelling} #{mode_name}"
+  end
+
+  def to_s
+    name
+  end
+
+  def ==(other)
+    other = self.class.get(other)
+    tonic_spelling == other.tonic_spelling && mode_name == other.mode_name
+  end
+end