musa-dsl 0.30.2 → 0.41.0

data/docs/subsystems/musicxml-builder.md

@@ -0,0 +1,264 @@
+# MusicXML Builder - Music Notation Export
+
+Comprehensive builder for generating MusicXML 3.0 files compatible with music notation software (Finale, Sibelius, MuseScore, Dorico, etc.). MusicXML is the standard open format for exchanging digital sheet music between applications.
+
+## Root Class: ScorePartwise
+
+The entry point for creating MusicXML documents is `Musa::MusicXML::Builder::ScorePartwise`, which represents the `<score-partwise>` root element. It organizes music by parts (instruments/voices) and measures.
+
+**Structure:**
+- **Metadata**: work info, movement info, creators, rights, encoding date
+- **Part List**: part definitions with names and abbreviations
+- **Parts**: musical content organized by measures
+
+## Key Features
+
+**Multiple staves:**
+Use `staff:` parameter to specify which staff (1, 2, etc.) for grand staff notation (piano, harp, organ, etc.).
+```ruby
+pitch 'C', octave: 3, staff: 2  # Note in staff 2 (bass clef)
+```
+
+**Multiple voices:**
+Use `voice:` parameter for polyphonic notation within a single staff (independent melodic lines).
+```ruby
+pitch 'C', octave: 4, voice: 1  # Voice 1
+pitch 'E', octave: 3, voice: 2  # Voice 2 (simultaneous)
+```
+
+**Backup/Forward:**
+Navigate timeline within measures to layer voices. `backup(duration)` returns to an earlier point, `forward(duration)` skips ahead.
+```ruby
+pitch 'C', octave: 4, duration: 4
+backup 4  # Return to beginning
+pitch 'E', octave: 3, duration: 4  # Play simultaneously
+```
+
+**Divisions:**
+Set rhythmic precision as divisions per quarter note in measure attributes. Higher values allow smaller note values.
+```ruby
+attributes do
+  divisions 4  # 4 divisions per quarter (allows 16th notes)
+end
+```
+
+**Alterations:**
+Use `alter:` parameter for accidentals: `-1` for flat, `1` for sharp, `2` for double sharp, etc.
+```ruby
+pitch 'F', octave: 4, alter: 1  # F# (sharp)
+pitch 'B', octave: 4, alter: -1  # Bb (flat)
+```
+
+**Articulations:**
+Add slurs, dots, and other articulations via parameters.
+```ruby
+pitch 'C', octave: 4, slur: 'start'  # Begin slur
+pitch 'D', octave: 4, slur: 'stop'   # End slur
+pitch 'E', octave: 4, dots: 1        # Dotted note
+```
+
+**Dynamics:**
+Add dynamic markings using `direction` blocks with `dynamics` method. Supported: `pp`, `p`, `mp`, `mf`, `f`, `ff`, `fff`, etc.
+```ruby
+direction do
+  dynamics 'f'  # Forte
+end
+```
+
+**Wedges:**
+Add crescendo/diminuendo markings with `wedge` in direction blocks.
+```ruby
+direction do
+  wedge 'crescendo'  # Start crescendo
+end
+# ... notes ...
+direction wedge: 'stop'  # End crescendo
+```
+
+**Metronome:**
+Add tempo markings with `metronome` in measures.
+```ruby
+metronome beat_unit: 'quarter', per_minute: 120
+```
+
+**Rests:**
+Use `rest` method instead of `pitch` for rest notation.
+```ruby
+rest duration: 2, type: 'quarter'
+```
+
+## Two Usage Modes
+
+**Constructor Style (Method Calls):**
+
+Use constructor parameters and `add_*` methods for programmatic building:
+
+```ruby
+require 'musa-dsl'
+
+# Create score with metadata
+score = Musa::MusicXML::Builder::ScorePartwise.new(
+  work_title: "Piano Piece",
+  creators: { composer: "Your Name" },
+  encoding_date: DateTime.new(2024, 1, 1)
+)
+
+# Add parts using add_* methods
+part = score.add_part(:p1, name: "Piano", abbreviation: "Pno.")
+
+# Add measures and attributes
+measure = part.add_measure(divisions: 4)
+
+# Add attributes (key, time, clef, etc.)
+measure.attributes.last.add_key(1, fifths: 0)        # C major
+measure.attributes.last.add_time(1, beats: 4, beat_type: 4)
+measure.attributes.last.add_clef(1, sign: 'G', line: 2)
+
+# Add notes
+measure.add_pitch(step: 'C', octave: 4, duration: 4, type: 'quarter')
+measure.add_pitch(step: 'E', octave: 4, duration: 4, type: 'quarter')
+measure.add_pitch(step: 'G', octave: 4, duration: 4, type: 'quarter')
+measure.add_pitch(step: 'C', octave: 5, duration: 4, type: 'quarter')
+
+# Export to file
+File.write("score.musicxml", score.to_xml.string)
+```
+
+**DSL Style (Blocks):**
+
+Use blocks with method names as setters/builders for more readable, declarative code:
+
+```ruby
+require 'musa-dsl'
+
+score = Musa::MusicXML::Builder::ScorePartwise.new do
+  work_title "Piano Piece"
+  creators composer: "Your Name"
+  encoding_date DateTime.new(2024, 1, 1)
+
+  part :p1, name: "Piano", abbreviation: "Pno." do
+    measure do
+      attributes do
+        divisions 4
+        key 1, fifths: 0        # C major
+        time 1, beats: 4, beat_type: 4
+        clef 1, sign: 'G', line: 2
+      end
+
+      pitch 'C', octave: 4, duration: 4, type: 'quarter'
+      pitch 'E', octave: 4, duration: 4, type: 'quarter'
+      pitch 'G', octave: 4, duration: 4, type: 'quarter'
+      pitch 'C', octave: 5, duration: 4, type: 'quarter'
+    end
+  end
+end
+
+File.write("score.musicxml", score.to_xml.string)
+```
+
+**Sophisticated Example - Piano Score with Multiple Features:**
+
+```ruby
+require 'musa-dsl'
+
+score = Musa::MusicXML::Builder::ScorePartwise.new do
+  work_title "Étude in D Major"
+  work_number 1
+  creators composer: "Example Composer"
+  encoding_date DateTime.now
+
+  part :p1, name: "Piano" do
+    # Measure 1 - Setup and opening with two staves
+    measure do
+      attributes do
+        divisions 2  # 2 divisions per quarter note
+
+        # Treble clef (staff 1)
+        key 1, fifths: 2        # D major (2 sharps)
+        clef 1, sign: 'G', line: 2
+        time 1, beats: 4, beat_type: 4
+
+        # Bass clef (staff 2)
+        key 2, fifths: 2
+        clef 2, sign: 'F', line: 4
+        time 2, beats: 4, beat_type: 4
+      end
+
+      # Tempo marking
+      metronome beat_unit: 'quarter', per_minute: 120
+
+      # Right hand melody (staff 1)
+      pitch 'D', octave: 4, duration: 4, type: 'half', slur: 'start'
+      pitch 'E', octave: 4, duration: 4, type: 'half', slur: 'stop'
+
+      # Return to beginning for left hand (staff 2)
+      backup 8
+
+      # Left hand accompaniment (staff 2)
+      pitch 'D', octave: 3, duration: 8, type: 'whole', staff: 2
+    end
+
+    # Measure 2 - Two voices in treble clef
+    measure do
+      # Voice 1
+      pitch 'F#', octave: 4, duration: 2, type: 'quarter', alter: 1, voice: 1
+      pitch 'G', octave: 4, duration: 2, type: 'quarter', voice: 1
+      pitch 'A', octave: 4, duration: 2, type: 'quarter', voice: 1
+      pitch 'B', octave: 4, duration: 2, type: 'quarter', voice: 1
+
+      # Return to beginning for voice 2
+      backup 8
+
+      # Voice 2 (inner voice)
+      pitch 'A', octave: 3, duration: 3, type: 'quarter', dots: 1, voice: 2
+      pitch 'B', octave: 3, duration: 1, type: 'eighth', voice: 2
+      pitch 'C#', octave: 4, duration: 3, type: 'quarter', dots: 1, alter: 1, voice: 2
+      pitch 'D', octave: 4, duration: 1, type: 'eighth', voice: 2
+
+      # Return for left hand
+      backup 8
+
+      # Left hand (staff 2)
+      pitch 'A', octave: 2, duration: 8, type: 'whole', staff: 2
+    end
+
+    # Measure 3 - Dynamics and articulations
+    measure do
+      # Dynamic marking
+      direction do
+        dynamics 'pp'
+        wedge 'crescendo'
+      end
+
+      # Notes with crescendo
+      pitch 'C#', octave: 5, duration: 1, type: 'eighth', alter: 1
+      pitch 'D', octave: 5, duration: 1, type: 'eighth'
+      pitch 'E', octave: 5, duration: 1, type: 'eighth'
+      pitch 'F#', octave: 5, duration: 1, type: 'eighth', alter: 1
+
+      pitch 'G', octave: 5, duration: 1, type: 'eighth'
+      pitch 'A', octave: 5, duration: 1, type: 'eighth'
+      pitch 'B', octave: 5, duration: 1, type: 'eighth'
+      pitch 'C#', octave: 6, duration: 1, type: 'eighth', alter: 1
+
+      # End of crescendo, forte
+      direction wedge: 'stop', dynamics: 'f'
+    end
+  end
+end
+
+# Export to file
+File.write("etude.musicxml", score.to_xml.string)
+
+# Or write directly to IO
+File.open("etude.musicxml", 'w') { |f| score.to_xml(f) }
+```
+
+## API Reference
+
+**Complete API documentation:**
+- [Musa::MusicXML::Builder](https://rubydoc.info/gems/musa-dsl/Musa/MusicXML/Builder) - MusicXML score generation
+
+**Source code:** `lib/musicxml/builder/`
+
+

data/docs/subsystems/neumas.md

@@ -0,0 +1,71 @@
+# Neumas & Neumalang - Musical Notation
+
+Neumas provide a compact text-based notation system for musical composition. Neumalang is the parser that converts this notation to structured musical data.
+
+```ruby
+require 'musa-dsl'
+require 'midi-communications'
+
+# To play the song, decode neumas to GDV and convert to PDV
+include Musa::All
+
+using Musa::Extension::Neumas
+
+# Neuma notation requires parentheses around each neuma element
+# Parsed using Musa::Neumalang::Neumalang.parse()
+
+# Complete example with durations and dynamics (parallel voices using |)
+song = "(0 1 mf) (+2 1 mp) (+4 2 p) (+5 1/2 mf) (+7 1 f)" |      # Voice 1: melody with varied dynamics
+       "(+7 2 p) (+5 1 mp) (+7 1 mf) (+9 1/2 f) (+12 2 ff)"      # Voice 2: harmony with crescendo
+
+# Wrap parallel structure in serie
+song_serie = S(song)
+
+# Create decoder with a scale
+scale = Scales.et12[440.0].major[60]
+decoder = Decoders::NeumaDecoder.new(scale, base_duration: 1r)
+
+# Setup sequencer with clock and transport
+output = MIDICommunications::Output.gets
+
+clock = TimerClock.new(bpm: 120, ticks_per_beat: 24)
+transport = Transport.new(clock, 4, 24)
+
+voices = MIDIVoices.new(sequencer: transport.sequencer, output: output, channels: [0, 1])
+
+# Play both voices simultaneously - sequencer handles parallel structure automatically
+transport.sequencer.with do
+  at 1 do
+    play song_serie, decoder: decoder, mode: :neumalang do |gdv|
+      # Convert GDV to PDV for MIDI output
+      pdv = gdv.to_pdv(scale)
+
+      # Use voice based on channel assignment (sequencer maintains voice separation)
+      voice_index = gdv[:channel] || 0
+      voices.voices[voice_index].note pitch: pdv[:pitch],
+                                      velocity: pdv[:velocity],
+                                      duration: pdv[:duration]
+    end
+  end
+end
+
+transport.start
+```
+
+**Notation syntax:**
+- `(0)`, `(+2)`, `(-1)` - Absolute/relative pitch steps (in parentheses)
+- `o0`, `o1`, `o-1` - Octave specification
+- `1`, `2`, `1/2`, `1/4` - Duration (whole, double, half, quarter)
+- `ppp`, `pp`, `p`, `mp`, `mf`, `f`, `ff`, `fff` - Dynamics (velocity)
+- `+f`, `+ff`, `-p`, `-pp` - Relative dynamics (louder/softer)
+- `|` operator - Parallel voices (polyphonic structure)
+
+## API Reference
+
+**Complete API documentation:**
+- [Musa::Neumas](https://rubydoc.info/gems/musa-dsl/Musa/Neumas) - Musical notation data structures
+- [Musa::Neumalang](https://rubydoc.info/gems/musa-dsl/Musa/Neumalang) - Notation parser and interpreter
+
+**Source code:** `lib/neumas/` and `lib/neumalang/`
+
+

data/docs/subsystems/repl.md

@@ -0,0 +1,135 @@
+# REPL - Live Coding Infrastructure
+
+The REPL (Read-Eval-Print Loop) provides a TCP-based server for live coding, enabling real-time code evaluation and interactive composition. It acts as a bridge between code editors (via MusaLCE clients) and the running Musa DSL environment.
+
+**Architecture:**
+```
+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
+
+## Communication Protocol
+
+The REPL uses a line-based protocol over TCP (default port: 1327).
+
+**Client to Server:**
+- `#path` - Start path block (optional, to inject file path context)
+- *file path* - Path to the user's file being edited
+- `#begin` - Start code block
+- *code lines* - Ruby code to execute
+- `#end` - Execute accumulated code block
+
+**Server to Client:**
+- `//echo` - Start echo block (code about to be executed)
+- `//error` - Start error block
+- `//backtrace` - Start backtrace section within error block
+- `//end` - End current block
+- *regular lines* - Output from code execution (puts, etc.)
+
+**Example Session:**
+```
+Client → Server:
+  #path
+  /Users/me/composition.rb
+  #begin
+  puts "Starting composition..."
+  at 1 do
+    note pitch: 60, duration: 1r
+  end
+  #end
+
+Server → Client:
+  //echo
+  puts "Starting composition..."
+  at 1 do
+    note pitch: 60, duration: 1r
+  end
+  //end
+  Starting composition...
+```
+
+## Server Setup
+
+**Basic REPL Server:**
+
+```ruby
+require 'musa-dsl'
+include Musa::All
+
+# Create sequencer and 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
+transport.sequencer.with do
+  # DSL methods available in REPL
+  def note(pitch:, duration:)
+    puts "Playing pitch #{pitch} for #{duration} bars"
+  end
+
+  # Create REPL server (port 1327 by default)
+  @repl = Musa::REPL::REPL.new(binding)
+end
+
+# Start playback (REPL runs in background thread)
+transport.start
+```
+
+**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:
+
+```ruby
+# In REPL context, clients can use:
+require_relative @user_pathname.dirname / 'my_helpers'
+```
+
+## Integration with Sequencer
+
+The REPL automatically hooks into sequencer error handling to report async errors during playback:
+
+```ruby
+require 'musa-dsl'
+include Musa::All
+
+clock = TimerClock.new(bpm: 120, ticks_per_beat: 24)
+transport = Transport.new(clock, 4, 24)
+
+transport.sequencer.with do
+  # If an error occurs during sequencer execution,
+  # REPL clients receive formatted error messages
+
+  at 1 do
+    raise "This error will be sent to REPL client"
+  end
+
+  @repl = Musa::REPL::REPL.new(binding)
+end
+
+transport.start
+```
+
+## Use Cases
+
+- **Live coding performances**: Real-time code evaluation during performances
+- **Interactive composition**: Develop compositions interactively with immediate feedback
+- **DAW synchronization**: Control Musa DSL from within Bitwig or Ableton Live
+- **Remote composition control**: Send commands to running compositions over network
+- **Educational workshops**: Live demonstrations with instant code execution
+
+## API Reference
+
+**Complete API documentation:**
+- [Musa::REPL](https://rubydoc.info/gems/musa-dsl/Musa/REPL) - Live coding server and protocol
+
+**Source code:** `lib/repl/`
+
+

data/docs/subsystems/sequencer.md

@@ -0,0 +1,98 @@
+# Sequencer - Temporal Engine
+
+The Sequencer manages time-based event scheduling with microsecond precision, supporting complex polyrhythmic and polytemporal structures.
+
+```ruby
+require 'musa-dsl'
+include Musa::All
+
+# Setup: Create clock and transport (for real-time execution)
+clock = TimerClock.new(bpm: 120, ticks_per_beat: 24)
+transport = Transport.new(clock, 4, 24)  # 4 beats per bar, 24 ticks per beat
+
+# Define series outside DSL block (Series constructors not available in DSL context)
+melody = S({ note: 60, duration: 1/2r }, { note: 62, duration: 1/2r },
+            { note: 64, duration: 1/2r }, { note: 65, duration: 1/2r },
+            { note: 67, duration: 1/2r }, { note: 65, duration: 1/2r },
+            { note: 64, duration: 1/2r }, { note: 62, duration: 1/2r })
+
+# Program sequencer using DSL
+transport.sequencer.with do
+  # Custom event handlers (on/launch)
+  on :section_change do |name|
+    puts "Section: #{name}"
+  end
+
+  # Immediate event (now)
+  now do
+    launch :section_change, "Start"
+  end
+
+  # Absolute positioning (at): event at bar 1
+  at 1 do
+    puts "Bar 1: position #{position}"
+  end
+
+  # Relative positioning (wait): event 2 bars later
+  wait 2 do
+    puts "Bar 3: position #{position}"
+  end
+
+  # Play series (play): reproduces series with automatic timing
+  at 5 do
+    play melody do |note:, duration:, control:|
+      puts "Playing note: #{note}, duration: #{duration}"
+    end
+  end
+
+  # Recurring event (every) with stop control
+  beat_loop = nil
+  at 10 do
+    # Store control object to stop it later
+    beat_loop = every 2, duration: 10 do
+      puts "Beat at position #{position}"
+    end
+  end
+
+  # Stop the beat loop at bar 18
+  at 18 do
+    beat_loop.stop if beat_loop
+    puts "Beat loop stopped"
+  end
+
+  # Animated value (move) from 0 to 10 over 4 bars
+  at 20 do
+    move from: 0, to: 10, duration: 4, every: 1/2r do |value|
+      puts "Value: #{value.round(2)}"
+    end
+  end
+
+  # Multi-parameter animation (move with hash)
+  at 25 do
+    move from: { pitch: 60, vel: 60 },
+         to: { pitch: 72, vel: 100 },
+         duration: 2,
+         every: 1/4r do |values|
+      puts "Pitch: #{values[:pitch].round}, Velocity: #{values[:vel].round}"
+    end
+  end
+
+  # Final event
+  at 30 do
+    launch :section_change, "End"
+    puts "Finished at position #{position}"
+  end
+end
+
+# Start real-time playback
+transport.start
+```
+
+## API Reference
+
+**Complete API documentation:**
+- [Musa::Sequencer](https://rubydoc.info/gems/musa-dsl/Musa/Sequencer) - Main sequencer class and DSL
+
+**Source code:** `lib/sequencer/`
+
+