musa-dsl 0.30.2 → 0.40.0

data/docs/subsystems/music.md

@@ -0,0 +1,233 @@
+# Music - Scales & Chords
+
+Comprehensive framework for working with musical scales, tuning systems, and chord structures. The system resolves two main domains:
+
+## Scales System
+
+The **Scales** module provides hierarchical access to musical scales with multiple tuning systems and scale types:
+
+**Architecture:**
+- **ScaleSystem** (`Musa::Scales::ScaleSystem`): Defines tuning systems (e.g., 12-tone equal temperament)
+- **ScaleSystemTuning** (`Musa::Scales::ScaleSystemTuning`): A scale system with specific reference frequency (e.g., A=440Hz)
+- **ScaleKind** (`Musa::Scales::ScaleKind`): Scale types (major, minor, chromatic, etc.)
+- **Scale** (`Musa::Scales::Scale`): A scale kind rooted on a specific pitch (e.g., C major)
+- **NoteInScale** (`Musa::Scales::NoteInScale`): A specific note within a scale
+
+**Registry:**
+- **Scales::Scales** (`Musa::Scales::Scales`): Central registry for accessing scale systems by ID or method name
+
+**Available scale systems:**
+- `:et12` (EquallyTempered12ToneScaleSystem): 12-tone equal temperament (default)
+
+**Available scale kinds in et12:**
+- `:major` - Major scale (Ionian mode)
+- `:minor` - Natural minor scale (Aeolian mode)
+- `:minor_harmonic` - Harmonic minor scale (raised 7th degree)
+- `:chromatic` - Chromatic scale (all 12 semitones)
+
+## Chords System
+
+The **Chords** module provides chord structures with scale context:
+
+**Architecture:**
+- **Chord** (`Musa::Chords::Chord`): Instantiated chord with root note and scale context
+- **ChordDefinition** (`Musa::Chords::ChordDefinition`): Abstract chord structure definition (quality, size, intervals)
+
+**Features:**
+- Access chord tones by name (root, third, fifth, seventh, etc.)
+- Voicing modifications (move, duplicate, octave)
+- Navigate between related chords (change quality, add extensions)
+- Extract pitches and notes
+
+**Usage examples:**
+
+```ruby
+require 'musa-dsl'
+
+include Musa::Scales
+include Musa::Chords
+
+# Access default system and tuning
+tuning = Scales.default_system.default_tuning  # A=440Hz
+
+# Create scales using available scale kinds
+c_major = tuning.major[60]           # C major (tonic pitch 60)
+d_minor = tuning.minor[62]           # D minor (natural)
+e_harmonic = tuning.minor_harmonic[64]  # E harmonic minor
+chromatic = tuning.chromatic[60]     # C chromatic
+
+# Alternative access methods
+c_major = Scales.et12[440.0].major[60]  # Explicit system and frequency
+
+# Access notes by grade (0-based) or function
+tonic = c_major[0]      # => C (grade 0)
+mediant = c_major[2]    # => E (grade 2)
+dominant = c_major[4]   # => G (grade 4)
+
+# Access by function name
+tonic = c_major.tonic         # => C
+supertonic = c_major.supertonic  # => D
+mediant = c_major.mediant     # => E
+subdominant = c_major.subdominant  # => F
+dominant = c_major.dominant   # => G
+
+# Access by Roman numeral or symbol
+c_major[:I]    # => Tonic (C)
+c_major[:V]    # => Dominant (G)
+
+# Get pitch values from notes
+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
+
+# Chromatic operations - sharp and flat
+c_sharp = c_major.tonic.sharp   # => C# (chromatic, +1 semitone)
+c_flat = c_major.tonic.flat     # => Cb (chromatic, -1 semitone)
+
+# Navigate by semitones
+fifth_up = c_major.tonic.sharp(7)  # => G (+7 semitones = perfect fifth)
+third_up = c_major.tonic.sharp(4)  # => E (+4 semitones = major third)
+
+# Frequency calculation
+frequency = c_major.tonic.frequency  # => 261.63 Hz (middle C at A=440)
+
+# Create chords from scale degrees
+i_chord = c_major.tonic.chord        # C major triad [C, E, G]
+ii_chord = c_major.supertonic.chord  # D minor triad [D, F, A]
+v_chord = c_major.dominant.chord     # G major triad [G, B, D]
+
+# Create extended chords
+i_seventh = c_major.tonic.chord :seventh  # C major 7th [C, E, G, B]
+v_ninth = c_major.dominant.chord :ninth   # G 9th chord
+
+# Access chord tones by name
+root = i_chord.root      # => C (NoteInScale)
+third = i_chord.third    # => E (NoteInScale)
+fifth = i_chord.fifth    # => G (NoteInScale)
+
+# Get chord pitches
+pitches = i_chord.pitches  # => [60, 64, 67] (C, E, G)
+notes = i_chord.notes      # Array of ChordGradeNote structs
+
+# Chord features
+i_chord.quality  # => :major
+i_chord.size     # => :triad
+
+# Navigate between chord qualities
+minor_chord = i_chord.with_quality(:minor)      # C minor [C, Eb, G]
+diminished = i_chord.with_quality(:diminished)  # C diminished [C, Eb, Gb]
+
+# Change chord extensions
+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
+
+# Duplicate tones in other octaves
+doubled = i_chord.duplicate(root: -2, third: [-1, 1])  # Root 2 down, third 1 down and 1 up
+
+# Transpose entire chord
+lower = i_chord.octave(-1)  # Move chord down one octave
+```
+
+## Defining Custom Scale Systems, Scale Kinds, and Chord Definitions
+
+The framework is extensible, allowing users to define custom tuning systems, scale types, and chord structures:
+
+**Custom Scale Systems:**
+
+Users can create custom tuning systems by subclassing `Musa::Scales::ScaleSystem` and implementing:
+- `.id` - Unique symbol identifier
+- `.notes_in_octave` - Number of notes per octave
+- `.part_of_tone_size` - Size of smallest pitch unit
+- `.intervals` - Hash mapping interval names to semitone offsets
+- `.frequency_of_pitch(pitch, root_pitch, a_frequency)` - Pitch to frequency conversion
+
+After defining, register with `Musa::Scales::Scales.register(CustomScaleSystem, default: false)`
+
+**Custom Scale Kinds:**
+
+Users can define new scale types by subclassing `Musa::Scales::ScaleKind` and implementing:
+- `.id` - Unique symbol identifier (e.g., `:dorian`, `:pentatonic`)
+- `.pitches` - Array defining scale structure with functions and pitch offsets
+- `.chromatic?` - Whether this is the chromatic scale (optional, default: false)
+- `.grades` - Number of grades per octave (optional, default: pitches.length)
+
+After defining, register with `YourScaleSystem.register(CustomScaleKind)`
+
+**Custom Chord Definitions:**
+
+Users can register new chord types using `Musa::Chords::ChordDefinition.register`:
+- `name` - Symbol identifier (e.g., `:sus4`, `:add9`)
+- `offsets:` - Hash defining semitone intervals from root (e.g., `{ root: 0, fourth: 5, fifth: 7 }`)
+- `**features` - Chord characteristics like `quality:` and `size:`
+
+**Examples of custom definitions:**
+
+```ruby
+require 'musa-dsl'
+
+include Musa::Scales
+include Musa::Chords
+
+# Example 1: Define a custom pentatonic scale kind for the 12-tone system
+class PentatonicMajorScaleKind < ScaleKind
+  class << self
+    def id
+      :pentatonic_major
+    end
+
+    def pitches
+      [{ functions: [:I, :_1, :tonic], pitch: 0 },
+       { functions: [:II, :_2], pitch: 2 },
+       { functions: [:III, :_3], pitch: 4 },
+       { functions: [:V, :_5], pitch: 7 },
+       { functions: [:VI, :_6], pitch: 9 }]
+    end
+
+    def grades
+      5  # 5 notes per octave
+    end
+  end
+end
+
+# Register the new scale kind with the 12-tone system
+Scales.et12.register(PentatonicMajorScaleKind)
+
+# Use the new scale kind
+tuning = Scales.default_system.default_tuning
+c_pentatonic = tuning[:pentatonic_major][60]  # C pentatonic major
+puts c_pentatonic[0].pitch  # => 60 (C)
+puts c_pentatonic[1].pitch  # => 62 (D)
+puts c_pentatonic[2].pitch  # => 64 (E)
+
+# Example 2: Register a custom chord definition (sus4)
+Musa::Chords::ChordDefinition.register :sus4,
+  quality: :suspended,
+  size: :triad,
+  offsets: { root: 0, fourth: 5, fifth: 7 }
+
+# Use the custom chord definition
+c_major = tuning.major[60]
+# To use custom chords, access via NoteInScale#chord with the definition name
+# or create manually using the definition
+
+# Example 3: Register a custom chord definition (add9)
+Musa::Chords::ChordDefinition.register :add9,
+  quality: :major,
+  size: :extended,
+  offsets: { root: 0, third: 4, fifth: 7, ninth: 14 }
+```
+
+## API Reference
+
+**Complete API documentation:**
+- [Musa::Scales](https://rubydoc.info/gems/musa-dsl/Musa/Scales) - Scale systems and tuning
+- [Musa::Chords](https://rubydoc.info/gems/musa-dsl/Musa/Chords) - Chord structures and navigation
+
+**Source code:** `lib/music/`
+
+

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/`
+
+