head_music 12.4.0 → 12.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fc52f4684dac9eebefdc696f1d7f74094c98b26994905f7436cd757800880764
-  data.tar.gz: 3087c3c68254f16768f875538d54028db26498b8f7dfb8e543e7d402582a4581
+  metadata.gz: db91f6ff65b081bb369f3d2a85e2bc6e6cd092bb0018c2c416bf36bcfc4d4e9d
+  data.tar.gz: 266914dfbc382dc27591ea37302b57571b8693f2e0e4bd5189d2fffdff2a7c00
 SHA512:
-  metadata.gz: 6344e623f21eaad3c5c1dab093980062701d33ebca7f73050e211a7665afc2f81e49ef0de69e99f6a5c14d0d7797608cf35a88ca2c54c94590bbf404e575db9f
-  data.tar.gz: d28d37afdaae4bb89cbe3de6e1b9957fc5d19d3e54a03f1d9145092e7e7727545751365bad050b96a2f26a5b8f56972ebcbd99f9ad985c11a27e6e95636c174b
+  metadata.gz: d53ea28ee01b301ae1070a94fe8929d00b649c7d581976183d20e0bbfd080ccf4c08003719f2280001fb7d6ed00cfe1a5a634bd69b046d5859db56dfab6c6bb5
+  data.tar.gz: 9cd2929bddff0033d3caa84832e97a77a920cfc61e4e2d55d4d0be338f1ef7904beaad73748f6d6cc4ef93aea5a3b06292e16b285d0b61d5ad78b4ba2818932b

data/CHANGELOG.md

@@ -7,6 +7,116 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [12.6.0] - 2026-07-03
+
+### Added
+
+- `DiatonicMelody` guide: a free diatonic melody not bound to cantus firmus start/end constraints (note-count range configurable, defaulting to 5–24)
+- Configurable guidelines — a guideline can now carry configuration into a `RULESET` via `Annotation.with(...)` (wrapped in `Annotation::Configured`):
+  - `MinimumNotes` / `MaximumNotes` — configurable note-count floor and ceiling (`AtLeastEightNotes` / `UpToFourteenNotes` retained as named defaults)
+  - `NoteCountPerBar` — configurable `count` and `rhythmic_value` (unifies `OnePerBar`, `TwoPerBar`, `ThreePerBar`, `FourPerBar`)
+  - `DirectionChanges` — configurable `maximum_notes_per_direction` (unifies `ModerateDirectionChanges` and `FrequentDirectionChanges`)
+  - Configurable thresholds on `SingableRange`, `MostlyConjunct`, `LimitOctaveLeaps`, and `SecondSpeciesBreak`
+
+### Changed
+
+- Extracted `HeadMusic::Style::Guides::Base` for shared guide analysis behavior; `SpeciesMelody` and `SpeciesHarmony` now inherit from it
+- Hoisted the guidelines common to every guide into `MELODIC_CORE` / `HARMONIC_CORE` constants on the species base classes
+- `SingableRange`'s message now reflects the configured range
+- Renamed the `quality` rake task to `validate`
+
+## [12.5.0] - 2026-04-08
+
+### Changed
+
+- Improved fifth-species counterpoint guidelines
+- Code quality improvements
+
+### Removed
+
+- Combined 2+3+4 species guides and their guidelines
+
+## [12.4.0] - 2026-04-06
+
+### Added
+
+- Fifth-species (florid) counterpoint guides
+- Standard and alternate instrument tunings
+
+### Fixed
+
+- Ukulele family stringings, tunings, and range data
+
+## [12.3.0] - 2026-02-25
+
+### Added
+
+- Fourth-species counterpoint guides
+
+### Changed
+
+- Code quality pass
+
+## [12.2.0] - 2026-02-24
+
+### Changed
+
+- Improved guidelines for first-bar entry
+
+## [12.1.0] - 2026-02-24
+
+### Changed
+
+- Refactored species guidelines into separate first-bar, middle-bar, and final-bar rules
+- Unified `FinalBarWholeNote` and `FinalBarDottedHalfNote` into `NoteFillsFinalBar`
+
+## [12.0.1] - 2026-02-23
+
+### Changed
+
+- Renamed triple-meter guides
+
+## [12.0.0] - 2026-02-21
+
+### Added
+
+- Third-species 3:1 guidelines
+- Allow a descending minor sixth as a singable interval
+
+### Changed
+
+- Extracted shared base classes for guides and step-to-final-note guidelines
+- Refactored third-species dissonance handling and other files to reduce code smells
+
+## [11.8.0] - 2026-02-16
+
+### Added
+
+- `ThirdSpeciesMelody` and `ThirdSpeciesHarmony` guides
+- `ThirdSpeciesDissonanceTreatment` guideline
+- `FourToOne` guideline
+- Third-species counterpoint reference document
+
+## [11.7.0] - 2026-02-13
+
+### Added
+
+- Parallel-perfect check for first species
+
+### Changed
+
+- `Analysis#fitness` now uses the geometric mean
+
+## [11.6.1] - 2026-02-12
+
+### Added
+
+- Additional test coverage for the two-to-one guideline
+
+### Fixed
+
+- Accept an implied rest in the first bar of second-species counterpoint
+
 ## [11.6.0] - 2026-02-10
 
 ### Added

