head_music 8.3.0 → 11.0.0

data/user_stories/done/epic--score-order/PLAN.md

@@ -0,0 +1,244 @@
+# Score-Order Epic: Implementation Plan
+
+## Executive Summary
+
+The score-order feature addresses a fundamental need in music composition software - automatically organizing instruments in standardized score orders based on ensemble type. This is critical for professional composers and arrangers who need their scores to follow industry conventions.
+
+## Value Proposition
+
+- **Saves time**: Composers won't need to manually reorder instruments
+- **Ensures accuracy**: Follows established conventions automatically
+- **Flexibility**: Supports multiple ensemble types (orchestral, band, chamber)
+- **Professional output**: Scores will meet industry standards
+
+## Priority Recommendations
+
+### Phase 1: Orchestral Order (MVP)
+- Most complex and widely used
+- Clear, established conventions
+- Highest value for professional users
+
+### Phase 2: Band Support
+- Different enough to showcase flexibility
+- Strong user base in educational settings
+- Notable percussion placement differences
+
+### Phase 3: Chamber Ensembles
+- More specialized use cases
+- Could potentially be template-based
+
+## Technical Implementation Approach
+
+### Architecture Insights
+
+The existing Instruments module already provides:
+- `orchestra_section_key` (woodwind, brass, percussion, string, keyboard, voice)
+- Instrument families with proper classification
+- Good foundation but NO ordering logic yet
+
+### Proposed Implementation
+
+Create a standalone **`HeadMusic::Instruments::ScoreOrder`** class that:
+
+1. **Defines ordering rules** for different ensemble types (orchestral, band, chamber)
+2. **Works with instrument instances** directly (not tied to Composition module)
+3. **Supports custom overrides** while maintaining sensible defaults
+4. **Handles instrument abbreviations** through existing i18n system
+
+### Key Design Decisions
+
+- **Keep it simple**: No complex inheritance, just a straightforward ordering system
+- **Data-driven approach**: Store ordering rules in YAML like existing instrument data
+- **Flexible API**: Accept arrays of instrument names/objects, return ordered list
+- **Support multiple sections**: Handle both full instruments and section groupings
+- **Independence**: Not dependent on Content module (which is being rewritten)
+
+## Acceptance Criteria
+
+### Basic Functionality
+- ✅ Can order an array of instruments by orchestral convention
+- ✅ Can order an array of instruments by band convention
+- ✅ Can order an array of instruments by chamber ensemble type
+- ✅ Returns instruments in correct family/section groupings
+
+### Flexibility
+- ✅ Handles unknown instruments gracefully (append at end)
+- ✅ Supports both instrument objects and string names as input
+- ✅ Allows custom ordering overrides
+
+### Integration
+- ✅ Works independently of Content module
+- ✅ Follows existing HeadMusic patterns (`.get()` factory method)
+- ✅ Maintains 90%+ test coverage
+
+### Performance
+- ✅ Orders 100+ instruments in < 100ms
+- ✅ Caches ordering rules efficiently
+
+## MVP Scope
+
+Start with orchestral ordering only:
+
+```ruby
+instruments = ["violin", "trumpet", "flute", "timpani", "cello"]
+ordered = HeadMusic::Instruments::ScoreOrder.in_orchestral_order(instruments)
+# => ["flute", "trumpet", "timpani", "violin", "cello"]
+```
+
+## Detailed Orchestral Order
+
+Standard orchestral score order from top to bottom:
+
+1. **Woodwinds**
+   - Piccolo
+   - Flutes (I, II, III)
+   - Oboes (I, II, III)
+   - English Horn
+   - Clarinets (I, II, III)
+   - Bass Clarinet
+   - Bassoons (I, II, III)
+   - Contrabassoon
+
+2. **Brass**
+   - Horns (I, II, III, IV)
+   - Trumpets (I, II, III)
+   - Trombones (I, II, III)
+   - Tuba
+
+3. **Percussion**
+   - Timpani
+   - Percussion (various)
+
+4. **Keyboards & Harp**
+   - Harp
+   - Piano
+   - Celesta
+   - Organ
+
+5. **Soloists** (if any)
+   - Instrumental soloists
+   - Vocal soloists
+
+6. **Voices** (if any)
+   - Soprano
+   - Alto
+   - Tenor
+   - Bass
+
+7. **Strings**
+   - Violin I
+   - Violin II
+   - Viola
+   - Cello
+   - Double Bass
+
+## Success Metrics
+
+- Can correctly order any standard ensemble
+- Supports custom overrides when needed
+- Integrates smoothly with existing Instrument class
+- Maintains 90%+ test coverage
+- Performance: < 100ms for typical ensemble sizes
+
+## Implementation Strategy
+
+### Class Design: Single Class with Data-Driven Instances
+
+We'll use a **single class with instances** approach, following HeadMusic's established patterns:
+
+```ruby
+class HeadMusic::Instruments::ScoreOrder
+  include HeadMusic::Named
+
+  def self.get(ensemble_type)
+    # Returns an instance configured for that ensemble type
+    # Follows existing HeadMusic factory pattern
+  end
+
+  def self.in_orchestral_order(instruments)
+    get(:orchestral).order(instruments)
+  end
+
+  def self.in_band_order(instruments)
+    get(:band).order(instruments)
+  end
+
+  def order(instruments)
+    # Apply ordering rules from YAML data
+    # Handle both instrument objects and strings
+    # Gracefully handle unknown instruments
+  end
+end
+```
+
+### Why This Approach
+
+1. **Consistency with HeadMusic patterns**:
+   - Matches `Instrument` and `InstrumentFamily` design
+   - Uses `.get()` factory method pattern
+   - Data-driven via YAML configuration
+
+2. **Maintainability**:
+   - Single class to test and maintain
+   - Shared logic for common operations
+   - Easy to add new ensemble types without code changes
+
+3. **Flexibility**:
+   - Rules defined in YAML, not hardcoded
+   - Simple to add custom orderings
+   - Could support user-defined orderings in future
+
+### YAML Structure
+
+```yaml
+# lib/head_music/instruments/score_orders.yml
+orchestral:
+  name: "Orchestral"
+  sections:
+    - section_key: woodwind
+      instruments: [piccolo, flute, oboe, english_horn, clarinet, bass_clarinet, bassoon, contrabassoon]
+    - section_key: brass
+      instruments: [horn, trumpet, trombone, tuba]
+    - section_key: percussion
+      instruments: [timpani, percussion]
+    - section_key: keyboard
+      instruments: [harp, piano, celesta, organ]
+    - section_key: voice
+      instruments: [soprano_voice, alto_voice, tenor_voice, bass_voice]
+    - section_key: string
+      instruments: [violin, viola, cello, double_bass]
+
+band:
+  name: "Concert Band"
+  sections:
+    - section_key: woodwind
+      instruments: [flute, oboe, bassoon, clarinet, saxophone]
+    - section_key: brass
+      instruments: [cornet, trumpet, horn, trombone, euphonium, tuba]
+    - section_key: percussion
+      instruments: [timpani, percussion]
+
+brass_quintet:
+  name: "Brass Quintet"
+  sections:
+    - section_key: brass
+      instruments: [trumpet, trumpet, horn, trombone, tuba]
+
+woodwind_quintet:
+  name: "Woodwind Quintet"
+  sections:
+    - section_key: woodwind
+      instruments: [flute, oboe, clarinet, horn, bassoon]
+```
+
+## Implementation Steps
+
+1. Create `HeadMusic::Instruments::ScoreOrder` class with factory pattern
+2. Create `score_orders.yml` with orchestral ordering rules
+3. Implement `#order` method with instrument resolution logic
+4. Add RSpec tests for orchestral ordering
+5. Add band ordering to YAML and test
+6. Add chamber ensemble templates and tests
+7. Add support for custom instrument positions
+8. Document API with YARD comments
+9. Consider future integration points with notation systems

