head_music 8.3.0 → 11.0.0

data/lib/head_music/instruments/score_order.rb

@@ -0,0 +1,136 @@
+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 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)
+  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 = HeadMusic::Utilities::Case.to_snake_case(instrument.name)
+    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/staff.rb

@@ -1,4 +1,3 @@
-# Namespace for instrument definitions, categorization, and configuration
 module HeadMusic::Instruments; end
 
 class HeadMusic::Instruments::Staff
@@ -30,4 +29,65 @@ class HeadMusic::Instruments::Staff
   def name
     name_key.to_s.tr("_", " ")
   end
+
+  # Get all staff mappings for composite instruments
+  #
+  # @return [Array<Notation::StaffMapping>] array of staff mappings
+  # @example
+  #   drum_kit_staff.mappings  #=> [#<Notation::StaffMapping...>, #<Notation::StaffMapping...>]
+  def mappings
+    @mappings ||= parse_mappings
+  end
+
+  # Find the staff mapping at a specific position
+  #
+  # @param position_index [Integer] the staff position index
+  # @return [Notation::StaffMapping, nil] the mapping at that position or nil
+  # @example
+  #   staff.mapping_for_position(4)  #=> #<Notation::StaffMapping instrument: snare_drum...>
+  def mapping_for_position(position_index)
+    mappings.find { |mapping| mapping.position_index == position_index }
+  end
+
+  # Get the instrument at a specific staff position
+  #
+  # @param position_index [Integer] the staff position index
+  # @return [Instrument, nil] the instrument at that position or nil
+  # @example
+  #   staff.instrument_for_position(4)  #=> #<Instrument name: "snare drum">
+  def instrument_for_position(position_index)
+    mapping = mapping_for_position(position_index)
+    mapping&.instrument
+  end
+
+  # Get all staff positions for a given instrument
+  #
+  # This is useful for instruments that appear at multiple positions
+  # (e.g., hi-hat with stick and pedal techniques)
+  #
+  # @param instrument_key [String, Symbol] the instrument key
+  # @return [Array<Integer>] array of position indices
+  # @example
+  #   staff.positions_for_instrument("hi_hat")  #=> [-1, 9]
+  def positions_for_instrument(instrument_key)
+    mappings.select { |mapping| mapping.instrument_key.to_s == instrument_key.to_s }
+      .map(&:position_index)
+  end
+
+  # Get all unique instruments used in this staff's mappings
+  #
+  # @return [Array<Instrument>] array of unique instruments
+  # @example
+  #   drum_kit_staff.components  #=> [#<Instrument: bass_drum>, #<Instrument: snare_drum>, ...]
+  def components
+    mappings.map(&:instrument).compact.uniq
+  end
+
+  private
+
+  def parse_mappings
+    mappings_data = attributes["mappings"] || []
+
+    mappings_data.map { |mapping_attrs| HeadMusic::Notation::StaffMapping.new(mapping_attrs) }
+  end
 end

data/lib/head_music/instruments/staff_scheme.rb

@@ -1,13 +1,15 @@
 require_relative "staff"
 
-# Namespace for instrument definitions, categorization, and configuration
 module HeadMusic::Instruments; end
 
 class HeadMusic::Instruments::StaffScheme
-  attr_reader :variant, :key, :list
+  attr_reader :instrument, :key, :list
 
-  def initialize(variant:, key:, list:)
-    @variant = variant
+  # For backward compatibility, also alias as variant
+  alias_method :variant, :instrument
+
+  def initialize(key:, list:, instrument: nil, variant: nil)
+    @instrument = instrument || variant
     @key = key || "default"
     @list = list
   end

data/lib/head_music/instruments/stringing.rb

