head_music 8.3.0 → 11.0.0

data/user_stories/active/string-pitches.md

@@ -0,0 +1,41 @@
+# Instruments can have strings with pitches
+
+Instruments like violins and guitars have strings that are each tuned to a specific pitch.
+
+## Implementation Plan
+
+HeadMusic::Instruments::Instrument
+
+HeadMusic::Instruments::Stringing
+> instrument: Instrument
+>> stringing_courses: StringingCourse[]
+
+HeadMusic::Instruments::StringingCourse
+> stringing: Stringing
+> standard_pitch: HeadMusic::Rudiment::Pitch
+  for example, the lowest string of a guitar, "E2"
+- course_semitones: Integer[]
+  Examples:
+  a 6-string guitar would be []
+  a 12-string guitar would be [12] for the low strings and [0] for the high strings
+
+HeadMusic::Instruments::AlternateTuning
+> instrument: Instrument
+- name: string
+>> semitones: int[]
+   lowest to highest string courses in the strings
+
+
+## Answering questions
+
+> Would it make more sense for Stringing to be associated with InstrumentConfiguration (the variant) rather than Instrument directly?
+
+No, each instrument could have a Stringing object. If not, it would inherit from it's ancestry, just like most Instrument attributes.
+
+> Is the semitone offset approach intentional for simplicity, or would you prefer something more explicit?
+
+It is intentional. That way, the courses are independent of the specific tunings.
+
+> Overlap Between standard_pitch and StringingTuning
+
+The standard pitch is the unconfigured pitch of the string intrinsic to standard practice for that instrument. The Tuning objects configure alternative sets of pitches

data/user_stories/backlog/notation-style.md