data/CLAUDE.md

@@ -26,8 +26,8 @@ bundle exec rspec spec/head_music/rudiments/pitch_spec.rb
 # Run linting
 bundle exec rubocop
 
-# Run all quality checks (tests, linting, security)
-bundle exec rake quality
+# Run all validation checks (tests, linting, security)
+bundle exec rake validate
 
 # Open interactive console with gem loaded
 bin/console
@@ -93,17 +93,33 @@ The codebase follows a domain-driven design with clear module boundaries:
 4. **HeadMusic::Content** - Musical composition representation
   - Compositions, voices, bars, positions
   - Notes in context (pitch + duration + placement)
-  - Temporal organization
-
-5. **HeadMusic::Analysis** - Musical analysis tools
-  - Intervals, chords, motion analysis
-  - Harmonic and melodic analysis
+  - Uses HeadMusic::Time for temporal positioning
+
+5. **HeadMusic::Time** - Temporal infrastructure
+  - Clock positions (elapsed nanoseconds as source of truth)
+  - Musical positions (bars:beats:ticks:subticks notation)
+  - SMPTE timecode (hours:minutes:seconds:frames for video/audio sync)
+  - Conductor: converts between clock time and musical position
+  - Tempo and meter maps for tracking changes over time
+
+6. **HeadMusic::Analysis** - Musical analysis tools
+  - Diatonic intervals (quality + size)
+  - Harmonic and melodic interval analysis
+  - Consonance classification
+  - Motion analysis (parallel, similar, contrary, oblique)
   - Pitch class sets and collections
+  - Sonority and dyad analysis
+  - Circle (of fifths) and interval cycles
 
-6. **HeadMusic::Style** - Composition rules and guidelines
-  - Counterpoint rules
+7. **HeadMusic::Style** - Composition rules and guidelines
+  - Counterpoint rules (species counterpoint guides)
   - Voice leading guidelines
-  - Style analysis
+  - Style analysis and annotations
+  - Historical traditions (medieval, renaissance, modern)
+
+8. **HeadMusic::Utilities** - Shared helpers
+  - Case conversion
+  - Hash key utilities
 
 ### Key Design Patterns
 
@@ -171,7 +187,7 @@ This project deliberately deprioritizes formal documentation in favor of clear,
 Domain reference materials live in `references/`.
 Consult these when implementing or modifying style guidelines:
 
-- `references/second-species-counterpoint.md` — Pedagogical survey of second-species counterpoint rules from Fux through contemporary sources, with cross-source comparison and mapping to head_music's style guideline architecture.
+Consult the files in `references/` when implementing or modifying style guidelines. These contain pedagogical surveys with cross-source comparisons mapped to head_music's style guideline architecture.
 
 ## Music theory and concepts
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    head_music (12.4.0)
+    head_music (12.6.0)
       activesupport (>= 7.0, < 10)
       humanize (~> 2.0)
       i18n (~> 1.8)
@@ -211,6 +211,7 @@ GEM
 PLATFORMS
   arm64-darwin-22
   arm64-darwin-23
+  arm64-darwin-25
   x86_64-linux
 
 DEPENDENCIES

