Skip to content

ROADMAP.md

Latest commit

 

History

History
428 lines (317 loc) · 10.9 KB

ROADMAP.md

File metadata and controls

428 lines (317 loc) · 10.9 KB
project riffstack
type roadmap
status active
date 2025-11-23
author Scott Senften
keywords
roadmap
planning
milestones
harmony-dsl
mlir
beth_topics
riffstack-roadmap
development-plan

🗺️ RiffStack Roadmap: From MVP to Creative Compiler

Vision: A complete creative compiler stack combining harmony DSL, audio synthesis, and MLIR compilation for unprecedented musical expressiveness and performance.

Current Status: MVP Complete ✅

What Works (as of Oct 2025):

  • Stack-based RPN expression evaluation
  • 11 DSP operations (sine, lowpass, delay, chorus, etc.)
  • YAML patch configuration
  • Real audio playback (sounddevice)
  • WAV file export
  • Parameter references ($pitch)
  • CLI interface (riffstack play, validate, ops)
  • Example patches (simple_tone, filtered_tone, etc.)
  • Audio graph representation
  • Operation registry pattern

What's Next: Evolution to complete creative compiler

Strategic Direction: The Three Pillars

🎼 Pillar 1: Harmony DSL

High-level musical intent language

Enables musicians to describe harmony as movement, not labels:

verse:
  start: Cmin11.lush(smooth)
  progression:
    - +5.bright(anticipate)
    - -2.dark(spread)

See: Harmony DSL Vision

🎛️ Pillar 2: RiffStack Audio

Mid-level audio synthesis language (current MVP)

Stack-based DSP operations for expressive sound design:

instruments:
  - id: pad
    expr: "sine $pitch 0.6 chorus 2.0 0.5 reverb 0.8 play"

See: RiffStack README

🧮 Pillar 3: MLIR Compilation

Multi-level compiler infrastructure

Transforms musical intent → optimized audio running on any device:

Harmony IR → Note IR → Audio IR → DSP IR → Machine Code

See: MLIR Architecture

Development Phases

✅ Phase 0: RiffStack MVP (COMPLETE)

Timeline: Completed Oct 2025 Status: Working CLI audio synthesizer

Achievements:

  • Core audio engine operational
  • Stack-based DSL proven
  • Registry pattern established
  • Real-time playback working

🎯 Phase 1: Core Harmony DSL (Months 1-3)

Goal: Prototype harmony language with basic voice-leading

