musalce-server 0.5.1 → 0.8.1

data/lib/bitwig/controllers.rb

@@ -2,7 +2,19 @@ require_relative 'tracks'
 
 module MusaLCEServer
   module Bitwig
+    # Manages Bitwig controller scripts and their MIDI channels.
+    #
+    # Controllers in Bitwig represent hardware MIDI devices configured
+    # through the MusaLCE controller extension. Each controller has
+    # 16 channels that can be named and mapped to tracks.
+    #
+    # @api private
     class Controllers
+      # Creates a new controllers manager.
+      #
+      # @param midi_devices [MIDIDevices] the MIDI devices manager
+      # @param clock [Musa::Clock::InputMidiClock] the MIDI clock
+      # @param logger [Logger] the logger
       def initialize(midi_devices, clock:, logger:)
         @midi_devices = midi_devices
         @clock = clock
@@ -11,8 +23,14 @@ module MusaLCEServer
         @tracks = Tracks.new(logger: logger)
       end
 
+      # @!attribute [r] tracks
+      #   @return [Tracks] the tracks collection
       attr_reader :tracks
 
+      # Registers or updates the list of available controllers.
+      #
+      # @param controllers [Array<String>] controller names from Bitwig
+      # @return [void]
       def register_controllers(controllers)
         to_delete = @controllers.keys - controllers
 
@@ -31,6 +49,12 @@ module MusaLCEServer
         end
       end
 
+      # Registers a controller with its port and clock settings.
+      #
+      # @param name [String] the controller name
+      # @param port_name [String] the MIDI port name
+      # @param is_clock [Boolean] whether this controller provides MIDI clock
+      # @return [void]
       def register_controller(name:, port_name:, is_clock:)
         controller = @controllers[name]
         controller.port_name = port_name
@@ -38,6 +62,13 @@ module MusaLCEServer
         @logger.info "Controller #{name} defined with port_name #{port_name} clock #{is_clock}"
       end
 
+      # Updates a controller's name and settings.
+      #
+      # @param old_name [String] the current controller name
+      # @param new_name [String] the new controller name
+      # @param port_name [String] the MIDI port name
+      # @param is_clock [Boolean] whether this controller provides MIDI clock
+      # @return [void]
       def update_controller(old_name:, new_name:, port_name:, is_clock:)
         controller = @controllers.delete(old_name)
         @controllers[new_name] = controller
@@ -49,6 +80,11 @@ module MusaLCEServer
         @logger.info "Controller #{old_name} updated as #{new_name} with port_name #{port_name} clock #{is_clock}"
       end
 
+      # Registers channel names for a controller.
+      #
+      # @param controller_name [String] the controller name
+      # @param channels [Array<String>] channel names (up to 16)
+      # @return [void]
       def register_channels(controller_name:, channels:)
         controller = @controllers[controller_name]
 
@@ -60,7 +96,20 @@ module MusaLCEServer
       end
     end
 
+    # Represents a MIDI controller in Bitwig.
+    #
+    # A controller corresponds to a hardware MIDI device with 16 channels
+    # that can be routed to tracks.
+    #
+    # @api private
     class Controller
+      # Creates a new controller.
+      #
+      # @param name [String] the controller name
+      # @param midi_devices [MIDIDevices] the MIDI devices manager
+      # @param clock [Musa::Clock::InputMidiClock] the MIDI clock
+      # @param tracks [Tracks] the tracks collection
+      # @param logger [Logger] the logger
       def initialize(name, midi_devices, clock, tracks, logger:)
         @midi_devices = midi_devices
         @clock = clock
@@ -73,15 +122,34 @@ module MusaLCEServer
         @channels = Array.new(16) { |channel| Channel.new(self, tracks, channel, logger: logger) }
       end
 
+      # @!attribute port_name
+      #   @return [String] the MIDI port name
       attr_accessor :port_name
+
+      # @!attribute [r] name
+      #   @return [String] the controller name
+      # @!attribute [r] midi_device
+      #   @return [MIDIDevice, nil] the associated MIDI device
+      # @!attribute [r] channels
+      #   @return [Array<Channel>] the 16 MIDI channels
+      # @!attribute [r] is_clock
+      #   @return [Boolean] whether this controller provides MIDI clock
       attr_reader :name, :midi_device, :channels, :is_clock
 
+      # Sets whether this controller provides MIDI clock.
+      #
+      # @param new_is_clock [Boolean] the clock setting
+      # @return [void]
       def is_clock=(new_is_clock)
         # TODO when new_is_clock is false look if another controller is true, else leave clock input as nil (the user has not selected any clock!)
         @is_clock = new_is_clock
         update_clock
       end
 
+      # Sets the controller name and finds the associated MIDI device.
+      #
+      # @param new_name [String] the controller name
+      # @return [void]
       def name=(new_name)
         @name = new_name
         @midi_device = @midi_devices.find(@name)
@@ -100,7 +168,18 @@ module MusaLCEServer
       end
     end
 
+    # Represents a MIDI channel on a controller.
+    #
+    # Each channel can be named and mapped to a track for MIDI output.
+    #
+    # @api private
     class Channel
+      # Creates a new channel.
+      #
+      # @param controller [Controller] the parent controller
+      # @param tracks [Tracks] the tracks collection
+      # @param channel_number [Integer] the MIDI channel (0-15)
+      # @param logger [Logger] the logger
       def initialize(controller, tracks, channel_number, logger:)
         @controller = controller
         @tracks = tracks
@@ -108,8 +187,16 @@ module MusaLCEServer
         @logger = logger
       end
 
+      # @!attribute [r] channel_number
+      #   @return [Integer] the MIDI channel number (0-15)
+      # @!attribute [r] name
+      #   @return [String, nil] the channel name
       attr_reader :channel_number, :name
 
