musa-dsl 0.30.2 → 0.40.0

data/lib/musa-dsl/sequencer/base-sequencer-tick-based.rb

@@ -1,11 +1,104 @@
 module Musa
   module Sequencer
     class BaseSequencer
+      # Tick-based timing implementation for BaseSequencer.
+      #
+      # TickBasedTiming provides quantized time progression where time advances
+      # in discrete tick increments. Musical time is divided into bars, beats,
+      # and ticks, with position rounded to the nearest tick boundary. This
+      # provides a traditional sequencer timing model similar to DAWs and MIDI
+      # sequencers.
+      #
+      # ## Tick-Based Time Model
+      #
+      # Time is quantized to a grid determined by:
+      #
+      # - **beats_per_bar**: Time signature numerator (e.g., 4 for 4/4)
+      # - **ticks_per_beat**: Subdivisions per beat (resolution)
+      # - **ticks_per_bar**: Total ticks = beats_per_bar × ticks_per_beat
+      # - **tick_duration**: 1 / ticks_per_bar (Rational)
+      #
+      # Position always aligns to tick boundaries. Non-aligned positions are
+      # rounded with a warning.
+      #
+      # ## Time Progression
+      #
+      # - **Forward only**: Position cannot decrease (enforced)
+      # - **Tick advancement**: {#tick} increments by tick_duration
+      # - **Fast-forward**: {#position=} jumps to future position
+      # - **Quantization**: All positions rounded to tick grid
+      #
+      # ## Fast-Forward Mechanism
+      #
+      # When jumping forward via `position=`:
+      # 1. Triggers on_fast_forward callbacks with `true`
+      # 2. Ticks forward until reaching target position
+      # 3. Triggers on_fast_forward callbacks with `false`
+      # 4. Allows event handlers to skip/optimize during jumps
+      #
+      # ## Musical Applications
+      #
+      # - Traditional MIDI sequencing with quantized timing
+      # - Grid-aligned rhythmic patterns
+      # - Time signature-based composition (4/4, 3/4, etc.)
+      # - Tick-precise event scheduling
+      #
+      # @example Creating tick-based sequencer (4/4, 96 ticks per beat)
+      #   sequencer = BaseSequencer.new(4, 96)  # 4 beats, 96 ticks/beat
+      #   sequencer.ticks_per_bar  # => 384r
+      #   sequencer.tick_duration  # => 1/384r
+      #   sequencer.position       # => 1r (start of bar 1)
+      #
+      # @example Advancing time with tick
+      #   sequencer.tick  # Advance one tick (1/384 of a bar)
+      #   sequencer.position  # => 385/384r
+      #
+      # @example Fast-forward to future position
+      #   sequencer.position = 2r  # Jump to bar 2
+      #   # Triggers on_fast_forward(true), ticks forward, on_fast_forward(false)
+      #
+      # @example Quantization warning
+      #   sequencer.at(1.5001r) { puts "event" }
+      #   # WARN: rounding position 1.5001 to tick precision: 1.5
+      #
+      # @api private
       module TickBasedTiming
         using Musa::Extension::InspectNice
 
-        attr_reader :position, :ticks_per_bar, :tick_duration
+        # Current playback position in bars (Rational).
+        #
+        # Always aligned to tick boundaries. Bar 1 starts at position 1r.
+        #
+        # @return [Rational] current position
+        attr_reader :position
 
+        # Total ticks per bar (beats_per_bar × ticks_per_beat).
+        #
+        # @return [Rational] ticks per bar
+        attr_reader :ticks_per_bar
+
+        # Duration of one tick in bars (1 / ticks_per_bar).
+        #
+        # @return [Rational] tick duration
+        attr_reader :tick_duration
+
+        # Advances sequencer by one tick.
+        #
+        # Increments position by tick_duration and executes all events
+        # scheduled at the new position. This is the primary time progression
+        # method for tick-based sequencers.
+        #
+        # If ticks are held (during fast-forward), accumulates ticks in buffer
+        # without executing events until released.
+        #
+        # @return [void]
+        #
+        # @example Normal tick progression
+        #   sequencer.position  # => 1r
+        #   sequencer.tick
+        #   sequencer.position  # => 385/384r (1 + 1/384)
+        #
+        # @api public
         def tick
           if @hold_public_ticks
             @hold_ticks += 1
