head_music 8.2.1 → 9.0.1

data/lib/head_music/analysis/diatonic_interval.rb

@@ -4,8 +4,8 @@ module HeadMusic::Analysis; end
 # A diatonic interval is the distance between two spelled pitches.
 class HeadMusic::Analysis::DiatonicInterval
   include Comparable
+  include HeadMusic::Named
 
-  # TODO: include Named module
   NUMBER_NAMES = %w[
     unison second third fourth fifth sixth seventh octave
     ninth tenth eleventh twelfth thirteenth fourteenth fifteenth
@@ -43,7 +43,6 @@ class HeadMusic::Analysis::DiatonicInterval
 
   attr_reader :lower_pitch, :higher_pitch
 
-  delegate :to_s, to: :name
   delegate :perfect?, :major?, :minor?, :diminished?, :augmented?, :doubly_diminished?, :doubly_augmented?, to: :quality
 
   delegate :step?, :skip?, :leap?, :large_leap?, to: :category
@@ -52,18 +51,41 @@ class HeadMusic::Analysis::DiatonicInterval
     to: :size
   )
   delegate(
-    :simple_name, :quality_name, :simple_number_name, :number_name, :name, :shorthand,
+    :simple_name, :quality_name, :simple_number_name, :number_name, :shorthand,
     to: :naming
   )
 
   alias_method :to_i, :semitones
 
+  # Override Named module method to try I18n and fall back to computed name
+  def name(locale_code: nil)
+    if locale_code
+      name_key = HeadMusic::Utilities::HashKey.for(naming.name)
+      if I18n.backend.translations[locale_code]
+        locale_data = I18n.backend.translations[locale_code][:head_music] || {}
+        return locale_data[:diatonic_intervals][name_key] if locale_data.dig(:diatonic_intervals, name_key)
+        return locale_data[:chromatic_intervals][name_key] if locale_data.dig(:chromatic_intervals, name_key)
+      end
+    end
+    naming.name
+  end
+
+  def to_s
+    name
+  end
+
   # Accepts a name and returns the interval with middle c on the bottom
   def self.get(identifier)
-    name = Parser.new(identifier)
-    semitones = Semitones.new(name.degree_name.to_sym, name.quality_name).count
-    higher_pitch = HeadMusic::Rudiment::Pitch.from_number_and_letter(HeadMusic::Rudiment::Pitch.middle_c + semitones, name.higher_letter)
-    new(HeadMusic::Rudiment::Pitch.middle_c, higher_pitch)
+    if identifier.is_a?(String) || identifier.is_a?(Symbol)
+      name = Parser.new(identifier)
+      semitones = Semitones.new(name.degree_name.to_sym, name.quality_name).count
+      higher_pitch = HeadMusic::Rudiment::Pitch.from_number_and_letter(HeadMusic::Rudiment::Pitch.middle_c + semitones, name.higher_letter)
+      interval = new(HeadMusic::Rudiment::Pitch.middle_c, higher_pitch)
+      interval.ensure_localized_name(name: identifier.to_s)
+      interval
+    else
+      identifier
+    end
   end
 
   def initialize(first_pitch, second_pitch)
@@ -90,26 +112,39 @@ class HeadMusic::Analysis::DiatonicInterval
   alias_method :invert, :inversion
 
   def consonance(style = :standard_practice)
-    consonance_for_perfect(style) ||
-      consonance_for_major_and_minor ||
-      HeadMusic::Rudiment::Consonance.get(:dissonant)
+    consonance_analysis(style).consonance
   end
 
   def consonance?(style = :standard_practice)
-    consonance(style).perfect? || consonance(style).imperfect?
+    consonance(style).consonant?
+  end
+
+  def consonant?(style = :standard_practice)
+    consonance_analysis(style).consonant?
   end
-  alias_method :consonant?, :consonance?
 
   def perfect_consonance?(style = :standard_practice)
-    consonance(style).perfect?
+    consonance_analysis(style).perfect_consonance?
   end
 
   def imperfect_consonance?(style = :standard_practice)
-    consonance(style).imperfect?
+    consonance_analysis(style).imperfect_consonance?
   end
 
   def dissonance?(style = :standard_practice)
