head_music 8.2.1 → 9.0.1

data/user_stories/done/instrument-variant.md

@@ -0,0 +1,65 @@
+## Instrument Variant Refactoring
+
+### Background
+The current architecture conflates instrument catalog data with specific instrument instances. We need to separate these concerns to better represent how instruments are actually used in musical scores.
+
+### Hierarchy
+The refactored hierarchy will provide three levels of abstraction:
+- **InstrumentFamily** (existing): Broad category like "saxophone" or "trumpet"
+- **InstrumentType** (renamed from Instrument): Catalog entry with all possible variants (e.g., "trumpet" which can be in Bb, C, D, Eb)
+- **Instrument** (new): Specific instance with selected variant (e.g., "Trumpet in C")
+
+### User Stories
+
+**STORY 1: Rename Instrument to InstrumentType**
+AS a developer
+WHEN I want to access instrument catalog data
+I WANT to use InstrumentType.get("trumpet")
+SO THAT it's clear I'm getting a type definition, not a specific instrument instance
+
+**STORY 2: Create new Instrument class for specific variants**
+AS a developer
+WHEN I need a specific instrument for a score
+I WANT to call Instrument.get("trumpet_in_c") or Instrument.get("trumpet", "in_c")
+SO THAT I get a specific, usable instrument instance with proper transposition
+
+**STORY 3: Instrument instances are sortable**
+AS a developer
+WHEN I have multiple Instrument instances in a score
+I WANT them to sort properly by orchestral order and transposition
+SO THAT "Trumpet in Eb" appears before "Trumpet in C" in the score
+
+**STORY 4: Clear API for common use cases**
+AS a developer
+WHEN I create an Instrument without specifying a variant
+I WANT to get the default variant automatically
+SO THAT Instrument.get("clarinet") returns a Bb clarinet (the default)
+
+**STORY 5: Instrument provides unified interface**
+AS a developer
+WHEN I have an Instrument instance
+I WANT to access properties like name, transposition, clefs, and pitch_designation
+SO THAT I don't need to navigate between instrument type and variant objects
+
+### Implementation Notes
+
+1. The Instrument class should:
+   - Wrap both an InstrumentType and a specific Variant
+   - Generate appropriate display names (e.g., "Clarinet in A")
+   - Provide methods for transposition, clefs, staff schemes
+   - Be directly usable in scores and parts
+
+2. Factory methods should support:
+   - `Instrument.get("trumpet_in_c")` - parse variant from name
+   - `Instrument.get("trumpet", "in_c")` - explicit variant
+   - `Instrument.get("trumpet")` - use default variant
+
+3. ScoreOrder should work with Instrument instances directly
+
+### Migration Path
+
+1. Rename existing Instrument class to InstrumentType
+2. Update all references to use InstrumentType where appropriate
+3. Create new Instrument class for variant instances
+4. Update ScoreOrder to work with new Instrument instances
+5. Update documentation and tests

data/user_stories/done/superclass-for-note.md

@@ -0,0 +1,30 @@
+IN ORDER TO accurately model sound events
+AS a developer
+I WANT a clear way to group the notion of a Note (pitch + rhythmic value) and an unpitched note.
+
+We need a hierarchy of classes
+
+class RhythmicEvent
+  attr_accessor :rhythmic_value
+
+class Note < RhythmicEvent
+  attr_accessor :pitch
+  def sounded?
+    true
+  end
+
+class UnpitchedNote < RhythmicEvent
+  def sounded?
+    true
+  end
+
+class Rest < RhythmicEvent
+  def sounded?
+    false
+  end
+
+
+acceptance criteria
+- the above class hierarchy and implementation requirements
+- full test coverage
+- use NotImplementedError instead of NotImplementedError in RhythmicEvent if and where appropriate.

data/user_stories/todo/agentic-daw.md

@@ -0,0 +1,3 @@
+
+agent-centric multimedia scoring
+(A/V DAW)

data/user_stories/todo/consonance-dissonance-classification.md

