head_music 8.2.1 → 9.0.1

data/lib/head_music/instruments/score_order.rb

@@ -0,0 +1,139 @@
+module HeadMusic::Instruments; end
+
+class HeadMusic::Instruments::ScoreOrder
+  include HeadMusic::Named
+
+  SCORE_ORDERS = YAML.load_file(File.expand_path("score_orders.yml", __dir__)).freeze
+
+  DEFAULT_ENSEMBLE_TYPE_KEY = :orchestral
+
+  attr_reader :ensemble_type_key, :sections
+
+  # Factory method to get a ScoreOrder instance for a specific ensemble type
+  def self.get(ensemble_type)
+    @instances ||= {}
+    key = HeadMusic::Utilities::HashKey.for(ensemble_type)
+    return unless SCORE_ORDERS.key?(key.to_s)
+
+    @instances[key] ||= new(key)
+  end
+
+  # Convenience method to order instruments in orchestral order
+  def self.in_orchestral_order(instruments)
+    get(:orchestral).order(instruments)
+  end
+
+  # Convenience method to order instruments in concert band order
+  def self.in_band_order(instruments)
+    get(:band).order(instruments)
+  end
+
+  # Accepts a list of instruments and orders them according to this ensemble type's conventions
+  def order(instruments)
+    valid_inputs = instruments.compact.reject { |i| i.respond_to?(:empty?) && i.empty? }
+    instrument_objects = valid_inputs.map { |i| normalize_to_instrument(i) }.compact
+
+    # Build ordering index
+    ordering_index = build_ordering_index
+
+    # Separate known and unknown instruments
+    known_instruments = []
+    unknown_instruments = []
+
+    instrument_objects.each do |instrument|
+      position_info = find_position_with_transposition(instrument, ordering_index)
+      if position_info
+        known_instruments << [instrument, position_info]
+      else
+        unknown_instruments << instrument
+      end
+    end
+
+    # Sort known instruments by position (primary) and transposition (secondary)
+    sorted_known = known_instruments.sort_by { |_, pos_info|
+      [pos_info[:position], -pos_info[:transposition]]
+    }.map(&:first)
+    sorted_known + unknown_instruments.sort_by(&:to_s)
+  end
+
+  private_class_method :new
+
+  private
+
+  def initialize(ensemble_type_key = DEFAULT_ENSEMBLE_TYPE_KEY)
+    @ensemble_type_key = ensemble_type_key.to_sym
+    data = SCORE_ORDERS[ensemble_type_key.to_s]
+
+    @sections = data["sections"] || []
+    self.name = data["name"] || ensemble_type_key.to_s.tr("_", " ").capitalize
+  end
+
+  def normalize_to_instrument(input)
+    # Return if already an Instrument instance
+    return input if input.is_a?(HeadMusic::Instruments::Instrument)
+
+    # Return InstrumentType instances as-is for backward compatibility (duck typing)
+    return input.default_instrument if input.is_a?(HeadMusic::Instruments::InstrumentType)
+
+    # Return other objects that respond to required methods (mock objects, etc.)
+    return input if input.respond_to?(:name_key) && input.respond_to?(:family_key)
+
+    # Create an Instrument instance for string inputs
+    HeadMusic::Instruments::Instrument.get(input) || HeadMusic::Instruments::InstrumentType.get(input)
+  end
+
+  # Builds an index mapping instrument names to their position in the order
+  def build_ordering_index
+    index = {}
+    position = 0
+
+    sections.each do |section|
+      instruments = section["instruments"] || []
+      instruments.each do |instrument_key|
+        # Store position for this instrument key
+        index[instrument_key.to_s] = position
+        position += 1
+      end
+    end
+
+    index
+  end
+
+  # Finds the position of an instrument in the ordering
+  def find_position(instrument, ordering_index)
+    # Try exact match with name_key
+    return ordering_index[instrument.name_key.to_s] if instrument.name_key && ordering_index.key?(instrument.name_key.to_s)
+
+    # Try matching by family + range category (e.g., alto_saxophone -> saxophone family)
+    if instrument.family_key
+      family_base = instrument.family_key.to_s
+      instrument_key = instrument.name_key.to_s
+
+      # Check if this is a variant of a family (e.g., alto_saxophone)
+      if instrument_key.include?(family_base)
+        # Look for the specific variant first
+        return ordering_index[instrument_key] if ordering_index.key?(instrument_key)
+
+        # Fall back to generic family instrument if listed
+        return ordering_index[family_base] if ordering_index.key?(family_base)
+      end
+    end
+
+    # Try normalized name (lowercase, underscored)
+    normalized = instrument.name.downcase.tr(" ", "_").tr("-", "_")
+    return ordering_index[normalized] if ordering_index.key?(normalized)
+
+    nil
+  end
+
+  # Finds the position and transposition information for an instrument
+  def find_position_with_transposition(instrument, ordering_index)
+    position = find_position(instrument, ordering_index)
+    return nil unless position
+
+    # Get the sounding transposition for secondary sorting
+    transposition = instrument.default_sounding_transposition || 0
+
+    {position: position, transposition: transposition}
+  end
+end

