musa-dsl 0.30.2 → 0.40.0

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

@@ -11,13 +11,167 @@ require_relative 'base-sequencer-tickless-based'
 
 module Musa
   module Sequencer
+    # Musical sequencer and scheduler system.
+    #
+    # Sequencer provides precise timing and scheduling for musical events,
+    # supporting both tick-based (quantized) and tickless (continuous) timing
+    # modes. Events are scheduled with musical time units (bars, beats, ticks)
+    # and executed sequentially.
+    #
+    # ## Core Concepts
+    #
+    # - **Position**: Current playback position in beats
+    # - **Timeslots**: Scheduled events indexed by time
+    # - **Timing Modes**:
+    #
+    #   - **Tick-based**: Quantized to beats_per_bar × ticks_per_beat grid
+    #   - **Tickless**: Continuous rational time (no quantization)
+    #
+    # - **Scheduling Methods**:
+    #
+    #   - `at`: Schedule block at absolute position
+    #   - `wait`: Schedule relative to current position
+    #   - `play`: Play series over time
+    #   - `every`: Repeat at intervals
+    #   - `move`: Animate value over time
+    #
+    # - **Event Handlers**: Hierarchical event pub/sub system
+    # - **Controls**: Objects returned by scheduling methods for lifecycle management
+    #
+    # ## Tick-based vs Tickless
+    #
+    # **Tick-based** (beats_per_bar and ticks_per_beat specified):
+    #
+    # - Positions quantized to tick grid
+    # - `tick` method advances by one tick
+    # - Suitable for MIDI-like discrete timing
+    # - Example: `BaseSequencer.new(4, 24)` → 4/4 time, 24 ticks per beat
+    #
+    # **Tickless** (no timing parameters):
+    #
+    # - Continuous rational time
+    # - `tick(position)` jumps to arbitrary position
+    # - Suitable for score-like continuous timing
+    # - Example: `BaseSequencer.new` → tickless mode
+    #
+    # ## Musical Time Units
+    #
+    # - **Bar**: Musical measure (defaults to 1.0 in value)
+    # - **Beat**: Subdivision of bar (e.g., quarter note in 4/4)
+    # - **Tick**: Smallest time quantum in tick-based mode
+    # - All times are Rational for precision
+    #
+    # @example Basic tick-based sequencer
+    #   seq = Musa::Sequencer::BaseSequencer.new(4, 24)  # 4/4, 24 ticks/beat
+    #
+    #   seq.at(1) { puts "Beat 1" }
+    #   seq.at(2) { puts "Beat 2" }
+    #   seq.at(3.5) { puts "Beat 3.5" }
+    #
+    #   seq.run  # Executes all scheduled events
+    #
+    # @example Tickless sequencer
+    #   seq = Musa::Sequencer::BaseSequencer.new  # Tickless mode
+    #
+    #   seq.at(1) { puts "Position 1" }
+    #   seq.at(1.5) { puts "Position 1.5" }
+    #
+    #   seq.tick(1)    # Jumps to position 1
+    #   seq.tick(1.5)  # Jumps to position 1.5
+    #
+    # @example Playing series
+    #   seq = Musa::Sequencer::BaseSequencer.new(4, 24)
+    #
+    #   pitches = Musa::Series::S(60, 62, 64, 65, 67)
+    #   durations = Musa::Series::S(1, 1, 0.5, 0.5, 2)
+    #   played_notes = []
+    #
+    #   seq.play(pitches.zip(durations)) do |pitch, duration|
+    #     played_notes << { pitch: pitch, duration: duration, position: seq.position }
+    #   end
+    #
+    #   seq.run
+    #   # Result: played_notes contains [{pitch: 60, duration: 1, position: 0}, ...]
+    #
+    # @example Every and move
+    #   seq = Musa::Sequencer::BaseSequencer.new(4, 24)
+    #
+    #   tick_positions = []
+    #   volume_values = []
+    #
+    #   # Execute every beat
+    #   seq.every(1, till: 8) { tick_positions << seq.position }
+    #
+    #   # Animate value from 0 to 127 over 4 beats
+    #   seq.move(every: 1/4r, from: 0, to: 127, duration: 4) do |value|
+    #     volume_values << value.round
+    #   end
+    #
+    #   seq.run
+    #   # Result: tick_positions = [0, 1, 2, 3, 4, 5, 6, 7]
+    #   # Result: volume_values = [0, 8, 16, ..., 119, 127]
+    #
+    # @api public
     class BaseSequencer
