head_music 9.0.1 → 11.1.0

data/lib/head_music/time/tempo_map.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+module HeadMusic
+  module Time
+    # Manages tempo changes along a musical timeline
+    #
+    # A TempoMap maintains a sorted list of tempo changes at specific musical
+    # positions, allowing you to determine which tempo is active at any point
+    # and iterate through tempo segments for time calculations.
+    #
+    # This is essential for converting between clock time and musical position
+    # when the tempo changes during a composition.
+    #
+    # @example Basic usage
+    #   tempo_map = HeadMusic::Time::TempoMap.new
+    #   tempo_map.add_change(MusicalPosition.new(5, 1, 0, 0), "quarter", 96)
+    #   tempo_map.add_change(MusicalPosition.new(9, 1, 0, 0), "quarter", 140)
+    #
+    #   tempo = tempo_map.tempo_at(MusicalPosition.new(7, 1, 0, 0))
+    #   tempo.beats_per_minute # => 96.0
+    #
+    # @example Iterating through segments
+    #   from = MusicalPosition.new(1, 1, 0, 0)
+    #   to = MusicalPosition.new(10, 1, 0, 0)
+    #   tempo_map.each_segment(from, to) do |start_pos, end_pos, tempo|
+    #     # Calculate clock time for this segment
+    #   end
+    class TempoMap
+      # @return [Array<TempoEvent>] all tempo events in chronological order
+      attr_reader :events
+
+      # Create a new tempo map
+      #
+      # @param starting_tempo [HeadMusic::Rudiment::Tempo] initial tempo (default: quarter = 120)
+      # @param starting_position [MusicalPosition] where the initial tempo begins (default: 1:1:0:0)
+      def initialize(starting_tempo: nil, starting_position: nil)
+        starting_tempo ||= HeadMusic::Rudiment::Tempo.new("quarter", 120)
+        starting_position ||= MusicalPosition.new
+        @events = [TempoEvent.new(starting_position, starting_tempo.beat_value.to_s, starting_tempo.beats_per_minute)]
+        @meter = nil # Will be set when used with a MeterMap
+      end
+
+      # Add a tempo change at the specified position
+      #
+      # If a tempo change already exists at this position, it will be replaced.
+      # Events are automatically maintained in sorted order.
+      #
+      # @param position [MusicalPosition] where the tempo change occurs
+      # @param beat_value_or_tempo [String, HeadMusic::Rudiment::Tempo] either a beat value like "quarter" or a Tempo object
+      # @param beats_per_minute [Numeric, nil] BPM (required if beat_value_or_tempo is a string)
+      # @return [TempoEvent] the created event
+      def add_change(position, beat_value_or_tempo, beats_per_minute = nil)
+        # Remove any existing event at this position (except the first)
+        remove_change(position)
+
+        # Create the new event
+        event = if beat_value_or_tempo.is_a?(HeadMusic::Rudiment::Tempo)
+          TempoEvent.new(position, beat_value_or_tempo.beat_value.to_s, beat_value_or_tempo.beats_per_minute).tap do |e|
+            e.tempo = beat_value_or_tempo
+          end
+        else
+          TempoEvent.new(position, beat_value_or_tempo, beats_per_minute)
+        end
+
+        @events << event
+        sort_events!
+        event
+      end
+
+      # Remove a tempo change at the specified position
+      #
+      # The starting tempo (first event) cannot be removed.
+      #
+      # @param position [MusicalPosition] the position of the event to remove
+      # @return [void]
+      def remove_change(position)
+        @events.reject! do |event|
+          event != @events.first && positions_equal?(event.position, position)
+        end
+      end
+
+      # Remove all tempo changes except the starting tempo
+      #
+      # @return [void]
+      def clear_changes
+        @events = [@events.first]
+      end
+
+      # Find the tempo active at a given position
+      #
+      # Returns the tempo from the most recent tempo event at or before
+      # the specified position.
+      #
+      # @param position [MusicalPosition] the position to query
+      # @return [HeadMusic::Rudiment::Tempo] the active tempo
+      def tempo_at(position)
+        # Normalize positions for comparison if we have a meter
+        normalized_pos = @meter ? position.dup.tap { |p| p.normalize!(@meter) } : position
+
+        # Find the last event at or before this position
+        active_event = @events.reverse.find do |event|
+          normalized_event_pos = @meter ? event.position.dup.tap { |p| p.normalize!(@meter) } : event.position
+          normalized_event_pos <= normalized_pos
+        end
+
+        active_event&.tempo || @events.first.tempo
+      end
+
+      # Iterate through tempo segments between two positions
+      #
+      # Yields each segment with its start position, end position, and tempo.
+      # Segments are created wherever a tempo change occurs within the range.
+      #
+      # @param from_position [MusicalPosition] start of the range
+      # @param to_position [MusicalPosition] end of the range
+      # @yield [start_position, end_position, tempo] for each segment
+      # @yieldparam start_position [MusicalPosition] segment start
+      # @yieldparam end_position [MusicalPosition] segment end
+      # @yieldparam tempo [HeadMusic::Rudiment::Tempo] active tempo
+      # @return [void]
+      def each_segment(from_position, to_position)
+        # Normalize positions if we have a meter
+        from_pos = @meter ? from_position.dup.tap { |p| p.normalize!(@meter) } : from_position
+        to_pos = @meter ? to_position.dup.tap { |p| p.normalize!(@meter) } : to_position
+
+        # Find events that affect this range
+        relevant_events = @events.select do |event|
+          normalized_event_pos = @meter ? event.position.dup.tap { |p| p.normalize!(@meter) } : event.position
+          normalized_event_pos < to_pos
+        end
+
+        # Start with the tempo active at from_position
+        current_pos = from_pos
+        current_tempo = tempo_at(from_pos)
+
+        # Iterate through relevant events
+        relevant_events.each do |event|
+          normalized_event_pos = @meter ? event.position.dup.tap { |p| p.normalize!(@meter) } : event.position
+
+          # Skip events before our starting position
+          next if normalized_event_pos <= from_pos
+
+          # Yield the segment up to this event
+          yield current_pos, normalized_event_pos, current_tempo
+
+          # Move to next segment
+          current_pos = normalized_event_pos
+          current_tempo = event.tempo
+        end
+
+        # Yield the final segment to the end position
+        yield current_pos, to_pos, current_tempo
+      end
+
+      # Set the meter for position normalization
+      #
+      # @param meter [HeadMusic::Rudiment::Meter] the meter to use
+      # @return [void]
+      # @api private
+      attr_writer :meter
+
+      private
+
+      # Sort events by position
+      #
+      # @return [void]
+      def sort_events!
+        @events.sort_by! do |event|
+          pos = event.position
+          [pos.bar, pos.beat, pos.tick, pos.subtick]
+        end
+      end
+
+      # Check if two positions are equal
+      #
+      # @param pos1 [MusicalPosition] first position
+      # @param pos2 [MusicalPosition] second position
+      # @return [Boolean] true if positions are equal
+      def positions_equal?(pos1, pos2)
+        pos1.bar == pos2.bar &&
+          pos1.beat == pos2.beat &&
+          pos1.tick == pos2.tick &&
+          pos1.subtick == pos2.subtick
+      end
+    end
+  end
+end

