head_music 8.3.0 → 11.0.0

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/voice.rb

@@ -170,7 +170,7 @@ class HeadMusic::Content::Voice
       combined_pitches = (pitches + other_note_pair.pitches).uniq
       return false if combined_pitches.length < 3
 
-      HeadMusic::Analysis::PitchSet.new(combined_pitches).consonant_triad?
+      HeadMusic::Analysis::PitchCollection.new(combined_pitches).consonant_triad?
     end
   end
 end

data/lib/head_music/instruments/alternate_tuning.rb

@@ -0,0 +1,102 @@
+module HeadMusic::Instruments; end
+
+# An alternate tuning for a stringed instrument.
+#
+# Tunings are defined as semitone adjustments from the standard tuning.
+# For example, "Drop D" tuning lowers the low E string by 2 semitones.
+#
+# Examples:
+#   drop_d = HeadMusic::Instruments::AlternateTuning.get("guitar", "drop_d")
+#   drop_d.semitones  # => [-2, 0, 0, 0, 0, 0]
+#
+# When applying a tuning:
+#   - First element applies to the lowest course
+#   - Missing elements are treated as 0 (no change)
+#   - Extra elements are ignored
+class HeadMusic::Instruments::AlternateTuning
+  TUNINGS = YAML.load_file(File.expand_path("alternate_tunings.yml", __dir__)).freeze
+
+  attr_reader :instrument_key, :name_key, :semitones
+
+  class << self
+    # Get an alternate tuning by instrument and name
+    # @param instrument [HeadMusic::Instruments::Instrument, String, Symbol] The instrument
+    # @param name [String, Symbol] The tuning name (e.g., "drop_d")
+    # @return [AlternateTuning, nil]
+    def get(instrument, name)
+      instrument_key = normalize_instrument_key(instrument)
+      name_key = name.to_s
+
+      data = TUNINGS.dig(instrument_key, name_key)
+      return nil unless data
+
+      new(
+        instrument_key: instrument_key,
+        name_key: name_key,
+        semitones: data["semitones"] || []
+      )
+    end
+
+    # Get all alternate tunings for an instrument
+    # @param instrument [HeadMusic::Instruments::Instrument, String, Symbol] The instrument
+    # @return [Array<AlternateTuning>]
+    def for_instrument(instrument)
+      instrument_key = normalize_instrument_key(instrument)
+      return [] unless TUNINGS.key?(instrument_key)
+
+      TUNINGS[instrument_key].map do |name_key, data|
+        new(
+          instrument_key: instrument_key,
+          name_key: name_key,
+          semitones: data["semitones"] || []
+        )
+      end
+    end
+
+    private
+
+    def normalize_instrument_key(instrument)
+      case instrument
+      when HeadMusic::Instruments::Instrument
+        instrument.name_key.to_s
+      else
+        instrument.to_s
+      end
+    end
+  end
+
+  def initialize(instrument_key:, name_key:, semitones:)
+    @instrument_key = instrument_key.to_sym
+    @name_key = name_key.to_sym
+    @semitones = Array(semitones)
+  end
+
+  # The instrument this tuning applies to
+  # @return [HeadMusic::Instruments::Instrument]
+  def instrument
+    HeadMusic::Instruments::Instrument.get(instrument_key)
+  end
+
+  # Human-readable name for the tuning
+  # @return [String]
+  def name
+    name_key.to_s.tr("_", " ").split.map(&:capitalize).join(" ")
+  end
+
+  # Apply this tuning to a stringing's standard pitches
+  # @param stringing [Stringing] The stringing to apply to
+  # @return [Array<HeadMusic::Rudiment::Pitch>]
+  def apply_to(stringing)
+    stringing.pitches_with_tuning(self)
+  end
+
+  def ==(other)
+    return false unless other.is_a?(self.class)
+
+    instrument_key == other.instrument_key && name_key == other.name_key
+  end
+
+  def to_s
+    "#{name} (#{instrument_key})"
+  end
+end

data/lib/head_music/instruments/alternate_tunings.yml

