musalce-server 0.5.1 → 0.8.0

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

data/lib/surface.rb

@@ -0,0 +1,369 @@
+require 'set'
+
+module MusaLCEServer
+  # Authoritative model of the physical control surface (Stream Deck
+  # buttons, encoders, …) as seen from the server.
+  #
+  # The surface is **the abstraction shared with hardware** but
+  # surface-agnostic: it knows only about named controls with a type
+  # and dynamic state. Each control is keyed by its **event name** — a
+  # Symbol (e.g. +:launch_chorus+) that doubles as the identifier used
+  # with the sequencer's +on+/+launch+ mechanism when the control
+  # fires. In MusaLCE the unit of interaction is always the *event*;
+  # the surface is the physical face of one or more events.
+  #
+  # Ownership of the two data axes:
+  #
+  # - **Inventory** (which controls exist and their type) flows
+  #   inbound from Pulso Bridge through the DAW extension; the server
+  #   trusts what it receives (Pulso validates type consistency
+  #   across physical instances).
+  # - **State** (message, enabled, value, …) is owned by the server:
+  #   the score writes to +surface[:event]+ and changes propagate
+  #   outbound on +/musalce/surface/state/<prop>+.
+  #
+  # Inventory may arrive as a full dump (between +inventory/begin+
+  # and +inventory/end+, in which case events absent from the dump
+  # are purged at end) or as runtime deltas (+inventory/add+ /
+  # +inventory/remove+). Re-adding an event with the same type
+  # preserves its state; a type change replaces the control and
+  # resets state.
+  #
+  # All mutating methods are expected to run on the sequencer tick
+  # thread (inbound OSC messages are routed there by
+  # {SurfaceBridge}). Score code writing +surface[:event].xxx =+ ...
+  # also runs on that thread (inside +at+/+every+/+on+ blocks),
+  # which keeps access serial without explicit locking.
+  class Surface
+    # @param bridge [SurfaceBridge] the bridge used to emit state outbound
+    # @param logger [Logger] the logger
+    def initialize(bridge:, logger:)
+      @bridge = bridge
+      @logger = logger
+      @controls = {}
+      @pending_events = nil
+    end
+
+    # Returns the control for the given event, or +nil+ if unknown.
+    #
+    # A control becomes known once its inventory entry has been
+    # received from the surface. Score code that runs before that
+    # should use safe navigation (+surface[:foo]&.enabled = true+)
+    # or guard with {#known?}.
+    #
+    # @param event [Symbol, String]
+    # @return [Control, nil]
+    def [](event)
+      @controls[event.to_sym]
+    end
+
+    # @return [Array<Symbol>] all known control events
+    def events
+      @controls.keys
+    end
+
+    # @param event [Symbol, String]
+    # @return [Boolean] whether a control with this event is in the inventory
+    def known?(event)
+      @controls.key?(event.to_sym)
+    end
+
+    # Begins a full inventory dump. Events that are not re-added before
+    # {#end_inventory} are purged.
+    # @return [void]
+    # @api private
+    def begin_inventory
+      @pending_events = Set.new
+    end
+
+    # Registers (or refreshes) a control in the inventory.
+    #
+    # If a control with the same event and type already exists, its
+    # state is preserved. If the type differs, the existing control
+    # is replaced with a fresh instance (state reset).
+    #
+    # @param event [Symbol, String]
+    # @param type [Symbol, String] one of +:toggle+, +:trigger+, +:encoder+
+    # @return [Control] the (possibly new) control
+    # @api private
+    def add_control(event, type)
+      event = event.to_sym
+      type = type.to_sym
+      existing = @controls[event]
+
+      if existing && existing.class.type_name == type
+        ctrl = existing
+      else
+        ctrl = Control.create(type, event: event, surface: self)
+        @controls[event] = ctrl
+        @logger.info "Surface: added control #{event} (#{type})"
+      end
+
+      @pending_events << event if @pending_events
+      ctrl
+    end
+
+    # Removes a control from the inventory and drops its state.
+    # @param event [Symbol, String]
+    # @return [Control, nil] the removed control, or nil if unknown
+    # @api private
+    def remove_control(event)
+      event = event.to_sym
+      removed = @controls.delete(event)
+      @logger.info "Surface: removed control #{event}" if removed
+      removed
+    end
+
+    # Ends a full inventory dump. Any event present before the dump
+    # but not re-added between {#begin_inventory} and this call is
+    # purged. Re-emits all state so the surface re-syncs after the
+    # round-trip.
+    # @return [void]
+    # @api private
+    def end_inventory
+      if @pending_events
+        stale = @controls.keys - @pending_events.to_a
+        stale.each do |event|
+          @controls.delete(event)
+          @logger.info "Surface: purged stale control #{event}"
+        end
+        @pending_events = nil
+      end
+      emit_full_state
+    end
+
+    # Re-emits state for every known control. Used after an
+    # inventory dump or in response to a +state_request+ from the
+    # surface side.
+    # @return [void]
+    # @api private
+    def emit_full_state
+      @controls.each_value(&:emit_all_state)
+    end
+
+    # Called by a Control when one of its properties changes; relays
+    # to the bridge.
+    # @param event [Symbol]
+    # @param prop [Symbol]
+    # @param value [Array<Object>] OSC-serializable values
+    # @return [void]
+    # @api private
+    def emit_state(event, prop, *value)
+      @bridge.send_state(event: event, prop: prop, value: value)
+    end
+  end
+
+  # Abstract base for all controls on a {Surface}.
+  #
+  # Subclasses declare a {.type_name} matching the inventory string
+  # received from the surface, expose typed state accessors, and
+  # implement {#emit_all_state} to push their current state outbound.
+  #
+  # Setting a property emits exactly one OSC
+  # +/musalce/surface/state/<prop>+ message; the setter is therefore
+  # the canonical mutation point. Direct manipulation of instance
+  # variables bypasses emission.
+  class Control
+    # @return [Symbol] the event name this control is bound to
+    attr_reader :event
+
+    # @return [String, nil] the displayable message, +nil+ if unset
+    attr_reader :message
+
+    def initialize(event:, surface:)
+      @event = event
+      @surface = surface
+      @message = nil
+    end
+
+    # Sets the displayable message. Two-line text is allowed; the
+    # surface side is responsible for truncation/wrapping.
+    # @param value [String, nil]
+    # @return [void]
+    def message=(value)
+      @message = value
+      emit(:message, value.to_s)
+    end
+
+    # Sets multiple attributes in a single call. Each key must name a
+    # writable attribute of the receiver's type; unknown keys raise
+    # +ArgumentError+ so a typo can't silently no-op.
+    #
+    # Order of assignment follows the kwargs hash insertion order
+    # (Ruby >= 1.9 guarantees insertion-ordered iteration). Each
+    # assignment goes through the regular setter, so each property
+    # emits its own +/musalce/surface/state/<prop>+ message. This is
+    # intentional: the wire protocol is per-property, and the plugin
+    # merges deltas into the rendered state, so two adjacent
+    # +/state/<prop>+ messages render exactly the same as a single
+    # batched one would.
+    #
+    # @example Toggle
+    #   surface[:launch_chorus].set(enabled: true, message: "Chorus on")
+    # @example Encoder
+    #   surface[:cutoff].set(range: 0..127, value: 64, message: "Cutoff")
+    #
+    # @param attrs [Hash{Symbol => Object}]
+    # @raise [ArgumentError] if a key doesn't correspond to a writer
+    # @return [self] for chaining
+    def set(**attrs)
+      attrs.each do |key, value|
+        writer = :"#{key}="
+        unless respond_to?(writer)
+          raise ArgumentError,
+                "#{self.class.type_name} control has no '#{key}' attribute"
+        end
+        public_send(writer, value)
+      end
+      self
+    end
+
+    # Re-emits every state property of this control. Called by the
+    # surface during +state_request+ or after inventory dumps.
+    # @return [void]
+    # @api private
+    def emit_all_state
+      emit(:message, @message.to_s) unless @message.nil?
+    end
+
+    # @return [Symbol] the inventory type identifier
+    def self.type_name
+      raise NotImplementedError, "#{self} must implement .type_name"
+    end
+
+    # Instantiates the right subclass for the given type.
+    # @param type [Symbol]
+    # @return [Control]
+    # @raise [ArgumentError] if the type is unknown
+    # @api private
+    def self.create(type, **kwargs)
+      case type.to_sym
+      when :toggle  then Toggle.new(**kwargs)
+      when :trigger then Trigger.new(**kwargs)
+      when :encoder then Encoder.new(**kwargs)
+      else raise ArgumentError, "Unknown control type: #{type.inspect}"
+      end
+    end
+
+    protected def emit(prop, *value)
+      @surface.emit_state(@event, prop, *value)
+    end
+  end
+
+  # A stateful on/off control with a three-valued enabled property:
+  # +true+ (on), +false+ (off available), +:inactive+ (control is
+  # known but currently not actionable, typically rendered dimmed).
+  class Toggle < Control
+    def self.type_name = :toggle
+
+    # @return [Boolean, Symbol] +true+, +false+, or +:inactive+
+    attr_reader :enabled
+
+    def initialize(**kwargs)
+      super
+      @enabled = :inactive
+    end
+
+    # Sets the enabled state. Accepts +true+, +false+, +:inactive+
+    # and their string equivalents.
+    # @param value [Boolean, Symbol, String]
+    # @raise [ArgumentError] on any other value
+    def enabled=(value)
+      @enabled = normalize_enabled(value)
+      emit(:enabled, @enabled.to_s)
+    end
+
+    # @return [Boolean] true iff +enabled+ is exactly +true+
+    def enabled?
+      @enabled == true
+    end
+
+    # @return [Boolean] true iff +enabled+ is +:inactive+
+    def inactive?
+      @enabled == :inactive
+    end
+
+    # Convenience: set to +true+.
+    def on!  = (self.enabled = true)
+    # Convenience: set to +false+.
+    def off! = (self.enabled = false)
+    # Convenience: set to +:inactive+.
+    def inactive! = (self.enabled = :inactive)
+
+    # Toggles between +true+ and +false+. From +:inactive+ goes to
+    # +true+ (entering active service).
+    def toggle!
+      case @enabled
+      when true  then off!
+      when false then on!
+      else            on!
+      end
+    end
+
+    def emit_all_state
+      super
+      emit(:enabled, @enabled.to_s)
+    end
+
+    private def normalize_enabled(v)
+      case v
+      when true,  :true,  'true'     then true
+      when false, :false, 'false'    then false
+      when :inactive, 'inactive', nil then :inactive
+      else
+        raise ArgumentError,
+              "enabled must be true, false or :inactive (got #{v.inspect})"
+      end
+    end
+  end
+
+  # A momentary, stateless control. Pressing it fires the
+  # corresponding sequencer event; the control itself carries no
+  # persistent on/off state beyond an optional {#message}.
+  class Trigger < Control
+    def self.type_name = :trigger
+  end
+
+  # An absolute-value rotary or fader control with an integer
+  # +value+ inside an inclusive +range+. Range defaults to
+  # +0..127+ (standard MIDI 7-bit).
+  class Encoder < Control
+    def self.type_name = :encoder
+
+    # @return [Integer]
+    attr_reader :value
+    # @return [Range]
+    attr_reader :range
+
+    def initialize(**kwargs)
+      super
+      @range = 0..127
+      @value = 0
+    end
+
+    # @param v [Integer, Numeric] clamped to {#range}
+    def value=(v)
+      @value = clamp_to_range(v.to_i)
+      emit(:value, @value)
+    end
+
+    # @param r [Range] inclusive integer range; +value+ is re-clamped
+    def range=(r)
+      raise ArgumentError, "range must be a Range (got #{r.inspect})" unless r.is_a?(Range)
+      @range = r
+      @value = clamp_to_range(@value)
+      emit(:range, r.min, r.max)
+      emit(:value, @value)
+    end
+
+    def emit_all_state
+      super
+      emit(:range, @range.min, @range.max)
+      emit(:value, @value)
+    end
+
+    private def clamp_to_range(v)
+      [[v, @range.min].max, @range.max].min
+    end
+  end
+end

