# Busbar

> *One machine. Every channel.*

**Busbar** is a saturation plugin where every instance shares **one single
analog machine**. The supply is common: what goes through one channel is felt by
all the others.

Drop it on as many tracks as you like. They do not become N independent
saturators — they become N channels of the same machine, drawing on the same
power rail and drifting on the same clock.

**VST3 · CLAP · AU — macOS, Windows, Linux.**

## How it works

Two forces are shared by every instance.

- **Supply sag.** Each channel publishes what it *draws*. The sum makes one rail
  sag, and the saturation ceiling of every channel comes down **together**. That
  is the glue of a real console desk, and it is the one thing a per-track plugin
  cannot do however good it is.
- **Drift.** One time base for everyone, so the channels undulate in step
  instead of smearing against each other as N decorrelated flutters.

Out of that comes the gesture that defines the plugin: what a channel **draws**
is published to everyone, while how much it **takes** is its own. A channel with
**ANCHOR** engaged keeps loading the supply — so it still makes everyone else
dip — but does not dip itself.

> *The lead vocal must not duck. But it must make everything else duck.*

**Six characters**, each shaped from measurements of a real hardware unit:
`bus` (dual-stage valve & FET bus), `valve` (discrete triode stage), `silicon`
(transistor saturator), **`reel`** (transformer tape stage — the default),
`iron` (passive iron & valve), `oxide` (tape bias & oxide). The character is
**global to the machine**; only the quantity is per track.

> We do not name the hardware units. Busbar has no endorsement from, or
> affiliation with, any hardware maker, and naming their products would imply
> one.

📖 **[Full user manual](docs/Busbar-Manual.md)** — installation, every control,
and how to use the machine on a real mix.

## Installation

- **macOS** — open the `.dmg`, run the `.pkg`. Signed and notarized; the
  publisher shows as *Tony Cuny*, the legal name behind Xeni-Audio.
- **Windows** — run the installer, or unpack the ZIP into
  `C:\Program Files\Common Files\VST3` and `…\CLAP\Busbar`.
- **Linux** — copy `Busbar.vst3` to `~/.vst3/` and `Busbar.clap` to `~/.clap/`.

## What Busbar does not claim to be

Busbar is **not** a faithful emulation, and that is worth saying plainly.

The shared sag does not exist on any hardware: an outboard manufacturer
*designs* power supplies against exactly that, and two measured units showed
0.000 dB of inter-channel coupling. The drift, at the setting that sounds best,
is around a hundred times the specification of a tape machine.

It is a deliberate effect — and that is also what makes it hard to copy, for
exactly the same reason.

## Known issues

- **Reaper on Windows, VST3: the window does not resize.** Reaper's VST3 host
  ignores `plugFrame->resizeView()`. Use the **CLAP** build there — same plugin,
  same shared machine, and the window resizes normally.
- **All instances report "1 instance on the rail".** They are not seeing each
  other, which happens if the plugin was updated while a host was still running
  with the previous version loaded. Quit every host and reopen: Busbar reclaims a
  stale shared machine on its own once nothing is using it.
- **Bitwig: the transport does not move while a plugin window is open.** A
  Bitwig behaviour, not a Busbar one — it affects every plugin.
- **Linux, focus-follows-mouse:** keep the pointer over the plugin window while
  typing a track name. Busbar only takes keyboard focus during actual text entry
  and gives it back on the way out.

---

## Developing

```sh
nix develop                                    # devShell complet
cmake -B build -G Ninja && cmake --build build
ctest --test-dir build --output-on-failure
./tests/run-chunk-harness.sh
pluginval --strictness-level 8 ~/.vst3/Busbar.vst3
clap-validator validate ~/.clap/Busbar.clap
./tests/reset-machine.sh          # 🔴 APRÈS les validateurs, avant tout test manuel
python tests/dsp_parity/compare.py --seconds 12
./build/busbar_ui_render p.png --scene default # ⭐ rendre et REGARDER
./scripts/build-manual-pdf.sh                  # docs/Busbar-Manual.pdf
```

Le shell apporte la chaîne complète : CMake/Ninja/clang, Boost, GL + X11,
**pluginval** et **clap-validator**, le cross MinGW pour Windows
(`nix develop .#windows`), NSIS, pandoc, et un Python numpy/scipy/soundfile pour
la **parité DSP contre le prototype**.

- ⭐ **`docs/IMPLEMENTATION-PLAN.md`** — le plan, les phases, les décisions
- 🔴 **`docs/PITFALLS-INHERITED.md`** — les bugs déjà payés sur les cinq produits
  en vente, à re-scanner **dans le code** à la fin de chaque phase
- 🎨 **`docs/ui/busbar-ui.html`** — la maquette validée (ouvrir dans un navigateur)
- 🍎 **`docs/macos-signing-notarization.md`** — signature + notarisation
- 📖 **`docs/Busbar-Manual.md`** — le manuel utilisateur (le `.pdf` est **commité** :
  l'installeur NSIS le référence, et sans lui `makensis` échoue)

⚠️ **`iPlug2/` est un lien symbolique partagé par les cinq produits en vente.**
Ne jamais le modifier depuis ce dépôt. `vendor/pugl`, lui, est local.

---

*Busbar — Xeni-Audio. Copyright 2026.*
