head_music 17.3.0 → 17.5.0

data/lib/head_music/analysis/dyad.rb

@@ -31,11 +31,7 @@ class HeadMusic::Analysis::Dyad
   end
 
   def possible_trichords
-    @possible_trichords ||= begin
-      trichords = generate_possible_trichords
-      trichords = filter_by_key(trichords) if key
-      sort_by_diatonic_agreement(trichords)
-    end
+    chord_implication.trichords
   end
 
   def possible_triads
@@ -43,11 +39,7 @@ class HeadMusic::Analysis::Dyad
   end
 
   def possible_seventh_chords
-    @possible_seventh_chords ||= begin
-      seventh_chords = generate_possible_seventh_chords
-      seventh_chords = filter_by_key(seventh_chords) if key
-      sort_by_diatonic_agreement(seventh_chords)
-    end
+    chord_implication.seventh_chords
   end
 
   def enharmonic_respellings
@@ -68,111 +60,39 @@ class HeadMusic::Analysis::Dyad
 
   private
 
-  TRICHORD_INTERVALS = [
-    %w[M3 P5],   # major triad
-    %w[m3 P5],   # minor triad
-    %w[m3 d5],   # diminished triad
-    %w[M3 A5],   # augmented triad
-    %w[P4 P5],   # sus4 (not a triad)
-    %w[M2 P5]    # sus2 (not a triad)
-  ].freeze
-
-  SEVENTH_CHORD_INTERVALS = [
-    %w[M3 P5 M7],   # major seventh
-    %w[M3 P5 m7],   # dominant seventh (major-minor)
-    %w[m3 P5 m7],   # minor seventh
-    %w[m3 P5 M7],   # minor-major seventh
-    %w[m3 d5 m7],   # half-diminished seventh
-    %w[m3 d5 d7],   # diminished seventh
-    %w[M2 M3 P5 m7], # dominant ninth
-    %w[m2 M3 P5 m7], # dominant minor ninth
-    %w[M2 m3 P5 m7], # minor ninth
-    %w[M2 M3 P5 M7]  # major ninth
-  ].freeze
-
-  def generate_possible_trichords
-    generate_possible_chords(TRICHORD_INTERVALS)
-  end
-
-  def generate_possible_seventh_chords
-    generate_possible_chords(SEVENTH_CHORD_INTERVALS)
-  end
-
-  def generate_possible_chords(interval_sets)
-    dyad_pitch_classes = [lower_pitch.pitch_class, upper_pitch.pitch_class]
-    chords = []
-
-    HeadMusic::Rudiment::Spelling::CHROMATIC_SPELLINGS.each do |root_spelling|
-      root_pitch = HeadMusic::Rudiment::Pitch.get("#{root_spelling}4")
-
-      interval_sets.each do |intervals|
-        chord_pitches = [root_pitch] + intervals.map { |name| HeadMusic::Analysis::DiatonicInterval.get(name).above(root_pitch) }
-        pitch_collection = HeadMusic::Analysis::PitchCollection.new(chord_pitches)
-
-        if dyad_pitch_classes.all? { |pc| pitch_collection.pitch_classes.include?(pc) }
-          chords << pitch_collection
-        end
-      end
-    end
-
-    chords.uniq { |chord| chord.pitch_classes.sort.map(&:to_i) }
-  end
-
-  def filter_by_key(pitch_collections)
-    return pitch_collections unless key
-
-    pitch_collections.select do |pitch_collection|
-      pitch_collection.pitches.all? { |pitch| diatonic_spellings.include?(pitch.spelling) }
-    end
-  end
-
-  def sort_by_diatonic_agreement(pitch_collections)
-    return pitch_collections unless key
-
-    pitch_collections.sort_by do |pitch_collection|
-      -pitch_collection.pitches.count { |pitch| diatonic_spellings.include?(pitch.spelling) }
-    end
-  end
-
-  def diatonic_spellings
-    @diatonic_spellings ||= key.scale.spellings
+  def chord_implication
+    @chord_implication ||= ChordImplication.new([lower_pitch.pitch_class, upper_pitch.pitch_class], key)
   end
 
   def generate_enharmonic_respellings
-    respellings = []
-
-    # Get enharmonic equivalents for each pitch
-    pitch1_equivalents = enharmonic_equivalents_for(pitch1)
-    pitch2_equivalents = enharmonic_equivalents_for(pitch2)
+    lower_equivalents = enharmonic_equivalents_for(pitch1)
+    upper_equivalents = enharmonic_equivalents_for(pitch2)
 
