# Introduction

Cagire includes an audio engine called `Doux`. No external software is needed to make sound. `Doux` is an opinionated, semi-modular synthesizer. It was designed for live coding environments and works by receiving command strings that describe sounds. Despite its fixed architecture,`Doux` is extremely versatile and will likely cover most of the audio needs of a live coder.

## How It Works

When you write a Forth script and emit (`.`), the script produces a command string. This command travels to the audio engine, which interprets it and creates a voice. The voice plays until its envelope finishes or until it is killed by another voice. You can also spawn infinite voices, but you will need to manage their lifecycle manually, otherwise they will never stop.

```forth
saw s c4 note 0.8 gain 0.3 verb .
```

## Voices

Each `emit` (`.`) creates or manages a voice by sending parameters. Voices are independent sound generators with their own oscillator, envelope, and effects. The engine can run many voices at once (up to `128`, default `32`). When you exceed the voice limit, the oldest voice is stolen (a process called _round robin scheduling_). You can monitor voice usage on the Engine page:

- **Active voices**: how many are playing right now.
- **Peak voices**: the maximum reached since last reset.

Press `r` on the Engine page to reset the peak counter.

## Parameters

After selecting a sound source, you add parameters. Each parameter word takes a value from the stack and stores it in the command register:

```forth
saw s
  c4 note        ;; pitch
  0.5 gain       ;; volume
  0.1 attack     ;; envelope attack time
  2000 lpf       ;; lowpass filter at 2kHz
  0.3 verb       ;; reverb mix
.
```

Parameters can appear in any order. They accumulate until you emit. You can clear the register using the `clear` word.

## Global Parameters

Use `all` to apply parameters globally. Global parameters persist across all patterns and steps until cleared with `noall`. They work both prospectively (before sounds) and retroactively (after sounds):

```forth
;; Prospective: set params before emitting
500 lpf 0.5 verb all
kick s 60 note .      ;; gets lpf=500 verb=0.5
hat s 70 note .       ;; gets lpf=500 verb=0.5
```

```forth
;; Retroactive: patch already-emitted sounds
kick s 60 note .
hat s 70 note .
500 lpf 0.5 verb all  ;; both outputs get lpf and verb
```

Per-sound parameters override global ones:

```forth
500 lpf all
kick s 2000 lpf .     ;; lpf=2000 (per-sound wins)
hat s .               ;; lpf=500  (global)
```

Use `noall` to clear global parameters:

```forth
500 lpf all
kick s .              ;; gets lpf
noall
hat s .               ;; no lpf
```

## Controlling Existing Voices

You can emit without a sound name. In this case, no new voice is created. Instead, the parameters are sent to control an existing voice. Use `voice` with an ID to target a specific voice:

```forth
0 voice 500 freq .   ;; change frequency on voice 0
```

This is useful for modulating long-running or infinite voices. Set up a drone on one step with a known voice ID, then tweak its parameters from other steps.

## Hush and Panic

Two emergency controls exist on the Engine page:

- `h` - **Hush**: gracefully fade out all voices
- `p` - **Panic**: immediately kill all voices

Use hush when things get too loud. Use panic when things go wrong.