Deliverables:

  • Motion operator syntax (+1, -3, T, 5)
  • Chord quality macros (min11, maj9, 7#11, sus4)
  • Basic voice-leading solver (smooth, common constraints)
  • YAML parser for progressions
  • MIDI output (proof-of-concept playback)
  • 10+ example progressions (ii-V-I, jazz, modal)

Milestone: Can write harmonic progressions and hear MIDI output

Key Questions:

  • Constraint solver: SAT/SMT vs heuristic?
  • YAML vs custom syntax?
  • Relative vs absolute root motion?

🎯 Phase 2: Harmony + Audio Integration (Months 3-6)

Goal: Bridge harmony DSL to RiffStack synthesis

Deliverables:

  • Harmony → RiffStack parameter binding
  • Multi-track rendering (harmony generates note streams)
  • Example compositions (verse/chorus/bridge structures)
  • Voice-leading quality validation
  • Audio rendering from harmony DSL

Milestone: Full audio synthesis driven by harmony language

Architecture:

Harmony DSL → Note Events → RiffStack Patches → Audio Output

🎯 Phase 3: Advanced Harmony Features (Months 6-9)

Goal: Production-ready harmony expressiveness

Deliverables:

  • Rhythm modifiers (arp, stab, roll, sync, anticipate)
  • Generative rules (choose, randomize with weights)
  • Mood/color system (lush, bright, dark, empty, rich)
  • Multi-scale structure (phrase → section → song)
  • Reharmonization algorithms
  • Alternative tunings (microtonal, just intonation)

Milestone: Professional composition tool for harmony exploration

🎯 Phase 4: MLIR Foundation (Months 6-12)

Goal: Establish compiler infrastructure

Deliverables:

  • Define MLIR dialects:
    • theory - Harmony operations
    • note - Pitch/rhythm streams
    • audio - RiffStack operations
    • dsp - Low-level signal processing
  • Lowering passes between dialects
  • Basic optimization passes
  • LLVM backend for CPU
  • Benchmark suite

Milestone: Compiled audio engine (CPU only)

Performance Target: <5ms latency @ 48kHz

🎯 Phase 5: Multi-Backend Compilation (Months 12-18)

Goal: Cross-device performance

Deliverables:

  • GPU backend (SPIR-V/CUDA)
  • WebGPU backend (browser audio)
  • Runtime abstraction layer
  • Platform-specific optimizations
  • Performance profiling tools

Milestone: One source → runs optimized on CPU/GPU/Web

Performance Targets:

Backend Latency Concurrent Voices
CPU (AVX2) <5ms 16
GPU (CUDA) <3ms 100+
WebGPU <20ms 8-16

🎯 Phase 6: Advanced Audio Features (Months 12-18)

Goal: Production-ready synthesis capabilities

Deliverables:

  • 50+ DSP operations (comprehensive library)
  • Live looping implementation (KT Tunstall-style)
  • MIDI integration (hardware controller support)
  • Pattern sequencing
  • Real-time performance mode
  • Effect chain optimization
  • Preset library

Milestone: Feature-complete audio engine

🎯 Phase 7: Polish & Distribution (Months 18-24)

Goal: Production release

Deliverables:

  • Web interface (browser-based editor)
  • VST/AU plugin version
  • Comprehensive documentation
  • Tutorial library
  • Community examples
  • Performance benchmarks

Milestone: Public v1.0 release

Parallel Workstreams

Workstream A: Language Design

Focus: User-facing DSL syntax and semantics

Activities:

  • Harmony DSL grammar finalization
  • RiffStack YAML spec evolution
  • Example composition library
  • User testing & feedback

Workstream B: Compiler Infrastructure

Focus: MLIR dialects and optimization

Activities:

  • Dialect definitions
  • Lowering pass implementation
  • Optimization strategy
  • Backend targeting

Workstream C: Audio Engine

Focus: DSP implementation and performance

Activities:

  • New operation development
  • Buffer management optimization
  • Real-time performance tuning
  • Device I/O abstraction

Success Metrics

Technical Milestones

Compiler:

  • Harmony DSL compiles to MIDI
  • Harmony DSL compiles to audio
  • MLIR lowers through all dialects
  • CPU backend <5ms latency
  • GPU backend handles 100+ voices
  • WebGPU runs in browser

Audio Quality:

  • 48kHz/16-bit minimum
  • No audible artifacts (clicks, pops)
  • Voice-leading matches human arrangers
  • Professional-grade synthesis quality

Developer Experience:

  • Compile time <1s for typical patches
  • Clear error messages (musical + technical)
  • Step-through IR debugging
  • Performance profiling tools

User Adoption

Community:

  • 1,000+ experimental users (months 6-12)
  • 100+ example compositions shared
  • 10+ tutorial videos/blog posts
  • Active Discord/forum discussions

Production Use:

  • 100+ paying users (educational/professional tiers)
  • 5+ livecoding performances
  • 3+ educational institution adoptions
  • Integration requests from DAW vendors

Validation Experiments

Musical Validation

  • Can voice-lead ii-V-I smoothly?
  • Can generate convincing jazz reharmonization?
  • Can create complete song from harmony DSL?
  • Do musicians prefer this to typing chord symbols?

Technical Validation

  • Does MLIR compilation improve performance?
  • Can we achieve <10ms end-to-end latency?
  • Does WebGPU match native quality?
  • Can constraint solver handle complex progressions?

Market Validation

  • Will livecoding community adopt this?
  • Will educators pay for licenses?
  • Is harmony DSL more accessible than Max/MSP?
  • Does MLIR differentiate vs SuperCollider/Pure Data?

Risk Mitigation

Technical Risks

Risk: Voice-leading constraint solver too slow

  • Mitigation: Heuristic fallback, precomputed voicing tables
  • Validation: Benchmark on complex progressions

Risk: MLIR learning curve too steep

  • Mitigation: Start with interpreter, add compilation later
  • Validation: Prototype without MLIR first

Risk: WebGPU audio latency unacceptable

  • Mitigation: Focus on CPU/GPU, WebGPU as bonus
  • Validation: Early WebGPU prototype testing

Market Risks

Risk: Musicians prefer visual tools (Max/MSP)

  • Mitigation: Build web GUI alongside text DSL
  • Validation: User testing with both interfaces

Risk: Free tools (SuperCollider, Pure Data) sufficient

  • Mitigation: Focus on unique harmony features, not just synthesis
  • Validation: Emphasize harmony DSL differentiation

Risk: Too niche (experimental music only)

  • Mitigation: Target education market alongside artists
  • Validation: Pilot programs with music schools

Dependencies & Prerequisites

Phase 1-2 (Harmony DSL)

  • Languages: Python (parser), YAML (syntax)
  • Libraries: music21 (music theory), constraint (SAT solver)
  • Skills: Music theory, language design

Phase 3-4 (MLIR)

  • Languages: C++ (MLIR), Python (bindings)
  • Libraries: LLVM/MLIR, pybind11
  • Skills: Compiler engineering, IR design

Phase 5 (Multi-Backend)

  • Languages: CUDA/HIP (GPU), WGSL (WebGPU)
  • Libraries: Vulkan, WebGPU API
  • Skills: GPU programming, parallel computing

Open Questions

Strategic

  • Standalone tool vs Kairo module?
  • VST plugin vs web app vs both?
  • Educational SaaS vs one-time purchase?

Technical

  • Pure YAML syntax vs hybrid (YAML + custom DSL)?
  • Compile-time vs runtime voice-leading?
  • Monolithic compiler vs separate tools?

Community

  • Open-source vs proprietary?
  • Self-hosted vs cloud rendering?
  • Desktop-first vs web-first?

Related Documents

Next Immediate Actions

This Week

  1. Finalize harmony DSL syntax grammar
  2. Prototype voice-leading constraint solver
  3. Create 5 example progressions (ii-V-I, modal, jazz)

This Month

  1. Implement basic harmony → MIDI pipeline
  2. Design theory MLIR dialect specification
  3. User testing with musician friends

This Quarter

  1. Complete Phase 1 (Core Harmony DSL)
  2. Begin Phase 2 (Harmony + Audio Integration)
  3. Validate musical quality with real compositions

Last Updated: 2025-11-23 Current Phase: Planning → Phase 1 (Harmony DSL Prototype) Next Milestone: MIDI output from harmony progressions