head_music 9.0.1 → 11.1.0

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

data/lib/head_music/time/smpte_timecode.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+module HeadMusic
+  module Time
+    # Represents a SMPTE (Society of Motion Picture and Television Engineers) timecode
+    #
+    # SMPTE timecode is used for synchronizing audio and video in professional
+    # production. It represents time as HH:MM:SS:FF (hours:minutes:seconds:frames).
+    #
+    # The framerate determines how many frames occur per second. Common framerates:
+    # - 24 fps: Film standard
+    # - 25 fps: PAL video standard (Europe)
+    # - 30 fps: NTSC video standard (North America)
+    # - 29.97 fps: NTSC drop-frame
+    #
+    # @example Creating a timecode at 1 hour
+    #   timecode = HeadMusic::Time::SmpteTimecode.new(1, 0, 0, 0)
+    #   timecode.to_s # => "01:00:00:00"
+    #
+    # @example Parsing from a string
+    #   timecode = HeadMusic::Time::SmpteTimecode.parse("02:30:45:15")
+    #   timecode.hour # => 2
+    #   timecode.minute # => 30
+    #
+    # @example Normalizing with overflow
+    #   timecode = HeadMusic::Time::SmpteTimecode.new(0, 0, 0, 60, framerate: 30)
+    #   timecode.normalize!
+    #   timecode.to_s # => "00:00:02:00" (frames carried into seconds)
+    #
+    # @example Comparing timecodes
+    #   tc1 = HeadMusic::Time::SmpteTimecode.new(1, 0, 0, 0)
+    #   tc2 = HeadMusic::Time::SmpteTimecode.new(1, 30, 0, 0)
+    #   tc1 < tc2 # => true
+    class SmpteTimecode
+      include Comparable
+
+      # @return [Integer] the hour component
+      attr_reader :hour
+
+      # @return [Integer] the minute component
+      attr_reader :minute
+
+      # @return [Integer] the second component
+      attr_reader :second
+
+      # @return [Integer] the frame component
+      attr_reader :frame
+
+      # @return [Integer] frames per second (default: 30 for NTSC)
+      attr_reader :framerate
+
+      # Default framerate (30 fps NTSC)
+      DEFAULT_FRAMERATE = 30
+
+      # Seconds per minute
+      SECONDS_PER_MINUTE = 60
+
+      # Minutes per hour
+      MINUTES_PER_HOUR = 60
+
+      # Parse a timecode from a string representation
+      #
+      # @param identifier [String] timecode in "HH:MM:SS:FF" format
+      # @return [SmpteTimecode] the parsed timecode
+      # @example
+      #   SmpteTimecode.parse("02:30:45:15")
+      def self.parse(identifier)
+        new(*identifier.scan(/\d+/)[0..3])
+      end
+
+      # Create a new SMPTE timecode
+      #
+      # @param hour [Integer, String] the hour component (default: 0)
+      # @param minute [Integer, String] the minute component (default: 0)
+      # @param second [Integer, String] the second component (default: 0)
+      # @param frame [Integer, String] the frame component (default: 0)
+      # @param framerate [Integer] frames per second (default: 30)
+      def initialize(hour = 0, minute = 0, second = 0, frame = 0, framerate: DEFAULT_FRAMERATE)
+        @hour = hour.to_i
+        @minute = minute.to_i
+        @second = second.to_i
+        @frame = frame.to_i
+        @framerate = framerate
+        @total_frames = nil
+      end
+
+      # Convert timecode to array format
+      #
+      # @return [Array<Integer>] [hour, minute, second, frame]
+      def to_a
+        [hour, minute, second, frame]
+      end
+
+      # Convert timecode to string format with zero padding
+      #
+      # @return [String] timecode in "HH:MM:SS:FF" format
+      def to_s
+        format("%02d:%02d:%02d:%02d", hour, minute, second, frame)
+      end
+
+      # Normalize the timecode, handling overflow and underflow
+      #
+      # This method modifies the timecode in place, carrying excess values
+      # from lower levels to higher levels (frames → seconds → minutes → hours).
+      # Also handles negative values by borrowing from higher levels.
+      #
+      # @return [self] returns self for method chaining
+      # @example
+      #   timecode = SmpteTimecode.new(0, 0, 0, 60, framerate: 30)
+      #   timecode.normalize! # => "00:00:02:00"
+      def normalize!
+        @total_frames = nil # Invalidate cached value
+
+        # Carry frames into seconds
+        if frame >= framerate || frame.negative?
+          second_delta, @frame = frame.divmod(framerate)
+          @second += second_delta
+        end
+
+        # Carry seconds into minutes
+        if second >= SECONDS_PER_MINUTE || second.negative?
+          minute_delta, @second = second.divmod(SECONDS_PER_MINUTE)
+          @minute += minute_delta
+        end
+
+        # Carry minutes into hours
+        if minute >= MINUTES_PER_HOUR || minute.negative?
+          hour_delta, @minute = minute.divmod(MINUTES_PER_HOUR)
+          @hour += hour_delta
+        end
+
+        self
+      end
+
+      # Compare this timecode to another
+      #
+      # @param other [SmpteTimecode] another timecode to compare
+      # @return [Integer] -1 if less than, 0 if equal, 1 if greater than
+      def <=>(other)
+        to_total_frames <=> other.to_total_frames
+      end
+
+      # Convert timecode to total frames from the beginning
+      #
+      # @return [Integer] total frames
+      def to_total_frames
+        return @total_frames if @total_frames
+
+        total = 0
+        total += hour * MINUTES_PER_HOUR * SECONDS_PER_MINUTE * framerate
+        total += minute * SECONDS_PER_MINUTE * framerate
+        total += second * framerate
+        total += frame
+
+        @total_frames = total
+      end
+
+      protected
+
+      # Allow other SmpteTimecode instances to access this method for comparison
+      alias_method :to_i, :to_total_frames
+    end
+  end
+end

