head_music 9.0.1 → 11.1.0

data/lib/head_music/analysis/pitch_class_set.rb

@@ -2,7 +2,7 @@
 module HeadMusic::Analysis; end
 
 # A PitchClassSet represents a pitch-class set or pitch collection.
-# See also: PitchSet, PitchClass
+# See also: PitchCollection, PitchClass
 class HeadMusic::Analysis::PitchClassSet
   attr_reader :pitch_classes
 
@@ -23,7 +23,7 @@ class HeadMusic::Analysis::PitchClassSet
   end
 
   def equivalent?(other)
-    pitch_classes.sort == other.pitch_classes.sort
+    pitch_classes == other.pitch_classes
   end
 
   def size
@@ -31,52 +31,149 @@ class HeadMusic::Analysis::PitchClassSet
   end
 
   def monochord?
-    pitch_classes.length == 1
+    size == 1
   end
   alias_method :monad?, :monochord?
 
   def dichord?
-    pitch_classes.length == 2
+    size == 2
   end
   alias_method :dyad?, :dichord?
 
   def trichord?
-    pitch_classes.length == 3
+    size == 3
   end
 
   def tetrachord?
-    pitch_classes.length == 4
+    size == 4
   end
 
   def pentachord?
-    pitch_classes.length == 5
+    size == 5
   end
 
   def hexachord?
-    pitch_classes.length == 6
+    size == 6
   end
 
   def heptachord?
-    pitch_classes.length == 7
+    size == 7
   end
 
   def octachord?
-    pitch_classes.length == 8
+    size == 8
   end
 
   def nonachord?
-    pitch_classes.length == 9
+    size == 9
   end
 
   def decachord?
-    pitch_classes.length == 10
+    size == 10
   end
 
   def undecachord?
-    pitch_classes.length == 11
+    size == 11
   end
 
   def dodecachord?
-    pitch_classes.length == 12
+    size == 12
+  end
+
+  # Returns the inversion of the pitch class set
+  # Inversion maps each pitch class to its inverse around 0
+  # For pitch class n, the inversion is (12 - n) mod 12
+  def inversion
+    @inversion ||=
+      self.class.new(
+        pitch_classes.map { |pc| (12 - pc.to_i) % 12 }
+      )
+  end
+
+  # Returns the normal form of the pitch class set
+  # The normal form is the most compact rotation of the set
+  # Algorithm:
+  # 1. Generate all rotations of the pitch class set
+  # 2. For each rotation, calculate the span (difference between first and last)
+  # 3. Choose the rotation with the smallest span
+  # 4. If there's a tie, choose the one with the smallest intervals from the left
+  def normal_form
+    return self if size <= 1
+
+    @rotations ||= generate_rotations
+    @most_compact_rotation ||= find_most_compact_rotation(@rotations)
+
+    self.class.new(@most_compact_rotation)
+  end
+
+  # Returns the prime form of the pitch class set
+  # The prime form is the most compact form among the normal form and its inversion
+  # Algorithm:
+  # 1. Find the normal form of the original set
+  # 2. Find the normal form of the inverted set
+  # 3. Compare and choose the most compact one
+  # 4. Transpose to start at 0
+  def prime_form
+    @prime_form ||= begin
+      # Handle edge cases
+      return self if size.zero?
+      return self.class.new([0]) if size == 1
+
+      normal = normal_form.pitch_classes
+      inverted_normal = inversion.normal_form.pitch_classes
+
+      # Compare which is more compact
+      chosen = compare_forms(normal, inverted_normal)
+
+      # Transpose to start at 0
+      transposed = transpose_to_zero(chosen)
+
+      self.class.new(transposed)
+    end
+  end
+
+  private
+
+  # Generate all rotations of the pitch class set
+  def generate_rotations
+    return [pitch_classes] if size <= 1
+
+    numbers = pitch_classes.map(&:to_i)
+    (0...size).map do |i|
+      rotation = numbers.rotate(i)
+      # Normalize each rotation to start from the first element
+      first = rotation.first
+      rotation.map { |n| (n - first) % 12 }
+    end
+  end
+
+  # Find the most compact rotation
+  # Returns the rotation with the smallest span
+  # In case of tie, prefer the one with smaller intervals from the left
+  def find_most_compact_rotation(rotations)
+    rotations.min_by do |rotation|
+      # Create a comparison key: [span, intervals from left]
+      [rotation.last] + rotation
+    end
+  end
+
+  # Compare two normal forms and return the more compact one
+  # If equal, return the first one
+  def compare_forms(form1, form2)
+    normalized1 = transpose_to_zero(form1).map(&:to_i)
+    normalized2 = transpose_to_zero(form2).map(&:to_i)
+
+    # Compare lexicographically element by element
+    comparison = normalized1 <=> normalized2
+    (comparison && comparison <= 0) ? form1 : form2
+  end
+
+  # Transpose a set of pitch classes to start at 0
+  def transpose_to_zero(pcs)
+    return pcs if pcs.empty?
+
+    numbers = pcs.map(&:to_i)
+    first = numbers.first
+    numbers.map { |n| HeadMusic::Rudiment::PitchClass.get((n - first) % 12) }
   end
 end

