musa-dsl 0.43.0 → 0.49.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa34fee0b26abe335f3288cc4593230f4f9e76b0b8f198594d5880c3055038f6
-  data.tar.gz: 7836f199fc7a81192269391d4e26d68e99de85d116750e30c32bf39df421ed39
+  metadata.gz: 489a7b49196f4a1ff58782264f6b1d36da306d6a64671785b4aa904567461b4c
+  data.tar.gz: '099acf5b2ed77c18494bcfecc7b73cf375cf37a46c6e2ba940df3a5015934d60'
 SHA512:
-  metadata.gz: 296f17a87edaf39c519c3054bfc790445aa45aa5295aee76b978c831465a6e4a312b2c541fc9d99424e7365ff9726055e05537ddb6b7b362ee5fb69bb5b3e83d
-  data.tar.gz: 571a82f51bc2e5d61c77f214629d727c8c47ed1c7a8d0ba6c4ac7c3019ccd4ba93f7a6f85b81e7041fdb773aa11607ab1606a7a2f9adbee252ccc72e8e516a76
+  metadata.gz: 94c57a46910a986ed39c997ed9680a8a232e6b38d892cc6780c03ef5a01c30f7f70ab3db3fa4cfbdb792b9e575191ef90ac8f6a380c7bd7cf8b74098e55acd1a
+  data.tar.gz: 394f30c7fc69e0e0474b75778440ac56a2e7847ab50c0f374e84c5893ded282e379bdc731b00dcedf2c4808fc918dcbfc4682f4b71ef3818d57c9daafe8f11e0

data/.yardopts

@@ -1,7 +1,6 @@
 --markup markdown
 --title "Musa-DSL API"
---readme README.md
+--readme README.yard.md
 --no-private
 --embed-mixins
 lib/**/*.rb
-

data/README.md

@@ -23,7 +23,7 @@ Musa-DSL is a programming language DSL (Domain-Specific Language) based on Ruby
 - **Transport & Timing** - Multiple clock sources (internal, MIDI, external) with microsecond precision
 - **Audio Engine Independent** - Works with any MIDI-capable, OSC-capable or any other output hardware or software system
 - **Series-Based Composition** - Flexible sequence generators for pitches, rhythms, dynamics, and any musical parameter
-- **Generative Tools** - Markov chains, combinatorial variations (Variatio), rule-based production systems (Rules), formal grammars (GenerativeGrammar), and genetic algorithms (Darwin)
+- **Generative Tools** - Markov chains, combinatorial variations (Variatio), formal grammars (GenerativeGrammar), and genetic algorithms (Darwin)
 - **Matrix Operations** - Mathematical transformations for musical structures
 - **Scale System** - Comprehensive support for scales, tuning systems, and chord structures
 - **Neumalang Notation** - Intuitive text-based and customizable musical (or sound) notation
