musa-dsl 0.42.6 → 0.42.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 88eb7916fe255e3b5d72520d25d4057252c41f24926975659712668a43c0cc41
-  data.tar.gz: 7fbe17e6453b42f4729104e47392c7b4819436de0bf0e64fd28505f0e936e76f
+  metadata.gz: '08cad9ebc734d1e470cbf691738f1f08b9042796a4cf01adadb0bb2d126ef121'
+  data.tar.gz: f5b9a5ec33e63d511507fa27f42f64b7b126e9104c0d14c747c95445f953dc13
 SHA512:
-  metadata.gz: 25514b23a820ff8ec8f2f99c6e607dcec8879db85d030e3d3e19398a26ea63f3c81752d7e839eefb27e6a640b355aa0b58fb0a43b6f076f79b59e2303bf00e8d
-  data.tar.gz: f89fbbf88a3f62f455dcf6cb342f47f324c1c4c93c225fcc45ba86f766e31a3300cacd7a3ff379698e97a201594a0e1610357cd20e843a4d797997c551b9c758
+  metadata.gz: 6ca2b3741c4d4d83bf3318efe27a30b4730a9a2664ec3a5a8ad8d64f54a71697ee3b119d6ecbbfc61b2f2f4a800d516c5f857d55a012611afa4ab6f120f0ca7a
+  data.tar.gz: e0956d3b3593c171e22ebf448182655f3e754bef2af495e96fbff4a096c8c0511d937cc5732f6d57d1ec7b0ea9d3bbd01c79bf1732c7ed06dd3d8965361f300f

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/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.42.7'.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.42.7
 platform: ruby
 authors:
 - Javier Sánchez Yeste