musa-dsl 0.40.0 → 0.42.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 603ecc3ddd2b6bcead498e08a747035df5ff2c2e87e4f527c66c48d5631ab435
-  data.tar.gz: 37dde89a2c5ff9dda9691ff245fa06b4e870475fb7320ef10bca5ef0a7a84ed2
+  metadata.gz: 6f157001c0d45494eda872c34d4d73c161b686da78f0192868637873845ca62e
+  data.tar.gz: 2d93034d622985b67ae894d0cf7f4a5acdba787b4453fd6dbad08aa88d096866
 SHA512:
-  metadata.gz: 8b1bd0544fd6b6fe611718809e50422e3accf376e88da0832e7b22b7f5b279eb52d9cab2fe3c3f75d2e996e17f0c1a604a2e56676249c946dae533988db8a54c
-  data.tar.gz: 4c4dbcbfb7243f751205f275eaba483e8d29ce3ca5f59e600a1b8be9d1687c0815572916415b4dfbb0ac14ae7f2bbaec3ee610af2922fe8ab9de42e4ab3a04b2
+  metadata.gz: 4dc00ab7d48971758d26bf982e8b61771fe81c26bd9e7cdedba97e457d3c97ff8286f7e53689712c97bb10674fe5f59261ee1f1186a1f20dbda87b62a16aa858
+  data.tar.gz: 9da464c4a8cfce824392e1c37b4987b84bde21c59924da5daf34b97b46c183d70d06afff212ab0de7d5b45971c7267aab5260730509b21522f12c49ab5474d46

data/.gitignore

@@ -12,3 +12,6 @@ test.musicxml
 doc
 .yardoc
 *.backup
+.vscode
+.ruby-lsp
+

data/Gemfile

@@ -1,4 +1,3 @@
 source 'https://rubygems.org'
 
 gemspec
-gem 'rubocop', group: 'development'

data/README.md

@@ -58,6 +58,20 @@ Detailed tutorial showing the Neuma notation system for composing melodies with
 
 **📖 [Complete Tutorial](docs/getting-started/tutorial.md)**
 
