BuboBubo/Cagire
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Feat: documentation, UI/UX

Browse Source
This commit is contained in:
Raphaël Forment
2026-03-01 19:09:52 +01:00
parent ecb559e556
commit db44f9b98e
57 changed files with 1531 additions and 615 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
docs/getting-started/banks_patterns.md
View File

@@ -6,6 +6,8 @@ Cagire organizes all your patterns and data following a strict hierarchy:
- **Banks** contain **Patterns**.
- **Patterns** contain **Steps**.
If strict organization isn't your style, don't worry, you can ignore banks entirely and just work in a single pattern. You can also escape the strict metric using sub-step timing and randomness.
## Structure
```
@@ -15,7 +17,7 @@ Project
└── 1024 Steps (per pattern)
```
A single project gives you 32 banks, each holding 32 patterns. You get 1024 patterns in each project, ~1.048.000 steps. This means that you can create a staggering amount of things. Don't hesitate to create copies, variations, and explore the pattern system thoroughly.
A single project gives you 32 banks, each holding 32 patterns. You get 1024 patterns in each project, ~1.048.000 steps. This means that you can create a staggering amount of music. Don't hesitate to create copies, variations, and explore the pattern system thoroughly. The more you add, the more surprising it becomes.
## Patterns
@@ -29,7 +31,7 @@ Each pattern is an independent sequence of steps with its own properties:
| Sync Mode | Reset or Phase-Lock on re-trigger | `Reset` |
| Follow Up | What happens when the pattern finishes an iteration | `Loop` |
Press `e` in the patterns view to edit these settings.
Press `e` in the patterns view to edit these settings. After editing properties, you will have to hit the `c` key to _commit_ these changes. More about that later!
### Follow Up
@@ -49,6 +51,8 @@ Access the patterns view with `F2` (or `Ctrl+Up` from the sequencer). The view s
- `M` Muted
- `S` Soloed
It is quite essential for you to understand the stage / commit system in order to use patterns. Please read the next section carefully!
### Keybindings
| Key | Action |
@@ -63,3 +67,5 @@ Access the patterns view with `F2` (or `Ctrl+Up` from the sequencer). The view s
| `Ctrl+c` / `Ctrl+v` | Copy / Paste |
| `Delete` | Reset to empty pattern |
| `Esc` | Cancel staged changes |

25
docs/getting-started/big_picture.md
View File

@@ -1,6 +1,8 @@
# 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.
> **What exactly is Cagire? What purpose does it serve?**
Cagire is a small and simple software that allows you to create music live while programming short 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 in form, but it goes rather deep if you take the time to discover the audio engine and all its capabilities. Adding the Forth language to program steps allows you to create patterns and behaviors of any complexity. Forth also makes it 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.
@@ -8,29 +10,40 @@ Cagire is not complex, it is just very peculiar. It has been created as a hybrid
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.
```forth
0.0 8.0 rand at
sine sound
200 2000 rand 100 4000 rand
4 slide freq 0.6 verb 2 vib
0.125 vibmod 0.2 chorus
0.4 0.6 rand gain
.
```
## 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:
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 for two steps using a sine wave:
```forth
c4 note sine sound .
c4 note sine sound 2 decay .
```
Read it backwards and you will understand what it does:
- `.` — play a sound.
- `2 decay` — the sound takes two steps to die.
- `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 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 `word` is anything that is not a space or a number (can include symbols).
- 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 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. Cagire requires you to understand what the stack is. The good thing is that it will take five minutes for you to make sense of it. See the **Forth** section for details.
## The Audio Engine

35
docs/getting-started/editing.md
View File

@@ -1,6 +1,6 @@
# Editing a Step
Each step in Cagire contains a Forth script. When the sequencer reaches that step, it runs the script to produce sound. This is where you write your music. Press `Enter` when hovering over any step to open the code editor. The editor appears as a modal overlay with the step number in the title bar. If the step is a linked step (shown with an arrow like `→05`), pressing `Enter` navigates to the source step instead.
Each step in Cagire contains a Forth script. When the sequencer reaches that step, it runs the script to produce sound. This is where you write your music. Press `Enter` when hovering over any step to open the code editor. The editor appears as a modal overlay with the step number in the title bar. If the step is a mirrored step (shown with an arrow like `→05`), pressing `Enter` navigates to the source step instead.
## Writing Scripts
@@ -18,7 +18,7 @@ Add parameters before words to modify them:
c4 note 0.75 decay sine sound .
```
Writing long lines is not recommended because it can become quite unmanageable. Instead, break them into multiple lines for clarity:
Writing long lines can become tedious. Instead, break your code into multiple lines for clarity:
```forth
;; the same sound on multiple lines
@@ -29,6 +29,12 @@ sine sound
.
```
Forth has no special rule about what a line should look like and space has no meaning.
## Adding comments to your code
You can comment a line using `;;`. This is not very common for people that are used to Forth. There are no multiline comments.
## Saving
- `Esc` — Save, compile, and close the editor.
@@ -64,27 +70,6 @@ Press `Ctrl+F` to open the search bar. Type your query, then navigate matches:
- `Enter` — Confirm and close search.
- `Esc` — Cancel search.
## Debugging
## Script preview
Press `Ctrl+S` to toggle the stack display. This shows the stack state evaluated up to the cursor line, useful for understanding how values flow through your script.
Press `Ctrl+R` to execute the script immediately as a one-shot, without waiting for the sequencer to reach the step. A green flash indicates success, red indicates an error.
## Keybindings
| Key | Action |
|-----|--------|
| `Esc` | Save and close |
| `Ctrl+E` | Evaluate (save + compile in place) |
| `Ctrl+R` | Execute script once |
| `Ctrl+S` | Toggle stack display |
| `Ctrl+B` | Open sample finder |
| `Ctrl+F` | Search |
| `Ctrl+N` | Next match / next suggestion |
| `Ctrl+P` | Previous match / previous suggestion |
| `Ctrl+A` | Select all |
| `Ctrl+C` | Copy |
| `Ctrl+X` | Cut |
| `Ctrl+V` | Paste |
| `Shift+Arrows` | Extend selection |
| `Tab` | Accept completion / sample |
Press `Ctrl+R` to execute the script immediately as a one-shot, without waiting for the sequencer to reach the step. A green flash indicates success, red indicates an error. This is super useful for sound design. It also works when hovering on a step with the editor closed.

