head_music 9.0.1 → 11.1.0

data/lib/head_music/rudiment/tuning/meantone.rb

@@ -45,43 +45,4 @@ class HeadMusic::Rudiment::Tuning::Meantone < HeadMusic::Rudiment::Tuning
     # Calculate the frequency
     tonal_center_frequency * ratio
   end
-
-  private
-
-  def calculate_tonal_center_frequency
-    # Use equal temperament to get the tonal center frequency from the reference pitch
-    interval_to_tonal_center = (tonal_center - reference_pitch.pitch).semitones
-    reference_pitch_frequency * (2**(interval_to_tonal_center / 12.0))
-  end
-
-  def ratio_for_interval(semitones)
-    # Handle octaves
-    octaves = semitones / 12
-    interval_within_octave = semitones % 12
-
-    # Make sure we handle negative intervals
-    if interval_within_octave < 0
-      interval_within_octave += 12
-      octaves -= 1
-    end
-
-    # Get the base ratio
-    base_ratio = case interval_within_octave
-    when 0 then INTERVAL_RATIOS[:unison]
-    when 1 then INTERVAL_RATIOS[:minor_second]
-    when 2 then INTERVAL_RATIOS[:major_second]
-    when 3 then INTERVAL_RATIOS[:minor_third]
-    when 4 then INTERVAL_RATIOS[:major_third]
-    when 5 then INTERVAL_RATIOS[:perfect_fourth]
-    when 6 then INTERVAL_RATIOS[:tritone]
-    when 7 then INTERVAL_RATIOS[:perfect_fifth]
-    when 8 then INTERVAL_RATIOS[:minor_sixth]
-    when 9 then INTERVAL_RATIOS[:major_sixth]
-    when 10 then INTERVAL_RATIOS[:minor_seventh]
-    when 11 then INTERVAL_RATIOS[:major_seventh]
-    end
-
-    # Apply octave adjustments
-    base_ratio * (2**octaves)
-  end
 end

data/lib/head_music/rudiment/tuning/pythagorean.rb

@@ -49,43 +49,4 @@ class HeadMusic::Rudiment::Tuning::Pythagorean < HeadMusic::Rudiment::Tuning
     # Calculate the frequency
     tonal_center_frequency * ratio
   end
-
-  private
-
-  def calculate_tonal_center_frequency
-    # Use equal temperament to get the tonal center frequency from the reference pitch
-    interval_to_tonal_center = (tonal_center - reference_pitch.pitch).semitones
-    reference_pitch_frequency * (2**(interval_to_tonal_center / 12.0))
-  end
-
-  def ratio_for_interval(semitones)
-    # Handle octaves
-    octaves = semitones / 12
-    interval_within_octave = semitones % 12
-
-    # Make sure we handle negative intervals
-    if interval_within_octave < 0
-      interval_within_octave += 12
-      octaves -= 1
-    end
-
-    # Get the base ratio
-    base_ratio = case interval_within_octave
-    when 0 then INTERVAL_RATIOS[:unison]
-    when 1 then INTERVAL_RATIOS[:minor_second]
-    when 2 then INTERVAL_RATIOS[:major_second]
-    when 3 then INTERVAL_RATIOS[:minor_third]
-    when 4 then INTERVAL_RATIOS[:major_third]
-    when 5 then INTERVAL_RATIOS[:perfect_fourth]
-    when 6 then INTERVAL_RATIOS[:tritone]
-    when 7 then INTERVAL_RATIOS[:perfect_fifth]
-    when 8 then INTERVAL_RATIOS[:minor_sixth]
-    when 9 then INTERVAL_RATIOS[:major_sixth]
-    when 10 then INTERVAL_RATIOS[:minor_seventh]
-    when 11 then INTERVAL_RATIOS[:major_seventh]
-    end
-
-    # Apply octave adjustments
-    base_ratio * (2**octaves)
-  end
 end

data/lib/head_music/rudiment/tuning.rb

