musa-dsl 0.41.0 → 0.42.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2a2ee1f86c7d0b4a6c6ecb95b92ea4b15ead3a305c9c6252ea74eb1d437b16fb
-  data.tar.gz: 07fea02dd0fe457b16c79e18eb82fedb0236c929fa3d1b1e3b32b621d419e6f7
+  metadata.gz: 6f157001c0d45494eda872c34d4d73c161b686da78f0192868637873845ca62e
+  data.tar.gz: 2d93034d622985b67ae894d0cf7f4a5acdba787b4453fd6dbad08aa88d096866
 SHA512:
-  metadata.gz: 0f186d4ac7ee38fb1984a7737e220c25a12411b104728181854898580a7059f87efc6828a769bee268695cb80d3d2818b6dadc0e21a4a1a3a57c853c7502817c
-  data.tar.gz: 84bf07953180497c334da1d471067a4561957da58a9aac4fe454bbfac364f4c44295e1e12e7ad935ca04f3e304e248fe9d89f2d866aaed9c62d87634d2fcbe15
+  metadata.gz: 4dc00ab7d48971758d26bf982e8b61771fe81c26bd9e7cdedba97e457d3c97ff8286f7e53689712c97bb10674fe5f59261ee1f1186a1f20dbda87b62a16aa858
+  data.tar.gz: 9da464c4a8cfce824392e1c37b4987b84bde21c59924da5daf34b97b46c183d70d06afff212ab0de7d5b45971c7267aab5260730509b21522f12c49ab5474d46

data/.gitignore

@@ -14,3 +14,4 @@ doc
 *.backup
 .vscode
 .ruby-lsp
+

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.

data/docs/subsystems/music.md

@@ -123,8 +123,8 @@ c_major[:V]    # => Dominant (G)
 pitch = c_major.tonic.pitch   # => 60
 
 # Navigate with octaves
-note = c_major[2].octave(1)  # E in octave 1
-pitch_with_octave = note.pitch     # => 76
+note = c_major[2].at_octave(1)  # E transposed up 1 octave
+pitch_with_octave = note.pitch      # => 76
 
 # Chromatic operations - sharp and flat
 c_sharp = c_major.tonic.sharp   # => C# (chromatic, +1 semitone)
@@ -211,10 +211,12 @@ seventh_chord = i_chord.with_size(:seventh)  # C major 7th
 ninth_chord = i_chord.with_size(:ninth)      # C major 9th
 
 # Voicing modifications - move specific tones to different octaves
-voiced = i_chord.move(root: -1, fifth: 1)  # Root down, fifth up
+voiced = i_chord.with_move(root: -1, fifth: 1)  # Root down, fifth up
+i_chord.move  # => { root: -1, fifth: 1 } (current settings)
 
 # Duplicate tones in other octaves
-doubled = i_chord.duplicate(root: -2, third: [-1, 1])  # Root 2 down, third 1 down and 1 up
+doubled = i_chord.with_duplicate(root: -2, third: [-1, 1])  # Root 2 down, third 1 down and 1 up
+i_chord.duplicate  # => { root: -2, third: [-1, 1] } (current settings)
 
 # Transpose entire chord
 lower = i_chord.octave(-1)  # Move chord down one octave
@@ -245,28 +247,45 @@ c_major.degree_of_chord(cm)     # => nil
 ```ruby
 # Get the same chord but with a different scale as context
 g_mixolydian = Scales.et12[440.0].mixolydian[67]
-g7_in_mixolydian = g_mixolydian.chord_on(g7)
+g7_in_mixolydian = g7.as_chord_in_scale(g_mixolydian)
 g7_in_mixolydian.scale                        # => G Mixolydian scale
 g_mixolydian.degree_of_chord(g7_in_mixolydian)  # => 0 (I degree)
 ```
 