@@ -14,6 +107,41 @@ module Musa
           end
         end
 
+        # Fast-forwards sequencer to new position.
+        #
+        # Jumps to a future position by ticking forward until reaching the
+        # target. Executes all scheduled events between current and target
+        # positions. Triggers on_fast_forward callbacks to allow handlers
+        # to optimize processing during the jump.
+        #
+        # Position can only move forward - attempting to move backward raises
+        # ArgumentError. Position is automatically quantized to tick boundaries.
+        #
+        # ## Fast-Forward Process
+        #
+        # 1. Validates new_position >= current position
+        # 2. Calls on_fast_forward callbacks with `true` (entering fast-forward)
+        # 3. Holds public tick accumulation
+        # 4. Ticks forward, executing events at each tick
+        # 5. Releases accumulated ticks
+        # 6. Calls on_fast_forward callbacks with `false` (exiting fast-forward)
+        #
+        # @param new_position [Rational] target position (must be >= current)
+        #
+        # @return [void]
+        #
+        # @raise [ArgumentError] if new_position < current position
+        #
+        # @example Jump to future bar
+        #   sequencer.position  # => 1r
+        #   sequencer.position = 5r  # Fast-forward to bar 5
+        #   # Executes all events from bar 1 to bar 5
+        #
+        # @example Cannot move backward
+        #   sequencer.position = 0r
+        #   # => ArgumentError: cannot move back
+        #
+        # @api public
         def position=(new_position)
           raise ArgumentError,
                 "Sequencer #{self}: cannot move back. current position: #{@position} new position: #{new_position}" \
@@ -28,6 +156,12 @@ module Musa
           _release_public_ticks
         end
 
+        # Initializes tick-based timing parameters.
+        #
+        # Calculates derived timing values from beats_per_bar and ticks_per_beat.
+        #
+        # @return [void]
+        # @api private
         private def _init_timing
           @ticks_per_bar = Rational(beats_per_bar * ticks_per_beat)
           @tick_duration = Rational(1, @ticks_per_bar)
@@ -36,10 +170,34 @@ module Musa
           @hold_ticks = 0
         end
 
+        # Resets position to start of first bar.
+        #
+        # Sets position to 1r + offset - tick_duration, so first tick brings
+        # position to 1r + offset (start of bar 1).
+        #
+        # @return [void]
+        # @api private
         private def _reset_timing
           @position = @position_mutex.synchronize { 1r + @offset - @tick_duration }
         end
 
+        # Quantizes position to nearest tick boundary.
+        #
+        # Rounds non-aligned positions to the tick grid, optionally logging
+        # a warning when rounding occurs. Ensures all positions align with
+        # tick_duration increments for consistent timing.
+        #
+        # @param position [Rational] position to quantize
+        # @param warn [Boolean] log warning if rounding occurs (default: true)
+        #
+        # @return [Rational] quantized position aligned to tick grid
+        #
+        # @example Quantization to tick boundaries
+        #   # With 384 ticks per bar, tick_duration = 1/384r
+        #   _quantize_position(1.5001r)  # => 1.5r (385/384 ticks)
+        #   # Logs warning: "rounding position 1.5001 to tick precision: 1.5"
+        #
+        # @api private
         private def _quantize_position(position, warn: true)
           ticks_position = position / @tick_duration
 
@@ -59,10 +217,24 @@ module Musa
           position
         end
 
+        # Holds tick accumulation during fast-forward.
+        #
+        # Prevents immediate tick execution, buffering ticks for batch release.
+        # Used during position= to collect ticks that occur during the jump.
+        #
+        # @return [void]
+        # @api private
         private def _hold_public_ticks
           @hold_public_ticks = true
         end
 
+        # Releases accumulated ticks after fast-forward.
+        #
+        # Executes all buffered ticks collected during hold period. Restores
+        # normal tick processing.
+        #
+        # @return [void]
+        # @api private
         private def _release_public_ticks
           @hold_ticks.times { _tick(@position_mutex.synchronize { @position += @tick_duration }) }
           @hold_ticks = 0

data/lib/musa-dsl/sequencer/base-sequencer-tickless-based.rb

@@ -1,14 +1,105 @@
 module Musa
   module Sequencer
     class BaseSequencer