-    # Generate all combinations
-    pitch1_equivalents.each do |lower|
-      pitch2_equivalents.each do |upper|
-        next if lower.spelling == pitch1.spelling && upper.spelling == pitch2.spelling
-
-        respellings << self.class.new(lower, upper, key: key)
-      end
-    end
+    lower_equivalents.product(upper_equivalents)
+      .reject { |lower, upper| original_spelling?(lower, upper) }
+      .map { |lower, upper| self.class.new(lower, upper, key: key) }
+  end
 
-    respellings
+  def original_spelling?(lower, upper)
+    lower.spelling == pitch1.spelling && upper.spelling == pitch2.spelling
   end
 
   ALTERATION_SIGNS = {-2 => "bb", -1 => "b", 0 => "", 1 => "#", 2 => "##"}.freeze
 
   def enharmonic_equivalents_for(pitch)
-    target_pitch_class = pitch.pitch_class
-    equivalents = [pitch]
-
-    HeadMusic::Rudiment::LetterName.all.each do |letter_name|
-      ALTERATION_SIGNS.each_value do |sign|
-        spelling = HeadMusic::Rudiment::Spelling.get("#{letter_name}#{sign}")
-        next unless spelling && spelling.pitch_class == target_pitch_class
-        next if equivalents.any? { |equiv| equiv.spelling == spelling }
-
-        equivalents << HeadMusic::Rudiment::Pitch.fetch_or_create(spelling, pitch.register)
-      end
+    equivalent_pitches = enharmonic_spellings_for(pitch.pitch_class).map do |spelling|
+      HeadMusic::Rudiment::Pitch.fetch_or_create(spelling, pitch.register)
     end
+    [pitch, *equivalent_pitches].uniq(&:spelling)
+  end
+
+  def enharmonic_spellings_for(target_pitch_class)
+    all_spellings.select { |spelling| spelling.pitch_class == target_pitch_class }
+  end
 
-    equivalents
+  def all_spellings
+    HeadMusic::Rudiment::LetterName.all.flat_map do |letter_name|
+      ALTERATION_SIGNS.each_value.map { |sign| HeadMusic::Rudiment::Spelling.get("#{letter_name}#{sign}") }
+    end.compact
   end
 end

data/lib/head_music/analysis/interval_cycle.rb

@@ -41,15 +41,21 @@ class HeadMusic::Analysis::IntervalCycle
   def pitches_up
     @pitches_up ||= [starting_pitch].tap do |list|
       loop do
-        next_pitch = list.last + interval
-        next_pitch -= octave while next_pitch - starting_pitch > 12
-        break if next_pitch.pitch_class == list.first.pitch_class
+        next_pitch = folded_up(list.last)
+        break if next_pitch.pitch_class == starting_pitch.pitch_class
 
         list << next_pitch
       end
     end
   end
 
+  # The next pitch a cycle-interval above, folded down by octaves to stay within an octave of the start.
+  def folded_up(pitch)
+    next_pitch = pitch + interval
+    next_pitch -= octave while next_pitch - starting_pitch > 12
+    next_pitch
+  end
+
   def octave
     @octave ||= HeadMusic::Analysis::DiatonicInterval.get(:perfect_octave)
   end

data/lib/head_music/analysis/pitch_collection.rb

@@ -6,15 +6,6 @@ module HeadMusic::Analysis; end
 # as distinct from a "pitch-class set" which abstracts away register and octave equivalence.
 # See also: PitchClassSet
 class HeadMusic::Analysis::PitchCollection
-  TERTIAN_SONORITIES = {
-    implied_triad: [3],
-    triad: [3, 5],
-    seventh_chord: [3, 5, 7],
-    ninth_chord: [2, 3, 5, 7],
-    eleventh_chord: [2, 3, 4, 5, 7],
-    thirteenth_chord: [2, 3, 4, 5, 6, 7] # a.k.a. diatonic scale
-  }.freeze
-
   attr_reader :pitches
 
   delegate :diatonic_intervals, to: :reduction, prefix: true
@@ -24,6 +15,17 @@ class HeadMusic::Analysis::PitchCollection
   delegate :heptachord?, :octachord?, :nonachord?, :decachord?, :undecachord?, :dodecachord?, to: :pitch_class_set
   delegate :size, to: :pitch_class_set, prefix: true
 
