musalce-server 0.5.1 → 0.8.0

data/lib/bitwig/bitwig.rb

@@ -4,8 +4,24 @@ require_relative 'handler'
 require_relative 'controllers'
 
 module MusaLCEServer
+  # Bitwig Studio integration module.
+  #
+  # Provides support for live coding with Bitwig Studio 5+ through
+  # the MusaLCE for Bitwig controller extension.
+  #
+  # @see https://github.com/javier-sy/MusaLCEforBitwig Controller extension
   module Bitwig
+    # DAW controller for Bitwig Studio.
+    #
+    # Implements the {Daw} interface for Bitwig Studio, providing
+    # transport control, track management, and MIDI routing through
+    # the MusaLCE for Bitwig controller extension.
+    #
+    # @example
+    #   # Started via MusaLCEServer.run('bitwig')
+    #   daw.track('Bass').out.note(60, velocity: 100, duration: 1)
     class Bitwig < Daw
+      # @api private
       def daw_initialize(midi_devices:, clock:, osc_server:, osc_client:, logger:)
         super
 
@@ -17,6 +33,11 @@ module MusaLCEServer
         return controllers.tracks, handler
       end
 
+      # Retrieves a track by name.
+      #
+      # @param name [String] the track name as configured in Bitwig
+      # @param all [Boolean] if true, returns array; otherwise returns single track
+      # @return [Track, Array<Track>] the track or array containing the track
       def track(name, all: false)
         if all
           [@tracks[name]]
@@ -25,26 +46,37 @@ module MusaLCEServer
         end
       end
 
+      # Starts playback in Bitwig.
+      # @return [void]
       def play
         @handler.play
         super
       end
 
+      # Stops playback in Bitwig.
+      # @return [void]
       def stop
         @handler.stop
         super
       end
 
+      # Continues playback from current position.
+      # @return [void]
       def continue
         @handler.continue
         super
       end
 
+      # Moves playhead to specified bar position.
+      # @param position [Numeric] the bar number (1-based)
+      # @return [void]
       def goto(position)
         @handler.goto(position)
         super
       end
 
+      # Starts recording in Bitwig.
+      # @return [void]
       def record
         @handler.record
         super

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