data/lib/head_music/time/tempo_event.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module HeadMusic
+  module Time
+    # Represents a tempo change at a specific musical position
+    #
+    # TempoEvent marks a point in a musical timeline where the tempo changes.
+    # This is essential for converting between clock time and musical position,
+    # as different tempos affect how long each beat takes in real time.
+    #
+    # @example Creating a tempo change to quarter = 120 at bar 1
+    #   position = HeadMusic::Time::MusicalPosition.new(1, 1, 0, 0)
+    #   event = HeadMusic::Time::TempoEvent.new(position, "quarter", 120)
+    #
+    # @example With a dotted quarter note tempo
+    #   position = HeadMusic::Time::MusicalPosition.new(5, 1, 0, 0)
+    #   event = HeadMusic::Time::TempoEvent.new(position, "dotted quarter", 92)
+    #
+    # @example With an eighth note tempo
+    #   position = HeadMusic::Time::MusicalPosition.new(10, 1, 0, 0)
+    #   event = HeadMusic::Time::TempoEvent.new(position, "eighth", 140)
+    class TempoEvent
+      # @return [MusicalPosition] the position where this tempo change occurs
+      attr_accessor :position
+
+      # @return [HeadMusic::Rudiment::Tempo] the tempo
+      attr_accessor :tempo
+
+      # Create a new tempo change event
+      #
+      # @param position [MusicalPosition] where the tempo change occurs
+      # @param beat_value [String] the rhythmic value that gets the beat (e.g., "quarter", "eighth")
+      # @param beats_per_minute [Numeric] the tempo in beats per minute
+      def initialize(position, beat_value, beats_per_minute)
+        @position = position
+        @tempo = HeadMusic::Rudiment::Tempo.new(beat_value, beats_per_minute)
+      end
+    end
+  end
+end