data/user_stories/done/expand-playing-techniques.md

@@ -0,0 +1,38 @@
+## User Story: Load Playing Techniques from YAML Data File
+
+**As a** client of the HeadMusic gem
+
+**I want** access to a comprehensive catalog of playing techniques across all instrument families
+
+**So that** I can notate and work with playing techniques for strings, winds, harp, keyboard, and percussion—not just drum kit techniques
+
+### Background
+
+The current `PlayingTechnique` class uses a hardcoded `TECHNIQUES` constant containing only 14 percussion-focused techniques (stick, pedal, mallet, hand, brush, rim_shot, cross_stick, open, closed, damped, let_ring, choked, bow, bell).
+
+A new `playing_techniques.yml` data file has been created with 50+ techniques organized by scope (common, strings, winds, percussion, harp, keyboard), including:
+
+- **Common techniques**: legato, marcato, vibrato, con sordino, naturale, ordinario
+- **String/wind techniques**: harmonics, bowing techniques
+- **Percussion techniques**: rim shots, cross sticks, dead strokes, motor on/off
+- **Harp techniques**: près de la table
+- **Rich metadata**: origin language, meaning, notation variants
+
+The YAML-driven approach aligns with how other HeadMusic components work (instruments, clefs, scales, etc.) and enables future extensibility.
+
+### Acceptance Criteria
+
+- [ ] `PlayingTechnique.all` returns techniques loaded from `playing_techniques.yml`
+- [ ] The `TECHNIQUES` constant is removed
+- [ ] Each technique retains access to its metadata (scopes, origin, meaning, notations)
+- [ ] `PlayingTechnique.get(identifier)` continues to work for any technique in the YAML
+- [ ] New accessor methods for metadata: `#scopes`, `#origin`, `#meaning`, `#notations`
+- [ ] Techniques can be filtered by scope (e.g., `PlayingTechnique.for_scope(:strings)`)
+- [ ] Existing specs pass; new specs cover the expanded technique catalog
+- [ ] Maintains 90%+ test coverage
+
+### Technical Notes
+
+- Follow the existing YAML-loading pattern used by `Instrument`, `Clef`, and other data-driven classes
+- The `HeadMusic::Named` mixin is already included, enabling future i18n support
+- Consider caching loaded techniques for performance (consistent with other HeadMusic patterns)