50
docs/getting-started/engine.md
View File

@@ -1,6 +1,6 @@
# The Audio Engine
The Engine page (`F6`) is where you configure audio hardware, adjust performance settings, and manage your sample library. The right side of the page shows a real-time oscilloscope and spectrum analyzer. The page is divided into three sections. Press `Tab` to move between them, `Shift+Tab` to go back.
The Engine page (`F6`) is where you configure audio hardware, manage MIDI connections, set up Ableton Link, and manage your sample library. The left column holds six configuration sections — press `Tab` to move between them, `Shift+Tab` to go back. The right column is a read-only monitoring panel with VU meters, status metrics, and an oscilloscope.
## Devices
@@ -17,11 +17,29 @@ Four audio parameters are adjustable with `Left`/`Right`:
| Voices | 1–128 | Maximum polyphony (simultaneous sounds) |
| Nudge | -100 to +100 ms | Timing offset to compensate for latency |
The last two rows — sample rate and audio host — are read-only values reported by your system. After changing the buffer size or channel count, press `Shift+r` to restart the audio engine for changes to take effect.
After changing the buffer size or channel count, press `Shift+r` to restart the audio engine for changes to take effect.
## Link
Ableton Link synchronizes tempo across devices and applications on the same network. Three settings are adjustable with `Left`/`Right`:
- **Enabled** — Turn Link on or off. A status badge next to the header shows DISABLED, LISTENING, or CONNECTED.
- **Start/Stop Sync** — Whether play/stop commands are shared with other Link peers.
- **Quantum** — Number of beats per phrase, used for phase alignment.
Below the settings, three read-only session values update in real time: Tempo, Beat, and Phase.
## MIDI Outputs
Four output slots (0–3). Browse with `Up`/`Down`, cycle available devices with `Left`/`Right`. A slot shows "(not connected)" until you assign a device.
## MIDI Inputs
Same layout as outputs — four input slots (0–3) with the same navigation.
## Samples
This section shows how many sample directories are registered and how many files have been indexed. Press `A` to open a file browser and add a new sample directory. Press `D` to remove the last one. Cagire indexes audio files (wav, mp3, ogg, flac, aac, m4a) from all registered paths.
This section shows how many sample directories are registered and how many files have been indexed. Browse existing paths with `Up`/`Down`. Press `A` to open a file browser and add a new sample directory. Press `D` to remove the selected path. Cagire indexes audio files (wav, mp3, ogg, flac, aac, m4a) from all registered paths.
Sample directories must be added here before you can use the sample browser or reference samples in your scripts.
@@ -30,23 +48,17 @@ Sample directories must be added here before you can use the sample browser or r
A few keys work from anywhere on the Engine page:
- `h` — Hush. Silence all audio immediately.
- `p` — Panic. Hard stop, clears all active voices.
- `p` — Panic. Hard stop, clears all active voices, stop all patterns.
- `t` — Test tone. Plays a brief sine wave to verify audio output.
- `r` — Reset the peak voice counter.
- `Shift+r` — Restart the audio engine.
## Keybindings
## Monitoring
| Key | Action |
|-----|--------|
| `Tab` / `Shift+Tab` | Next / previous section |
| `Up` / `Down` | Navigate within section |
| `Left` / `Right` | Switch device column / adjust setting |
| `PageUp` / `PageDown` | Scroll device list |
| `Enter` | Select device |
| `D` | Refresh devices / remove last sample path |
| `A` | Add sample directory |
| `Shift+r` | Restart audio engine |
| `h` | Hush |
| `p` | Panic |
| `t` | Test tone |
| `r` | Reset peak voices |
The right column displays a live overview of the engine state. Everything here is read-only.
- **VU Meters** — Left and right channel levels with horizontal bars and dB readouts. Green below -12 dB, yellow approaching 0 dB, red above.
- **Status** — CPU load (with bar graph), active voices and peak count, scheduled events, schedule depth, nudge offset, sample rate, audio host, and Link peers (when connected).
- **Scope** — An oscilloscope showing the current audio output waveform.

