head_music 8.3.0 → 11.0.0

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

data/lib/head_music/time/meter_map.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+module HeadMusic
+  module Time
+    # Manages meter (time signature) changes along a musical timeline
+    #
+    # A MeterMap maintains a sorted list of meter changes at specific musical
+    # positions, allowing you to determine which meter is active at any point
+    # and iterate through meter segments for musical position calculations.
+    #
+    # This is essential for normalizing musical positions when the meter changes
+    # during a composition.
+    #
+    # @example Basic usage
+    #   meter_map = HeadMusic::Time::MeterMap.new
+    #   meter_map.add_change(MusicalPosition.new(5, 1, 0, 0), "3/4")
+    #   meter_map.add_change(MusicalPosition.new(9, 1, 0, 0), "6/8")
+    #
+    #   meter = meter_map.meter_at(MusicalPosition.new(7, 1, 0, 0))
+    #   meter.to_s # => "3/4"
+    #
+    # @example Iterating through segments
+    #   from = MusicalPosition.new(1, 1, 0, 0)
+    #   to = MusicalPosition.new(10, 1, 0, 0)
+    #   meter_map.each_segment(from, to) do |start_pos, end_pos, meter|
+    #     # Process each meter segment
+    #   end
+    class MeterMap
+      # @return [Array<MeterEvent>] all meter events in chronological order
+      attr_reader :events
+
+      # Create a new meter map
+      #
+      # @param starting_meter [HeadMusic::Rudiment::Meter, String] initial meter (default: 4/4)
+      # @param starting_position [MusicalPosition] where the initial meter begins (default: 1:1:0:0)
+      def initialize(starting_meter: nil, starting_position: nil)
+        starting_meter = HeadMusic::Rudiment::Meter.get(starting_meter || "4/4")
+        starting_position ||= MusicalPosition.new
+        @events = [MeterEvent.new(starting_position, starting_meter)]
+      end
+
+      # Add a meter change at the specified position
+      #
+      # If a meter change already exists at this position, it will be replaced.
+      # Events are automatically maintained in sorted order.
+      #
+      # @param position [MusicalPosition] where the meter change occurs
+      # @param meter_or_identifier [String, HeadMusic::Rudiment::Meter] either a meter string like "3/4" or a Meter object
+      # @return [MeterEvent] the created event
+      def add_change(position, meter_or_identifier)
+        # Remove any existing event at this position (except the first)
+        remove_change(position)
+
+        # Create the new event
+        meter = meter_or_identifier.is_a?(HeadMusic::Rudiment::Meter) ? meter_or_identifier : HeadMusic::Rudiment::Meter.get(meter_or_identifier)
+        event = MeterEvent.new(position, meter)
+
+        @events << event
+        sort_events!
+        event
+      end
+
+      # Remove a meter change at the specified position
+      #
+      # The starting meter (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 meter changes except the starting meter
+      #
+      # @return [void]
+      def clear_changes
+        @events = [@events.first]
+      end
+
+      # Find the meter active at a given position
+      #
+      # Returns the meter from the most recent meter event at or before
+      # the specified position.
+      #
+      # @param position [MusicalPosition] the position to query
+      # @return [HeadMusic::Rudiment::Meter] the active meter
+      def meter_at(position)
+        # Find the last event at or before this position
+        # We need to compare positions carefully since they might not be normalized
+        active_event = @events.reverse.find do |event|
+          compare_positions(event.position, position) <= 0
+        end
+
+        active_event&.meter || @events.first.meter
+      end
+
+      # Iterate through meter segments between two positions
+      #
+      # Yields each segment with its start position, end position, and meter.
+      # Segments are created wherever a meter 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, meter] for each segment
+      # @yieldparam start_position [MusicalPosition] segment start
+      # @yieldparam end_position [MusicalPosition] segment end
+      # @yieldparam meter [HeadMusic::Rudiment::Meter] active meter
+      # @return [void]
+      def each_segment(from_position, to_position)
+        # Find events that affect this range
+        relevant_events = @events.select do |event|
+          compare_positions(event.position, to_position) < 0
+        end
+
+        # Start with the meter active at from_position
+        current_pos = from_position
+        current_meter = meter_at(from_position)
+
+        # Iterate through relevant events
+        relevant_events.each do |event|
+          # Skip events before our starting position
+          next if compare_positions(event.position, from_position) <= 0
+
+          # Yield the segment up to this event
+          yield current_pos, event.position, current_meter
+
+          # Move to next segment
+          current_pos = event.position
+          current_meter = event.meter
+        end
+
+        # Yield the final segment to the end position
+        yield current_pos, to_position, current_meter
+      end
+
+      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
+
+      # Compare two positions
+      #
+      # @param pos1 [MusicalPosition] first position
+      # @param pos2 [MusicalPosition] second position
+      # @return [Integer] -1, 0, or 1
+      def compare_positions(pos1, pos2)
+        [pos1.bar, pos1.beat, pos1.tick, pos1.subtick] <=>
+          [pos2.bar, pos2.beat, pos2.tick, pos2.subtick]
+      end
+    end
+  end
+end

