56 lines
2.5 KiB
Markdown
56 lines
2.5 KiB
Markdown
# 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.
|
|
|
|
## 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.
|