98
docs/getting-started/grid.md
View File

@@ -1,43 +1,48 @@
# The Sequencer Grid
The sequencer grid is the main view of Cagire (`F5`). This is the one you see when you open the application. On this view, you can see the step sequencer grid and edit each step using the code editor. You can optionally display the following widgets:
- **an oscilloscope**: visualize the current audio output.
- **a spectrum analyzer**: 32 bands spectrum analyze (mostly cosmetic).
- **a step preview**: visualize the content of the hovered script.
You can press `o` to cycle through layouts. It will basically rotate the sequencer around. Use it to find the view that makes the more sense for you.
The sequencer grid (`F5`) is where you spend most of your time in Cagire. It shows the step sequencer and lets you edit each step using the code editor. This is the first view you see when you open the application. Optional widgets — oscilloscope, spectrum analyzer, goniometer, prelude preview, and step preview — can be toggled on for visual feedback while you work.
## Navigation
Use arrow keys to move between steps. The grid wraps around at pattern boundaries. Press `:` to jump directly to a step by number. This keybinding is useful for very long patterns.
Use arrow keys to move between steps. `Shift+arrows` selects multiple steps, and `Esc` clears any selection. The grid wraps around at pattern boundaries. Press `:` to jump directly to a step by number.
## Preview
Press `p` to enter preview mode. A read-only code editor opens showing the script of the step under the cursor. You can still navigate the grid while previewing. Press `Esc` to exit preview mode.
## Selection
Hold `Shift` while pressing arrow keys to select multiple steps. Press `Esc` to clear the selection.
- `Alt+Up` / `Alt+Down` — Previous / next pattern
- `Alt+Left` / `Alt+Right` — Previous / next bank
## Editing Steps
- `Enter` — Open the script editor
- `t` — Toggle step active/inactive
- `t` — Make a step active / inactive
- `r` — Rename a step
- `Del` — Delete selected steps
## Mirrored Steps
Imagine a drum pattern where four steps play the same kick script. You tweak the sound on one of them — now you have to find and edit all four. Mirrored steps solve this: one step is the source, the others are mirrors that always reflect its script. Edit the source once, every mirror follows.
On the grid, mirrors are easy to spot. They show an arrow prefix like `→05`, meaning "I mirror step 05." Steps that share a source also share a background color, so clusters of linked steps are visible at a glance.
To create mirrors: copy a step with `Ctrl+C`, then paste with `Ctrl+B` instead of `Ctrl+V`. The pasted steps become mirrors of the original. Pressing `Enter` on a mirror jumps to its source and opens the editor there. If you want to break the link and make a mirror independent again, press `Ctrl+H` to harden it back into a regular copy.
## Copy & Paste
- `Ctrl+C` — Copy selected steps
- `Ctrl+V` — Paste as copies
- `Ctrl+B` — Paste as linked steps
- `Ctrl+V` — Paste as independent copies
- `Ctrl+B` — Paste as mirrored steps
- `Ctrl+D` — Duplicate selection
- `Ctrl+H` — Harden links (convert to independent copies)
- `Ctrl+H` — Harden mirrors (convert to independent copies)
Linked steps share the same script as their source. When you edit the source, all linked steps update automatically. This is an extremely important and powerful feature. It allows you to create complex patterns with minimal effort. `Ctrl+H` converts linked steps back to independent copies.
## Prelude
The prelude is a Forth script that runs before every step, useful for defining shared variables and setup code.
- `p` — Open the prelude editor
- `d` — Evaluate the prelude
## Pattern Controls
Each pattern has its own length and speed. Length sets how many steps it cycles through. Speed is a multiplier on the global tempo.
- `<` / `>` — Decrease / increase pattern length
- `[` / `]` — Decrease / increase pattern speed
- `L` — Set length directly
@@ -45,6 +50,8 @@ Linked steps share the same script as their source. When you edit the source, al
## Playback
Playback starts and stops globally across all unmuted patterns. The highlighted cell on the grid marks the currently playing step.
- `Space` — Toggle play / stop
- `+` / `-` — Adjust tempo
- `T` — Set tempo directly
@@ -52,57 +59,24 @@ Linked steps share the same script as their source. When you edit the source, al
## Mute & Solo
Mute silences a pattern; solo silences everything except it. Both work while playing.
- `m` — Mute current pattern
- `x` — Solo current pattern
- `Shift+m` — Clear all mutes
- `Shift+x` — Clear all solos
## Prelude
## Project
The prelude is a Forth script that runs before every step, useful for defining shared variables and setup code.
- `d` — Open the prelude editor
- `Shift+d` — Evaluate the prelude
- `s` — Save project
- `l` — Load project
- `q` — Quit
## Tools
A few utilities accessible from the grid.
- `e` — Euclidean rhythm distribution
- `?` — Show keybindings help
- `o` — Cycle layout
- `Tab` — Toggle sample browser panel
## Visual Indicators
- **Highlighted cell** — Currently playing step
- **Colored backgrounds** — Linked steps share colors by source
- **Arrow prefix** (`→05`) — Step is linked to step 05
## Keybindings
| Key | Action |
|-----|--------|
| `Arrows` | Navigate grid |
| `Shift+Arrows` | Extend selection |
| `:` | Jump to step |
| `Enter` | Open editor |
| `p` | Preview step |
| `t` | Toggle step active |
| `r` | Rename step |
| `Del` | Delete steps |
| `Ctrl+C` / `Ctrl+V` | Copy / Paste |
| `Ctrl+B` | Paste as links |
| `Ctrl+D` | Duplicate |
| `Ctrl+H` | Harden links |
| `<` / `>` | Pattern length |
| `[` / `]` | Pattern speed |
| `L` / `S` | Set length / speed |
| `Space` | Play / Stop |
| `+` / `-` | Tempo up / down |
| `T` | Set tempo |
| `Ctrl+R` | Execute step once |
| `m` / `x` | Mute / Solo |
| `d` | Prelude editor |
| `e` | Euclidean distribution |
| `o` | Cycle layout |
| `Tab` | Sample browser |
| `Ctrl+Z` | Undo |
| `Ctrl+Shift+Z` | Redo |
| `?` | Show keybindings |

