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.

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:

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:

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.

2.5 KiB Raw Blame History