@@ -32,4 +32,24 @@ class HeadMusic::Rudiment::Tuning < HeadMusic::Rudiment::Base
     pitch = HeadMusic::Rudiment::Pitch.get(pitch)
     reference_pitch_frequency * (2**(1.0 / 12))**(pitch - reference_pitch.pitch).semitones
   end
+
+  private
+
+  def calculate_tonal_center_frequency
+    # Use equal temperament to get the tonal center frequency from the reference pitch
+    interval_to_tonal_center = (tonal_center - reference_pitch.pitch).semitones
+    reference_pitch_frequency * (2**(interval_to_tonal_center / 12.0))
+  end
+
+  def ratio_for_interval(semitones)
+    # Handle octaves
+    octaves = semitones / 12
+    interval_within_octave = semitones % 12
+
+    # Get the base ratio from the subclass's INTERVAL_RATIOS constant
+    base_ratio = self.class::INTERVAL_RATIOS[self.class::INTERVAL_RATIOS.keys[interval_within_octave]]
+
+    # Apply octave adjustments
+    base_ratio * (2**octaves)
+  end
 end

data/lib/head_music/style/guidelines/consonant_climax.rb

@@ -27,11 +27,11 @@ class HeadMusic::Style::Guidelines::ConsonantClimax < HeadMusic::Style::Annotati
   end
 
   def highest_pitch_consonant_with_tonic?
-    diatonic_interval_to_highest_pitch.consonance?(:melodic)
+    !diatonic_interval_to_highest_pitch.dissonant?(:melodic)
   end
 
   def lowest_pitch_consonant_with_tonic?
-    diatonic_interval_to_lowest_pitch.consonance?(:melodic)
+    !diatonic_interval_to_lowest_pitch.dissonant?(:melodic)
   end
 
   def diatonic_interval_to_highest_pitch

data/lib/head_music/style/modern_tradition.rb

@@ -9,25 +9,22 @@ class HeadMusic::Style::ModernTradition < HeadMusic::Style::Tradition
     end
 
     case interval_mod
-    when 0, 12  # Unison, Octave
+    when 0  # Unison, Octave
       HeadMusic::Rudiment::Consonance::PERFECT_CONSONANCE
-    when 7      # Perfect Fifth
+    when 7  # Perfect Fifth
       HeadMusic::Rudiment::Consonance::PERFECT_CONSONANCE
-    when 3, 4   # Minor Third, Major Third
+    when 3, 4  # Minor Third, Major Third
       HeadMusic::Rudiment::Consonance::IMPERFECT_CONSONANCE
-    when 8, 9   # Minor Sixth, Major Sixth
+    when 8, 9  # Minor Sixth, Major Sixth
       HeadMusic::Rudiment::Consonance::IMPERFECT_CONSONANCE
-    when 5      # Perfect Fourth
-      # In standard practice, perfect fourth is considered consonant
-      # but contextual would be more accurate
-      HeadMusic::Rudiment::Consonance::PERFECT_CONSONANCE
+    when 5  # Perfect Fourth
+      # Perfect fourth is contextual: consonant in upper voices, dissonant against bass
+      HeadMusic::Rudiment::Consonance::CONTEXTUAL
     when 2, 10  # Major Second, Minor Seventh
       HeadMusic::Rudiment::Consonance::MILD_DISSONANCE
     when 1, 11  # Minor Second, Major Seventh
       HeadMusic::Rudiment::Consonance::HARSH_DISSONANCE
-    when 6      # Tritone (Aug 4th/Dim 5th)
-      HeadMusic::Rudiment::Consonance::DISSONANCE
-    else
+    when 6  # Tritone (Aug 4th/Dim 5th)
       HeadMusic::Rudiment::Consonance::DISSONANCE
     end
   end

data/lib/head_music/style/tradition.rb

@@ -15,7 +15,7 @@ module HeadMusic::Style
     end
 
     def name
-      self.class.name.split("::").last.sub(/Tradition$/, "").downcase.gsub(" ", "_").to_sym
+      HeadMusic::Utilities::Case.to_snake_case(self.class.name.split("::").last.sub(/Tradition$/, "")).to_sym
     end
   end
 end