-    consonance(style).dissonant?
+    consonance_analysis(style).dissonant?
+  end
+
+  def dissonant?(style = :standard_practice)
+    consonance_analysis(style).dissonant?
+  end
+
+  def consonance_analysis(style = :standard_practice)
+    HeadMusic::Analysis::IntervalConsonance.new(self, style)
+  end
+
+  def consonance_classification(style: :standard_practice)
+    consonance_analysis(style).classification
   end
 
   def above(pitch)
@@ -160,16 +195,4 @@ class HeadMusic::Analysis::DiatonicInterval
   def naming
     @naming ||= Naming.new(number: number, semitones: semitones)
   end
-
-  def consonance_for_perfect(style = :standard_practice)
-    HeadMusic::Rudiment::Consonance.get(dissonant_fourth?(style) ? :dissonant : :perfect) if perfect?
-  end
-
-  def consonance_for_major_and_minor
-    HeadMusic::Rudiment::Consonance.get((third_or_compound? || sixth_or_compound?) ? :imperfect : :dissonant) if major? || minor?
-  end
-
-  def dissonant_fourth?(style = :standard_practice)
-    fourth_or_compound? && style == :two_part_harmony
-  end
 end

data/lib/head_music/analysis/interval_consonance.rb

@@ -0,0 +1,51 @@
+# Analysis class that combines an interval with a style tradition to determine consonance
+class HeadMusic::Analysis::IntervalConsonance
+  attr_reader :interval, :style_tradition
+
+  def initialize(interval, style_tradition = HeadMusic::Style::ModernTradition.new)
+    @interval = interval
+    @style_tradition = style_tradition.is_a?(HeadMusic::Style::Tradition) ?
+                       style_tradition :
+                       HeadMusic::Style::Tradition.get(style_tradition)
+  end
+
+  def classification
+    @classification ||= style_tradition.consonance_classification(interval)
+  end
+
+  def consonance
+    @consonance ||= HeadMusic::Rudiment::Consonance.get(classification)
+  end
+
+  def consonant?
+    [HeadMusic::Rudiment::Consonance::PERFECT_CONSONANCE, HeadMusic::Rudiment::Consonance::IMPERFECT_CONSONANCE].include?(classification)
+  end
+
+  def dissonant?
+    [HeadMusic::Rudiment::Consonance::MILD_DISSONANCE, HeadMusic::Rudiment::Consonance::HARSH_DISSONANCE, HeadMusic::Rudiment::Consonance::DISSONANCE].include?(classification)
+  end
+
+  def contextual?
+    classification == HeadMusic::Rudiment::Consonance::CONTEXTUAL
+  end
+
+  def perfect_consonance?
+    classification == HeadMusic::Rudiment::Consonance::PERFECT_CONSONANCE
+  end
+
+  def imperfect_consonance?
+    classification == HeadMusic::Rudiment::Consonance::IMPERFECT_CONSONANCE
+  end
+
+  def mild_dissonance?
+    classification == HeadMusic::Rudiment::Consonance::MILD_DISSONANCE
+  end
+
+  def harsh_dissonance?
+    classification == HeadMusic::Rudiment::Consonance::HARSH_DISSONANCE
+  end
+
+  def dissonance?
+    classification == HeadMusic::Rudiment::Consonance::DISSONANCE
+  end
+end

data/lib/head_music/content/note.rb

@@ -11,7 +11,7 @@ class HeadMusic::Content::Note
 
   def initialize(pitch, rhythmic_value, voice = nil, position = nil)
     @pitch = HeadMusic::Rudiment::Pitch.get(pitch)
-    @rhythmic_value = HeadMusic::Content::RhythmicValue.get(rhythmic_value)
+    @rhythmic_value = HeadMusic::Rudiment::RhythmicValue.get(rhythmic_value)
     @voice = voice || HeadMusic::Content::Voice.new
     @position = position || HeadMusic::Content::Position.new(@voice.composition, "1:1")
   end

data/lib/head_music/content/placement.rb

@@ -55,7 +55,7 @@ class HeadMusic::Content::Placement
   def ensure_attributes(voice, position, rhythmic_value, pitch)
     @voice = voice
     ensure_position(position)
-    @rhythmic_value = HeadMusic::Content::RhythmicValue.get(rhythmic_value)
+    @rhythmic_value = HeadMusic::Rudiment::RhythmicValue.get(rhythmic_value)
     @pitch = HeadMusic::Rudiment::Pitch.get(pitch)
   end
 

data/lib/head_music/content/position.rb