64
docs/getting-started/navigation.md
View File

@@ -1,41 +1,6 @@
# Navigation
Cagire's interface is organized as a 3x2 grid of six views:
```
Dict Patterns Options
Help Sequencer Engine
```
- *Dict* : Forth dictionary — learn about the language.
- *Help* : Help and tutorials — learn about the tool.
- *Patterns* : Manage your current session / project.
- *Sequencer* : The main view, where you edit sequences and play music.
- *Options* : Configuration settings for the application.
- *Engine* : Configuration settings for the audio engine.
## Switching Views
Use `Ctrl+Arrow` keys to move between views. A minimap will briefly appear to show your position in the grid. You can also click on the view name at the bottom left to open the switch view panel.
- `Ctrl+Left` / `Ctrl+Right` — move horizontally (wraps around)
- `Ctrl+Up` / `Ctrl+Down` — move vertically (does not wrap)
- `Click` at bottom left — select a view
You can also jump directly to any view with the F-keys:
| Key | View |
|------|------------|
| `F1` | Dict |
| `F2` | Patterns |
| `F3` | Options |
| `F4` | Help |
| `F5` | Sequencer |
| `F6` | Engine |
## Common Keys
These shortcuts work on every view:
Press `?` on any view to see its keybindings. The most important shortcuts are always displayed in the footer bar. Press `Esc` to close the keybindings panel. These shortcuts work on every view:
| Key | Action |
|---------|---------------------------|
@@ -45,6 +10,29 @@ These shortcuts work on every view:
| `l` | Load project |
| `?` | Show keybindings for view |
## Getting Help
## Views
Press `?` on any view to see the associated keybindings. This shows all available shortcuts for the current context. The most important keybindings are displayed in the footer bar. Press `Esc` to close the keybindings panel.
Cagire's interface is organized as a 3x2 grid of six views. Jump to any view with its F-key or `Ctrl+Arrow` keys:
```
F1 Dict F2 Patterns F3 Options
F4 Help F5 Sequencer F6 Engine
```
| Key | View | Description |
|------|------------|-------------|
| `F1` | Dict | Forth dictionary — learn about the language |
| `F2` | Patterns | Manage your current session / project |
| `F3` | Options | Configuration settings for the application |
| `F4` | Help | Help and tutorials — learn about the tool |
| `F5` | Sequencer | The main view, where you edit sequences and play music |
| `F6` | Engine | Configuration settings for the audio engine |
Use `Ctrl+Arrow` keys to move between adjacent views. A minimap will briefly appear to show your position in the grid. You can also click on the view name at the bottom left or in the top left corner of the header bar to open the switch view panel.
- `Ctrl+Left` / `Ctrl+Right` — move horizontally (wraps around)
- `Ctrl+Up` / `Ctrl+Down` — move vertically (does not wrap)
## Secrets
There is a hidden seventh view: the **Periodic Script**. Press `F11` to open it. The periodic script is a free-running Forth script evaluated at every step, independent of any pattern. It is useful for drones, global effects, control logic, and experimentation. See the **Periodic Script** tutorial for details.

