project	type	status	beth_topics	tags
riffstack	software	active	riffstack audio music dsl	audio-synthesis live-looping stack-based yaml

🎛️ RiffStack

A Composable Audio Performance Language

Stack-based audio synthesis and live looping system with YAML-driven patch configuration.

---

🎯 What is RiffStack?

RiffStack combines the power of:

• Stack-based DSL - Concise RPN expressions for signal flow
• Live looping - KT Tunstall-style layered performance
• YAML patches - Human-readable, declarative configuration
• Extensibility - Add your own operations, instruments, effects

🚀 Quick Start

Installation

cd /path/to/riffstack
pip install -r requirements.txt
export PATH=$PATH:$(pwd)

Your First Patch

Create hello.yaml:

version: 0.1
bpm: 120
samplerate: 44100

tracks:
  - id: simple_tone
    expr: "sine 440 0.5 play"

Play it:

riffstack play hello.yaml

📖 Documentation

Getting Started

• YAML Specification - Complete YAML format reference
• Architecture Patterns - Design philosophy
• Operation Reference - Standard library (coming soon)

Vision & Roadmap

• 🎼 Harmony DSL Vision - Musical intent language (composable harmony)
• 🧮 MLIR Architecture - Multi-level compiler infrastructure
• 🗺️ Roadmap - Development phases and milestones

🎨 Examples

Simple Synthesis

# Filtered sine wave
tracks:
  - id: tone
    expr: "sine 440 0.8 lowpass 2000 0.7 play"

Instrument Definition

instruments:
  - id: pluck
    type: karplus_strong
    build:
      expr: "noise 0.002 delay feedback 0.97 lowpass 2000 env"
    params:
      decay: 0.98

tracks:
  - id: melody
    instrument: pluck
    pattern: my_riff

Live Looping

inputs:
  - id: guitar
    type: live

loopers:
  - id: main_loop
    input: guitar
    length: 4 bars
    overdub: true
    fx_chain: ["comp", "reverb"]

controls:
  - trigger: space
    action: toggle_record main_loop

🔧 CLI Commands

# Play a patch
riffstack play patch.yaml

# Validate patch syntax
riffstack validate patch.yaml

# List available operations
riffstack ops list

# Show operation details
riffstack ops show sine

# Initialize new project
riffstack init my_project

🏗️ Project Structure

my_project/
├── patches/           # Your patches
├── lib/
│   ├── ops/          # Custom operations
│   ├── instruments/  # Instrument definitions
│   └── presets/      # Named presets
└── output/           # Rendered audio

🧩 Extensibility

Custom Operation

Create ~/.riffstack/ops/my_effect.py:

from riffstack_core import audio_op

@audio_op(name="chorus", inputs=1, outputs=1,
          params={"rate": float, "depth": float})
def chorus_effect(signal, rate=2.0, depth=0.5):
    """Add chorus effect to signal."""
    # Implementation
    return processed_signal

Now use it in any patch:

expr: "input chorus 2.0 0.5 play"

📊 Current Status

MVP Complete! ✅

✅ Project structure ✅ Core registry pattern ✅ RPN stack machine ✅ Audio graph representation ✅ CLI skeleton ✅ 11 working DSP operations ✅ Real audio playback (sounddevice) ✅ WAV file export ✅ Parameter references ($param) ✅ Working example patches

RiffStack actually makes sound! Try the examples:

python3 -m riffstack_core play examples/simple_tone.yaml
python3 -m riffstack_core play examples/filtered_tone.yaml

🎓 Learning Resources

1. Tutorial - docs/TUTORIAL.md (coming soon)
2. YAML Reference - docs/RIFFSTACK_YAML_SPEC.md
3. Operation Library - riffstack ops list
4. Examples - examples/ directory

🤝 Contributing

RiffStack is in early development. Contributions welcome!

Areas needing help:

• Core audio operations (DSP implementations)
• Example patches
• Documentation
• Testing

📜 License

MIT (or your preferred license)

🙏 Acknowledgments

Architecture inspired by:

• TiaCAD - Parametric CAD system
• TIA - Task Intelligence Augmentation system

Related Projects

Kairo - Multi-domain creative computation language

While RiffStack focuses specifically on audio synthesis and live performance, Kairo is a broader language covering fields (PDEs), agents, signals, and visuals. Both projects share similar design principles around composability and declarative configuration, but serve different creative domains. If you're interested in visual simulations, generative art, or multi-domain creative work, check out Kairo!

Built with Python, NumPy, and love for modular synthesis.

---

Status: Early development - API subject to change

For questions or feedback, see PROJECT.md for development status.