head_music 1.0.0 → 2.0.0

data/lib/head_music/instrument.rb

@@ -1,23 +1,47 @@
 # frozen_string_literal: true
 
-# An instrument can be assigned to a staff.
+# 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
+#   transposition: the number of semitones between the written and the sounding pitch (optional, default: 0)
+#   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
+#   notation:
+#     a hash of default and alternative notation systems,
+#     each with a staffs key with an array of hashes
+#     including clef and transposition (where applicable)
+# Associations:
+#   family: the family of the instrument (e.g. "saxophone")
+#   orchestra_section: the section of the orchestra (e.g. "strings")
 class HeadMusic::Instrument
   include HeadMusic::Named
 
   INSTRUMENTS = YAML.load_file(File.expand_path("data/instruments.yml", __dir__)).freeze
 
   def self.get(name)
-    return get_by_name(name) if get_by_name(name)
-    return get_by_name(key_for_name(name)) if key_for_name(name)
-
-    new(name)
+    result = get_by_name(name) || get_by_name(key_for_name(name)) || get_by_alias(name)
+    result || new(name)
   end
 
   def self.all
-    INSTRUMENTS.map { |key, _data| get(key) }.sort_by(&:name)
+    HeadMusic::InstrumentFamily.all
+    @all ||=
+      INSTRUMENTS.map { |key, _data| get(key) }.sort_by(&:name)
   end
 
-  attr_reader :name_key, :family, :standard_staves, :classifications
+  attr_reader(
+    :name_key, :alias_name_keys,
+    :family_key, :orchestra_section_key,
+    :notation, :classification_keys,
+    :fundamental_pitch_spelling, :transposition,
+    :default_staffs, :default_clefs
+  )
 
   def ==(other)
     to_s == other.to_s
@@ -29,6 +53,36 @@ class HeadMusic::Instrument
     I18n.translate(name_key, scope: [:instruments], locale: locale)
   end
 
+  def family
+    return unless family_key
+
+    HeadMusic::InstrumentFamily.get(family_key)
+  end
+
+  # Returns true if the instrument sounds at a different pitch than written.
+  def transposing?
+    transposition != 0
+  end
+
+  # Returns true if the instrument sounds at a different register than written.
+  def transposing_at_the_octave?
+    transposing? && transposition % 12 == 0
+  end
+
+  def single_staff?
+    default_staffs.length == 1
+  end
+
+  def multiple_staffs?
+    default_staffs.length > 1
+  end
+
+  def pitched?
+    return false if default_clefs.compact.uniq == ["percussion"]
+
+    default_clefs.any?
+  end
+
   private_class_method :new
 
   private
@@ -65,11 +119,37 @@ class HeadMusic::Instrument
   end
 
   def initialize_data_from_record(record)
+    initialize_family(record)
+    inherit_family_attributes(record)
+    initialize_names(record)
+    initialize_attributes(record)
+  end
+
+  def initialize_family(record)
+    @family_key = record["family_key"]
+    @family = HeadMusic::InstrumentFamily.get(family_key)
+  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
-    @family = record["family"]
-    @standard_staves = record["standard_staves"] || []
-    @classifications = record["classifications"] || []
     self.name = I18n.translate(name_key, scope: "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
+    @fundamental_pitch_spelling = record["fundamental_pitch_spelling"]
+    @default_staffs = (record.dig("notation", "default", "staffs") || [])
+    @default_clefs = @default_staffs.map { |staff| staff["clef"] }
+    @transposition = @default_staffs&.first&.[]("transposition") || 0
   end
 
   def inferred_name

data/lib/head_music/instrument_family.rb

@@ -0,0 +1,69 @@
+# 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.
+class HeadMusic::InstrumentFamily
+  include HeadMusic::Named
+
+  INSTRUMENT_FAMILIES =
+    YAML.load_file(File.expand_path("data/instrument_families.yml", __dir__)).freeze
+
+  attr_reader :name_key, :classification_keys, :orchestra_section_key, :default_staffs
+  attr_accessor :name
+
+  def self.get(name)
+    result = get_by_name(name) || get_by_name(key_for_name(name))
+    result || new(name)
+  end
+
+  def self.all
+    @all ||=
+      INSTRUMENT_FAMILIES.map { |key, _data| get(key) }.sort_by(&:name)
+  end
+
+  private_class_method :new
+
+  private
+
+  def initialize(name)
+    record = record_for_name(name)
+    if record
+      initialize_data_from_record(record)
+    else
+      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))
+  end
+
+  def key_for_name(name)
+    INSTRUMENT_FAMILIES.each do |key, _data|
+      I18n.config.available_locales.each do |locale|
+        translation = I18n.t("instruments.#{key}", locale: locale)
+        return key if translation.downcase == name.downcase
+      end
+    end
+    nil
+  end
+
+  def record_for_key(key)
+    INSTRUMENT_FAMILIES.each do |name_key, data|
+      return data.merge!("name_key" => name_key) if name_key.to_s == key.to_s
+    end
+    nil
+  end
+
+  def initialize_data_from_record(record)
+    @name_key = record["name_key"].to_sym
+    @orchestra_section_key = record["orchestra_section_key"]
+    @classification_keys = record["classification_keys"] || []
+    self.name = I18n.translate(name_key, scope: "instruments", locale: "en", default: inferred_name)
+  end
+
+  def inferred_name
+    name_key.to_s.tr("_", " ")
+  end
+end