+  # Tertian chord classification (triad/seventh/extended, quality, inversion).
+  delegate(
+    :triad?, :consonant_triad?,
+    :major_triad?, :minor_triad?, :diminished_triad?, :augmented_triad?,
+    :root_position_triad?, :first_inversion_triad?, :second_inversion_triad?,
+    :seventh_chord?, :root_position_seventh_chord?, :first_inversion_seventh_chord?,
+    :second_inversion_seventh_chord?, :third_inversion_seventh_chord?,
+    :ninth_chord?, :eleventh_chord?, :thirteenth_chord?, :tertian?,
+    to: :chord_analysis
+  )
+
   def initialize(pitches)
     @pitches = pitches.map { |pitch| HeadMusic::Rudiment::Pitch.get(pitch) }.sort.uniq
   end
@@ -60,20 +62,17 @@ class HeadMusic::Analysis::PitchCollection
     # questions:
     # - should this be absolute? 0 = C?
     # - should there be both absolute and relative versions?
-    @integer_notation ||= begin
-      return [] if pitches.empty?
-      diatonic_intervals_above_bass_pitch.map { |interval| interval.semitones % 12 }.flatten.sort.unshift(0).uniq
-    end
+    @integer_notation ||= integer_notation_values
   end
 
   def invert
-    inverted_pitch = pitches[0] + HeadMusic::Analysis::DiatonicInterval.get("perfect octave")
+    inverted_pitch = pitches.first + octave
     new_pitches = pitches.drop(1) + [inverted_pitch]
     HeadMusic::Analysis::PitchCollection.new(new_pitches)
   end
 
   def uninvert
-    inverted_pitch = pitches[-1] - HeadMusic::Analysis::DiatonicInterval.get("perfect octave")
+    inverted_pitch = pitches.last - octave
     new_pitches = [inverted_pitch] + pitches[0..-2]
     HeadMusic::Analysis::PitchCollection.new(new_pitches)
   end
@@ -83,11 +82,11 @@ class HeadMusic::Analysis::PitchCollection
   end
 
   def inspect
-    pitches.map(&:to_s).join(" ")
+    pitches.join(" ")
   end
 
   def to_s
-    pitches.map(&:to_s).join(" ")
+    pitches.join(" ")
   end
 
   def ==(other)
@@ -102,92 +101,6 @@ class HeadMusic::Analysis::PitchCollection
     pitches.length
   end
 
-  def triad?
-    trichord? && tertian?
-  end
-
-  def consonant_triad?
-    major_triad? || minor_triad?
-  end
-
-  TRIAD_PATTERNS = {
-    major: [%w[M3 m3], %w[m3 P4], %w[P4 M3]],
-    minor: [%w[m3 M3], %w[M3 P4], %w[P4 m3]],
-    diminished: [%w[m3 m3], %w[m3 A4], %w[A4 m3]],
-    augmented: [%w[M3 M3], %w[M3 d4], %w[d4 M3]]
-  }.freeze
-
-  def major_triad?
-    triad_type?(:major)
-  end
-
-  def minor_triad?
-    triad_type?(:minor)
-  end
-
-  def diminished_triad?
-    triad_type?(:diminished)
-  end
-
-  def augmented_triad?
-    triad_type?(:augmented)
-  end
-
-  def root_position_triad?
-    trichord? && reduction_diatonic_intervals.all?(&:third?)
-  end
-
-  def first_inversion_triad?
-    trichord? && reduction.uninvert.diatonic_intervals.all?(&:third?)
-  end
-
-  def second_inversion_triad?
-    trichord? && reduction.invert.diatonic_intervals.all?(&:third?)
-  end
-
-  def seventh_chord?
-    tetrachord? && tertian?
-  end
-
-  def root_position_seventh_chord?
-    tetrachord? && reduction_diatonic_intervals.all?(&:third?)
-  end
-
-  def first_inversion_seventh_chord?
-    tetrachord? && reduction.uninvert.diatonic_intervals.all?(&:third?)
-  end
-
-  def second_inversion_seventh_chord?
-    tetrachord? && reduction.uninvert.uninvert.diatonic_intervals.all?(&:third?)
-  end
-
-  def third_inversion_seventh_chord?
-    tetrachord? && reduction.invert.diatonic_intervals.all?(&:third?)
-  end
-
-  def ninth_chord?
-    pentachord? && tertian?
-  end
-
-  def eleventh_chord?
-    hexachord? && tertian?
-  end
-
-  def thirteenth_chord?
-    heptachord? && tertian?
-  end
-
-  def tertian?
-    return false unless diatonic_intervals.any?
-
-    inversion = reduction
-    pitches.length.times do
-      return true if TERTIAN_SONORITIES.value?(inversion.scale_degrees_above_bass_pitch)
-      inversion = inversion.invert
-    end
-    false
-  end
-
   def scale_degrees
     @scale_degrees ||= pitches.empty? ? [] : scale_degrees_above_bass_pitch.unshift(1)
   end
