musa-dsl 0.30.2 → 0.40.0

data/lib/musa-dsl/transcription/transcription.rb

@@ -1,8 +1,185 @@
 module Musa
+  # Transcription framework for converting GDV musical events to output formats.
+  #
+  # Provides infrastructure for transcribing GDV (Grade-Duration-Velocity) events
+  # into various output formats (MIDI, MusicXML) through a pipeline of feature
+  # processors. The transcription system handles musical ornaments, articulations,
+  # and notation-specific transformations.
+  #
+  # ## Architecture Overview
+  #
+  # ### Core Components
+  #
+  # 1. **Transcriptor** - Main orchestrator that chains feature processors
+  # 2. **FeatureTranscriptor** - Base class for individual feature processors
+  # 3. **Transcriptor Sets** - Pre-configured processor chains for specific formats
+  #
+  # ### Processing Pipeline
+  #
+  # ```ruby
+  # GDV Event → [Transcriptor 1] → [Transcriptor 2] → ... → Output Format
+  # ```
+  #
+  # Each transcriptor in the chain:
+  #
+  # - Extracts specific features (appogiatura, trill, staccato, etc.)
+  # - Transforms/expands the event based on those features
+  # - Passes result to next transcriptor in chain
+  #
+  # ## GDV Format
+  #
+  # GDV events are hashes representing musical notes/events:
+  # ```ruby
+  # {
+  #   grade: 0,           # Scale degree (pitch)
+  #   duration: 1r,       # Rational duration
+  #   velocity: 0.8,      # Note velocity (0.0-1.0)
+  #   # Plus optional ornament/articulation attributes:
+  #   tr: true,           # Trill
+  #   mor: :up,           # Mordent
+  #   st: 2,              # Staccato
+  #   appogiatura: {...}  # Grace note
+  # }
+  # ```
+  #
+  # ## Output Formats
+  #
+  # - **MIDI** (`FromGDV::ToMIDI`): Expands ornaments to note sequences for playback
+  # - **MusicXML** (`FromGDV::ToMusicXML`): Preserves ornaments as notation symbols
+  #
+  # ## Usage
+  #
+  # ```ruby
+  # # MIDI transcription (expands ornaments)
+  # transcriptor = Musa::Transcription::Transcriptor.new(
+  #   Musa::Transcriptors::FromGDV::ToMIDI.transcription_set(duration_factor: 1/4r),
+  #   base_duration: 1/4r,
+  #   tick_duration: 1/96r
+  # )
+  # midi_events = transcriptor.transcript(gdv_event)
+  #
+  # # MusicXML transcription (preserves ornaments as symbols)
+  # transcriptor = Musa::Transcription::Transcriptor.new(
+  #   Musa::Transcriptors::FromGDV::ToMusicXML.transcription_set,
+  #   base_duration: 1/4r
+  # )
+  # musicxml_events = transcriptor.transcript(gdv_event)
+  # ```
+  #
+  # ## Supported Features
+  #
+  # ### Ornaments
+  #
+  # - **Appogiatura**: Grace notes
+  # - **Mordent**: Quick alternation with adjacent note
+  # - **Turn**: Four-note circling figure
+  # - **Trill**: Rapid alternation with upper neighbor
+  #
+  # ### Articulations
+  #
+  # - **Staccato**: Shortened note duration
+  # - **Base/Rest**: Zero-duration structural markers
+  #
+  # ## Creating Custom Transcriptors
+  #
+  # Extend `FeatureTranscriptor` and implement `transcript` method:
+  # ```ruby
+  # class MyOrnament < Musa::Transcription::FeatureTranscriptor
+  #   def transcript(gdv, base_duration:, tick_duration:)
+  #     if ornament = gdv.delete(:my_ornament)
+  #       # Process ornament, return modified event(s)
+  #       [event1, event2, ...]
+  #     else
+  #       super  # Pass through unchanged
+  #     end
+  #   end
+  # end
+  # ```
+  #
+  # ## Integration
+  #
+  # The transcription system integrates with:
+  #
+  # - **Sequencer**: Converting generative patterns to playable events
+  # - **MIDI**: Real-time MIDI output with ornament expansion
+  # - **MusicXML**: Score generation with notation symbols
+  # - **Datasets**: Using AbsD (absolute duration) extensions
+  #
+  # @example Complete transcription workflow
+  #   # 1. Generate GDV events
+  #   gdv_events = [
+  #     { grade: 0, duration: 1r, tr: true },
+  #     { grade: 2, duration: 1r, mor: :up },
+  #     { grade: 4, duration: 1/2r, st: true }
+  #   ]
+  #
+  #   # 2. Create MIDI transcriptor
+  #   transcriptor = Musa::Transcription::Transcriptor.new(
+  #     Musa::Transcriptors::FromGDV::ToMIDI.transcription_set,
+  #     base_duration: 1/4r
+  #   )
+  #
+  #   # 3. Transcribe to MIDI events
+  #   midi_events = gdv_events.collect { |gdv| transcriptor.transcript(gdv) }.flatten
+  #
+  #   # 4. Send to MIDI output
+  #   midi_events.each { |event| midi_output.send_event(event) }
+  #
+  # @see Musa::Transcriptors::FromGDV::ToMIDI
+  # @see Musa::Transcriptors::FromGDV::ToMusicXML
+  # @see Musa::Sequencer
+  #
+  # @api public
   module Transcription