@@ -0,0 +1,115 @@
+module HeadMusic::Instruments; end
+
+# The string configuration for a stringed instrument.
+#
+# A Stringing defines the courses (strings) of an instrument and their
+# standard tuning pitches. Each course can have one or more strings.
+#
+# Examples:
+#   guitar = HeadMusic::Instruments::Instrument.get("guitar")
+#   stringing = HeadMusic::Instruments::Stringing.for_instrument(guitar)
+#   stringing.courses.map(&:standard_pitch)  # => [E2, A2, D3, G3, B3, E4]
+class HeadMusic::Instruments::Stringing
+  STRINGINGS = YAML.load_file(File.expand_path("stringings.yml", __dir__)).freeze
+
+  attr_reader :instrument_key, :courses
+
+  class << self
+    # Find the stringing for an instrument
+    # @param instrument [HeadMusic::Instruments::Instrument, String, Symbol] The instrument
+    # @return [Stringing, nil]
+    def for_instrument(instrument)
+      instrument_key = normalize_instrument_key(instrument)
+      return nil unless instrument_key
+
+      data = find_stringing_data(instrument_key, instrument)
+      return nil unless data
+
+      new(instrument_key: instrument_key, courses_data: data["courses"])
+    end
+
+    private
+
+    def normalize_instrument_key(instrument)
+      case instrument
+      when HeadMusic::Instruments::Instrument
+        instrument.name_key.to_s
+      else
+        instrument.to_s
+      end
+    end
+
+    def find_stringing_data(instrument_key, instrument)
+      # Direct match
+      return STRINGINGS[instrument_key] if STRINGINGS.key?(instrument_key)
+
+      # Try parent instrument if this is an Instrument object
+      if instrument.is_a?(HeadMusic::Instruments::Instrument) && instrument.parent
+        parent_key = instrument.parent.name_key.to_s
+        return STRINGINGS[parent_key] if STRINGINGS.key?(parent_key)
+      end
+
+      nil
+    end
+  end
+
+  def initialize(instrument_key:, courses_data:)
+    @instrument_key = instrument_key.to_sym
+    @courses = build_courses(courses_data)
+  end
+
+  # The instrument this stringing belongs to
+  # @return [HeadMusic::Instruments::Instrument]
+  def instrument
+    HeadMusic::Instruments::Instrument.get(instrument_key)
+  end
+
+  # Number of courses
+  # @return [Integer]
+  def course_count
+    courses.length
+  end
+
+  # Total number of physical strings across all courses
+  # @return [Integer]
+  def string_count
+    courses.sum(&:string_count)
+  end
+
+  # Standard pitches for each course (primary string only)
+  # @return [Array<HeadMusic::Rudiment::Pitch>]
+  def standard_pitches
+    courses.map(&:standard_pitch)
+  end
+
+  # Apply an alternate tuning to get adjusted pitches
+  # @param tuning [AlternateTuning] The alternate tuning to apply
+  # @return [Array<HeadMusic::Rudiment::Pitch>]
+  def pitches_with_tuning(tuning)
+    courses.each_with_index.map do |course, index|
+      semitone_adjustment = tuning.semitones[index] || 0
+      HeadMusic::Rudiment::Pitch.from_number(course.standard_pitch.to_i + semitone_adjustment)
+    end
+  end
+
+  def ==(other)
+    return false unless other.is_a?(self.class)
+
+    instrument_key == other.instrument_key && courses == other.courses
+  end
+
+  def to_s
+    "#{course_count}-course stringing for #{instrument_key}"
+  end
+
+  private
+
+  def build_courses(courses_data)
+    courses_data.map do |course_data|
+      HeadMusic::Instruments::StringingCourse.new(
+        standard_pitch: course_data["pitch"],
+        course_semitones: course_data["course_semitones"] || []
+      )
+    end
+  end
+end

data/lib/head_music/instruments/stringing_course.rb

@@ -0,0 +1,58 @@
+module HeadMusic::Instruments; end
+
+# A single course (string or set of strings) on a stringed instrument.
+#
+# A "course" is a set of strings that are played together. On most guitars,
+# each course has a single string. On a 12-string guitar or mandolin,
+# courses have multiple strings tuned in unison or octaves.
+#
+# Examples:
+#   - 6-string guitar: 6 courses, each with 1 string
+#   - 12-string guitar: 6 courses, each with 2 strings (octave or unison)
+#   - Mandolin: 4 courses, each with 2 strings in unison
+class HeadMusic::Instruments::StringingCourse
+  attr_reader :standard_pitch, :course_semitones
+
+  # @param standard_pitch [HeadMusic::Rudiment::Pitch, String] The pitch of the primary string
+  # @param course_semitones [Array<Integer>] Semitone offsets for additional strings in the course
+  def initialize(standard_pitch:, course_semitones: [])
+    @standard_pitch = HeadMusic::Rudiment::Pitch.get(standard_pitch)
+    @course_semitones = Array(course_semitones)
+  end
+
+  # Returns all pitches in this course (primary + additional strings)
+  # @return [Array<HeadMusic::Rudiment::Pitch>]
+  def pitches
+    [standard_pitch] + additional_pitches
+  end
+
+  # Returns the number of physical strings in this course
+  # @return [Integer]
+  def string_count
+    1 + course_semitones.length
+  end
+
+  # Whether this course has multiple strings
+  # @return [Boolean]
+  def doubled?
+    course_semitones.any?
+  end
+
+  def ==(other)
+    return false unless other.is_a?(self.class)
+
+    standard_pitch == other.standard_pitch && course_semitones == other.course_semitones
+  end
+
+  def to_s
+    standard_pitch.to_s
+  end
+
+  private
+
+  def additional_pitches
+    course_semitones.map do |semitones|
+      HeadMusic::Rudiment::Pitch.from_number(standard_pitch.to_i + semitones)
+    end
+  end
+end

