musalce-server 0.5.1 → 0.8.0

data/lib/daw.rb

@@ -3,16 +3,59 @@ require 'midi-communications'
 require_relative 'midi-devices'
 
 module MusaLCEServer
+  # @return [Surface, nil] active control surface, set during {Daw}
+  #   initialization. Exposed to the DSL as +surface+ in
+  #   {MusaLCE_Context}; mutating its controls (e.g.
+  #   +surface[:foo].enabled = true+) emits OSC state outbound to
+  #   the DAW extension and on to Pulso Bridge / Stream Deck.
+  class << self
+    attr_accessor :surface
+  end
+
+  # Base class for DAW (Digital Audio Workstation) controllers.
+  #
+  # This class provides the common infrastructure for communicating with
+  # DAWs like Ableton Live and Bitwig Studio. It manages:
+  # - OSC server/client for communication with DAW controller extensions
+  # - MIDI clock synchronization
+  # - Musa-DSL sequencer integration
+  # - MIDI device management
+  # - Transport controls (play, stop, record, etc.)
+  #
+  # Subclasses must implement {#daw_initialize} to set up DAW-specific
+  # handlers and track management.
+  #
+  # @abstract Subclass and implement {#daw_initialize} and {#track}
+  #
+  # @see Bitwig::Bitwig Bitwig Studio implementation
+  # @see Live::Live Ableton Live implementation
   class Daw
+    # Registers a DAW driver class for a given identifier.
+    #
+    # @param daw_id [Symbol] the DAW identifier (:bitwig or :live)
+    # @param daw_class [Class] the DAW controller class to register
+    # @return [void]
+    #
+    # @example
+    #   Daw.register(:bitwig, Bitwig::Bitwig)
     def self.register(daw_id, daw_class)
       @@daws ||= {}
       @@daws[daw_id] = daw_class
     end
 
+    # Creates and returns a new DAW controller instance for the given identifier.
+    #
+    # @param daw_id [Symbol] the DAW identifier (:bitwig or :live)
+    # @return [Daw] a new instance of the registered DAW controller
     def self.daw_controller_for(daw_id)
       @@daws[daw_id].new
     end
 
+    # Creates a new DAW controller instance.
+    #
+    # Sets up OSC server (port 11011) and client (port 10001),
+    # initializes the Musa-DSL sequencer, MIDI clock, and transport.
+    # Calls {#daw_initialize} for DAW-specific setup.
     def initialize
       osc_server = OSC::EMServer.new(11_011)
       osc_client = OSC::Client.new('localhost', 10_001)
@@ -22,70 +65,172 @@ module MusaLCEServer
       @sequencer = Musa::Sequencer::Sequencer.new 4, 24, dsl_context_class: MusaLCE_Context, do_log: true
 
       @clock = Musa::Clock::InputMidiClock.new do_log: true, logger: @sequencer.logger
-      transport = Musa::Transport::Transport.new @clock, sequencer: @sequencer
+      @transport = Musa::Transport::Transport.new @clock, sequencer: @sequencer
 
-      transport.after_stop do
+      @transport.after_stop do
         sequencer.reset
       end
 
       @midi_devices = MIDIDevices.new(@sequencer)
 
+      # Build the surface side: inbound +/musalce/surface/*+
+      # messages land on the EM reactor thread, are enqueued by the
+      # bridge, then drained on the sequencer tick thread via
+      # +before_tick+ — guaranteeing that inventory mutations and
+      # user-defined trigger handlers can safely use any DSL method
+      # (+play+, +at+, +launch+, …). Drainer latency is one tick
+      # (≈20 ms at 120 BPM / 24 PPQN).
+      surface_bridge = SurfaceBridge.new(osc_client, @sequencer, logger: @sequencer.logger)
+      @surface = Surface.new(bridge: surface_bridge, logger: @sequencer.logger)
+      surface_bridge.surface = @surface
+      surface_bridge.register_inbound(osc_server)
+      MusaLCEServer.surface = @surface
+
+      @sequencer.before_tick do |_position|
+        surface_bridge.drain
+      end
+
       @tracks, @handler = daw_initialize(midi_devices: @midi_devices, clock: @clock, osc_server: osc_server, osc_client: osc_client, logger: @sequencer.logger)
 
       @handler.version
       @handler.sync
 
-      Thread.new { transport.start }
+      # Ask Pulso Bridge (through the DAW extension) to dump its
+      # current inventory. The reply re-establishes
+      # +@surface.controls+ from scratch and triggers a full state
+      # re-emit. Sent after +@handler.sync+ so the DAW extension is
+      # known to be alive.
+      surface_bridge.request_sync
+
+      Thread.new { @transport.start }
     end
 