@@ -53,7 +53,7 @@ class HeadMusic::Content::Position
   end
 
   def +(other)
-    other = HeadMusic::Content::RhythmicValue.new(other) if [HeadMusic::Rudiment::RhythmicUnit, Symbol, String].include?(other.class)
+    other = HeadMusic::Rudiment::RhythmicValue.new(other) if [HeadMusic::Rudiment::RhythmicUnit, Symbol, String].include?(other.class)
     self.class.new(composition, bar_number, count, tick + other.ticks)
   end
 

data/lib/head_music/content/staff.rb

@@ -8,7 +8,7 @@ class HeadMusic::Content::Staff
   attr_reader :default_clef, :line_count, :instrument
 
   def initialize(default_clef_key, instrument: nil, line_count: nil)
-    @instrument = HeadMusic::Instruments::Instrument.get(instrument) if instrument
+    @instrument = HeadMusic::Instruments::InstrumentType.get(instrument) if instrument
     begin
       @default_clef = HeadMusic::Rudiment::Clef.get(default_clef_key)
     rescue KeyError, NoMethodError

data/lib/head_music/instruments/instrument.rb

@@ -1,67 +1,74 @@
 # Namespace for instrument definitions, categorization, and configuration
 module HeadMusic::Instruments; end
 
-# A musical instrument.
-# An instrument object can be assigned to a staff object.
-# Attributes:
-#   name_key: the name of the instrument
-#   alias_name_keys: an array of alternative names for the instrument
-#   orchestra_section_key: the section of the orchestra (e.g. "strings")
-#   family_key: the key for the family of the instrument (e.g. "saxophone")
-#   classification_keys: an array of classification_keys
-#   default_clefs: the default clef or system of clefs for the instrument
-#     - [treble] for instruments that use the treble clef
-#     - [treble, bass] for instruments that use the grand staff
-#   variants:
-#     a hash of default and alternative pitch designations
-# Associations:
-#   family: the family of the instrument (e.g. "saxophone")
-#   orchestra_section: the section of the orchestra (e.g. "strings")
+# A specific musical instrument instance with a selected variant.
+# Represents an actual playable instrument with its transposition and configuration.
+#
+# Examples:
+#   trumpet_in_c = HeadMusic::Instruments::Instrument.get("trumpet_in_c")
+#   trumpet_in_c = HeadMusic::Instruments::Instrument.get("trumpet", "in_c")
+#   clarinet = HeadMusic::Instruments::Instrument.get("clarinet")  # uses default Bb variant
+#
+# Attributes accessible via delegation to instrument_type and variant:
+#   name: display name including variant (e.g. "Trumpet in C")
+#   transposition: sounding transposition in semitones
+#   clefs: array of clefs for this instrument
+#   pitch_designation: the pitch designation for transposing instruments
 class HeadMusic::Instruments::Instrument
   include HeadMusic::Named
 
-  INSTRUMENTS = YAML.load_file(File.expand_path("instruments.yml", __dir__)).freeze
+  attr_reader :instrument_type, :variant
 
-  def self.get(name)
-    get_by_name(name)
-  end
+  # Factory method to get an Instrument instance
+  # @param type_or_name [String, Symbol] instrument type name or full name with variant
+  # @param variant_key [String, Symbol, nil] optional variant key if not included in name
+  # @return [Instrument] instrument instance with specified or default variant
+  def self.get(type_or_name, variant_key = nil)
+    return type_or_name if type_or_name.is_a?(self)
 
-  def self.all
-    HeadMusic::Instruments::InstrumentFamily.all
-    @all ||=
-      INSTRUMENTS.map { |key, _data| get(key) }.sort_by { |instrument| instrument.name.downcase }
-  end
+    type_name, parsed_variant_key = parse_instrument_name(type_or_name)
+    variant_key ||= parsed_variant_key
 
-  attr_reader(
-    :name_key, :alias_name_keys,
-    :family_key, :orchestra_section_key,
-    :variants, :classification_keys
-  )
+    instrument_type = HeadMusic::Instruments::InstrumentType.get(type_name)
+    return nil unless instrument_type&.name_key
 
-  def ==(other)
-    to_s == other.to_s
+    variant = find_variant(instrument_type, variant_key)
+    new(instrument_type, variant)
+  end
+
+  def initialize(instrument_type, variant)
+    @instrument_type = instrument_type
+    @variant = variant
+    initialize_name
   end
 