data/lib/head_music/analysis/{pitch_set.rb → pitch_collection.rb}

@@ -1,9 +1,11 @@
 # A module for musical analysis
 module HeadMusic::Analysis; end
 
-# A PitchSet is a collection of one or more pitches.
+# A PitchCollection is a collection of one or more pitches with specific registers.
+# In music theory, "pitch collection" refers to an ordered or unordered group of actual pitches,
+# as distinct from a "pitch-class set" which abstracts away register and octave equivalence.
 # See also: PitchClassSet
-class HeadMusic::Analysis::PitchSet
+class HeadMusic::Analysis::PitchCollection
   TERTIAN_SONORITIES = {
     implied_triad: [3],
     triad: [3, 5],
@@ -35,7 +37,7 @@ class HeadMusic::Analysis::PitchSet
   end
 
   def reduction
-    @reduction ||= HeadMusic::Analysis::PitchSet.new(reduction_pitches)
+    @reduction ||= HeadMusic::Analysis::PitchCollection.new(reduction_pitches)
   end
 
   def diatonic_intervals
@@ -67,13 +69,13 @@ class HeadMusic::Analysis::PitchSet
   def invert
     inverted_pitch = pitches[0] + HeadMusic::Analysis::DiatonicInterval.get("perfect octave")
     new_pitches = pitches.drop(1) + [inverted_pitch]
-    HeadMusic::Analysis::PitchSet.new(new_pitches)
+    HeadMusic::Analysis::PitchCollection.new(new_pitches)
   end
 
   def uninvert
     inverted_pitch = pitches[-1] - HeadMusic::Analysis::DiatonicInterval.get("perfect octave")
     new_pitches = [inverted_pitch] + pitches[0..-2]
-    HeadMusic::Analysis::PitchSet.new(new_pitches)
+    HeadMusic::Analysis::PitchCollection.new(new_pitches)
   end
 
   def bass_pitch
@@ -187,6 +189,10 @@ class HeadMusic::Analysis::PitchSet
     @scale_degrees_above_bass_pitch ||= diatonic_intervals_above_bass_pitch.map(&:simple_number).sort - [8]
   end
 
+  def sonority
+    @sonority ||= HeadMusic::Analysis::Sonority.new(self)
+  end
+
   private
 
   def reduction_pitches

data/lib/head_music/analysis/sonority.rb

@@ -27,17 +27,55 @@ class HeadMusic::Analysis::Sonority
     quartal_chord: %w[P4 m7]
   }.freeze
 
-  attr_reader :pitch_set
+  DEFAULT_ROOT = "C4"
+
+  # Factory method to get a sonority by identifier
+  # Returns a Sonority with pitches starting at the default root (C4)
+  #
+  # @param identifier [Symbol, String] the sonority identifier (e.g., :major_triad)
+  # @param root [String] the root pitch (default: "C4")
+  # @param inversion [Integer] the inversion number (default: 0 for root position)
+  # @return [Sonority, nil] the sonority object, or nil if identifier not found
+  def self.get(identifier, root: DEFAULT_ROOT, inversion: 0)
+    identifier = identifier.to_sym
+    return nil unless SONORITIES.key?(identifier)
+
+    root_pitch = HeadMusic::Rudiment::Pitch.get(root)
+    interval_shorthands = SONORITIES[identifier]
+
+    # Build pitches: root + intervals above root
+    pitches = [root_pitch] + interval_shorthands.map do |shorthand|
+      interval = HeadMusic::Analysis::DiatonicInterval.get(shorthand)
+      interval.above(root_pitch)
+    end
+
+    pitch_collection = HeadMusic::Analysis::PitchCollection.new(pitches)
+
+    # Apply inversions if requested
+    inversion.times do
+      pitch_collection = pitch_collection.invert
+    end
+
+    new(pitch_collection)
+  end
+
+  # Returns all available sonority identifiers
+  # @return [Array<Symbol>] array of sonority identifiers
+  def self.identifiers
+    SONORITIES.keys
+  end
+
+  attr_reader :pitch_collection
 