data/lib/head_music/instruments/score_orders.yml

@@ -0,0 +1,130 @@
+---
+orchestral:
+  name: "Orchestral"
+  sections:
+    - section_key: woodwind
+      instruments:
+        - piccolo_flute
+        - flute
+        - alto_flute
+        - alto_recorder
+        - soprano_recorder
+        - tenor_recorder
+        - oboe
+        - english_horn
+        - clarinet
+        - alto_clarinet
+        - bass_clarinet
+        - soprano_saxophone
+        - alto_saxophone
+        - tenor_saxophone
+        - baritone_saxophone
+        - bassoon
+        - contrabassoon
+    - section_key: brass
+      instruments:
+        - french_horn
+        - trumpet
+        - cornet
+        - trombone
+        - bass_trombone
+        - tuba
+    - section_key: percussion
+      instruments:
+        - timpani
+        - snare_drum
+        - bass_drum
+        - cymbal
+        - gong
+        - xylophone
+        - glockenspiel
+        - marimba
+        - vibraphone
+        - percussion
+    - section_key: keyboard
+      instruments:
+        - harp
+        - piano
+        - celesta
+        - harpsichord
+        - organ
+    - section_key: voice
+      instruments:
+        - soprano_voice
+        - alto_voice
+        - tenor_voice
+        - bass_voice
+    - section_key: string
+      instruments:
+        - violin
+        - viola
+        - cello
+        - double_bass
+
+band:
+  name: "Concert Band"
+  sections:
+    - section_key: woodwind
+      instruments:
+        - piccolo
+        - flute
+        - oboe
+        - english_horn
+        - bassoon
+        - contrabassoon
+        - clarinet
+        - alto_clarinet
+        - bass_clarinet
+        - soprano_saxophone
+        - alto_saxophone
+        - tenor_saxophone
+        - baritone_saxophone
+    - section_key: brass
+      instruments:
+        - cornet
+        - trumpet
+        - french_horn
+        - trombone
+        - bass_trombone
+        - euphonium
+        - baritone_horn
+        - tuba
+    - section_key: percussion
+      instruments:
+        - timpani
+        - snare_drum
+        - bass_drum
+        - cymbal
+        - percussion
+
+brass_quintet:
+  name: "Brass Quintet"
+  sections:
+    - section_key: brass
+      instruments:
+        - trumpet  # First trumpet
+        - trumpet  # Second trumpet
+        - french_horn
+        - trombone
+        - tuba
+
+woodwind_quintet:
+  name: "Woodwind Quintet"
+  sections:
+    - section_key: mixed
+      instruments:
+        - flute
+        - oboe
+        - clarinet
+        - french_horn  # Horn is traditional in woodwind quintets
+        - bassoon
+
+string_quartet:
+  name: "String Quartet"
+  sections:
+    - section_key: string
+      instruments:
+        - violin  # First violin
+        - violin  # Second violin
+        - viola
+        - cello

data/lib/head_music/instruments/variant.rb

@@ -35,4 +35,10 @@ class HeadMusic::Instruments::Variant
     @default_staff_scheme ||=
       staff_schemes.find(&:default?) || staff_schemes.first
   end
+
+  def ==(other)
+    return false unless other.is_a?(self.class)
+
+    key == other.key && attributes == other.attributes
+  end
 end

data/lib/head_music/locales/de.yml

@@ -1,5 +1,11 @@
 de:
   head_music:
+    alterations:
+      sharp: Kreuz
+      flat: Be
+      natural: Auflösungszeichen
+      double_sharp: Doppelkreuz
+      double_flat: Doppel-Be
     chromatic_intervals:
       perfect_unison: reine Prime
       minor_second: kleine Sekunde

data/lib/head_music/locales/en.yml

@@ -1,5 +1,11 @@
 en:
   head_music:
+    alterations:
+      sharp: sharp
+      flat: flat
+      natural: natural
+      double_sharp: double sharp
+      double_flat: double flat
     chromatic_intervals:
       perfect_unison: perfect unison
       minor_second: minor second
@@ -14,6 +20,98 @@ en:
       minor_seventh: minor seventh
       major_seventh: major seventh
       perfect_octave: perfect octave
+    diatonic_intervals:
+      perfect_unison: perfect unison
+      minor_second: minor second
+      major_second: major second
+      diminished_second: diminished second
+      augmented_second: augmented second
+      doubly_diminished_second: doubly diminished second
+      doubly_augmented_second: doubly augmented second
+      minor_third: minor third
+      major_third: major third
+      diminished_third: diminished third
+      augmented_third: augmented third
+      doubly_diminished_third: doubly diminished third
+      doubly_augmented_third: doubly augmented third
+      perfect_fourth: perfect fourth
+      diminished_fourth: diminished fourth
+      augmented_fourth: augmented fourth
+      doubly_diminished_fourth: doubly diminished fourth
+      doubly_augmented_fourth: doubly augmented fourth
+      perfect_fifth: perfect fifth
+      diminished_fifth: diminished fifth
+      augmented_fifth: augmented fifth
+      doubly_diminished_fifth: doubly diminished fifth
+      doubly_augmented_fifth: doubly augmented fifth
+      minor_sixth: minor sixth
+      major_sixth: major sixth
+      diminished_sixth: diminished sixth
+      augmented_sixth: augmented sixth
+      doubly_diminished_sixth: doubly diminished sixth
+      doubly_augmented_sixth: doubly augmented sixth
+      minor_seventh: minor seventh
+      major_seventh: major seventh
+      diminished_seventh: diminished seventh
+      augmented_seventh: augmented seventh
+      doubly_diminished_seventh: doubly diminished seventh
+      doubly_augmented_seventh: doubly augmented seventh
+      perfect_octave: perfect octave
+      diminished_octave: diminished octave
+      augmented_octave: augmented octave
+      doubly_diminished_octave: doubly diminished octave
+      doubly_augmented_octave: doubly augmented octave
+      minor_ninth: minor ninth
+      major_ninth: major ninth
+      diminished_ninth: diminished ninth
+      augmented_ninth: augmented ninth
+      doubly_diminished_ninth: doubly diminished ninth
+      doubly_augmented_ninth: doubly augmented ninth
+      minor_tenth: minor tenth
+      major_tenth: major tenth
+      diminished_tenth: diminished tenth
+      augmented_tenth: augmented tenth
+      doubly_diminished_tenth: doubly diminished tenth
+      doubly_augmented_tenth: doubly augmented tenth
+      perfect_eleventh: perfect eleventh
+      diminished_eleventh: diminished eleventh
+      augmented_eleventh: augmented eleventh
+      doubly_diminished_eleventh: doubly diminished eleventh
+      doubly_augmented_eleventh: doubly augmented eleventh
+      perfect_twelfth: perfect twelfth
+      diminished_twelfth: diminished twelfth
+      augmented_twelfth: augmented twelfth
+      doubly_diminished_twelfth: doubly diminished twelfth
+      doubly_augmented_twelfth: doubly augmented twelfth
+      minor_thirteenth: minor thirteenth
+      major_thirteenth: major thirteenth
+      diminished_thirteenth: diminished thirteenth
+      augmented_thirteenth: augmented thirteenth
+      doubly_diminished_thirteenth: doubly diminished thirteenth
+      doubly_augmented_thirteenth: doubly augmented thirteenth
+      minor_fourteenth: minor fourteenth
+      major_fourteenth: major fourteenth
+      diminished_fourteenth: diminished fourteenth
+      augmented_fourteenth: augmented fourteenth
+      doubly_diminished_fourteenth: doubly diminished fourteenth
+      doubly_augmented_fourteenth: doubly augmented fourteenth
+      perfect_fifteenth: perfect fifteenth
+      diminished_fifteenth: diminished fifteenth
+      augmented_fifteenth: augmented fifteenth
+      doubly_diminished_fifteenth: doubly diminished fifteenth
+      doubly_augmented_fifteenth: doubly augmented fifteenth
+      minor_sixteenth: minor sixteenth
+      major_sixteenth: major sixteenth
+      diminished_sixteenth: diminished sixteenth
+      augmented_sixteenth: augmented sixteenth
+      doubly_diminished_sixteenth: doubly diminished sixteenth
+      doubly_augmented_sixteenth: doubly augmented sixteenth
+      minor_seventeenth: minor seventeenth
+      major_seventeenth: major seventeenth
+      diminished_seventeenth: diminished seventeenth
+      augmented_seventeenth: augmented seventeenth
+      doubly_diminished_seventeenth: doubly diminished seventeenth
+      doubly_augmented_seventeenth: doubly augmented seventeenth
     clefs:
       alto_clef: alto clef
       baritone_c_clef: baritone C-clef