-  def translation(locale = :en)
-    return name unless name_key
+  # Delegations to instrument_type
+  delegate :name_key, :family_key, :family, :orchestra_section_key, :classification_keys,
+    :alias_name_keys, :variants, :translation, to: :instrument_type
 
-    I18n.translate(name_key, scope: %i[head_music instruments], locale: locale, default: name)
+  # Delegations to variant
+  delegate :pitch_designation, :staff_schemes, :default_staff_scheme, to: :variant
+
+  def default_staves
+    default_staff_scheme&.staves || []
   end
 
-  def family
-    return unless family_key
+  def default_clefs
+    default_staves&.map(&:clef) || []
+  end
 
-    HeadMusic::Instruments::InstrumentFamily.get(family_key)
+  def sounding_transposition
+    default_staves&.first&.sounding_transposition || 0
   end
 
-  # Returns true if the instrument sounds at a different pitch than written.
+  alias_method :default_sounding_transposition, :sounding_transposition
+
   def transposing?
-    default_sounding_transposition != 0
+    sounding_transposition != 0
   end
 
-  # Returns true if the instrument sounds at a different register than written.
   def transposing_at_the_octave?
-    transposing? && default_sounding_transposition % 12 == 0
+    transposing? && sounding_transposition % 12 == 0
   end
 
   def single_staff?
@@ -78,94 +85,77 @@ class HeadMusic::Instruments::Instrument
     default_clefs.any?
   end
 
-  def default_variant
-    variants.find(&:default?) || variants.first
-  end
-
-  delegate :default_staff_scheme, to: :default_variant
+  def ==(other)
+    return false unless other.is_a?(self.class)
 
-  def default_staves
-    default_staff_scheme&.staves || []
+    instrument_type == other.instrument_type && variant == other.variant
   end
 
-  def default_clefs
-    default_staves&.map(&:clef) || []
+  def to_s
+    name
   end
 
-  def default_sounding_transposition
-    default_staves&.first&.sounding_transposition || 0
-  end
-
-  private_class_method :new
-
   private
 
-  def initialize(name)
-    record = record_for_name(name)
-    if record
-      initialize_data_from_record(record)
+  def initialize_name
+    if variant.default? || !pitch_designation
+      self.name = instrument_type.name
+    elsif pitch_designation
+      pitch_name = format_pitch_name(pitch_designation)
+      self.name = "#{instrument_type.name} in #{pitch_name}"
     else
-      self.name = name.to_s
+      variant_name = variant.key.to_s.tr("_", " ")
+      self.name = "#{instrument_type.name} (#{variant_name})"
     end
   end
 