37
docs/getting-started/options.md
View File

@@ -1,45 +1,28 @@
# Options
The Options page (`F3`) gathers all configuration settings in one place: display, synchronization and MIDI. Navigate options with `Up`/`Down` or `Tab`, change values with `Left`/`Right`. All changes are saved automatically.
The Options page (`F3`) gathers display and onboarding settings in one place. Navigate with `Up`/`Down` or `Tab`, change values with `Left`/`Right`. All changes are saved automatically. A description line appears below the focused option to explain what it does.
## Display
| Option | Values | Description |
|--------|--------|-------------|
| Theme | (cycle) | Color scheme for the entire interface |
| Hue rotation | 0–360° | Shift theme colors by a hue angle (±5° per step) |
| Hue rotation | 0–360° | Shift all theme colors by a hue angle (±5° per step) |
| Refresh rate | 60 / 30 / 15 fps | Lower values reduce CPU usage |
| Runtime highlight | on / off | Highlight executed code spans during playback |
| Show scope | on / off | Oscilloscope on the engine page |
| Show spectrum | on / off | Spectrum analyzer on the engine page |
| Show scope | on / off | Oscilloscope on the main view |
| Show spectrum | on / off | Spectrum analyzer on the main view |
| Show lissajous | on / off | XY stereo phase scope |
| Gain boost | 1x – 16x | Amplify scope and lissajous waveforms |
| Normalize | on / off | Auto-scale visualizations to fill the display |
| Completion | on / off | Word completion popup in the editor |
| Show preview | on / off | Step script preview on the sequencer grid |
| Performance mode | on / off | Hide header and footer bars |
| Font | 6x13 – 10x20 | Bitmap font size (plugin mode only) |
| Zoom | 0.5x – 2.0x | Interface zoom factor (plugin mode only) |
| Zoom | 50% – 200% | Interface zoom factor (plugin mode only) |
| Window | (presets) | Window size presets (plugin mode only) |
## Ableton Link
Cagire uses Ableton Link to synchronize tempo with other applications on the same network. Three settings control the connection:
- **Enabled** — Turn Link on or off. When enabled, Cagire listens for peers and shares its tempo.
- **Start/Stop sync** — When on, pressing play or stop in one app affects all peers.
- **Quantum** — The beat subdivision used for phase alignment.
Below these settings, a read-only session display shows the current tempo, beat position, and phase. The status line at the top shows the connection state: disabled, listening, or connected with peer count.
## MIDI
Four output slots and four input slots let you connect to MIDI devices. Cycle through available devices with `Left`/`Right`. Each slot can hold one device, and the same device cannot be assigned to multiple slots.
## Onboarding
At the bottom, you can reset the onboarding guides if you dismissed them earlier and want to see them again.
## Keybindings
| Key | Action |
|-----|--------|
| `Up` / `Down` / `Tab` | Navigate options |
| `Left` / `Right` | Change value |
- **Reset guides** — Re-enable all dismissed guide popups.
- **Demo on startup** — Load a rotating demo song on fresh startup.

