musalce-server 0.5.1 → 0.8.1

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.1'.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-27'
   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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: musalce-server
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.8.1
 platform: ruby
 authors:
 - Javier Sánchez Yeste
 bindir: bin
 cert_chain: []
-date: 2025-08-23 00:00:00.000000000 Z
+date: 2026-05-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: musa-dsl
@@ -15,62 +15,56 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.26.0
+        version: '0.40'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.26.0
+        version: '0.40'
 - !ruby/object:Gem::Dependency
   name: midi-communications
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.6'
+        version: '0.7'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.6'
+        version: '0.7'
 - !ruby/object:Gem::Dependency
   name: midi-events
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.6'
+        version: '0.7'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.6'
+        version: '0.7'
 - !ruby/object:Gem::Dependency
   name: midi-parser
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.4'
+        version: '0.5'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.4'
+        version: '0.5'
 - !ruby/object:Gem::Dependency
   name: osc-ruby
   requirement: !ruby/object:Gem::Requirement
@@ -91,6 +85,76 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 1.1.5
+- !ruby/object:Gem::Dependency
+  name: eventmachine
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
+- !ruby/object:Gem::Dependency
+  name: webrick
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
 description: This package implements the Server part of the Musa DSL Live Coding Environment
   for Ableton Live and Bitwig Studio
 email: javier.sy@gmail.com
@@ -99,11 +163,15 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/workflows/notify-plugin.yml"
 - ".gitignore"
+- ".version"
+- ".yardopts"
 - Gemfile
 - LICENSE
 - README.md
 - bin/musalce-server
+- docs/architecture.md
 - lib/bitwig/bitwig.rb
 - lib/bitwig/controllers.rb
 - lib/bitwig/handler.rb
@@ -114,12 +182,17 @@ files:
 - lib/live/tracks.rb
 - lib/midi-devices.rb
 - lib/musalce-server.rb
+- lib/surface-bridge.rb
+- lib/surface.rb
 - lib/version.rb
 - musalce-server.gemspec
 homepage: https://github.com/javier-sy/musalce-server
 licenses:
 - GPL-3.0-or-later
-metadata: {}
+metadata:
+  homepage_uri: https://github.com/javier-sy/musalce-server
+  source_code_uri: https://github.com/javier-sy/musalce-server
+  documentation_uri: https://www.rubydoc.info/gems/musalce-server
 rdoc_options: []
 require_paths:
 - lib