# 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:

```forth
kick snd .              ;; play kick.wav
snare snd 0.5 gain .    ;; play snare at half volume
```

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

```forth
hats snd 0 n .          ;; play hats/closed.wav (index 0)
hats snd 1 n .          ;; play hats/open.wav (index 1)
hats snd 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"
```

```forth
kick snd .              ;; plays kick.wav
kick snd a bank .       ;; plays kick_a.wav
kick snd 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.