@@ -0,0 +1,57 @@
+# Consonance and Dissonance Classification
+
+As a music theorist or counterpoint student
+
+I want to classify intervals by their consonance and dissonance levels
+
+So that I can apply proper voice leading rules
+
+## Scenario: Classify open consonances
+
+Given I have a perfect fifth or perfect octave
+
+When I check the consonance classification
+
+Then it should be identified as "open consonance"
+
+## Scenario: Classify soft consonances
+
+Given I have a third or sixth interval (major or minor)
+
+When I check the consonance classification
+
+Then it should be identified as "soft consonance"
+
+## Scenario: Classify mild dissonances
+
+Given I have a major second or minor seventh
+
+When I check the consonance classification
+
+Then it should be identified as "mild dissonance"
+
+## Scenario: Classify sharp dissonances
+
+Given I have a minor second or major seventh
+
+When I check the consonance classification
+
+Then it should be identified as "sharp dissonance"
+
+## Scenario: Handle perfect fourth context
+
+Given I have a perfect fourth interval
+
+When I check the consonance classification
+
+Then it should indicate context-dependent classification
+
+And note it can be either consonant or dissonant
+
+## Scenario: Classify tritone
+
+Given I have a tritone interval
+
+When I check the consonance classification
+
+Then it should be identified as "neutral" or "restless"

data/user_stories/todo/dyad-analysis.md

@@ -0,0 +1,57 @@
+# Dyad Analysis
+
+As a music analyst or counterpoint student
+
+I want to analyze two-note combinations (dyads)
+
+So that I can understand harmonic implications in two-part music
+
+Constructor should accept to pitches (or pitch classes) and an optional key
+
+## Scenario: Identify interval in dyad
+
+Given I have two pitches forming a dyad
+
+When I access the interval property
+
+Then I should receive the correct interval between the pitches
+
+## Scenario: List possible triads from fifth
+
+Given I have a dyad forming a perfect fifth
+
+When I request possible triads
+
+Then I should receive both major and minor triad options
+
+And each should contain the given pitches
+
+## Scenario: List possible triads from third
+
+Given I have a dyad forming a minor third
+
+When I request possible triads
+
+Then I should receive minor and diminished triad options
+
+And for a major third I should receive major and augmented options
+
+## Scenario: Find possible seventh chords
+
+Given I have a dyad
+
+When I request possible seventh chords
+
+Then I should receive all seventh chords containing those pitches
+
+And they should include appropriate inversions
+
+## Scenario: Handle enharmonic possibilities
+
+Given I have a dyad with enharmonic possibilities
+
+When I request possible enharmonic chords
+
+Then I should receive chords based on enharmonic respellings
+
+And each should be correctly identified

data/user_stories/todo/material-and-scores.md

@@ -0,0 +1,10 @@
+
+
+
+Material
+
+Fragment < Material
+
+Score < Material
+- name
+-

data/user_stories/todo/organizing-content.md

@@ -0,0 +1,72 @@
+
+Project = overall container.
+Flow = segment-level unit (supports sketches, movements, cues).
+Sequence = neutral term for the editing canvas (2D space).
+Timeline = strictly the axis.
+
+
+Material?
+
+ScorePart
+@name
+>> instruments
+def primary_instrument
+def default_staff_system
+
+
+MusicContent
+>> score_parts
+@score_type (orchestral, band, chamber, pop, solo)
+def ordered_score_parts
+def score_parts_grouped_by_orchestra_section
+  # so we can square-bracket the sections
+
+
+
+Score < MusicContent
+@title
+@subtitle
+@dedication
+>> score_credits
+
+
+ScoreCredit
+> person
+- role (composer, songwriter, lyricist, arranger, transcriber)
+
+
+Person
+- full_name
+- birth_year int optional
+- death_year int optional
+
+
+ScoreLayout < Layout
+
+
+
+EnsembleSession (rehearsal, recording, or performance)
+>> scores
+>> score_part_players
+
+
+ScorePartPlayer
+> score_part
+>> players
+
+
+
+
+Player
+> person
+
+
+
+Fragment < MusicContent
+
+
+
+
+
+
+