data/lib/head_music/locales/de.yml

@@ -6,7 +6,7 @@ de:
     baritone_f_clef: Baritonschlüssel
     bass_clef: Bassschlüssel
     c_clef: C-Schlüssel
-    choral_tenor_clef: oktavierten Violinschlüssel
+    vocal_tenor_clef: oktavierten Violinschlüssel
     contrabass_clef: contrabass clef
     countertenor_clef: countertenor clef
     double_treble_clef: double treble clef
@@ -61,10 +61,10 @@ de:
     bagpipe: Dudelsack
     baritone_horn: Baritonhorn
     baritone_voice: Bariton
-    bass_voice: Bass
     bass_clarinet: Bassklarinette
     bass_drum: Grosse Trommel
     bass_trombone: Bass Posaune
+    bass_voice: Bass
     bassoon: Fagott
     castanets: Kastagnetten
     celesta: Celesta
@@ -78,7 +78,7 @@ de:
     english_horn: Englischhorn
     euphonium: Euphonium
     fiddle: Geige
-    flugel_horn: Flügelhorn
+    flugelhorn: Flügelhorn
     flute: Flöte
     french_horn: Horn
     glockenspiel: Glockenspiel

data/lib/head_music/locales/en.yml

@@ -6,7 +6,7 @@ en:
     baritone_f_clef: baritone F-clef
     bass_clef: bass clef
     c_clef: C-clef
-    choral_tenor_clef: choral tenor clef
+    vocal_tenor_clef: vocal tenor clef
     contrabass_clef: contrabass clef
     countertenor_clef: countertenor clef
     double_treble_clef: double treble clef
@@ -92,7 +92,6 @@ en:
     bass_drum: bass drum
     bass_guitar: bass guitar
     bass_oboe: bass oboe
-    bass_drum: bass drum
     bass_trombone: bass trombone
     bass_tuba: bass tuba
     bass_voice: bass
@@ -102,21 +101,20 @@ en:
     cello: cello
     chimes: chimes
     cimbalom: cimbalom
-    cowbell: cowbell
     clarinet: clarinet
-    clavichord: clavichord
     clash_cymbals: clash cymbals
-    cornet: cornet
-    contrabassoon: contrabassoon
+    clavichord: clavichord
     contra_bass_clarinet: contra bass clarinet
+    contrabassoon: contrabassoon
     cor_anglais: cor anglais
+    cornet: cornet
     cowbell: cowbell
-    cymbal: cymbal
     crotales: crotales
+    cymbal: cymbal
     double_bass: double bass
     english_horn: English horn
     euphonium: euphonium
-    flugel_horn: flugel horn
+    flugelhorn: flugelhorn
     flute: flute
     french_horn: French horn
     glockenspiel: glockenspiel

data/lib/head_music/locales/es.yml

@@ -6,7 +6,7 @@ es:
     baritone_f_clef: clave de fa en tercera
     bass_clef: clave de bajo
     c_clef: clave de do
-    choral_tenor_clef: choral tenor clef
+    vocal_tenor_clef: vocal tenor clef
     contrabass_clef: clave de contrabajo
     countertenor_clef: clave de contratenor
     double_treble_clef: double clave de sol
@@ -72,7 +72,7 @@ es:
     double_bass: contrabajo
     english_horn: Cuerno inglés
     euphonium: euphonium
-    flugel_horn: fliscorno
+    flugelhorn: fliscorno
     flute: flauta
     french_horn: corno
     glockenspiel: campanólogo

data/lib/head_music/locales/fr.yml

@@ -6,7 +6,7 @@ fr:
     baritone_f_clef: clé de fa 3e
     bass_clef: clé de basse
     c_clef: clé d'ut
-    choral_tenor_clef: choral tenor clef
+    vocal_tenor_clef: vocal tenor clef
     contrabass_clef: clé de contrebasse
     countertenor_clef: clé de contre-ténor
     double_treble_clef: double clé de sol

data/lib/head_music/locales/it.yml

@@ -6,7 +6,7 @@ it:
     baritone_f_clef: chiave di baritono
     bass_clef: chiave di basso
     c_clef: chiave di do
-    choral_tenor_clef: chiave di sol in ottava
+    vocal_tenor_clef: chiave di sol in ottava
     contrabass_clef: chiave di contrabbasso
     countertenor_clef: chiave di controtenore
     double_treble_clef: chiave di sol in ottava
