# tunes
A standalone Rust library for music composition, synthesis, and audio generation with real-time, concurrent playback and control.
Build complex musical pieces with an intuitive, expressive API — no runtime dependencies required.
Perfect for algorithmic music, game audio, generative art, and interactive installations.
> **Performance:** CPU synthesis measured at 90x realtime (uncached) and 18.6x realtime (cached complex compositions) on modern hardware. SIMD sample playback: **11-17x realtime with true concurrent playback (all samples playing simultaneously)** - can handle 550-1,100+ concurrent samples in real-world scenarios. SIMD effects: 98.8x realtime with all effects stacked. Optional GPU acceleration available via `gpu` feature - provides minimal benefit on integrated GPUs (~1.1x) but scales with discrete GPU hardware.
## Features
- **Music Theory**: Scales, chords, patterns, progressions, and transposition
- **Composition DSL**: Fluent API for building musical sequences
- **Sections & Arrangements**: Create reusable sections (verse, chorus, bridge) and arrange them
- **Synthesis**: FM synthesis, Granular synthesis, Karplus Strong, additive synthesis, filter envelopes, wavetable oscillators
- **Instruments**: 150+ Pre-configured synthesizers, bass, pads, leads, guitars, percussion, brass, strings, woodwinds and more
- **Rhythm & Drums**: 100+ pre-configured drum sounds, drum grids, euclidean rhythms, 808-style synthesis, and pattern sequencing
- **Effects, Automation and Filters**: Delay, convolution reverb, distortion, parametric EQ, chorus, modulation, tremolo, autopan, gate, limiter, compressor (with multiband support), bitcrusher, eq, phaser, flanger, saturation, sidechaining/ducking, various filters
- **Musical Patterns**: Arpeggios, ornaments, tuplets, and many classical techniques and patterns built-in
- **Algorithmic Sequences**: 50+ algorithms, including Primes, Fib, 2^x, Markov, L-map, Collatz, Euclidean, Golden ratio, random/bounded walks, Thue-Morse, Recamán's, Van der Corput, L-System, Cantor, Shepherd, Cellular Automaton, and many more
- **Tempo & Timing**: Tempo changes, time signatures (3/4, 5/4, 7/8, etc.), key signatures with modal support
- **Key Signatures & Modes**: Major, minor, and all 7 Greek modes (Dorian, Phrygian, Lydian, etc.)
- **Real-time Playback**: Cross-platform audio output with concurrent mixing, live volume/pan control
- **Live Audio Recording**: Record from microphone or line-in to WAV files, then process with full effects pipeline
- **Sample Playback**: Load and play audio files (MP3, OGG, FLAC, WAV, AAC) with pitch shifting, time dilation and slicing, powered by SIMD with auto caching for efficient sample playback
- **GPU Acceleration** (optional `gpu` feature): GPU compute shader acceleration via wgpu for synthesis and export. Transparent API integration - enable with `AudioEngine::new_with_gpu()`. Performance scales with GPU hardware; integrated GPUs show minimal improvement while discrete GPUs can provide significant acceleration
- **WebAssembly Support** (optional `web` feature): Full browser support via WebAssembly - synthesis, effects, sample playback, and real-time audio in web applications. Powered by Web Audio API through cpal's wasm-bindgen integration
- **Streaming Audio**: Memory-efficient streaming for long background music and ambience without loading entire files into RAM (native-only)
- **Spatial Audio**: 3D sound positioning with distance attenuation, azimuth panning, doppler effect, and listener orientation for immersive game audio
- **Audio Export**: WAV (uncompressed), FLAC (lossless ~50-60% compression), STEM export
- **MIDI Import/Export**: Import Standard MIDI Files and export compositions to MIDI with proper metadata
- **Live Coding**: Hot-reload system - edit code and hear changes instantly
* The library includes **1117 comprehensive tests and 444 doc tests** ensuring reliability and correctness.
## Who this is and isn't for:
For:
learners
tinkerers
algorithmic/generative/procedural music
experimental musicians
game jammers and indie devs,
rust coders looking to play with Digital Signal Processing without having to re-implement everything from scratch
Not for:
professional producers
DAW dwellers
DSP engineers
live-repl-first musicians
## PROS
rust
music theory integration
batteries included approach
composition and code first environment (rust's ide integration and your choice of ide is everything here)
high CPU performance (90x realtime synthesis uncached, 18.6x cached on complex compositions)
automatic SIMD acceleration for concurrent sample playback (11-17x realtime, 550-1,100+ concurrent samples)
automatic SIMD acceleration for effects (98.8x realtime with all effects stacked)
multi-core parallelism (automatic via Rayon)
optional GPU compute shader acceleration with transparent API
## CONS
no gui or graphical elements
no "instant feedback" outside of hot-reloading segments
no external control or input (no midi in, osc or network controls) or hardware control
no plugin system
rust (not as beginner friendly as something like sonic pi)
## Installation
Add this to your `Cargo.toml`:
```toml
[dependencies]
tunes = "0.20.0"
# Optional: Enable GPU acceleration (requires discrete GPU for best results)
# tunes = { version = "0.20.0", features = ["gpu"] }
# Optional: Enable WebAssembly support for browser-based applications
# tunes = { version = "0.20.0", features = ["web"] }
```
### Platform Requirements
**Linux users** need ALSA development libraries:
```bash
# Debian/Ubuntu
sudo apt install libasound2-dev
# Fedora/RHEL
sudo dnf install alsa-lib-devel
```
**macOS and Windows** work out of the box with no additional dependencies.
**WebAssembly** requires wasm-pack for building:
```bash
cargo install wasm-pack
wasm-pack build --target web --features web
```
See [WEB_DEMO.md](WEB_DEMO.md) for complete WebAssembly setup and usage guide.
## Quick Start: Super simple!!
### Real-time Playback
```rust
use tunes::prelude::*;
fn main() -> Result<(), anyhow::Error> {
let engine = AudioEngine::new()?;
let mut comp = Composition::new(Tempo::new(120.0));
let eighth = comp.tempo().eighth_note(); //getting this value to use in the next example
// This is where you can do everything.
// Notes and chords can be input as floats with frequencies in hz or using or by prelude constants
// Durations can be input as a duration of seconds as a float or using durations inferred by tempo
comp.instrument("piano", &Instrument::electric_piano())
.note(&[C4], 0.5) //plays a c4 for half a second
.note(&[280.0], eighth); //plays 280.0 hz note for half a second
//continue chaining methods after the second note if you want.
engine.play_mixer(&comp.into_mixer())?;
Ok(())
}
```
### Export to WAV
```rust
use tunes::prelude::*;
fn main() -> Result<(), anyhow::Error> {
let mut comp = Composition::new(Tempo::new(120.0));
// Create a melody with instruments and effects
comp.instrument("lead", &Instrument::synth_lead())
.filter(Filter::low_pass(1200.0, 0.6))
.notes(&[C4, E4, G4, C5], 0.5);
// Export to WAV file
let mut mixer = comp.into_mixer();
mixer.export_wav("my_song.wav", 44100)?;
Ok(())
}
```
### Export to FLAC (Lossless Compression)
```rust
use tunes::prelude::*;
fn main() -> Result<(), anyhow::Error> {
let mut comp = Composition::new(Tempo::new(120.0));
comp.instrument("piano", &Instrument::electric_piano())
.notes(&[C4, E4, G4, C5], 0.5);
// Export to FLAC (50-60% smaller than WAV, lossless quality)
let mut mixer = comp.into_mixer();
mixer.export_flac("my_song.flac", 44100)?;
Ok(())
}
```
### Sample Playback (Game Audio - Simple!)
```rust
use tunes::prelude::*;
fn main() -> Result<(), anyhow::Error> {
let engine = AudioEngine::new()?;
// That's it! Play samples with automatic caching and SIMD acceleration
engine.play_sample("explosion.wav")?; // Loads once, caches, plays with SIMD
engine.play_sample("footstep.wav")?; // Loads once, caches
engine.play_sample("footstep.wav")?; // Instant! Uses cache, SIMD playback
engine.play_sample("jump.wav")?;
// All samples play concurrently with automatic mixing
Ok(())
}
```
**With GPU Acceleration (requires `gpu` feature):**
```rust
use tunes::prelude::*;
fn main() -> Result<(), anyhow::Error> {
// Transparent GPU acceleration - enable at engine creation
let engine = AudioEngine::new_with_gpu()?;
// All operations automatically GPU-accelerated when possible
let mut comp = Composition::new(Tempo::new(120.0));
comp.track("synth").sine(440.0, 1.0);
// Export uses GPU acceleration
engine.export_wav(&mut comp.into_mixer(), "output.wav")?;
// Playback uses GPU acceleration
engine.play_sample("output.wav")?;
Ok(())
}
```
**Advanced: Sample Playback in Compositions**
For precise timing and mixing with synthesis:
```rust
use tunes::prelude::*;
fn main() -> Result<(), anyhow::Error> {
let mut comp = Composition::new(Tempo::new(120.0));
// Load samples into composition
comp.load_sample("kick", "samples/kick.wav")?;
comp.load_sample("snare", "samples/snare.wav")?;
// Use samples with precise timing
comp.track("drums")
.sample("kick") // Play at normal speed
.sample("snare")
.sample_with_rate("kick", 1.5); // 1.5x speed (pitch up)
// Mix samples with synthesis
comp.instrument("bass", &Instrument::sub_bass())
.notes(&[C2, C2, G2, G2], 0.5);
let mixer = comp.into_mixer();
let engine = AudioEngine::new()?;
engine.play_mixer(&mixer)?;
Ok(())
}
```
### MIDI Import/Export
```rust
use tunes::prelude::*;
fn main() -> Result<(), anyhow::Error> {
// Export: Create and export a composition to MIDI
let mut comp = Composition::new(Tempo::new(120.0));
comp.instrument("melody", &Instrument::synth_lead())
.notes(&[C4, E4, G4, C5], 0.5);
comp.track("drums")
.drum_grid(16, 0.125)
.kick(&[0, 4, 8, 12])
.snare(&[4, 12]);
let mixer = comp.into_mixer();
mixer.export_midi("song.mid")?;
// Import: Load a MIDI file and render to audio
let mut imported = Mixer::import_midi("song.mid")?;
imported.export_wav("output.wav", 44100)?;
// Or play it directly
let engine = AudioEngine::new()?;
engine.play_mixer(&imported)?;
Ok(())
}
```
### Live Coding (Hot Reload)
```bash
# 1. Copy the template
cp templates/live_template.rs my_live.rs
# 2. Start live coding mode
cargo run --bin tunes-live -- my_live.rs
# 3. Edit my_live.rs and save - hear changes instantly!
```
The live coding system watches your file and automatically:
- ✅ Recompiles when you save
- ✅ Stops the old version
- ✅ Starts playing the new version
- ✅ Shows compilation errors in real-time
Perfect for iterative composition, live performances, and experimentation!
```rust
// my_live.rs - edit and save to hear changes!
use tunes::prelude::*;
fn main() -> anyhow::Result<()> {
let mut comp = Composition::new(Tempo::new(140.0));
comp.track("drums")
.drum_grid(16, 0.125)
.kick(&[0, 4, 8, 12]);
// Try changing notes here and saving!
comp.instrument("lead", &Instrument::synth_lead())
.notes(&[C4, E4, G4], 0.25);
let mixer = comp.into_mixer();
// 4096 samples = ~93ms latency - good balance for live coding
let engine = AudioEngine::with_buffer_size(4096)?;
// Start looping playback
let loop_id = engine.play_looping(&mixer)?;
// Keep program running (live reload will restart)
loop {
std::thread::sleep(std::time::Duration::from_millis(100));
}
}
```
**Important:**
- Use `play_looping()` for seamless loops without gaps
- Buffer size 4096 works well for most systems (increase to 8192 or 16384 if you hear glitches)
- The live reload system will automatically stop and restart with your changes
## Comparison with Other Music Programming Libraries
`tunes` occupies a unique position in the music programming landscape:
| Feature | SuperCollider | Sonic Pi | Leipzig | Strudel | **tunes** | Music21 |
|--------------------------|---------------|-----------------|-----------------|-------------------|--------------------|---------|
| **Type safety** | No | No | No (Clojure) | Partial (TS) | **Yes (Rust)** | No |
| **Real-time audio** | Yes | Yes | Yes (Overtone) | Yes (Web Audio) | **Yes** | No |
| **Sample playback** | Yes | Yes | Yes (Overtone) | Yes | **Yes** | No |
| **WebAssembly support** | No | No | No | Yes (JS native) | **Yes (Rust)** | No |
| **GPU acceleration** | No | No | No | No | **Yes (wgpu)** | No |
| **SIMD acceleration** | Some | No | Via Overtone | No | **Yes (11-17x)** | No |
| **WAV export** | Yes (manual) | No | Via Overtone | No (browser) | **Yes (easy)** | Yes |
| **FLAC export** | Yes (manual) | No | No | No | **Yes (easy)** | No |
| **MIDI import** | Yes | No | No | No | **Yes** | Yes |
| **MIDI export** | Yes | No | No | No | **Yes** | Yes |
| **Live coding** | Yes | Yes | Partial | Yes | **Yes** | No |
| **Easy to learn** | No | Yes | Medium | Yes | **Yes** | Yes |
| **No dependencies** | No (needs SC) | No (needs Ruby) | No (Clojure+SC) | No (browser/Node) | **Yes** | No |
| **Algorithmic patterns** | Yes | Yes | Yes | Yes | **Yes** | Yes |
| **Music theory** | Manual | Manual | Yes | Some | **Yes (built-in)** | Yes |
| **Standalone binary** | No | No | No | No | **Yes** | No |
| **Embeddable** | No | No | No | No | **Yes** | No |
### When to use `tunes`
**tunes excels at:**
- Building Rust applications with music generation (games, art installations, tools)
- Browser-based music applications and interactive web demos
- Algorithmic composition with type-safe APIs
- Offline music generation and batch processing
- Learning music programming without complex setup
- Prototyping musical ideas with immediate feedback
**Use alternatives if you need:**
- **SuperCollider**: Extreme synthesis flexibility and live coding ecosystem
- **Sonic Pi**: Classroom-ready live coding with visual feedback
- **Leipzig**: Functional composition with Clojure's elegance
- **Strudel**: Browser-based collaboration and live coding
- **Music21**: Academic music analysis and score manipulation
### tunes' unique position
`tunes` is the only **standalone, embeddable, type-safe** music library with synthesis + sample playback that works on both **native and WebAssembly**. It compiles to a single binary with no runtime dependencies, making it ideal for:
- Rust game developers (Bevy, ggez, etc.)
- Browser-based music applications and web audio tools
- Desktop music applications
- Command-line music tools
- Embedded audio systems
## Documentation
Run `cargo doc --open` to view the full API documentation with detailed examples for each module.
## Testing
```bash
cargo test
```
## Examples
Run the included **99 examples** to hear the library in action:
```bash
# Sample playback (WAV file loading and playback)
cargo run --release --example sample_playback_demo
# Export to WAV file
cargo run --release --example wav_export_demo
# Synthesis showcase (FM, filters, envelopes)
cargo run --release --example synthesis_demo
# Theory and scales
cargo run --example theory_demo
# Effects and effect automation (dynamic parameter changes over time)
cargo run --example effects_showcase
cargo run --example automation_demo
# And many more...
cargo run -- example example-name-here
```
**Note:** Use `--release` for examples with very complex synthesis to avoid audio underruns.
## Documentation Book
**📚 Comprehensive Guide Available!**
Tunes includes a complete book with tutorials, examples, and in-depth comparisons with other audio libraries.
**Find it at:** `book/` directory in the repository
**To read locally:**
```bash
# Install mdbook if you don't have it
cargo install mdbook
# Serve the book locally
cd book
mdbook serve --open
```
The book includes:
- 🚀 **Getting Started** - From first sound to algorithmic music
- 🎵 **Core Concepts** - Architecture, engine, mixer, composition layers
- 🎮 **Game Audio Patterns** - Samples, concurrent SFX, dynamic music, spatial audio
- 🎹 **Synthesis & Effects** - FM synthesis, granular, effects chains
- 🔬 **Advanced Topics** - Generators, transformations, MIDI, optimization
- ⚖️ **Comparisons** - Clinical, honest comparisons with Kira, Rodio, SoLoud, TidalCycles, Sonic Pi, and more
**Not sure if Tunes is right for you?** Check the [Comparisons](book/src/comparisons.md) page for honest, technical comparisons with other libraries.
---
## Performance & Benchmarks
Tunes is designed for exceptional performance with automatic optimizations:
### Measured Performance (i5-6500 @ 3.2GHz, Intel HD 530)
**CPU Performance (SIMD + Rayon):**
- Uncached synthesis: 90.0x realtime (192 FM notes)
- Cached complex composition: 18.6x realtime
- SIMD concurrent sample playback: 11-17x realtime (25-100 samples playing simultaneously)
- Conservative concurrent capacity: **550-1,100+ samples** in real-world scenarios
- SIMD effects (all stacked): 98.8x realtime
- WAV export: 12.2x realtime (124-second multi-track composition)
**GPU Performance (Intel HD 530 integrated):**
- Speedup: ~1.1x vs CPU (marginal improvement on integrated graphics)
- WAV export: 12.2x realtime (marginal improvement vs CPU baseline)
- Note: Integrated GPUs show minimal benefit - CPU performance already excellent
**Hardware Scaling:**
- Integrated GPUs show 1.0-1.2x speedup (marginal improvement)
- Discrete GPUs: Performance scales with compute capacity and memory bandwidth
- Note: Integrated GPU matches full CPU performance while using a fraction of system resources
### What This Means
**For a 16-bar drum pattern (192 notes, 13.6 seconds of audio):**
- CPU renders in: **0.15 seconds** (90x realtime)
**For game audio with true concurrent samples:**
- SIMD handles 50-100 samples playing **simultaneously** at **11-17x realtime**
- Conservative estimate: **550-1,100+ concurrent samples** in real-world scenarios
- This is **10-20x more than other libraries** claiming "50 or dozens" of concurrent samples!
- Automatic caching and multi-core parallelism optimize performance
**For effects processing:**
- All SIMD effects stacked: **98.8x realtime** (incredibly fast)
### Automatic Optimizations
Tunes automatically applies:
- ✅ **SIMD vectorization** (AVX2/SSE/NEON) - 11-17x realtime concurrent sample playback, 98.8x effects
- ✅ **Multi-core parallelism** (Rayon) - automatic scaling across CPU cores
- ✅ **Block processing** (512-sample chunks) - reduces overhead
- ✅ **Integer-based routing** (Vec-indexed, not HashMap)
- ✅ **Sample caching** (LRU eviction, Arc-based sharing)
### Optional GPU Acceleration
Enable with the `gpu` feature flag in Cargo.toml:
```toml
tunes = { version = "0.20.0", features = ["gpu"] }
```
**Transparent API (recommended):**
```rust
// Automatic GPU acceleration for all operations
let engine = AudioEngine::new_with_gpu()?;
engine.export_wav(&mut comp.into_mixer(), "output.wav")?; // GPU accelerated
engine.play_mixer_realtime(&mixer)?; // GPU accelerated
```
**Manual control:**
```rust
let mut mixer = comp.into_mixer();
mixer.enable_gpu(); // Explicit GPU enablement
```
**Performance characteristics:**
- Integrated GPUs: 1.0-1.2x speedup (minimal benefit)
- Discrete GPUs: Performance scales with hardware capabilities
- Fallback-safe: Automatically uses CPU if GPU unavailable
- Transparent: No API changes required beyond engine initialization
- Cross-platform: wgpu supports Vulkan, Metal, DX12, WebGPU
### Run Benchmarks Yourself
```bash
# GPU vs CPU comparison with transparent API
cargo bench --bench gpu_benchmark --features gpu
# Export performance (CPU and GPU)
cargo bench --bench export_speed --features gpu
# Two-stage GPU pipeline demonstration
cargo bench --bench pipeline_benchmark --features gpu
# Additional benchmarks to be found in the benches/ directory!
```
### Comparison with Other Rust Audio Libraries
| Library | SIMD | Multi-core | GPU | CPU Performance |
|---------|------|------------|-----|-----------------|
| **Tunes** | ✅ | ✅ (Rayon) | ✅ (wgpu) | 90x realtime (uncached) |
| Kira | Unknown | No | No | ~10-30x (estimated) |
| Rodio | Unknown | No | No | ~10-20x (estimated) |
| SoLoud (C++) | ✅ | Yes | No | ~10-50x (estimated) |
Tunes is the only Rust audio library with GPU compute shader acceleration via wgpu.
### Why This Matters for Games
**Traditional approach:**
- Pre-record all sound variations → Large asset files
- Limited variations → Repetitive audio
**With Tunes:**
- Generate sound variations at runtime (procedural synthesis)
- Each variation unique
- Zero disk space for variations
- 90x realtime synthesis on CPU (fast enough for most games)
- Can handle **550-1,100+ concurrent samples** at realtime (10-20x more than other libraries!)
**Example: Procedural game audio**
- Synthesize unique sounds per enemy type
- Dynamic music that responds to gameplay
- Algorithmic sound effects with variations
- Result: **Unique audio without large asset files**
---
## License
MIT OR Apache-2.0
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.