musa-dsl 0.30.2 → 0.40.0

data/lib/musa-dsl/transport/input-midi-clock.rb

@@ -4,7 +4,81 @@ require_relative 'clock'
 
 module Musa
   module Clock
+    # Clock synchronized to external MIDI Clock messages.
+    #
+    # InputMidiClock receives MIDI Clock, Start, Stop, Continue, and Song Position
+    # messages from an external source (typically a DAW or hardware sequencer) and
+    # generates ticks synchronized to that source.
+    #
+    # ## Activation Model
+    #
+    # **IMPORTANT**: InputMidiClock requires external MIDI activation. After calling
+    # `transport.start` (which blocks), the clock waits for MIDI "Start" (0xFA)
+    # message from the external source to begin generating ticks.
+    #
+    # This activation model is appropriate for:
+    # 
+    # - **DAW synchronization**: DAW controls start/stop via MIDI Clock
+    # - **Hardware sequencer sync**: External device controls timing
+    # - **Multi-device setups**: One master device controls all slaves
+    #
+    # ## MIDI Clock Protocol
+    #
+    # - **Clock (0xF8)**: Sent 24 times per quarter note (generates ticks when started)
+    # - **Start (0xFA)**: Begin playing from start (activates tick generation)
+    # - **Stop (0xFC)**: Stop playing (halts tick generation)
+    # - **Continue (0xFB)**: Resume from current position
+    # - **Song Position Pointer (0xF2)**: Jump to specific position
+    #
+    # ## Features
+    #
+    # - Automatic synchronization to external MIDI Clock
+    # - Position changes via Song Position Pointer
+    # - Start/Stop/Continue handling
+    # - Performance monitoring (time_table for tick processing times)
+    # - Graceful handling of missing input (waits until assigned)
+    #
+    # ## Special Sequences
+    #
+    # The clock handles the common sequence: Stop + Song Position + Continue
+    # as a position change while running, avoiding unnecessary stop/start cycles.
+    #
+    # ## Performance Monitoring
+    #
+    # The time_table tracks processing time per tick in milliseconds, useful
+    # for detecting performance issues.
+    #
+    # @example Basic setup with DAW synchronization
+    #   input = MIDICommunications::Input.all.first
+    #   clock = InputMidiClock.new(input, logger: logger)
+    #   transport = Transport.new(clock)
+    #
+    #   # Start transport (blocks waiting for MIDI Start message)
+    #   transport.start  # Waits until DAW sends MIDI Start (0xFA)
+    #
+    # @example Dynamic input assignment
+    #   clock = InputMidiClock.new  # No input yet
+    #   transport = Transport.new(clock)
+    #   transport.start  # Waits for input to be assigned
+    #
+    #   # Later:
+    #   clock.input = MIDICommunications::Input.all.first
+    #
+    # @example Checking performance
+    #   clock.time_table  # => [0 => 1543, 1 => 234, 2 => 12, ...]
+    #   # Shows histogram: X ms took Y ticks
+    #
+    # @see Transport Connects clock to sequencer
+    # @see MIDICommunications::Input MIDI input ports
+    # @see TimerClock For internal timing without MIDI
+    # @see DummyClock For automatic activation (testing/batch)
     class InputMidiClock < Clock
+      # Creates a new MIDI Clock synchronized clock.
+      #
+      # @param input [MIDICommunications::Input, nil] MIDI input port.
+      #   Can be nil; clock will wait for assignment.
+      # @param logger [Logger, nil] logger for messages
+      # @param do_log [Boolean, nil] enable debug logging
       def initialize(input = nil, logger: nil, do_log: nil)
         do_log ||= false
 
@@ -25,25 +99,64 @@ module Musa
         @midi_parser = MIDIParser.new
       end
 
+      # Current MIDI input port.
+      #
+      # @return [MIDICommunications::Input, nil] the input port
       attr_reader :input
+
+      # Performance timing histogram.
+      #
+      # Maps processing time in milliseconds to tick count.
+      #
+      # @return [Array<Integer>] histogram indexed by milliseconds
+      #
+      # @example
+      #   time_table[5]  # => 123 (123 ticks took 5ms)
       attr_reader :time_table
 