data/lib/head_music/time.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module HeadMusic
+  # The Time module provides classes and methods to handle representations
+  # of musical time and its relationship to clock time and SMPTE Time Code.
+  #
+  # This module enables synchronization between three time representations:
+  # - Clock time: elapsed nanoseconds (source of truth)
+  # - Musical position: bars:beats:ticks:subticks notation
+  # - SMPTE timecode: hours:minutes:seconds:frames for video/audio sync
+  #
+  # @example Converting between time representations
+  #   conductor = HeadMusic::Time::Conductor.new
+  #   clock_pos = HeadMusic::Time::ClockPosition.new(1_000_000_000) # 1 second
+  #   musical_pos = conductor.clock_to_musical(clock_pos)
+  module Time
+    # Ticks per quarter note value (MIDI standard)
+    PPQN = PULSES_PER_QUARTER_NOTE = 960
+
+    # Subticks provide finer resolution than ticks for precise timing
+    SUBTICKS_PER_TICK = 240
+  end
+end
+
+require_relative "time/clock_position"
+require_relative "time/musical_position"
+require_relative "time/smpte_timecode"
+require_relative "time/meter_event"
+require_relative "time/tempo_event"
+require_relative "time/tempo_map"
+require_relative "time/meter_map"
+require_relative "time/conductor"

data/lib/head_music/utilities/case.rb

@@ -0,0 +1,27 @@
+# A namespace for utilities classes and modules
+module HeadMusic::Utilities; end
+
+# Util for converting an object to a particular case
+class HeadMusic::Utilities::Case
+  def self.to_snake_case(text)
+    text.to_s
+      .gsub("::", "/")
+      .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+      .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+      .tr("-", "_")
+      .tr(" ", "_")
+      .gsub(/[^\w\/]+/, "_")
+      .squeeze("_")
+      .gsub(/^_|_$/, "")
+      .downcase
+  end
+
+  def self.to_kebab_case(text)
+    to_snake_case(text).tr("_", "-")
+  end
+
+  def self.to_camel_case(text)
+    str = to_snake_case(text)
+    str.split("_").map.with_index { |word, index| index.zero? ? word : word.capitalize }.join
+  end
+end

data/lib/head_music/utilities/hash_key.rb

@@ -22,7 +22,7 @@ class HeadMusic::Utilities::HashKey
 
   def normalized_string
     @normalized_string ||=
-      transliterated_string.downcase.gsub(/\W+/, "_")
+      HeadMusic::Utilities::Case.to_snake_case(transliterated_string)
   end
 
   def transliterated_string