data/user_stories/done/handle-time.md

@@ -0,0 +1,7 @@
+# Handling Time and Tempo
+
+AS a developer
+WHEN I am dealing with musical material
+I WANT to be able to synchronize the position of bars and beats with the flow of clock time
+
+See `./handle-time.rb`

data/user_stories/done/handle-time.rb

@@ -0,0 +1,163 @@
+# The Time module provides classes and methods to handle representations
+# of musical time and its relationship to clock time and SMPTE Time Code.
+module HeadMusic::Time
+  # ticks per quarter note value
+  PPQN = PULSES_PER_QUARTER_NOTE = 960
+  SUBTICKS_PER_TICK = 240
+end
+
+# Representation of a conductor track for musical material
+# Each moment in a track corresponds to the following positions:
+# - ellapsed clock time
+#   - starts at 0.0 seconds
+#   - the source-of-truth clock time
+#   - nanosecond resolution
+# - a musical position
+#   - bars:beats:ticks:subticks
+# - a SMPTE timecode
+#   - hours:minutes:seconds:frames
+class HeadMusic::Time::Conductor
+  attr_accessor :starting_position, :starting_smpte_timecode, :framerate
+
+  def initialize(attributes = {})
+    attributes = attributes.symbolize_keys
+    @starting_position = attributes.fetch(:starting_position, HeadMusic::Time::MusicalPosition.new)
+    @starting_smpte_timecode = attributes.fetch(:starting_smpte_timecode, HeadMusic::Time::SmpteTimecode.new)
+  end
+end
+
+class HeadMusic::Time::MeterEvent
+  attr_accessor :position, :meter
+
+  def initialize(position, meter)
+    @position = position
+    @meter = meter
+  end
+end
+
+class HeadMusic::Time::TempoEvent
+  attr_accessor :position, :tempo
+
+  # accepts a rhythmic value and a bpm
+  def initialize(position, beat_value, beats_per_minute)
+    @position = position
+    @tempo = HeadMusic::Rudiment::Tempo.new(beat_value, beats_per_minute)
+  end
+end
+
+# A value object representing ellapsed nanoseconds of clock time
+class HeadMusic::Time::ClockPosition
+  include Comparable
+
+  attr_reader :nanoseconds
+
+  def initialize(nanoseconds)
+    @nanoseconds = nanoseconds
+  end
+
+  def to_i
+    nanoseconds
+  end
+
+  def to_microseconds
+    nanoseconds / 1_000.0
+  end
+
+  def to_milliseconds
+    nanoseconds / 1_000_000.0
+  end
+
+  def to_seconds
+    nanoseconds / 1_000_000_000.0
+  end
+
+  def +(other)
+    HeadMusic::Time::ClockPosition.new(nanoseconds + other.to_i)
+  end
+
+  def <=>(other)
+    nanoseconds <=> other.to_i
+  end
+end
+
+# Representation of a musical position.
+# Consists of:
+# - bar
+# - beat (or count)
+# - tick (960 ticks / quarter note value)
+# - subtick (240 subticks / tick)
+#
+# Note: In the absence of a specific meter,
+# no math can be performed on the position.
+class HeadMusic::Time::MusicalPosition
+  attr_reader :bar, :beat, :tick, :subtick
+
+  DEFAULT_FIRST_BAR = 1
+  FIRST_BEAT = 1
+  FIRST_TICK = 0
+  FIRST_SUBTICK = 0
+
+  def self.parse(identifier)
+    new(*identifier.scan(/\d+/)[0..3])
+  end
+
+  def initialize(
+    bar = DEFAULT_FIRST_BAR,
+    beat = FIRST_BEAT,
+    tick = FIRST_TICK,
+    subtick = FIRST_SUBTICK
+  )
+    @bar = bar.to_i
+    @beat = beat.to_i
+    @tick = tick.to_i
+    @subtick = subtick.to_i
+  end
+
+  def to_a
+    [bar, beat, tick, subtick]
+  end
+
+  def to_s
+    "#{bar}:#{beat}:#{tick}:#{subtick}"
+  end
+
+  # Accept a meter and roll excessive values over to the next level
+  def normalize!(meter)
+    return self unless meter
+
+    # Carry subticks into ticks
+    if subtick >= HeadMusic::Time::SUBTICKS_PER_TICK || subtick.negative?
+      tick_delta, @subtick = subtick.divmod(HeadMusic::Time::SUBTICKS_PER_TICK)
+      @tick += tick_delta
+    end
+
+    # Carry ticks into beats
+    if tick >= meter.ticks_per_count || tick.negative?
+      beat_delta, @tick = tick.divmod(meter.ticks_per_count)
+      @beat += beat_delta
+    end
+
+    # Carry beats into bars
+    if beat >= meter.counts_per_bar || beat.negative?
+      bar_delta, @beat = beat.divmod(meter.counts_per_bar)
+      @bar += bar_delta
+    end
+    self
+  end
+end
+
+class HeadMusic::Time::SamplesPosition
+end
+
+class HeadMusic::Time::TimecodePosition # (SMPTE/MTC)
+end
+
+# Represents a SMPTE timecode position
+# HH:MM:SS:FF (hours:minutes:seconds:frames)
+class HeadMusic::Time::SmpteTimecode
+  attr_reader :hour, :minute, :second, :frame
+
+  def initialize(hour = 1, minute = 0, second = 0, frame = 0)
+    @hour, @minute, @second, @frame = hour.to_i, minute.to_i, second.to_i, frame.to_i
+  end
+end