@@ -200,16 +113,29 @@ class HeadMusic::Analysis::PitchCollection
     @sonority ||= HeadMusic::Analysis::Sonority.new(self)
   end
 
+  def chord_analysis
+    @chord_analysis ||= HeadMusic::Analysis::ChordAnalysis.new(self)
+  end
+
   private
 
-  def triad_type?(type)
-    TRIAD_PATTERNS[type].include?(reduction_diatonic_intervals.map(&:shorthand))
+  def octave
+    @octave ||= HeadMusic::Analysis::DiatonicInterval.get("perfect octave")
+  end
+
+  def integer_notation_values
+    return [] if pitches.empty?
+
+    diatonic_intervals_above_bass_pitch.map { |interval| interval.semitones % 12 }.sort.unshift(0).uniq
   end
 
   def reduction_pitches
-    pitches.map do |pitch|
-      pitch = HeadMusic::Rudiment::Pitch.fetch_or_create(pitch.spelling, pitch.register - 1) while pitch > bass_pitch + 12
-      pitch
-    end.sort
+    pitches.map { |pitch| folded_into_reduction(pitch) }.sort
+  end
+
+  def folded_into_reduction(pitch)
+    ceiling = bass_pitch + 12
+    pitch = HeadMusic::Rudiment::Pitch.fetch_or_create(pitch.spelling, pitch.register - 1) while pitch > ceiling
+    pitch
   end
 end

data/lib/head_music/analysis/sonority.rb

@@ -73,6 +73,7 @@ class HeadMusic::Analysis::Sonority
   delegate :heptachord?, :octachord?, :nonachord?, :decachord?, :undecachord?, :dodecachord?, to: :pitch_collection
   delegate :pitch_class_set, :pitch_class_set_size, to: :pitch_collection
   delegate :scale_degrees_above_bass_pitch, to: :pitch_collection
+  delegate :triad?, :seventh_chord?, :tertian?, to: :pitch_collection
 
   def initialize(pitch_collection)
     @pitch_collection = pitch_collection
@@ -117,32 +118,13 @@ class HeadMusic::Analysis::Sonority
       root_position.diatonic_intervals_above_bass_pitch.all?(&:consonant?)
   end
 
-  def triad?
-    @triad ||= trichord? && tertian?
-  end
-
-  def seventh_chord?
-    @seventh_chord ||= tetrachord? && tertian?
-  end
-
-  def tertian?
-    @tertian ||= inversions.detect do |inversion|
-      inversion.diatonic_intervals.count(&:third?).to_f / inversion.diatonic_intervals.length > 0.5 ||
-        (scale_degrees_above_bass_pitch && [3, 5, 7]).length == 3
-    end
-  end
-
   def secundal?
-    @secundal ||= inversions.detect do |inversion|
-      inversion.diatonic_intervals.count(&:second?).to_f / inversion.diatonic_intervals.length > 0.5
-    end
+    @secundal ||= inversions.detect { |inversion| interval_ratio(inversion, &:second?) > 0.5 }
   end
 
   def quartal?
     @quartal ||= inversions.detect do |inversion|
-      inversion.diatonic_intervals.count do |interval|
-        interval.fourth? || interval.fifth?
-      end.to_f / inversion.diatonic_intervals.length > 0.5
+      interval_ratio(inversion) { |interval| interval.fourth? || interval.fifth? } > 0.5
     end
   end
   alias_method :quintal?, :quartal?
@@ -159,4 +141,12 @@ class HeadMusic::Analysis::Sonority
     other = self.class.new(other) if other.is_a?(HeadMusic::Analysis::PitchCollection)
     identifier == other.identifier
   end
+
+  private
+
+  # Fraction of an inversion's diatonic intervals that satisfy the given predicate.
+  def interval_ratio(inversion, &predicate)
+    intervals = inversion.diatonic_intervals
+    intervals.count(&predicate).to_f / intervals.length
+  end
 end

data/lib/head_music/content/composition/hash_deserializer.rb