data/MUSIC_THEORY.md

@@ -8,7 +8,7 @@ The rudiments of music theory are built up piece-by-piece.
 letter name
   - C, D, E, F, G, A, B, …
   - equivalent to:
-   - do, re, mi, fa, sol, la, si/ti, …
+    - do, re, mi, fa, sol, la, si/ti, …
 
 alteration
   - sharp, flat, double sharp, double flat
@@ -44,7 +44,7 @@ rhythmic value (duration)
   - augmentation dots extend the duration of the rhythmic unit
     - one dot extends the rhythmic value 50%
     - two dots extend the rhythmic value 75%
-    - two dots extend the rhythmic value 87.5%
+    - three dots extend the rhythmic value 87.5%
 
 rest
   - a rhythmic value that passes in silence
@@ -64,9 +64,9 @@ tied duration
 articulation
   - a category of expressions that modify how one or more notes are performed.
   - level of connection
-    - staccatissimo - the most staccato, even shorted and more clipped
-    - staccato – detatched (shortened to lease space between adjacent notes)
-    - tenuto - held of the full value
+    - staccatissimo - the most staccato, even shorter and more clipped
+    - staccato – detached (shortened to leave space between adjacent notes)
+    - tenuto - held for the full value
     - legato - smoothly connected
   - emphasis
     - accent - play with emphasis or a stronger attack
@@ -76,45 +76,108 @@ articulation
     - breath mark
     - roll mark
 
-## Instrument Families
+## Intervals
+
+interval
+  - the distance between two pitches
+  - described by quality + size
+  - size: unison, second, third, fourth, fifth, sixth, seventh, octave, etc.
+  - quality: perfect, major, minor, augmented, diminished
+  - perfect intervals: unison, fourth, fifth, octave
+  - major/minor intervals: second, third, sixth, seventh
+  - a chromatic interval measures distance in half steps (semitones)
+  - a diatonic interval considers the letter names and key context
+
+harmonic interval
+  - two pitches sounding simultaneously
+
+melodic interval
+  - two pitches sounding in succession
+  - ascending or descending
+
+## Consonance and Dissonance
+
+consonance
+  - intervals that sound stable and resolved
+  - perfect consonances: unison, perfect fifth, octave
+  - imperfect consonances: major/minor third, major/minor sixth
+
+dissonance
+  - intervals that sound tense and seek resolution
+  - seconds, sevenths, tritone (augmented fourth / diminished fifth)
+  - perfect fourth considered "dissonance" requiring resolution in traditional counterpoint
 
-There are several ways that people talk about families and other categorizations of instruments. For example, the "string family" or "woodwind family", but also more specifically, the word family is applied more specifically (e.g. the "oboe family").
+## Scales and Modes
 
-### Text Conversation with Brian Head (May 7, 2023)
+scale
+  - an ordered collection of pitches spanning an octave
+  - defined by a pattern of whole steps and half steps
+  - named by its tonic (starting pitch) and type
 
-Brian Head, brother and faculty at USC Thornton School of Music
-https://music.usc.edu/brian-head/
+major scale
+  - pattern: W-W-H-W-W-W-H (W = whole step, H = half step)
 
-Robert Head:
-	Hey, Brian. You have a sec for a music question? I’m trying to come up with different terms for the way “family” is used. “Woodwind family” vs. “Oboe family”.
+natural minor scale
+  - pattern: W-H-W-W-H-W-W
 
-Brian Head:
-	Those are good, I’d say.  In what context?
+modes
+  - scales derived by starting on different degrees of a parent scale
+  - Ionian (= major), Dorian, Phrygian, Lydian, Mixolydian, Aeolian (= natural minor), Locrian
 
-Robert Head:
-	In my software project, I’m trying to define those relationships. One is a section of the orchestra and the other is species of instrument. But usually people, in my experience, just say “family”.
-	Is there some more precise terminology or adjective that can disambiguate those two terms?
+## Keys and Key Signatures
 
-Brian Head:
-	Hmmm. Already “family” is informal. Blatter distinguishes between “choir” and “family” as in the  trumpet family” within the “brass choir”.
+key
+  - a tonal center (tonic) combined with a scale type (major or minor)
+  - example: "E-flat major", "A minor"
 