data/lib/version.rb

@@ -1,3 +1,15 @@
+# Musa Live Coding Environment Server.
+#
+# A Ruby server for live coding with Ableton Live and Bitwig Studio DAWs.
+# Provides OSC communication, MIDI device management, and a REPL for
+# interactive music composition using Musa-DSL.
+#
+# @see MusaLCEServer.run Entry point for starting the server
+# @see MusaLCEServer::Daw Base class for DAW controllers
+#
+# @author Javier Sánchez Yeste
+# @since 0.1.0
 module MusaLCEServer
-  VERSION = '0.5.1'.freeze
+  # Current version of the musalce-server gem.
+  VERSION = '0.8.0'.freeze
 end

data/musalce-server.gemspec

@@ -3,7 +3,7 @@ require_relative 'lib/version'
 Gem::Specification.new do |s|
   s.name        = 'musalce-server'
   s.version     = MusaLCEServer::VERSION
-  s.date        = '2025-08-23'
+  s.date        = '2026-05-16'
   s.summary     = 'A Musa DSL live coding environment for Ableton Live 11 and Bitwig Studio 5'
   s.description = 'This package implements the Server part of the Musa DSL Live Coding Environment for Ableton Live and Bitwig Studio'
   s.authors     = ['Javier Sánchez Yeste']
