musa-dsl 0.30.2 → 0.40.0

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

@@ -3,12 +3,110 @@ require_relative '../core-ext/inspect-nice'
 require_relative '../sequencer'
 
 module Musa
+  # Transport system connecting clocks to sequencers.
+  #
+  # The Transport module provides the infrastructure for managing musical playback,
+  # connecting timing sources (clocks) to the sequencer that executes musical events.
+  #
+  # @see Transport Main transport class
+  # @see Clock Clock implementations
+  # @see Sequencer Event scheduling
   module Transport
+    # Main transport class connecting clocks to sequencers with lifecycle management.
+    #
+    # Transport acts as the bridge between a clock (timing source) and a sequencer
+    # (event scheduler). It manages the playback lifecycle, including initialization,
+    # start/stop, and position changes, with support for callbacks at each stage.
+    #
+    # ## Architecture
+    #
+    #     Clock --ticks--> Transport --tick()--> Sequencer --events--> Music
+    #
+    # ## Lifecycle Phases
+    #
+    # 1. **before_begin**: Run once before first start (initialization)
+    # 2. **on_start**: Run each time transport starts
+    # 3. **Running**: Clock generates ticks → sequencer processes events
+    # 4. **on_position_change**: Run when position jumps/seeks
+    # 5. **after_stop**: Run when transport stops
+    #
+    # ## Position Management
+    #
+    # Transport handles three position formats:
+    #
+    # - **bars**: Musical position in bars (Rational)
+    # - **beats**: Position in beats
+    # - **midi_beats**: Position in MIDI beats (for MIDI Clock sync)
+    #
+    # ## Use Cases
+    #
+    # - Standalone compositions with internal timing
+    # - DAW-synchronized playback via MIDI Clock
+    # - Testing with dummy/external clocks
+    # - Live coding with dynamic tempo changes
+    #
+    # @example Basic setup with TimerClock
+    #   clock = Musa::Clock::TimerClock.new(bpm: 120)
+    #   transport = Musa::Transport::Transport.new(
+    #     clock,
+    #     beats_per_bar: 4,
+    #     ticks_per_beat: 24
+    #   )
+    #
+    #   # Schedule events
+    #   transport.sequencer.at 0 { puts "Start!" }
+    #   transport.sequencer.at 4 { puts "Bar 4" }
+    #
+    #   transport.start
+    #
+    # @example With lifecycle callbacks
+    #   transport = Transport.new(clock) do |t|
+    #     t.before_begin { puts "Initializing..." }
+    #     t.on_start { puts "Started!" }
+    #     t.after_stop { puts "Stopped, cleaning up..." }
+    #   end
+    #
+    # @example MIDI Clock synchronization
+    #   midi_input = MIDICommunications::Input.all.first
+    #   clock = Musa::Clock::InputMidiClock.new(midi_input)
+    #   transport = Transport.new(clock)
+    #   transport.start  # Waits for MIDI Clock Start
+    #
+    # @see Clock::TimerClock Internal timer-based clock
+    # @see Clock::InputMidiClock MIDI Clock synchronized
+    # @see Sequencer Event scheduling
     class Transport
       using Musa::Extension::InspectNice
 
+      # The sequencer instance managing event scheduling.
+      #
+      # @return [Sequencer::Sequencer] the sequencer
       attr_reader :sequencer
 