-    attr_reader :clock, :sequencer, :tracks
+    # @!attribute [r] clock
+    #   @return [Musa::Clock::InputMidiClock] the MIDI clock for synchronization
+    # @!attribute [r] sequencer
+    #   @return [Musa::Sequencer::Sequencer] the Musa-DSL sequencer instance
+    # @!attribute [r] transport
+    #   @return [Musa::Transport::Transport] the transport driving the
+    #     sequencer. Exposed so REPL users can register callbacks
+    #     ({Musa::Transport::Transport#on_start},
+    #     {Musa::Transport::Transport#after_stop},
+    #     {Musa::Transport::Transport#before_begin}) that survive across
+    #     DAW Stop/Play cycles — useful for re-installing +on :event+
+    #     handlers, +every+ loops or +at+ schedules that are wiped by
+    #     the built-in +after_stop { sequencer.reset }+ callback.
+    # @!attribute [r] tracks
+    #   @return [Object] the DAW-specific tracks collection
+    # @!attribute [r] surface
+    #   @return [Surface] the control surface (Stream Deck etc.)
+    attr_reader :clock, :sequencer, :transport, :tracks, :surface
 
+    # DAW-specific initialization hook.
+    #
+    # Subclasses must implement this method to set up their specific
+    # handlers and track management.
+    #
+    # @param midi_devices [MIDIDevices] the MIDI devices manager
+    # @param clock [Musa::Clock::InputMidiClock] the MIDI clock
+    # @param osc_server [OSC::EMServer] the OSC server for receiving messages
+    # @param osc_client [OSC::Client] the OSC client for sending messages
+    # @param logger [Logger] the logger instance
+    # @return [Array(Object, Handler)] tuple of [tracks, handler]
+    # @api private
     protected def daw_initialize(midi_devices:, clock:, osc_server:, osc_client:, logger:); end
 
+    # Retrieves a track by name.
+    #
+    # @param name [String] the track name
+    # @param all [Boolean] if true, returns all matching tracks; otherwise returns first match
+    # @return [Object, Array<Object>] the track(s) matching the name
+    # @raise [NotImplementedError] must be implemented by subclasses
+    # @abstract
     def track(name, all: false)
       raise NotImplementedError
     end
 
+    # Starts playback in the DAW.
+    # @return [void]
     def play; end
 
+    # Stops playback in the DAW.
+    # @return [void]
     def stop; end
 
+    # Continues playback from current position.
+    # @return [void]
     def continue; end
 
+    # Moves playhead to specified position.
+    # @param position [Numeric] the bar position to go to
+    # @return [void]
     def goto(position); end
 
+    # Starts recording in the DAW.
+    # @return [void]
     def record; end
 
+    # Sends All Notes Off to all tracks.
+    #
+    # Use this to stop stuck notes after errors or interruptions.
+    # @return [void]
     def panic!
       @tracks.each do |track|
         track.out.all_notes_off
       end
     end
 
+    # Requests track synchronization from the DAW.
+    # @return [void]
     def sync
       @handler.sync
     end
 
+    # Requests the DAW controller extension to reload.
+    # @return [void]
     def reload
       @handler.reload
     end
   end
 
+  # Base class for DAW-specific OSC message handlers.
+  #
+  # Handles communication with DAW controller extensions via OSC.
+  # Subclasses implement DAW-specific message handling.
+  #
+  # @abstract
+  # @api private
   class Handler
+    # Requests the DAW controller extension to reload its configuration.
+    # @return [void]
     def reload
       @logger.info 'Asking controller reset and reload'
       send_osc '/reload'
     end
 
+    # Sends the server version to the DAW controller extension.
+    # @return [void]
     def version
       @logger.info "Sending version #{VERSION}"
       send_osc '/version', VERSION
     end
 
+    # Sends panic (All Notes Off) to all tracks.
+    # @return [void]
+    # @raise [NotImplementedError] must be implemented by subclasses
+    # @abstract
     def panic!
       raise NotImplementedError
     end
 
+    # Sends an OSC message to the DAW controller.
+    #
+    # Includes retry logic for connection refused errors.
+    #
+    # @param message [String] the OSC address pattern
+    # @param args [Array] optional arguments to send
+    # @return [void]
+    # @api private
     private def send_osc(message, *args)
       counter = 0
       begin
@@ -98,17 +243,61 @@ module MusaLCEServer
     end
   end
 
