Cagire/docs/how_it_works.md

How Does It Work?

Cagire is a step sequencer where each step contains a Forth script instead of the typical note data. When the sequencer reaches a step, it runs the script. A script can do whatever it is programed to do, such as producing sound commands sent to an internal audio engine. Everything else is similar to a step sequencer: you can toggle / untoggle, copy / paste any step or group of steps, etc. You are completely free to define what your scripts will do. It can be as simple as playing a note, or as complex as triggering random audio samples with complex effects. Scripts can also share code and data with each other.

Project / session organization

Cagire can run multiple patterns concurrently. Each pattern contains a given number of steps. Every session / project is organized hierarchically:

• 32 Banks
• 32 Patterns per bank
• 128 Steps per pattern

That's over 130,000 possible steps per project. Most of my sessions use 15-20 at best.

What does a script look like?

Forth is a stack-based programming language. It is very minimalistic and emphasizes simplicity and readability. Using Forth doesn't feel like programming at all. It feels more like juggling with words and numbers or writing bad computer poetry. There is pretty much no syntax to learn, just a few rules to follow. Forth is ancient, powerful, flexible, and... super fun to live code with! Here is a minimal program that will play a middle C note using a sine wave:

c4 note sine sound .

Read the program backwards and you will understand what it does instantly:

• .: we want to play a sound.
• sine sound: the sound is a sinewave.
• c4 note: the pitch is C4 (middle-C).

Scripts can be simple one-liners or complex programs with conditionals, loops, and randomness. They tend to look like an accumulation of words and numbers. Use space and line returns to your advantage. The Forth language can be learned... on the spot. You just need to understand the following basic rules:

• there are words and numbers.
• they are delimited by spaces.
• everything piles up on the stack.

Obviously you will need to understand what the stack is, but it will take you five minutes. That's it. See the Forth section for details.

The Audio Engine

Cagire includes a complete synthesis engine. No external software is required to play music. It comes with a large number of sound sources and sound shaping tools: oscillators, sample players, effects, filters, and more. The audio engine is quite capable and versatile, and can accomodate a vast array of genres / styles. Here are a few examples :

;; sawtooth wave with lowpass filter, chorus and reverb
saw sound 1200 lpf 0.2 chorus 0.8 verb .

;; pure sine wave with vibrato and bit crushing
0.5 vibmod 4 vib sine sound 8 crush 0.8 gain .

;; very loud and pitched-down kick drum using an audio sample
kkick sound 1.5 distort 0.9 postgain 0.8 speed .

Timing & Synchronization

Cagire uses Ableton Link to manage timing and synchronization. This means that all devices using the same protocol can be synchronized to the same tempo. Most commercial softwares support this protocol. The playback speed is defined as a BPM (beats per minute) value. Patterns can run at different speeds relative to the master tempo. Most of the durations in Cagire are defined in terms of beats.