head_music 9.0.1 → 11.0.0

data/lib/head_music/instruments/score_order.rb

@@ -72,14 +72,11 @@ class HeadMusic::Instruments::ScoreOrder
     # 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)
+    HeadMusic::Instruments::Instrument.get(input)
   end
 
   # Builds an index mapping instrument names to their position in the order
@@ -120,7 +117,7 @@ class HeadMusic::Instruments::ScoreOrder
     end
 
     # Try normalized name (lowercase, underscored)
-    normalized = instrument.name.downcase.tr(" ", "_").tr("-", "_")
+    normalized = HeadMusic::Utilities::Case.to_snake_case(instrument.name)
     return ordering_index[normalized] if ordering_index.key?(normalized)
 
     nil

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

data/lib/head_music/locales/de.yml

@@ -159,6 +159,8 @@ de:
       descant: Diskant
       didgeridoo: Didgeridoo
       double_bass: Kontrabass
+      drum_kit: Schlagzeug
+      floor_tom: Floor-Tom
       double_contrabass_recorder: Doppelkontrabassblockflöte
       english_horn: Englischhorn
       euphonium: Euphonium
@@ -179,6 +181,7 @@ de:
       harpsichord: Cembalo
       hautbois_d_amour: Liebeshoboe
       hi-hat: Hi-Hat
+      high_tom: High-Tom
       horn: Horn
       kettledrum: Pauke
       kick_drum: Große Trommel
@@ -190,6 +193,7 @@ de:
       mezzo: Mezzo
       mezzo_soprano: Mezzosopran
       mezzo_soprano_voice: Mezzosopran
+      mid_tom: Mid-Tom
       military_drum: Militärtrommel
       mouth_organ: Mundharmonika
       natural_horn: Waldhorn
@@ -278,6 +282,25 @@ de:
       woodblock: Holzblock
       xylophone: Xylophon
       zither: Zither
+    instrument_families:
+      drum_kit: Schlagzeug
+      hi_hat: Hi-Hat
+      tom_tom: Tom-Tom
+    playing_techniques:
+      bell: Glocke
+      bow: Bogen
+      brush: Bürste
+      choked: Erstickt
+      closed: Geschlossen
+      cross_stick: Querstöckchen
+      damped: Gedämpft
+      hand: Hand
+      let_ring: Ausklingen lassen
+      mallet: Schläger
+      open: Offen
+      pedal: Pedal
+      rim_shot: Rimshot
+      stick: Stick
     locales:
       de: Deutsch
       en: Englisch

data/lib/head_music/locales/en.yml

@@ -276,6 +276,7 @@ en:
       cymbal: cymbal
       descant: descant
       didgeridoo: didgeridoo
+      drum_kit: drum kit
       double_bass: double bass
       double_contrabass_recorder: double-contrabass recorder
       electronic_keyboard: electronic keyboard
@@ -283,6 +284,7 @@ en:
       euphonium: euphonium
       fiddle: fiddle
       field_drum: field drum
+      floor_tom: floor tom
       flugelhorn: flugelhorn
       flute: flute
       fortepiano: fortepiano
@@ -299,6 +301,7 @@ en:
       harpsichord: harpsichord
       hautbois_d_amour: hautbois d'amour
       hi-hat: hi-hat
+      high_tom: high tom
       horn: horn
       kettledrum: kettledrum
       kick_drum: kick drum
@@ -310,6 +313,7 @@ en:
       mezzo: mezzo
       mezzo_soprano: mezzo-soprano
       mezzo_soprano_voice: mezzo-soprano
+      mid_tom: mid tom
       military_drum: military drum
       mouth_organ: mouth_organ
       natural_horn: natural horn
@@ -397,6 +401,102 @@ en:
       woodblock: woodblock
       xylophone: xylophone
       zither: zither