+      # Tickless (continuous) timing implementation for BaseSequencer.
+      #
+      # TicklessBasedTiming provides continuous, non-quantized time progression
+      # where events can be scheduled at any Rational position without rounding
+      # to a tick grid. Time advances by jumping directly to the next scheduled
+      # event, enabling precise timing for complex musical structures and
+      # avoiding quantization artifacts.
+      #
+      # ## Tickless Time Model
+      #
+      # - **No quantization**: Positions are exact Rational values
+      # - **Event-driven**: Time jumps to next scheduled event
+      # - **Infinite resolution**: ticks_per_bar = Float::INFINITY
+      # - **Zero tick duration**: tick_duration = 0r
+      # - **Continuous time**: No discrete grid or rounding
+      #
+      # ## Time Progression
+      #
+      # Unlike tick-based mode that advances in fixed increments, tickless
+      # mode advances position directly to the next scheduled event. If events
+      # are at positions [1r, 1.25r, 1.5r, 2r], calling {#tick} jumps through
+      # these exact positions without intermediate steps.
+      #
+      # - **Forward only**: Position cannot decrease (enforced)
+      # - **Event jumping**: {#tick} moves to next scheduled position
+      # - **Fast-forward**: {#position=} executes events up to target
+      # - **No rounding**: Positions preserved exactly
+      #
+      # ## Comparison with Tick-Based Mode
+      #
+      # | Aspect | Tick-Based | Tickless |
+      # |--------|-----------|----------|
+      # | Time grid | Quantized to ticks | Continuous |
+      # | Resolution | ticks_per_beat | Infinite (Rational) |
+      # | Advancement | Fixed tick_duration | Jump to next event |
+      # | Rounding | Yes (with warning) | No |
+      # | Use case | Traditional sequencing | Complex timing, microtiming |
+      #
+      # ## Musical Applications
+      #
+      # - Complex polyrhythms without quantization loss
+      # - Precise microtiming and groove timing
+      # - Non-isochronous meters and irregular divisions
+      # - Algorithmic composition with exact ratios
+      # - Avoiding rounding errors in long sequences
+      #
+      # @example Creating tickless sequencer
+      #   sequencer = BaseSequencer.new  # No tick parameters
+      #   sequencer.ticks_per_bar   # => Float::INFINITY
+      #   sequencer.tick_duration   # => 0r
+      #   sequencer.position        # => nil (before first event)
+      #
+      # @example Precise timing without quantization
+      #   sequencer.at(1r) { puts "Event 1" }
+      #   sequencer.at(1 + 1/7r) { puts "Event 2" }  # Exact 1/7 division
+      #   sequencer.at(1 + 1/3r) { puts "Event 3" }  # Exact 1/3 division
+      #   sequencer.tick  # Jumps to 1r
+      #   sequencer.tick  # Jumps to 8/7r (1 + 1/7)
+      #   sequencer.tick  # Jumps to 4/3r (1 + 1/3)
+      #
+      # @example Complex polyrhythm (5 against 7)
+      #   require 'musa-dsl'
+      #
+      #   sequencer = Musa::Sequencer::BaseSequencer.new  # Tickless mode
+      #
+      #   7.times { |i| sequencer.at(1 + Rational(i, 7)) { puts "Note A at #{sequencer.position}" } }
+      #   5.times { |i| sequencer.at(1 + Rational(i, 5)) { puts "Note B at #{sequencer.position}" } }
+      #
+      #   sequencer.run  # Events at exact rational positions
+      #
+      # @api private
       module TicklessBasedTiming
 
+        # Current playback position in bars (Rational or nil).
+        #
+        # Position is nil before first event, then becomes the exact Rational
+        # position of the current event. No quantization or rounding occurs.
+        #
+        # @return [Rational, nil] current position or nil before first event
         attr_reader :position
 
+        # Returns infinite ticks per bar for tickless mode.
+        #
+        # Indicates unlimited timing resolution (no tick grid).
+        #
+        # @return [Float] Float::INFINITY
+        #
+        # @api public
         def ticks_per_bar
           Float::INFINITY
         end
 
+        # Returns zero tick duration for tickless mode.
+        #
+        # Indicates infinitesimal tick duration (continuous time).
+        #
+        # @return [Rational] 0r
+        #
+        # @api public
         def tick_duration
           0r
         end