+      # Sets the channel name and associates it with a track.
+      #
+      # @param new_name [String] the channel name
+      # @return [void]
       def name=(new_name)
         @tracks[@name]&._forget_channel
         @name = new_name
@@ -117,10 +204,16 @@ module MusaLCEServer
         @tracks[@name]._channel = self
       end
 
+      # Returns the MIDI voice for this channel.
+      #
+      # @return [Musa::MIDIVoices::MIDIVoice] the MIDI voice for output
       def output
         @controller.midi_device.channels[@channel_number]
       end
 
+      # Returns a string representation of this channel.
+      #
+      # @return [String] description including channel number, name, port, and controller
       def to_s
         "<Channel #{@channel_number} '#{@name}' on port '#{@controller.port_name}' (controller '#{@controller.name}')>"
       end

data/lib/bitwig/handler.rb

@@ -2,7 +2,21 @@ require_relative '../daw'
 
 module MusaLCEServer
   module Bitwig
+    # OSC message handler for Bitwig Studio.
+    #
+    # Handles communication with the MusaLCE for Bitwig controller extension,
+    # processing incoming OSC messages for controller and channel registration,
+    # and sending transport commands.
+    #
+    # @api private
     class Handler < ::MusaLCEServer::Handler
+      # Creates a new Bitwig handler.
+      #
+      # @param osc_server [OSC::EMServer] the OSC server for receiving messages
+      # @param osc_client [OSC::Client] the OSC client for sending messages
+      # @param controllers [Controllers] the controllers manager
+      # @param sequencer [Musa::Sequencer::Sequencer] the sequencer instance
+      # @param logger [Logger] the logger
       def initialize(osc_server, osc_client, controllers, sequencer, logger:)
         super()
 
@@ -44,36 +58,52 @@ module MusaLCEServer
         end
       end
 
+      # Requests synchronization of controllers and channels from Bitwig.
+      # @return [void]
       def sync
         @logger.info 'Asking sync'
         send_osc '/musalce4bitwig/sync'
       end
 
+      # Sends play command to Bitwig.
+      # @return [void]
       def play
         @logger.info 'Asking play'
         send_osc '/musalce4bitwig/play'
       end
 
+      # Sends stop command to Bitwig.
+      # @return [void]
       def stop
         @logger.info 'Asking stop'
         send_osc '/musalce4bitwig/stop'
       end
 
+      # Sends continue command to Bitwig.
+      # @return [void]
       def continue
         @logger.info 'Asking continue'
         send_osc '/musalce4bitwig/continue'
       end
 
+      # Moves playhead to specified position.
+      #
+      # @param position [Numeric] the bar number (1-based)
+      # @return [void]
       def goto(position)
         @logger.info "Asking goto #{position}"
         send_osc '/musalce4bitwig/goto', OSC::OSCDouble64.new(((position - 1) * @sequencer.beats_per_bar).to_f)
       end
 
+      # Sends record command to Bitwig.
+      # @return [void]
       def record
         @logger.info 'Asking record'
         send_osc '/musalce4bitwig/record'
       end
 
+      # Sends panic to all tracks.
+      # @return [void]
       def panic!
         @controllers.tracks.each(:panic!)
       end

data/lib/bitwig/tracks.rb

@@ -2,18 +2,35 @@ require 'musa-dsl/core-ext/dynamic-proxy'
 
 module MusaLCEServer
   module Bitwig
+    # Collection of tracks for Bitwig.
+    #
+    # Tracks are created dynamically based on channel names received
+    # from the Bitwig controller extension.
+    #
+    # @api private
     class Tracks
       include Enumerable
 
+      # Creates a new tracks collection.
+      #
+      # @param logger [Logger] the logger
       def initialize(logger:)
         @logger = logger
         @tracks = {}
       end
 
+      # Creates a new track with the given name.
+      #
+      # @param name [String] the track name
+      # @return [Track] the created track
       def create(name)
         @tracks[name] = Track.new(name, logger: @logger)
       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)
@@ -22,16 +39,33 @@ module MusaLCEServer
         end
       end
 
+      # Retrieves a track by name.
+      #
+      # @param name [String] the track name
+      # @return [Track, nil] the track or nil if not found
       def [](name)
         @tracks[name]
       end
 
+      # Sets a track by name.
+      #
+      # @param name [String] the track name
+      # @param track [Track] the track
+      # @return [Track] the track
       def []=(name, track)
         @tracks[name] = track
       end
     end
 
+    # Represents a track in Bitwig with dynamic MIDI output.
+    #
+    # Uses DynamicProxy to allow the output to be reassigned
+    # when channel mappings change.
     class Track
+      # Creates a new track.
+      #
+      # @param name [String] the track name
+      # @param logger [Logger] the logger
       def initialize(name, logger:)
         @name = name
         @logger = logger
@@ -39,17 +73,29 @@ module MusaLCEServer
         @output = Musa::Extension::DynamicProxy::DynamicProxy.new
       end
 
+      # @!attribute [r] name
+      #   @return [String] the track name
       attr_reader :name
 
+      # Disconnects the current channel from this track.
+      # @api private
+      # @return [void]
       def _forget_channel
         @output.receiver = nil
       end
 
+      # Sets the channel for this track.
+      # @api private
+      # @param new_channel [Channel] the channel to assign
+      # @return [void]
       def _channel=(new_channel)
         @logger.info "Assigning #{new_channel} to track '#{@name}'"
         @output.receiver = new_channel.output
       end
 
+      # Returns the MIDI output for this track.
+      #
+      # @return [Musa::Extension::DynamicProxy::DynamicProxy] proxy to the MIDI voice
       def out
         @output
       end

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