-Robert Head:
-	Ah, yes! I do like that.
-	But does it apply to percussion?
-	“Section” is another candidate, but that gets used for string parts as well.
+key signature
+  - the set of sharps or flats applied to a key
+  - written at the beginning of each staff line
+  - determines the default alteration for each letter name
 
-Brian Head:
-	Strings and percussion probably don’t think of themselves as a choir, but if you’re mainly looking for a taxonomically consistent word, that’s the feat I can think of at the moment.
-	Section is a good word, too, which easily flows between smaller and larger meanings.
+## Chords
 
-Robert Head:
-	Obviously, the four “families” is a garbage way to classify all instruments and it really is more applicable to the orchestral context, so maybe “orchestra family” or “orchestra section”.
+chord
+  - three or more pitches sounding together
+  - built by stacking intervals (typically thirds)
 
-Brian Head:
-	I’d say that “family” is best used at the instrument level, as in “saxophone family”. Choir or section are better for larger collections. Still, both of those words connote membership in an orchestra. Or large ensemble.  “Woodwinds” or “percussion” describe the class of instruments themselves.
+triad
+  - a three-note chord: root, third, fifth
+  - types: major, minor, diminished, augmented
 
-Robert Head:
-	Cool
+seventh chord
+  - a four-note chord: root, third, fifth, seventh
+  - types: major seventh, dominant seventh, minor seventh, half-diminished, diminished
+
+inversion
+  - a reordering of chord tones so that a note other than the root is the lowest
+  - root position, first inversion, second inversion (third inversion for seventh chords)
+
+## Voice Leading and Counterpoint
+
+voice leading
+  - the way individual melodic lines (voices) move from one chord to the next
+  - smooth voice leading minimizes the distance each voice moves
+
+types of motion between two voices
+  - parallel: both voices move in the same direction by the same interval
+  - similar: both voices move in the same direction by different intervals
+  - contrary: voices move in opposite directions
+  - oblique: one voice stays on the same pitch while the other moves
+
+counterpoint
+  - the art of combining independent melodic lines
+  - species counterpoint is a pedagogical method with five species of increasing complexity
+    - first species: note against note
+    - second species: two notes against one
+    - third species: four notes against one
+    - fourth species: suspensions — notes tied across the barline create dissonances that resolve by step
+    - fifth species: florid counterpoint, combining all species
+
+## Instrument Families
 