data/user_stories/todo/percussion_set.md

@@ -0,0 +1 @@
+Create a PercussionSet staff for percussion or drum kit parts in a score.

data/user_stories/todo/pitch-class-set-analysis.md

@@ -0,0 +1,79 @@
+# Pitch Class Set Analysis
+
+As a music theorist studying atonal music
+
+I want to analyze pitch class sets
+
+So that I can identify set relationships and transformations
+
+## Scenario: Get size of pitch class set
+
+Given I have a pitch class set
+
+When I call the size method
+
+Then it should return the number of unique pitch classes
+
+## Scenario: Check if monad
+
+Given I have a pitch class set with one pitch class
+
+When I call monad?
+
+Then it should return true
+
+## Scenario: Check if dyad
+
+Given I have a pitch class set with two pitch classes
+
+When I call dyad?
+
+Then it should return true
+
+## Scenario: Check if triad
+
+Given I have a pitch class set with three pitch classes
+
+When I call triad?
+
+Then it should return true only if they form stacked thirds
+
+## Scenario: Check if trichord
+
+Given I have a pitch class set with three pitch classes
+
+When I call trichord?
+
+Then it should return true for any 3-pitch class set
+
+## Scenario: Find normal form
+
+Given I have a pitch class set
+
+When I request the normal form
+
+Then I should receive the most compact rotation
+
+And it should minimize the interval span
+
+## Scenario: Find prime form
+
+Given I have a pitch class set
+
+When I request the prime form
+
+Then I should receive the most compact form
+
+And it should consider both the original and all inversions
+
+And it should be the optimal normal form among all possibilities
+
+## Scenario: Compare equivalent sets
+
+Given I have two different pitch class sets
+
+When I compare their prime forms
+
+Then I can determine if they are equivalent
+
+And identify the transformation relationship between them

data/user_stories/todo/pitch-set-classification.md

@@ -0,0 +1,72 @@
+# Pitch Set Classification
+
+As a music theorist
+
+I want to classify pitch sets by their size and properties
+
+So that I can analyze and categorize harmonic structures
+
+Note: A PitchSet is unlike a PitchClassSet in that the pitches have spellings with octaves rather than Spellings only or octave-less 0-11 designations.
+
+## Scenario: Get size of pitch set
+
+Given I have a pitch set with N pitches
+
+When I call the size method
+
+Then it should return the number of pitches in the set
+
+## Scenario: Identify empty set
+
+Given I have no pitches
+
+When I create a pitch set
+
+Then it should be identified as an EmptySet
+
+## Scenario: Identify monad
+
+Given I have a single pitch
+
+When I check the pitch set type
+
+Then it should be identified as a Monad
+
+And monad? should return true
+
+## Scenario: Identify dyad
+
+Given I have exactly two pitches
+
+When I check the pitch set type
+
+Then it should be identified as a Dyad
+
+And dyad? should return true
+
+## Scenario: Distinguish triads from trichords
+
+Given I have three pitches
+
+When I analyze the pitch set
+
+Then trichord? should return true for any 3-pitch set
+
+And triad? should return true only if they form stacked thirds
+
+## Scenario: Identify larger pitch sets
+
+Given I have a pitch set with N pitches
+
+When I check the classification
+
+Then it should be identified as:
+  - Tetrachord (4 pitches) with seventh_chord? check
+  - Pentachord (5 pitches)
+  - Hexachord (6 pitches)
+  - Heptachord (7 pitches)
+  - Octachord (8 pitches)
+  - Nonachord (9 pitches)
+  - Decachord (10 pitches)
+  - Undecachord (11 pitches)
+  - Dodecachord (12 pitches)

data/user_stories/todo/sonority-identification.md