+      # Creates a new transport connecting a clock to a sequencer.
+      #
+      # @param clock [Clock] timing source (TimerClock, InputMidiClock, etc.)
+      # @param beats_per_bar [Integer, nil] time signature numerator (default: 4)
+      # @param ticks_per_beat [Integer, nil] timing resolution (default: 24)
+      # @param offset [Rational, nil] time offset in bars (default: 0)
+      # @param sequencer [Sequencer, nil] existing sequencer (creates new if nil)
+      # @param before_begin [Proc, nil] callback run once before first start
+      # @param on_start [Proc, nil] callback run each time transport starts
+      # @param after_stop [Proc, nil] callback run when transport stops
+      # @param on_position_change [Proc, nil] callback for position changes
+      # @param logger [Logger, nil] logger instance
+      # @param do_log [Boolean, nil] enable logging
+      #
+      # @example With callback parameters
+      #   Transport.new(clock, 4, 24,
+      #     on_start: -> (seq) { puts "Started at #{seq.position}" }
+      #   )
+      #
+      # @example With callback methods
+      #   transport = Transport.new(clock, 4, 24)
+      #   transport.before_begin { setup_instruments }
+      #   transport.on_start { start_recording }
+      #   transport.after_stop { save_recording }
       def initialize(clock,
                      beats_per_bar = nil,
                      ticks_per_beat = nil,
@@ -57,24 +155,161 @@ module Musa
         @clock.on_change_position do |bars: nil, beats: nil, midi_beats: nil|
           change_position_to bars: bars, beats: beats, midi_beats: midi_beats
         end
+
+        # TODO: Consider adding block/DSL support for cleaner initialization syntax.
+        #
+        # Future enhancement could yield a DSL context that provides direct access to
+        # transport methods without requiring the transport variable. This would enable:
+        #
+        #   Transport.new(clock, 4, 24) do
+        #     before_begin { setup_instruments }
+        #     on_start { start_recording }
+        #     after_stop { save_recording }
+        #   end
+        #
+        # Instead of current approach:
+        #
+        #   transport = Transport.new(clock, 4, 24)
+        #   transport.before_begin { setup_instruments }
+        #   transport.on_start { start_recording }
+        #   transport.after_stop { save_recording }
+        #
+        # Implementation would require a DSL context object that delegates methods to
+        # the transport instance, similar to the sequencer DSL pattern.
       end
 
+      # Registers a callback to run once before the first start.
+      #
+      # before_begin callbacks are run only once, before the very first start.
+      # They're ideal for one-time setup like loading samples or initializing state.
+      #
+      # After a stop, before_begin runs again before the next start.
+      #
+      # @yield [sequencer] Called before first start
+      # @yieldparam sequencer [Sequencer] the sequencer instance
+      # @return [void]
+      #
+      # @example
+      #   transport.before_begin do |seq|
+      #     puts "Initializing at position #{seq.position}"
+      #     load_samples
+      #   end
       def before_begin(&block)
         @before_begin << Musa::Extension::SmartProcBinder::SmartProcBinder.new(block)
       end
 
+      # Registers a callback to run each time the transport starts.
+      #
+      # on_start callbacks run every time {#start} is called, after before_begin.
+      #
+      # @yield [sequencer] Called on each start
+      # @yieldparam sequencer [Sequencer] the sequencer instance
+      # @return [void]
+      #
+      # @example
+      #   transport.on_start do |seq|
+      #     puts "Starting playback at #{seq.position}"
+      #   end
       def on_start(&block)
         @on_start << Musa::Extension::SmartProcBinder::SmartProcBinder.new(block)
       end
 
+      # Registers a callback to run when the transport stops.
+      #
+      # after_stop callbacks run when the clock stops, before the sequencer is reset.
+      #
+      # @yield [sequencer] Called when stopping
+      # @yieldparam sequencer [Sequencer] the sequencer instance
+      # @return [void]
+      #
+      # @example
+      #   transport.after_stop do |seq|
+      #     puts "Stopped at position #{seq.position}"
+      #     cleanup_resources
+      #   end
       def after_stop(&block)
         @after_stop << Musa::Extension::SmartProcBinder::SmartProcBinder.new(block)
       end
 
+      # Registers a callback for position changes.
+      #
+      # Called when playback position changes non-linearly (seek/jump), typically
+      # from MIDI Song Position Pointer or manual position changes.
+      #
+      # @yield [sequencer] Called on position change
+      # @yieldparam sequencer [Sequencer] the sequencer instance
+      # @return [void]
+      #
+      # @example
+      #   transport.on_change_position do |seq|
+      #     puts "Position jumped to #{seq.position}"
+      #     resync_external_devices
+      #   end
       def on_change_position(&block)
         @on_change_position << Musa::Extension::SmartProcBinder::SmartProcBinder.new(block)
       end
 
+      # Starts the transport and begins playback.
+      #
+      # Runs before_begin (if first start or after stop), then starts the clock's
+      # run loop. **Behavior depends on the clock type**:
+      #
+      # ## Clock Activation by Type
+      #
+      # **DummyClock** (automatic activation):
+      # - Starts generating ticks immediately
+      # - Blocks until tick count/condition completes
+      # - No external activation needed
+      #
+      # **TimerClock** (external activation required):
+      # - Blocks but remains paused until `clock.start` is called
+      # - Must call `clock.start()` from another thread to begin ticks
+      # - Typical pattern: `Thread.new { transport.start }` then `clock.start`
+      #
+      # **InputMidiClock** (MIDI activation required):
+      # - Blocks waiting for MIDI "Start" (0xFA) message
+      # - External DAW/device controls when ticks begin
+      # - Automatically starts when MIDI Start received
+      #
+      # **ExternalTickClock** (manual tick control):
+      # - Returns immediately (doesn't block)
+      # - Call `clock.tick()` manually to generate each tick
+      # - Complete control over timing from external system
+      #
+      # @return [void]
+      #
+      # @note Blocking behavior varies by clock type (see above)
+      # @note For TimerClock, must call clock.start from separate thread
+      #
+      # @example With DummyClock (automatic)
+      #   clock = DummyClock.new(100)
+      #   transport = Transport.new(clock, 4, 24)
+      #   transport.start  # Runs 100 ticks automatically, then returns
+      #
+      # @example With TimerClock (external activation)
+      #   clock = TimerClock.new(bpm: 120)
+      #   transport = Transport.new(clock, 4, 24)
+      #
+      #   thread = Thread.new { transport.start }  # Blocks waiting
+      #   sleep 0.1
+      #   clock.start  # Activate from external control
+      #   thread.join
+      #
+      # @example With InputMidiClock (MIDI activation)
+      #   input = MIDICommunications::Input.all.first
+      #   clock = InputMidiClock.new(input)
+      #   transport = Transport.new(clock, 4, 24)
+      #   transport.start  # Blocks until MIDI Start received from DAW
+      #
+      # @example With ExternalTickClock (manual control)
+      #   clock = ExternalTickClock.new
+      #   transport = Transport.new(clock, 4, 24)
+      #
+      #   thread = Thread.new { transport.start }  # Returns immediately
+      #   sleep 0.1
+      #   100.times { clock.tick }  # Generate ticks manually
+      #   transport.stop
+      #   thread.join
       def start
         do_before_begin unless @before_begin_already_done
 
@@ -84,16 +319,73 @@ module Musa
         end
       end
 
+      # Changes the playback position (seek/jump).
+      #
+      # Handles position changes from various sources, converting between formats.
+      # **IMPORTANT**: Position changes trigger fast-forward, which executes all
+      # intermediate events between current and target positions.
+      #
+      # ## Fast-Forward Behavior
+      #
+      # When changing position forward:
+      # 1. Calls `sequencer.on_fast_forward` callbacks with `true` (entering fast-forward)
+      # 2. Ticks through all intermediate positions, **executing all scheduled events**
+      # 3. Calls `sequencer.on_fast_forward` callbacks with `false` (exiting fast-forward)
+      # 4. Calls `on_change_position` callbacks at the new position
+      #
+      # When changing position backward (requires stop):
+      # 1. Stops the transport (calls `after_stop` callbacks)
+      # 2. Resets the sequencer to initial state
+      # 3. Sets position to target
+      # 4. Restarts (calls `on_start` callbacks)
+      #
+      # ## Handling Intermediate Events
+      #
+      # During fast-forward, all scheduled events execute. To prevent unwanted sound
+      # output (e.g., MIDI notes), use `on_fast_forward` callbacks:
+      #
+      # - **MIDIVoices integration**: Set `midi_voices.fast_forward = true` during
+      #   fast-forward to register note state internally without emitting MIDI messages
+      # - **Custom handlers**: Check fast-forward state in event handlers to skip
+      #   audio/visual output during position jumps
+      #
+      # @param bars [Numeric, nil] target position in bars
+      # @param beats [Numeric, nil] offset in beats to add
+      # @param midi_beats [Integer, nil] offset in MIDI beats (for MIDI Clock)
+      #
+      # @return [void]
+      #
+      # @raise [ArgumentError] if no valid position specified
+      #
+      # @note Backward seeks trigger stop/restart cycle
+      # @note Calls on_change_position callbacks at new position
+      # @note Calls sequencer.on_fast_forward callbacks during forward seek
+      #
+      # @example Jump to bar 8 (fast-forwards through bars 1-7)
+      #   transport.change_position_to(bars: 8)
+      #
+      # @example MIDI Song Position Pointer
+      #   transport.change_position_to(midi_beats: 96)  # Bar 4 in 4/4
+      #
+      # @example Preventing sound during fast-forward with MIDIVoices
+      #   transport.sequencer.on_fast_forward do |is_starting|
+      #     midi_voices.fast_forward = is_starting
+      #   end
+      #
+      #   # Now position changes won't produce audible MIDI output
+      #   transport.change_position_to(bars: 10)
       def change_position_to(bars: nil, beats: nil, midi_beats: nil)
         logger.debug('Transport') do
           "asked to change position to #{"#{bars} bars " if bars}#{"#{beats} beats " if beats}" \
           "#{"#{midi_beats} midi beats " if midi_beats}"
         end
 
+        # Calculate position from provided parameters
         position = bars&.rationalize || 1r
         position += Rational(midi_beats, 4 * @sequencer.beats_per_bar) if midi_beats
         position += Rational(beats, @sequencer.beats_per_bar) if beats
 
+        # Adjust for sequencer offset and tick duration
         position += @sequencer.offset
         position -= @sequencer.tick_duration
 
@@ -103,6 +395,7 @@ module Musa
 
         start_again_later = false
 
+        # Backward seek requires stop/restart to reinitialize state
         if @sequencer.position > position
           do_stop
           start_again_later = true
@@ -110,6 +403,7 @@ module Musa
 
         logger.debug('Transport') { "setting sequencer position #{position.inspect}" }
 
+        # Schedule position change callback at new position
         @sequencer.raw_at position, force_first: true do
           @on_change_position.each { |block| block.call @sequencer }
         end
@@ -119,28 +413,51 @@ module Musa
         do_on_start if start_again_later
       end
 
+      # Stops the transport.
+      #
+      # Terminates the clock, which triggers the stop sequence (after_stop callbacks,
+      # sequencer reset, etc.)
+      #
+      # @return [void]
       def stop
         @clock.terminate
       end
 
+      # Returns the transport's logger.
+      #
+      # Delegates to sequencer's logger.
+      #
+      # @return [Logger] the logger instance
       def logger
         @sequencer.logger
       end
 
       private
 
+      # Executes before_begin callbacks.
+      #
+      # @api private
       def do_before_begin
         logger.debug('Transport') { 'doing before_begin initialization...' } unless @before_begin.empty?
         @before_begin.each { |block| block.call @sequencer }
         logger.debug('Transport') { 'doing before_begin initialization... done' } unless @before_begin.empty?
       end
 
+      # Executes on_start callbacks.
+      #
+      # @api private
       def do_on_start
         logger.debug('Transport') { 'starting...' } unless @on_start.empty?
         @on_start.each { |block| block.call @sequencer }
         logger.debug('Transport') { 'starting... done' } unless @on_start.empty?
       end
 
+      # Executes the stop sequence.
+      #
+      # Runs after_stop callbacks, resets the sequencer, then runs before_begin
+      # callbacks (preparing for next start).
+      #
+      # @api private
       def do_stop
         logger.debug('Transport') { 'stopping...' } unless @after_stop.empty?
         @after_stop.each { |block| block.call @sequencer }
@@ -150,6 +467,7 @@ module Musa
         @sequencer.reset
         logger.debug('Transport') { 'resetting sequencer... done' }
 
+        # Prepare for next start
         do_before_begin
         @before_begin_already_done = true
       end

data/lib/musa-dsl/version.rb

@@ -1,3 +1,3 @@
 module Musa
-  VERSION = '0.30.2'.freeze
+  VERSION = '0.40.0'.freeze
 end

data/lib/musa-dsl.rb

@@ -24,41 +24,148 @@ require_relative 'musa-dsl/music'
 
 require_relative 'musa-dsl/generative'
 
-module Musa::All
-  # Core
+# Musa-DSL: A Ruby framework and DSL for algorithmic sound and musical thinking and composition.
+#
+# Musa-DSL is a programming language DSL (Domain-Specific Language) based on Ruby designed for
+# sonic and musical composition. It emphasizes the creation of complex temporal structures
+# independently of the audio rendering engine, providing composers and developers with powerful
+# tools for algorithmic composition, generative music, and musical notation.
+#
+# ## Who is it for?
+#
+# - Composers exploring algorithmic composition
+# - Musicians interested in generative music systems
+# - Developers building music applications
+# - Researchers in computational musicology
+# - Live coders and interactive music performers
+#
+# ## Key Features
+#
+# - **Advanced Sequencer** - Precise temporal control for complex polyrhythmic and polytemporal structures
+# - **Transport & Timing** - Multiple clock sources (internal, MIDI, external) with microsecond precision
+# - **Audio Engine Independent** - Works with any MIDI-capable, OSC-capable or any other output hardware or software system
+# - **Series-Based Composition** - Flexible sequence generators for pitches, rhythms, dynamics, and any musical parameter
+# - **Generative Tools** - Markov chains, combinatorial variations (Variatio), rule-based production systems (Rules), formal grammars (GenerativeGrammar), and genetic algorithms (Darwin)
+# - **Matrix Operations** - Mathematical transformations for musical structures
+# - **Scale System** - Comprehensive support for scales, tuning systems, and chord structures
+# - **Neumalang Notation** - Intuitive text-based and customizable musical (or sound) notation
+# - **Transcription System** - Convert musical gestures to MIDI and MusicXML with ornament transcription expansion
+#
+# ## Documentation
+#
+# For complete user manual, tutorials, examples, and detailed subsystem documentation,
+# please visit the Musa-DSL project on GitHub:
+#
+# https://github.com/javier-sy/musa-dsl
+#
+# The README.md file contains comprehensive documentation including:
+# 
+# - Quick Start guide
+# - Complete tutorial
+# - System architecture overview
+# - Detailed documentation for all subsystems
+# - Installation instructions
+# - Usage examples
+#
+module Musa
+  # Convenience module that includes all Musa DSL components in a single namespace.
   #
-  include Musa::Logger
+  # This module provides a convenient way to include all Musa DSL functionality
+  # into your code with a single `include Musa::All` statement, rather than
+  # including each component individually.
+  #
+  # ## Included Components
+  #
+  # ### Core Functionality
+  # 
+  # - {Musa::Logger} - Logging utilities
+  # - {Musa::Clock} - Timing and clock management
+  # - {Musa::Transport} - Transport control (play, stop, tempo)
+  # - {Musa::Sequencer} - Event sequencing and scheduling
+  # - {Musa::Series} - Series operations and transformations
+  # - {Musa::Datasets} - Musical dataset management
+  # - {Musa::REPL} - Read-Eval-Print Loop for live coding
+  #
+  # ### Notation and Language
+  # 
+  # - {Musa::Neumalang} - Neuma language parser
+  # - {Musa::Neumas} - Neuma notation system
+  #
+  # ### Musical Theory
+  # 
+  # - {Musa::Scales} - Scale definitions and operations
+  # - {Musa::Chords} - Chord construction and manipulation
+  #
+  # ### Data Structures
+  # 
+  # - {Musa::Matrix} - Matrix operations for musical data
+  #
+  # ### Generative Algorithms
+  # 
+  # - {Musa::Darwin} - Evolutionary/genetic algorithms
+  # - {Musa::Markov} - Markov chain generation
+  # - {Musa::Rules} - Rule-based generative system
+  # - {Musa::Variatio} - Combinatorial variation generator
+  #
+  # ### Input/Output
+  # 
+  # - {Musa::MIDIRecorder} - MIDI event recording
+  # - {Musa::MIDIVoices} - MIDI voice management
+  # - {Musa::MusicXML} - MusicXML score generation
+  # - {Musa::Transcription} - Event transcription system
+  # - {Musa::Transcriptors} - Transcriptor implementations
+  #
+  # ## Usage
+  #
+  # @example Include all Musa DSL components
+  #   require 'musa-dsl'
+  #   include Musa::All
+  #
+  #   # Now you have access to all Musa DSL methods and classes
+  #   score = S.with(pitches: [60, 62, 64, 65])
+  #   sequencer = Sequencer.new
+  #
+  # @example Selective inclusion (alternative)
+  #   # Instead of Musa::All, you can include only what you need:
+  #   include Musa::Series
+  #   include Musa::Sequencer
+  module All
+    # Core
+    #
+    include Musa::Logger
 
-  include Musa::Clock
-  include Musa::Transport
-  include Musa::Sequencer
+    include Musa::Clock
+    include Musa::Transport
+    include Musa::Sequencer
 
-  include Musa::Series
-  include Musa::Datasets
+    include Musa::Series
+    include Musa::Datasets
 
-  include Musa::Neumalang
-  include Musa::Neumas
+    include Musa::Neumalang
+    include Musa::Neumas
 
-  include Musa::Transcription
+    include Musa::Transcription
 
-  include Musa::REPL
+    include Musa::REPL
 
-  # Extensions: ojo, el nombre extensions ya se usa para algunos paquetes de core-ext que funcionan con Refinements
-  #
-  include Musa::Scales
-  include Musa::Chords
+    # Extensions: ojo, el nombre extensions ya se usa para algunos paquetes de core-ext que funcionan con Refinements
+    #
+    include Musa::Scales
+    include Musa::Chords
 
-  include Musa::Matrix
+    # Note: Musa::Extension::Matrix is a refinement and cannot be included
+    # Use: using Musa::Extension::Matrix
 
-  include Musa::Darwin
-  include Musa::Markov
-  include Musa::Rules
-  include Musa::Variatio
+    include Musa::Darwin
+    include Musa::Markov
+    include Musa::Rules
+    include Musa::Variatio
 
-  include Musa::MIDIRecorder
-  include Musa::MIDIVoices
+    include Musa::MIDIRecorder
+    include Musa::MIDIVoices
 
-  include Musa::MusicXML
+    include Musa::MusicXML
 
-  include Musa::Transcriptors
+    include Musa::Transcriptors
+  end
 end

data/musa-dsl.gemspec

@@ -12,15 +12,13 @@ Gem::Specification.new do |s|
   s.homepage    = 'https://github.com/javier-sy/musa-dsl'
   s.license     = 'LGPL-3.0-or-later'
 
-  s.required_ruby_version = '~> 3.4'
+  s.required_ruby_version = '>= 3.4.7'
 
-  # TODO para sistema de paquetes de MusaDSL
-  #s.metadata    = {
-    # "source_code_uri" => "https://",
-    # "homepage_uri" => "",
-    # "documentation_uri" => "",
-    # "changelog_uri" => ""
-  #}
+  s.metadata = {
+    'homepage_uri' => s.homepage,
+    'source_code_uri' => s.homepage,
+    'documentation_uri' => 'https://www.rubydoc.info/gems/musa-dsl'
+  }
 
   s.add_runtime_dependency 'prime', '~> 0.1'
   s.add_runtime_dependency 'matrix', '~> 0.4'
@@ -30,9 +28,13 @@ Gem::Specification.new do |s|
 
   s.add_runtime_dependency 'citrus', '~> 3.0'
 
-  s.add_runtime_dependency 'midi-events', '~> 0.6'
-  s.add_runtime_dependency 'midi-parser', '~> 0.4'
+  s.add_runtime_dependency 'midi-events', '~> 0.7'
+  s.add_runtime_dependency 'midi-parser', '~> 0.5'
 
   s.add_development_dependency 'descriptive-statistics', '~> 2.2'
   s.add_development_dependency 'rspec', '~> 3'
+  s.add_development_dependency 'yard', '~> 0.9'
+  s.add_development_dependency 'redcarpet', '~> 3.6'
+  s.add_development_dependency 'webrick', '~> 1.8'
+  s.add_development_dependency 'rack', '~> 2.2'
 end