+    # Main transcription orchestrator.
+    #
+    # Chains multiple feature transcriptors to process GDV events through a
+    # transformation pipeline. Each transcriptor in the chain processes specific
+    # musical features (ornaments, articulations, etc.).
+    #
+    # ## Processing
+    #
+    # The transcriptor applies each feature processor in sequence:
+    # 1. First transcriptor processes event
+    # 2. Result passed to second transcriptor
+    # 3. Continue through chain
+    # 4. Final result returned
+    #
+    # ## Array Handling
+    #
+    # If a transcriptor returns an array (e.g., expanding one note to many),
+    # subsequent transcriptors process each element and results are flattened.
+    #
+    # @example Create transcriptor chain
+    #   transcriptor = Musa::Transcription::Transcriptor.new(
+    #     [Appogiatura.new, Trill.new, Staccato.new],
+    #     base_duration: 1/4r,
+    #     tick_duration: 1/96r
+    #   )
+    #
+    # @api public
     class Transcriptor
+      # Returns the transcriptor chain.
+      #
+      # @return [Array<FeatureTranscriptor>] array of feature processors
+      #
+      # @api public
       attr_reader :transcriptors
 
+      # Creates transcriptor with specified feature processors.
+      #
+      # @param transcriptors [Array<FeatureTranscriptor>] chain of feature processors
+      # @param base_duration [Rational] base duration unit (e.g., quarter note = 1/4)
+      # @param tick_duration [Rational] minimum tick duration (e.g., 1/96 for MIDI)
+      #
+      # @example Create MIDI transcriptor
+      #   transcriptor = Musa::Transcription::Transcriptor.new(
+      #     Musa::Transcriptors::FromGDV::ToMIDI.transcription_set,
+      #     base_duration: 1/4r,
+      #     tick_duration: 1/96r
+      #   )
+      #
+      # @api public
       def initialize(transcriptors = nil, base_duration: nil, tick_duration: nil)
         @transcriptors = transcriptors || []
 
@@ -10,6 +187,28 @@ module Musa
         @tick_duration = tick_duration || 1/96r
       end
 
+      # Transcribes GDV event(s) through the processor chain.
+      #
+      # Applies each transcriptor in sequence. Handles both single events and
+      # arrays of events, flattening results when transcriptors expand events.
+      #
+      # @param element [Hash, Array<Hash>] GDV event or array of events
+      #
+      # @return [Hash, Array<Hash>, nil] transcribed event(s)
+      #
+      # @example Transcribe single event
+      #   gdv = { grade: 0, duration: 1r, tr: true }
+      #   result = transcriptor.transcript(gdv)
+      #   # => [{ grade: 1, duration: 1/16r }, { grade: 0, duration: 1/16r }, ...]
+      #
+      # @example Transcribe array of events
+      #   gdvs = [
+      #     { grade: 0, duration: 1r, mor: true },
+      #     { grade: 2, duration: 1r }
+      #   ]
+      #   results = transcriptor.transcript(gdvs)
+      #
+      # @api public
       def transcript(element)
         @transcriptors.each do |transcriptor|
           if element