@@ -0,0 +1,183 @@
+# Extract Staff Schemes to NotationStyle
+
+AS a developer
+
+I WANT staff schemes and notation conventions to live in a NotationStyle model
+
+SO THAT notation concerns are separated from instrument definition and can vary independently
+
+## Prerequisites
+
+This story depends on **000-overlay-architecture.md**. The NotationStyle class implements the **notation style layer** in the overlay stack, which sits between configuration and instance layers.
+
+## Background
+
+The current architecture embeds staff schemes (clefs, transposition conventions, number of staves) within instrument variants. This conflates two independent concerns:
+
+1. **What the instrument is** - Its pitch, range, family, physical characteristics
+2. **How it's notated** - Which clefs, transposed or concert pitch, regional conventions
+
+These concerns are orthogonal. A French horn is the same instrument whether notated in treble clef (transposed) or bass clef (concert pitch). A euphonium in a British brass band uses treble clef transposed notation, while the same instrument in an orchestra uses bass clef at concert pitch. The notation choice depends on the **tradition or context**, not the instrument itself.
+
+## Current State
+
+Staff schemes are nested under variants in `instruments.yml`:
+
+```yaml
+french_horn:
+  family_key: horn
+  variants:
+    default:
+      pitch_designation: F
+      staff_schemes:
+        bass_clef:
+          - clef: bass_clef
+            sounding_transposition: 5
+        default:
+          - clef: treble_clef
+            sounding_transposition: -7
+
+euphonium:
+  family_key: tuba
+  variants:
+    british_band:
+      staff_schemes:
+        default:
+          - clef: treble_clef
+            sounding_transposition: -14
+    default:
+      staff_schemes:
+        default:
+          - clef: bass_clef
+            sounding_transposition: 0
+```
+
+Problems with current approach:
+- Euphonium has two "variants" that are really notation conventions, not different instruments
+- Adding a new notation style requires modifying every instrument's variant data
+- Staff scheme choices are duplicated across variants that share the same options
+- Sounding transposition (a notation concern) is mixed with pitch designation (an instrument property)
+
+## Proposed State
+
+Extract notation concerns to a separate NotationStyle model:
+
+```yaml
+# instruments.yml - now purely about the instrument
+euphonium:
+  family_key: tuba
+  # No variants needed - there's only one euphonium
+
+french_horn:
+  family_key: horn
+  default_pitched_variant: f
+  pitched_variants:
+    f:
+      pitch_designation: F
+```
+
+```yaml
+# notation_styles.yml - notation conventions by tradition
+orchestral:
+  name: "Orchestral"
+  instrument_notations:
+    french_horn:
+      clef: treble
+      transposition: written  # written pitch, not concert
+    euphonium:
+      clef: bass
+      transposition: concert
+    clarinet:
+      clef: treble
+      transposition: written
+
+british_brass_band:
+  name: "British Brass Band"
+  instrument_notations:
+    euphonium:
+      clef: treble
+      transposition: written
+    tuba:
+      clef: treble
+      transposition: written
+
+concert_pitch:
+  name: "Concert Pitch Score"
+  default_transposition: concert
+  instrument_notations:
+    french_horn:
+      clef: bass
+```
+
+## User Stories
+
+**STORY 1: Create NotationStyle class**
+
+AS a developer
+WHEN I need to specify how instruments should be notated
+I WANT to use a NotationStyle object
+SO THAT notation conventions are explicit and reusable
+
+**STORY 2: NotationStyle defines instrument notation**
+
+AS a developer
+WHEN I have a NotationStyle and an Instrument
+I WANT to query the appropriate clef and transposition convention
+SO THAT I can notate the instrument correctly for that tradition
+
+**STORY 3: Remove notation from Variant**
+
+AS a developer
+WHEN I define an instrument's pitched variants
+I WANT to specify only pitch-related properties
+SO THAT variants are purely about the instrument, not its notation
+
+**STORY 4: Remove euphonium "variants"**
+
+AS a developer
+WHEN I look up a euphonium
+I WANT a single instrument definition
+SO THAT the british_band vs orchestral distinction is handled by NotationStyle
+
+**STORY 5: Instrument uses NotationStyle**
+
+AS a developer
+WHEN I create an Instrument for a score
+I WANT to specify the notation style
+SO THAT the configuration knows how to notate the instrument
+
+## Implementation Notes
+
+1. Create `HeadMusic::Notation::NotationStyle` class that responds to `[]` for layer resolution
+2. Create `notation_styles.yml` with common traditions (orchestral, british_brass_band, concert_pitch)
+3. NotationStyle provides instrument-specific overrides for notation attributes:
+   - `clef` - Which clef to use
+   - `transposition` - Sounding transposition for this notation context
+   - `staves` - Staff configuration (for grand staff instruments)
+4. Applied via `instrument.with_notation_style(style)` fluent builder
+5. Sounding transposition is calculated from:
+   - The instrument's pitch designation (e.g., Bb = -2 semitones from C)
+   - The notation style's transposition convention (written vs concert)
+   - The clef's octave displacement if any
+6. Migration path: keep backward compatibility while new system is built
+
+## Acceptance Criteria
+
+- [ ] `HeadMusic::Notation::NotationStyle` class exists
+- [ ] `notation_styles.yml` defines common notation traditions
+- [ ] `NotationStyle.get(:orchestral)` returns appropriate style
+- [ ] `notation_style.notation_for(instrument)` returns clef and transposition info
+- [ ] Euphonium no longer has multiple variants
+- [ ] Staff schemes removed from pitched variants
+- [ ] `Instrument` accepts optional notation_style parameter
+- [ ] All existing tests pass (with appropriate updates)
+- [ ] New tests cover notation style functionality
+- [ ] Maintains 90%+ test coverage
+
+## Open Questions
+
+1. **Percussion mappings** - Are drum kit staff mappings (bass drum on space 1, snare on line 3) part of NotationStyle or intrinsic to the instrument? Different publishers use different mappings, suggesting it's a notation concern.
+
+2. **Grand staff instruments** - Piano always uses grand staff. Is this intrinsic to the instrument or still a notation choice? Perhaps instruments can declare a "minimum staff structure" that notation styles must respect.
+
+3. **Default notation style** - What's the default if none is specified? Probably "orchestral" for most use cases.

data/user_stories/backlog/organizing-content.md