data/lib/head_music/locales/es.yml

@@ -1,5 +1,11 @@
 es:
   head_music:
+    alterations:
+      sharp: sostenido
+      flat: bemol
+      natural: becuadro
+      double_sharp: doble sostenido
+      double_flat: doble bemol
     chromatic_intervals:
       perfect_unison: unísono perfecto
       minor_second: segunda menor

data/lib/head_music/locales/fr.yml

@@ -1,5 +1,11 @@
 fr:
   head_music:
+    alterations:
+      sharp: dièse
+      flat: bémol
+      natural: bécarre
+      double_sharp: double dièse
+      double_flat: double bémol
     chromatic_intervals:
       perfect_unison: unisson parfait
       minor_second: seconde mineure

data/lib/head_music/locales/it.yml

@@ -1,5 +1,11 @@
 it:
   head_music:
+    alterations:
+      sharp: diesis
+      flat: bemolle
+      natural: bequadro
+      double_sharp: doppio diesis
+      double_flat: doppio bemolle
     chromatic_intervals:
       perfect_unison: unisono perfetto
       minor_second: seconda minore

data/lib/head_music/locales/ru.yml

@@ -1,5 +1,11 @@
 ru:
   head_music:
+    alterations:
+      sharp: диез
+      flat: бемоль
+      natural: бекар
+      double_sharp: дубль-диез
+      double_flat: дубль-бемоль
     chromatic_intervals:
       perfect_unison: чистый унисон
       minor_second: малая секунда

data/lib/head_music/rudiment/alteration.rb

@@ -5,8 +5,9 @@ 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
 
@@ -36,6 +37,9 @@ class HeadMusic::Rudiment::Alteration
   ].freeze
 
   ALTERATION_IDENTIFIERS = ALTERATION_RECORDS.map { |attributes| attributes[:identifier] }.freeze
+  SYMBOLS = ALTERATION_RECORDS.map { |attributes| attributes[:symbols].map { |symbol| [symbol[:unicode], symbol[:ascii]] } }.flatten.freeze
+  PATTERN = Regexp.union(SYMBOLS.reject { |s| s.nil? || s.empty? })
+  MATCHER = PATTERN
 
   def self.all
     ALTERATION_RECORDS.map { |attributes| new(attributes) }
@@ -45,12 +49,8 @@ class HeadMusic::Rudiment::Alteration
     @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)
@@ -67,8 +67,16 @@ class HeadMusic::Rudiment::Alteration
     end
   end
 
-  def name
-    identifier.to_s.tr("_", " ")
+  def self.get_by_name(name)
+    all.detect { |alteration| alteration.name == name.to_s }
+  end
+
+  def self.from_pitched_item(input)
+    nil
+  end
+
+  def name(locale_code: I18n.locale)
+    super || identifier.to_s.tr("_", " ")
   end
 
   def representions
@@ -103,6 +111,13 @@ class HeadMusic::Rudiment::Alteration
     @identifier = attributes[:identifier]
     @cents = attributes[:cents]
     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)

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
 
@@ -23,11 +23,8 @@ class HeadMusic::Rudiment::ChromaticInterval
   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

data/lib/head_music/rudiment/consonance.rb

@@ -1,13 +1,30 @@
 # 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
+  # Detailed categories aligned with music theory
+  LEVELS = %w[
+    perfect_consonance
+    imperfect_consonance
+    contextual
+    mild_dissonance
+    harsh_dissonance
+    dissonance
+  ].freeze
+
+  # Constants for each consonance level
+  PERFECT_CONSONANCE = :perfect_consonance
+  IMPERFECT_CONSONANCE = :imperfect_consonance
+  CONTEXTUAL = :contextual
+  MILD_DISSONANCE = :mild_dissonance
+  HARSH_DISSONANCE = :harsh_dissonance
+  DISSONANCE = :dissonance
 
   def self.get(name)
     @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.to_s)
   end
 
   attr_reader :name
@@ -22,6 +39,22 @@ 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 }
   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