head_music 8.3.0 → 9.0.1

data/lib/head_music.rb

@@ -14,7 +14,7 @@ require "i18n"
 require "i18n/backend/fallbacks"
 
 I18n::Backend::Simple.include I18n::Backend::Fallbacks
-I18n.load_path << Dir[File.join(File.dirname(__dir__), "lib", "head_music", "locales", "*.yml")]
+I18n.load_path += Dir[File.join(File.dirname(__dir__), "lib", "head_music", "locales", "*.yml")]
 I18n.config.available_locales = %i[en fr de it ru es en_US en_GB]
 I18n.default_locale = :en
 I18n.fallbacks[:de] = %i[de en_GB en]
@@ -32,40 +32,57 @@ require "head_music/utilities/hash_key"
 require "head_music/named"
 
 # rudiments
+require "head_music/rudiment/base"
+require "head_music/rudiment/letter_name"
 require "head_music/rudiment/alteration"
+require "head_music/rudiment/spelling"
+require "head_music/rudiment/rhythmic_unit"
+require "head_music/rudiment/rhythmic_unit/parser"
+require "head_music/rudiment/rhythmic_value"
+require "head_music/rudiment/rhythmic_value/parser"
+require "head_music/rudiment/register"
+require "head_music/rudiment/pitch"
+require "head_music/rudiment/pitch/parser"
+require "head_music/rudiment/rhythmic_element"
+require "head_music/rudiment/note"
+require "head_music/rudiment/unpitched_note"
+require "head_music/rudiment/rest"
+
 require "head_music/rudiment/chromatic_interval"
 require "head_music/rudiment/clef"
 require "head_music/rudiment/consonance"
+require "head_music/rudiment/tonal_context"
+require "head_music/rudiment/diatonic_context"
+require "head_music/rudiment/key"
+require "head_music/rudiment/mode"
 require "head_music/rudiment/key_signature"
 require "head_music/rudiment/key_signature/enharmonic_equivalence"
-require "head_music/rudiment/letter_name"
 require "head_music/rudiment/meter"
 require "head_music/rudiment/musical_symbol"
-require "head_music/rudiment/pitch"
 require "head_music/rudiment/pitch/enharmonic_equivalence"
 require "head_music/rudiment/pitch/octave_equivalence"
 require "head_music/rudiment/pitch_class"
 require "head_music/rudiment/quality"
 require "head_music/rudiment/reference_pitch"
-require "head_music/rudiment/register"
 require "head_music/rudiment/rhythm"
-require "head_music/rudiment/rhythmic_unit"
 require "head_music/rudiment/scale"
 require "head_music/rudiment/scale_degree"
 require "head_music/rudiment/scale_type"
 require "head_music/rudiment/solmization"
-require "head_music/rudiment/spelling"
+require "head_music/rudiment/tempo"
 require "head_music/rudiment/tuning"
 require "head_music/rudiment/tuning/just_intonation"
-require "head_music/rudiment/tuning/pythagorean"
 require "head_music/rudiment/tuning/meantone"
+require "head_music/rudiment/tuning/pythagorean"
 
 # instruments
 require "head_music/instruments/instrument_family"
-require "head_music/instruments/instrument"
+require "head_music/instruments/instrument_type"
+require "head_music/instruments/variant"
 require "head_music/instruments/staff_scheme"
 require "head_music/instruments/staff"
-require "head_music/instruments/variant"
+require "head_music/instruments/instrument"
+require "head_music/instruments/score_order"
 
 # content
 require "head_music/content/bar"
@@ -73,7 +90,6 @@ require "head_music/content/composition"
 require "head_music/content/note"
 require "head_music/content/placement"
 require "head_music/content/position"
-require "head_music/content/rhythmic_value"
 require "head_music/content/staff"
 require "head_music/content/voice"
 
@@ -86,6 +102,7 @@ require "head_music/analysis/diatonic_interval/parser"
 require "head_music/analysis/diatonic_interval/semitones"
 require "head_music/analysis/diatonic_interval/size"
 require "head_music/analysis/harmonic_interval"
+require "head_music/analysis/interval_consonance"
 require "head_music/analysis/interval_cycle"
 require "head_music/analysis/melodic_interval"
 require "head_music/analysis/motion"
@@ -94,6 +111,10 @@ require "head_music/analysis/pitch_set"
 require "head_music/analysis/sonority"
 
 # style analysis
+require "head_music/style/tradition"
+require "head_music/style/modern_tradition"
+require "head_music/style/renaissance_tradition"
+require "head_music/style/medieval_tradition"
 require "head_music/style/analysis"
 require "head_music/style/annotation"
 require "head_music/style/mark"

data/user_stories/active/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/active/handle-time.rb

@@ -0,0 +1,177 @@
+# 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.get(:starting_position, HeadMusic::Time::Position.new)
+    @starting_smpte_timecode = attributes.get(:starting_smpte_timecode, HeadMusic::Time::SmpteTimecode.new)
+  end
+end
+
+class HeadMusic::Time::MeterEvent
+  attr_accessor :position, :meter
+
+  def initialize(position, meter)
+    @position = position
+  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
+
+# Abstract superclass
+class HeadMusic::Time::Position
+  include Comparable
+
+  def initialize(value, meter: nil, tempo: nil)
+    @value = value
+    @meter = meter || HeadMusic::Rudiment::Meter.default
+    @tempo = tempo || HeadMusic::Rudiment::Tempo.default
+  end
+
+  def <=>(other)
+    to_i <=> other.to_i
+  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::Value.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
+    HeadMusic::Time::Position.new(@bar, @beat, @tick, @subtick)
+  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/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/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/{backlog → todo}/dyad-analysis.md

@@ -6,6 +6,8 @@ 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
@@ -14,16 +16,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

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

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