Cagire/docs/prelude.md

The Prelude

When you define a word in a step, it becomes available to all steps. But when you close and reopen the project, the dictionary is empty again. Words defined in steps only exist after those steps run.

The prelude solves this. It's a project-wide script that runs automatically when playback starts and when you load a project.

Accessing the Prelude

Press d to open the prelude editor. Press Esc to save and evaluate. Press D (Shift+d) to re-evaluate the prelude without opening the editor.

What It's For

Define words that should be available everywhere, always:

: kick "kick" s 0.9 gain . ;
: hat "hat" s 0.4 gain . ;
: bass "saw" s 0.7 gain 200 lpf . ;

Now every step in your project can use kick, hat, and bass from the first beat.

When It Runs

The prelude evaluates:

1. When you press Space to start playback (if stopped)
2. When you load a project
3. When you press D manually

It does not run on every step, only once at these moments. This makes it ideal for setup code: word definitions, initial variable values, seed resets.

Practical Example

A prelude for a techno project:

: k "kick" s 1.2 attack . ;
: sn "snare" s 0.6 gain 0.02 attack . ;
: hh "hat" s 0.3 gain 8000 hpf . ;
: sub "sine" s 0.8 gain 150 lpf . ;
0 seed

Step scripts become trivial:

c1 note k sub

The sound design lives in the prelude. Steps focus on rhythm and melody.