@@ -39,40 +39,7 @@ Musa-DSL is a programming language DSL (Domain-Specific Language) based on Ruby
 - [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.
+[VSCode](https://code.visualstudio.com/) with the Ruby LSP extension also works well, though Ruby autocomplete and hover documentation are less complete.
 
 ### Framework Installation
 
@@ -91,24 +58,19 @@ gem install musa-dsl
 **Requirements:**
 - Ruby ~> 3.4
 
-## Quick Start
-
-A complete working example with multiple interacting voice lines, demonstrating sequencer DSL, timing control, and shared state.
+## Examples
 
-**📖 [Complete Quick Start Guide](docs/getting-started/quick-start.md)**
+Two complete, runnable examples included here. Pedagogical learning is covered separately in the [musadsl-demo](https://github.com/javier-sy/musadsl-demo) repository.
 
-## Tutorial
-
-Detailed tutorial showing the Neuma notation system for composing melodies with grade-based notation.
-
-**📖 [Complete Tutorial](docs/getting-started/tutorial.md)**
+- **[Sequencer DSL with interacting voices](docs/examples/sequencer-dsl-voices.md)** — multiple voice lines coordinated through shared state, demonstrating the sequencer DSL and timing primitives.
+- **[Neuma notation](docs/examples/neuma-notation.md)** — composing melodies with grade-based Neuma notation and the parser.
 
 ## 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
+- **Generative tools**: Markov chains, Variatio, Darwin, Grammar, 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
@@ -117,175 +79,132 @@ Each demo is a complete, runnable project with documentation explaining the conc
 
 **📦 [musadsl-demo Repository](https://github.com/javier-sy/musadsl-demo)**
 
-## System Architecture
+## MusaDSL Ecosystem
 
 MusaDSL is a comprehensive ecosystem consisting of a core framework (musa-dsl) and associated projects for communication, development, and integration.
 
-### MusaDSL Ecosystem
-
 **Core Framework:**
 - [**musa-dsl**](https://github.com/javier-sy/musa-dsl) - Main DSL framework for algorithmic composition and musical thinking
 
-**MIDI Communication Stack:**
+**MIDI Communication Stack** (used internally by musa-dsl for MIDI I/O):
 - [**midi-events**](https://github.com/javier-sy/midi-events) - Low-level MIDI event definitions and protocols
 - [**midi-parser**](https://github.com/javier-sy/midi-parser) - MIDI file parsing and analysis
 - [**midi-communications**](https://github.com/javier-sy/midi-communications) - Cross-platform MIDI I/O abstraction layer
 - [**midi-communications-macos**](https://github.com/javier-sy/midi-communications-macos) - macOS-specific MIDI native implementation
 
-**Live Coding Environment (MusaLCE):**
-- [**musalce-server**](https://github.com/javier-sy/musalce-server) - Live coding evaluation server with hot-reload capabilities
-- [**MusaLCEClientForVSCode**](https://github.com/javier-sy/MusaLCEClientForVSCode) - Visual Studio Code extension for live coding
-- [**MusaLCEClientForAtom**](https://github.com/javier-sy/MusaLCEClientForAtom) - Atom editor plugin for live coding
-- [**MusaLCEforBitwig**](https://github.com/javier-sy/MusaLCEforBitwig) - Bitwig Studio integration for live coding
-- [**MusaLCEforLive**](https://github.com/javier-sy/MusaLCEforLive) - Ableton Live integration for live coding
-
-### musa-dsl Internal Architecture
-
-The musa-dsl framework is organized in modular layers:
+## MusaDSL Architecture
 
-#### 1. Foundation Layer
-- **core-ext** - Ruby core extensions (refinements for enhanced syntax)
-- **logger** - Structured logging system with severity levels
+The musa-dsl framework is organized in modular layers. Each component has its own detailed documentation.
 
-#### 2. Temporal & Scheduling Layer
-- **sequencer** - Event scheduling engine with microsecond precision
-  - Tick-based (quantized) and tickless (continuous) timing modes
-  - Series playback with automatic duration management
-  - Support for polyrhythms and polytemporal structures
-- **transport** - High-level playback control with clock synchronization
-  - BPM management and tempo changes
-  - Start/stop/pause/continue controls
-  - Multiple clock source support (internal, MIDI, external)
+### 1. Foundation Layer
+- [**core-ext**](docs/subsystems/core-extensions.md) - Ruby refinements and metaprogramming utilities: Arrayfy, Hashify, ExplodeRanges, DeepCopy, DynamicProxy, AttributeBuilder.
+- **logger** - Structured logging system with severity levels.
 
-#### 3. Notation & Parsing Layer
-- **neumas** - Text-based musical notation system
-- **neumalang** - Parser and interpreter for neuma notation with DSL support
+### 2. Temporal & Scheduling Layer
+- [**sequencer**](docs/subsystems/sequencer.md) - Event scheduling engine with musical time (bars/beats), microsecond-precise tick-based timing, and a DSL for temporal composition. Tick-based (quantized) and tickless (continuous) modes; series playback with automatic duration management; polyrhythms and polytemporal structures.
+- [**transport**](docs/subsystems/transport.md) - Comprehensive timing infrastructure connecting clock sources to the sequencer. Supports multiple clock types (TimerClock, InputMidiClock, ExternalTickClock, DummyClock), BPM management, tempo changes, and the start/stop/pause/continue playback lifecycle.
 
-#### 4. Generation & Transformation Layer
-- **series** - Lazy sequence generators with functional operations
-  - Map, filter, transpose, repeat, and combination operations
-  - Infinite and finite series support
-- **generative** - Algorithmic composition tools
-  - **Markov chains**: Probabilistic sequence generation
-  - **Variatio**: Cartesian product parameter variations
-  - **Rules**: L-system-like production systems with growth/pruning
-  - **GenerativeGrammar**: Formal grammar-based generation
-  - **Darwin**: Genetic algorithms for evolutionary composition
-- **matrix** - Matrix operations for musical gestures
-  - Matrix-to-P (point sequence) conversion
-  - Gesture condensation and transformation
+### 3. Notation & Parsing Layer
+- [**neumas + neumalang**](docs/subsystems/neumas.md) - Compact text-based musical notation system with parser and interpreter for converting notation to structured musical data, with DSL support.
 
-#### 5. Output & Communication Layer
-- **transcription** - Musical event transformation system
-  - Ornament expansion (trills, mordents, turns)
-  - GDV to MIDI/MusicXML conversion
-  - Dynamic articulation rendering
-- **musicxml** - MusicXML score generation
-  - Multi-part score creation
-  - Notation directives (dynamics, tempo, articulations)
-  - Standard MusicXML 3.0 output
-- **midi** - MIDI voice management
-  - Polyphonic voice allocation
-  - Channel management
-  - Note-on/note-off scheduling
+### 4. Generation & Transformation Layer
+- [**series**](docs/subsystems/series.md) - Lazy functional sequence generators with map/filter operations, numeric generators, buffering, quantization, and timed merging. Transpose, repeat, and combination operations; infinite and finite series support.
+- [**generative**](docs/subsystems/generative.md) - Algorithmic composition tools: Markov chains (probabilistic sequence generation), Variatio (Cartesian product parameter variations), GenerativeGrammar (formal grammar-based generation), and Darwin (genetic algorithms for evolutionary composition).
+- [**matrix**](docs/subsystems/matrix.md) - Matrix operations for musical gestures: matrix-to-P (point sequence) conversion for sequencer playback, gesture condensation and transformation. Treats sonic gestures as geometric objects.
 
-#### 6. Musical Knowledge Layer
-- **music** - Scales, tuning systems, intervals, and chord structures
-  - Equal temperament and just intonation support
-  - Modal scales (major, minor, chromatic, etc.)
-  - Chord definitions and harmonic analysis
-- **datasets** - Musical data structures (GDV, PDV, Score)
-  - GDV (Grade-Duration-Velocity): Scale-relative representation
-  - PDV (Pitch-Duration-Velocity): Absolute pitch representation
-  - Score: Timeline-based multi-track composition structure
+### 5. Output & Communication Layer
+- [**transcription**](docs/subsystems/transcription.md) - Musical event transformation system with ornament expansion (trills, mordents, turns), GDV to MIDI/MusicXML conversion, and dynamic articulation rendering. Expansion for MIDI or preservation as notation symbols for MusicXML.
+- [**musicxml**](docs/subsystems/musicxml-builder.md) - MusicXML score generation. Hierarchical structure, multiple voices, multi-part scores, articulations, dynamics, tempo, and notation directives. Standard MusicXML 3.0 output.
+- [**midi**](docs/subsystems/midi.md) - MIDI voice management with polyphonic voice allocation, channel management, note-on/note-off scheduling, automatic note tracking, and MIDI input recording with precise timestamping.
 
-#### 7. Development & Interaction Layer
-- **repl** - Interactive Read-Eval-Print Loop for live composition
+### 6. Musical Knowledge Layer
+- [**music**](docs/subsystems/music.md) - Scales, tuning systems, intervals, and chord structures. Equal temperament and just intonation support; modal scales (major, minor, chromatic, etc.); chord definitions, harmonic analysis, and chord navigation.
+- [**datasets**](docs/subsystems/datasets.md) - Type-safe musical event representations: GDV (Grade-Duration-Velocity, scale-relative), PDV (Pitch-Duration-Velocity, absolute), PS, P, V. Conversions, validation, Score container (timeline-based multi-track composition), and advanced queries.
 
-## Core Subsystems
+### 7. Development & Interaction Layer
+- [**repl**](docs/subsystems/repl.md) - Interactive Read-Eval-Print Loop for live composition. TCP-based server for real-time code evaluation and error handling. Consumed by external REPL clients (editor extensions, custom evaluators).
 
-### MIDI - Voice Management & Recording
+## Where to start
 
-Polyphonic voice management for MIDI output with automatic note tracking, and MIDI input recording with precise timestamping.
+The layers above are the order the framework is BUILT in, bottom-up by
+dependency. It is not the order to read it in. These are:
 
-**📖 [Complete Documentation](docs/subsystems/midi.md)**
+**New to MusaDSL?** Start with one of the [examples](#examples) and the
+architecture above, then read in this order — which cuts across the layers on
+purpose, because output is the fastest way to hear that something works:
 
-### Sequencer - Temporal Engine
+1. [midi](docs/subsystems/midi.md) — getting a sound out
+2. [sequencer](docs/subsystems/sequencer.md) — putting it in time
+3. [series](docs/subsystems/series.md) — generating the material
+4. [datasets](docs/subsystems/datasets.md) — what an event is made of
 
-Event scheduling engine with musical time (bars/beats), precise tick-based timing, and DSL for temporal composition.
+**Want to compose?**
 
-**📖 [Complete Documentation](docs/subsystems/sequencer.md)**
+1. [neumas](docs/subsystems/neumas.md) — the notation
+2. [music](docs/subsystems/music.md) — scales and chords
+3. [generative](docs/subsystems/generative.md) — Markov, Variatio, grammars, Darwin
+4. [musicxml-builder](docs/subsystems/musicxml-builder.md) — if the piece has to be read on paper
+5. The [22 demo projects](https://github.com/javier-sy/musadsl-demo), which are
+   complete pieces rather than snippets
 
-### Transport - Timing & Clocks
+**Live coding?**
 
-Comprehensive timing infrastructure connecting clock sources to the sequencer. Supports multiple clock types (TimerClock, InputMidiClock, ExternalTickClock, DummyClock) and manages playback lifecycle with precise timing control.
+1. [repl](docs/subsystems/repl.md) — the server your editor talks to
+2. A MusaLCE client (VSCode, Bitwig, Live)
+3. [sequencer](docs/subsystems/sequencer.md) — its DSL is what you type live
+4. [transport](docs/subsystems/transport.md) — syncing to a DAW's clock
 
-**📖 [Complete Transport Documentation](docs/subsystems/transport.md)**
+**Extending the DSL?** These two are the foundation the framework is written on,
+and they are the last thing to read rather than the first:
 
+1. [core-extensions](docs/subsystems/core-extensions.md) — the refinements and
+   metaprogramming everything else assumes
+2. [datasets](docs/subsystems/datasets.md) — read as an extension point: how a
+   Hash becomes a musical event, and how to add your own
 
-### Series - Sequence Generators
+**And one that is not a stage of any of them.**
+[idioms](docs/idioms.md) is for the moment of writing, whichever path brought you
+there: it is organised by the SHAPE of the problem, and each entry names a reflex
+— something a competent programmer writes before asking what MusaDSL calls it.
+The reflex always works, which is the problem: it produces code that runs, sounds
+right, passes every test, and is foreign to the framework. Read it from the
+symptom, when you are about to make the mistake rather than after.
 
-Lazy functional sequence generators with map/filter operations, numeric generators, buffering, quantization, and timed merging.
+## Documentation
 
-**📖 [Complete Documentation](docs/subsystems/series.md)**
+The subsystem guides linked above are the conceptual documentation: when each
+one is the answer, how to think about it, and the traps. Every Ruby block in
+them is executed by `tools/doc-examples.rb`, and every output they declare is
+compared with what the code actually returns -- so a page that has drifted fails
+the suite rather than misleading a reader.
 
-### Neumas & Neumalang - Musical Notation
+The API reference is generated from the inline YARD documentation, whose
+`@example` blocks are held to the same standard:
 
-Compact text-based musical notation system with parser for converting notation to structured musical data.
-
-**📖 [Complete Documentation](docs/subsystems/neumas.md)**
-
-### Datasets - Sonic Data Structures
-
-Type-safe musical event representations (GDV, PDV, PS, P, V) with conversions, validation, Score container, and advanced queries.
-
-**📖 [Complete Documentation](docs/subsystems/datasets.md)**
-
-### Matrix - Sonic Gesture Conversion
-
-Convert matrix representations to point sequences for sequencer playback, treating sonic gestures as geometric objects.
-
-**📖 [Complete Documentation](docs/subsystems/matrix.md)**
-
-### Transcription - MIDI & MusicXML Output
-
-Convert between representations with ornament expansion for MIDI or preservation as notation symbols for MusicXML.
-
-**📖 [Complete Documentation](docs/subsystems/transcription.md)**
-
-### Music - Scales & Chords
-
-Comprehensive scale and chord systems with equal temperament, custom tunings, chord navigation, and extensible definitions.
-
-**📖 [Complete Documentation](docs/subsystems/music.md)**
-
-### Generative - Algorithmic Composition
-
-Algorithmic composition tools: Markov chains, Variatio, Rules (L-systems), GenerativeGrammar, and Darwin (genetic algorithms).
-
-**📖 [Complete Documentation](docs/subsystems/generative.md)**
-
-### MusicXML Builder - Music Notation Export
-
-Comprehensive MusicXML score generation with hierarchical structure, multiple voices, articulations, and dynamics.
-
-**📖 [Complete Documentation](docs/subsystems/musicxml-builder.md)**
+```bash
+bundle exec yard doc
+bundle exec yard server
+```
 
-### REPL - Live Coding Infrastructure
+Then open http://localhost:8808.
 
-TCP-based server for live coding with MusaLCE clients (VSCode, Atom, Bitwig, Live), real-time code evaluation and error handling.
+## Contributing
 
-**📖 [Complete Documentation](docs/subsystems/repl.md)**
+Contributions are welcome. Fork the repository, create a feature branch, make
+your changes with tests, and open a pull request.
 
-### Core Extensions - Advanced Metaprogramming
+**Repository:** https://github.com/javier-sy/musa-dsl
 
-Ruby refinements and metaprogramming utilities: Arrayfy, Hashify, ExplodeRanges, DeepCopy, DynamicProxy, AttributeBuilder, Logger.
+## Examples & Works
 
-**📖 [Complete Documentation](docs/subsystems/core-extensions.md)**
+Listen to compositions created with Musa-DSL: [yeste.studio](https://yeste.studio)
 
 ## Author
 
-* [Javier Sánchez Yeste](https://github.com/javier-sy)
+* [Javier Sánchez Yeste](https://github.com/javier-sy) -- javier (at) yeste.studio
+
+Special thanks to [JetBrains](https://www.jetbrains.com/?from=Musa-DSL) for
+providing an Open Source project license for RubyMine during several years.
 
 ## License
 

data/README.yard.md

@@ -0,0 +1,37 @@
+# Musa-DSL — API reference
+
+A Ruby framework and DSL for algorithmic sound and musical thinking and
+composition. It builds complex temporal structures independently of the audio
+rendering engine: sequencing and transport, lazy series, a text notation
+(neumalang), scales and chords, generative tools, and transcription to MIDI and
+MusicXML.
+
+**This page is the API reference** — classes, methods, signatures, and the
+`@example` blocks attached to them. Every one of those examples is executed and
+its declared output compared against what the code actually returns, so what you
+read here has been run.
+
+## The conceptual documentation is not here
+
+Knowing a signature is not knowing when to reach for it. The guides that answer
+*when is this the answer, and when is it not* — one per subsystem, plus a
+catalogue of idioms organised by the shape of the problem — live in the
+repository, where their cross-references work:
+
+**https://github.com/javier-sy/musa-dsl**
+
+They also travel inside the gem itself, under `docs/`, so they are readable
+offline from the installed copy and always match the version you have.
+
+## Installing
+
+```ruby
+gem 'musa-dsl'
+```
+
+Requires Ruby ~> 3.4.
+
+---
+
+Copyright (c) 2016-2026 [Javier Sánchez Yeste](https://yeste.studio),
+licensed under LGPL-3.0-or-later.

data/docs/{getting-started/tutorial.md → examples/neuma-notation.md}

@@ -1,6 +1,6 @@
-# Tutorial: Not So Quick Start
+# Neuma notation
 
-Here's a more detailed example showing the Neuma notation system:
+A more detailed example showing the Neuma notation system:
 
 ```ruby
 require 'musa-dsl'
@@ -20,7 +20,10 @@ decoder = Decoders::NeumaDecoder.new(
 
 # Define a melody using neuma notation with duration and velocity
 # Format: (grade duration velocity)
-# Durations: 1/4 = quarter, 1/2 = half, 1 = whole
+# Durations are multiples of base_duration, which here is 1r -- a bar. So the
+# numbers below are fractions of a bar: 1/4 of a bar, 1/2 of a bar, a whole
+# bar. In 4/4 those are a quarter, a half and a whole note; in another meter
+# they are not, because a bar and a whole note are only the same in 4/4.
 # Velocities: pp, p, mp, mf, f, ff
 melody = "(0 1/4 p) (+2 1/4 mp) (+2 1/4 mf) (-1 1/2 f) " \
          "(0 1/4 mf) (+4 1/4 mp) (+5 1/2 f) (+7 1/4 ff) " \

data/docs/{getting-started/quick-start.md → examples/sequencer-dsl-voices.md}

@@ -1,6 +1,6 @@
-# Quick Start
+# Sequencer DSL with interacting voices
 
-Here's a complete example showcasing the sequencer DSL with multiple melodic lines that interact with each other:
+A complete example showcasing the sequencer DSL with multiple melodic lines that interact with each other:
 
 ```ruby
 require 'musa-dsl'