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.

Writing Scripts

Scripts are written in Forth. Type words and numbers separated by spaces. The simplest script that makes sound is:

;; a very simple sound
sine sound .

Add parameters before words to modify them:

;; the same sound with more parameters
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:

;; the same sound on multiple lines
c4 note
0.75 decay
sine sound
0.4 verb
.

Saving

Esc — Save, compile, and close the editor.
Ctrl+E — Save and compile without closing (evaluate in place).

When you save, the script is compiled and sent to the sequencer. If there's an error, a message flashes briefly at the bottom of the screen. Esc has layered behavior: if text is selected, it cancels the selection first. If completions are showing, it dismisses them. Otherwise it saves and closes.

Completion

As you type, the editor suggests matching Forth words. The completion popup appears once you've typed two or more characters of a word, showing candidates that match your input along with their stack signature and description.

Tab — Accept the selected suggestion.
Ctrl+N / Ctrl+P — Navigate between suggestions.
Esc — Dismiss the list.

Completion helps you discover words without memorizing them all. Type a few letters and browse what's available. For example, typing ver will suggest verb (reverb), typing chor will show chorus-related words.

Sample Finder

Press Ctrl+B to open the sample finder. This provides fuzzy search over your loaded sample folders, making it easy to insert sample names without remembering their exact spelling.

Type to filter by name
Tab or Enter — Insert the selected sample name.
Ctrl+N / Ctrl+P — Navigate matches.
Esc — Dismiss.

Search

Press Ctrl+F to open the search bar. Type your query, then navigate matches:

Ctrl+N — Jump to next match.
Ctrl+P — Jump to previous match.
Enter — Confirm and close search.
Esc — Cancel search.

Debugging

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

3.4 KiB Raw Blame History