+  # DSL context for the MusaLCE REPL environment.
+  #
+  # Extends the Musa-DSL sequencer context with REPL customization
+  # capabilities, allowing users to import additional modules and
+  # access the binding for evaluation.
+  #
+  # @api private
   class MusaLCE_Context < Musa::Sequencer::Sequencer::DSLContext
     include Musa::REPL::CustomizableDSLContext
 
+    # Returns the binding for this context.
+    #
+    # Used by the REPL for evaluating user code.
+    #
+    # @return [Binding] the context binding
     def binder
       @__binder ||= binding
     end
 
+    # Imports modules into this context.
+    #
+    # Allows users to extend the REPL environment with additional
+    # functionality by including modules.
+    #
+    # @param modules [Array<Module>] modules to include
+    # @return [void]
+    #
+    # @example
+    #   import(MyHelperModule, AnotherModule)
     def import(*modules)
       modules.each do |m|
         self.class.include(m)
       end
     end
+
+    # @return [Surface] the active control surface (Stream Deck and
+    #   similar hardware reached via Pulso Bridge).
+    #
+    # The surface holds typed controls keyed by event name. Controls
+    # appear in the inventory once Pulso Bridge advertises them over
+    # OSC; before that, +surface[:event]+ returns +nil+.
+    #
+    # @example single-line state write via {Control#set}
+    #   on :launch_chorus do |payload|
+    #     launch :chorus_section
+    #     surface[:launch_chorus]&.set(enabled: true, message: "Chorus on")
+    #   end
+    #
+    # @example reading state to toggle
+    #   on :master_mute do
+    #     surface[:master_mute]&.toggle!
+    #   end
+    def surface
+      MusaLCEServer.surface or
+        raise 'No Surface available (DAW not initialized)'
+    end
   end
 end

data/lib/live/handler.rb

@@ -2,7 +2,19 @@ require_relative '../daw'
 
 module MusaLCEServer
   module Live
+    # OSC message handler for Ableton Live.
+    #
+    # Handles communication with the MusaLCE for Live MIDI Remote Script,
+    # processing incoming OSC messages for track registration and routing.
+    #
+    # @api private
     class Handler < ::MusaLCEServer::Handler
+      # Creates a new Live handler.
+      #
+      # @param osc_server [OSC::EMServer] the OSC server for receiving messages
+      # @param osc_client [OSC::Client] the OSC client for sending messages
+      # @param tracks [Tracks] the tracks manager
+      # @param logger [Logger] the logger
       def initialize(osc_server, osc_client, tracks, logger:)
         super()
 
@@ -47,6 +59,8 @@ module MusaLCEServer
         end
       end
 
+      # Requests track information from Live.
+      # @return [void]
       def sync
         send_osc '/musalce4live/tracks'
       end

data/lib/live/live.rb

@@ -4,8 +4,27 @@ require_relative 'handler'
 require_relative 'tracks'
 
 module MusaLCEServer
+  # Ableton Live integration module.
+  #
+  # Provides support for live coding with Ableton Live 11+ through
+  # the MusaLCE for Live MIDI Remote Script.
+  #
+  # @see https://github.com/javier-sy/MusaLCEforLive MIDI Remote Script
   module Live
+    # DAW controller for Ableton Live.
+    #
+    # Implements the {Daw} interface for Ableton Live, providing
+    # track management and MIDI routing through the MusaLCE for Live
+    # MIDI Remote Script.
+    #
+    # @note Transport controls (play, stop, etc.) are not implemented
+    #   for Live as the MIDI Remote Script API doesn't support them.
+    #
+    # @example
+    #   # Started via MusaLCEServer.run('live')
+    #   daw.track('Bass').out.note(60, velocity: 100, duration: 1)
     class Live < Daw
+      # @api private
       def daw_initialize(midi_devices:, clock:, osc_server:, osc_client:, logger:)
         super
         tracks = Tracks.new(midi_devices, logger: logger)
@@ -16,6 +35,13 @@ module MusaLCEServer
         return tracks, handler
       end
 
+      # Retrieves track(s) by name.
+      #
+      # Unlike Bitwig, Live can have multiple tracks with the same name.
+      #
+      # @param name [String] the track name
+      # @param all [Boolean] if true, returns all matching tracks; otherwise returns first match
+      # @return [Track, Array<Track>] the track(s) matching the name
       def track(name, all: false)
         if all
           @tracks.find_by_name(name)
@@ -24,6 +50,16 @@ module MusaLCEServer
         end
       end
 