@@ -76,7 +76,7 @@ it:
     double_bass: contrabasso
     english_horn: corno inglese
     euphonium: eufonio
-    flugel_horn: flicorno
+    flugelhorn: flicorno
     flute: flauto
     french_horn: corno
     glockenspiel: glockenspiel
@@ -91,9 +91,9 @@ it:
     natural_horn: corno naturale
     oboe: oboe
     oboe_d_amore: oboe d'amore
-    piccolo: ottavino
     organ: organo
     piano: piano
+    piccolo: ottavino
     recorder: flauto dolce
     saxophone: sassofono
     snare_drum: tamburo rullante

data/lib/head_music/locales/ru.yml

@@ -32,7 +32,7 @@ ru:
     double_bass: kontrabas
     english_horn: angliiskii rozhok
     euphonium: evfonium
-    flugel_horn: fliugel'gorn
+    flugelhorn: fliugel'gorn
     flute: fleita
     french_horn: Gorn
     glockenspiel: kolokol'chiki
@@ -67,4 +67,4 @@ ru:
     violoncello: violonchel'
     voice: golos
     xylophone: ksilofon
-    zither: tsitra
+    zither: tsitra

data/lib/head_music/staff.rb

@@ -5,11 +5,14 @@ class HeadMusic::Staff
   DEFAULT_LINE_COUNT = 5
 
   attr_reader :default_clef, :line_count, :instrument
-  alias_method :clef, :default_clef
 
   def initialize(default_clef, instrument: nil, line_count: nil)
     @default_clef = HeadMusic::Clef.get(default_clef)
     @line_count = line_count || DEFAULT_LINE_COUNT
     @instrument = HeadMusic::Instrument.get(instrument) if instrument
   end
+
+  def clef
+    default_clef || instrument&.default_staffs&.first
+  end
 end

data/lib/head_music/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module HeadMusic
-  VERSION = "1.0.0"
+  VERSION = "2.0.0"
 end

data/lib/head_music.rb

@@ -39,8 +39,8 @@ require "head_music/circle"
 require "head_music/clef"
 require "head_music/consonance"
 require "head_music/diatonic_interval"
-require "head_music/grand_staff"
 require "head_music/harmonic_interval"
+require "head_music/instrument_family"
 require "head_music/instrument"
 require "head_music/interval_cycle"
 require "head_music/key_signature"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: head_music
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Rob Head
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-05-03 00:00:00.000000000 Z
+date: 2023-07-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -132,11 +132,12 @@ files:
 - lib/head_music/content/rhythmic_value.rb
 - lib/head_music/content/voice.rb
 - lib/head_music/data/clefs.yml
+- lib/head_music/data/instrument_families.yml
 - lib/head_music/data/instruments.yml
 - lib/head_music/diatonic_interval.rb
-- lib/head_music/grand_staff.rb
 - lib/head_music/harmonic_interval.rb
 - lib/head_music/instrument.rb
+- lib/head_music/instrument_family.rb
 - lib/head_music/interval_cycle.rb
 - lib/head_music/key_signature.rb
 - lib/head_music/letter_name.rb
@@ -234,7 +235,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.26
+rubygems_version: 3.4.12
 signing_key:
 specification_version: 4
 summary: The rudiments of western music theory.

data/lib/head_music/grand_staff.rb

@@ -1,56 +0,0 @@
-# frozen_string_literal: true
-
-# A grand staff is a group of staves for a single instrument, such as a piano.
-class HeadMusic::GrandStaff
-  GRAND_STAVES = {
-    piano: {
-      instrument: :piano,
-      staves: [
-        {clef: :treble_clef, for: :right_hand},
-        {clef: :bass_clef, for: :left_hand}
-      ]
-    },
-    organ: {
-      instrument: :organ,
-      staves: [
-        {clef: :treble_clef, for: :right_hand},
-        {clef: :bass_clef, for: :left_hand},
-        {clef: :bass_clef, for: :pedals}
-      ]
-    }
-  }.freeze
-
-  def self.get(name)
-    @grand_staves ||= {}
-    hash_key = HeadMusic::Utilities::HashKey.for(name)
-    return nil unless GRAND_STAVES.key?(hash_key)
-
-    @grand_staves[hash_key] ||= new(hash_key)
-  end
-
-  attr_reader :identifier, :data
-
-  def initialize(name)
-    @identifier = HeadMusic::Utilities::HashKey.for(name)
-    @data = GRAND_STAVES[identifier]
-  end
-
-  def instrument
-    @instrument ||= HeadMusic::Instrument.get(data[:instrument])
-  end
-
-  def staves
-    @staves ||=
-      data[:staves].map do |staff|
-        HeadMusic::Staff.new(staff[:clef], instrument: instrument)
-      end
-  end
-
-  def brace_staves_index_first
-    0
-  end
-
-  def brace_staves_index_last
-    1
-  end
-end