quiver-dsp 0.1.0

# Installation

Getting Quiver into your project is straightforward. The library is pure Rust with minimal dependencies.

## Prerequisites

- **Rust 1.78+** (2021 edition) — this is Quiver's MSRV (Minimum Supported Rust Version)
- **Cargo** (comes with Rust)

Verify your installation:

```bash
rustc --version
cargo --version
```

## Adding Quiver to Your Project

### As a Dependency

Add to your `Cargo.toml`. The package is published on crates.io as
**`quiver-dsp`** (the bare name `quiver` was already taken by an unrelated
crate), but the *library* name is still `quiver` — so your code writes
`use quiver::prelude::*` regardless:

```toml
[dependencies]
quiver-dsp = "0.1"
```

Or with specific features:

```toml
[dependencies]
quiver-dsp = { version = "0.1", features = ["simd"] }
```

To track the development branch instead, use a git dependency:

```toml
[dependencies]
quiver-dsp = { git = "https://github.com/alexnodeland/quiver" }
```

### Available Features

| Feature | Default | Description |
|---------|---------|-------------|
| `std` | Yes | Full functionality including OSC, visualization (implies `alloc`) |
| `alloc` | No | Serialization, presets, and I/O for `no_std` + heap environments |
| `simd` | No | SIMD vectorization for block processing (works with any tier) |
| `wasm` | No | WebAssembly bindings via `wasm-bindgen` + TypeScript types via `tsify` (implies `alloc`). See [Browser & App Integration](../how-to/browser-integration.md). |

### Feature Tiers

Quiver supports three tiers for different environments:

#### Tier 1: Core Only (`default-features = false`)

`no_std`, but still requires a global allocator — the core patch graph uses
`Box`/`Vec`/`String`, so you must provide a `#[global_allocator]` (there is no
allocator-free tier). Suitable for embedded systems that have a heap:

```toml
[dependencies]
quiver-dsp = { version = "0.1", default-features = false }
```

Includes all core DSP modules: oscillators, filters, envelopes, amplifiers, mixers, utilities, logic modules, analog modeling, polyphony, and the patch graph.

#### Tier 2: With Alloc (`features = ["alloc"]`)

For WASM web apps and embedded systems with heap:

```toml
[dependencies]
quiver-dsp = { version = "0.1", default-features = false, features = ["alloc"] }
```

Adds:
- **Serialization** - JSON save/load for patches (`PatchDef`, `ModuleDef`, `CableDef`)
- **Presets** - Ready-to-use patch presets (`ClassicPresets`, `PresetLibrary`)
- **I/O Modules** - External inputs/outputs, MIDI state (`AtomicF64`, `MidiState`)

#### Tier 3: Full Std (default)

For desktop applications:

```toml
[dependencies]
quiver-dsp = "0.1"
```

Adds:
- **Extended I/O** - OSC protocol, Web Audio interfaces
- **Visual Tools** - Scope, Spectrum Analyzer, Level Meter, Automation Recorder
- **MDK** - Module Development Kit for creating custom modules

#### Feature Matrix

| Tier | DSP | Serialize | Presets | I/O | OSC | Visual | MDK |
|------|-----|-----------|---------|-----|-----|--------|-----|
| Core | ✓ | | | | | | |
| `alloc` | ✓ | ✓ | ✓ | ✓ | | | |
| `std` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |

#### Implementation Notes

- Uses `BTreeMap` instead of `HashMap` in non-std modes (no hashing required)
- Includes a seedable Xorshift128+ RNG for deterministic random generation
- Math functions provided by `libm` (sin, cos, pow, sqrt, exp, log, etc.)
- Heap allocations via `alloc` crate (Vec, Box, String)

## Verifying Installation

Create a simple test program:

```rust,ignore
use quiver::prelude::*;

fn main() {
    let patch = Patch::new(44100.0);
    println!("Quiver is working! Patch created at {}Hz", 44100.0);
}
```

Run it:

```bash
cargo run
```

## Building the Examples

Clone the repository and run an example:

```bash
git clone https://github.com/alexnodeland/quiver
cd quiver
cargo run --example simple_patch
```

## Building Documentation

Generate the API documentation locally:

```bash
cargo doc --open
```

This opens the rustdoc documentation in your browser with all type information and examples.

## Editor Setup

For the best experience, use an editor with Rust support:

- **VS Code** with rust-analyzer extension
- **IntelliJ IDEA** with Rust plugin
- **Neovim** with rust-tools.nvim

Type hints are particularly helpful given Quiver's strong typing—your editor will show you exactly what signals flow where.

---

Next: [Your First Patch](./first-patch.md)