musa-dsl 0.42.6 → 0.43.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 88eb7916fe255e3b5d72520d25d4057252c41f24926975659712668a43c0cc41
-  data.tar.gz: 7fbe17e6453b42f4729104e47392c7b4819436de0bf0e64fd28505f0e936e76f
+  metadata.gz: fa34fee0b26abe335f3288cc4593230f4f9e76b0b8f198594d5880c3055038f6
+  data.tar.gz: 7836f199fc7a81192269391d4e26d68e99de85d116750e30c32bf39df421ed39
 SHA512:
-  metadata.gz: 25514b23a820ff8ec8f2f99c6e607dcec8879db85d030e3d3e19398a26ea63f3c81752d7e839eefb27e6a640b355aa0b58fb0a43b6f076f79b59e2303bf00e8d
-  data.tar.gz: f89fbbf88a3f62f455dcf6cb342f47f324c1c4c93c225fcc45ba86f766e31a3300cacd7a3ff379698e97a201594a0e1610357cd20e843a4d797997c551b9c758
+  metadata.gz: 296f17a87edaf39c519c3054bfc790445aa45aa5295aee76b978c831465a6e4a312b2c541fc9d99424e7365ff9726055e05537ddb6b7b362ee5fb69bb5b3e83d
+  data.tar.gz: 571a82f51bc2e5d61c77f214629d727c8c47ed1c7a8d0ba6c4ac7c3019ccd4ba93f7a6f85b81e7041fdb773aa11607ab1606a7a2f9adbee252ccc72e8e516a76

data/README.md

@@ -29,7 +29,52 @@ Musa-DSL is a programming language DSL (Domain-Specific Language) based on Ruby
 - **Neumalang Notation** - Intuitive text-based and customizable musical (or sound) notation
 - **Transcription System** - Convert musical gestures to MIDI and MusicXML with ornament transcription expansion
 