+#### Creating Chords from Scale Degrees
+
+```ruby
+# Create chords directly from scale degrees using Scale#chord_on
+i_chord = scale.chord_on(0)                    # Tonic triad
+v7 = scale.chord_on(:dominant, :seventh)       # V7
+iv_maj7 = scale.chord_on(:IV, :seventh, :major)  # IVmaj7
+
+# Equivalent to using the note method then chord:
+scale[0].chord                      # Same as scale.chord_on(0)
+scale[:dominant].chord(:seventh)    # Same as scale.chord_on(:dominant, :seventh)
+
+# With voicing parameters
+scale.chord_on(:I, :seventh, move: {root: -1})
+scale.chord_on(0, :triad, duplicate: {root: 1})
+```
+
 #### Finding Scales That Contain a Chord
 
 ```ruby
 g_triad = c_major.dominant.chord  # G-B-D
 
 # Search in diatonic scales
-g_triad.in_scales(family: :diatonic)
+g_triad.search_in_scales(family: :diatonic)
 # => [Chord in C major (V), Chord in G major (I), Chord in D major (IV), ...]
 
 # Search using metadata filters
-g_triad.in_scales(family: :greek_modes, brightness: -1..1)
+g_triad.search_in_scales(family: :greek_modes, brightness: -1..1)
 
 # Search in all scale types
-g_triad.in_scales
+g_triad.search_in_scales
 
 # Each result has its scale context
-g_triad.in_scales(family: :diatonic).each do |chord|
+g_triad.search_in_scales(family: :diatonic).each do |chord|
   scale = chord.scale
   degree = scale.degree_of_chord(chord)
   puts "#{scale.kind.class.id} rooted on #{scale.root_pitch}: degree #{degree}"
@@ -283,10 +302,10 @@ end
 tuning = Scales.et12[440.0]
 
 # Search at ScaleKind level
-tuning.major.scales_containing(g_triad)
+tuning.major.find_chord_in_scales(g_triad)
 
 # Search at ScaleSystemTuning level with metadata filters
-tuning.chords_of(g7, family: :diatonic, roots: 60..71)
+tuning.search_chord_in_scales(g7, family: :diatonic, roots: 60..71)
 ```
 
 ### Scale Kind Metadata
