🏹 Quiver

A modular audio synthesis library using Arrow-style combinators and graph-based patching.

Table of Contents

• Project Status
• Why Quiver?
• Features
• Architecture
• Quick Start
• Documentation
• Examples
• Development
• Contributing
• License

🚧 Project Status

Quiver is pre-1.0 and under active development. There are no published releases yet — depend on it via git if you want to experiment. The three-layer architecture is in place and the module set is broad, but the public API is still evolving and may change between commits without notice. Expect rough edges; feedback and contributions are very welcome.

🤔 Why Quiver?

Traditional audio synthesis libraries often force you to choose between:

• Low-level control with verbose, error-prone code
• High-level convenience that hides the signal flow

Quiver gives you both. Inspired by category theory and modular synthesizers, it provides:

// Compose modules functionally with Arrow-style combinators
let synth = oscillator >>> filter >>> amplifier;

// Or patch them like hardware, jack to jack
patch.connect(vco.out("saw"), vcf.in_("in")).unwrap();

How Quiver Compares

Quiver's niche is an embeddable, Rust-first modular-synth graph with hardware-style semantics — a no_std core plus first-class WebAssembly bindings.

If you want a signal-flow combinator DSP library, FunDSP is excellent and an inspiration. If you want a finished desktop instrument, use VCV Rack. Quiver is for building modular instruments and tools — in native apps, plugins, or the browser — from Rust.

✨ Features

• 🔗 Typed Combinators: Compose audio modules using category-theory-inspired operators (>>>, ***, &&&)
• 🎛️ Graph-Based Patching: Build complex synthesizer patches with a flexible node/cable system
• 🎚️ Analog Modeling: Realistic VCO drift, filter saturation, and component tolerances
• 🎹 Polyphony: Built-in voice allocation with multiple algorithms
• ⚡ SIMD Optimization: Optional vectorized processing for performance-critical applications
• 💾 Serialization: Save and load patches as JSON
• 🔧 no_std Support: Run on embedded systems and WebAssembly targets

🏗️ Architecture

Quiver is built in three composable layers:

graph TD
    subgraph "Layer 3: Patch Graph"
        VCO[VCO] --> VCF[VCF]
        VCF --> VCA[VCA]
        VCA --> Output[Output]
        VCO --> LFO[LFO]
        LFO --> VCF
        ADSR[ADSR] --> VCA
    end

    subgraph "Layer 2: Port System"
        Ports["SignalKind: Audio | V/Oct | Gate | Trigger | CV<br/>ModulatedParam: Linear | Exponential | V/Oct ranges"]
    end

    subgraph "Layer 1: Typed Combinators"
        Combinators["Chain (>>>) | Parallel (***) | Fanout (&&&) | Feedback"]
    end

    Output ~~~ Ports
    Ports ~~~ Combinators

Layer 1 - Combinators: Functional composition with type-safe signal flow Layer 2 - Ports: Rich metadata for inputs/outputs with modulation support Layer 3 - Graph: Visual patching with cables, mixing, and normalled connections

🚀 Quick Start

Add Quiver to your Cargo.toml (the package is published as quiver-dsp because the bare name quiver was taken on crates.io; the library name is still quiver, so imports are use quiver::...):

[dependencies]
quiver-dsp = "0.1"

Feature Flags

no_std Support

Quiver supports three tiers for different environments. All tiers are no_std but require a global allocator — the core graph uses Box/Vec/String, so there is no allocator-free tier:

# Tier 1: Core DSP only (no_std, heap required — bring your own #[global_allocator])
quiver-dsp = { version = "0.1", default-features = false }

# Tier 2: With serialization & presets (WASM web apps)
quiver-dsp = { version = "0.1", default-features = false, features = ["alloc"] }

# Tier 3: Full std (desktop apps, default)
quiver-dsp = "0.1"

Build a subtractive synthesizer voice — VCO → VCF → VCA, shaped by an ADSR envelope:

use quiver::prelude::*;

fn main() {
    // Create a patch at CD-quality sample rate.
    let sr = 44_100.0;
    let mut patch = Patch::new(sr);

    // Add modules — each `add` takes a name and returns a `NodeHandle`
    // used to reference that module's ports.
    let vco = patch.add("vco", Vco::new(sr));
    let vcf = patch.add("vcf", Svf::new(sr));
    let vca = patch.add("vca", Vca::new());
    let env = patch.add("env", Adsr::new(sr));
    let out = patch.add("out", StereoOutput::new());

    // Patch cables jack-to-jack: VCO → VCF → VCA → stereo out.
    // `in_()` is spelled with a trailing underscore because `in` is a Rust keyword.
    patch.connect(vco.out("saw"), vcf.in_("in")).unwrap();
    patch.connect(vcf.out("lp"), vca.in_("in")).unwrap();
    patch.connect(vca.out("out"), out.in_("left")).unwrap();
    patch.connect(vca.out("out"), out.in_("right")).unwrap();

    // The envelope modulates both the filter cutoff and the amplitude.
    patch.connect(env.out("env"), vcf.in_("cutoff")).unwrap();
    patch.connect(env.out("env"), vca.in_("cv")).unwrap();

    // Select the output module, then compile before processing (required).
    patch.set_output(out.id());
    patch.compile().unwrap();

    // Advance the patch one sample at a time; each `tick()` returns stereo audio.
    let (left, right) = patch.tick();
    println!("first sample: {left}, {right}");
}

📚 Documentation

🎵 Examples

Run the examples to hear Quiver in action:

# Simple patch demo
cargo run --example simple_patch

# FM synthesis tutorial
cargo run --example tutorial_fm

# Polyphonic synth
cargo run --example tutorial_polyphony

# See all examples
cargo run --example

Example Patches

🛠️ Development

# Setup development environment (installs tools and git hooks)
make setup

# Run all checks (format, lint, test)
make check

# Run tests with coverage (80% threshold)
make coverage

# Format and lint
make fmt lint

# Generate changelog
make changelog

# See all available commands
make help

See DEVELOPMENT.md for the development roadmap and architecture decisions.

🤝 Contributing

Contributions are welcome! Please read our Contributing Guidelines before submitting a PR.

Areas Where Help is Appreciated

Quick Contribution Guide

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-filter)
3. Make your changes
4. Run checks (make check)
5. Commit with conventional commits
6. Open a Pull Request

Look for issues labeled good first issue to get started!

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.