@@ -25,7 +224,49 @@ module Musa
       end
     end
 
+    # Base class for feature transcriptors.
+    #
+    # Provides common functionality for processing specific musical features
+    # in GDV events. Subclasses implement `transcript` method to handle
+    # their specific feature (ornament, articulation, etc.).
+    #
+    # ## Contract
+    #
+    # Transcriptor implementations should:
+    #
+    # 1. Extract their specific feature from GDV hash
+    # 2. Process/transform the event based on that feature
+    # 3. Return modified event(s) or call `super` if feature not present
+    # 4. Use `delete` to remove processed feature attributes
+    #
+    # ## Helper Methods
+    #
+    # - `check(value, &block)`: Safely iterate over value or array
+    #
+    # @example Implement custom transcriptor
+    #   class Accent < FeatureTranscriptor
+    #     def transcript(gdv, base_duration:, tick_duration:)
+    #       if accent = gdv.delete(:accent)
+    #         gdv[:velocity] *= 1.2  # Increase velocity
+    #       end
+    #       super  # Clean up and pass through
+    #     end
+    #   end
+    #
+    # @api public
     class FeatureTranscriptor
+      # Transcribes GDV event for this feature.
+      #
+      # Base implementation cleans up empty `:modifiers` attribute. Subclasses
+      # should override to process their specific feature, then call `super`.
+      #
+      # @param element [Hash, Array<Hash>] GDV event or array of events
+      # @param base_duration [Rational] base duration unit
+      # @param tick_duration [Rational] minimum tick duration
+      #
+      # @return [Hash, Array<Hash>] transcribed event(s)
+      #
+      # @api public
       def transcript(element, base_duration:, tick_duration:)
         case element
         when Hash
@@ -37,6 +278,23 @@ module Musa
         element
       end
 
+      # Helper to safely process value or array.
+      #
+      # Yields each element if array, or yields single value.
+      # Useful for processing feature values that may be single or multiple.
+      #
+      # @param value_or_array [Object, Array] value to check
+      # @yield [value] block to call for each value
+      #
+      # @example Check ornament options
+      #   check(ornament_value) do |option|
+      #     case option
+      #     when :up then direction = :up
+      #     when :down then direction = :down
+      #     end
+      #   end
+      #
+      # @api public
       def check(value_or_array, &block)
         if block_given?
           if value_or_array.is_a?(Array)
@@ -49,5 +307,12 @@ module Musa
     end
   end
 
+  # Namespace for transcriptor implementations.
+  #
+  # Contains modules for different transcription targets:
+  # - `FromGDV::ToMIDI` - MIDI playback transcriptors
+  # - `FromGDV::ToMusicXML` - MusicXML notation transcriptors
+  #
+  # @api public
   module Transcriptors; end
 end

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

@@ -1,6 +1,73 @@
 module Musa
+  # Clock and timing infrastructure for musical transport.
+  #
+  # The Clock module provides the foundation for all timing mechanisms in Musa DSL.
+  # Clocks generate regular ticks that drive the sequencer forward, and can be
+  # sourced from internal timers, external MIDI clock, or manual control.
+  #
+  # ## Architecture
+  #
+  # - **Clock (base class)**: Abstract interface for all clock implementations
+  # - **TimerClock**: Internal high-precision timer-based clock
+  # - **InputMidiClock**: Synchronized to external MIDI Clock messages
+  # - **ExternalTickClock**: Manually triggered ticks (for testing/integration)
+  # - **DummyClock**: Simplified clock for testing
+  #
+  # ## Clock Lifecycle
+  #
+  # 1. **Creation**: Clock instance created with configuration
+  # 2. **Registration**: Callbacks registered (on_start, on_stop, on_change_position)
+  # 3. **Running**: Clock.run called (blocks, generates ticks via yield)
+  # 4. **Termination**: Clock.terminate called to stop
+  #
+  # @see Transport Connects clocks to sequencers
+  # @see Sequencer Receives ticks from clocks
   module Clock
