head_music 8.2.1 → 9.0.1

data/lib/head_music/utilities/hash_key.rb

@@ -2,8 +2,40 @@
 module HeadMusic::Utilities; end
 
 # Util for converting an object to a consistent hash key
-module HeadMusic::Utilities::HashKey
+class HeadMusic::Utilities::HashKey
   def self.for(identifier)
-    I18n.transliterate(identifier.to_s).downcase.gsub(/\W+/, "_").to_sym
+    @hash_keys ||= {}
+    @hash_keys[identifier] ||= new(identifier).to_sym
+  end
+
+  attr_reader :original
+
+  def initialize(identifier)
+    @original = identifier
+  end
+
+  def to_sym
+    normalized_string.to_sym
+  end
+
+  private
+
+  def normalized_string
+    @normalized_string ||=
+      transliterated_string.downcase.gsub(/\W+/, "_")
+  end
+
+  def transliterated_string
+    I18n.transliterate(desymbolized_string)
+  end
+
+  def desymbolized_string
+    original.to_s
+      .gsub("𝄫", "_double_flat")
+      .gsub("♭", "_flat")
+      .gsub("♮", "_natural")
+      .gsub("♯", "_sharp")
+      .gsub("#", "_sharp")
+      .gsub("𝄪", "_double_sharp")
   end
 end

data/lib/head_music/version.rb

@@ -1,3 +1,3 @@
 module HeadMusic
-  VERSION = "8.2.1"
+  VERSION = "9.0.1"
 end

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,37 +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/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"
@@ -70,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"
 
@@ -83,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"
@@ -91,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/epic--score-order/band-score-order.md

@@ -0,0 +1,38 @@
+# Band Score Order
+
+As a band director or arranger
+
+I want to organize instruments in band score order
+
+So that my scores follow standard concert band conventions
+
+## Scenario: Display instruments in band order
+
+Given I have a composition for concert band
+
+When I request the score order for a band arrangement
+
+Then the instruments should be ordered as follows:
+  - Flutes
+  - Oboes
+  - Bassoons
+  - Clarinets
+  - Saxophones
+  - Cornets
+  - Trumpets
+  - Horns
+  - Trombones
+  - Euphoniums
+  - Tubas
+  - Timpani
+  - Percussion
+
+## Scenario: Recognize different percussion placement
+
+Given I am working with both orchestral and band scores
+
+When I compare the score orders
+
+Then I should note that percussion placement differs:
+  - In orchestral scores: percussion appears after brass
+  - In band scores: percussion appears at the bottom

data/user_stories/done/epic--score-order/chamber-ensemble-score-order.md

@@ -0,0 +1,33 @@
+# Chamber Ensemble Score Order
+
+As a chamber music composer
+
+I want to organize instruments in standard chamber ensemble orders
+
+So that my scores follow established conventions for small ensembles
+
+## Scenario: Display brass quintet in standard order
+
+Given I have a brass quintet composition
+
+When I request the score order
+
+Then the instruments should be ordered as follows:
+  - Trumpet I
+  - Trumpet II
+  - Horn
+  - Trombone
+  - Tuba
+
+## Scenario: Display woodwind quintet in standard order
+
+Given I have a woodwind quintet composition
+
+When I request the score order
+
+Then the instruments should be ordered as follows:
+  - Flute
+  - Oboe
+  - Clarinet
+  - Horn
+  - Bassoon

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

@@ -0,0 +1,43 @@
+# Orchestral Score Order
+
+As a composer or conductor
+
+I want to organize instruments in orchestral score order
+
+So that my scores follow standard orchestral conventions
+
+## Scenario: Display instruments in orchestral order
+
+Given I have a composition with multiple instruments
+
+When I request the score order for an orchestral arrangement
+
+Then the instruments should be ordered as follows:
+  - Woodwinds (flutes, oboes, clarinets, bassoons)
+  - Brass (horns, trumpets, trombones, tuba)
+  - Percussion (timpani, percussion)
+  - Harp and keyboards
+  - Soloists (instrumental or vocal)
+  - Voices
+  - Strings (violins I, violins II, viola, violoncellos, double bass)
+
+## Scenario: Use standard orchestral abbreviations
+
+Given I am creating an orchestral score
+
+When I display instrument names
+
+Then I should see standard abbreviations:
+  - Fl or Fls for Flutes
+  - Ob or Obs for Oboes
+  - Cl or Cls for Clarinets
+  - Bsn or Bsns for Bassoons
+  - Hn or Hns for Horns
+  - Tpt or Tpts for Trumpets
+  - Trb or Trbs for Trombones
+  - Timp for Timpani
+  - Perc for Percussion
+  - Vlns for Violins
+  - Vla for Viola
+  - Vcl for Violoncellos
+  - DB for Double Bass