head_music 8.2.1 → 9.0.1

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,9 +1,10 @@
 # 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
+  attr_reader :tonal_context
 
   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 +17,32 @@ 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_tonal_context(tonal_context)
+    new_from_context(tonal_context)
   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)
@@ -31,6 +50,26 @@ class HeadMusic::Rudiment::KeySignature
     @scale_type ||= HeadMusic::Rudiment::ScaleType.default
     @scale_type = @scale_type.parent || @scale_type
     @scale = HeadMusic::Rudiment::Scale.get(@tonic_spelling, @scale_type)
+
+    # Create appropriate tonal context
+    scale_type_str = scale_type.to_s.downcase if scale_type
+
+    @tonal_context = if %w[major minor].include?(scale_type_str)
+      HeadMusic::Rudiment::Key.get("#{tonic_spelling} #{scale_type}")
+    elsif scale_type
+      HeadMusic::Rudiment::Mode.get("#{tonic_spelling} #{scale_type}")
+    else
+      HeadMusic::Rudiment::Key.get("#{tonic_spelling} major")
+    end
+  rescue ArgumentError
+    # Fall back to creating a major key if mode is not recognized
+    @tonal_context = HeadMusic::Rudiment::Key.get("#{tonic_spelling} major")
+  end
+
+  def self.new_from_context(context)
+    instance = allocate
+    instance.instance_variable_set(:@tonal_context, context)
+    instance
   end
 
   def spellings

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

data/lib/head_music/rudiment/musical_symbol.rb

@@ -2,7 +2,7 @@
 module HeadMusic::Rudiment; end
 
 # A symbol is a mark or sign that signifies a particular rudiment of music
-class HeadMusic::Rudiment::MusicalSymbol
+class HeadMusic::Rudiment::MusicalSymbol < HeadMusic::Rudiment::Base
   attr_reader :ascii, :unicode, :html_entity
 
   def initialize(ascii: nil, unicode: nil, html_entity: nil)

data/lib/head_music/rudiment/note.rb

