musalce-server 0.5.1 → 0.8.1

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

data/lib/musalce-server.rb

@@ -4,10 +4,43 @@ require 'osc-ruby'
 require 'osc-ruby/em_server'
 
 require_relative 'version'
+require_relative 'surface'
+require_relative 'surface-bridge'
 require_relative 'live/live'
 require_relative 'bitwig/bitwig'
 
+# Musa Live Coding Environment Server.
+#
+# This module provides the main entry point for the MusaLCE server,
+# which enables live coding with Ableton Live 11+ and Bitwig Studio 5+.
+#
+# The server provides:
+# - OSC communication with DAW controller extensions
+# - MIDI device management and routing
+# - A REPL (Read-Eval-Print-Loop) for interactive live coding
+# - Integration with Musa-DSL sequencer for music composition
+#
+# @example Starting the server for Bitwig Studio
+#   MusaLCEServer.run('bitwig')
+#
+# @example Starting the server for Ableton Live
+#   MusaLCEServer.run('live')
+#
+# @see Daw Base class for DAW controllers
+# @see Bitwig::Bitwig Bitwig Studio driver
+# @see Live::Live Ableton Live driver
 module MusaLCEServer
+  # Starts the MusaLCE server for the specified DAW.
+  #
+  # This method initializes the DAW controller, sets up the REPL environment,
+  # and starts the main server loop. The server runs until `shutdown` is called from the REPL.
+  #
+  # @param daw_name [String] the DAW to connect to ('bitwig' or 'live')
+  # @return [void]
+  # @raise [ArgumentError] if daw_name is nil or not a supported DAW
+  #
+  # @example
+  #   MusaLCEServer.run('bitwig')
   def self.run(daw_name)
     raise ArgumentError, 'A daw must be specified. Options: \'bitwig\' or \'live\'' unless daw_name
     raise ArgumentError, "Incompatible DAW '#{daw_name}'. Options: 'bitwig' or 'live'" unless %w[bitwig live].include?(daw_name)

data/lib/surface-bridge.rb