data/lib/head_music/time/clock_position.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module HeadMusic
+  module Time
+    # A value object representing elapsed nanoseconds of clock time
+    #
+    # ClockPosition provides a high-precision representation of time elapsed
+    # from a reference point, stored as nanoseconds. This allows for precise
+    # temporal calculations in musical contexts where millisecond-level accuracy
+    # is required for MIDI timing, audio synchronization, and SMPTE timecode.
+    #
+    # @example Creating a position at one second
+    #   position = HeadMusic::Time::ClockPosition.new(1_000_000_000)
+    #   position.to_seconds # => 1.0
+    #
+    # @example Adding two positions together
+    #   pos1 = HeadMusic::Time::ClockPosition.new(500_000_000)
+    #   pos2 = HeadMusic::Time::ClockPosition.new(300_000_000)
+    #   result = pos1 + pos2
+    #   result.to_milliseconds # => 800.0
+    #
+    # @example Comparing positions
+    #   early = HeadMusic::Time::ClockPosition.new(1_000_000_000)
+    #   late = HeadMusic::Time::ClockPosition.new(2_000_000_000)
+    #   early < late # => true
+    class ClockPosition
+      include Comparable
+
+      # @return [Integer] the number of nanoseconds since the reference point
+      attr_reader :nanoseconds
+
+      # Create a new clock position
+      #
+      # @param nanoseconds [Integer] the number of nanoseconds elapsed
+      def initialize(nanoseconds)
+        @nanoseconds = nanoseconds
+      end
+
+      # Convert to integer representation (nanoseconds)
+      #
+      # @return [Integer] nanoseconds
+      def to_i
+        nanoseconds
+      end
+
+      # Convert nanoseconds to microseconds
+      #
+      # @return [Float] elapsed microseconds
+      def to_microseconds
+        nanoseconds / 1_000.0
+      end
+
+      # Convert nanoseconds to milliseconds
+      #
+      # @return [Float] elapsed milliseconds
+      def to_milliseconds
+        nanoseconds / 1_000_000.0
+      end
+
+      # Convert nanoseconds to seconds
+      #
+      # @return [Float] elapsed seconds
+      def to_seconds
+        nanoseconds / 1_000_000_000.0
+      end
+
+      # Add another clock position to this one
+      #
+      # @param other [ClockPosition, #to_i] another position or value with nanoseconds
+      # @return [ClockPosition] a new position with the combined duration
+      def +(other)
+        self.class.new(nanoseconds + other.to_i)
+      end
+
+      # Compare this position to another
+      #
+      # @param other [ClockPosition, #to_i] another position to compare
+      # @return [Integer] -1 if less than, 0 if equal, 1 if greater than
+      def <=>(other)
+        nanoseconds <=> other.to_i
+      end
+    end
+  end
+end

data/lib/head_music/time/conductor.rb