+      # Sets the MIDI device to use for clock synchronization.
+      #
+      # @param midi_device_name [String] default device name to search for
+      # @param manufacturer [String, nil] optional manufacturer filter
+      # @param model [String, nil] optional model filter
+      # @param name [String, nil] optional name filter (overrides midi_device_name)
+      # @return [void]
+      #
+      # @example
+      #   daw.midi_sync('IAC Driver Bus 1')
       def midi_sync(midi_device_name, manufacturer: nil, model: nil, name: nil)
         name ||= midi_device_name
 

data/lib/live/tracks.rb

@@ -2,7 +2,17 @@ require 'musa-dsl/core-ext/dynamic-proxy'
 
 module MusaLCEServer
   module Live
+    # Represents a track in Ableton Live.
+    #
+    # Tracks in Live are identified by their internal ID and can have
+    # MIDI input routing configured. The output is dynamically proxied
+    # to allow routing changes without recreating the track object.
     class Track
+      # Creates a new track.
+      #
+      # @param id [Integer] the Live track ID
+      # @param midi_devices [MIDIDevices] the MIDI devices manager
+      # @param logger [Logger] the logger
       def initialize(id, midi_devices, logger:)
         @id = id
         @midi_devices = midi_devices
@@ -11,35 +21,49 @@ module MusaLCEServer
         @output = Musa::Extension::DynamicProxy::DynamicProxy.new
       end
 
+      # @!attribute [r] id
+      #   @return [Integer] the Live track ID
+      # @!attribute [r] name
+      #   @return [String, nil] the track name
       attr_reader :id, :name
 
+      # Returns the MIDI output for this track.
+      #
+      # @return [Musa::Extension::DynamicProxy::DynamicProxy] proxy to the MIDI voice
       def out
         @output
       end
 
+      # @api private
       def _update_name(value)
         @name = value
         @logger.info "track #{@id} assigned name #{@name}"
       end
 
+      # @api private
       def _update_has_midi_input(value);
       @has_midi_input = value == 1;
       end
+      # @api private
       def _update_has_midi_output(value);
       @has_midi_output = value == 1;
       end
+      # @api private
       def _update_has_audio_input(value);
       @has_audio_input = value == 1;
       end
+      # @api private
       def _update_has_audio_output(value);
       @has_audio_output = value == 1;
       end
 
+      # @api private
       def _update_current_input_routing(value)
         @current_input_routing = value
         _update_current_input_sub_routing(@current_input_sub_routing)
       end
 
+      # @api private
       def _update_current_input_sub_routing(value)
         @current_input_sub_routing = value
 
@@ -59,24 +83,40 @@ module MusaLCEServer
         @output.receiver = effective_midi_voice
       end
 
+      # @api private
       def _update_current_output_routing(value);
       @current_output_routing = value
       end
 
+      # @api private
       def _update_current_output_sub_routing(value);
       @current_output_sub_routing = value
       end
     end
 
+    # Collection of tracks for Ableton Live.
+    #
+    # Manages track registration and lookup, automatically creating
+    # and updating tracks based on OSC messages from the MIDI Remote Script.
+    #
+    # @api private
     class Tracks
       include Enumerable
 
+      # Creates a new tracks collection.
+      #
+      # @param midi_devices [MIDIDevices] the MIDI devices manager
+      # @param logger [Logger] the logger
       def initialize(midi_devices, logger:)
         @midi_devices = midi_devices
         @logger = logger
         @tracks = {}
       end
 
+      # Processes a batch of track data, creating, updating, and deleting tracks.
+      #
+      # @param tracks_data [Array<Array>] array of track data arrays
+      # @return [void]
       def grant_registry_collection(tracks_data)
         tracks_to_delete = Set[*@tracks.keys]
 
@@ -91,6 +131,19 @@ module MusaLCEServer
         end
       end
 
