A Ruby framework and DSL for algorithmic sound and musical thinking and composition.
Musa-DSL is a programming language DSL (Domain-Specific Language) based on Ruby designed for sonic and musical composition. It emphasizes the creation of complex temporal structures independently of the audio rendering engine, providing composers and developers with powerful tools for algorithmic composition, generative music, and musical notation.
Who is it for?
- Composers exploring algorithmic composition
- Musicians interested in generative music systems
- Developers building music applications
- Researchers in computational musicology
- Live coders and interactive music performers
- Advanced Sequencer - Precise temporal control for complex polyrhythmic and polytemporal structures
- 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)
- 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
- Transcription System - Convert musical gestures to MIDI and MusicXML with ornament transcription expansion
Add to your Gemfile:
gem 'musa-dsl'Or install directly:
gem install musa-dslRequirements:
- Ruby ~> 3.4
A complete working example with multiple interacting voice lines, demonstrating sequencer DSL, timing control, and shared state.
Detailed tutorial showing the Neuma notation system for composing melodies with grade-based notation.
MusaDSL is a comprehensive ecosystem consisting of a core framework (musa-dsl) and associated projects for communication, development, and integration.
Core Framework:
- musa-dsl - Main DSL framework for algorithmic composition and musical thinking
MIDI Communication Stack:
- midi-events - Low-level MIDI event definitions and protocols
- midi-parser - MIDI file parsing and analysis
- midi-communications - Cross-platform MIDI I/O abstraction layer
- midi-communications-macos - macOS-specific MIDI native implementation
Live Coding Environment (MusaLCE):
- musalce-server - Live coding evaluation server with hot-reload capabilities
- MusaLCEClientForVSCode - Visual Studio Code extension for live coding
- MusaLCEClientForAtom - Atom editor plugin for live coding
- MusaLCEforBitwig - Bitwig Studio integration for live coding
- MusaLCEforLive - Ableton Live integration for live coding
The musa-dsl framework is organized in modular layers:
- core-ext - Ruby core extensions (refinements for enhanced syntax)
- logger - Structured logging system with severity levels
- 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)
- neumas - Text-based musical notation system
- neumalang - Parser and interpreter for neuma notation with DSL support
- 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
- 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
- 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
- repl - Interactive Read-Eval-Print Loop for live composition
Polyphonic voice management for MIDI output with automatic note tracking, and MIDI input recording with precise timestamping.
Event scheduling engine with musical time (bars/beats), precise tick-based timing, and DSL for temporal composition.
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.
📖 Complete Transport Documentation
Lazy functional sequence generators with map/filter operations, numeric generators, buffering, quantization, and timed merging.
Compact text-based musical notation system with parser for converting notation to structured musical data.
Type-safe musical event representations (GDV, PDV, PS, P, V) with conversions, validation, Score container, and advanced queries.
Convert matrix representations to point sequences for sequencer playback, treating sonic gestures as geometric objects.
Convert between representations with ornament expansion for MIDI or preservation as notation symbols for MusicXML.
Comprehensive scale and chord systems with equal temperament, custom tunings, chord navigation, and extensible definitions.
Algorithmic composition tools: Markov chains, Variatio, Rules (L-systems), GenerativeGrammar, and Darwin (genetic algorithms).
Comprehensive MusicXML score generation with hierarchical structure, multiple voices, articulations, and dynamics.
TCP-based server for live coding with MusaLCE clients (VSCode, Atom, Bitwig, Live), real-time code evaluation and error handling.
Ruby refinements and metaprogramming utilities: Arrayfy, Hashify, ExplodeRanges, DeepCopy, DynamicProxy, AttributeBuilder, Logger.
Musa-DSL Copyright (c) 2016-2025 Javier Sánchez Yeste, licensed under LGPL 3.0 License