@@ -0,0 +1,264 @@
+# frozen_string_literal: true
+
+module HeadMusic
+  module Time
+    # Representation of a conductor track for musical material
+    #
+    # The Conductor class synchronizes three different time representations:
+    # - Clock time: elapsed nanoseconds (source of truth)
+    # - Musical position: bars:beats:ticks:subticks notation
+    # - SMPTE timecode: hours:minutes:seconds:frames
+    #
+    # Each moment in a track corresponds to all three positions simultaneously.
+    # The conductor handles conversions between these representations based on
+    # the current tempo, meter, and framerate.
+    #
+    # @example Basic usage
+    #   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)
+    #   smpte = conductor.clock_to_smpte(clock_pos)
+    #
+    # @example With custom tempo and meter
+    #   conductor = HeadMusic::Time::Conductor.new(
+    #     starting_tempo: HeadMusic::Rudiment::Tempo.new("quarter", 96),
+    #     starting_meter: HeadMusic::Rudiment::Meter.get("3/4")
+    #   )
+    #
+    # @example Converting between representations
+    #   conductor = HeadMusic::Time::Conductor.new
+    #   musical = HeadMusic::Time::MusicalPosition.new(2, 1, 0, 0)
+    #   clock = conductor.musical_to_clock(musical)
+    #   smpte = conductor.clock_to_smpte(clock)
+    class Conductor
+      # @return [MusicalPosition] the musical position at clock time 0
+      attr_accessor :starting_musical_position
+
+      # @return [SmpteTimecode] the SMPTE timecode at clock time 0
+      attr_accessor :starting_smpte_timecode
+
+      # @return [Integer] frames per second for SMPTE conversions
+      attr_accessor :framerate
+
+      # @return [TempoMap] the tempo map for this conductor
+      attr_reader :tempo_map
+
+      # @return [MeterMap] the meter map for this conductor
+      attr_reader :meter_map
+
+      # @return [HeadMusic::Rudiment::Tempo] the initial tempo (delegates to tempo_map)
+      def starting_tempo
+        tempo_map.events.first.tempo
+      end
+
+      # @return [HeadMusic::Rudiment::Meter] the initial meter (delegates to meter_map)
+      def starting_meter
+        meter_map.events.first.meter
+      end
+
+      # Create a new conductor
+      #
+      # @param starting_musical_position [MusicalPosition] initial musical position (default: 1:1:0:0)
+      # @param starting_smpte_timecode [SmpteTimecode] initial SMPTE timecode (default: 00:00:00:00)
+      # @param framerate [Integer] frames per second (default: 30)
+      # @param starting_tempo [HeadMusic::Rudiment::Tempo] initial tempo (default: quarter = 120)
+      # @param starting_meter [HeadMusic::Rudiment::Meter, String] initial meter (default: 4/4)
+      # @param tempo_map [TempoMap] custom tempo map (optional, creates one from starting_tempo if not provided)
+      # @param meter_map [MeterMap] custom meter map (optional, creates one from starting_meter if not provided)
+      def initialize(
+        starting_musical_position: nil,
+        starting_smpte_timecode: nil,
+        framerate: SmpteTimecode::DEFAULT_FRAMERATE,
+        starting_tempo: nil,
+        starting_meter: nil,
+        tempo_map: nil,
+        meter_map: nil
+      )
+        @starting_musical_position = starting_musical_position || MusicalPosition.new
+        @starting_smpte_timecode = starting_smpte_timecode || SmpteTimecode.new(0, 0, 0, 0, framerate: framerate)
+        @framerate = framerate
+
+        # Create or use provided maps
+        @tempo_map = tempo_map || TempoMap.new(
+          starting_tempo: starting_tempo || HeadMusic::Rudiment::Tempo.new("quarter", 120),
+          starting_position: @starting_musical_position
+        )
+        @meter_map = meter_map || MeterMap.new(
+          starting_meter: starting_meter || "4/4",
+          starting_position: @starting_musical_position
+        )
+
+        # Link maps together for position normalization
+        @tempo_map.meter = @meter_map.meter_at(@starting_musical_position)
+      end
+
+      # Convert clock position to musical position
+      #
+      # Uses the tempo map to determine how many beats have elapsed,
+      # accounting for tempo changes along the timeline.
+      #
+      # @param clock_position [ClockPosition] the clock time to convert
+      # @return [MusicalPosition] the corresponding musical position
+      def clock_to_musical(clock_position)
+        target_nanoseconds = clock_position.nanoseconds
+        accumulated_nanoseconds = 0
+        current_position = starting_musical_position
+
+        # We need an end position far enough to contain our target clock time
+        # Start with a reasonable guess and extend if needed
+        estimated_end_bar = starting_musical_position.bar + 1000
+        estimated_end = MusicalPosition.new(estimated_end_bar, 1, 0, 0)
+
+        tempo_map.each_segment(starting_musical_position, estimated_end) do |start_pos, end_pos, tempo|
+          meter = meter_map.meter_at(start_pos)
+
+          # Calculate clock duration of this segment
+          start_subticks = musical_position_to_subticks(start_pos, meter)
+          end_subticks = musical_position_to_subticks(end_pos, meter)
+          segment_subticks = end_subticks - start_subticks
+          segment_ticks = segment_subticks / HeadMusic::Time::SUBTICKS_PER_TICK.to_f
+          segment_nanoseconds = (segment_ticks * tempo.tick_duration_in_nanoseconds).round
+
+          # Check if our target falls within this segment
+          if accumulated_nanoseconds + segment_nanoseconds >= target_nanoseconds
+            # Target is in this segment - calculate exact position
+            remaining_nanoseconds = target_nanoseconds - accumulated_nanoseconds
+            remaining_ticks = remaining_nanoseconds / tempo.tick_duration_in_nanoseconds.to_f
+            remaining_subticks = (remaining_ticks * HeadMusic::Time::SUBTICKS_PER_TICK).round
+
+            # Add to start position of this segment
+            total_subticks = start_subticks + remaining_subticks
+
+            # Convert to bar:beat:tick:subtick
+            ticks_per_count = meter.ticks_per_count
+            counts_per_bar = meter.counts_per_bar
+            subticks_per_count = ticks_per_count * HeadMusic::Time::SUBTICKS_PER_TICK
+            subticks_per_bar = counts_per_bar * subticks_per_count
+
+            bars = (total_subticks / subticks_per_bar).floor
+            remaining = total_subticks % subticks_per_bar
+
+            beats = (remaining / subticks_per_count).floor
+            remaining %= subticks_per_count
+
+            ticks = (remaining / HeadMusic::Time::SUBTICKS_PER_TICK).floor
+            subticks = remaining % HeadMusic::Time::SUBTICKS_PER_TICK
+
+            position = MusicalPosition.new(bars + 1, beats + 1, ticks, subticks)
+            return position.normalize!(meter)
+          end
+
+          accumulated_nanoseconds += segment_nanoseconds
+          current_position = end_pos
+        end
+
+        # If we get here, return the last position (shouldn't normally happen)
+        current_position
+      end
+
+      # Convert musical position to clock position
+      #
+      # Uses the tempo map to determine how much clock time has elapsed
+      # based on the musical position, accounting for tempo changes.
+      #
+      # @param musical_position [MusicalPosition] the musical position to convert
+      # @return [ClockPosition] the corresponding clock time
+      def musical_to_clock(musical_position)
+        total_nanoseconds = 0
+
+        # Iterate through each tempo segment from start to target position
+        tempo_map.each_segment(starting_musical_position, musical_position) do |start_pos, end_pos, tempo|
+          # Get the meter for this segment to calculate subticks correctly
+          meter = meter_map.meter_at(start_pos)
+
+          # Calculate subticks in this segment
+          start_subticks = musical_position_to_subticks(start_pos, meter)
+          end_subticks = musical_position_to_subticks(end_pos, meter)
+          segment_subticks = end_subticks - start_subticks
+
+          # Convert subticks to ticks
+          segment_ticks = segment_subticks / HeadMusic::Time::SUBTICKS_PER_TICK.to_f
+
+          # Convert ticks to nanoseconds using this segment's tempo
+          nanoseconds_per_tick = tempo.tick_duration_in_nanoseconds
+          segment_nanoseconds = (segment_ticks * nanoseconds_per_tick).round
+
+          total_nanoseconds += segment_nanoseconds
+        end
+
+        ClockPosition.new(total_nanoseconds)
+      end
+
+      # Convert clock position to SMPTE timecode
+      #
+      # Uses the framerate to determine the timecode.
+      #
+      # @param clock_position [ClockPosition] the clock time to convert
+      # @return [SmpteTimecode] the corresponding SMPTE timecode
+      def clock_to_smpte(clock_position)
+        # Calculate total frames from nanoseconds
+        nanoseconds_per_second = 1_000_000_000.0
+        elapsed_seconds = clock_position.nanoseconds / nanoseconds_per_second
+        total_frames = (elapsed_seconds * framerate).round
+
+        # Add starting timecode frames
+        starting_frames = starting_smpte_timecode.to_total_frames
+        total_frames += starting_frames
+
+        # Convert frames to HH:MM:SS:FF
+        hours = total_frames / (framerate * 60 * 60)
+        remaining = total_frames % (framerate * 60 * 60)
+
+        minutes = remaining / (framerate * 60)
+        remaining %= (framerate * 60)
+
+        seconds = remaining / framerate
+        frames = remaining % framerate
+
+        timecode = SmpteTimecode.new(hours, minutes, seconds, frames, framerate: framerate)
+        timecode.normalize!
+      end
+
+      # Convert SMPTE timecode to clock position
+      #
+      # Uses the framerate to determine the clock time.
+      #
+      # @param smpte_timecode [SmpteTimecode] the SMPTE timecode to convert
+      # @return [ClockPosition] the corresponding clock time
+      def smpte_to_clock(smpte_timecode)
+        # Calculate total frames
+        total_frames = smpte_timecode.to_total_frames
+        starting_frames = starting_smpte_timecode.to_total_frames
+        elapsed_frames = total_frames - starting_frames
+
+        # Convert frames to seconds, then to nanoseconds
+        nanoseconds_per_second = 1_000_000_000.0
+        elapsed_seconds = elapsed_frames / framerate.to_f
+        elapsed_nanoseconds = (elapsed_seconds * nanoseconds_per_second).round
+
+        ClockPosition.new(elapsed_nanoseconds)
+      end
+
+      private
+
+      # Convert a musical position to total subticks for calculation
+      #
+      # @param position [MusicalPosition] the position to convert
+      # @param meter [HeadMusic::Rudiment::Meter] the meter to use for calculation
+      # @return [Integer] total subticks from the beginning
+      def musical_position_to_subticks(position, meter = nil)
+        meter ||= meter_map.meter_at(position)
+        ticks_per_count = meter.ticks_per_count
+        counts_per_bar = meter.counts_per_bar
+
+        total = 0
+        total += (position.bar - 1) * counts_per_bar * ticks_per_count * HeadMusic::Time::SUBTICKS_PER_TICK
+        total += (position.beat - 1) * ticks_per_count * HeadMusic::Time::SUBTICKS_PER_TICK
+        total += position.tick * HeadMusic::Time::SUBTICKS_PER_TICK
+        total += position.subtick
+
+        total
+      end
+    end
+  end
+end