+      # Assigns a MIDI input port.
+      #
+      # If the clock is waiting for input (sleeping), wakes it up.
+      #
+      # @param input_midi_port [MIDICommunications::Input] MIDI input port
+      # @return [MIDICommunications::Input] the assigned input
       def input=(input_midi_port)
         @input = input_midi_port
         @waiting_for_input&.wakeup
       end
 
+      # Runs the MIDI Clock processing loop.
+      #
+      # This method blocks and processes incoming MIDI messages, generating ticks
+      # in response to MIDI Clock messages. If no input is assigned, it waits
+      # until one is assigned via {#input=}.
+      #
+      # ## Message Handling
+      #
+      # - **Clock**: Yields (generates tick) if started
+      # - **Start**: Triggers on_start callbacks
+      # - **Stop**: Triggers on_stop callbacks
+      # - **Continue**: Resumes (typically after Stop)
+      # - **Song Position**: Triggers on_change_position
+      #
+      # @yield Called once per MIDI Clock message (24 ppqn)
+      # @return [void]
+      #
+      # @note This method blocks until {#terminate} is called
+      # @note Waits if no input assigned
       def run
         @run = true
 
         while @run
           if @input
+            # Read raw MIDI messages from input port
             raw_messages = @input.gets
           else
+            # No input assigned yet - wait for assignment
             @logger.warn('InputMidiClock') { 'Waiting for clock input MIDI port' }
 
             @waiting_for_input = Thread.current
-            sleep
+            sleep  # Wait until input= wakes us
             @waiting_for_input = nil
 
             if @input
@@ -53,6 +166,7 @@ module Musa
             end
           end
 
+          # Parse raw MIDI bytes into message objects
           messages = []
           stop_index = nil
 
@@ -104,12 +218,20 @@ module Musa
         end
       end
 
+      # Terminates the MIDI Clock processing loop.
+      #
+      # @return [void]
       def terminate
         @run = false
       end
 
       private
 
+      # Processes MIDI Start message.
+      #
+      # Calls registered on_start callbacks and marks as started.
+      #
+      # @api private
       def process_start
         @logger.debug('InputMidiClock') { 'processing Start...' }
 
@@ -119,6 +241,16 @@ module Musa
         @logger.debug('InputMidiClock') { 'processing Start... done' }
       end
 
+      # Processes individual MIDI Clock protocol messages.
+      #
+      # Handles Start, Stop, Continue, Clock, and Song Position Pointer messages.
+      # For Clock messages, yields and tracks processing time.
+      #
+      # @param m [MIDIEvents::Event] parsed MIDI message
+      # @yield Called for Clock messages if started
+      # @return [void]
+      #
+      # @api private
       def process_message(m)
         case m.name
         when 'Start'

data/lib/musa-dsl/transport/timer-clock.rb

@@ -2,7 +2,92 @@ require_relative 'clock'
 
 module Musa
   module Clock