@@ -0,0 +1,171 @@
+require 'osc-ruby'
+
+module MusaLCEServer
+  # OSC bridge between the server-side {Surface} and the physical
+  # control surface (Stream Deck, …) reached through the chain
+  # MusaLCEServer ↔ MusaLCEforXXX ↔ Pulso Bridge ↔ plugin.
+  #
+  # Two responsibilities:
+  #
+  # 1. **Outbound emission** — translates {Surface} state changes
+  #    and sync requests into +/musalce/surface/*+ OSC messages
+  #    sent on the existing UDP client (port 10001, shared with
+  #    {Daw}).
+  #
+  # 2. **Inbound dispatch** — receives +/musalce/surface/*+ messages
+  #    on the OSC server (EM reactor thread), enqueues them, and
+  #    drains the queue on the sequencer tick thread via
+  #    {#drain}. This is critical: inventory mutations and trigger
+  #    dispatch may invoke arbitrary user DSL code (+play+, +at+,
+  #    +launch+, …) which must run on the sequencer thread.
+  #
+  # Wired up by {Daw#initialize}; expected to be the sole emitter
+  # of +/musalce/surface/*+ on the server side.
+  class SurfaceBridge
+    # @return [Surface] the surface this bridge dispatches inbound
+    #   messages to; set during {Daw} initialization after both
+    #   instances exist.
+    attr_accessor :surface
+
+    # @param osc_client [OSC::Client] outbound OSC client (shared
+    #   with the active {Handler})
+    # @param sequencer [Musa::Sequencer::Sequencer] used to launch
+    #   user-defined event handlers in response to surface triggers
+    # @param logger [Logger] the logger
+    def initialize(osc_client, sequencer, logger:)
+      @client = osc_client
+      @sequencer = sequencer
+      @logger = logger
+      @inbox = Queue.new
+    end
+
+    # Sends +/musalce/surface/sync_request+ outbound. Used on
+    # server startup to ask Pulso Bridge (via the DAW extension) to
+    # dump its current inventory. The reply arrives as a sequence
+    # of +inventory/begin+, +inventory/add+ ..., +inventory/end+.
+    # @return [void]
+    def request_sync
+      send_osc '/musalce/surface/sync_request'
+    end
+
+    # Sends +/musalce/surface/state/<prop>+ for a property change.
+    #
+    # One address per property so the Java relay and the surface
+    # plugin can dispatch on a fixed argument layout per address
+    # (event + N typed args). All values are serialized to strings
+    # on the wire — receivers parse them based on the address.
+    # Keeps the Java forwarder generic without inspecting typetags.
+    #
+    # @param event [Symbol] the event the control is bound to
+    # @param prop [Symbol] the property name (+:message+,
+    #   +:enabled+, +:value+, +:range+, …)
+    # @param value [Array<Object>] one or more values for the
+    #   property (e.g. one for +:message+, two for +:range+)
+    # @return [void]
+    def send_state(event:, prop:, value:)
+      args = value.map { |v| serialize_arg(v) }
+      send_osc "/musalce/surface/state/#{prop}", event.to_s, *args
+    end
+
+    # Registers all inbound +/musalce/surface/*+ handlers on the
+    # given OSC server. Each handler enqueues the message; actual
+    # processing happens on {#drain}.
+    #
+    # @param osc_server [OSC::EMServer]
+    # @return [void]
+    def register_inbound(osc_server)
+      osc_server.add_method('/musalce/surface/inventory/begin') do |_msg|
+        @inbox << [:inventory_begin]
+      end
+
+      osc_server.add_method('/musalce/surface/inventory/add') do |msg|
+        args = msg.to_a
+        @inbox << [:inventory_add, args[0], args[1]]
+      end
+
+      osc_server.add_method('/musalce/surface/inventory/remove') do |msg|
+        @inbox << [:inventory_remove, msg.to_a[0]]
+      end
+
+      osc_server.add_method('/musalce/surface/inventory/end') do |_msg|
+        @inbox << [:inventory_end]
+      end
+
+      osc_server.add_method('/musalce/surface/state_request') do |_msg|
+        @inbox << [:state_request]
+      end
+
+      osc_server.add_method('/musalce/surface/trigger') do |msg|
+        args = msg.to_a
+        @inbox << [:trigger, args[0], (args[1] || '').to_s]
+      end
+    end
+
+    # Drains the inbound queue. Called from the sequencer tick
+    # thread (via +before_tick+) so every dispatched action runs in
+    # a context where DSL methods like +launch+, +play+, +at+ are
+    # safe to invoke.
+    # @return [void]
+    # @api private
+    def drain
+      loop do
+        msg = @inbox.pop(true)
+        dispatch(msg)
+      end
+    rescue ThreadError
+      # Queue empty — done draining.
+    end
+
+    private def dispatch(msg)
+      kind = msg[0]
+      case kind
+      when :inventory_begin
+        @surface.begin_inventory
+      when :inventory_add
+        event, type = msg[1], msg[2]
+        if event.nil? || type.nil?
+          @logger.warn "/musalce/surface/inventory/add missing event or type (#{msg.inspect})"
+        else
+          @surface.add_control(event, type)
+        end
+      when :inventory_remove
+        event = msg[1]
+        @surface.remove_control(event) unless event.nil?
+      when :inventory_end
+        @surface.end_inventory
+      when :state_request
+        @surface.emit_full_state
+      when :trigger
+        event, payload = msg[1], msg[2]
+        if event.nil? || event.to_s.empty?
+          @logger.warn '/musalce/surface/trigger received without event'
+        elsif !@surface.known?(event)
+          @logger.warn "/musalce/surface/trigger for unknown event #{event.inspect}; ignoring"
+        else
+          @sequencer.launch(event.to_sym, payload)
+        end
+      end
+    rescue StandardError => e
+      @logger.error "Error dispatching surface message #{msg.inspect}: #{e.class}: #{e.message}"
+    end
+
+    # All values cross the wire as strings: this lets the Java
+    # relay forward generically without inspecting OSC typetags,
+    # and lets the plugin parse per-property. Receivers know how
+    # to interpret each value from the OSC address.
+    private def serialize_arg(v)
+      v.nil? ? '' : v.to_s
+    end
+
+    private def send_osc(address, *args)
+      counter = 0
+      begin
+        @client.send OSC::Message.new(address, *args)
+      rescue Errno::ECONNREFUSED
+        counter += 1
+        @logger.warn "Errno::ECONNREFUSED sending #{address} #{args}. Retrying... (#{counter})"
+        retry if counter < 3
+      end
+    end
+  end
+end