+    # Abstract base class for all clock implementations.
+    #
+    # This class defines the interface and callback infrastructure that all
+    # concrete clock implementations must follow. Subclasses must implement
+    # the `run` and `terminate` methods.
+    #
+    # ## Callback System
+    #
+    # Clocks maintain three callback collections:
+    #
+    # - **on_start**: Called when clock starts running
+    # - **on_stop**: Called when clock stops
+    # - **on_change_position**: Called when position changes (seek/jump)
+    #
+    # ## Subclass Responsibilities
+    #
+    # Concrete clocks must:
+    #
+    # 1. Implement `run(&block)` - Start generating ticks, yield for each tick
+    # 2. Implement `terminate` - Stop the clock
+    # 3. Call registered callbacks at appropriate times
+    # 4. Manage @run state properly
+    #
+    # @example Creating a simple clock subclass
+    #   class SimpleClock < Clock
+    #     def run
+    #       @run = true
+    #       @on_start.each(&:call)
+    #
+    #       while @run
+    #         yield if block_given?  # Generate tick
+    #         sleep 0.1
+    #       end
+    #
+    #       @on_stop.each(&:call)
+    #     end
+    #
+    #     def terminate
+    #       @run = false
+    #     end
+    #   end
+    #
+    # @abstract Subclass and implement {#run} and {#terminate}
     class Clock
+      # Initializes the clock with empty callback collections.
       def initialize
         @run = nil
         @on_start = []
@@ -8,26 +75,84 @@ module Musa
         @on_change_position = []
       end
 
+      # Checks if the clock is currently running.
+      #
+      # @return [Boolean] true if clock is running, false otherwise.
       def running?
         @run
       end
 
+      # Registers a callback to be called when the clock starts.
+      #
+      # Multiple callbacks can be registered and will be called in order.
+      #
+      # @yield Called when clock starts running.
+      # @return [void]
+      #
+      # @example
+      #   clock.on_start { puts "Clock started!" }
       def on_start(&block)
         @on_start << block
       end
 
+      # Registers a callback to be called when the clock stops.
+      #
+      # Multiple callbacks can be registered and will be called in order.
+      #
+      # @yield Called when clock stops running.
+      # @return [void]
+      #
+      # @example
+      #   clock.on_stop { puts "Clock stopped!" }
       def on_stop(&block)
         @on_stop << block
       end
 
+      # Registers a callback to be called when playback position changes.
+      #
+      # This is typically used for handling seek/jump operations where the
+      # transport position changes non-linearly.
+      #
+      # @yield [bars, beats, midi_beats] Position change information
+      # @yieldparam bars [Rational, nil] new position in bars
+      # @yieldparam beats [Rational, nil] new position in beats
+      # @yieldparam midi_beats [Integer, nil] new position in MIDI beats (for MIDI Clock)
+      # @return [void]
+      #
+      # @example
+      #   clock.on_change_position do |bars:, beats:, midi_beats:|
+      #     puts "Position changed to bar #{bars}"
+      #   end
       def on_change_position(&block)
         @on_change_position << block
       end
 
+      # Starts the clock running and generates ticks.
+      #
+      # This method should block and yield once per tick. Subclasses must
+      # implement this method.
+      #
+      # @yield Called once per tick to advance the sequencer.
+      # @return [void]
+      #
+      # @raise [NotImplementedError] if not overridden by subclass.
+      #
+      # @note This method typically runs in a loop until {#terminate} is called.
+      # @note Subclasses should call @on_start callbacks when starting.
+      # @note Subclasses should call @on_stop callbacks when stopping.
       def run
         raise NotImplementedError
       end
 
+      # Stops the clock and terminates the run loop.
+      #
+      # Subclasses must implement this method to cleanly stop the clock.
+      #
+      # @return [void]
+      #
+      # @raise [NotImplementedError] if not overridden by subclass.
+      #
+      # @note After calling this, {#run} should exit.
       def terminate
         raise NotImplementedError
       end

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

@@ -2,7 +2,67 @@ require_relative 'clock'
 
 module Musa
   module Clock