+    # Internal timer-based clock for standalone operation.
+    #
+    # TimerClock uses a high-precision Timer to generate ticks at a configurable
+    # rate. Unlike DummyClock, TimerClock requires external activation and is
+    # designed for scenarios where timing control comes from outside (e.g., live
+    # coding clients, interactive systems).
+    #
+    # ## Activation Model
+    #
+    # **IMPORTANT**: TimerClock starts in a paused state. After calling
+    # `transport.start` (which blocks), you must call `clock.start()` from
+    # another thread to begin generating ticks.
+    #
+    # This activation model is appropriate for:
+    # 
+    # - **Live coding**: Client controls when to start/stop
+    # - **Interactive systems**: External controller manages playback
+    # - **Testing with control**: Precise control over when ticks begin
+    #
+    # ## Configuration Methods
+    #
+    # The clock can be configured in three equivalent ways:
+    #
+    # 1. **BPM + ticks_per_beat**: Musical tempo-based (most common)
+    # 2. **Period**: Direct tick period in seconds
+    # 3. **Any combination**: Changes one parameter, others auto-calculate
+    #
+    # ## Relationship Between Parameters
+    #
+    #     period = 60 / (bpm * ticks_per_beat)
+    #
+    # Example: 120 BPM, 24 ticks/beat → period = 60/(120*24) = 0.02083s
+    #
+    # ## States
+    #
+    # - **Not started**: Clock created but not running
+    # - **Started**: Clock running, generating ticks
+    # - **Paused**: Clock started but temporarily stopped
+    #
+    # @example Complete setup with external activation (live coding pattern)
+    #   clock = TimerClock.new(bpm: 120, ticks_per_beat: 24)
+    #   transport = Transport.new(clock, beats_per_bar: 4)
+    #
+    #   # Schedule events
+    #   transport.sequencer.at(4) { transport.stop }
+    #
+    #   # Start transport in background (it blocks)
+    #   thread = Thread.new { transport.start }
+    #   sleep 0.1  # Let transport initialize
+    #
+    #   # Activate clock from external control (e.g., live coding client)
+    #   clock.start  # Now ticks begin generating
+    #
+    #   thread.join  # Wait for completion
+    #
+    # @example With timing correction
+    #   # Correction compensates for system-specific timing offsets
+    #   clock = TimerClock.new(bpm: 140, correction: -0.001)
+    #
+    # @example Dynamic tempo changes
+    #   clock = TimerClock.new(bpm: 120)
+    #   # ... later, while running:
+    #   clock.bpm = 140  # Tempo change takes effect immediately
+    #
+    # @see Timer Internal precision timer
+    # @see Transport Connects clock to sequencer
+    # @see DummyClock For automatic activation (testing/batch)
     class TimerClock < Clock
+      # Creates a new timer-based clock.
+      #
+      # At least one timing parameter must be provided (period, bpm, or ticks_per_beat).
+      # Missing parameters use defaults: bpm=120, ticks_per_beat=24.
+      #
+      # @param period [Numeric, nil] tick period in seconds (direct specification)
+      # @param ticks_per_beat [Numeric, nil] number of ticks per beat (default: 24)
+      # @param bpm [Numeric, nil] beats per minute (default: 120)
+      # @param correction [Numeric, nil] timing correction in seconds (for calibration)
+      # @param delayed_ticks_error [Numeric, nil] threshold for error-level logging
+      # @param logger [Logger, nil] logger for warnings/errors
+      # @param do_log [Boolean, nil] enable timing logs
+      #
+      # @example
+      #   # All equivalent for 120 BPM, 24 ticks/beat:
+      #   TimerClock.new(bpm: 120, ticks_per_beat: 24)
+      #   TimerClock.new(bpm: 120)  # ticks_per_beat defaults to 24
+      #   TimerClock.new(period: 0.02083, ticks_per_beat: 24)
       def initialize(period = nil, ticks_per_beat: nil, bpm: nil, correction: nil, delayed_ticks_error: nil, logger: nil, do_log: nil)
         do_log ||= false
 
@@ -10,10 +95,12 @@ module Musa
 
         @correction = correction
 
+        # Set parameters in any combination
         self.period = period if period
         self.ticks_per_beat = ticks_per_beat if ticks_per_beat
         self.bpm = bpm if bpm
 
+        # Apply defaults
         self.bpm ||= 120
         self.ticks_per_beat ||= 24
 
@@ -25,34 +112,87 @@ module Musa
         @do_log = do_log
       end
 
-      attr_reader :period, :ticks_per_beat, :bpm
+      # Current tick period in seconds.
+      #
+      # @return [Rational] seconds between ticks
+      attr_reader :period
 
+      # Number of ticks per beat.
+      #
+      # @return [Rational] ticks per beat (typically 24 or 96)
+      attr_reader :ticks_per_beat
+
+      # Current tempo in beats per minute.
+      #
+      # @return [Rational] BPM
+      attr_reader :bpm
+
+      # Sets the tick period in seconds and recalculates BPM.
+      #
+      # @param period_in_seconds [Numeric] new period in seconds
+      # @return [Rational] the rationalized period
+      #
+      # @note If clock is running, change takes effect immediately via @timer.period
       def period=(period_in_seconds)
         @period = period_in_seconds.rationalize
         @bpm = 60r / (@period * @ticks_per_beat) if @period && @ticks_per_beat
         @timer.period = @period if @timer
       end
 
