Cagire/docs/staging.md

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:

• 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.

Staging is an essential feature to understand to be effective when doing live performances:

1. Open the Patterns view (Ctrl+Up from sequencer)
2. Navigate to a pattern you wish to change/play
3. Press Space to stage it. The pending change is going to be displayed:
   • + (staged to play)
   • - (staged to stop)
4. Repeat for other patterns you want to change
5. Press c to commit all changes
6. Or press Esc to cancel

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

Indicator	Meaning
>	Currently playing
+	Staged to play
-	Staged to stop

A pattern can show both > (playing) and - (staged to stop).

Quantization

Committed changes don't execute immediately. They wait for a quantization boundary:

Setting	Behavior
Immediate	Next sequencer tick
Beat	Next beat
1 Bar	Next bar (default)
2/4/8 Bars	Next 2, 4, or 8-bar boundary

Edit quantization in pattern properties (press e on a pattern).

Sync Mode

When a pattern starts, its playback position depends on sync mode:

• Reset: Always start at step 0
• Phase-Lock: Start at the current beat-aligned position (stays in sync with other patterns)