@@ -0,0 +1,67 @@
+# Sonority Identification
+
+As a music theorist or composer
+
+I want to identify and work with named sonorities
+
+So that I can analyze and create harmonic structures
+
+## Scenario: Get sonority by identifier
+
+Given I need a specific sonority
+
+When I call Sonority.get with an identifier like "major triad"
+
+Then I should receive the corresponding sonority object
+
+And it should contain the correct interval structure
+
+## Scenario: Identify sonority from pitch set
+
+Given I have a set of pitches
+
+When I call Sonority.for with the pitch set
+
+Then I should receive the identified sonority
+
+And it should correctly name the harmonic structure
+
+## Scenario: Generate pitch set from sonority
+
+Given I have a sonority and a root pitch
+
+When I call Sonority.pitch_set_for with root pitch and inversion
+
+Then I should receive the correct pitches
+
+And they should be in the specified inversion
+
+## Scenario: Access sonority from pitch set
+
+Given I have a PitchSet object
+
+When I call the sonority method
+
+Then I should receive the corresponding Sonority object
+
+And it should correctly identify the harmonic content
+
+## Scenario: Work with triads
+
+Given I need to analyze triadic harmony
+
+When I work with Triad objects
+
+Then I should be able to identify major, minor, diminished, and augmented triads
+
+And access their specific properties and methods
+
+## Scenario: Work with seventh chords
+
+Given I need to analyze seventh chord harmony
+
+When I work with SeventhChord objects
+
+Then I should be able to identify all common seventh chord types
+
+And note that nothing beyond seventh chords is needed to analyze pre-Romantic music

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: head_music
 version: !ruby/object:Gem::Version
-  version: 8.2.1
+  version: 9.0.1
 platform: ruby
 authors:
 - Rob Head
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-06-21 00:00:00.000000000 Z
+date: 2025-10-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -86,14 +86,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.2'
+        version: '2.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.2'
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: bundler-audit
   requirement: !ruby/object:Gem::Requirement
@@ -144,16 +144,19 @@ files:
 - ".ruby-version"
 - ".yardopts"
 - CHANGELOG.md
+- CLAUDE.md
 - CODE_OF_CONDUCT.md
 - CONTRIBUTING.md
 - Gemfile
 - Gemfile.lock
 - LICENSE.txt
+- MUSIC_THEORY.md
 - README.md
 - Rakefile
-- TODO.md
+- bin/check_instrument_consistency.rb
 - bin/console
 - bin/setup
+- check_instrument_consistency.rb
 - head_music.gemspec
 - lib/head_music.rb
 - lib/head_music/analysis/circle.rb
@@ -164,6 +167,7 @@ files:
 - lib/head_music/analysis/diatonic_interval/semitones.rb
 - lib/head_music/analysis/diatonic_interval/size.rb
 - lib/head_music/analysis/harmonic_interval.rb
+- lib/head_music/analysis/interval_consonance.rb
 - lib/head_music/analysis/interval_cycle.rb
 - lib/head_music/analysis/melodic_interval.rb
 - lib/head_music/analysis/motion.rb
@@ -175,13 +179,15 @@ files:
 - lib/head_music/content/note.rb
 - lib/head_music/content/placement.rb
 - lib/head_music/content/position.rb
-- lib/head_music/content/rhythmic_value.rb
 - lib/head_music/content/staff.rb
 - lib/head_music/content/voice.rb
 - lib/head_music/instruments/instrument.rb
 - lib/head_music/instruments/instrument_families.yml
 - lib/head_music/instruments/instrument_family.rb
+- lib/head_music/instruments/instrument_type.rb
 - lib/head_music/instruments/instruments.yml
+- lib/head_music/instruments/score_order.rb
+- lib/head_music/instruments/score_orders.yml
 - lib/head_music/instruments/staff.rb
 - lib/head_music/instruments/staff_scheme.rb
 - lib/head_music/instruments/variant.rb
@@ -194,31 +200,49 @@ files:
 - lib/head_music/locales/ru.yml
 - lib/head_music/named.rb
 - lib/head_music/rudiment/alteration.rb
+- lib/head_music/rudiment/base.rb
 - lib/head_music/rudiment/chromatic_interval.rb
 - lib/head_music/rudiment/clef.rb
 - lib/head_music/rudiment/clefs.yml
 - lib/head_music/rudiment/consonance.rb