@@ -0,0 +1,78 @@
+# Alternate tunings for stringed instruments.
+#
+# Each tuning is defined as semitone adjustments from standard tuning.
+# - First element = lowest course
+# - Missing elements = 0 (no change)
+# - Extra elements = ignored
+
+guitar:
+  drop_d:
+    semitones: [-2, 0, 0, 0, 0, 0]
+  double_drop_d:
+    semitones: [-2, 0, 0, 0, 0, -2]
+  dadgad:
+    semitones: [-2, 0, 0, 0, -2, -2]
+  open_d:
+    semitones: [-2, 0, 0, -1, -2, -2]
+  open_g:
+    semitones: [-2, -2, 0, 0, 0, -2]
+  open_e:
+    semitones: [0, 2, 2, 1, 0, 0]
+  open_a:
+    semitones: [0, 0, 2, 2, 2, 0]
+  open_c:
+    semitones: [-4, -2, 0, 0, 1, 0]
+  half_step_down:
+    semitones: [-1, -1, -1, -1, -1, -1]
+  whole_step_down:
+    semitones: [-2, -2, -2, -2, -2, -2]
+  drop_c:
+    semitones: [-4, -2, -2, -2, -2, -2]
+  nashville:
+    semitones: [12, 12, 12, 12, 0, 0]
+
+bass_guitar:
+  drop_d:
+    semitones: [-2, 0, 0, 0]
+  half_step_down:
+    semitones: [-1, -1, -1, -1]
+  whole_step_down:
+    semitones: [-2, -2, -2, -2]
+  drop_c:
+    semitones: [-4, -2, -2, -2]
+
+five_string_bass:
+  standard:
+    semitones: [0, 0, 0, 0, 0]
+  drop_a:
+    semitones: [-2, 0, 0, 0, 0]
+
+banjo:
+  open_g:
+    semitones: [0, 0, 0, 0, 0]
+  double_c:
+    semitones: [-2, -2, 0, -2, 0]
+  sawmill:
+    semitones: [-2, -2, 0, 0, -2]
+  open_d:
+    semitones: [-5, -2, -2, -1, -2]
+
+ukulele:
+  low_g:
+    semitones: [-12, 0, 0, 0]
+  baritone:
+    semitones: [-5, -5, -5, -5]
+  slack_key:
+    semitones: [0, 0, -1, 0]
+
+violin:
+  solo_tuning:
+    semitones: [1, 1, 1, 1]
+  cross_tuning:
+    semitones: [0, 0, -2, 0]
+
+cello:
+  solo_tuning:
+    semitones: [1, 1, 1, 1]
+  drop_c:
+    semitones: [-2, 0, 0, 0]

data/lib/head_music/instruments/instrument.rb

@@ -1,51 +1,104 @@
-# Namespace for instrument definitions, categorization, and configuration
 module HeadMusic::Instruments; end
 
-# A musical instrument.
-# An instrument object can be assigned to a staff object.
+# A musical instrument with parent-based inheritance.
+#
+# Instruments can inherit from parent instruments, allowing for a clean
+# hierarchy where child instruments override specific attributes while
+# inheriting others from their parents.
+#
+# Examples:
+#   trumpet = HeadMusic::Instruments::Instrument.get("trumpet")
+#   clarinet_in_a = HeadMusic::Instruments::Instrument.get("clarinet_in_a")
+#   clarinet_in_a.parent  # => clarinet
+#   clarinet_in_a.pitch_key  # => "a" (own attribute)
+#   clarinet_in_a.family_key  # => "clarinet" (inherited from parent)
+#
 # 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")
+#   name_key: the primary identifier for the instrument
+#   parent_key: optional key referencing the parent instrument
+#   family_key: the instrument family (e.g., "clarinet", "trumpet")
+#   pitch_key: the pitch designation (e.g., "b_flat", "a", "c")
+#   alias_name_keys: alternative names for the instrument
+#   range_categories: size/range classifications
+#   staff_schemes: notation schemes (to be moved to NotationStyle later)
 class HeadMusic::Instruments::Instrument
   include HeadMusic::Named
 
   INSTRUMENTS = YAML.load_file(File.expand_path("instruments.yml", __dir__)).freeze
 