-  delegate :reduction, to: :pitch_set
-  delegate :empty?, :empty_set?, to: :pitch_set
-  delegate :monochord?, :monad, :dichord?, :dyad?, :trichord?, :tetrachord?, :pentachord?, :hexachord?, to: :pitch_set
-  delegate :heptachord?, :octachord?, :nonachord?, :decachord?, :undecachord?, :dodecachord?, to: :pitch_set
-  delegate :pitch_class_set, :pitch_class_set_size, to: :pitch_set
-  delegate :scale_degrees_above_bass_pitch, to: :pitch_set
+  delegate :reduction, to: :pitch_collection
+  delegate :empty?, :empty_set?, to: :pitch_collection
+  delegate :monochord?, :monad, :dichord?, :dyad?, :trichord?, :tetrachord?, :pentachord?, :hexachord?, to: :pitch_collection
+  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
 
-  def initialize(pitch_set)
-    @pitch_set = pitch_set
+  def initialize(pitch_collection)
+    @pitch_collection = pitch_collection
     identifier
   end
 
@@ -75,7 +113,7 @@ class HeadMusic::Analysis::Sonority
 
   def consonant?
     @consonant ||=
-      pitch_set.reduction_diatonic_intervals.all?(&:consonant?) &&
+      pitch_collection.reduction_diatonic_intervals.all?(&:consonant?) &&
       root_position.diatonic_intervals_above_bass_pitch.all?(&:consonant?)
   end
 
@@ -117,8 +155,8 @@ class HeadMusic::Analysis::Sonority
   end
 
   def ==(other)
-    other = HeadMusic::Analysis::PitchSet.new(other) if other.is_a?(Array)
-    other = self.class.new(other) if other.is_a?(HeadMusic::Analysis::PitchSet)
+    other = HeadMusic::Analysis::PitchCollection.new(other) if other.is_a?(Array)
+    other = self.class.new(other) if other.is_a?(HeadMusic::Analysis::PitchCollection)
     identifier == other.identifier
   end
 end

data/lib/head_music/content/cantus_firmus_examples.rb

