terion/README.md

# Terion

Real-time stereo analyzer and mid-side vector scope audio plugin for macOS.

Terion visualizes the stereo field of any audio signal using a mid/side coordinate system. The X axis represents the Side (difference) signal and the Y axis represents the Mid (sum) signal, plotted as an XY vectorscope with a configurable phosphor-style fading trail. It is an analysis-only plugin - audio passes through unmodified.

## Features

- **Mid/Side vectorscope** - XY plot with phase-mapped color (correlated content in cyan/blue, out-of-phase content shifting toward red)
- **Phosphor trail** - configurable fade time from 0.1 to 10 seconds for persistent visual history
- **Real-time stereo metrics** - correlation, stereo width, mid/side levels, balance, phase angle, crest factor, and peak/RMS levels
- **Freeze** - capture and hold the current display for inspection
- **Resizable UI** - scales from 420×420 up to 1200×1200, with preset scale factors (100/125/150/200/300%)
- **Custom arc knobs** - clean rotary controls with teal arc indicators
- **VST3 and Audio Unit** formats

## Requirements

- macOS
- CMake 3.22 or later
- C++17 compiler (Xcode command line tools)
- JUCE framework (cloned automatically by `make juce`, or use an existing `~/JUCE` install)

## Building

```sh
make all        # configure + build (Release)
make install    # build, codesign, un-quarantine, install to ~/Library/Audio/Plug-Ins
```

### Makefile targets

| Target | Description |
|---|---|
| `make all` | Configure and build |
| `make juce` | Clone JUCE into `third_party/JUCE` (skipped if `~/JUCE` exists) |
| `make configure` | Run CMake configure only |
| `make build` | Compile only |
| `make install` | Build, codesign (ad-hoc), strip quarantine, install to user plug-in dirs |
| `make sign` | Codesign installed bundles |
| `make unquarantine` | Strip Gatekeeper quarantine xattrs from installed bundles |
| `make uninstall` | Remove installed VST3 and AU bundles |
| `make clean` | Remove `build/` |
| `make deepclean` | Remove `build/`, `third_party/`, and stray artefacts |

### Variables

| Variable | Default | Description |
|---|---|---|
| `BUILD_DIR` | `build` | CMake build directory |
| `CONFIG` | `Release` | Build configuration |
| `JOBS` | `$(ncpu)` | Parallel compilation jobs |
| `CODESIGN_ID` | *(empty = ad-hoc)* | Codesign identity string |
| `JUCE_DIR` | auto-detected | Override JUCE source location |

## Parameters

| Parameter | Range | Description |
|---|---|---|
| Fade | 0.1 – 10 s | Trail persistence time |
| Sensitivity | -12 – +24 dB | Input gain for M/S decode |
| Dot size | 0.5 – 3.0 px | Size of each plotted point |
| Smoothing | 0 – 0.99 | One-pole smoothing on M/S signals |
| Freeze | on/off | Stop capturing new points |

## Project structure

```
terion/
├── CMakeLists.txt          # JUCE plugin build configuration
├── Makefile                # Build/install/sign wrapper
├── Source/
│   ├── PluginProcessor.*   # Audio engine: M/S decode, ring buffer, metrics
│   ├── PluginEditor.*      # UI layout, knobs, freeze, scale, footer
│   ├── VectorScope.*       # XY scope rendering, trail, legends, overlay
│   ├── ArcKnob.*           # Custom rotary arc slider
│   └── Version.h.in        # Git hash/timestamp template
└── third_party/JUCE/       # JUCE framework (auto-cloned, gitignored)
```