data/lib/head_music/instruments/stringings.yml

@@ -0,0 +1,168 @@
+# Stringing configurations for stringed instruments.
+#
+# Each instrument has courses (strings played together).
+# course_semitones defines additional strings in a course relative to the pitch.
+#
+# Examples:
+#   - [] = single string
+#   - [12] = doubled an octave higher
+#   - [0] = doubled in unison
+
+guitar:
+  courses:
+    - pitch: E2
+    - pitch: A2
+    - pitch: D3
+    - pitch: G3
+    - pitch: B3
+    - pitch: E4
+
+twelve_string_guitar:
+  courses:
+    - pitch: E2
+      course_semitones: [12]
+    - pitch: A2
+      course_semitones: [12]
+    - pitch: D3
+      course_semitones: [12]
+    - pitch: G3
+      course_semitones: [12]
+    - pitch: B3
+      course_semitones: [0]
+    - pitch: E4
+      course_semitones: [0]
+
+bass_guitar:
+  courses:
+    - pitch: E1
+    - pitch: A1
+    - pitch: D2
+    - pitch: G2
+
+five_string_bass:
+  courses:
+    - pitch: B0
+    - pitch: E1
+    - pitch: A1
+    - pitch: D2
+    - pitch: G2
+
+six_string_bass:
+  courses:
+    - pitch: B0
+    - pitch: E1
+    - pitch: A1
+    - pitch: D2
+    - pitch: G2
+    - pitch: C3
+
+ukulele:
+  courses:
+    - pitch: G4
+    - pitch: C4
+    - pitch: E4
+    - pitch: A4
+
+baritone_ukulele:
+  courses:
+    - pitch: D3
+    - pitch: G3
+    - pitch: B3
+    - pitch: E4
+
+mandolin:
+  courses:
+    - pitch: G3
+      course_semitones: [0]
+    - pitch: D4
+      course_semitones: [0]
+    - pitch: A4
+      course_semitones: [0]
+    - pitch: E5
+      course_semitones: [0]
+
+banjo:
+  courses:
+    - pitch: G4
+    - pitch: D3
+    - pitch: G3
+    - pitch: B3
+    - pitch: D4
+
+violin:
+  courses:
+    - pitch: G3
+    - pitch: D4
+    - pitch: A4
+    - pitch: E5
+
+viola:
+  courses:
+    - pitch: C3
+    - pitch: G3
+    - pitch: D4
+    - pitch: A4
+
+cello:
+  courses:
+    - pitch: C2
+    - pitch: G2
+    - pitch: D3
+    - pitch: A3
+
+double_bass:
+  courses:
+    - pitch: E1
+    - pitch: A1
+    - pitch: D2
+    - pitch: G2
+
+harp:
+  courses:
+    - pitch: C1
+    - pitch: D1
+    - pitch: E1
+    - pitch: F1
+    - pitch: G1
+    - pitch: A1
+    - pitch: B1
+    - pitch: C2
+    - pitch: D2
+    - pitch: E2
+    - pitch: F2
+    - pitch: G2
+    - pitch: A2
+    - pitch: B2
+    - pitch: C3
+    - pitch: D3
+    - pitch: E3
+    - pitch: F3
+    - pitch: G3
+    - pitch: A3
+    - pitch: B3
+    - pitch: C4
+    - pitch: D4
+    - pitch: E4
+    - pitch: F4
+    - pitch: G4
+    - pitch: A4
+    - pitch: B4
+    - pitch: C5
+    - pitch: D5
+    - pitch: E5
+    - pitch: F5
+    - pitch: G5
+    - pitch: A5
+    - pitch: B5
+    - pitch: C6
+    - pitch: D6
+    - pitch: E6
+    - pitch: F6
+    - pitch: G6
+    - pitch: A6
+    - pitch: B6
+    - pitch: C7
+    - pitch: D7
+    - pitch: E7
+    - pitch: F7
+    - pitch: G7

data/lib/head_music/instruments/variant.rb

@@ -1,4 +1,3 @@
-# Namespace for instrument definitions, categorization, and configuration
 module HeadMusic::Instruments; end
 
 class HeadMusic::Instruments::Variant
@@ -35,4 +34,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