@@ -0,0 +1,58 @@
+module HeadMusic
+  module Content
+    # Sample cantus firmus examples from various pedagogical sources.
+    # These are traditional melodies used for teaching counterpoint.
+    module CantusFirmusExamples
+      FUX = [
+        { source: "Fux", key: "D dorian", pitches: %w[D F E D G F A G F E D] },
+        { source: "Fux", key: "E phrygian", pitches: %w[E C D C A3 A G E F E] },
+        { source: "Fux", key: "F lydian", pitches: %w[F G A F D E F C5 A F G F] },
+        { source: "Fux", key: "G mixolydian", pitches: %w[G3 C B3 G3 C E D G E C D B3 A3 G3] },
+        { source: "Fux", key: "A aeolian", pitches: %w[A3 C B3 D C E F E D C B3 A3] },
+        { source: "Fux", key: "C ionian", pitches: %w[C E F G E A G E F E D C] },
+        { source: "Fux", key: "C ionian", pitches: %w[C E F E G F E D C] }
+      ].freeze
+
+      CLENDINNING = [
+        { source: "Clendinning", name: "CF in F major", key: "F major", pitches: %w[F3 G3 A3 F3 D3 E3 F3 C4 A3 F3 G3 F3] },
+        { source: "Clendinning", name: "CF in D minor", key: "D minor", pitches: %w[D3 A3 G3 F3 E3 D3 F3 E3 D3] },
+        { source: "Clendinning", name: "CF in C major (treble)", key: "C major", pitches: %w[C D F E F G A G E D C] },
+        { source: "Clendinning", name: "CF in C major (bass)", key: "C major", pitches: %w[C3 E3 F3 G3 E3 A3 G3 E3 F3 E3 D3 C3] }
+      ].freeze
+
+      DAVIS_AND_LYBBERT = [
+        { source: "Davis & Lybbert", name: "CF 1 in C major", key: "C major", pitches: %w[C3 E3 D3 G3 A3 G3 E3 F3 D3 C3] },
+        { source: "Davis & Lybbert", name: "CF 2 in C major", key: "C major", pitches: %w[C3 D3 E3 G3 A3 F3 E3 D3 C3] },
+        { source: "Davis & Lybbert", name: "CF 3 in G major", key: "G major", pitches: %w[G3 F#3 G3 E3 D3 B2 C3 D3 B2 A2 G2] },
+        { source: "Davis & Lybbert", name: "CF 4 in G major", key: "G major", pitches: %w[G2 B2 C3 D3 E3 D3 B2 C3 A2 G2] },
+        { source: "Davis & Lybbert", name: "CF 5 in F major", key: "F major", pitches: %w[F3 D3 C3 F3 G3 A3 E3 D3 G3 F3] },
+        { source: "Davis & Lybbert", name: "CF 6 in A minor", key: "A minor", pitches: %w[A2 E3 C3 D3 B2 G2 A2 C3 B2 A2] },
+        { source: "Davis & Lybbert", name: "CF 7 in A minor", key: "A minor", pitches: %w[A2 B2 C3 D3 E3 F3 E3 C3 B2 A2] },
+        { source: "Davis & Lybbert", name: "CF 8 in E minor", key: "E minor", pitches: %w[E3 A3 B3 G3 C4 A3 B3 G3 F#3 E3] },
+        { source: "Davis & Lybbert", name: "CF 9 in E minor", key: "E minor", pitches: %w[E3 D3 C3 B2 G2 A2 B2 E3 G3 F#3 E3] },
+        { source: "Davis & Lybbert", name: "CF 10 in D minor", key: "D minor", pitches: %w[D3 F3 E3 G3 F3 D3 A3 G3 F3 E3 D3] }
+      ].freeze
+
+      SCHOENBERG = [
+        { source: "Schoenberg", key: "Eb major", pitches: %w[Eb D G3 Ab3 C Ab3 F3 Eb3] },
+        { source: "Schoenberg", key: "A major", pitches: %w[A3 C#4 B3 F#3 A3 F#3 G#3 A3] }
+      ].freeze
+
+      EXAMPLES = (FUX + CLENDINNING + DAVIS_AND_LYBBERT + SCHOENBERG).freeze
+
+      class << self
+        def all
+          EXAMPLES
+        end
+
+        def by_source(source)
+          EXAMPLES.select { |ex| ex[:source] == source }
+        end
+
+        def sources
+          EXAMPLES.map { |ex| ex[:source] }.uniq
+        end
+      end
+    end
+  end
+end

data/lib/head_music/content/staff.rb

@@ -8,7 +8,7 @@ class HeadMusic::Content::Staff
   attr_reader :default_clef, :line_count, :instrument
 
   def initialize(default_clef_key, instrument: nil, line_count: nil)
-    @instrument = HeadMusic::Instruments::InstrumentType.get(instrument) if instrument
+    @instrument = HeadMusic::Instruments::Instrument.get(instrument) if instrument
     begin
       @default_clef = HeadMusic::Rudiment::Clef.get(default_clef_key)
     rescue KeyError, NoMethodError

data/lib/head_music/content/voice.rb

@@ -170,7 +170,7 @@ class HeadMusic::Content::Voice
       combined_pitches = (pitches + other_note_pair.pitches).uniq
       return false if combined_pitches.length < 3
 
-      HeadMusic::Analysis::PitchSet.new(combined_pitches).consonant_triad?
+      HeadMusic::Analysis::PitchCollection.new(combined_pitches).consonant_triad?
     end
   end
 end

data/lib/head_music/instruments/alternate_tuning.rb

@@ -0,0 +1,102 @@
+module HeadMusic::Instruments; end
+
+# An alternate tuning for a stringed instrument.
+#
+# Tunings are defined as semitone adjustments from the standard tuning.
+# For example, "Drop D" tuning lowers the low E string by 2 semitones.
+#
+# Examples:
+#   drop_d = HeadMusic::Instruments::AlternateTuning.get("guitar", "drop_d")
+#   drop_d.semitones  # => [-2, 0, 0, 0, 0, 0]
+#
+# When applying a tuning:
+#   - First element applies to the lowest course
+#   - Missing elements are treated as 0 (no change)
+#   - Extra elements are ignored
+class HeadMusic::Instruments::AlternateTuning
+  TUNINGS = YAML.load_file(File.expand_path("alternate_tunings.yml", __dir__)).freeze
+
+  attr_reader :instrument_key, :name_key, :semitones
+
+  class << self
+    # Get an alternate tuning by instrument and name
+    # @param instrument [HeadMusic::Instruments::Instrument, String, Symbol] The instrument
+    # @param name [String, Symbol] The tuning name (e.g., "drop_d")
+    # @return [AlternateTuning, nil]
+    def get(instrument, name)
+      instrument_key = normalize_instrument_key(instrument)
+      name_key = name.to_s
+
+      data = TUNINGS.dig(instrument_key, name_key)
+      return nil unless data
+
+      new(
+        instrument_key: instrument_key,
+        name_key: name_key,
+        semitones: data["semitones"] || []
+      )
+    end
+
+    # Get all alternate tunings for an instrument
+    # @param instrument [HeadMusic::Instruments::Instrument, String, Symbol] The instrument
+    # @return [Array<AlternateTuning>]
+    def for_instrument(instrument)
+      instrument_key = normalize_instrument_key(instrument)
+      return [] unless TUNINGS.key?(instrument_key)
+
+      TUNINGS[instrument_key].map do |name_key, data|
+        new(
+          instrument_key: instrument_key,
+          name_key: name_key,
+          semitones: data["semitones"] || []
+        )
+      end
+    end
+
+    private
+
+    def normalize_instrument_key(instrument)
+      case instrument
+      when HeadMusic::Instruments::Instrument
+        instrument.name_key.to_s
+      else
+        instrument.to_s
+      end
+    end
+  end
+
+  def initialize(instrument_key:, name_key:, semitones:)
+    @instrument_key = instrument_key.to_sym
+    @name_key = name_key.to_sym
+    @semitones = Array(semitones)
+  end
+
+  # The instrument this tuning applies to
+  # @return [HeadMusic::Instruments::Instrument]
+  def instrument
+    HeadMusic::Instruments::Instrument.get(instrument_key)
+  end
+
+  # Human-readable name for the tuning
+  # @return [String]
+  def name
+    name_key.to_s.tr("_", " ").split.map(&:capitalize).join(" ")
+  end
+
+  # Apply this tuning to a stringing's standard pitches
+  # @param stringing [Stringing] The stringing to apply to
+  # @return [Array<HeadMusic::Rudiment::Pitch>]
+  def apply_to(stringing)
+    stringing.pitches_with_tuning(self)
+  end
+
+  def ==(other)
+    return false unless other.is_a?(self.class)
+
+    instrument_key == other.instrument_key && name_key == other.name_key
+  end
+
+  def to_s
+    "#{name} (#{instrument_key})"
+  end
+end

data/lib/head_music/instruments/alternate_tunings.yml

@@ -0,0 +1,78 @@
+# Alternate tunings for stringed instruments.
+#
+# Each tuning is defined as semitone adjustments from standard tuning.
+# - First element = lowest course
+# - Missing elements = 0 (no change)
+# - Extra elements = ignored
+
+guitar:
+  drop_d:
+    semitones: [-2, 0, 0, 0, 0, 0]
+  double_drop_d:
+    semitones: [-2, 0, 0, 0, 0, -2]
+  dadgad:
+    semitones: [-2, 0, 0, 0, -2, -2]
+  open_d:
+    semitones: [-2, 0, 0, -1, -2, -2]
+  open_g:
+    semitones: [-2, -2, 0, 0, 0, -2]
+  open_e:
+    semitones: [0, 2, 2, 1, 0, 0]
+  open_a:
+    semitones: [0, 0, 2, 2, 2, 0]
+  open_c:
+    semitones: [-4, -2, 0, 0, 1, 0]
+  half_step_down:
+    semitones: [-1, -1, -1, -1, -1, -1]
+  whole_step_down:
+    semitones: [-2, -2, -2, -2, -2, -2]
+  drop_c:
+    semitones: [-4, -2, -2, -2, -2, -2]
+  nashville:
+    semitones: [12, 12, 12, 12, 0, 0]
+
+bass_guitar:
+  drop_d:
+    semitones: [-2, 0, 0, 0]
+  half_step_down:
+    semitones: [-1, -1, -1, -1]
+  whole_step_down:
+    semitones: [-2, -2, -2, -2]
+  drop_c:
+    semitones: [-4, -2, -2, -2]
+
+five_string_bass:
+  standard:
+    semitones: [0, 0, 0, 0, 0]
+  drop_a:
+    semitones: [-2, 0, 0, 0, 0]
+
+banjo:
+  open_g:
+    semitones: [0, 0, 0, 0, 0]
+  double_c:
+    semitones: [-2, -2, 0, -2, 0]
+  sawmill:
+    semitones: [-2, -2, 0, 0, -2]
+  open_d:
+    semitones: [-5, -2, -2, -1, -2]
+
+ukulele:
+  low_g:
+    semitones: [-12, 0, 0, 0]
+  baritone:
+    semitones: [-5, -5, -5, -5]
+  slack_key:
+    semitones: [0, 0, -1, 0]
+
+violin:
+  solo_tuning:
+    semitones: [1, 1, 1, 1]
+  cross_tuning:
+    semitones: [0, 0, -2, 0]
+
+cello:
+  solo_tuning:
+    semitones: [1, 1, 1, 1]
+  drop_c:
+    semitones: [-2, 0, 0, 0]