-## Installation
+## Getting Started
+
+### Recommended Editor: RubyMine
+
+[RubyMine](https://www.jetbrains.com/ruby/) provides the best experience for MusaDSL development: intelligent autocomplete of methods and parameters, hover documentation, and type inference help you discover the API as you write.
+
+**Free licenses available:**
+- [Non-commercial use](https://www.jetbrains.com/non-commercial/) — for learning, hobbies, open-source, content creation
+- [Students](https://www.jetbrains.com/academy/student-pack/) and [Teachers/Researchers](https://www.jetbrains.com/academy/teacher-pack/) — with institutional email
+
+VSCode with the Ruby LSP extension also works well, though Ruby autocomplete and hover documentation are less complete.
+
+### AI Composition Assistant: Claude Code Plugin
+
+The fastest way to learn and compose with MusaDSL is through **[Nota](https://github.com/javier-sy/nota-plugin-for-claude)** — a plugin for [Claude Code](https://claude.ai/code) that provides:
+
+- **`/nota:explain`** — Ask any question about MusaDSL and get sourced answers with working code examples
+- **`/nota:think`** — Creative ideation across multiple musical dimensions
+- **`/nota:code`** — Describe your musical intention in natural language and get verified MusaDSL code
+- **`/nota:analyze`** — Structured analysis of your compositions
+- **`/nota:best-practices`** — Consolidate recurring patterns into searchable best practices
+
+The plugin includes a semantic knowledge base covering all MusaDSL documentation, API reference, 22+ demo projects, and 12 built-in composition best practices. Your compositions, analyses, and practices become searchable knowledge that enriches future sessions.
+
+**Requirements:** [Ruby 3.4+](https://www.ruby-lang.org/) and a [Voyage AI](https://dash.voyageai.com/) API key (free tier is sufficient for personal use).
+
+**Install in Claude Code:**
+
+First, add the Nota marketplace:
+```
+/plugin marketplace add javier-sy/nota-plugin-for-claude
+```
+
+Then install the plugin:
+```
+/plugin install nota@yeste.studio
+```
+
+Then add your Voyage AI API key to your shell profile:
+```
+export VOYAGE_API_KEY="your-key-here"
+```
+
+Run `/nota:setup` to verify the installation.
+
+### Framework Installation
 
 Add to your Gemfile:
 

data/docs/subsystems/repl.md

@@ -9,11 +9,40 @@ Editor → MusaLCE Client → TCP (port 1327) → REPL Server → DSL Context
                                              Results/Errors
 ```
 
-**Available MusaLCE Clients:**
-- **MusaLCEClientForVSCode**: Visual Studio Code extension
-- **MusaLCEClientForAtom**: Atom editor plugin
-- **MusaLCEforBitwig**: Bitwig Studio integration
-- **MusaLCEforLive**: Ableton Live integration
+The REPL is **only** the TCP eval channel between editor and server. Anything else a live-coding session needs (DAW transport, MIDI routing, OSC surface relay, etc.) lives outside this subsystem.
+
+## Two scenarios
+
+### Case 1 — Standalone live coding (you bring your own REPL)
+
+This is the scenario this document covers. You build your own `main.rb` (sequencer, voices, clock, transport, your own helpers) and start `Musa::REPL::REPL.new(binding)` inside the sequencer's DSL context. Your editor connects to it on `localhost:1327` and you send Ruby fragments live.
+
+Maximum control. Useful when:
+
+- You drive non-DAW targets — SuperCollider, Max/MSP, OSC apps, OS voice synthesis, custom hardware.
+- You're prototyping a personal live-coding DSL (helpers, Tidal-Cycles-style API).
+- You want to keep the dependency footprint to musa-dsl alone.
+
+A complete worked example with a Tidal-Cycles-style `d(n)` / `hush` / `solo` API: [`musadsl-demo/_demo-13-live-coding`](https://github.com/javier-sy/musadsl-demo).
+
+### Case 2 — Suite workflow (musalce-server handles everything)
+
+When the target is **Ableton Live** or **Bitwig Studio**, the [musalce-server](https://github.com/javier-sy/musalce-server) gem packages this REPL plus a sequencer, a clock, a transport, a DAW handler (OSC over UDP to the per-DAW extension) and a surface for Stream Deck integration via Pulso. Internally case 2 is a **specialization** of case 1 — `musalce-server` opens `Musa::REPL::REPL.new(binding)` after pre-building all the boilerplate, and exposes a `daw.*` API in the DSL context.
+
+Documented separately in the suite's architecture reference: [musalce-server/docs/architecture.md](https://github.com/javier-sy/musalce-server/blob/master/docs/architecture.md).
+
+## Components
+
+**REPL clients** (talk to the REPL server over TCP 1327 — same shape in both scenarios):
+
+- [MusaLCEClientForVSCode](https://github.com/javier-sy/MusaLCEClientForVSCode) — Visual Studio Code extension
+- [MusaLCEClientForAtom](https://github.com/javier-sy/MusaLCEClientForAtom) — Atom editor plugin (discontinued, December 2022)
+
+**Suite-only components** (only used in case 2 — see musalce-server architecture doc):
+
+- [musalce-server](https://github.com/javier-sy/musalce-server) — packages REPL + sequencer + DAW handler + surface
+- [MusaLCEforBitwig](https://github.com/javier-sy/MusaLCEforBitwig) — Bitwig Studio controller extension (Java)
+- [MusaLCEforLive](https://github.com/javier-sy/MusaLCEforLive) — Ableton Live MIDI Remote Script (Python)
 
 ## Communication Protocol
 
@@ -55,34 +84,41 @@ Server → Client:
   Starting composition...
 ```
 
-## Server Setup
-
-**Basic REPL Server:**
+## Server Setup (Case 1 — canonical pattern)
 
 ```ruby
 require 'musa-dsl'
+require 'midi-communications'    # or any other MIDI/OSC layer you prefer
+
 include Musa::All
 
-# Create sequencer and transport
+# 1. MIDI output of your choice
+output = MIDICommunications::Output.gets
+
+# 2. Clock + transport
 clock = TimerClock.new(bpm: 120, ticks_per_beat: 24)
 transport = Transport.new(clock, 4, 24)
 
-# Start REPL server bound to sequencer context
-# The REPL will execute code in the sequencer's DSL context
+# 3. Sequencer DSL context — anything you define inside `with` becomes
+#    available in the REPL (instance methods, accessors, helpers).
 transport.sequencer.with do
-  # DSL methods available in REPL
-  def note(pitch:, duration:)
-    puts "Playing pitch #{pitch} for #{duration} bars"
+  voices = MIDIVoices.new(sequencer: transport.sequencer, output: output, channels: [0, 1])
+
+  # Define whatever DSL surface you want exposed to the REPL.
+  def my_note(pitch:, duration:)
+    voices.voices[0].note(pitch, duration: duration)
   end
 
-  # Create REPL server (port 1327 by default)
+  # 4. Start the REPL server (binds to TCP/1327 in this DSL context)
   @repl = Musa::REPL::REPL.new(binding)
 end
 
-# Start playback (REPL runs in background thread)
+# 5. Start playback (REPL runs in background thread)
 transport.start
 ```
 
+If you instead want the **suite workflow** (case 2 — Bitwig or Live with DAW handler + Stream Deck surface), don't write the above by hand: install [musalce-server](https://github.com/javier-sy/musalce-server) and run `musalce-server bitwig|live`. It opens this same REPL with a richer DSL context (`daw.*`, `surface[:event]`, …).
+
 **File Path Injection:**
 
 When a client sends a file path via `#path`, the REPL injects it as `@user_pathname` (Pathname object). This enables relative requires based on the editor's current file location:

data/docs/subsystems/sequencer.md

@@ -39,6 +39,7 @@ transport.sequencer.with do
   end
 
   # Play series (play): reproduces series with automatic timing
+  # Default mode is :wait — each element's :duration determines the wait before the next
   at 5 do
     play melody do |note:, duration:, control:|
       puts "Playing note: #{note}, duration: #{duration}"
@@ -46,6 +47,7 @@ transport.sequencer.with do
   end
 
   # Recurring event (every) with stop control
+  # Note: every passes control: as a keyword — declare only the params you need
   beat_loop = nil
   at 10 do
     # Store control object to stop it later
@@ -102,6 +104,88 @@ every 1/4r do ... end
 at 0.5 do ... end
 ```
 
+## Block Parameter Flexibility (SmartProcBinder)
+
+All scheduling methods (`every`, `play`, `move`, `play_timed`) pass parameters to user blocks via **SmartProcBinder**. This means blocks can declare **only the parameters they need** — undeclared parameters are silently ignored.
+
+**Important**: keyword parameters (like `control:`) must be declared as **keyword arguments** in the block signature (`|control:|`), not as positional arguments (`|control|`).
+
+### Parameters available per method
+
+| Method | Positional params | Keyword params |
+|--------|-------------------|----------------|
+| `every` | _(none)_ | `control:` |
+| `play` | element (+ hash keys as keywords) | `control:` |
+| `move` | value, next_value | `control:`, `duration:`, `quantized_duration:`, `started_ago:`, `position_jitter:`, `duration_jitter:`, `right_open:` |
+| `play_timed` | values (+ extra attributes as keywords) | `time:`, `started_ago:`, `control:` |
+
+### Examples
+
+```ruby
+# every — no params needed
+every 1r, duration: 4r do
+  puts "tick at #{position}"
+end
+
+# every — with control keyword
+every 1r do |control:|
+  puts "iteration #{control._execution_counter}"
+  control.stop if some_condition
+end
+
+# play — hash keys become keywords
+melody = S({ note: 60, duration: 1 }, { note: 64, duration: 1/2r })
+play melody do |note:, duration:|
+  voice.note(note, duration: duration)
+end
+
+# play — with control keyword
+play melody do |note:, duration:, control:|
+  voice.note(note, duration: duration)
+  control.stop if note == 64
+end
+
+# move — only positional value
+move from: 0, to: 127, duration: 4r, every: 1/4r do |value|
+  midi_cc(7, value.round)
+end
+
+# move — with keyword metadata
+move from: 60, to: 72, duration: 4r, every: 1/4r do |value, next_value, control:, duration:|
+  puts "value=#{value.round} next=#{next_value&.round} dur=#{duration}"
+end
+
+# play_timed — full signature
+play_timed(timed_serie) do |values, time:, started_ago:, control:|
+  puts "values=#{values} at time=#{time}"
+end
+```
+
+## Play Modes
+
+`play` supports three modes that determine how series elements are scheduled. The default mode is `:wait`.
+
+```ruby
+# :wait (default) — each element must have :duration; the sequencer waits
+# that duration before consuming the next element
+progression = S({ grade: 0, duration: 1 }, { grade: 3, duration: 1 })
+play progression do |grade:, duration:|
+  puts "Grade #{grade}, duration #{duration}"
+end
+
+# :at — each element must have :at; the sequencer schedules it at that absolute position
+events = S({ note: 60, at: 1 }, { note: 64, at: 3 })
+play events, mode: :at do |note:, at:|
+  puts "Note #{note} at position #{at}"
+end
+
+# :neumalang — full Neumalang DSL processing with decoder
+play neuma_serie, mode: :neumalang, decoder: decoder do |gdv|
+  pdv = gdv.to_pdv(scale)
+  voice.note(pdv[:pitch], velocity: pdv[:velocity], duration: pdv[:duration])
+end
+```
+
 ## Control Objects and `.stop`
 
 All scheduling methods (`at`, `wait`, `now`, `play`, `play_timed`, `every`, `move`) return a control object that supports `.stop` to cancel execution. Calling `.stop` on the control prevents the associated block from running at its scheduled position, or stops further iterations for series/recurring operations.

data/lib/musa-dsl/sequencer/base-sequencer.rb

@@ -38,6 +38,22 @@ module Musa
     # - **Event Handlers**: Hierarchical event pub/sub system
     # - **Controls**: Objects returned by scheduling methods for lifecycle management
     #
+    # ## Block Parameter Flexibility (SmartProcBinder)
+    #
+    # All scheduling methods (`every`, `play`, `move`, `play_timed`) pass parameters
+    # to user blocks via SmartProcBinder. This means blocks can declare **only the
+    # parameters they need** — undeclared parameters are silently ignored.
+    #
+    # Keyword parameters (like `control:`) must be declared as keyword arguments
+    # in the block signature (`|control:|`), not as positional arguments (`|control|`).
+    #
+    # | Method | Positional params | Keyword params |
+    # |--------|-------------------|----------------|
+    # | `every` | _(none)_ | `control:` |
+    # | `play` | element (+ hash keys as keywords) | `control:` |
+    # | `move` | value, next_value | `control:`, `duration:`, `quantized_duration:`, `started_ago:`, `position_jitter:`, `duration_jitter:`, `right_open:` |
+    # | `play_timed` | values (+ extra attributes as keywords) | `time:`, `started_ago:`, `control:` |
+    #
     # ## Tick-based vs Tickless
     #
     # **Tick-based** (beats_per_bar and ticks_per_beat specified):
@@ -642,20 +658,23 @@ module Musa
       # Timing determined by mode.
       #
       # @param serie [Series] series to play
-      # @param mode [Symbol] running mode (:at, :wait, :neumalang)
+      # @param mode [Symbol] running mode (:at, :wait, :neumalang). Defaults to :wait
       # @param parameter [Symbol, nil] duration parameter name from serie values
       # @param on_stop [Proc, nil] callback when play stops (any reason, including manual stop)
       # @param after_bars [Numeric, nil] delay for after callback
       # @param after [Proc, nil] callback after play completes naturally (NOT on manual stop)
       # @param context [Object, nil] context for neumalang processing
       # @param mode_args [Hash] additional mode-specific parameters
-      # @yield [value] block executed for each serie value
+      # @yield block executed for each serie value (via SmartProcBinder — declare only the parameters you need)
+      # @yieldparam element [Object] the current serie element (positional). When the element is a Hash,
+      #   its keys are also available as keyword arguments (e.g., `|note:, duration:|`)
+      # @yieldparam control [PlayControl] the play control object (keyword, optional)
       # @return [PlayControl] control object
       #
       # ## Available Running Modes
       #
+      # - **:wait** (default): Elements with duration specify wait time before next element
       # - **:at**: Elements specify absolute positions via :at key
-      # - **:wait**: Elements with duration specify wait time
       # - **:neumalang**: Full Neumalang DSL with variables, commands, series, etc.
       #
       #
@@ -755,7 +774,11 @@ module Musa
       # @param on_stop [Proc, nil] callback when playback stops
       # @param after_bars [Numeric, nil] schedule after completion
       # @param after [Proc, nil] block after completion
-      # @yield [value] block for each value
+      # @yield block for each timed value (via SmartProcBinder — declare only the parameters you need)
+      # @yieldparam values [Hash, Array] current component values (positional). Hash in hash mode, Array in array mode
+      # @yieldparam time [Rational] absolute position of this event (keyword, optional)
+      # @yieldparam started_ago [Hash, Array] time since each component's last update (keyword, optional)
+      # @yieldparam control [PlayTimedControl] the play_timed control object (keyword, optional)
       # @return [PlayTimedControl] control object
       #
       # @example Hash mode timed series
@@ -842,6 +865,13 @@ module Musa
       # - **condition**: condition block returns false
       # - **nil interval**: immediate stop after first execution
       #
+      # ## Block Parameters (via SmartProcBinder)
+      #
+      # The block receives the following keyword parameter via SmartProcBinder.
+      # You can declare only the parameters you need — undeclared ones are silently ignored.
+      #
+      # - **control:** [EveryControl] — the control object for the current loop
+      #
       # @param interval [Numeric, nil] interval between executions (nil = once)
       # @param duration [Numeric, nil] total duration
       # @param till [Numeric, nil] end position
@@ -849,18 +879,16 @@ module Musa
       # @param on_stop [Proc, nil] callback when loop stops
       # @param after_bars [Numeric, nil] schedule after completion
       # @param after [Proc, nil] block after completion
-      # @yield [position] block executed each interval
+      # @yieldparam control [EveryControl] the loop's control object (keyword, optional)
       # @return [EveryControl] control object
       #
-      # @example
-      #   seq.every(1, till: 8) { |pos| puts "Beat #{pos}" }
-      #
-      # @example Every 4 beats for 16 bars
-      #   sequencer.every(1r, duration: 4r) { puts "tick" }
-      #   # Executes at 1r, 2r, 3r, 4r, 5r (5 times total)
+      # @example No parameters needed
+      #   seq.every(1, till: 8) { puts "Beat at #{seq.position}" }
       #
-      # @example Every beat until position 10
-      #   sequencer.every(1r, till: 10r) { |control| puts control.position }
+      # @example Accessing the control object (keyword argument)
+      #   seq.every(1r, duration: 4r) do |control:|
+      #     puts "Iteration #{control._execution_counter}"
+      #   end
       #
       # @example Conditional loop
       #   count = 0
@@ -947,7 +975,16 @@ module Musa
       # @param on_stop [Proc, nil] callback when animation stops
       # @param after_bars [Numeric, nil] schedule after completion
       # @param after [Proc, nil] block after completion
-      # @yield [value] block executed with interpolated value
+      # @yield block executed with interpolated value (via SmartProcBinder — declare only the parameters you need)
+      # @yieldparam value [Numeric, Array, Hash] current interpolated value(s) (positional)
+      # @yieldparam next_value [Numeric, Array, Hash, nil] next interpolated value(s), nil at end (positional)
+      # @yieldparam control [MoveControl] the move control object (keyword, optional)
+      # @yieldparam duration [Numeric, Array, Hash] interval duration per component (keyword, optional)
+      # @yieldparam quantized_duration [Numeric, Array, Hash] quantized interval duration (keyword, optional)
+      # @yieldparam started_ago [Numeric, Array, Hash, nil] time since component last changed (keyword, optional)
+      # @yieldparam position_jitter [Numeric, Array, Hash] position rounding error (keyword, optional)
+      # @yieldparam duration_jitter [Numeric, Array, Hash] duration rounding error (keyword, optional)
+      # @yieldparam right_open [Boolean, Array, Hash] whether final value is excluded (keyword, optional)
       # @return [MoveControl] control object
       #
       # @example Simple pitch glide
@@ -990,7 +1027,7 @@ module Musa
       #     function: proc { |ratio| ratio ** 2 }  # Ease-in
       #   ) { |value| puts value }
       #
-      # @example Linear fade
+      # @example Linear fade (only positional value needed)
       #   seq = Musa::Sequencer::BaseSequencer.new(4, 24)
       #
       #   volume_values = []
@@ -1001,6 +1038,11 @@ module Musa
       #
       #   seq.run
       #   # Result: volume_values contains [0, 8, 16, 24, ..., 119, 127]
+      #
+      # @example Using keyword parameters
+      #   seq.move(from: 60, to: 72, duration: 4r, every: 1/4r) do |value, next_value, control:, duration:|
+      #     puts "value=#{value.round} next=#{next_value&.round} dur=#{duration}"
+      #   end
       def move(every: nil,
                from: nil, to: nil, step: nil,
                duration: nil, till: nil,

data/lib/musa-dsl/version.rb

@@ -1,3 +1,3 @@
 module Musa
-  VERSION = '0.42.6'.freeze
+  VERSION = '0.43.0'.freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: musa-dsl
 version: !ruby/object:Gem::Version
-  version: 0.42.6
+  version: 0.43.0
 platform: ruby
 authors:
 - Javier Sánchez Yeste