@@ -0,0 +1,112 @@
+# A module for music rudiments
+module HeadMusic::Rudiment; end
+
+# A Note is a fundamental musical element consisting of a pitch and a duration.
+# This is the rudiment version, representing the abstract concept of a note
+# independent of its placement in a composition.
+#
+# For notes placed within a composition context, see HeadMusic::Content::Note
+class HeadMusic::Rudiment::Note < HeadMusic::Rudiment::RhythmicElement
+  include HeadMusic::Named
+
+  attr_reader :pitch
+
+  delegate :spelling, :register, :letter_name, :alteration, to: :pitch
+  delegate :sharp?, :flat?, :natural?, to: :pitch
+  delegate :pitch_class, :midi_note_number, :frequency, to: :pitch
+
+  # Regex pattern for parsing note strings like "C#4 quarter" or "Eb3 dotted half"
+  # Extract the core pattern from Spelling::MATCHER without anchors
+  PITCH_PATTERN = /([A-G])(#{HeadMusic::Rudiment::Alteration::PATTERN.source}?)(-?\d+)?/i
+  MATCHER = /^\s*(#{PITCH_PATTERN.source})\s+(.+)$/i
+
+  def self.get(pitch, rhythmic_value = nil)
+    return pitch if pitch.is_a?(HeadMusic::Rudiment::Note)
+
+    if rhythmic_value.nil? && pitch.is_a?(String)
+      # Try to parse as "pitch rhythmic_value" format (e.g., "F#4 dotted-quarter")
+      match = pitch.match(MATCHER)
+      if match
+        pitch_str = match[1] # The full pitch part
+        rhythmic_value_str = match[5] # The rhythmic value part
+
+        pitch_obj = HeadMusic::Rudiment::Pitch.get(pitch_str)
+        rhythmic_value_obj = HeadMusic::Rudiment::RhythmicValue.get(rhythmic_value_str)
+
+        return fetch_or_create(pitch_obj, rhythmic_value_obj) if pitch_obj && rhythmic_value_obj
+      end
+
+      # If parsing fails, treat it as just a pitch with default quarter note
+      pitch_obj = HeadMusic::Rudiment::Pitch.get(pitch)
+      return fetch_or_create(pitch_obj, HeadMusic::Rudiment::RhythmicValue.get(:quarter)) if pitch_obj
+
+      nil
+    else
+      pitch = HeadMusic::Rudiment::Pitch.get(pitch)
+      rhythmic_value = HeadMusic::Rudiment::RhythmicValue.get(rhythmic_value || :quarter)
+      fetch_or_create(pitch, rhythmic_value)
+    end
+  end
+
+  def self.fetch_or_create(pitch, rhythmic_value)
+    @notes ||= {}
+    hash_key = [pitch.to_s, rhythmic_value.to_s].join("_")
+    @notes[hash_key] ||= new(pitch, rhythmic_value)
+  end
+
+  def initialize(pitch, rhythmic_value)
+    super(rhythmic_value)
+    @pitch = pitch
+  end
+
+  # Make new public for this concrete class
+  public_class_method :new
+
+  def name
+    "#{pitch} #{rhythmic_value}"
+  end
+
+  def to_s
+    name
+  end
+
+  def ==(other)
+    other = HeadMusic::Rudiment::Note.get(other)
+    super && pitch == other.pitch
+  end
+
+  def <=>(other)
+    return nil unless other.is_a?(HeadMusic::Rudiment::RhythmicElement)
+    return super unless other.is_a?(self.class)
+
+    [rhythmic_value, pitch] <=> [other.rhythmic_value, other.pitch]
+  end
+
+  # Transpose the note up by an interval or semitones
+  def +(other)
+    new_pitch = pitch + other
+    self.class.get(new_pitch, rhythmic_value)
+  end
+
+  # Transpose the note down by an interval or semitones
+  def -(other)
+    new_pitch = pitch - other
+    self.class.get(new_pitch, rhythmic_value)
+  end
+
+  # Override to maintain pitch when changing rhythmic value
+  def with_rhythmic_value(new_rhythmic_value)
+    self.class.get(pitch, new_rhythmic_value)
+  end
+
+  # Change the pitch while keeping the same rhythmic value
+  def with_pitch(new_pitch)
+    self.class.get(new_pitch, rhythmic_value)
+  end
+
+  def sounded?
+    true
+  end
+
+  private_class_method :fetch_or_create
+end

data/lib/head_music/rudiment/pitch/parser.rb

@@ -0,0 +1,52 @@
+class HeadMusic::Rudiment::Pitch::Parser
+  attr_reader :identifier, :letter_name, :alteration, :register
+
+  LetterName = HeadMusic::Rudiment::LetterName
+  Alteration = HeadMusic::Rudiment::Alteration
+  Spelling = HeadMusic::Rudiment::Spelling
+  Register = HeadMusic::Rudiment::Register
+  Pitch = HeadMusic::Rudiment::Pitch
+
+  # Pattern that handles negative registers (e.g., -1) and positive registers
+  # Anchored to match complete pitch strings only
+  PATTERN = /\A(#{LetterName::PATTERN})?(#{Alteration::PATTERN.source})?(-?\d+)?\z/
+
+  # Parse a pitch identifier and return a Pitch object
+  # Returns nil if the identifier cannot be parsed into a valid pitch
+  def self.parse(identifier)
+    return nil if identifier.nil?
+    new(identifier).pitch
+  end
+
+  def initialize(identifier)
+    @identifier = identifier.to_s.strip
+    parse_components
+  end
+
+  def pitch
+    return unless spelling
+    # Default to register 4 if not provided (matching old behavior)
+    # Convert Register object to integer for fetch_or_create
+    reg = register ? register.to_i : Register::DEFAULT
+
+    @pitch ||= Pitch.fetch_or_create(spelling, reg)
+  end
+
+  def spelling
+    return unless letter_name
+
+    @spelling ||= Spelling.new(letter_name, alteration)
+  end
+
+  private
+
+  def parse_components
+    match = identifier.match(PATTERN)
+
+    if match
+      @letter_name = LetterName.get(match[1].upcase) unless match[1].to_s.empty?
+      @alteration = Alteration.get(match[2] || "") unless match[2].to_s.empty?
+      @register = Register.get(match[3]&.to_i) unless match[3].to_s.empty?
+    end
+  end
+end

data/lib/head_music/rudiment/pitch.rb

@@ -1,8 +1,7 @@
-# A module for music rudiments
 module HeadMusic::Rudiment; end
 
 # A pitch is a named frequency represented by a spelling and a register.
-class HeadMusic::Rudiment::Pitch
+class HeadMusic::Rudiment::Pitch < HeadMusic::Rudiment::Base
   include Comparable
 
   attr_reader :spelling, :register
@@ -29,6 +28,8 @@ class HeadMusic::Rudiment::Pitch
   #   - a name string, such as 'Ab4'
   #   - a number corresponding to the midi note number
   def self.get(value)
+    return value if value.is_a?(HeadMusic::Rudiment::Pitch)
+
     from_pitch_class(value) ||
       from_name(value) ||
       from_number(value)
@@ -51,7 +52,7 @@ class HeadMusic::Rudiment::Pitch
   def self.from_name(name)
     return nil unless name == name.to_s
 
-    fetch_or_create(HeadMusic::Rudiment::Spelling.get(name), HeadMusic::Rudiment::Register.get(name).to_i)
+    Parser.parse(name)
   end
 
   def self.from_number(number)
@@ -114,7 +115,7 @@ class HeadMusic::Rudiment::Pitch
   end
 
   def natural
-    HeadMusic::Rudiment::Pitch.get(to_s.gsub(HeadMusic::Rudiment::Alteration.matcher, ""))
+    HeadMusic::Rudiment::Pitch.get(to_s.gsub(HeadMusic::Rudiment::Alteration::PATTERN, ""))
   end
 
   def +(other)
@@ -167,8 +168,6 @@ class HeadMusic::Rudiment::Pitch
     letter_name_steps_to(other) + 7 * octave_changes_to(other)
   end
 
-  private_class_method :new
-
   private
 
   def octave_changes_to(other)

data/lib/head_music/rudiment/pitch_class.rb

@@ -2,7 +2,7 @@
 module HeadMusic::Rudiment; end
 
 # A pitch class is a set of pitches separated by octaves.
-class HeadMusic::Rudiment::PitchClass
+class HeadMusic::Rudiment::PitchClass < HeadMusic::Rudiment::Base
   include Comparable
 
   attr_reader :number, :spelling

data/lib/head_music/rudiment/quality.rb

@@ -2,7 +2,7 @@
 module HeadMusic::Rudiment; end
 
 # A quality is a categorization of an interval.
-class HeadMusic::Rudiment::Quality
+class HeadMusic::Rudiment::Quality < HeadMusic::Rudiment::Base
   SHORTHAND = {
     perfect: "P",
     major: "M",

data/lib/head_music/rudiment/reference_pitch.rb

@@ -3,7 +3,7 @@ module HeadMusic::Rudiment; end
 
 # A reference pitch has a pitch and a frequency
 # With no arguments, it assumes that A4 = 440.0 Hz
-class HeadMusic::Rudiment::ReferencePitch
+class HeadMusic::Rudiment::ReferencePitch < HeadMusic::Rudiment::Base
   include HeadMusic::Named
 
   DEFAULT_PITCH_NAME = "A4"

data/lib/head_music/rudiment/register.rb

@@ -6,9 +6,12 @@ module HeadMusic::Rudiment; end
 # A pitch is a spelling plus a register. For example, C4 is middle C and C5 is the C one octave higher.
 # The number changes between the letter names B and C regardless of sharps and flats,
 # so as an extreme example, Cb5 is actually a semitone below B#4.
-class HeadMusic::Rudiment::Register
+class HeadMusic::Rudiment::Register < HeadMusic::Rudiment::Base
   include Comparable
 
+  AUDIBLE_REGISTERS = (0..10).map.freeze
+  PATTERN = Regexp.union(AUDIBLE_REGISTERS.map(&:to_s))
+
   DEFAULT = 4
 
   def self.get(identifier)

data/lib/head_music/rudiment/rest.rb

@@ -0,0 +1,36 @@
+# A module for music rudiments
+module HeadMusic::Rudiment; end
+
+# A Rest represents a period of silence with a specific rhythmic value.
+# It inherits from RhythmicElement and has a duration but no pitch.
+class HeadMusic::Rudiment::Rest < HeadMusic::Rudiment::RhythmicElement
+  include HeadMusic::Named
+
+  # Make new public for this concrete class
+  public_class_method :new
+
+  def self.get(rhythmic_value)
+    return rhythmic_value if rhythmic_value.is_a?(HeadMusic::Rudiment::Rest)
+
+    rhythmic_value = HeadMusic::Rudiment::RhythmicValue.get(rhythmic_value)
+    return nil unless rhythmic_value
+
+    fetch_or_create(rhythmic_value)
+  end
+
+  def self.fetch_or_create(rhythmic_value)
+    @rests ||= {}
+    hash_key = rhythmic_value.to_s
+    @rests[hash_key] ||= new(rhythmic_value)
+  end
+
+  def name
+    "#{rhythmic_value} rest"
+  end
+
+  def sounded?
+    false
+  end
+
+  private_class_method :fetch_or_create
+end