data/lib/head_music/version.rb

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

data/lib/head_music.rb

@@ -13,19 +13,36 @@ require "humanize"
 require "i18n"
 require "i18n/backend/fallbacks"
 
-I18n::Backend::Simple.include I18n::Backend::Fallbacks
+# Configure I18n for HeadMusic locales
+# Include fallbacks backend if not already included
+I18n::Backend::Simple.include(I18n::Backend::Fallbacks) unless I18n::Backend::Simple.included_modules.include?(I18n::Backend::Fallbacks)
+
+# Add HeadMusic locale files to the load path (additive, doesn't overwrite)
 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]
-I18n.fallbacks[:en_US] = %i[en_US en en_GB]
-I18n.fallbacks[:en_GB] = %i[en_GB en en_US]
-I18n.fallbacks[:es] = %i[es en]
-I18n.fallbacks[:fr] = %i[fr en_GB en]
-I18n.fallbacks[:it] = %i[it en_GB en]
-I18n.fallbacks[:ru] = %i[ru en_GB en]
+
+# Add HeadMusic locales to available locales (additive, doesn't overwrite existing)
+HEAD_MUSIC_LOCALES = %i[en fr de it ru es en_US en_GB].freeze
+existing_locales = I18n.config.available_locales || []
+I18n.config.available_locales = (existing_locales + HEAD_MUSIC_LOCALES).uniq
+
+# Configure fallbacks for HeadMusic locales (only if not already configured)
+# These provide sensible defaults for music terminology translations
+HEAD_MUSIC_FALLBACKS = {
+  de: %i[de en_GB en],
+  en_US: %i[en_US en en_GB],
+  en_GB: %i[en_GB en en_US],
+  es: %i[es en],
+  fr: %i[fr en_GB en],
+  it: %i[it en_GB en],
+  ru: %i[ru en_GB en]
+}.freeze
+
+HEAD_MUSIC_FALLBACKS.each do |locale, fallbacks|
+  I18n.fallbacks[locale] = fallbacks if I18n.fallbacks[locale].empty? || I18n.fallbacks[locale] == [locale]
+end
 
 # utilities
+require "head_music/utilities/case"
 require "head_music/utilities/hash_key"
 
 # modules
@@ -58,7 +75,6 @@ require "head_music/rudiment/mode"
 require "head_music/rudiment/key_signature"
 require "head_music/rudiment/key_signature/enharmonic_equivalence"
 require "head_music/rudiment/meter"
-require "head_music/rudiment/musical_symbol"
 require "head_music/rudiment/pitch/enharmonic_equivalence"
 require "head_music/rudiment/pitch/octave_equivalence"
 require "head_music/rudiment/pitch_class"
@@ -75,17 +91,26 @@ require "head_music/rudiment/tuning/just_intonation"
 require "head_music/rudiment/tuning/meantone"
 require "head_music/rudiment/tuning/pythagorean"
 
+# time
+require "head_music/time"
+
 # instruments
 require "head_music/instruments/instrument_family"
-require "head_music/instruments/instrument_type"
 require "head_music/instruments/variant"
+require "head_music/instruments/playing_technique"
 require "head_music/instruments/staff_scheme"
 require "head_music/instruments/staff"
+require "head_music/instruments/instrument_configuration_option"
+require "head_music/instruments/instrument_configuration"
 require "head_music/instruments/instrument"
+require "head_music/instruments/stringing_course"
+require "head_music/instruments/stringing"
+require "head_music/instruments/alternate_tuning"
 require "head_music/instruments/score_order"
 
 # content
 require "head_music/content/bar"
+require "head_music/content/cantus_firmus_examples"
 require "head_music/content/composition"
 require "head_music/content/note"
 require "head_music/content/placement"
@@ -93,6 +118,9 @@ require "head_music/content/position"
 require "head_music/content/staff"
 require "head_music/content/voice"
 
+# notation
+require "head_music/notation"
+
 # analysis
 require "head_music/analysis/circle"
 require "head_music/analysis/diatonic_interval"
@@ -101,13 +129,14 @@ require "head_music/analysis/diatonic_interval/naming"
 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/dyad"
 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"
 require "head_music/analysis/pitch_class_set"
-require "head_music/analysis/pitch_set"
+require "head_music/analysis/pitch_collection"
 require "head_music/analysis/sonority"
 
 # style analysis

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/{todo → backlog}/organizing-content.md

@@ -5,7 +5,7 @@ Sequence = neutral term for the editing canvas (2D space).
 Timeline = strictly the axis.
 
 
-Material?
+
 
 ScorePart
 @name
@@ -59,6 +59,8 @@ ScorePartPlayer
 
 Player
 > person
+  - identity? // is a person really a person or a particular name
+  - distinction between a unique person and a name
 
 
 
@@ -66,7 +68,13 @@ Fragment < MusicContent
 
 
 
+Material?
 
 
+Material
 
+Fragment < Material
 
+Score < Material
+- name
+-