data/lib/head_music/time/meter_event.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module HeadMusic
+  module Time
+    # Represents a meter change at a specific musical position
+    #
+    # MeterEvent marks a point in a musical timeline where the meter
+    # (time signature) changes. This is essential for properly calculating
+    # musical positions and normalizing bar:beat:tick:subtick values.
+    #
+    # @example Creating a meter change to 3/4 at bar 5
+    #   position = HeadMusic::Time::MusicalPosition.new(5, 1, 0, 0)
+    #   meter = HeadMusic::Rudiment::Meter.get("3/4")
+    #   event = HeadMusic::Time::MeterEvent.new(position, meter)
+    #
+    # @example With common time
+    #   position = HeadMusic::Time::MusicalPosition.new(1, 1, 0, 0)
+    #   meter = HeadMusic::Rudiment::Meter.common_time
+    #   event = HeadMusic::Time::MeterEvent.new(position, meter)
+    class MeterEvent
+      # @return [MusicalPosition] the position where this meter change occurs
+      attr_accessor :position
+
+      # @return [HeadMusic::Rudiment::Meter, String] the meter (time signature)
+      attr_accessor :meter
+
+      # Create a new meter change event
+      #
+      # @param position [MusicalPosition] where the meter change occurs
+      # @param meter [HeadMusic::Rudiment::Meter, String] the new meter
+      def initialize(position, meter)
+        @position = position
+        @meter = meter
+      end
+    end
+  end
+end