+    # Simple clock for testing with fixed tick count or custom condition.
+    #
+    # DummyClock is designed for testing and batch processing where automatic
+    # execution without external dependencies is desired.
+    #
+    # ## Activation Model
+    #
+    # **IMPORTANT**: Unlike TimerClock, InputMidiClock, and ExternalTickClock,
+    # DummyClock **activates automatically** when `transport.start` is called.
+    # It immediately begins generating ticks without waiting for external signals.
+    #
+    # This activation model is appropriate for:
+    # 
+    # - **Unit testing**: No external dependencies, deterministic execution
+    # - **Batch processing**: Generate music as fast as possible
+    # - **Fast-forward simulations**: Skip real-time delays
+    # - **Deterministic debugging**: Predictable tick counts
+    #
+    # ## Modes of Operation
+    #
+    # 1. **Fixed tick count**: Runs for exactly N ticks then stops
+    # 2. **Custom condition**: Runs while a block returns true
+    #
+    # ## Differences from Other Clocks
+    #
+    # DummyClock is the only clock that starts generating ticks immediately
+    # upon `transport.start`. It uses Thread.pass instead of sleep, making
+    # execution as fast as possible without real-time constraints.
+    #
+    # @example Fixed tick count (automatic activation)
+    #   clock = DummyClock.new(100)  # Exactly 100 ticks
+    #   transport = Transport.new(clock)
+    #   transport.start  # Immediately runs 100 ticks, then stops
+    #
+    # @example Custom condition (automatic activation)
+    #   continue = true
+    #   clock = DummyClock.new { continue }
+    #   transport = Transport.new(clock)
+    #
+    #   transport.sequencer.at(10) { continue = false }
+    #   transport.start  # Immediately begins, stops at tick 10
+    #
+    # @example Testing specific sequences
+    #   ticks = 0
+    #   clock = DummyClock.new { ticks < 50 || some_condition }
+    #   transport.sequencer.every(1) { ticks += 1 }
+    #   transport.start  # Immediately runs minimum 50 ticks
+    #
+    # @see TimerClock For real-time operation with external activation
+    # @see InputMidiClock For MIDI-synchronized operation
+    # @see ExternalTickClock For manual tick control
     class DummyClock < Clock
+      # Creates a new dummy clock with tick limit or condition.
+      #
+      # @param ticks [Integer, nil] number of ticks to generate (mutually exclusive with block)
+      # @param do_log [Boolean, nil] enable logging
+      # @yield Condition block called each iteration; runs while truthy
+      #
+      # @raise [ArgumentError] if both ticks and block are provided
+      #
+      # @note Only one of ticks or block should be provided
       def initialize(ticks = nil, do_log: nil, &block)
         do_log ||= false
 
@@ -15,8 +75,26 @@ module Musa
         @block = block
       end
 
-      attr_accessor :block, :ticks
+      # Condition block for continuing (can be changed dynamically).
+      #
+      # @return [Proc, nil] the condition block
+      attr_accessor :block
 
+      # Number of ticks remaining (can be changed dynamically).
+      #
+      # @return [Integer, nil] ticks remaining
+      attr_accessor :ticks
+
+      # Runs the clock loop, yielding for each tick.
+      #
+      # Calls on_start callbacks, then yields while the condition is true.
+      # Uses Thread.pass instead of sleep for fast operation.
+      # Calls on_stop callbacks when done.
+      #
+      # @yield Called once per tick
+      # @return [void]
+      #
+      # @note No real-time delays; runs as fast as possible
       def run
         @on_start.each(&:call)
         @run = true
@@ -24,23 +102,32 @@ module Musa
         while @run && eval_condition
           yield if block_given?
 
-          Thread.pass
+          Thread.pass  # Cooperate with other threads
         end
 
         @on_stop.each(&:call)
       end
 
+      # Terminates the clock loop.
+      #
+      # @return [void]
       def terminate
         @run = false
       end
 
       private
 
+      # Evaluates continuation condition based on mode.
+      #
+      # @return [Boolean] true to continue, false to stop
+      # @api private
       def eval_condition
         if @ticks
+          # Tick count mode: decrement and check
           @ticks -= 1
           @ticks.positive?
         else
