# The Audio Engine

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

Two columns show available output and input devices. Press `Left` or `Right` to switch between them. Browse with `Up`/`Down` and press `Enter` to select a device. Use `PageUp`/`PageDown` to scroll long device lists. Press `D` to refresh the device list if you plugged something in after launching Cagire.

## Settings

Four audio parameters are adjustable with `Left`/`Right`:

| Setting | Range | Description |
|---------|-------|-------------|
| Channels | 1–64 | Number of output channels |
| Buffer | 64–4096 | Audio buffer size in bytes |
| Voices | 1–128 | Maximum polyphony (simultaneous sounds) |
| Nudge | -100 to +100 ms | Timing offset to compensate for latency |

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

## Audio Controls

A few keys work from anywhere on the Engine page:

- `h` — Hush. Silence all audio immediately.
- `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.

## Monitoring

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.