-  def record_for_name(name)
-    record_for_key(HeadMusic::Utilities::HashKey.for(name)) ||
-      record_for_key(key_for_name(name))
-  end
-
-  def key_for_name(name)
-    INSTRUMENTS.each do |key, _data|
-      I18n.config.available_locales.each do |locale|
-        translation = I18n.t("head_music.instruments.#{key}", locale: locale)
-        return key if translation.downcase == name.downcase
+  def format_pitch_name(pitch_designation)
+    # Format the pitch designation for display
+    # e.g. "Bb" -> "B♭", "C" -> "C", "Eb" -> "E♭"
+    pitch_designation.to_s.gsub("b", "♭").gsub("#", "♯")
+  end
+
+  def self.parse_instrument_name(name)
+    name_str = name.to_s
+
+    # Check for variant patterns like "trumpet_in_e_flat"
+    if name_str =~ /(.+)_in_([a-g])_(flat|sharp)$/i
+      type_name = Regexp.last_match(1)
+      note = Regexp.last_match(2).downcase
+      accidental = Regexp.last_match(3)
+      variant_key = :"in_#{note}_#{accidental}"
+      [type_name, variant_key]
+    # Check for variant patterns like "trumpet_in_c" or "clarinet_in_a" or "trumpet_in_eb"
+    elsif name_str =~ /(.+)_in_([a-g][b#]?)$/i
+      type_name = Regexp.last_match(1)
+      variant_note = Regexp.last_match(2).downcase
+      # Convert "eb" to "e_flat", "bb" to "b_flat", etc.
+      if variant_note.end_with?("b") && variant_note.length == 2
+        note_letter = variant_note[0]
+        variant_key = :"in_#{note_letter}_flat"
+      elsif variant_note.end_with?("#") && variant_note.length == 2
+        note_letter = variant_note[0]
+        variant_key = :"in_#{note_letter}_sharp"
+      else
+        variant_key = :"in_#{variant_note}"
       end
+      [type_name, variant_key]
+    else
+      [name_str, nil]
     end
-    nil
   end
 
-  def record_for_key(key)
-    INSTRUMENTS.each do |name_key, data|
-      return data.merge!("name_key" => name_key) if name_key.to_s == key.to_s
-    end
-    nil
-  end
+  def self.find_variant(instrument_type, variant_key)
+    return instrument_type.default_variant unless variant_key
 
-  def initialize_data_from_record(record)
-    initialize_family(record)
-    inherit_family_attributes(record)
-    initialize_names(record)
-    initialize_attributes(record)
-  end
+    # Convert to symbol for comparison
+    variant_sym = variant_key.to_sym
 
-  def initialize_family(record)
-    @family_key = record["family_key"]
-    @family = HeadMusic::Instruments::InstrumentFamily.get(family_key)
+    # Find the variant by key
+    variants = instrument_type.variants || []
+    variant = variants.find { |v| v.key == variant_sym }
+    variant || instrument_type.default_variant
   end
 
-  def inherit_family_attributes(record)
-    return unless family
-
-    @orchestra_section_key = family.orchestra_section_key
-    @classification_keys = family.classification_keys || []
-  end
-
-  def initialize_names(record)
-    @name_key = record["name_key"].to_sym
-    self.name = I18n.translate(name_key, scope: "head_music.instruments", locale: "en", default: inferred_name)
-    @alias_name_keys = record["alias_name_keys"] || []
-  end
-
-  def initialize_attributes(record)
-    @orchestra_section_key ||= record["orchestra_section_key"]
-    @classification_keys = [@classification_keys, record["classification_keys"]].flatten.compact.uniq
-    @variants =
-      (record["variants"] || {}).map do |key, attributes|
-        HeadMusic::Instruments::Variant.new(key, attributes)
-      end
-  end
-
-  def inferred_name
-    name_key.to_s.tr("_", " ")
-  end
+  private_class_method :parse_instrument_name, :find_variant
 end

data/lib/head_music/instruments/instrument_families.yml

@@ -28,6 +28,15 @@ bassoon:
     - wind
     - woodwind
   orchestra_section_key: woodwind
+celesta:
+  classification_keys:
+    - idiophone
+    - keyboard
+    - percussion
+    - struck
+    - metal
+    - pitched
+  orchestra_section_key: keyboard
 clarinet:
   classification_keys:
     - aerophone
@@ -42,15 +51,6 @@ clavichord:
     - keyboard
     - string
   orchestra_section_key: keyboard
-celesta:
-  classification_keys:
-    - idiophone
-    - keyboard
-    - percussion
-    - struck
-    - metal
-    - pitched
-  orchestra_section_key: percussion
 cornet:
   classification_keys:
     - aerophone
@@ -239,6 +239,7 @@ tambourine:
   classification_keys:
     - percussion
     - membranophone
+    - shaken
     - idiophone
     - unpitched
   orchestra_section_key: percussion

data/lib/head_music/instruments/instrument_family.rb

@@ -3,8 +3,19 @@ module HeadMusic::Instruments; end
 
 # An *InstrumentFamily* is a species of instrument
 # that may exist in a variety of keys or other variations.
-# For example, _saxophone_ is an instrument family, while
-# _alto saxophone_ and _baritone saxophone_ are specific instruments.
+# For example:
+# - _saxophone_ is an instrument family, while
+#   _alto saxophone_ and _baritone saxophone_ are specific instruments.
+# - _oboe_ is an instrument family, while
+#   _oboe d'amore_ and _English horn_ are specific instruments.
+#
+# Instrument families are categorized by:
+# - orchestra section (e.g. woodwind, brass, percussion, strings)
+# - classification (e.g. bowed string, plucked string, double reed, single reed, brass, keyboard, electronic, percussion)
+#
+# Instrument families are defined in `lib/head_music/instruments/instrument_families.yml`.
+#
+# @see HeadMusic::Instruments::InstrumentType
 class HeadMusic::Instruments::InstrumentFamily
   include HeadMusic::Named