+      # Sets ticks per beat and recalculates period.
+      #
+      # @param ticks [Numeric] new ticks per beat
+      # @return [Rational] the rationalized ticks_per_beat
+      #
+      # @note Common values: 24 (standard), 96 (high resolution)
+      # @note If clock is running, change takes effect immediately
       def ticks_per_beat=(ticks)
         @ticks_per_beat = ticks.rationalize
         @period = 60r / (@bpm * @ticks_per_beat) if @bpm && @ticks_per_beat
         @timer.period = @period if @timer && @period
       end
 
+      # Sets tempo in BPM and recalculates period.
+      #
+      # @param bpm [Numeric] new tempo in beats per minute
+      # @return [Rational] the rationalized BPM
+      #
+      # @note If clock is running, tempo change takes effect immediately
+      # @example Tempo automation
+      #   clock.bpm = 120
+      #   sleep 10
+      #   clock.bpm = 140  # Speed up!
       def bpm=(bpm)
         @bpm =  bpm.rationalize
         @period = 60r / (@bpm * @ticks_per_beat) if @bpm && @ticks_per_beat
         @timer.period = @period if @timer && @period
       end
 
+      # Checks if the clock has been started.
+      #
+      # @return [Boolean] true if started (even if currently paused)
       def started?
         @started
       end
 
+      # Checks if the clock is paused.
+      #
+      # @return [Boolean] true if paused
       def paused?
         @paused
       end
 
+      # Starts the clock's run loop.
+      #
+      # This method blocks and runs the timer loop, yielding for each tick.
+      # The clock starts in a paused state and must be explicitly started
+      # via {#start}.
+      #
+      # @yield Called once per tick
+      # @return [void]
+      #
+      # @note This method blocks until {#terminate} is called
+      # @note Clock begins paused; call {#start} to begin ticking
       def run
         @run = true
 
@@ -70,6 +210,15 @@ module Musa
         end
       end
 
+      # Starts the clock from paused state.
+      #
+      # Triggers @on_start callbacks and begins generating ticks.
+      # Has no effect if already started.
+      #
+      # @return [void]
+      #
+      # @note Must call {#run} first to start the run loop
+      # @note Calls registered on_start callbacks
       def start
         unless @started
           @on_start.each(&:call)
@@ -79,6 +228,15 @@ module Musa
         end
       end
 
+      # Stops the clock and resets to initial state.
+      #
+      # Triggers @on_stop callbacks and marks clock as not started.
+      # Has no effect if not currently started.
+      #
+      # @return [void]
+      #
+      # @note Calls registered on_stop callbacks
+      # @note Different from {#pause}: stop resets to initial state
       def stop
         if @started
           @timer.stop
@@ -88,6 +246,15 @@ module Musa
         end
       end
 
+      # Pauses the clock without stopping it.
+      #
+      # Ticks stop but clock remains in started state. Use {#continue}
+      # to resume.
+      #
+      # @return [void]
+      #
+      # @note No effect if not started or already paused
+      # @see #continue
       def pause
         if @started && !@paused
           @timer.stop
@@ -95,6 +262,14 @@ module Musa
         end
       end
 
+      # Resumes the clock from paused state.
+      #
+      # Continues generating ticks. Has no effect if not paused.
+      #
+      # @return [void]
+      #
+      # @note No effect if not started or not paused
+      # @see #pause
       def continue
         if @started && @paused
           @paused = false
@@ -102,6 +277,13 @@ module Musa
         end
       end
 
+      # Terminates the clock's run loop.
+      #
+      # Causes {#run} to exit. This is the clean shutdown mechanism.
+      #
+      # @return [void]
+      #
+      # @note After calling this, {#run} will exit
       def terminate
         @run = false
       end

data/lib/musa-dsl/transport/timer.rb

@@ -1,8 +1,54 @@
 module Musa
   module Clock