+## Demo Projects
+
+A collection of 22+ working demo projects covering the full spectrum of Musa DSL capabilities:
+
+- **Basic concepts**: Setup, series, neumas, canon
+- **Generative tools**: Markov chains, Variatio, Darwin, Grammar, Rules, Matrix
+- **DAW integration**: MIDI sync, live coding, clock modes
+- **External protocols**: OSC with SuperCollider and Max/MSP
+- **Advanced patterns**: Event architecture, parameter automation, multi-phase compositions
+
+Each demo is a complete, runnable project with documentation explaining the concepts demonstrated.
+
+**📦 [musadsl-demo Repository](https://github.com/javier-sy/musadsl-demo)**
+
 ## System Architecture
 
 MusaDSL is a comprehensive ecosystem consisting of a core framework (musa-dsl) and associated projects for communication, development, and integration.
@@ -230,4 +244,4 @@ Ruby refinements and metaprogramming utilities: Arrayfy, Hashify, ExplodeRanges,
 
 ## License
 
-[Musa-DSL](https://github.com/javier-sy/musa-dsl) Copyright (c) 2016-2025 [Javier Sánchez Yeste](https://yeste.studio), licensed under LGPL 3.0 License
+[Musa-DSL](https://github.com/javier-sy/musa-dsl) Copyright (c) 2016-2026 [Javier Sánchez Yeste](https://yeste.studio), licensed under LGPL 3.0 License

data/docs/README.md

@@ -52,6 +52,7 @@ For users extending the DSL or integrating deeply:
 2. Explore [Music](subsystems/music.md) (scales & chords)
 3. Try [Generative](subsystems/generative.md) algorithms
 4. Use [MusicXML Builder](subsystems/musicxml-builder.md) for scores
+5. Explore [Demo Projects](https://github.com/javier-sy/musadsl-demo) - 22+ working examples
 
 ### Live Coding?
 1. Set up [REPL](subsystems/repl.md)

data/docs/subsystems/datasets.md

@@ -52,6 +52,51 @@ E (base event)
 - Glissandi and parameter sweeps (PS)
 - Dynamics changes and other evolving parameters
 
+## Duration Types in AbsD
+
+AbsD defines three duration concepts that enable complex rhythmic structures:
+
+| Field | Purpose | Default |
+|-------|---------|---------|
+| `:duration` | Total event process time | Required |
+| `:note_duration` | Actual sound length (staccato/legato) | = duration |
+| `:forward_duration` | Time until next event starts | = duration |
+
+**Examples:**
+
+```ruby
+include Musa::Datasets
+
+# Normal note - all durations equal
+{ pitch: 60, duration: 1.0 }.extend(AbsD)
+
+# Staccato - sounds shorter than it "lasts"
+{ pitch: 60, duration: 1.0, note_duration: 0.5 }.extend(AbsD)
+
+# Chord (simultaneous notes) - next event starts immediately
+{ pitch: 60, duration: 1.0, forward_duration: 0 }.extend(AbsD)
+
+# Overlap (legato) - next note starts before this one ends
+{ pitch: 60, duration: 1.0, forward_duration: 0.8 }.extend(AbsD)
+```
+
+**Understanding DeltaD:**
+
+DeltaD is the delta-encoding counterpart to AbsD. While AbsD stores absolute durations, DeltaD stores changes relative to a previous event. If duration hasn't changed from the previous event, it can be omitted for compression (as shown in GDV → GDVd conversions).
+
+## Natural Keys
+
+Each dataset type defines "natural keys" - semantically meaningful fields for that type:
+
+| Module | Natural Keys |
+|--------|--------------|
+| **E** | `[]` (none) |
+| **AbsD** | `[:duration, :note_duration, :forward_duration]` |
+| **PDV** | AbsD keys + `[:pitch, :velocity]` |
+| **GDV** | AbsD keys + `[:grade, :sharps, :octave, :velocity, :silence]` |
+
+Custom keys (any not in NaturalKeys) are preserved through conversions, enabling you to attach composition-specific metadata that travels with your musical data.
+
 ## Extensibility
 
 All datasets support custom parameters beyond their natural keys:
@@ -102,6 +147,36 @@ gdv.is_a?(Abs)   # => true (GDV includes Abs)
 gdv.is_a?(AbsD)  # => true (GDV includes AbsD for duration)
 ```
 
+## Using AbsD for Containers
+
+AbsD is not just for notes - use it for any time-spanning structure that needs a duration. This is useful for chord progression steps, sections, or any compositional element that occupies time but isn't itself a single note.
+
+```ruby
+include Musa::Datasets
+
+scale = Musa::Scales::Scales.et12[440.0].major[60]
+
+# A chord progression step (not a note, but has duration)
+step = {
+  duration: 2,                    # How long this step lasts
+  symbol: :I,                     # Chord symbol for reference
+  bass: { grade: 0, octave: -1, duration: 2, velocity: 0 }.extend(GDV),
+  chord: scale[:I].chord,         # Chord object
+  chord_duration: 7/4r,
+  chord_velocity: -1
+}.extend(AbsD)
+
+# Now the sequencer can use step.duration for timing
+# while the step contains all the musical information needed to render it
+```
+
+**When to use AbsD directly:**
+
+- Containers that hold multiple notes (chords, arpeggios)
+- Section markers with timing information
+- Harmonic rhythm steps in a progression
+- Any structure where you need `:duration` but PDV/GDV semantics don't apply
+
 ## Dataset Conversions
 
 Datasets provide rich conversion capabilities for transforming between different representations, each optimized for specific compositional tasks:

data/docs/subsystems/generative.md

@@ -80,18 +80,30 @@ limited_chords = variatio.on(root: [60, 64])
 
 Production system with growth and pruning rules (similar to L-systems). Generates tree structures by applying sequential growth rules to create branches and validation rules to prune invalid paths. Useful for harmonic progressions with voice leading rules, melodic variations with contour constraints, or rhythmic patterns following metric rules.
 
+### Execution Model
+
+**Critical concept: Each `grow` rule = 1 level of depth in the tree.**
+
+```
+Seed → GrowRule1 → GrowRule2 → GrowRule3 → ... → Result
+         ↓            ↓            ↓
+      branches    branches    branches
+```
+
+Rules are processed **sequentially**: the first grow rule applies to the seed, the second grow rule applies to all results from the first, and so on. If you define N grow rules, you get N levels of transformation.
+
 **Constructor parameters:**
 - `&block` - DSL block defining grow rules, cut rules, and end condition
 
 **DSL methods:**
 - `grow(name, &block)` - Define growth rule that generates new branches
-  - Block receives: `|object, history, **params|`
+  - Block receives: `|object|` or `|object, history|` or `|object, history, **params|`
   - Use `branch(new_object)` to create new possibilities
 - `cut(reason, &block)` - Define pruning rule to eliminate invalid paths
-  - Block receives: `|object, history, **params|`
+  - Block receives: `|object|` or `|object, history|` or `|object, history, **params|`
   - Use `prune` to reject current branch
 - `ended_when(&block)` - Define end condition to mark complete branches
-  - Block receives: `|object, history, **params|`
+  - Block receives: `|object|` or `|object, history|` or `|object, history, **params|`
   - Return `true` to mark branch as complete
 
 **Execution methods:**
@@ -103,23 +115,83 @@ Production system with growth and pruning rules (similar to L-systems). Generate
 - `combinations` - Returns array of all valid complete paths through tree
 - `fish` - Returns array of all valid endpoint objects
 
+### Important: The `history` Parameter
+
+**Warning:** When using a single seed (the typical case), the `history` parameter is **always an empty array `[]`** in all grow rules. This is because `history` contains the path of *confirmed* objects from previous seeds when using multiple seeds.
+
+**Do NOT rely on `history` for tracking sequence length with a single seed:**
+```ruby
+# THIS DOES NOT WORK as expected with a single seed:
+ended_when do |pitch, history|
+  history.size == 7  # Always false! history is []
+end
+```
+
+### Recommended Pattern: Cumulative State
+
+The recommended approach is to make your **object accumulate state** rather than relying on `history`:
+
+```ruby
+require 'musa-dsl'
+
+# Generate 8-note melodies with interval constraints
+rules = Musa::Rules::Rules.new do
+  # Each grow rule adds ONE note. For 8 notes, we need 7 grow rules (seed + 7).
+  7.times do
+    grow 'add next note' do |melody, max_interval:|
+      last_note = melody.last
+      (-max_interval..max_interval).each do |interval|
+        next if interval == 0  # Skip unisons
+        new_note = last_note + interval
+        branch melody + [new_note] if new_note.between?(48, 84)  # Range limit
+      end
+    end
+  end
+
+  # Cut rule: no repeated notes
+  cut 'no repetition' do |melody|
+    prune if melody.size >= 2 && melody[-1] == melody[-2]
+  end
+
+  # End condition checks the OBJECT size, not history
+  ended_when do |melody|
+    melody.size == 8
+  end
+end
+
+# Seed is [[60]] - double array to prevent automatic flattening
+tree = rules.apply([[60]], max_interval: 4)
+
+# Extract all valid 8-note melodies
+melodies = tree.combinations.map(&:last)
+puts "Generated #{melodies.size} valid melodies"
+```
+
+**Key points:**
+- Use `N.times { grow }` to create N levels of depth
+- The object (`melody`) accumulates state as an array
+- Check `object.size` in `ended_when`, not `history.size`
+- Seed with `[[value]]` (double array) to prevent Ruby's `arrayfy` from flattening
+
+### Basic Example: Chord Voicings
+
 ```ruby
 require 'musa-dsl'
 
 # Build chord voicings by adding notes sequentially
 rules = Musa::Rules::Rules.new do
-  # Step 1: Choose root note
+  # Step 1: Choose root note (1st grow rule = 1st level)
   grow 'add root' do |seed|
     [60, 64, 67].each { |root| branch [root] }  # C, E, G
   end
 
-  # Step 2: Add third (major or minor)
+  # Step 2: Add third (2nd grow rule = 2nd level)
   grow 'add third' do |chord|
     branch chord + [chord[0] + 4]  # Major third
     branch chord + [chord[0] + 3]  # Minor third
   end
 
-  # Step 3: Add fifth
+  # Step 3: Add fifth (3rd grow rule = 3rd level)
   grow 'add fifth' do |chord|
     branch chord + [chord[0] + 7]
   end
@@ -149,6 +221,20 @@ voicings = combinations.map { |path| path.last }
 tree_with_params = rules.apply(0, max_interval: 7)
 ```
 
+### Multiple Seeds (Advanced)
+
+When passing an array of seeds `[s1, s2, s3]`, they are processed **sequentially and chained**: each seed starts from the valid endpoints of the previous seed's tree. In this case, `history` contains the confirmed path from previous seeds.
+
+```ruby
+# With multiple seeds, history IS populated:
+rules.apply([seed1, seed2, seed3])
+# seed1 processes → fish valid endpoints
+# seed2 starts from each endpoint, history contains seed1's path
+# seed3 starts from seed2's endpoints, history contains seed1+seed2's paths
+```
+
+This is useful for multi-phase generation where each phase has different rules, but for most use cases the single-seed cumulative state pattern is simpler and recommended.
+
 ## Generative Grammar
 
 Formal grammars with combinatorial generation using operators. Useful for generating melodic patterns with rhythmic constraints, harmonic progressions, or variations of musical motifs.