-  def self.get(name)
-    get_by_name(name)
-  end
+  attr_reader :name_key, :parent_key, :alias_name_keys, :range_categories, :staff_schemes_data
+
+  class << self
+    # Factory method to get an Instrument instance
+    # @param name [String, Symbol] instrument name (e.g., "clarinet", "clarinet_in_a")
+    # @param variant_key [String, Symbol, nil] DEPRECATED: variant key (for backward compatibility)
+    # @return [Instrument, nil] instrument instance or nil if not found
+    def get(name, variant_key = nil)
+      return name if name.is_a?(self)
+
+      # Handle two-argument form for backward compatibility
+      if variant_key
+        combined_name = "#{name}_#{variant_key}"
+        result = find_valid_instrument(combined_name) || find_valid_instrument(name.to_s)
+      else
+        result = find_valid_instrument(name.to_s) || find_valid_instrument(normalize_variant_name(name))
+      end
+
+      result
+    end
+
+    def find_valid_instrument(name)
+      instrument = get_by_name(name)
+      instrument&.name_key ? instrument : nil
+    end
 
-  def self.all
-    HeadMusic::Instruments::InstrumentFamily.all
-    @all ||=
-      INSTRUMENTS.map { |key, _data| get(key) }.sort_by { |instrument| instrument.name.downcase }
+    def all
+      HeadMusic::Instruments::InstrumentFamily.all # Ensure families are loaded first
+      INSTRUMENTS.map { |key, _data| get(key) }
+      @all ||= @instances.values.compact.sort_by { |instrument| instrument.name.downcase }
+    end
+
+    private
+
+    # Convert shorthand variant names to full form
+    # e.g., "trumpet_in_eb" -> "trumpet_in_e_flat"
+    # e.g., "clarinet_in_bb" -> "clarinet_in_b_flat"
+    def normalize_variant_name(name)
+      name_str = name.to_s
+
+      # Match patterns like "_in_eb" or "_in_bb" at the end (flat)
+      flat_pattern = /^(.+)_in_([a-g])b$/i
+      sharp_pattern = %r{^(.+)_in_([a-g])\#$}i
+
+      if name_str =~ flat_pattern
+        instrument = Regexp.last_match(1)
+        note = Regexp.last_match(2).downcase
+        "#{instrument}_in_#{note}_flat"
+      elsif name_str =~ sharp_pattern
+        instrument = Regexp.last_match(1)
+        note = Regexp.last_match(2).downcase
+        "#{instrument}_in_#{note}_sharp"
+      else
+        name_str
+      end
+    end
   end
 
-  attr_reader(
-    :name_key, :alias_name_keys,
-    :family_key, :orchestra_section_key,
-    :variants, :classification_keys
-  )
+  # Parent instrument (for inheritance)
+  def parent
+    return nil unless parent_key
 
-  def ==(other)
-    to_s == other.to_s
+    @parent ||= self.class.get(parent_key)
   end
 
-  def translation(locale = :en)
-    return name unless name_key
+  # Attributes with parent chain resolution
 
-    I18n.translate(name_key, scope: %i[head_music instruments], locale: locale, default: name)
+  def family_key
+    @family_key || parent&.family_key
+  end
+
+  def pitch_key
+    @pitch_key || parent&.pitch_key
   end
 
   def family
@@ -54,14 +107,51 @@ class HeadMusic::Instruments::Instrument
     HeadMusic::Instruments::InstrumentFamily.get(family_key)
   end
 
-  # Returns true if the instrument sounds at a different pitch than written.
+  def orchestra_section_key
+    family&.orchestra_section_key
+  end
+
+  def classification_keys
+    family&.classification_keys || []
+  end
+
+  # Pitch designation as a Spelling object (for backward compatibility)
+  def pitch_designation
+    return nil unless pitch_key
+
+    @pitch_designation ||= HeadMusic::Rudiment::Spelling.get(pitch_key_to_designation)
+  end
+
+  # Staff schemes (notation concern - kept for backward compatibility)
+  def staff_schemes
+    @staff_schemes ||= build_staff_schemes
+  end
+
+  def default_staff_scheme
+    @default_staff_scheme ||=
+      staff_schemes.find(&:default?) || staff_schemes.first
+  end
+
+  def default_staves
+    default_staff_scheme&.staves || []
+  end
+
+  def default_clefs
+    default_staves&.map(&:clef) || []
+  end
+
+  def sounding_transposition
+    default_staves&.first&.sounding_transposition || 0
+  end
+
+  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,22 +168,47 @@ class HeadMusic::Instruments::Instrument
     default_clefs.any?
   end
 
-  def default_variant
-    variants.find(&:default?) || variants.first
+  def translation(locale = :en)
+    return name unless name_key
+
+    I18n.translate(name_key, scope: %i[head_music instruments], locale: locale, default: name)
   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 || []
+    name_key == other.name_key
   end
 
-  def default_clefs
-    default_staves&.map(&:clef) || []
+  def to_s
+    name
   end
 
-  def default_sounding_transposition
-    default_staves&.first&.sounding_transposition || 0
+  # For backward compatibility with code that expects variants
+  def variants
+    []
+  end
+
+  def default_variant
+    nil
+  end
+
+  # Collect all instrument_configurations from self and ancestors
+  def instrument_configurations
+    own_configs = HeadMusic::Instruments::InstrumentConfiguration.for_instrument(name_key)
+    parent_configs = parent&.instrument_configurations || []
+    own_configs + parent_configs
+  end
+
+  def stringing
+    @stringing ||= HeadMusic::Instruments::Stringing.for_instrument(self) || parent&.stringing
+  end
+
+  def alternate_tunings
+    own_tunings = HeadMusic::Instruments::AlternateTuning.for_instrument(name_key)
+    return own_tunings if own_tunings.any?
+
+    parent&.alternate_tunings || []
   end
 
   private_class_method :new
@@ -105,13 +220,16 @@ class HeadMusic::Instruments::Instrument
     if record
       initialize_data_from_record(record)
     else
+      # Mark as invalid - will be filtered out by get_by_name
+      @name_key = nil
       self.name = name.to_s
     end
   end
 
   def record_for_name(name)
     record_for_key(HeadMusic::Utilities::HashKey.for(name)) ||
-      record_for_key(key_for_name(name))
+      record_for_key(key_for_name(name)) ||
+      record_for_alias(name)
   end
 
   def key_for_name(name)
@@ -126,46 +244,87 @@ class HeadMusic::Instruments::Instrument
 
   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
+      return data.merge("name_key" => name_key) if name_key.to_s == key.to_s
     end
     nil
   end
 
-  def initialize_data_from_record(record)
-    initialize_family(record)
-    inherit_family_attributes(record)
-    initialize_names(record)
-    initialize_attributes(record)
+  def record_for_alias(name)
+    normalized_name = HeadMusic::Utilities::HashKey.for(name).to_s
+    INSTRUMENTS.each do |name_key, data|
+      data["alias_name_keys"]&.each do |alias_key|
+        return data.merge("name_key" => name_key) if HeadMusic::Utilities::HashKey.for(alias_key).to_s == normalized_name
+      end
+    end
+    nil
   end
 
-  def initialize_family(record)
+  def initialize_data_from_record(record)
+    @name_key = record["name_key"].to_sym
+    @parent_key = record["parent_key"]&.to_sym
     @family_key = record["family_key"]
-    @family = HeadMusic::Instruments::InstrumentFamily.get(family_key)
-  end
-
-  def inherit_family_attributes(record)
-    return unless family
+    @pitch_key = record["pitch_key"]
+    @alias_name_keys = record["alias_name_keys"] || []
+    @range_categories = record["range_categories"] || []
+    @staff_schemes_data = record["staff_schemes"] || {}
 
-    @orchestra_section_key = family.orchestra_section_key
-    @classification_keys = family.classification_keys || []
+    initialize_name
   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"] || []
+  def initialize_name
+    # Try to get a translation first
+    base_name = I18n.translate(name_key, scope: "head_music.instruments", locale: "en", default: nil)
+
+    if base_name
+      # Use the translation as-is
+      self.name = base_name
+    elsif parent_key && pitch_key
+      # Build name from parent + pitch for child instruments
+      pitch_name = format_pitch_name(pitch_key_to_designation)
+      self.name = "#{parent_translation} in #{pitch_name}"
+    else
+      # Fall back to inferred name
+      self.name = inferred_name
+    end
   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
+  def parent_translation
+    return nil unless parent_key
+
+    I18n.translate(parent_key, scope: "head_music.instruments", locale: "en", default: parent_key.to_s.tr("_", " "))
   end
 
   def inferred_name
     name_key.to_s.tr("_", " ")
   end
+
+  def format_pitch_name(pitch_designation)
+    pitch_designation.to_s.tr("b", "♭").tr("#", "♯")
+  end
+
+  # Convert pitch_key (e.g., "b_flat") to designation format (e.g., "Bb")
+  def pitch_key_to_designation
+    return nil unless pitch_key
+
+    key = pitch_key.to_s
+    if key.end_with?("_flat")
+      "#{key[0].upcase}b"
+    elsif key.end_with?("_sharp")
+      "#{key[0].upcase}#"
+    else
+      key.upcase
+    end
+  end
+
+  def build_staff_schemes
+    return parent&.staff_schemes || [] if staff_schemes_data.empty?
+
+    staff_schemes_data.map do |key, list|
+      HeadMusic::Instruments::StaffScheme.new(
+        key: key,
+        instrument: self,
+        list: list
+      )
+    end
+  end
 end

data/lib/head_music/instruments/instrument_configuration.rb

@@ -0,0 +1,66 @@
+module HeadMusic::Instruments; end
+
+# A configurable aspect of an instrument, such as a leadpipe, mute, or attachment.
+#
+# Examples:
+#   - Piccolo trumpet "leadpipe" configuration with options: b_flat (default), a
+#   - Trumpet "mute" configuration with options: open (default), straight, cup, harmon
+#   - Bass trombone "f_attachment" with options: disengaged (default), engaged
+class HeadMusic::Instruments::InstrumentConfiguration
+  CONFIGURATIONS = YAML.load_file(File.expand_path("instrument_configurations.yml", __dir__)).freeze
+
+  attr_reader :name_key, :instrument_key, :options
+
+  class << self
+    def for_instrument(instrument_key)
+      instrument_key = instrument_key.to_s
+      return [] unless CONFIGURATIONS.key?(instrument_key)
+
+      CONFIGURATIONS[instrument_key].map do |config_name, config_data|
+        new(
+          name_key: config_name,
+          instrument_key: instrument_key,
+          options_data: config_data["options"] || {}
+        )
+      end
+    end
+  end
+
+  def initialize(name_key:, instrument_key:, options_data: {})
+    @name_key = name_key.to_sym
+    @instrument_key = instrument_key.to_sym
+    @options = build_options(options_data)
+  end
+
+  def default_option
+    @default_option ||= options.find(&:default?) || options.first
+  end
+
+  def option(option_key)
+    options.find { |opt| opt.name_key == option_key.to_sym }
+  end
+
+  def ==(other)
+    return false unless other.is_a?(self.class)
+
+    name_key == other.name_key && instrument_key == other.instrument_key
+  end
+
+  def to_s
+    name_key.to_s
+  end
+
+  private
+
+  def build_options(options_data)
+    options_data.map do |option_name, option_attrs|
+      attrs = option_attrs || {}
+      HeadMusic::Instruments::InstrumentConfigurationOption.new(
+        name_key: option_name,
+        default: attrs["default"],
+        transposition_semitones: attrs["transposition_semitones"],
+        lowest_pitch_semitones: attrs["lowest_pitch_semitones"]
+      )
+    end
+  end
+end