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
RubyMine provides the best experience for MusaDSL development: intelligent autocomplete of methods and parameters, hover documentation, and type inference help you discover the API as you write.
Free licenses available:
- Non-commercial use — for learning, hobbies, open-source, content creation
- Students and Teachers/Researchers — with institutional email
VSCode with the Ruby LSP extension also works well, though Ruby autocomplete and hover documentation are less complete.
The fastest way to learn and compose with MusaDSL is through Nota — a plugin for Claude 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+ and a Voyage AI 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.
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.
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
- 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
Each demo is a complete, runnable project with documentation explaining the concepts demonstrated.
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-2026 Javier Sánchez Yeste, licensed under LGPL 3.0 License