+- lib/head_music/rudiment/diatonic_context.rb
+- lib/head_music/rudiment/key.rb
 - lib/head_music/rudiment/key_signature.rb
 - lib/head_music/rudiment/key_signature/enharmonic_equivalence.rb
 - lib/head_music/rudiment/letter_name.rb
 - lib/head_music/rudiment/meter.rb
+- lib/head_music/rudiment/mode.rb
 - lib/head_music/rudiment/musical_symbol.rb
+- lib/head_music/rudiment/note.rb
 - lib/head_music/rudiment/pitch.rb
 - lib/head_music/rudiment/pitch/enharmonic_equivalence.rb
 - lib/head_music/rudiment/pitch/octave_equivalence.rb
+- lib/head_music/rudiment/pitch/parser.rb
 - lib/head_music/rudiment/pitch_class.rb
 - lib/head_music/rudiment/quality.rb
 - lib/head_music/rudiment/reference_pitch.rb
 - lib/head_music/rudiment/register.rb
+- lib/head_music/rudiment/rest.rb
 - lib/head_music/rudiment/rhythm.rb
+- lib/head_music/rudiment/rhythmic_element.rb
 - lib/head_music/rudiment/rhythmic_unit.rb
+- lib/head_music/rudiment/rhythmic_unit/parser.rb
+- lib/head_music/rudiment/rhythmic_units.yml
+- lib/head_music/rudiment/rhythmic_value.rb
+- lib/head_music/rudiment/rhythmic_value/parser.rb
 - lib/head_music/rudiment/scale.rb
 - lib/head_music/rudiment/scale_degree.rb
 - lib/head_music/rudiment/scale_type.rb
 - lib/head_music/rudiment/solmization.rb
 - lib/head_music/rudiment/solmizations.yml
 - lib/head_music/rudiment/spelling.rb
+- lib/head_music/rudiment/tempo.rb
+- lib/head_music/rudiment/tonal_context.rb
 - lib/head_music/rudiment/tuning.rb
+- lib/head_music/rudiment/tuning/just_intonation.rb
+- lib/head_music/rudiment/tuning/meantone.rb
+- lib/head_music/rudiment/tuning/pythagorean.rb
+- lib/head_music/rudiment/unpitched_note.rb
 - lib/head_music/style/analysis.rb
 - lib/head_music/style/annotation.rb
 - lib/head_music/style/guidelines/always_move.rb
@@ -259,9 +283,30 @@ files:
 - lib/head_music/style/guides/fux_cantus_firmus.rb
 - lib/head_music/style/guides/modern_cantus_firmus.rb
 - lib/head_music/style/mark.rb
+- lib/head_music/style/medieval_tradition.rb
+- lib/head_music/style/modern_tradition.rb
+- lib/head_music/style/renaissance_tradition.rb
+- lib/head_music/style/tradition.rb
 - lib/head_music/utilities/hash_key.rb
 - lib/head_music/version.rb
 - test_translations.rb
+- user_stories/active/handle-time.md
+- user_stories/active/handle-time.rb
+- user_stories/done/epic--score-order/PLAN.md
+- user_stories/done/epic--score-order/band-score-order.md
+- user_stories/done/epic--score-order/chamber-ensemble-score-order.md
+- user_stories/done/epic--score-order/orchestral-score-order.md
+- user_stories/done/instrument-variant.md
+- user_stories/done/superclass-for-note.md
+- user_stories/todo/agentic-daw.md
+- user_stories/todo/consonance-dissonance-classification.md
+- user_stories/todo/dyad-analysis.md
+- user_stories/todo/material-and-scores.md
+- user_stories/todo/organizing-content.md
+- user_stories/todo/percussion_set.md
+- user_stories/todo/pitch-class-set-analysis.md
+- user_stories/todo/pitch-set-classification.md
+- user_stories/todo/sonority-identification.md
 homepage: https://github.com/roberthead/head_music
 licenses:
 - MIT