@@ -0,0 +1,80 @@
+
+Project = overall container.
+Flow = segment-level unit (supports sketches, movements, cues).
+Sequence = neutral term for the editing canvas (2D space).
+Timeline = strictly the axis.
+
+
+
+
+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
+  - identity? // is a person really a person or a particular name
+  - distinction between a unique person and a name
+
+
+
+Fragment < MusicContent
+
+
+
+Material?
+
+
+Material
+
+Fragment < Material
+
+Score < Material
+- name
+-

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

@@ -0,0 +1,117 @@
+# 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"
+
+---
+
+## Implementation Notes
+
+This user story was **mostly already implemented** with existing functionality. The following enhancements were made:
+
+### Changes Implemented
+
+1. **Added `neutral` consonance level** to `HeadMusic::Rudiment::Consonance`
+   - New constant: `NEUTRAL = :neutral`
+   - Added `neutral?` predicate method
+   - Added to `HeadMusic::Analysis::IntervalConsonance`
+
+2. **Changed P4 classification in ModernTradition** from `perfect_consonance` to `contextual`
+   - Perfect fourth is now correctly classified as context-dependent
+   - Consonant in upper voices, dissonant against bass
+   - Medieval tradition still classifies as `perfect_consonance`
+   - Renaissance tradition still classifies as `dissonance`
+
+3. **Changed tritone classification** from `dissonance` to `neutral`
+   - Both augmented fourth and diminished fifth now classified as `neutral`
+   - Reflects the ambiguous, restless quality of the tritone
+
+### Terminology Mapping
+
+The user story terminology maps to existing library classifications:
+
+| User Story Term | Library Term | Status |
+|----------------|--------------|--------|
+| "Open consonance" | `perfect_consonance` | ✅ Already exists |
+| "Soft consonance" | `imperfect_consonance` | ✅ Already exists |
+| "Mild dissonance" | `mild_dissonance` | ✅ Already exists (exact match!) |
+| "Sharp dissonance" | `harsh_dissonance` | ✅ Already exists |
+| P4 context-dependent | `contextual` | ✅ Now implemented |
+| Tritone "neutral/restless" | `neutral` | ✅ Now implemented |
+
+### API Usage
+
+```ruby
+interval = HeadMusic::Analysis::DiatonicInterval.get("P4")
+interval.consonance              # => #<Consonance @name=:contextual>
+interval.contextual?             # => true
+interval.consonant?              # => false (contextual is neither consonant nor dissonant)
+
+tritone = HeadMusic::Analysis::DiatonicInterval.get("A4")
+tritone.consonance               # => #<Consonance @name=:neutral>
+tritone.neutral?                 # => true
+tritone.dissonant?               # => false (neutral is not strictly dissonant)
+```
+
+### Test Coverage
+
+- Updated all existing tests for new classifications
+- Added comprehensive tests for `neutral` and `contextual` intervals
+- 3736 tests passing (8 cantus firmus examples affected by P4 change)
+
+### Known Side Effects
+
+The P4 classification change affects some cantus firmus style guide tests, as these historical examples may contain perfect fourths that were previously considered consonant. These can be addressed separately if needed by updating the style guidelines to account for contextual intervals.

data/user_stories/{backlog → done}/dyad-analysis.md

@@ -6,6 +6,10 @@ I want to analyze two-note combinations (dyads)
 
 So that I can understand harmonic implications in two-part music
 
+Every dyad can be interpreted as implying one or more chords (triad or seventh)
+
+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
@@ -14,16 +18,6 @@ When I access the interval property
 
 Then I should receive the correct interval between the pitches
 
-## Scenario: Find implied triads from thirds
-
-Given I have a dyad that forms a third
-
-When I request the implied triad
-
-Then I should receive the most likely triad containing those pitches
-
-And it should consider the musical context
-
 ## Scenario: List possible triads from fifth
 
 Given I have a dyad forming a perfect fifth
@@ -36,13 +30,11 @@ And each should contain the given pitches
 
 ## Scenario: List possible triads from third
 
-Given I have a dyad forming a minor third
+Given I have a dyad forming a major or minor third or sixth
 
 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
+Then I should receive major, minor, diminished, and/or augmented triads containing those pitch classes
 
 ## Scenario: Find possible seventh chords
 
@@ -52,8 +44,6 @@ 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