data/lib/head_music/time/musical_position.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+module HeadMusic
+  module Time
+    # Representation of a musical position in bars:beats:ticks:subticks notation
+    #
+    # A MusicalPosition represents a point in musical time using a hierarchical
+    # structure:
+    # - bar: the measure number (1-indexed)
+    # - beat: the beat within the bar (1-indexed)
+    # - tick: subdivision of a beat (0-indexed, 960 ticks per quarter note)
+    # - subtick: finest resolution (0-indexed, 240 subticks per tick)
+    #
+    # The position can be normalized according to a meter, which handles
+    # overflow by carrying excess values to higher levels (e.g., excess ticks
+    # become beats, excess beats become bars).
+    #
+    # @example Creating a position at bar 1, beat 1
+    #   position = HeadMusic::Time::MusicalPosition.new
+    #   position.to_s # => "1:1:0:0"
+    #
+    # @example Parsing from a string
+    #   position = HeadMusic::Time::MusicalPosition.parse("2:3:480:0")
+    #   position.bar # => 2
+    #   position.beat # => 3
+    #
+    # @example Normalizing with overflow
+    #   meter = HeadMusic::Rudiment::Meter.get("4/4")
+    #   position = HeadMusic::Time::MusicalPosition.new(1, 1, 960, 0)
+    #   position.normalize!(meter)
+    #   position.to_s # => "1:2:0:0" (ticks carried into beats)
+    #
+    # @example Comparing positions
+    #   pos1 = HeadMusic::Time::MusicalPosition.new(1, 1, 0, 0)
+    #   pos2 = HeadMusic::Time::MusicalPosition.new(1, 2, 0, 0)
+    #   meter = HeadMusic::Rudiment::Meter.get("4/4")
+    #   pos1.normalize!(meter)
+    #   pos2.normalize!(meter)
+    #   pos1 < pos2 # => true
+    class MusicalPosition
+      include Comparable
+
+      # @return [Integer] the bar (measure) number (1-indexed)
+      attr_reader :bar
+
+      # @return [Integer] the beat within the bar (1-indexed)
+      attr_reader :beat
+
+      # @return [Integer] the tick within the beat (0-indexed)
+      attr_reader :tick
+
+      # @return [Integer] the subtick within the tick (0-indexed)
+      attr_reader :subtick
+
+      # Default starting bar number
+      DEFAULT_FIRST_BAR = 1
+
+      # First beat in a bar
+      FIRST_BEAT = 1
+
+      # First tick in a beat
+      FIRST_TICK = 0
+
+      # First subtick in a tick
+      FIRST_SUBTICK = 0
+
+      # Parse a position from a string representation
+      #
+      # @param identifier [String] position in "bar:beat:tick:subtick" format
+      # @return [MusicalPosition] the parsed position
+      # @example
+      #   MusicalPosition.parse("2:3:480:120")
+      def self.parse(identifier)
+        new(*identifier.scan(/\d+/)[0..3])
+      end
+
+      # Create a new musical position
+      #
+      # @param bar [Integer, String] the bar number (default: 1)
+      # @param beat [Integer, String] the beat number (default: 1)
+      # @param tick [Integer, String] the tick number (default: 0)
+      # @param subtick [Integer, String] the subtick number (default: 0)
+      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
+        @meter = nil
+        @total_subticks = nil
+      end
+
+      # Convert position to array format
+      #
+      # @return [Array<Integer>] [bar, beat, tick, subtick]
+      def to_a
+        [bar, beat, tick, subtick]
+      end
+
+      # Convert position to string format
+      #
+      # @return [String] position in "bar:beat:tick:subtick" format
+      def to_s
+        "#{bar}:#{beat}:#{tick}:#{subtick}"
+      end
+
+      # Normalize the position according to a meter, handling overflow
+      #
+      # This method modifies the position in place, carrying excess values
+      # from lower levels to higher levels (subticks → ticks → beats → bars).
+      # Also handles negative values by borrowing from higher levels.
+      #
+      # @param meter [HeadMusic::Rudiment::Meter, nil] the meter to use for normalization
+      # @return [self] returns self for method chaining
+      # @example
+      #   meter = HeadMusic::Rudiment::Meter.get("4/4")
+      #   position = MusicalPosition.new(1, 1, 960, 240)
+      #   position.normalize!(meter) # => "1:2:1:0"
+      def normalize!(meter)
+        return self unless meter
+
+        @meter = meter
+        @total_subticks = nil # Invalidate cached value
+
+        # 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
+
+      # Compare this position to another
+      #
+      # Note: For accurate comparison, both positions should be normalized
+      # with the same meter first.
+      #
+      # @param other [MusicalPosition] another position to compare
+      # @return [Integer] -1 if less than, 0 if equal, 1 if greater than
+      def <=>(other)
+        to_total_subticks <=> other.to_total_subticks
+      end
+
+      # Convert position to total subticks for comparison and calculation
+      #
+      # @return [Integer] total subticks from the beginning
+      # @note This calculation assumes the position has been normalized
+      def to_total_subticks
+        return @total_subticks if @total_subticks
+
+        # Calculate based on the structure
+        # Note: This is a simplified calculation that assumes consistent meter
+        ticks_per_count = @meter&.ticks_per_count || HeadMusic::Time::PPQN
+        counts_per_bar = @meter&.counts_per_bar || 4
+
+        total = 0
+        total += (bar - 1) * counts_per_bar * ticks_per_count * HeadMusic::Time::SUBTICKS_PER_TICK
+        total += (beat - 1) * ticks_per_count * HeadMusic::Time::SUBTICKS_PER_TICK
+        total += tick * HeadMusic::Time::SUBTICKS_PER_TICK
+        total += subtick
+
+        @total_subticks = total
+      end
+
+      protected
+
+      # Allow other MusicalPosition instances to access this method for comparison
+      alias_method :to_i, :to_total_subticks
+    end
+  end
+end