Cagire/docs/engine/settings.md

Settings

The audio engine can be configured through the Engine page or via command-line arguments. Settings are saved and restored between sessions.

Engine Page

Press Ctrl+Right until you reach the Engine page. Here you can see the engine status and adjust settings.

Display

The right side of the page shows visualizations:

• Scope: oscilloscope showing the audio waveform
• Spectrum: 32-band frequency analyzer

Settings

Navigate with arrow keys, adjust values with left/right:

• Output Device: where sound goes (speakers, headphones, interface).
• Input Device: what audio input source to use (microphone, line-in, etc.).
• Channels: number of output channels (2 for stereo).
• Buffer Size: audio buffer in samples (64-4096).
• Max Voices: polyphony limit (1-128, default 32).

Buffer Size

Smaller buffers mean lower latency but higher CPU load. Larger buffers are safer but feel sluggish.

Buffer	Latency at 44.1kHz
64	~1.5ms
128	~3ms
256	~6ms
512	~12ms
1024	~23ms

Start with 512. Lower it if you need tighter timing. Raise it if you hear glitches.

Samples

The engine indexes audio files from your sample directories. Add directories with A, remove with D. The sample count shows how many files are indexed.

Supported Formats

• WAV (.wav)
• MP3 (.mp3)
• OGG Vorbis (.ogg)
• FLAC (.flac)
• AIFF (.aiff, .aif)
• AAC (.aac)
• M4A (.m4a)

Lazy Loading

Samples are not loaded into memory at startup. They are decoded on demand when first played. This means you can have thousands of samples indexed without using much RAM until you actually use them.

Folder Organization

The scanner looks at top-level files and one level of subdirectories:

samples/
├── kick.wav           -> "kick"
├── snare.wav          -> "snare"
├── hats/
│   ├── closed.wav     -> "hats" n 0
│   ├── open.wav       -> "hats" n 1
│   └── pedal.wav      -> "hats" n 2
└── breaks/
    ├── amen.wav       -> "breaks" n 0
    └── think.wav      -> "breaks" n 1

Top-level files are named by their filename (without extension). Files inside folders are sorted alphabetically and numbered starting from 0.

Playing Samples

Reference samples by name:

kick s .              ;; play kick.wav
snare s 0.5 gain .    ;; play snare at half volume

For samples in folders, use n to select which one:

hats s 0 n .          ;; play hats/closed.wav (index 0)
hats s 1 n .          ;; play hats/open.wav (index 1)
hats s 2 n .          ;; play hats/pedal.wav (index 2)

The index wraps around. If you have 3 samples and request 5 n, you get index 2 (because 5 % 3 = 2).

Sample Variations with Bank

The bank parameter lets you organize variations:

samples/
├── kick.wav          -> default
├── kick_a.wav        -> bank "a"
├── kick_b.wav        -> bank "b"
└── kick_hard.wav     -> bank "hard"

kick s .              ;; plays kick.wav
kick s a bank .       ;; plays kick_a.wav
kick s hard bank .    ;; plays kick_hard.wav

If the banked version does not exist, it falls back to the default.

Troubleshooting

• No sound: Check output device selection.

  • Try the test sound (t) on Engine page).

• Glitches/crackling: Increase buffer size, restart the Engine.

• High CPU: Reduce max voices. Disable scope/spectrum. Increase buffer size.

• Samples not found: Check sample directories on Engine page. Filenames are case-sensitive on some systems.