+    # High-precision timer for generating regular ticks.
+    #
+    # Timer uses Ruby's monotonic clock (Process::CLOCK_MONOTONIC) for drift-free
+    # timing. It compensates for processing delays and reports when the system
+    # cannot keep up with the requested tick rate.
+    #
+    # ## Precision Features
+    #
+    # - **Monotonic clock**: Immune to system time changes
+    # - **Drift compensation**: Calculates exact next tick time
+    # - **Overload detection**: Reports delayed ticks when processing is slow
+    # - **Correction parameter**: Fine-tune timing for specific systems
+    #
+    # ## Usage Pattern
+    #
+    # Timer is typically used internally by TimerClock, not directly. It runs
+    # in a loop, yielding for each tick and managing precise sleep intervals.
+    #
+    # ## Timing Algorithm
+    #
+    # 1. Record next expected tick time
+    # 2. Yield (caller processes tick)
+    # 3. Add period to next_moment
+    # 4. Calculate sleep time = (next_moment + correction) - current_time
+    # 5. Sleep if positive, warn if negative (delayed)
+    #
+    # @example Internal use by TimerClock
+    #   timer = Timer.new(0.02083, logger: logger)  # ~48 ticks/second
+    #   timer.run { sequencer.tick }
+    #
+    # @see TimerClock Uses Timer internally
     class Timer
+      # The period between ticks in seconds.
+      #
+      # @return [Rational] tick period in seconds
       attr_accessor :period
 
+      # Creates a new precision timer.
+      #
+      # @param tick_period_in_seconds [Numeric] time between ticks in seconds
+      # @param correction [Numeric, nil] timing correction offset in seconds (for calibration)
+      # @param stop [Boolean, nil] initial stopped state (true = paused)
+      # @param delayed_ticks_error [Numeric, nil] threshold for error-level logging (default: 1.0 tick)
+      # @param logger [Logger, nil] logger for timing warnings/errors
+      # @param do_log [Boolean, nil] enable logging
+      #
+      # @example 120 BPM, 24 ticks per beat
+      #   period = 60.0 / (120 * 24)  # 0.02083 seconds
+      #   timer = Timer.new(period, logger: logger)
       def initialize(tick_period_in_seconds, correction: nil, stop: nil, delayed_ticks_error: nil, logger: nil, do_log: nil)
         @period = tick_period_in_seconds.rationalize
         @correction = (correction || 0r).rationalize
@@ -13,6 +59,21 @@ module Musa
         @do_log = do_log
       end
 
+      # Runs the timer loop, yielding for each tick.
+      #
+      # This method blocks and runs indefinitely until stopped. For each tick:
+      # 1. Yields to caller if not stopped
+      # 2. Calculates next tick time
+      # 3. Sleeps precisely until next tick
+      # 4. Logs warnings if timing cannot be maintained
+      #
+      # When stopped (@stop = true), the thread sleeps until {#continue} is called.
+      #
+      # @yield Called once per tick for processing
+      # @return [void]
+      #
+      # @note This method blocks the current thread
+      # @note Uses monotonic clock for drift-free timing
       def run
         @thread = Thread.current
 
@@ -20,11 +81,14 @@ module Musa
 
         loop do
           unless @stop
+            # Process the tick
             yield
 
+            # Calculate next tick moment (compensates for processing time)
             @next_moment += @period
             to_sleep = (@next_moment + @correction) - Process.clock_gettime(Process::CLOCK_MONOTONIC)
 
+            # Log timing issues if enabled
             if @do_log && to_sleep.negative? & @logger
               tick_errors = -to_sleep / @period
               if tick_errors >= @delayed_ticks_error
@@ -34,17 +98,36 @@ module Musa
               end
             end
 
+            # Sleep precisely until next tick (if not already late)
             sleep to_sleep if to_sleep > 0.0
           end
 
+          # When stopped, sleep thread until continue is called
           sleep if @stop
         end
       end
 
+      # Pauses the timer without terminating the loop.
+      #
+      # The timer thread sleeps until {#continue} is called. Ticks are not
+      # generated while stopped.
+      #
+      # @return [void]
+      #
+      # @see #continue
       def stop
         @stop = true
       end
 
+      # Resumes the timer after being stopped.
+      #
+      # Resets the next tick moment to avoid a burst of catchup ticks,
+      # then wakes the timer thread.
+      #
+      # @return [void]
+      #
+      # @note Resets timing baseline to prevent tick accumulation
+      # @see #stop
       def continue
         @stop = false
         @next_moment = Process.clock_gettime(Process::CLOCK_MONOTONIC)