mindball/README.md

# Mindball

A tiny, minimal stereo delay plugin with a no-frills UI. Feedback echoes, ping-pong
and inverting modes, tempo-synced delay time, and an auto-panner — all wrapped in a
clean, resizable interface with 20 factory presets.

Built with [JUCE](https://juce.com) 8.0.9 and CMake, available as a VST3, Audio Unit
and standalone app.

---

## Features

- **Stereo delay engine** with independent left/right delay lines (up to 16 seconds)
- **Smooth delay-time changes** — a two-head crossfade avoids the pitch-bend
  artifacts of a gliding read head
- **Feedback loop filtering** — separate low-cut and high-cut filters on the repeats
- **Four modes**: Normal, Invert, Ping-Pong, SuperPong
- **Tempo sync** — 12 note divisions (1/16 to 8 bars), tempo read from the host
- **Double, Center and Auto-Pan** options, with a syncable panning LFO
- **Per-channel level meters** with peak hold
- **20 factory presets** and a UI scale control (50%–300%)
- **No external runtime dependencies** — no GTK, no libcurl

---

## Controls

### Knobs

| Control   | Range            | Default | Description                              |
| --------- | ---------------- | ------- | ---------------------------------------- |
| FEEDBACK  | 0 – 95%          | 35%     | Amount of the delayed signal fed back    |
| LO-CUT    | 20 – 4000 Hz     | 100 Hz  | High-pass filter on the delay repeats    |
| HI-CUT    | 500 – 18000 Hz   | 12 kHz  | Low-pass filter on the delay repeats     |
| TIME      | 10 – 3000 ms     | 300 ms  | Delay time (or note division when synced)|
| PAN       | 0 – 100%         | 100%    | Auto-pan depth (when AUTO-PAN is on)     |
| DRY/WET   | 0 – 100%         | 40%     | Mix between the dry and delayed signal   |

### Toggles

| Toggle     | Description                                          |
| ---------- | ---------------------------------------------------- |
| ON         | Bypass the effect (inverted indicator)               |
| MODE       | Cycles Normal → Invert → Ping-Pong → SuperPong       |
| DOUBLE     | Adds a second tap at twice the delay time            |
| SYNC       | Syncs TIME to the host tempo instead of milliseconds |
| AUTO-PAN   | Applies a stereo LFO to the wet signal               |
| CENTER     | Collapses ping-pong/superpong output to the center   |

### Meters

DRY and WET level meters show both channels with peak hold. A red segment marks the
current peak.

### Top bar

- **Preset menu** — pick one of the 20 factory presets; the active preset is ticked
- **UI scale menu** — resize the interface from 50% to 300%

---

## Presets

Default, Slapback, Analog Echo, Tape Echo, Dub Delay, Ping-Pong, Wide Ping-Pong,
SuperPong, Sync 1/16, Sync 1/8, Sync 1/4, Sync 1/2, Sync 3/4, Invert, Hall Echo,
Whale Song, Filtered Space, Auto-Pan Delay, Centered Pong, Clean Echo.

The currently loaded preset is detected from the live parameter values, so if you
tweak a knob the preset name updates to the closest match.

---

## Building

### Prerequisites

- CMake 3.22 or newer
- A C++20 compiler
- JUCE 8.0.9 is fetched automatically from GitHub — you only need a network
  connection (or `git`) on the first configure. To build against a local checkout
  instead, pass `-DJUCE_ROOT=/path/to/juce`.

### macOS

```sh
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --target Mindball_VST3 Mindball_AU Mindball_Standalone
```

Requires the Xcode command line tools. Built plugins are copied to
`~/Library/Audio/Plug-Ins/VST3` and `~/Library/Audio/Plug-Ins/Components`.

### Linux

```sh
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --target Mindball_VST3 Mindball_Standalone
```

The configure step checks for the required system headers (X11, FreeType, FontConfig
and ALSA) and fails with a clear message naming the missing packages:

```sh
sudo apt-get install pkg-config libx11-dev libfreetype-dev libfontconfig-dev libasound2-dev
```

Mindball deliberately does **not** require the GTK/webkit2gtk or libcurl development
packages. libcurl support is disabled in `juce_core`, and the GTK-dependent
`juce_gui_extra` module is not linked.

### Build formats

The default formats are `AU VST3 Standalone`. Override with the `MINDBALL_FORMATS`
cache variable, e.g.:

```sh
cmake -B build -DMINDBALL_FORMATS="VST3 LV2"
```

---

## Project layout

```
CMakeLists.txt                  Build configuration (JUCE, formats, Linux checks)
Source/
  PluginProcessor.cpp/.h        Audio processing and the parameter tree
  PluginEditor.cpp/.h           UI: knobs, toggles, meters, presets, scale
  DelayEngine.h                 Stereo delay engine (filters, modes, crossfades)
  DelayLine.h                   Circular buffer delay line
  BuildInfo.h.in                Template for generated build info header
```

---

## License

See the source files. This project uses the JUCE framework, which is subject to its
own [licensing terms](https://juce.com/legal/juce-8-licence/).