@@ -432,16 +451,16 @@ tuning.scale_kinds(family: :greek_modes) { |klass| klass.metadata[:brightness]&.
 
 #### Integration with Chord Search
 
-The `chords_of` method uses the same metadata filtering:
+The `search_chord_in_scales` method uses the same metadata filtering:
 
 ```ruby
 g7 = tuning.major[60].dominant.chord(:seventh)
 
 # Find G7 in diatonic scales
-tuning.chords_of(g7, family: :diatonic)
+tuning.search_chord_in_scales(g7, family: :diatonic)
 
 # Find G7 in scales with specific brightness
-tuning.chords_of(g7, brightness: -1..1)
+tuning.search_chord_in_scales(g7, brightness: -1..1)
 ```
 
 ## Defining Custom Scale Systems, Scale Kinds, and Chord Definitions

data/docs/subsystems/transport.md

@@ -87,6 +87,32 @@ dummy_clock = Musa::Clock::DummyClock.new(100)
 4. **on_change_position** - Run when position jumps/seeks
 5. **after_stop** - Run when transport stops
 
+### Clean Shutdown
+
+To cleanly terminate a transport using TimerClock:
+
+1. Call `transport.stop` from within a scheduled event
+2. This calls `clock.terminate` internally
+3. The clock's run loop exits
+4. `transport.start` returns
+5. Your code continues after `transport.start` for cleanup
+
+```ruby
+# Example: Self-terminating composition
+transport.sequencer.at 10 do
+  puts "Composition finished"
+  transport.stop  # This will cause transport.start to return
+end
+
+transport.start  # Blocks until transport.stop is called
+puts "Cleanup..."  # Executes after stop
+output.close
+```
+
+**Note:** For `InputMidiClock`, stop/start cycles are controlled by the DAW
+and don't terminate the process. The `terminate` method can be used explicitly
+if you need the run loop to exit.
+
 **Key methods:**
 - `start` - Start playback (blocks while running)
 - `stop` - Stop playback

data/lib/musa-dsl/datasets/dataset.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Musical dataset framework for MusaDSL.
 #
 # The Datasets module provides a comprehensive framework for representing and transforming

data/lib/musa-dsl/datasets/gdv.rb

@@ -204,7 +204,7 @@ module Musa::Datasets
         pdv[:pitch] = if self[:silence]
                         :silence
                       else
-                        scale[self[:grade]].sharp(self[:sharps] || 0).octave(self[:octave] || 0).pitch
+                        scale[self[:grade]].sharp(self[:sharps] || 0).at_octave(self[:octave] || 0).pitch
                       end
       end
 
@@ -399,8 +399,8 @@ module Musa::Datasets
             (self[:sharps] || 0) != (previous[:sharps] || 0)
 
             gdvd[:delta_grade] =
-                scale[self[:grade]].octave(self[:octave]).wide_grade -
-                scale[previous[:grade]].octave(previous[:octave]).wide_grade
+                scale[self[:grade]].at_octave(self[:octave]).wide_grade -
+                scale[previous[:grade]].at_octave(previous[:octave]).wide_grade
 
             gdvd[:delta_sharps] = (self[:sharps] || 0) - (previous[:sharps] || 0)
           end

data/lib/musa-dsl/datasets/p.rb

@@ -206,7 +206,7 @@ module Musa::Datasets
     #
     # @api private
     class PtoTimedSerie
-      include Musa::Series::Serie.base
+      include Musa::Series::Serie::Base
 
       # Creates new timed serie adapter.
       #

data/lib/musa-dsl/datasets/score/to-mxml/process-time.rb

@@ -42,7 +42,8 @@ module Musa::Datasets::Score::ToMXML
     # @note This method is experimental and currently unused. See TODO comment.
     #
     # @api private
-    def initialize(element, bar, bar_size = 1r) # TODO remove (unused because of bad strategy to time groups)
+    def initialize(element, bar, bar_size = Rational(1))
+      # TODO remove (unused because of bad strategy to time groups)
       @continue_from_previous_bar = element[:start] < bar
       @continue_to_next_bar = element[:finish] >= bar + bar_size
 
@@ -99,7 +100,8 @@ module Musa::Datasets::Score::ToMXML
   #
   # @api private
   # @todo Complete or remove this experimental method
-  def time_and_tuplet_optimize(elements, bar, bar_size = 1r) # TODO remove (unused because of bad strategy to time groups)
+  def time_and_tuplet_optimize(elements, bar, bar_size = Rational(1))
+    # TODO remove (unused because of bad strategy to time groups)
     decompositions = elements.collect { |pdv| ElementDurationDecomposition.new(pdv, bar, bar_size) }
 
     denominators = decompositions.collect { |g| g.duration_decomposition.collect { |d| d.to_r.denominator } }.flatten.uniq

data/lib/musa-dsl/datasets/score.rb

@@ -143,12 +143,14 @@ module Musa::Datasets
     # @return [Object, nil] attribute value
     #
     # @api private
-    def [](key)
+    def get(key)
       if NaturalKeys.include?(key) && self.respond_to?(key)
         self.send(key)
       end
     end
 
+    alias_method :[], :get
+
     # Returns latest finish time of all events.
     #
     # @return [Rational, nil] latest finish time, or nil if score is empty

data/lib/musa-dsl/generative/generative-grammar.rb

@@ -369,10 +369,12 @@ module Musa
         # @param index [Integer] option index
         #
         # @return [Node] option converted to node
-        def [](index)
+        def get(index)
           options[index].to_serie.to_node
         end
 
+        alias_method :[], :get
+
         # Converts options to series.
         #
         # Generates options and converts them to a {Musa::Series::Serie}.

data/lib/musa-dsl/generative/markov.rb

@@ -97,7 +97,7 @@ module Musa
     # Implements {Musa::Series::Serie} interface for integration with series operations.
     class Markov
       # TODO: adapt to series prototyping
-      include Musa::Series::Serie.base
+      include Musa::Series::Serie::Base
 
       # Creates Markov chain generator.
       #

data/lib/musa-dsl/midi/midi-voices.rb

@@ -385,10 +385,12 @@ module Musa
         end
 
         # @return [Integer, nil] last value assigned to the controller.
-        def [](controller_number_or_symbol)
+        def get(controller_number_or_symbol)
           @controller[number_of(controller_number_or_symbol)]
         end
 
+        alias_method :[], :get
+
         # Resolves a controller reference to its MIDI CC number.
         #
         # @param controller_number_or_symbol [Integer, Symbol] CC number or alias.

data/lib/musa-dsl/music/chord-definition.rb

@@ -1,5 +1,3 @@
-require 'set'
-
 module Musa
   # Chord construction and manipulation framework.
   #
@@ -115,10 +113,14 @@ module Musa
       # @example
       #   ChordDefinition[:maj]   # => <ChordDefinition :maj>
       #   ChordDefinition[:min7]  # => <ChordDefinition :min7>
-      def self.[](name)
+      def self.get(name)
         @definitions[name]
       end
 
+      class << self
+        alias_method :[], :get
+      end
+
       # Registers a new chord definition.
       #
       # Creates and registers a chord definition with specified intervals and features.
@@ -150,7 +152,7 @@ module Musa
         definition.features.each { |k, v| @features_by_value[v] = k }
 
         @feature_keys ||= Set[]
-        features.keys.each { |feature_name| @feature_keys << feature_name }
+        features.each_key { |feature_name| @feature_keys << feature_name }
 
         self
       end
@@ -267,7 +269,7 @@ module Musa
 
       # Checks if chord fits within a scale.
       #
-      # @param scale [Scale] scale to check against
+      # @param scale [Scales::Scale] scale to check against
       # @param chord_root_pitch [Integer] chord root pitch
       # @return [Boolean] true if all chord notes are in scale
       #

data/lib/musa-dsl/music/chord-definitions.rb

@@ -1,5 +1,42 @@
 require_relative 'chord-definition'
 
+# Standard chord definitions for Western harmony.
+#
+# This file registers the common chord types used in Western music theory,
+# organized by size (number of notes) and quality (major, minor, etc.).
+#
+# ## Chord Categories
+#
+# ### Triads (3 notes)
+# - **Major** (:maj) - Root, major 3rd, perfect 5th (0-4-7)
+# - **Minor** (:min) - Root, minor 3rd, perfect 5th (0-3-7)
+# - **Diminished** (:dim) - Root, minor 3rd, diminished 5th (0-3-6)
+# - **Augmented** (:aug) - Root, major 3rd, augmented 5th (0-4-8)
+#
+# ### Seventh Chords (4 notes)
+# - **Major 7th** (:maj7) - Major triad + major 7th (0-4-7-11)
+# - **Minor 7th** (:min7) - Minor triad + minor 7th (0-3-7-10)
+# - **Dominant 7th** (:dom7) - Major triad + minor 7th (0-4-7-10)
+#
+# ### Extended Chords (5+ notes)
+# - **9th chords**: :maj9, :min9, :dom9
+# - **11th chords**: :maj11, :min11
+# - **13th chords**: :maj13, :min13
+#
+# ## Usage
+#
+# Chords are accessed via scale notes using the {Musa::Scales::NoteInScale#chord} method:
+#
+#     scale = Scales.et12[440.0].major[60]
+#     scale.tonic.chord                    # Major triad (default)
+#     scale.tonic.chord :seventh           # Major 7th
+#     scale.dominant.chord :seventh        # Dominant 7th
+#     scale.tonic.chord quality: :minor    # Minor triad
+#
+# @see Musa::Chords::ChordDefinition.register How chords are registered
+# @see Musa::Chords::Chord How to build and use chords
+# @see Musa::Scales::NoteInScale#chord Building chords from scale notes
+
 # TODO trasladar los acordes de https://en.wikipedia.org/wiki/Chord_notation
 
 # TRIADS