+      # Registers or updates a track with the provided data.
+      #
+      # @param id [Integer] the track ID
+      # @param name [String, nil] the track name
+      # @param has_midi_input [Integer, nil] 1 if track has MIDI input
+      # @param has_midi_output [Integer, nil] 1 if track has MIDI output
+      # @param has_audio_input [Integer, nil] 1 if track has audio input
+      # @param has_audio_output [Integer, nil] 1 if track has audio output
+      # @param current_input_routing [String, nil] input routing device name
+      # @param current_input_sub_routing [String, nil] input sub-routing (channel)
+      # @param current_output_routing [String, nil] output routing device name
+      # @param current_output_sub_routing [String, nil] output sub-routing
+      # @return [void]
       def grant_registry(id, name = nil,
                          has_midi_input = nil, has_midi_output = nil,
                          has_audio_input = nil, has_audio_output = nil,
@@ -115,6 +168,10 @@ module MusaLCEServer
         track._update_current_output_sub_routing(current_output_sub_routing) if current_output_sub_routing
       end
 
+      # Iterates over all tracks.
+      #
+      # @yield [Track] each track
+      # @return [Enumerator] if no block given
       def each(&block)
         if block_given?
           @tracks.values.each(&block)
@@ -123,12 +180,20 @@ module MusaLCEServer
         end
       end
 
+      # Retrieves a track by ID.
+      #
+      # @param id [Integer] the track ID
+      # @return [Track, nil] the track or nil if not found
       def [](id)
         @tracks[id]
       end
 
-      # TODO adaptar a contrato y semántica de Bitwig (en bitwig sólo hay un track con un nombre determinado, el id no existe)
-
+      # Finds all tracks with the given name.
+      #
+      # @param name [String] the track name
+      # @return [Array<Track>] matching tracks
+      #
+      # @todo Adapt to Bitwig semantics where track names are unique
       def find_by_name(name)
         @tracks.values.select { |_| _.name == name }
       end

data/lib/midi-devices.rb

@@ -3,9 +3,22 @@ require 'midi-communications'
 require 'musa-dsl/midi/midi-voices'
 
 module MusaLCEServer
+  # Manages available MIDI output devices.
+  #
+  # Provides enumeration and lookup of MIDI devices, automatically
+  # synchronizing with the system's available devices.
+  #
+  # @example Iterating over devices
+  #   midi_devices.each { |device| puts device.name }
+  #
+  # @example Finding a device by name suffix
+  #   device = midi_devices.find('IAC Driver Bus 1')
   class MIDIDevices
     include Enumerable
 
+    # Creates a new MIDI devices manager.
+    #
+    # @param sequencer [Musa::Sequencer::Sequencer] the sequencer for MIDI voice management
     def initialize(sequencer)
       @sequencer = sequencer
       @low_level_devices = {}
@@ -13,6 +26,11 @@ module MusaLCEServer
       sync
     end
 
+    # Synchronizes the device list with system MIDI devices.
+    #
+    # Adds newly connected devices and removes disconnected ones.
+    #
+    # @return [void]
     def sync
       names = @low_level_devices.keys
 
@@ -30,15 +48,32 @@ module MusaLCEServer
       end
     end
 
+    # Retrieves a device by exact name.
+    #
+    # @param name [String] the exact device name
+    # @return [MIDIDevice, nil] the device or nil if not found
     def [](name)
       @low_level_devices[name]
     end
 
+    # Finds a device by name suffix.
+    #
+    # Useful when device names include prefixes that vary by system.
+    #
+    # @param name [String] the name suffix to match
+    # @return [MIDIDevice, nil] the first matching device or nil
+    #
+    # @example
+    #   device = midi_devices.find('Bus 1')  # Matches 'IAC Driver Bus 1'
     def find(name)
       full_name = @low_level_devices.keys.find { |_| _.end_with?(name) }
       @low_level_devices[full_name]
     end
 
+    # Iterates over all MIDI devices.
+    #
+    # @yield [MIDIDevice] each device
+    # @return [Enumerator] if no block given
     def each(&block)
       if block_given?
         @low_level_devices.values.each(&block)
@@ -47,27 +82,49 @@ module MusaLCEServer
       end
     end
   end
-  
+
+  # Wrapper for a MIDI output device with voice management.
+  #
+  # Provides access to individual MIDI channels as voices and
+  # panic functionality.
   class MIDIDevice
+    # Creates a new MIDI device wrapper.
+    #
+    # @param sequencer [Musa::Sequencer::Sequencer] the sequencer for voice management
+    # @param low_level_device [MIDICommunications::Output] the underlying MIDI device
     def initialize(sequencer, low_level_device)
       @low_level_device = low_level_device
       @voices = Musa::MIDIVoices::MIDIVoices.new(sequencer: sequencer, output: low_level_device, channels: 0..15, do_log: true)
     end
 
+    # @!attribute [r] low_level_device
+    #   @return [MIDICommunications::Output] the underlying MIDI output device
     attr_reader :low_level_device
 
+    # Returns the device name.
+    #
+    # @return [String] the device name
     def name
       @low_level_device.name
     end
 
+    # Sends All Notes Off and reset to all channels.
+    #
+    # @return [void]
     def panic!
       @voices.panic reset: true
     end
 
+    # Returns the MIDI channels/voices for this device.
+    #
+    # @return [Array<Musa::MIDIVoices::MIDIVoice>] the 16 MIDI channels
     def channels
       @voices.voices
     end
 
+    # Returns the display name of the device.
+    #
+    # @return [String] the display name
     def to_s
       @low_level_device.display_name
     end