@@ -15,20 +15,27 @@ Gem::Specification.new do |s|
 
   s.required_ruby_version = '>= 2.7'
 
-  # TODO
-  #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/musalce-server'
+  }
 
-  s.add_runtime_dependency 'musa-dsl', '~> 0', '>= 0.26.0'
+  s.add_runtime_dependency 'musa-dsl', '~> 0.40'
 
-  s.add_runtime_dependency 'midi-communications', '~> 0.6'
-  s.add_runtime_dependency 'midi-events', '~> 0.6'
-  s.add_runtime_dependency 'midi-parser', '~> 0.4'
+  s.add_runtime_dependency 'midi-communications', '~> 0.7'
+  s.add_runtime_dependency 'midi-events', '~> 0.7'
+  s.add_runtime_dependency 'midi-parser', '~> 0.5'
 
-  #s.add_runtime_dependency 'eventmachine', '~> 1.2', '>= 1.2.7'
   s.add_runtime_dependency 'osc-ruby', '~> 1.1', '>= 1.1.5'
+  # EventMachine is an *optional* dep of osc-ruby (only needed when
+  # using OSC::EMServer, which we do in daw.rb to receive OSC from
+  # the DAW extension). osc-ruby doesn't declare it, so we must.
+  s.add_runtime_dependency 'eventmachine', '~> 1.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'
 end