-      attr_reader :beats_per_bar, :ticks_per_beat
+      # @return [Rational, nil] beats per bar (tick-based mode only)
+      attr_reader :beats_per_bar
+
+      # @return [Rational, nil] ticks per beat (tick-based mode only)
+      attr_reader :ticks_per_beat
+
+      # @return [Rational] time offset for position calculations
       attr_reader :offset
+
+      # @return [Rational] current running position
       attr_reader :running_position
-      attr_reader :everying, :playing, :moving
+
+      # @return [Array<EveryControl>] active every loops
+      attr_reader :everying
+
+      # @return [Array<PlayControl, PlayTimedControl>] active play operations
+      attr_reader :playing
+
+      # @return [Array<MoveControl>] active move operations
+      attr_reader :moving
+
+      # @return [Musa::Logger::Logger] sequencer logger
       attr_reader :logger
 
+      # Creates sequencer with timing configuration.
+      #
+      # ## Timing Modes
+      #
+      # **Tick-based**: Provide both beats_per_bar and ticks_per_beat
+      #
+      # - Position quantized to tick grid
+      # - `tick` advances by one tick
+      #
+      # **Tickless**: Omit beats_per_bar and ticks_per_beat
+      #
+      # - Continuous rational time
+      # - `tick` advances to next scheduled position (without timing quantization)
+      #
+      # @param beats_per_bar [Numeric, nil] beats per bar (nil for tickless)
+      # @param ticks_per_beat [Numeric, nil] ticks per beat (nil for tickless)
+      # @param offset [Rational, nil] starting position offset
+      # @param logger [Musa::Logger::Logger, nil] custom logger
+      # @param do_log [Boolean, nil] enable debug logging
+      # @param do_error_log [Boolean, nil] enable error logging
+      # @param log_position_format [Proc, nil] custom position formatter for logs
+      #
+      # @raise [ArgumentError] if only one of beats_per_bar/ticks_per_beat provided
+      #
+      # @example Tick-based 4/4 time
+      #   seq = BaseSequencer.new(4, 24)
+      #
+      # @example Tick-based 3/4 time
+      #   seq = BaseSequencer.new(3, 24)
+      #
+      # @example Tickless mode
+      #   seq = BaseSequencer.new
+      #
+      # @example With offset
+      #   seq = BaseSequencer.new(4, 24, offset: 10r)
       def initialize(beats_per_bar = nil, ticks_per_beat = nil,
                      offset: nil,
                      logger: nil,
@@ -68,6 +222,30 @@ module Musa
         reset
       end
 
+      # Resets sequencer to initial state.
+      #
+      # Clears all scheduled events, active operations, and event handlers.
+      # Resets timing to start position.
+      #
+      # @return [void]
+      #
+      # @example Resetting sequencer state
+      #   seq = Musa::Sequencer::BaseSequencer.new(4, 24)
+      #
+      #   # Schedule some events
+      #   seq.at(1) { puts "Event 1" }
+      #   seq.at(2) { puts "Event 2" }
+      #   seq.every(1, till: 8) { puts "Repeating" }
+      #
+      #   puts seq.size  # => 2 (scheduled events)
+      #   puts seq.empty?  # => false
+      #
+      #   # Reset clears everything
+      #   seq.reset
+      #
+      #   puts seq.size  # => 0
+      #   puts seq.empty?  # => true
+      #   puts seq.position  # => 0
       def reset
         @timeslots.clear
         @everying.clear
@@ -79,51 +257,278 @@ module Musa
         _reset_timing
       end
 
+      # Counts total scheduled events.
+      #
+      # @return [Integer] number of scheduled events across all timeslots
       def size
         @timeslots.values.sum(&:size)
       end
 
+      # Checks if sequencer has no scheduled events.
+      #
+      # @return [Boolean] true if no events scheduled
       def empty?
         @timeslots.empty?
       end
 
+      # Quantizes position to tick grid (tick-based mode only).
+      #
+      # @param position [Rational] position to quantize
+      # @param warn [Boolean] emit warning if quantization changes value
+      #
+      # @return [Rational] quantized position
       def quantize_position(position, warn: nil)
         warn ||= false
         _quantize_position(position, warn: warn)
       end
 
+      # Executes all scheduled events until empty.
+      #
+      # Advances time tick by tick (or position by position in tickless mode)
+      # until no events remain.
+      #
+      # @return [void]
+      #
+      # @example
+      #   seq.at(1) { puts "Event 1" }
+      #   seq.at(2) { puts "Event 2" }
+      #   seq.run  # Executes both events
       def run
         tick until empty?
       end
 
+      # Returns current event handler.
+      #
+      # @return [EventHandler] active event handler
+      # @api private
       def event_handler
         @event_handlers.last
       end
 
+      # Registers debug callback for scheduled events.
+      #
+      # Callback is invoked when debug logging is enabled (see do_log parameter in
+      # initialize). Called before executing each scheduled event, allowing inspection
+      # of sequencer state at event execution time.
+      #
+      # @yield debug callback (receives no parameters)
+      # @return [void]
+      #
+      # @example Monitoring event execution
+      #   seq = Musa::Sequencer::BaseSequencer.new(4, 24, do_log: true)
+      #
+      #   debug_calls = []
+      #
+      #   seq.on_debug_at do
+      #     debug_calls << { position: seq.position, time: Time.now }
+      #   end
+      #
+      #   seq.at(1) { puts "Event 1" }
+      #   seq.at(2) { puts "Event 2" }
+      #
+      #   seq.run
+      #
+      #   # debug_calls now contains [{position: 1, time: ...}, {position: 2, time: ...}]
       def on_debug_at(&block)
         @on_debug_at << Musa::Extension::SmartProcBinder::SmartProcBinder.new(block)
       end
 
+      # Registers error callback.
+      #
+      # Callback is invoked when an error occurs during event execution. The error
+      # is logged and passed to all registered error handlers. Handlers receive the
+      # exception object and can process or report it.
+      #
+      # @yield [error] error callback receiving the exception object
+      # @yieldparam error [StandardError, ScriptError] the exception that occurred
+      # @return [void]
+      #
+      # @example Handling errors in scheduled events
+      #   seq = Musa::Sequencer::BaseSequencer.new(4, 24, do_error_log: false)
+      #
+      #   errors = []
+      #
+      #   seq.on_error do |error|
+      #     errors << { message: error.message, position: seq.position }
+      #   end
+      #
+      #   seq.at(1) { puts "Normal event" }
+      #   seq.at(2) { raise "Something went wrong!" }
+      #   seq.at(3) { puts "This still executes" }
+      #
+      #   seq.run
+      #
+      #   # errors now contains [{message: "Something went wrong!", position: 2}]
+      #   # All events execute despite the error at position 2
       def on_error(&block)
         @on_error << Musa::Extension::SmartProcBinder::SmartProcBinder.new(block)
       end
 
+      # Registers fast-forward callback (when jumping over events).
+      #
+      # Callback is invoked when position is changed directly (via position=), causing
+      # the sequencer to skip ahead. Called twice: once with true when fast-forward
+      # begins, and once with false when it completes. Events between old and new
+      # positions are executed during fast-forward.
+      #
+      # @yield [is_starting] callback receiving fast-forward state
+      # @yieldparam is_starting [Boolean] true when fast-forward begins, false when it ends
+      # @return [void]
+      #
+      # @example Tracking fast-forward operations
+      #   seq = Musa::Sequencer::BaseSequencer.new(4, 24)
+      #
+      #   ff_state = []
+      #
+      #   seq.on_fast_forward do |is_starting|
+      #     if is_starting
+      #       ff_state << "Fast-forward started from position #{seq.position}"
+      #     else
+      #       ff_state << "Fast-forward ended at position #{seq.position}"
+      #     end
+      #   end
+      #
+      #   seq.at(1) { puts "Event 1" }
+      #   seq.at(5) { puts "Event 5" }
+      #
+      #   # Jump to position 10 (executes events at 1 and 5 during fast-forward)
+      #   seq.position = 10
+      #
+      #   # ff_state contains ["Fast-forward started from position 0", "Fast-forward ended at position 10"]
       def on_fast_forward(&block)
         @on_fast_forward << Musa::Extension::SmartProcBinder::SmartProcBinder.new(block)
       end
 
+      # Registers callback executed before each tick.
+      #
+      # Callback is invoked before processing events at each position. Useful for
+      # logging, metrics collection, or performing pre-tick setup. Receives the
+      # position about to be executed.
+      #
+      # @yield [position] callback receiving the upcoming position
+      # @yieldparam position [Rational] the position about to be processed
+      # @return [void]
+      #
+      # @example Logging tick positions
+      #   seq = Musa::Sequencer::BaseSequencer.new(4, 24)
+      #
+      #   tick_log = []
+      #
+      #   seq.before_tick do |position|
+      #     tick_log << position
+      #   end
+      #
+      #   seq.at(1) { puts "Event" }
+      #   seq.at(2) { puts "Event" }
+      #
+      #   seq.tick  # Executes position 1
+      #   seq.tick  # Advances position
+      #   seq.tick  # Executes position 2
+      #
+      #   # tick_log contains [1, 1 + 1/96r, 2, ...]
+      #
+      # @example Conditional event scheduling
+      #   seq = Musa::Sequencer::BaseSequencer.new(4, 24)
+      #
+      #   seq.before_tick do |position|
+      #     # Schedule event only on whole beats
+      #     if position == position.to_i
+      #       seq.now { puts "Beat #{position}" }
+      #     end
+      #   end
+      #
+      #   seq.at(5) { puts "Trigger" }  # Start the sequencer
+      #   seq.run
       def before_tick(&block)
         @before_tick << Musa::Extension::SmartProcBinder::SmartProcBinder.new(block)
       end
 
+      # Subscribes to custom event.
+      #
+      # Registers a handler for custom events in the sequencer's pub/sub system.
+      # Events can be launched from scheduled blocks and handled at the sequencer
+      # level or at specific control levels. Supports hierarchical event delegation.
+      #
+      # @param event [Symbol] event name
+      # @yield [*args] event handler receiving event parameters
+      # @return [void]
+      #
+      # @example Basic event pub/sub
+      #   seq = Musa::Sequencer::BaseSequencer.new(4, 24)
+      #
+      #   received_values = []
+      #
+      #   # Subscribe to custom event
+      #   seq.on(:note_played) do |pitch, velocity|
+      #     received_values << { pitch: pitch, velocity: velocity }
+      #   end
+      #
+      #   # Launch event from scheduled block
+      #   seq.at(1) do
+      #     seq.launch(:note_played, 60, 100)
+      #   end
+      #
+      #   seq.at(2) do
+      #     seq.launch(:note_played, 64, 80)
+      #   end
+      #
+      #   seq.run
+      #
+      #   # received_values contains [{pitch: 60, velocity: 100}, {pitch: 64, velocity: 80}]
+      #
+      # @example Hierarchical event handling with control
+      #   seq = Musa::Sequencer::BaseSequencer.new(4, 24)
+      #
+      #   global_events = []
+      #   local_events = []
+      #
+      #   # Global handler (sequencer level)
+      #   seq.on(:finished) do |name|
+      #     global_events << name
+      #   end
+      #
+      #   # Local handler (control level)
+      #   control = seq.at(1) do |control:|
+      #     control.launch(:finished, "local task")
+      #   end
+      #
+      #   control.on(:finished) do |name|
+      #     local_events << name
+      #   end
+      #
+      #   seq.run
+      #
+      #   # local_events contains ["local task"]
+      #   # global_events is empty (event handled locally, doesn't bubble up)
       def on(event, &block)
         @event_handlers.last.on event, &block
       end
 
+      # Launches custom event.
+      #
+      # Publishes a custom event to registered handlers. Events bubble up through
+      # the handler hierarchy if not handled locally. Supports both positional and
+      # keyword parameters.
+      #
+      # @param event [Symbol] event name
+      # @param value_parameters [Array] positional parameters
+      # @param key_parameters [Hash] keyword parameters
+      # @return [void]
+      #
+      # @see #on
       def launch(event, *value_parameters, **key_parameters)
         @event_handlers.last.launch event, *value_parameters, **key_parameters
       end
 
+      # Schedules block relative to current position.
+      #
+      # @param bars_delay [Numeric, Series, Array] delay from current position
+      # @param debug [Boolean] enable debug logging
+      # @yield block to execute at position + delay
+      # @return [EventHandler] control object
+      #
+      # @example
+      #   seq.wait(2) { puts "2 beats later" }
       def wait(bars_delay, debug: nil, &block)
         debug ||= false
 
@@ -144,6 +549,13 @@ module Musa
         control
       end
 
+      # Schedules block at current position (immediate execution on next tick).
+      #
+      # @yield block to execute at current position
+      # @return [EventHandler] control object
+      #
+      # @example
+      #   seq.now { puts "Executes now" }
       def now(&block)
         control = EventHandler.new @event_handlers.last
         @event_handlers.push control
@@ -155,12 +567,31 @@ module Musa
         control
       end
 
+      # Schedules block at absolute position (low-level, no control object).
+      #
+      # @param bar_position [Numeric] absolute position
+      # @param force_first [Boolean] force execution before other events at same time
+      # @yield block to execute
+      # @return [nil]
+      # @api private
       def raw_at(bar_position, force_first: nil, &block)
         _raw_numeric_at bar_position.rationalize, force_first: force_first, &block
 
         nil
       end
 
+      # Schedules block at absolute position.
+      #
+      # @param bar_position [Numeric, Series, Array] absolute position(s)
+      # @param debug [Boolean] enable debug logging
+      # @yield block to execute at position
+      # @return [EventHandler] control object
+      #
+      # @example Single position
+      #   seq.at(4) { puts "At beat 4" }
+      #
+      # @example Series of positions
+      #   seq.at([1, 2, 3.5, 4]) { |pos| puts "At #{pos}" }
       def at(bar_position, debug: nil, &block)
         debug ||= false
 
@@ -181,6 +612,57 @@ module Musa
         control
       end
 
+      # Plays series over time.
+      #
+      # Consumes series values sequentially, evaluating each element to determine
+      # operation and scheduling continuation. Supports pause/continue,
+      # nested plays, parallel plays, and event-driven continuation.
+      # Timing determined by mode.
+      #
+      # @param serie [Series] series to play
+      # @param mode [Symbol] running mode (:at, :wait, :neumalang)
+      # @param parameter [Symbol, nil] duration parameter name from serie values
+      # @param after_bars [Numeric, nil] schedule block after play finishes
+      # @param after [Proc, nil] block to execute after play finishes
+      # @param context [Object, nil] context for neumalang processing
+      # @param mode_args [Hash] additional mode-specific parameters
+      # @yield [value] block executed for each serie value
+      # @return [PlayControl] control object
+      #
+      # ## Available Running Modes
+      #
+      # - **:at**: Elements specify absolute positions via :at key
+      # - **:wait**: Elements with duration specify wait time
+      # - **:neumalang**: Full Neumalang DSL with variables, commands, series, etc.
+      #
+      #
+      # @example Playing notes from a series
+      #   seq = Musa::Sequencer::BaseSequencer.new(4, 24)
+      #
+      #   notes = Musa::Series::S(60, 62, 64).zip(Musa::Series::S(1, 1, 2))
+      #   played_notes = []
+      #
+      #   seq.play(notes) do |pitch, duration|
+      #     played_notes << { pitch: pitch, duration: duration, position: seq.position }
+      #   end
+      #
+      #   seq.run
+      #   # Result: played_notes contains [{pitch: 60, duration: 1, position: 0}, ...]
+      #
+      # @example Parallel plays
+      #   seq = Musa::Sequencer::BaseSequencer.new(4, 24)
+      #
+      #   melody = Musa::Series::S(60, 62, 64)
+      #   harmony = Musa::Series::S(48, 52, 55)
+      #   played_notes = []
+      #
+      #   seq.play([melody, harmony]) do |pitch|
+      #     # pitch will be array [melody_pitch, harmony_pitch]
+      #     played_notes << { melody: pitch[0], harmony: pitch[1], position: seq.position }
+      #   end
+      #
+      #   seq.run
+      #   # Result: played_notes contains [{melody: 60, harmony: 48, position: 0}, ...]
       def play(serie,
                mode: nil,
                parameter: nil,
@@ -204,19 +686,88 @@ module Musa
         control.after do
           @playing.delete control
         end
-
+        
         control
       end
-
+      
       def continuation_play(parameters)
         _play parameters[:serie],
-              parameters[:control],
-              parameters[:neumalang_context],
-              mode: parameters[:mode],
-              decoder: parameters[:decoder],
-              __play_eval: parameters[:play_eval],
-              **parameters[:mode_args]
+        parameters[:control],
+        parameters[:neumalang_context],
+        mode: parameters[:mode],
+        decoder: parameters[:decoder],
+        __play_eval: parameters[:play_eval],
+        **parameters[:mode_args]
       end
+      
+      # Plays timed series (series with embedded timing information).
+      #
+      # Similar to play but serie values include timing: each element specifies its
+      # own timing via `:time` attribute. Unlike regular `play` which derives timing
+      # from evaluation mode, play_timed uses explicit times from series data.
+      #
+      # ## Timed Series Format
+      #
+      # Each element must have:
+      #
+      # - **:time**: Rational time offset from start
+      # - **:value**: Actual value(s) - Hash or Array
+      # - Optional extra attributes (passed to block)
+      #
+      # ## Value Modes
+      #
+      # - **Hash mode**: `{ time: 0r, value: {pitch: 60, velocity: 96} }`
+      # - **Array mode**: `{ time: 0r, value: [60, 96] }`
+      #
+      # Mode is detected from first element and applied to entire series.
+      #
+      # ## Component Tracking
+      #
+      # Tracks last update time per component (hash key or array index) to
+      # calculate `started_ago` - how long since each component changed.
+      #
+      # @param timed_serie [Series] timed series
+      # @param at [Rational, nil] starting position
+      # @param on_stop [Proc, nil] callback when playback stops
+      # @param after_bars [Numeric, nil] schedule after completion
+      # @param after [Proc, nil] block after completion
+      # @yield [value] block for each value
+      # @return [PlayTimedControl] control object
+      #
+      # @example Hash mode timed series
+      #   seq = Musa::Sequencer::BaseSequencer.new(4, 24)
+      #
+      #   timed_notes = Musa::Series::S(
+      #     { time: 0r, value: {pitch: 60, velocity: 96} },
+      #     { time: 1r, value: {pitch: 64, velocity: 80} },
+      #     { time: 2r, value: {pitch: 67, velocity: 64} }
+      #   )
+      #
+      #   played_notes = []
+      #
+      #   seq.play_timed(timed_notes) do |values, time:, started_ago:, control:|
+      #     played_notes << { pitch: values[:pitch], velocity: values[:velocity], time: time }
+      #   end
+      #
+      #   seq.run
+      #   # Result: played_notes contains [{pitch: 60, velocity: 96, time: 0r}, ...]
+      #
+      # @example Array mode with extra attributes
+      #   seq = Musa::Sequencer::BaseSequencer.new(4, 24)
+      #
+      #   timed = Musa::Series::S(
+      #     { time: 0r, value: [60, 96], channel: 0 },
+      #     { time: 1r, value: [64, 80], channel: 1 }
+      #   )
+      #
+      #   played_notes = []
+      #
+      #   seq.play_timed(timed) do |values, channel:, time:, started_ago:, control:|
+      #     played_notes << { pitch: values[0], velocity: values[1], channel: channel, time: time }
+      #   end
+      #
+      #   seq.run
+      #   # Result: played_notes contains [{pitch: 60, velocity: 96, channel: 0, time: 0r}, ...]
 
       def play_timed(timed_serie,
                      at: nil,
@@ -250,6 +801,55 @@ module Musa
         control
       end
 
+      # Executes block repeatedly at regular intervals.
+      #
+      # ## Execution Model
+      #
+      # Every loop schedules itself recursively:
+      # 1. Execute block at current position
+      # 2. Check stopping conditions
+      # 3. If not stopped, schedule next iteration at start + counter * interval
+      # 4. If stopped, call on_stop and after callbacks
+      #
+      # This ensures precise timing - iterations are scheduled relative to start
+      # position, not accumulated from previous iteration (avoiding drift).
+      #
+      # ## Stopping Conditions
+      #
+      # Loop stops when any of these conditions is met:
+      #
+      # - **manual stop**: `control.stop` called
+      # - **duration**: elapsed time >= duration (in bars)
+      # - **till**: current position >= till position
+      # - **condition**: condition block returns false
+      # - **nil interval**: immediate stop after first execution
+      #
+      # @param interval [Numeric, nil] interval between executions (nil = once)
+      # @param duration [Numeric, nil] total duration
+      # @param till [Numeric, nil] end position
+      # @param condition [Proc, nil] continue while condition true
+      # @param on_stop [Proc, nil] callback when loop stops
+      # @param after_bars [Numeric, nil] schedule after completion
+      # @param after [Proc, nil] block after completion
+      # @yield [position] block executed each interval
+      # @return [EveryControl] control object
+      #
+      # @example
+      #   seq.every(1, till: 8) { |pos| puts "Beat #{pos}" }
+      #
+      # @example Every 4 beats for 16 bars
+      #   sequencer.every(1r, duration: 4r) { puts "tick" }
+      #   # Executes at 1r, 2r, 3r, 4r, 5r (5 times total)
+      #
+      # @example Every beat until position 10
+      #   sequencer.every(1r, till: 10r) { |control| puts control.position }
+      #
+      # @example Conditional loop
+      #   count = 0
+      #   sequencer.every(1r, condition: proc { count < 5 }) do
+      #     puts count
+      #     count += 1
+      #   end
       def every(interval,
                 duration: nil, till: nil,
                 condition: nil,
@@ -283,6 +883,106 @@ module Musa
         control
       end
 
+      # Animates value from start to end over time. 
+      # Supports single values, arrays, and hashes
+      # with flexible parameter combinations for controlling timing and interpolation.
+      #
+      # ## Value Modes
+      #
+      # - **Single value**: `from: 0, to: 100`
+      # - **Array**: `from: [60, 0.5], to: [72, 1.0]` - multiple values
+      # - **Hash**: `from: {pitch: 60}, to: {pitch: 72}` - named values
+      #
+      # ## Parameter Combinations
+      #
+      # Move requires enough information to calculate both step size and iteration
+      # interval. Valid combinations:
+      #
+      # - `from, to, step, every` - All explicit
+      # - `from, to, step, duration/till` - Calculates every from steps needed
+      # - `from, to, every, duration/till` - Calculates step from duration
+      # - `from, step, every, duration/till` - Open-ended with time limit
+      #
+      # ## Interpolation
+      #
+      # - **Linear** (default): `function: proc { |ratio| ratio }`
+      # - **Ease-in**: `function: proc { |ratio| ratio ** 2 }`
+      # - **Ease-out**: `function: proc { |ratio| 1 - (1 - ratio) ** 2 }`
+      # - **Custom**: Any proc mapping [0..1] to [0..1]
+      #
+      # ## Applications
+      #
+      # - Pitch bends and glissandi
+      # - Volume fades and swells
+      # - Filter sweeps and modulation
+      # - Tempo changes and rubato
+      # - Multi-parameter automation
+      #
+      # @param every [Numeric] interval between updates
+      # @param from [Numeric] starting value
+      # @param to [Numeric] ending value
+      # @param step [Numeric, nil] value increment per step
+      # @param duration [Numeric, nil] total duration
+      # @param till [Numeric, nil] end position
+      # @param function [Symbol, Proc, nil] interpolation function
+      # @param right_open [Boolean, nil] exclude final value
+      # @param on_stop [Proc, nil] callback when animation stops
+      # @param after_bars [Numeric, nil] schedule after completion
+      # @param after [Proc, nil] block after completion
+      # @yield [value] block executed with interpolated value
+      # @return [MoveControl] control object
+      #
+      # @example Simple pitch glide
+      #   seq = Musa::Sequencer::BaseSequencer.new(4, 24)
+      #
+      #   pitch_values = []
+      #
+      #   seq.move(from: 60, to: 72, duration: 4r, every: 1/4r) do |pitch|
+      #     pitch_values << { pitch: pitch.round, position: seq.position }
+      #   end
+      #
+      #   seq.run
+      #   # Result: pitch_values contains [{pitch: 60, position: 0}, {pitch: 61, position: 0.25}, ...]
+      #
+      # @example Multi-parameter fade
+      #   seq = Musa::Sequencer::BaseSequencer.new(4, 24)
+      #
+      #   controller_values = []
+      #
+      #   seq.move(
+      #     from: {volume: 0, brightness: 0},
+      #     to: {volume: 127, brightness: 127},
+      #     duration: 8r,
+      #     every: 1/8r
+      #   ) do |params|
+      #     controller_values << {
+      #       volume: params[:volume].round,
+      #       brightness: params[:brightness].round,
+      #       position: seq.position
+      #     }
+      #   end
+      #
+      #   seq.run
+      #   # Result: controller_values contains [{volume: 0, brightness: 0, position: 0}, ...]
+      #
+      # @example Non-linear interpolation
+      #   sequencer.move(
+      #     from: 0, to: 100,
+      #     duration: 4r, every: 1/16r,
+      #     function: proc { |ratio| ratio ** 2 }  # Ease-in
+      #   ) { |value| puts value }
+      #
+      # @example Linear fade
+      #   seq = Musa::Sequencer::BaseSequencer.new(4, 24)
+      #
+      #   volume_values = []
+      #
+      #   seq.move(every: 1/4r, from: 0, to: 127, duration: 4) do |value|
+      #     volume_values << value.round
+      #   end
+      #
+      #   seq.run
+      #   # Result: volume_values contains [0, 8, 16, 24, ..., 119, 127]
       def move(every: nil,
                from: nil, to: nil, step: nil,
                duration: nil, till: nil,