beamgrid/README.md

# BEAMGRID

BEAMGRID is a JUCE-based VST3 / AU spectrum analyzer with a fully black UI, teal accents, and a configurable display.
For more information about the JUCE C++ framework, see: https://juce.com/

## Screenshots
![Screenshot 01](beamgrid01.png)
![Screenshot 01](beamgrid02.png)

## Features

- **Three display modes** (`MODE` knob):
  - **BARS** - classic log-spaced spectrum bars with peak-hold caps.
  - **SPECTRUM** - a smooth (quadratic-spline) waveform trace of the spectrum, with a matching smooth peak-hold wave. Use the `SMOOTH` knob to go from raw/edgy to heavily smoothed.
  - **LED** - an LED-meter style view (`LEDS` knob sets LEDs per bar).
- **Frequency range** fixed to **20 Hz – 20 kHz**.
- **HUE** knob rotates the hue of every UI accent (knob arcs, peaks, title) without altering the underlying data.
- **UI scaling** dropdown (75% – 300%) in the top-right.
- Per-project **size & scale persistence** (stored in the plugin state).

## Parameters

| Knob        | Range            | Description                                   |
|-------------|------------------|-----------------------------------------------|
| PEAK GRACE  | 0 – 2000 ms      | Grace period before a peak-hold marker decays |
| PEAK FALLOFF| 0 – 1            | Peak-hold decay rate                          |
| BAR FALLOFF | 0 – 1            | Spectrum bar release speed                    |
| BARS        | 8 - 128          | Number of spectrum bands (snaps)              |
| HUE         | 0 – 1            | Rotates the UI accent hue (0.5 = no change)   |
| MODE        | 1 / 2 / 3        | BARS / SPECTRUM / LED                         |
| LEDS        | 4 – 48           | LEDs per bar in LED mode                      |
| SMOOTH      | 0 – 1            | Waveform smoothing amount in SPECTRUM mode    |
| GRID        | 0 – 1            | Grid (frequency/level) visibility / brightness|
| ZOOM        | 98.0% – 102.0%   | Grid zoom about the plot centre               |
| GRID FADE   | 0 – 1            | Fades inner grid lines; outer border stays    |
| CURVING     | 0 – 1            | LED corner radius (0 = square, 1 = rounded)   |
| TILT        | -1 – 1           | Spectral tilt: + boosts highs / cuts lows, - does the reverse (0 = flat) |
| BOOST       | 0.75 – 2.5       | Global display level multiplier (1.0 = unity)                            |
| 3D          | 0 – 1            | Pseudo-3D bevel/shading on bars, LEDs, peaks and curve (0 = flat)        |
| G-ANG       | -180 – 180       | Gradient angle for the 3D shading (0 = top-lit, +/-90 = side-lit)        |

## Building

Requires [CMake](https://cmake.org/) (>= 3.22) and a JUCE-supported
toolchain (Xcode / clang on macOS, GCC / Clang on Linux, etc.). JUCE is
fetched automatically by CMake.

### macOS

```sh
cmake -B build -G Ninja
cmake --build build --config Release
```

### Linux

Install the JUCE system dependencies, then build:

```sh
# Debian / Ubuntu (DEB)
sudo apt-get install -y libasound2-dev libfreetype6-dev libx11-dev \
  libxcomposite-dev libxcursor-dev libxext-dev libxinerama-dev libxrandr-dev

# Fedora (RPM)
sudo dnf install -y alsa-lib-devel freetype-devel libX11-devel \
  libXcomposite-devel libXcursor-devel libXext-devel libXinerama-devel libXrandr-devel

# Arch Linux / Artix
sudo pacman -S alsa-lib freetype2 libx11 libxcomposite libxcursor \
  libxext libxinerama libxrandr
```

> **Note on `gtk/gtk.h` / `fatal error: gtk/gtk.h: No such file or directory`**
>
> BEAMGRID links `juce_gui_extra`, which on Linux unconditionally compiles a
> WebKit/GTK section (see `juce_gui_extra.cpp`). Even if the GTK *runtime* is
> installed, the build needs the **development** headers plus WebKit2GTK:
>
> ```sh
> # Debian / Ubuntu
> sudo apt-get install -y libgtk-3-dev libwebkit2gtk-4.1-dev
> # Fedora
> sudo dnf install -y gtk3-devel webkit2gtk3-devel
> # Arch
> sudo pacman -S gtk3 webkit2gtk-4.1
> ```
>
> BEAMGRID does **not** use a web browser, so `JUCE_WEB_BROWSER` is disabled in
> `CMakeLists.txt`. With that, the GTK/WebKit dev packages above are **not**
> required to build — the error disappears even if you skip them.

Build BEAMGRID:

```sh
cmake -B build -G Ninja
cmake --build build --config Release
```

The built plugins are installed to your system plugin folders:

- `build/BEAMGRID_artefacts/Release/VST3/BEAMGRID.vst3`
- `build/BEAMGRID_artefacts/Release/AU/BEAMGRID.component` (macOS only)

Then rescan plugins in your DAW. BEAMGRID should show up.

### Windows

It *might* work on Windows, too, but I have not tested that, and I have zero intentions to do so. Good luck, nevertheless.

## Project layout

```
Source/
  PluginProcessor.cpp/.h   Audio processor + parameter layout
  PluginEditor.cpp/.h      Editor UI, knobs, layout
  Analyser.h/.cpp          FFT analysis, banding, peak-hold
  AnalyserComponent.h      Drawing (BARS / SPECTRUM / LED)
  BeamgridLookAndFeel.h    Black/teal styling, hue rotation, rotary drawing
```

## License

See the repository license file.