-Action Item: Call them orchestra_section
-DONE
+instrument family
+  - instruments grouped by shared characteristics
+  - broad families: strings, woodwinds, brass, percussion, keyboards, voices
+  - specific families: e.g. the oboe family (oboe, English horn, oboe d'amore)
+  - instruments within a family share similar tone production and playing technique

data/Rakefile

@@ -33,8 +33,8 @@ end
 
 task default: :spec
 
-desc "Run all quality checks (tests, linting, security audit, code quality)"
-task quality: [:spec, :standard, "bundle:audit:check", :rubycritic]
+desc "Run all validation checks (tests, linting, security audit, code quality)"
+task validate: [:spec, :standard, "bundle:audit:check", :rubycritic]
 
 desc "Open an irb session preloaded with this library"
 task :console do

data/lib/head_music/style/annotation.rb

@@ -23,8 +23,36 @@ class HeadMusic::Style::Annotation
   delegate :key_signature, to: :composition
   delegate :tonic_spelling, to: :key_signature
 
-  def initialize(voice)
+  def initialize(voice, **options)
     @voice = voice
+    @options = options
+  end
+
+  # Wraps a guideline class with preset options so it can live in a RULESET
+  # and still be instantiated with just a voice, e.g. MinimumNotes.with(minimum: 5).
+  def self.with(**options)
+    Configured.new(self, options)
+  end
+
+  # A RULESET entry pairing a guideline class with configuration. Quacks like a
+  # class to the analyze loop by responding to #new(voice).
+  class Configured
+    attr_reader :guideline_class, :options
+
+    def initialize(guideline_class, options)
+      @guideline_class = guideline_class
+      @options = options
+    end
+
+    def new(voice)
+      guideline_class.new(voice, **options)
+    end
+
+    def name
+      guideline_class.name
+    end
+    alias_method :to_s, :name
+    alias_method :inspect, :name
   end
 
   def fitness
@@ -61,6 +89,8 @@ class HeadMusic::Style::Annotation
 
   protected
 
+  attr_reader :options
+
   def voices
     @voices ||= voice.composition.voices
   end

data/lib/head_music/style/guidelines/allowed_rhythmic_values_for_fifth_species.rb

@@ -1,12 +1,107 @@
 # Module for style guidelines.
 module HeadMusic::Style::Guidelines; end
 
-# All rhythmic values are allowed in fifth species counterpoint.
-# This guideline is always adherent.
+# Validates that counterpoint notes use only permitted rhythmic values for fifth species.
+# Whole notes (final bar only), half notes, quarter notes, and paired stepwise eighth notes
+# on weak beats are allowed. No dotted rhythms.
 class HeadMusic::Style::Guidelines::AllowedRhythmicValuesForFifthSpecies < HeadMusic::Style::Annotation
-  MESSAGE = "All rhythmic values are allowed in fifth species."
+  MESSAGE = "Use only permitted rhythmic values: whole (final bar only), half, quarter, " \
+    "or paired stepwise eighth notes on weak beats."
+
+  PERMITTED_UNIT_NAMES = %w[whole half quarter eighth].freeze
 
   def marks
-    []
+    [
+      *disallowed_unit_marks,
+      *dotted_rhythm_marks,
+      *whole_note_not_in_final_bar_marks,
+      *unpaired_eighth_note_marks,
+      *non_stepwise_eighth_note_marks,
+      *excess_eighth_note_pair_marks
+    ]
+  end
+
+  private
+
+  def disallowed_unit_marks
+    mark_each(notes.reject { |note| PERMITTED_UNIT_NAMES.include?(note.rhythmic_value.unit_name) })
+  end
+
+  def dotted_rhythm_marks
+    mark_each(notes.select { |note| note.rhythmic_value.dots > 0 })
+  end
+
+  def whole_note_not_in_final_bar_marks
+    mark_each(
+      notes
+        .select { |note| note.rhythmic_value.unit_name == "whole" }
+        .reject { |note| note.position.bar_number == final_bar_number }
+    )
+  end
+
+  def unpaired_eighth_note_marks
+    mark_each(eighth_notes.reject { |note| paired_eighth?(note) })
+  end
+
+  def non_stepwise_eighth_note_marks
+    mark_each(
+      eighth_notes
+        .select { |note| paired_eighth?(note) }
+        .reject { |note| stepwise_eighth?(note) }
+    )
+  end
+
+  def excess_eighth_note_pair_marks
+    bars_with_excess_eighth_pairs.flat_map do |bar_number|
+      mark_each(eighth_notes_in_bar(bar_number)[2..])
+    end
+  end
+
+  def mark_each(violating_notes)
+    violating_notes.map { |note| HeadMusic::Style::Mark.for(note) }
+  end
+
+  def eighth_notes
+    @eighth_notes ||= notes.select { |note| note.rhythmic_value.unit_name == "eighth" }
+  end
+
+  def paired_eighth?(note)
+    prev = preceding_note(note)
+    foll = following_note(note)
+    (prev && prev.rhythmic_value.unit_name == "eighth") ||
+      (foll && foll.rhythmic_value.unit_name == "eighth")
+  end
+
+  def stepwise_eighth?(note)
+    prev = preceding_note(note)
+    foll = following_note(note)
+    stepwise_from_prev = prev && HeadMusic::Analysis::MelodicInterval.new(prev, note).step?
+    stepwise_to_foll = foll && HeadMusic::Analysis::MelodicInterval.new(note, foll).step?
+    stepwise_from_prev || stepwise_to_foll
+  end
+
+  def bars_with_excess_eighth_pairs
+    eighth_notes
+      .group_by { |note| note.position.bar_number }
+      .select { |_bar, bar_eighths| bar_eighths.length > 2 }
+      .keys
+  end
+
+  def eighth_notes_in_bar(bar_number)
+    eighth_notes.select { |note| note.position.bar_number == bar_number }
+  end
+
+  def final_bar_number
+    last_note&.position&.bar_number
+  end
+
+  def preceding_note(note)
+    index = notes.index(note)
+    notes[index - 1] if index && index > 0
+  end
+
+  def following_note(note)
+    index = notes.index(note)
+    notes[index + 1] if index && index < notes.length - 1
   end
 end

data/lib/head_music/style/guidelines/at_least_eight_notes.rb

@@ -1,29 +1,7 @@
 # Module for style guidelines.
 module HeadMusic::Style::Guidelines; end
 
-# A counterpoint guideline
-class HeadMusic::Style::Guidelines::AtLeastEightNotes < HeadMusic::Style::Annotation
+# A counterpoint guideline: the cantus firmus should have at least eight notes.
+class HeadMusic::Style::Guidelines::AtLeastEightNotes < HeadMusic::Style::Guidelines::MinimumNotes
   MINIMUM_NOTES = 8
-
-  MESSAGE = "Write at least eight notes."
-
-  def marks
-    placements.empty? ? no_placements_mark : deficiency_mark
-  end
-
-  private
-
-  def no_placements_mark
-    HeadMusic::Style::Mark.new(
-      HeadMusic::Content::Position.new(composition, "1:1"),
-      HeadMusic::Content::Position.new(composition, "2:1"),
-      fitness: 0
-    )
-  end
-
-  def deficiency_mark
-    return unless notes.length < MINIMUM_NOTES
-
-    HeadMusic::Style::Mark.for_all(placements, fitness: notes.length.to_f / MINIMUM_NOTES)
-  end
 end

data/lib/head_music/style/guidelines/consonant_downbeats.rb

@@ -1,9 +1,11 @@
 # Module for style guidelines.
 module HeadMusic::Style::Guidelines; end
 
-# A counterpoint guideline
+# A counterpoint guideline.
+# Dissonant downbeats are permitted only when the counterpoint note is a
+# properly tied-over suspension (i.e., it began before the current CF note).
 class HeadMusic::Style::Guidelines::ConsonantDownbeats < HeadMusic::Style::Annotation
-  MESSAGE = "Use consonant harmonic intervals on every downbeat."
+  MESSAGE = "Use consonant harmonic intervals on every downbeat (unless a tied suspension)."
 
   def marks
     dissonant_pairs.map do |dissonant_pair|
@@ -14,10 +16,21 @@ class HeadMusic::Style::Guidelines::ConsonantDownbeats < HeadMusic::Style::Annot
   private
 
   def dissonant_pairs
-    dissonant_intervals.map(&:notes).compact
+    non_suspension_dissonant_intervals.map(&:notes).compact
+  end
+
+  def non_suspension_dissonant_intervals
+    dissonant_intervals.reject { |interval| tied_suspension?(interval) }
   end
 
   def dissonant_intervals
     downbeat_harmonic_intervals.select { |interval| interval.dissonance?(:two_part_harmony) }
   end
+
+  def tied_suspension?(interval)
+    cp_note = voice.note_at(interval.position)
+    return false unless cp_note
+
+    cp_note.position < interval.position
+  end
 end

data/lib/head_music/style/guidelines/direction_changes.rb

@@ -1,8 +1,12 @@
 # Module for style guidelines.
 module HeadMusic::Style::Guidelines; end
 
-# A melodic line should have direction changes.
+# A melodic line should change direction often enough. Configurable via the
+# `maximum_notes_per_direction:` option; subclasses may set a
+# MAXIMUM_NOTES_PER_DIRECTION default and their own MESSAGE.
 class HeadMusic::Style::Guidelines::DirectionChanges < HeadMusic::Style::Annotation
+  MESSAGE = "Change melodic direction regularly."
+
   def marks
     return unless overage.positive?
 
@@ -15,7 +19,11 @@ class HeadMusic::Style::Guidelines::DirectionChanges < HeadMusic::Style::Annotat
   def overage
     return 0 if notes.length < 2
 
-    [notes_per_direction - self.class.maximum_notes_per_direction, 0].max
+    [notes_per_direction - maximum_notes_per_direction, 0].max
+  end
+
+  def maximum_notes_per_direction
+    options.fetch(:maximum_notes_per_direction) { self.class::MAXIMUM_NOTES_PER_DIRECTION }
   end
 
   def notes_per_direction