@@ -0,0 +1,113 @@
+class HeadMusic::Content::Composition
+  # Rebuilds a composition from a schema v3 hash by replaying the public
+  # builder API in dependency order: meter and key changes first (position
+  # strings roll counts and ticks over via the meter map), then placements,
+  # then repeat flags (a pickup-bar flag needs its bar allocated), then
+  # comments. Raw values are validated at the boundary by SchemaValues so
+  # corrupted input raises ArgumentError with path context instead of
+  # silently deserializing wrong.
+  class HashDeserializer
+    def initialize(hash)
+      raise ArgumentError, "expected a Hash, got #{hash.class}" unless hash.is_a?(Hash)
+
+      @hash = hash.deep_transform_keys(&:to_s)
+      validate_schema_version
+    end
+
+    def composition
+      @composition ||= build_base_composition.tap do |composition|
+        apply_bar_changes(composition)
+        build_voices(composition)
+        apply_repeat_flags(composition)
+        add_comments(composition)
+      end
+    end
+
+    private
+
+    attr_reader :hash
+
+    def values
+      @values ||= SchemaValues.new
+    end
+
+    def validate_schema_version
+      version = hash["schema_version"]
+      return if version.is_a?(Integer) && version == SCHEMA_VERSION
+
+      message = "unsupported schema_version: #{version.inspect} (supported: #{SCHEMA_VERSION})"
+      if version == 2
+        message += "; migrate v2 \"pitches\" arrays to v3 \"sounds\" arrays " \
+          "(pitch strings unchanged; unpitched sounds are {\"unpitched\" => name_key} objects)"
+      end
+      raise ArgumentError, message
+    end
+
+    def build_base_composition
+      HeadMusic::Content::Composition.new(
+        name: hash["name"],
+        key_signature: values.key_signature(hash["key_signature"], "key_signature"),
+        meter: values.meter(hash["meter"], "meter"),
+        composer: hash["composer"],
+        origin: hash["origin"]
+      )
+    end
+
+    def bar_hashes
+      @bar_hashes ||= Array(hash["bars"])
+    end
+
+    def apply_bar_changes(composition)
+      bar_hashes.each_with_index do |bar_hash, index|
+        number = values.bar_number(bar_hash, index)
+        path = "bars[#{index}]"
+        key_signature = values.key_signature(bar_hash["key_signature"], path)
+        meter = values.meter(bar_hash["meter"], path)
+        composition.change_key_signature(number, key_signature) if key_signature
+        composition.change_meter(number, meter) if meter
+      end
+    end
+
+    def build_voices(composition)
+      Array(hash["voices"]).each_with_index do |voice_hash, voice_index|
+        voice = composition.add_voice(role: voice_hash["role"])
+        Array(voice_hash["placements"]).each_with_index do |placement_hash, placement_index|
+          path = "voices[#{voice_index}].placements[#{placement_index}]"
+          position = values.position(placement_hash["position"], path)
+          rhythmic_value = values.rhythmic_value(placement_hash["rhythmic_value"], path)
+          sounds = values.placement_sounds(placement_hash, path)
+          placement = voice.place(position, rhythmic_value, sounds)
+          placement.beam_break_before = placement_hash["beam_break_before"] if placement_hash.key?("beam_break_before")
+          values.placement_syllables(placement_hash, path).each do |syllable|
+            placement.sing(syllable.text, verse: syllable.verse, hyphen_after: syllable.hyphen_after)
+          end
+        end
+      end
+    end
+
+    def apply_repeat_flags(composition)
+      bar_hashes.each_with_index do |bar_hash, index|
+        next unless repeat_state?(bar_hash)
+
+        bar = composition.bars(values.bar_number(bar_hash, index)).last
+        bar.starts_repeat = true if bar_hash["starts_repeat"]
+        ends_repeat = bar_hash["ends_repeat_after_num_plays"]
+        bar.ends_repeat_after_num_plays = ends_repeat if ends_repeat
+        plays_on_passes = bar_hash["plays_on_passes"]
+        bar.plays_on_passes = plays_on_passes if plays_on_passes
+      end
+    end
+
+    def add_comments(composition)
+      Array(hash["comments"]).each_with_index do |comment_hash, index|
+        raw_position = comment_hash["position"]
+        position = values.position(raw_position, "comments[#{index}]") if raw_position
+        composition.add_comment(comment_hash["text"], position)
+      end
+    end
+
+    def repeat_state?(bar_hash)
+      bar_hash["starts_repeat"] || bar_hash["ends_repeat_after_num_plays"] || bar_hash["plays_on_passes"]
+    end
+  end
+end