musa-dsl 0.30.2 → 0.41.0

data/docs/subsystems/series.md

@@ -0,0 +1,302 @@
+# Series - Sequence Generators
+
+Series are the fundamental building blocks for generating musical sequences. They provide functional operations for transforming pitches, rhythms, dynamics, and any musical parameter.
+
+## Basic Series Operations
+
+```ruby
+require 'musa-dsl'
+include Musa::Series
+
+# S constructor: Create series from values
+melody = S(0, 2, 4, 5, 7).repeat(2)
+melody.i.to_a  # => [0, 2, 4, 5, 7, 0, 2, 4, 5, 7]
+
+# Transform with map
+transposed = S(60, 64, 67).map { |n| n + 12 }
+transposed.i.to_a  # => [72, 76, 79]
+
+# Filter with select
+evens = S(1, 2, 3, 4, 5, 6).select { |n| n.even? }
+evens.i.to_a  # => [2, 4, 6]
+```
+
+## Combining Multiple Parameters
+
+Use `.with` to combine pitches, durations, and velocities:
+
+```ruby
+# Combine pitch, duration, and velocity
+pitches = S(60, 64, 67, 72)
+durations = S(1r, 1/2r, 1/2r, 1r)
+velocities = S(96, 80, 90, 100)
+
+notes = pitches.with(dur: durations, vel: velocities) do |p, dur:, vel:|
+  { pitch: p, duration: dur, velocity: vel }
+end
+
+notes.i.to_a
+# => [{pitch: 60, duration: 1, velocity: 96},
+#     {pitch: 64, duration: 1/2, velocity: 80},
+#     {pitch: 67, duration: 1/2, velocity: 90},
+#     {pitch: 72, duration: 1, velocity: 100}]
+```
+
+**Creating PDV with `H()` and `HC()`:**
+
+When series have different lengths, use `H` (stops at shortest) or `HC` (cycles all series):
+
+```ruby
+# Create PDV from series of different sizes
+pitches = S(60, 62, 64, 65, 67)      # 5 notes
+durations = S(1r, 1/2r, 1/4r)        # 3 durations
+velocities = S(96, 80, 90, 100)      # 4 velocities
+
+# H: Stop when shortest series exhausts (3 notes - limited by durations)
+notes = H(pitch: pitches, duration: durations, velocity: velocities)
+
+notes.i.to_a
+# => [{pitch: 60, duration: 1, velocity: 96},
+#     {pitch: 62, duration: 1/2, velocity: 80},
+#     {pitch: 64, duration: 1/4, velocity: 90}]
+
+# HC: Continue cycling all series (cycles until common multiple)
+notes_cycling = HC(pitch: pitches, duration: durations, velocity: velocities)
+  .max_size(7)  # Limit output for readability
+
+notes_cycling.i.to_a
+# => [{pitch: 60, duration: 1, velocity: 96},
+#     {pitch: 62, duration: 1/2, velocity: 80},
+#     {pitch: 64, duration: 1/4, velocity: 90},
+#     {pitch: 65, duration: 1, velocity: 100},
+#     {pitch: 67, duration: 1/2, velocity: 96},
+#     {pitch: 60, duration: 1/4, velocity: 80},
+#     {pitch: 62, duration: 1, velocity: 90}]
+```
+
+## Merging Melodic Phrases
+
+Use `MERGE` to concatenate multiple series:
+
+```ruby
+# Build melody from phrases
+phrase1 = S(60, 64, 67)        # C major triad ascending
+phrase2 = S(72, 69, 65)        # Descending from octave
+phrase3 = S(60, 62, 64)        # Scale fragment
+
+melody = MERGE(phrase1, phrase2, phrase3)
+melody.i.to_a  # => [60, 64, 67, 72, 69, 65, 60, 62, 64]
+
+# Repeat merged structure
+section = MERGE(S(1, 2, 3), S(4, 5, 6)).repeat(2)
+section.i.to_a  # => [1, 2, 3, 4, 5, 6, 1, 2, 3, 4, 5, 6]
+```
+
+## Numeric Generators
+
+```ruby
+# FOR: Numeric ranges
+ascending = FOR(from: 0, to: 7, step: 1)
+ascending.i.to_a  # => [0, 1, 2, 3, 4, 5, 6, 7]
+
+descending = FOR(from: 10, to: 0, step: 2)
+descending.i.to_a  # => [10, 8, 6, 4, 2, 0]
+
+# FIBO: Fibonacci rhythmic proportions
+rhythm = FIBO().max_size(8).map { |n| Rational(n, 16) }
+rhythm.i.to_a
+# => [1/16, 1/16, 1/8, 3/16, 5/16, 1/2, 13/16, 21/16]
+
+# RND: Random melody with constraints
+melody = RND(60, 62, 64, 65, 67, 69, 71, 72)
+  .max_size(16)
+  .remove { |note, history| note == history.last }  # No consecutive repeats
+
+# HARMO: Harmonic series (overtones)
+harmonics = HARMO(error: 0.5).max_size(10)
+harmonics.i.to_a  # => [0, 12, 19, 24, 28, 31, 34, 36, 38, 40]
+```
+
+## Structural Transformations
+
+```ruby
+# Reverse: Retrograde motion
+melody = S(60, 64, 67, 72)
+retrograde = melody.reverse
+retrograde.i.to_a  # => [72, 67, 64, 60]
+
+# merge operation: Flatten serie of series
+chunks = S(1, 2, 3, 4, 5, 6).cut(2)  # Split into pairs (serie of series)
+
+# Each chunk is a serie, use .merge to flatten
+reconstructed = chunks.merge
+reconstructed.i.to_a  # => [1, 2, 3, 4, 5, 6]
+
+# Chaining operations
+result = S(60, 62, 64, 65, 67, 69, 71, 72)
+  .select { |n| n.even? }     # Keep even pitches: [60, 62, 64, 72]
+  .map { |n| n + 12 }         # Transpose up octave: [72, 74, 76, 84]
+  .reverse                     # Retrograde: [84, 76, 74, 72]
+  .repeat(2)                   # Repeat twice
+
+result.i.to_a  # => [84, 76, 74, 72, 84, 76, 74, 72]
+```
+
+**Serie Constructors:**
+- `S(...)` - Array serie
+- `E(&block)` - Serie from evaluation block
+- `H(k1: s1, k2: s2, ...)` - Hash serie from series (stops at shortest)
+- `HC(k1: s1, k2: s2, ...)` - Hash combined (cycles all series)
+- `A(s1, s2, ...)` - Array of series (stops at shortest)
+- `AC(s1, s2, ...)` - Array combined (cycles all series)
+- `FOR(from:, to:, step:)` - Numeric range generator
+- `MERGE(s1, s2, ...)` - Concatenate series sequentially
+- `RND(...)` - Random values (infinite)
+- `RND1(...)` - Random single value (exhausts after one)
+- `SIN(steps:, amplitude:, center:)` - Sinusoidal waveform
+- `FIBO()` - Fibonacci sequence
+- `HARMO(error:, extended:)` - Harmonic series (overtones)
+
+**Serie Operations:**
+- `.map(&block)` - Transform each value
+- `.select(&block)`, `.remove(&block)` - Filter values
+- `.with(*series, &block)` - Combine multiple series
+- `.hashify(*keys)` - Convert array values to hash
+- `.repeat(times)`, `.autorestart` - Repetition control
+- `.reverse` - Reverse order
+- `.randomize(random:)` - Randomize order
+- `.merge`, `.flatten` - Flatten nested series
+- `.cut(length)` - Split into chunks
+- `.max_size(n)`, `.skip(n)` - Limit/offset control
+- `.shift(n)` - Circular rotation (negative: rotate left, positive: rotate right)
+- `.after(*series)` - Concatenate series
+- `.switch(*series)`, `.multiplex(*series)` - Switch between series
+- `.lock` - Lock/freeze values
+- `.anticipate(&block)`, `.lazy(&block)` - Advanced evaluation
+
+## API Reference
+
+**Complete API documentation:**
+- [Musa::Series](https://rubydoc.info/gems/musa-dsl/Musa/Series) - Sequence generators and operations
+
+**Source code:** `lib/musa-dsl/series/`
+
+## Specialized Series Types
+
+Beyond basic operations, Series provides specialized types for advanced transformations and musical applications.
+
+**BufferSerie** - Multiple Independent Readers:
+
+Enables multiple "readers" to independently iterate over the same series source without interfering with each other. Essential for canonic structures (rounds, fugues), polyphonic playback from a single source, and multi-voice compositions.
+
+```ruby
+require 'musa-dsl'
+include Musa::Series
+
+# Create buffered melody for canon
+melody = S(60, 64, 67, 72, 76).buffered
+
+# Create independent readers (voices)
+voice1 = melody.buffer.i
+voice2 = melody.buffer.i
+voice3 = melody.buffer.i
+
+# Each voice progresses independently
+voice1.next_value  # => 60
+voice1.next_value  # => 64
+
+voice2.next_value  # => 60 (independent of voice1)
+voice3.next_value  # => 60 (independent of others)
+
+voice1.next_value  # => 67
+voice2.next_value  # => 64
+
+# Use in canon: play voice2 delayed by 2 beats, voice3 delayed by 4 beats
+# Each voice reads the same melodic material at its own pace
+```
+
+**QuantizerSerie** - Value Quantization:
+
+Quantizes continuous time-value pairs to discrete steps. Useful for converting MIDI controller data to discrete values, snapping pitch bends to semitones, or generating stepped automation curves.
+
+Two quantization modes:
+- **Raw mode**: Rounds values to nearest step with configurable boundary inclusion
+- **Predictive mode**: Predicts crossings of quantization boundaries for smooth transitions
+
+```ruby
+require 'musa-dsl'
+include Musa::Series
+
+# Example 1: Quantize continuous pitch bend to semitones
+pitch_bend = S({ time: 0r, value: 60.3 },
+               { time: 1r, value: 61.8 },
+               { time: 2r, value: 63.1 })
+
+quantized = pitch_bend.quantize(step: 1)  # Quantize to integer semitones
+
+quantized.i.to_a
+# => [{ time: 0r, value: 60, duration: 1r },
+#     { time: 1r, value: 62, duration: 1r }]
+
+# Example 2: Predictive quantization for smooth crossings
+continuous = S({ time: 0r, value: 0 }, { time: 4r, value: 10 })
+
+predicted = continuous.quantize(step: 2, predictive: true)
+
+predicted.i.to_a
+# Generates crossing points at values 0, 2, 4, 6, 8, 10
+# with precise timing for each boundary crossing
+```
+
+**TimedSerie Operations** - Time-Based Merging:
+
+Operations for series with explicit `:time` attributes. Enables multi-track MIDI sequencing, polyphonic event streams, and synchronized parameter automation.
+
+```ruby
+require 'musa-dsl'
+include Musa::Series
+
+# Create independent melodic lines with timing
+melody = S({ time: 0r, value: 60 },
+           { time: 1r, value: 64 },
+           { time: 2r, value: 67 })
+
+bass = S({ time: 0r, value: 36 },
+         { time: 2r, value: 38 },
+         { time: 4r, value: 41 })
+
+harmony = S({ time: 0r, value: 64 },
+            { time: 2r, value: 67 })
+
+# Merge by time using TIMED_UNION (hash mode)
+combined = TIMED_UNION(melody: melody, bass: bass, harmony: harmony)
+
+combined.i.to_a
+# => [{ time: 0r, value: { melody: 60, bass: 36, harmony: 64 } },
+#     { time: 1r, value: { melody: 64, bass: nil, harmony: nil } },
+#     { time: 2r, value: { melody: 67, bass: 38, harmony: 67 } },
+#     { time: 4r, value: { melody: nil, bass: 41, harmony: nil } }]
+
+# Array mode for unnamed voices
+voice1 = S({ time: 0r, value: 60 }, { time: 1r, value: 64 })
+voice2 = S({ time: 0r, value: 48 }, { time: 1r, value: 52 })
+
+merged = TIMED_UNION(voice1, voice2)
+
+merged.i.to_a
+# => [{ time: 0r, value: [60, 48] },
+#     { time: 1r, value: [64, 52] }]
+
+# Flatten timed values
+multi = S({ time: 0r, value: { soprano: 60, alto: 64 } })
+flat = multi.flatten_timed.i.next_value
+# => { soprano: { time: 0r, value: 60 },
+#      alto: { time: 0r, value: 64 } }
+
+# Compact removes nil values
+sparse = S({ time: 0r, value: [60, nil, 67] })
+compact = sparse.compact_timed.i.to_a
+# Removes entries where all values are nil
+```
+
+

data/docs/subsystems/transcription.md

@@ -0,0 +1,152 @@
+# Transcription - MIDI & MusicXML Output
+
+The Transcription system converts GDV events to MIDI (with ornament expansion) or MusicXML format (preserving ornaments as symbols).
+
+## MIDI with Ornament Expansion
+
+```ruby
+require 'musa-dsl'
+
+using Musa::Extension::Neumas
+
+# Neuma notation with ornaments: trill (.tr) and mordent (.mor)
+neumas = "(0 1 mf) (+2 1 tr) (+4 1 mor) (+5 1)"
+
+# Create scale and decoder
+scale = Musa::Scales::Scales.et12[440.0].major[60]
+decoder = Musa::Neumas::Decoders::NeumaDecoder.new(scale, base_duration: 1/4r)
+
+# Create MIDI transcriptor with ornament expansion
+transcriptor = Musa::Transcription::Transcriptor.new(
+  Musa::Transcriptors::FromGDV::ToMIDI.transcription_set(duration_factor: 1/6r),
+  base_duration: 1/4r,
+  tick_duration: 1/96r
+)
+
+# Parse and expand ornaments to PDV
+result = Musa::Neumalang::Neumalang.parse(neumas, decode_with: decoder)
+                                   .process_with { |gdv| transcriptor.transcript(gdv) }
+                                   .map { |gdv| gdv.to_pdv(scale) }
+                                   .to_a(recursive: true)
+
+# View expanded notes (ornaments rendered as note sequences)
+result.each do |pdv|
+  puts "Pitch: #{pdv[:pitch]}, Duration: #{pdv[:duration]}, Velocity: #{pdv[:velocity]}"
+end
+# => Pitch: 60, Duration: 1/4, Velocity: 80     # C4 (no ornament)
+#    Pitch: 65, Duration: 1/24, Velocity: 80   # Trill: F4 (upper neighbor)
+#    Pitch: 64, Duration: 1/24, Velocity: 80   # Trill: E4 (original)
+#    Pitch: 65, Duration: 1/24, Velocity: 80   # Trill: F4
+#    Pitch: 64, Duration: 1/24, Velocity: 80   # Trill: E4
+#    ... (trill alternation continues)
+#    Pitch: 71, Duration: 1/24, Velocity: 80   # Mordent: B4 (original)
+#    Pitch: 72, Duration: 1/24, Velocity: 80   # Mordent: C5 (neighbor)
+#    Pitch: 71, Duration: 1/6, Velocity: 80    # Mordent: B4 (return)
+#    Pitch: 79, Duration: 1/4, Velocity: 80    # G5 (no ornament)
+```
+
+**Supported ornaments:**
+- `.tr` - Trill (rapid alternation with upper note)
+- `.mor` - Mordent (quick alternation with adjacent note)
+- `.turn` - Turn (four-note figure)
+- `.st` - Staccato (shortened duration)
+
+## MusicXML with Ornament Symbols
+
+```ruby
+require 'musa-dsl'
+
+using Musa::Extension::Neumas
+
+# Same phrase as MIDI example (ornaments preserved as symbols)
+neumas = "(0 1 mf) (+2 1 tr) (+4 1 mor) (+5 1)"
+
+# Create scale and decoder
+scale = Musa::Scales::Scales.et12[440.0].major[60]
+decoder = Musa::Neumas::Decoders::NeumaDecoder.new(scale, base_duration: 1/4r)
+
+# Create MusicXML transcriptor (preserves ornaments as symbols)
+transcriptor = Musa::Transcription::Transcriptor.new(
+  Musa::Transcriptors::FromGDV::ToMusicXML.transcription_set,
+  base_duration: 1/4r,
+  tick_duration: 1/96r
+)
+
+# Parse and convert to GDV with preserved ornament markers
+serie = Musa::Neumalang::Neumalang.parse(neumas, decode_with: decoder)
+                                   .process_with { |gdv| transcriptor.transcript(gdv) }
+
+# Create Score and use sequencer to fill it
+score = Musa::Datasets::Score.new
+sequencer = Musa::Sequencer::Sequencer.new(4, 24)
+
+sequencer.at 1 do
+  play serie, decoder: decoder, mode: :neumalang do |gdv|
+    pdv = gdv.to_pdv(scale)
+    score.at(position, add: pdv)  # position is automatically tracked by sequencer
+  end
+end
+
+sequencer.run
+
+# Convert to MusicXML
+mxml = score.to_mxml(
+  4, 24,  # 4 beats per bar, 24 ticks per beat
+  bpm: 120,
+  title: 'Ornaments Example',
+  creators: { composer: 'MusaDSL' },
+  parts: { piano: { name: 'Piano', clefs: { g: 2 } } }
+)
+
+# Generated MusicXML (excerpt showing notes with ornaments):
+puts mxml.to_xml.string
+```
+
+**Generated MusicXML output (excerpt):**
+```xml
+<note>
+  <pitch>
+    <step>C</step>
+    <octave>4</octave>
+  </pitch>
+  <duration>24</duration>
+  <type>quarter</type>
+</note>
+<note>
+  <pitch>
+    <step>E</step>
+    <octave>4</octave>
+  </pitch>
+  <duration>24</duration>
+  <type>quarter</type>
+  <notations>
+    <ornaments>
+      <trill-mark />      <!-- Trill preserved as notation symbol -->
+    </ornaments>
+  </notations>
+</note>
+<note>
+  <pitch>
+    <step>B</step>
+    <octave>4</octave>
+  </pitch>
+  <duration>24</duration>
+  <type>quarter</type>
+  <notations>
+    <ornaments>
+      <inverted-mordent />   <!-- Mordent preserved as notation symbol -->
+    </ornaments>
+  </notations>
+</note>
+```
+
+**Note:** Only 4 notes (vs 11 in MIDI) - ornaments preserved as notation symbols, not expanded
+
+## API Reference
+
+**Complete API documentation:**
+- [Musa::Transcription](https://rubydoc.info/gems/musa-dsl/Musa/Transcription) - Musical event transformation and ornament expansion
+
+**Source code:** `lib/transcription/` and `lib/musicxml/`
+
+

data/docs/subsystems/transport.md

@@ -0,0 +1,177 @@
+# Transport - Timing & Clocks
+
+Comprehensive timing infrastructure connecting clock sources to the sequencer. The transport system manages musical playback lifecycle, timing synchronization, and position control.
+
+**Architecture:**
+```
+Clock --ticks--> Transport --tick()--> Sequencer --events--> Music
+```
+
+The system provides precise timing control with support for internal timers, MIDI clock synchronization, and manual control for testing and integration.
+
+## Clock - Timing Sources
+
+**Clock** is the abstract base class for timing sources. All clocks generate regular ticks that drive the sequencer forward. Multiple clock implementations are available for different use cases.
+
+### Clock Activation Models
+
+Clocks use two different activation models:
+
+**Automatic Activation** (DummyClock):
+- Begins generating ticks immediately when `transport.start` is called
+- No external activation required
+- Appropriate for testing, batch processing, simulations
+
+**External Activation** (TimerClock, InputMidiClock, ExternalTickClock):
+- Requires external signal/control to begin generating ticks
+- `transport.start` blocks waiting for activation
+- Appropriate for live coding, DAW sync, external control
+
+### Available Clock Types
+
+**DummyClock** - Simplified clock for testing (automatic activation):
+- Fast playback without real-time constraints
+- Immediately begins generating ticks
+- Useful for test suites or batch generation
+- No external dependencies
+
+**TimerClock** - Internal high-precision timer-based clock (external activation):
+- Standalone compositions with internal timing
+- Requires calling `clock.start()` from another thread
+- Configurable BPM (tempo) and ticks per beat
+- Can dynamically change tempo during playback
+- Appropriate for live coding clients
+
+**InputMidiClock** - Synchronized to external MIDI Clock messages (external activation):
+- DAW-synchronized playback
+- Waits for MIDI "Start" (0xFA) message to begin ticks
+- Automatically follows external MIDI Clock Start/Stop/Continue
+- Locked to external timing source
+
+**ExternalTickClock** - Manually triggered ticks (external activation):
+- Testing and debugging with precise control
+- Integration with external systems (game engines, etc.)
+- Call `clock.tick()` manually to generate each tick
+- Frame-by-frame control
+
+```ruby
+require 'musa-dsl'
+
+# TimerClock - Internal timer-based timing
+timer_clock = Musa::Clock::TimerClock.new(
+  bpm: 120,              # Beats per minute
+  ticks_per_beat: 24     # Resolution
+)
+
+# InputMidiClock - Synchronized to external MIDI Clock
+require 'midi-communications'
+midi_input = MIDICommunications::Input.gets  # Select MIDI input
+
+midi_clock = Musa::Clock::InputMidiClock.new(midi_input)
+
+# ExternalTickClock - Manual tick control
+external_clock = Musa::Clock::ExternalTickClock.new
+
+# DummyClock - For testing (100 ticks)
+dummy_clock = Musa::Clock::DummyClock.new(100)
+```
+
+## Transport - Playback Lifecycle Manager
+
+**Transport** connects a clock to a sequencer and manages the playback lifecycle. It provides methods for starting/stopping playback, seeking to different positions, and registering callbacks for lifecycle events.
+
+**Lifecycle phases:**
+1. **before_begin** - Run once before first start (initialization)
+2. **on_start** - Run each time transport starts
+3. **Running** - Clock generates ticks → sequencer processes events
+4. **on_change_position** - Run when position jumps/seeks
+5. **after_stop** - Run when transport stops
+
+**Key methods:**
+- `start` - Start playback (blocks while running)
+- `stop` - Stop playback
+- `change_position_to(bars: n)` - Seek to position (in bars)
+
+```ruby
+require 'musa-dsl'
+
+# Create clock
+clock = Musa::Clock::TimerClock.new(bpm: 120, ticks_per_beat: 24)
+
+# Create transport
+transport = Musa::Transport::Transport.new(
+  clock,
+  4,   # beats_per_bar (time signature numerator)
+  24   # ticks_per_beat (resolution)
+)
+
+# Access sequencer through transport
+sequencer = transport.sequencer
+
+# Schedule events
+sequencer.at 1 do
+  puts "Starting at bar 1!"
+end
+
+sequencer.at 4 do
+  puts "Reached bar 4"
+  transport.stop
+end
+
+# Register lifecycle callbacks
+transport.before_begin do
+  puts "Initializing (runs once)..."
+end
+
+transport.on_start do
+  puts "Transport started!"
+end
+
+transport.after_stop do
+  puts "Transport stopped, cleaning up..."
+end
+
+# IMPORTANT: TimerClock requires external activation
+# Start transport in background thread (it will block waiting)
+thread = Thread.new { transport.start }
+sleep 0.1  # Let transport initialize
+
+# Activate clock from external control (e.g., live coding client)
+clock.start  # NOW ticks begin generating
+
+# Wait for completion
+thread.join
+
+# Seeking example (in separate context)
+# transport.change_position_to(bars: 2)  # Jump to bar 2
+```
+
+**Complete example with MIDI Clock synchronization:**
+
+```ruby
+require 'musa-dsl'
+require 'midi-communications'
+
+# Setup MIDI-synchronized clock
+midi_input = MIDICommunications::Input.gets
+clock = Musa::Clock::InputMidiClock.new(midi_input)
+
+# Create transport
+transport = Musa::Transport::Transport.new(clock, 4, 24)
+
+# Schedule events
+transport.sequencer.at 1 do
+  puts "Synchronized start at bar 1!"
+end
+
+# Start and wait for MIDI Clock Start message
+transport.start
+```
+
+## API Reference
+
+**Complete API documentation:**
+- [Musa::Transport](https://rubydoc.info/gems/musa-dsl/Musa/Transport) - Playback lifecycle management
+- [Musa::Clock](https://rubydoc.info/gems/musa-dsl/Musa/Clock) - Timing sources and clock implementations
+
+**Source code:** `lib/transport/`

data/lib/musa-dsl/core-ext/array-explode-ranges.rb

@@ -1,6 +1,74 @@
+require_relative 'extension'
+
 module Musa
   module Extension
+    # Refinement that expands Range objects within arrays into their constituent elements.
+    #
+    # This is particularly useful in musical contexts where arrays may contain both
+    # individual values and ranges (like MIDI note ranges or channel ranges), and you
+    # need to work with the fully expanded list.
+    #
+    # ## Use Cases
+    #
+    # - Expanding MIDI channel specifications: [0, 2..4, 7] → [0, 2, 3, 4, 7]
+    # - Expanding note ranges in chord definitions
+    # - Processing mixed literal and range values in musical parameters
+    # - Any scenario where ranges need to be flattened for iteration
+    #
+    # @example Basic usage
+    #   using Musa::Extension::ExplodeRanges
+    #
+    #   [1, 3..5, 8].explode_ranges
+    #   # => [1, 3, 4, 5, 8]
+    #
+    # @example MIDI channels
+    #   using Musa::Extension::ExplodeRanges
+    #
+    #   channels = [0, 2..4, 7, 9..10]
+    #   channels.explode_ranges
+    #   # => [0, 2, 3, 4, 7, 9, 10]
+    #
+    # @example Mixed with other array methods
+    #   using Musa::Extension::ExplodeRanges
+    #
+    #   [1..3, 5, 7..9].explode_ranges.map { |n| n * 2 }
+    #   # => [2, 4, 6, 10, 14, 16, 18]
+    #
+    # @see Musa::MIDIVoices::MIDIVoices#initialize Uses this for channel expansion
+    # @note This refinement must be activated with `using Musa::Extension::ExplodeRanges`
+    #
+    # ## Methods Added
+    #
+    # ### Array
+    # - {Array#explode_ranges} - Expands all Range objects in the array into their individual elements
     module ExplodeRanges
+      # @!method explode_ranges
+      #   Expands all Range objects in the array into their individual elements.
+      #
+      #   Iterates through the array and converts any Range objects to their
+      #   constituent elements via `to_a`, leaving non-Range elements unchanged.
+      #   The result is a new flat array.
+      #
+      #   @note This method is added to Array via refinement. Requires `using Musa::Extension::ExplodeRanges`.
+      #
+      #   @return [Array] new array with all ranges expanded.
+      #
+      #   @example Empty ranges
+      #     using Musa::Extension::ExplodeRanges
+      #     [1, (5..4), 8].explode_ranges  # (5..4) is empty
+      #     # => [1, 8]
+      #
+      #   @example Exclusive ranges
+      #     using Musa::Extension::ExplodeRanges
+      #     [1, (3...6), 9].explode_ranges
+      #     # => [1, 3, 4, 5, 9]
+      #
+      #   @example Nested arrays are NOT expanded recursively
+      #     using Musa::Extension::ExplodeRanges
+      #     [1, [2..4], 5].explode_ranges
+      #     # => [1, [2..4], 5]  # Inner range NOT expanded
+      class ::Array; end
+
       refine Array do
         def explode_ranges
           array = []