+    instrument_families:
+      drum_kit: drum kit
+      hi_hat: hi-hat
+      tom_tom: tom-tom
+    playing_techniques:
+      aeolian: aeolian
+      air: air
+      alla_chitarra: alla chitarra
+      arco: arco
+      artificial_harmonic: artificial harmonic
+      au_talon: au talon
+      barre: barré
+      bell: bell
+      bisbigliando: bisbigliando
+      bow: bow
+      brush: brush
+      bucket_mute: bucket mute
+      center: center
+      choked: choked
+      closed: closed
+      col_legno: col legno
+      col_legno_battuto: col legno battuto
+      col_legno_tratto: col legno tratto
+      con_bocca_chiusa: con bocca chiusa
+      con_sordino: con sordino
+      cross_stick: cross stick
+      cuivre: cuivré
+      cup_mute: cup mute
+      damped: damped
+      dead_stroke: dead stroke
+      detache: détaché
+      edge: edge
+      flautando: flautando
+      flutter_tongue: flutter tongue
+      frullato: frullato
+      half_barre: half barré
+      hand: hand
+      harmonic: harmonic
+      jete: jeté
+      harmon_mute: harmon mute
+      harmon_mute_stem_in: harmon mute stem in
+      harmon_mute_stem_out: harmon mute stem out
+      key_clicks: key clicks
+      laissez_vibrer: laissez vibrer
+      left_hand: left hand
+      legato: legato
+      let_ring: let ring
+      mallet: mallet
+      marcato: marcato
+      martele: martelé
+      martellato: martellato
+      modo_ordinario: modo ordinario
+      motor_off: motor off
+      motor_on: motor on
+      muffled: muffled
+      multiphonic: multiphonic
+      natural_harmonic: natural harmonic
+      naturale: naturale
+      non_laissez_vibrer: non laissez vibrer
+      non_vibrato: non vibrato
+      open: open
+      open_percussion: open
+      ordinario: ordinario
+      half_pedal: half pedal
+      mano_destra: mano destra
+      mano_sinistra: mano sinistra
+      palm_mute: palm mute
+      pedal: pedal
+      pizzicato: pizzicato
+      plunger_mute: plunger mute
+      poco_vibrato: poco vibrato
+      punta_d_arco: punta d'arco
+      quarter_pedal: quarter pedal
+      pres_de_la_table: près de la table
+      right_hand: right hand
+      rim_shot: rim shot
+      saltando: saltando
+      senza_sordino: senza sordino
+      senza_vibrato: senza vibrato
+      slap_tongue: slap tongue
+      snares_off: snares off
+      snares_on: snares on
+      sopra: sopra
+      sostenuto_pedal: sostenuto pedal
+      sotto: sotto
+      spiccato: spiccato
+      stick: stick
+      stopped: stopped
+      straight_mute: straight mute
+      sul_ponticello: sul ponticello
+      sul_tasto: sul tasto
+      three_quarter_pedal: three quarter pedal
+      tre_corde: tre corde
+      una_corda: una corda
+      vibrato: vibrato
+      whistle_tone: whistle tone
     locales:
       de: German
       en: English

data/lib/head_music/locales/es.yml

@@ -155,6 +155,8 @@ es:
       descant: flauta dulce soprano
       didgeridoo: didgeridoo
       double_bass: contrabajo
+      drum_kit: batería
+      floor_tom: tom de piso
       double_contrabass_recorder: flauta dulce subcontrabajo
       english_horn: corno inglés
       euphonium: euphonium
@@ -176,6 +178,7 @@ es:
       harpsichord: clavecín
       hautbois_d_amour: oboe de amor
       hi-hat: charles
+      high_tom: tom agudo
       horn: corno
       kettledrum: timbal
       kick_drum: bombo
@@ -187,6 +190,7 @@ es:
       mezzo: mezzosoprano
       mezzo_soprano: mezzosoprano
       mezzo_soprano_voice: voz de mezzosoprano
+      mid_tom: tom grave
       military_drum: tambor militar
       mouth_organ: armónica
       natural_horn: trompa natural
@@ -275,6 +279,25 @@ es:
       woodblock: bloque de madera
       xylophone: xilofón
       zither: cítara
+    instrument_families:
+      drum_kit: batería
+      hi_hat: charles
+      tom_tom: tom-tom
+    playing_techniques:
+      bell: campana
+      bow: arco
+      brush: cepillo
+      choked: apagado
+      closed: cerrado
+      cross_stick: baqueta inversa
+      damped: amortiguado
+      hand: mano
+      let_ring: dejar sonar
+      mallet: baqueta
+      open: abierto
+      pedal: pedal
+      rim_shot: golpe de borde
+      stick: baqueta
     locales:
       de: alemán
       en: inglés