@@ -19,6 +110,29 @@ module Musa
         # TODO tendría sentido sólo si también se usa con ticks temporizados, lo cual ocurriría si se reimplementa el modo tickbased
         # TODO a partir del modo tickless.
 
+        # Advances sequencer to next scheduled event.
+        #
+        # Jumps position directly to the next event in the timeslots, skipping
+        # any intermediate positions. Executes all handlers scheduled at that
+        # position. This is the primary time progression method for tickless
+        # sequencers.
+        #
+        # Unlike tick-based mode with fixed increments, tickless tick jumps to
+        # wherever the next event is scheduled, enabling precise event-driven
+        # timing without quantization.
+        #
+        # @return [void]
+        #
+        # @example Event-driven progression
+        #   sequencer.at(1r) { puts "A" }
+        #   sequencer.at(1.5r) { puts "B" }
+        #   sequencer.at(2r) { puts "C" }
+        #
+        #   sequencer.tick  # position becomes 1r, prints "A"
+        #   sequencer.tick  # position becomes 1.5r, prints "B"
+        #   sequencer.tick  # position becomes 2r, prints "C"
+        #
+        # @api public
         def tick
           _tick @position_mutex.synchronize { @position = @timeslots.first_after(@position) }
         end
@@ -29,6 +143,44 @@ module Musa
         # TODO Por otro lado cuando se cuantiza en _at se redondea al más cercano, mientras que el modelo basado en avanzar redondea siempre hacia arriba,
         # TODO pero esto podría resolverse con una opción de cuantización opcional que en _at ajustara la posición a la más cercana.
 
+        # Fast-forwards sequencer to new position.
+        #
+        # Jumps to a future position by executing all scheduled events between
+        # current and target positions. Triggers on_fast_forward callbacks to
+        # allow handlers to optimize processing during the jump.
+        #
+        # Position can only move forward - attempting to move backward raises
+        # ArgumentError. Unlike tick-based mode, no quantization occurs.
+        #
+        # ## Fast-Forward Process
+        #
+        # 1. Validates new_position >= current position
+        # 2. Calls on_fast_forward callbacks with `true` (entering fast-forward)
+        # 3. Executes all events at positions <= new_position
+        # 4. Sets position to new_position (exact, no rounding)
+        # 5. Calls on_fast_forward callbacks with `false` (exiting fast-forward)
+        #
+        # @param new_position [Rational] target position (must be >= current)
+        #
+        # @return [void]
+        #
+        # @raise [ArgumentError] if new_position < current position
+        #
+        # @example Jump to future position
+        #   sequencer.at(1.25r) { puts "Event 1" }
+        #   sequencer.at(1.5r) { puts "Event 2" }
+        #   sequencer.at(2.75r) { puts "Event 3" }
+        #
+        #   sequencer.position = 2r
+        #   # Executes events at 1.25r and 1.5r
+        #   # Position becomes exactly 2r (not 2.75r)
+        #
+        # @example Cannot move backward
+        #   sequencer.position = 1r
+        #   sequencer.tick  # position = 1.25r
+        #   sequencer.position = 1r  # => ArgumentError: cannot move back
+        #
+        # @api public
         def position=(new_position)
           raise ArgumentError, "Sequencer #{self}: cannot move back. current position: #{@position} new position: #{new_position}" if new_position < @position
 
@@ -53,13 +205,38 @@ module Musa
           @on_fast_forward.each { |block| block.call(false) }
         end
 
+        # Initializes tickless timing (no-op).
+        #
+        # Tickless mode requires no timing parameter calculation or setup.
+        #
+        # @return [void]
+        # @api private
         private def _init_timing
         end
 
+        # Resets position to nil (before first event).
+        #
+        # Sets position to nil, indicating sequencer has not yet reached any
+        # scheduled event. First tick will advance to first scheduled position.
+        #
+        # @return [void]
+        # @api private
         private def _reset_timing
           @position = nil
         end
 
+        # Returns position unchanged (no quantization).
+        #
+        # Tickless mode preserves exact Rational positions without rounding.
+        # The warn parameter is ignored (included for interface compatibility
+        # with tick-based mode).
+        #
+        # @param position [Rational] position to pass through
+        # @param warn [Boolean] ignored (for compatibility)
+        #
+        # @return [Rational] exact position unchanged
+        #
+        # @api private
         private def _quantize_position(position, warn: false)
           position
         end