+          # Block condition mode
           @block.call
         end
       end

data/lib/musa-dsl/transport/external-tick-clock.rb

@@ -2,7 +2,76 @@ require_relative 'clock'
 
 module Musa
   module Clock
+    # Clock driven by external tick() calls for integration and testing.
+    #
+    # ExternalTickClock doesn't generate its own ticks. Instead, ticks are
+    # triggered manually by calling the {#tick} method.
+    #
+    # ## Activation Model
+    #
+    # **IMPORTANT**: ExternalTickClock requires manual tick generation. After calling
+    # `transport.start` (which returns immediately, doesn't block), you must call
+    # `clock.tick()` repeatedly from your external system to generate ticks.
+    #
+    # This activation model is appropriate for:
+    # 
+    # - **Testing**: Precise control over timing for step-by-step debugging
+    # - **Game engine integration**: Game loop controls tick timing
+    # - **Frame-based systems**: One tick per frame or custom logic
+    # - **Offline rendering**: Generate ticks as fast as needed
+    #
+    # ## Operation
+    #
+    # 1. Call {#run} to initialize (doesn't block, returns immediately)
+    # 2. Call {#tick} repeatedly to generate ticks manually
+    # 3. Call {#terminate} when done
+    #
+    # ## Differences from Other Clocks
+    #
+    # Unlike TimerClock and InputMidiClock, ExternalTickClock's `run` method
+    # **does not block** - it returns immediately. This allows your external
+    # system to control the timing loop.
+    #
+    # @example Manual stepping for testing
+    #   clock = ExternalTickClock.new
+    #   transport = Transport.new(clock)
+    #
+    #   # Schedule some events
+    #   transport.sequencer.at 1 { puts "Tick 1" }
+    #   transport.sequencer.at 2 { puts "Tick 2" }
+    #
+    #   # Start in background (non-blocking for ExternalTickClock)
+    #   thread = Thread.new { transport.start }
+    #   sleep 0.1  # Let transport initialize
+    #
+    #   # Generate ticks manually
+    #   clock.tick  # => (nothing, position 0)
+    #   clock.tick  # => "Tick 1"
+    #   clock.tick  # => "Tick 2"
+    #
+    #   transport.stop
+    #   thread.join
+    #
+    # @example Integration with game loop
+    #   clock = ExternalTickClock.new
+    #   transport = Transport.new(clock)
+    #   thread = Thread.new { transport.start }
+    #   sleep 0.1
+    #
+    #   # In game update loop:
+    #   def update(delta_time)
+    #     if should_tick?(delta_time)
+    #       clock.tick  # Advance sequencer by one tick
+    #     end
+    #   end
+    #
+    # @see DummyClock For automatic testing with fixed tick counts
+    # @see TimerClock For internal timer-based timing
+    # @see InputMidiClock For MIDI-synchronized timing
     class ExternalTickClock < Clock
+      # Creates a new externally-controlled clock.
+      #
+      # @param do_log [Boolean, nil] enable logging
       def initialize(do_log: nil)
         do_log ||= false
 
@@ -11,18 +80,40 @@ module Musa
         @do_log = do_log
       end
 
+      # Initializes the clock (non-blocking).
+      #
+      # Unlike other clocks, this method doesn't block. It stores the block
+      # and calls on_start callbacks, then returns immediately. Ticks are
+      # generated by calling {#tick}.
+      #
+      # @yield Called for each tick triggered by {#tick}
+      # @return [void]
+      #
+      # @note This method does NOT block
       def run(&block)
         @on_start.each(&:call)
         @run = true
         @block = block
       end
 
+      # Generates one tick manually.
+      #
+      # If the clock is running, calls the registered block (typically
+      # sequencer.tick). Has no effect if clock is not running.
+      #
+      # @return [void]
+      #
+      # @note Only works if {#run} has been called
+      # @note Thread-safe for integration with external event loops
       def tick
         if @run
           @block.call if @block
         end
       end
 
+      # Terminates the clock and calls on_stop callbacks.
+      #
+      # @return [void]
       def terminate
         @on_stop.each(&:call)
         @run = false