14
docs/getting-started/samples.md
View File

@@ -1,6 +1,6 @@
# The Sample Browser
Press `Tab` on the sequencer grid to open the sample browser. It appears as a side panel showing a tree of all your sample directories and files. Press `Tab` again to close it. Before using the browser, you need to register at least one sample directory on the Engine page (`F6`). Cagire indexes audio files (wav, mp3, ogg, flac, aac, m4a) from all registered paths.
Press `Tab` on the sequencer grid to open the sample browser. It appears as a side panel showing a tree of all your sample directories and files. Press `Tab` again to close it. Before using the browser, you need to register at least one sample directory on the Engine page (`F6`). Cagire indexes audio files (`.wav`, `.mp3`, `.ogg`, `.flac`, `.aac`, `.m4a`) from all registered paths.
## Browsing
@@ -28,15 +28,3 @@ kick sound .
See the **Samples** section in the Audio Engine documentation for details on how sample playback works.
## Keybindings
| Key | Action |
|-----|--------|
| `Tab` | Open / close browser |
| `Up` / `Down` | Navigate |
| `Right` | Expand folder / play file |
| `Left` | Collapse folder |
| `Enter` | Play file |
| `PageUp` / `PageDown` | Fast scroll |
| `/` | Search |
| `Esc` | Clear search / close |

12
docs/getting-started/saving.md
View File

@@ -23,15 +23,3 @@ When saving, type a filename and press `Enter`. Parent directories are created a
When loading, browse to a `.cagire` file and press `Enter`. The project replaces the current session entirely.
## Keybindings
| Key | Action |
|-----|--------|
| `s` | Save (from any view) |
| `l` | Load (from any view) |
| `Up` / `Down` | Browse entries |
| `Right` | Enter directory |
| `Left` | Parent directory |
| `Tab` | Autocomplete path |
| `Enter` | Confirm |
| `Esc` | Cancel |

22
docs/getting-started/staging.md
View File

@@ -1,18 +1,27 @@
# Stage / Commit
Cagire requires you to `stage` changes you wish to make to the playback state and then `commit` it. It is way more simple than it seems. For instance, you mark pattern `04` and `05` to start playing, and _then_ you send the order to start the playback (`commit`). The same goes for stopping patterns. You mark which pattern to stop (`stage`) and then you give the order to stop them (`commit`). Why is staging useful? Here are some reasons why this design choice was made:
In Cagire, changes to playback happen in two steps. First you **stage**: you mark what you want to happen. Then you **commit**: you apply all staged changes at once. Nothing changes until you commit. It is simpler than it sounds.
- **To apply multiple changes**: Queue several patterns to start/stop, commit them together.
- **To get clean timing**: All changes happen on beat/bar boundaries.
- **To help with live performance**: Prepare the next section without affecting current playback.
Say you want patterns `04` and `05` to start playing together. You stage both (`p` on each), then commit (`c`). Both start at the same time. Want to stop them later? Stage them again, commit again. That's it.
This two-step process exists for good reasons:
- **Multiple changes at once**: queue several patterns to start/stop, commit them together.
- **Clean timing**: all changes land on beat or bar boundaries, never mid-step.
- **Safe preparation**: set up the next section while the current one keeps playing.
## Push changes, then apply
Staging is an essential feature to understand to be effective when doing live performances:
1. Open the **Patterns** view (`F2` or `Ctrl+Up` from sequencer)
2. Navigate to a pattern you wish to change/play
3. Press `p` to stage it. The pending change is going to be displayed:
- `+` (staged to play)
- `+` (staged to play)
- `-` (staged to stop)
- `m` (staged to mute)
- `s` (staged to solo)
- etc.
4. Repeat for other patterns you want to change
5. Press `c` to commit all changes
6. Or press `Esc` to cancel
@@ -24,7 +33,8 @@ You can also stage mute/solo changes:
- Press `Shift+m` to clear all mutes
- Press `Shift+x` to clear all solos
A pattern might not start immediately depending on the sync mode you have chosen. It might wait for the next beat/bar boundary.
A pattern might not start immediately depending on the sync mode you have chosen.
It might wait for the next beat/bar boundary.
## Status Indicators