# Big Picture

Let's answer some basic questions: what exactly is Cagire? What purpose does it serve? Cagire is a small and simple piece of software that allows you to create music live while playing with scripts. At heart, it is really nothing more than a classic step sequencer, the kind you can buy in a music store. It is deliberately kept small and simple. Adding the Forth language to program steps allows you to create patterns and behaviors of any complexity. Forth also makes it super easy to extend and to customize Cagire while keeping the core mechanisms and the logic simple.

Cagire is not complex, it is just very peculiar. It has been created as a hybrid between a step sequencer and a programming environment. It allows you to create music live and to extend and customize it using the power of Forth. It has been designed to be fast and responsive, low-tech in the sense that you can run it on any decent computer. You can think of it as a musical instrument. You learn it by getting into the flow and practicing. What you ultimately do with it is up to you: improvisation, composition, etc. Cagire is also made to be autonomous, self-contained, and self-sustaining: it contains all the necessary components to make music without relying on external software or hardware.

## Scripts, Not Notes

A traditional step sequencer would offer the musician a grid where each step represents a note or a single musical event. Cagire replaces notes and/or events in favour of **Forth scripts**. When the sequencer reaches a step to play, it runs the script associated with it. A script can do whatever it is programmed to do: play a note, trigger a sample, apply effects, generate randomness, or all of the above. Scripts can share code and data with each other. Everything else works like a regular step sequencer: you can toggle, copy, paste, and rearrange steps freely.

## What Does a Script Look Like?

A Forth script is generally kind of small, and it solves a simple problem: playing a chord, tweaking some parameters, etc. The more focused it is, the better. Using Forth doesn't feel like programming at all. It feels more like juggling with words and numbers or writing bad computer poetry. Here is a program that plays a middle C note using a sine wave:

```forth
c4 note sine sound .
```

Read it backwards and you will understand what it does:

- `.` — play a sound.
- `sine sound` — the sound is a sine wave.
- `c4 note` — the pitch is C4 (middle C).

Five tokens separated by spaces. There is pretty much no syntax to learn, just three rules:

- There are `words` and `numbers`.
  - A `word` is anything that is not a space or a number.
  - A `number` is anything that is not a space or a word.
- They are separated by spaces.
- Everything piles up on the **stack**.

The stack is what makes Forth tick. Think of it as a pile of things. `c4` puts a pitch on the pile. `note` picks it up. `sine` chooses a waveform. `sound` assembles everything into a voice. `.` plays it. Each word picks up what the previous ones left behind and leaves something for the next. Scripts can be simple one-liners or complex programs with conditionals, loops, and randomness. You will need to understand the stack, but it will take five minutes. See the **Forth** section for details.

## The Audio Engine

Cagire includes a complete synthesis and sampling engine. No external software is required to play music. It comes with oscillators, sample players, effects, filters, and more. Here are a few examples:

```forth
;; sawtooth wave + lowpass filter with envelope + chorus + reverb
100 199 freq saw sound 250 lpf 8 lpe 1 lpd 0.2 chorus 0.8 verb 2 dur .
```

```forth
;; sine wave + vibrato + bit crushing
0.25 vibmod 8 vib sine sound 6 crush 0.8 gain .
```

```forth
;; white noise + sine wave + envelope = percussion 
white sine sound 100 freq 0.5 decay 24 penv 0.5 pdec 2 dur .
```

```forth
;; random robot noises: sine + randomized freq + ring modulation
10 1000 rand freq sine sound 1 100 rand rm 0.5 1.0 rand rmddepth .
```

By _creating words_, registering synth definitions and effects, you will form a vocabulary that can be used to create complex sounds and music. The audio engine is quite capable, and you won't ever run out of new things to try!

## Project Organization

A step sequencer can generally keep multiple patterns in memory, organized in banks. By switching from pattern to pattern, from bank to bank, you can create complex compositions and entire live performances. Cagire works exactly the same and offers banks and patterns. Cagire can also run multiple patterns at the same time. Each pattern can contain from `1` to `1024` steps. Every project is organized following a hierarchical structure:

- **32 Banks**: a (named) container holding patterns.
- **32 Patterns**: each pattern can contain from `1` to `1024` steps.
- **1024 Steps**: each step can be used to program anything you have in mind. 

A single project / session can store a lot, probably more than you'll need for a gig or an album. That's up to you to decide if you prefer to keep things simple or to store your entire life in Forth.

## Timing and Synchronization

Everything in Cagire is measured in **beats**. A beat is the pulse of the music. How fast that pulse goes is controlled by a single number, the **BPM** (_beats per minute_). At 120 BPM, one beat lasts half a second. Each step in a pattern is a sixteenth note: **four steps per beat**. At 120 BPM, that is one step every 125 milliseconds. Change the BPM and every step follows. Patterns can run at different speeds. A pattern set to **2x** fires its steps twice as fast. A pattern at **0.5x** takes twice as long. The speed is a multiplier on the step rate, not a separate tempo — all patterns still share the same beat.

Cagire uses **Ableton Link** for synchronization. All devices on the same network share a common tempo automatically. If you change the BPM in Cagire, other apps follow. If they change it, Cagire follows. Most commercial music software supports Link.

## Live Coding

The sequencer runs while you edit. When you change a step's script, the new version takes effect the next time that step fires. There is no compile step, no "run" button — just write, listen, and adjust. This is the core loop: you hear a pattern playing, open a step, change a word, close it, and immediately hear the difference. Forth's brevity helps — swapping `sine` for `saw` or adding `0.3 verb` at the end is a single edit that reshapes the sound. Cagire is not a write-then-run environment. It is closer to a conversation: you propose something, the sequencer plays it back, and you refine from there.
