horizont/README.md

# Horizont

A stereo algorithmic reverb audio plugin (VST3 / AU) for macOS, built with
JUCE and C++17.

It pairs a Schroeder/Moorer-style reverb core - a diffusion allpass section and
a bank of parallel damped combs whose gains are derived from an RT60 time - with
a **feedback pitch-shifting loop**: each pass through the reverb is recirculated
through a granular crossfade pitch shifter, so the tail climbs or descends in
pitch on every echo. The UI is a dark teal hardware-rack style skin with
skeuomorphic rotary knobs and a live wet-spectrum analyser.

## Screenshot
![Horizont](horizontshot.png)

## Features

- 9 fully automatable, host-saveable parameters in an `AudioProcessorValueTreeState`
- Stable, self-scaling reverb: comb gains are computed from RT60 so the loop
  never diverges, and every delay length / filter / window scales with sample rate
- Per-sample parameter smoothing (`juce::SmoothedValue`) - no clicks, no allocation
  in the audio callback
- Granular pitch shifter with seamless crossfade; bypasses transparently at 0 semitones
- Feedback loop routing the wet signal back through the pitch shifter and diffusers
- Dark themed GUI: skeuomorphic knobs, glass panel highlights, animated spectrum display
- Factory presets exposed through the host's program mechanism
- VST3 and Audio Unit formats; plain `make` build + install on macOS

## Controls

| Control    | Range           | Default | Notes                                      |
|------------|-----------------|---------|--------------------------------------------|
| Low Cut    | 20 – 500 Hz     | 40 Hz   | Input high-pass filter                     |
| High Cut   | 800 Hz – 20 kHz | 14 kHz  | Input low-pass filter                      |
| Decay      | 0.2 – 10 s      | 3.5 s   | RT60 of the comb bank                      |
| Size       | 0.4 – 2.0       | 1.0     | Room size scaling of comb delays           |
| Diffusion  | 0 – 1           | 0.6     | Input allpass diffusion depth              |
| Brightness | 0 – 1           | 0.75    | High-frequency damping of the tail         |
| Feedback   | 0 – 1           | 0.6     | Recirculation through the pitch shifter    |
| Pitch      | -12 – +12 st    | 0 st    | Pitch shift applied per feedback pass      |
| Dry/Wet    | 0 – 1           | 0.35    | Dry / wet mix                              |

## DSP architecture

```
 input -> [low-cut HP] -> [high-cut LP] -----> feedback node
                                                 |      ^
                                        (pitch shifter) |
                                                 |  wet tail
                                    [2 cascaded allpass diffusers]
                                                 |
                                  8 parallel combs (damping + RT60 gain)
                                                 |
                                        wet sum -> dry/wet mix -> output
```

- **Diffusers** shape the early reflections before the diffuse tail.
- **Combs** each use a different prime-based delay length; their loop gains are
  `10^(-3 * delaySeconds / decaySeconds)` so the composite RT60 tracks *Decay*.
- **Pitch shifter** runs on the wet feedback path. Grains are windowed and
  crossfaded; the read point moves at a rate proportional to the shift, with
  sample-rate-scaled window lengths and a 32-sample crossfade.
- The wet output passes through a DC blocker, and the whole engine is
  sample-rate independent.

## Requirements

- macOS with Xcode Command Line Tools (`xcode-select --install`)
- CMake >= 3.22
- `git`, `make`, `codesign` (all ship with the command line tools)

## Build & install

From the repository root:

```
make            # fetches JUCE 8.0.15 into ./JUCE, configures and builds
make install    # installs into ~/Library/Audio/Plug-Ins/VST3 and .../Components
```

`make` is fully self-contained: if `./JUCE` is missing it clones a pinned,
stable JUCE release into the current directory, then builds the plugin. The
resulting bundles land in `build/Horizont_artefacts/Release/`.

Other targets:

```
make uninstall  # remove installed copies
make clean      # delete the build directory
make help       # list targets
```

If you prefer to manage JUCE yourself, either check it out as `./JUCE` next to
this repo, or point CMake at it with `-DJUCE_ROOT=/path/to/JUCE`.

> **Note:** JUCE 9 / `master` refactored the LookAndFeel API and is not yet
> supported - a JUCE 8.0.x release tag is required.

After installing, ask your DAW / Audio Unit host to rescan plug-ins (or run
`auval` to validate the component). Installed bundles are ad-hoc code-signed.

## Project layout

```
CMakeLists.txt          build configuration
Makefile                one-command build/install on macOS
Source/
  PluginProcessor.*     processor, APVTS, state save/load, program (preset) handling
  PluginEditor.*        layout, panels, preset combo box
  HorizontEngine.*        the reverb DSP core
  PitchShifter.*        granular crossfade pitch shifter
  HorizontLookAndFeel.*   dark teal theme, skeuomorphic rotary knobs
  Knob.*                knob component (slider + caption + value readout)
  SpectrumDisplay.*     animated wet-spectrum analyser
  Presets.h             factory presets
```

## License

This project is released under the GPL v3 - the standard license for JUCE
projects that use the open-source JUCE distribution. You may additionally use
it under the terms of a JUCE commercial license if you hold one.