data/user_stories/done/instrument-architecture.md

@@ -0,0 +1,238 @@
+# Instrument Inheritance Architecture
+
+AS a developer
+
+I WANT instruments to resolve attributes through composable parent-based inheritance with configurable options
+
+SO THAT I can model the full complexity of instruments with a simple, familiar pattern
+
+## Background
+
+The current instrument architecture uses nested objects (GenericInstrument → Variant → StaffScheme → Staff) which conflates several independent concerns:
+
+1. **Species defaults** - What a trumpet typically is
+2. **Pitched identity** - This specific clarinet is in A
+3. **Physical configuration** - Piccolo trumpet with A leadpipe installed
+4. **Notation conventions** - British brass band uses treble clef for euphonium
+
+This story addresses concerns 1-3 through parent-based inheritance. Notation (concern 4) is orthogonal and will be handled separately.
+
+## The Inheritance Pattern
+
+### Self-Referential Instrument
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  Instrument                                             │
+│    belongs_to :parent (optional)                        │
+│    has_many :instrument_configurations                  │
+│                                                         │
+│  Attributes resolve via parent chain:                   │
+│    pitch_key || parent&.pitch_key                       │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Inheritance Examples
+
+```
+trumpet (no parent)
+  ├── piccolo_trumpet (parent: trumpet, different range)
+  ├── bass_trumpet (parent: trumpet, different range)
+  └── pocket_trumpet (parent: trumpet, same attributes)
+
+clarinet (no parent, pitch_key: b_flat)
+  ├── clarinet_in_a (parent: clarinet, pitch_key: a)
+  ├── clarinet_in_c (parent: clarinet, pitch_key: c)
+  ├── clarinet_in_e_flat (parent: clarinet, pitch_key: e_flat)
+  └── bass_clarinet (parent: clarinet, different range)
+```
+
+### Resolution Example
+
+```ruby
+clarinet = Instrument.get("clarinet")
+clarinet.pitch_key        # => "b_flat"
+clarinet.family_key       # => "clarinet"
+
+clarinet_in_a = Instrument.get("clarinet_in_a")
+clarinet_in_a.pitch_key   # => "a" (own attribute)
+clarinet_in_a.family_key  # => "clarinet" (from parent)
+clarinet_in_a.parent      # => clarinet
+```
+
+### Key Characteristics
+
+1. **Simple**: One class, one relationship, familiar pattern
+2. **Natural resolution**: `attribute || parent&.attribute`
+3. **Arbitrary depth**: Can model instrument families at any level
+4. **Data-driven**: YAML or database records, not code
+
+## Core Attributes
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `name_key` | String | Primary identifier ("trumpet", "clarinet_in_a") |
+| `alias_name_keys` | Array | Alternative names |
+| `pitch_key` | String | The pitch designation ("b_flat", "a", "f") |
+| `family_key` | String | Instrument family ("trumpet", "clarinet") |
+| `orchestra_section_key` | String | Section ("brass", "woodwind", "strings") |
+| `classification_keys` | Array | Hornbostel-Sachs style classifications |
+| `default_clef_key` | String | Primary clef for this instrument |
+| `range_low` | String | Lowest playable pitch |
+| `range_high` | String | Highest playable pitch |
+
+## Configuration System
+
+Instruments can have configurable options that modify their attributes when selected.
+
+### Structure
+
+```ruby
+class Instrument
+  belongs_to :parent, class_name: "Instrument", optional: true
+  has_many :instrument_configurations  # applies to self and descendants
+end
+
+class InstrumentConfiguration
+  belongs_to :instrument
+  has_many :instrument_configuration_options
+
+  # name_key: "leadpipe", "mute", "crook", "extension", "attachment"
+end
+
+class InstrumentConfigurationOption
+  belongs_to :instrument_configuration
+
+  # name_key: "a_leadpipe", "straight_mute", "f_crook"
+  # transposition_semitones: Integer (e.g., -1 for A leadpipe on Bb instrument)
+  # lowest_pitch_semitones: Integer (e.g., -4 for C extension on double bass)
+end
+```
+
+### Configuration Examples
+
+| Instrument | Configuration | Options |
+|------------|---------------|---------|
+| Piccolo trumpet | `leadpipe` | `b_flat` (default), `a` (transposition: -1) |
+| Bass trombone | `f_attachment` | `disengaged`, `engaged` (lowest_pitch: -6) |
+| Double bass | `c_extension` | `without`, `with` (lowest_pitch: -4) |
+| Natural horn | `crook` | `e_flat`, `f`, `g`, etc. (various transpositions) |
+| Trumpet | `mute` | `open`, `straight`, `cup`, `harmon` |
+| Guitar | `capo` | `fret_0` through `fret_12` (transposition: 0-12) |
+
+### Configuration Resolution
+
+- `instrument.instrument_configurations` walks parent chain, collects all
+- No configuration selected = base instrument attributes unchanged
+- Configuration selection lives in composition context (Part/Voice), not on Instrument
+- A Part specifies target characteristics; configuration selection is derived/validated
+
+```ruby
+# The instrument defines what CAN be configured
+piccolo_trumpet = Instrument.get("piccolo_trumpet")
+piccolo_trumpet.instrument_configurations  # => [leadpipe config from parent chain]
+
+# A Part specifies what characteristics are needed
+part.instrument           # => piccolo_trumpet
+part.target_pitch_key     # => "a"
+part.effective_transposition  # resolved via configuration options
+```
+
+## User Stories
+
+### STORY 1: Implement parent-based attribute resolution
+
+AS a developer
+WHEN I access an attribute on an Instrument
+I WANT it resolved through the parent chain
+SO THAT child instruments inherit from parents
+
+**Acceptance criteria:**
+- `instrument.pitch_key` returns own value or walks parent chain
+- All core attributes support parent chain resolution
+- Returns nil if no instrument in chain provides the attribute
+
+### STORY 2: Implement configuration inheritance
+
+AS a developer
+WHEN I query an instrument's available configurations
+I WANT to get configurations from the entire parent chain
+SO THAT child instruments inherit configurable options
+
+**Acceptance criteria:**
+- `instrument.instrument_configurations` collects from self and all ancestors
+- Configurations defined on parent apply to all descendants
+- Child can define additional configurations
+
+### STORY 3: Model configuration options with effects
+
+AS a developer
+WHEN I define configuration options
+I WANT to specify their effects on instrument attributes
+SO THAT transposition and range changes are calculable
+
+**Acceptance criteria:**
+- `InstrumentConfigurationOption` has `transposition_semitones` attribute
+- `InstrumentConfigurationOption` has `lowest_pitch_semitones` attribute
+- Effects are integers representing semitone adjustments
+
+### STORY 4: Migrate existing instrument data
+
+AS a developer
+WHEN I use the existing `Instrument.get()` API
+I WANT it to work with the new inheritance architecture
+SO THAT existing code continues to function
+
+**Acceptance criteria:**
+- `Instrument.get("trumpet")` returns instrument with no parent
+- `Instrument.get("clarinet_in_a")` returns instrument with parent: clarinet
+- All existing tests pass
+
+### STORY 5: Remove Variant class
+
+AS a developer
+WHEN pitched variants are modeled as child instruments
+I WANT to remove the separate Variant class
+SO THAT the model is simplified
+
+**Acceptance criteria:**
+- `Variant` class removed
+- All pitched variants are now `Instrument` records with parents
+- YAML structure updated to reflect inheritance
+
+## Migration Strategy
+
+1. **Phase 1**: Add `parent` relationship to Instrument class
+2. **Phase 2**: Implement parent chain attribute resolution
+3. **Phase 3**: Migrate YAML data to parent-based structure
+4. **Phase 4**: Create InstrumentConfiguration and InstrumentConfigurationOption classes
+5. **Phase 5**: Remove Variant class and update GenericInstrument
+6. **Phase 6**: Update all specs
+
+## Acceptance Criteria
+
+- [x] `Instrument` class has `belongs_to :parent` relationship
+- [x] Attributes resolve through parent chain
+- [x] `Instrument#instrument_configurations` collects from ancestor chain
+- [x] `InstrumentConfiguration` class exists with `name_key`
+- [x] `InstrumentConfigurationOption` class exists with effect attributes
+- [x] `Variant` class removed
+- [x] YAML structure uses parent-based inheritance
+- [x] `Instrument.get()` API preserved for backward compatibility
+- [x] All existing tests pass
+- [x] New tests cover inheritance and configuration
+- [x] Maintains 90%+ test coverage
+
+## Deferred
+
+- **Tunings**: String instruments need individual string modeling before alternate tunings can be represented
+- **Notation**: Clef and transposition display conventions are orthogonal; see 002-notation-style.md
+
+## Open Questions
+
+1. **Multiple staves**: Piano needs two staves (grand staff). Is this an attribute on the instrument, or a notation concern?
+
+2. **Configuration selection in composition**: How does a Part specify which configuration options are selected? Options:
+   - Part stores selected options directly
+   - Part stores target attributes, system validates/suggests configurations
+   - Both (target attributes preferred, explicit selection as override)