bass-foundry/docs/ballast/README.md

# Ballast

Ballast levels every note or switch-up of a bassline to one loudness, with a
single gain for each. Current version **0.1.0**.

Riddim and dubstep basslines change patch every few beats. Patches at the same
peak level still differ in how loud they sound, so each switch-up lands at a
different loudness and gets hand-set gain or clipping. A compressor would even
them out but also change their envelope and punch. Ballast measures each part's
loudness and gives the whole part one gain: inside a part nothing moves.

![Ballast](assets/editor.png)

## Install on Windows

Copy `Ballast.clap` into `C:\Program Files\Common Files\CLAP\`. In FL Studio
2024.1 or newer, open Options → Manage plugins, enable Verify plugins, and Find
installed plugins. Load Ballast in the mixer slot of the bass, after its sound
design. Keep the font license with redistributed packages.

## Work with it

1. Choose where a part starts with **Parts from**:
   - **Notes**: every note start, detected from the audio, or from MIDI notes
     sent to the effect (**Notes from**: AUDIO or MIDI).
   - **Grid**: every line of the host's beat grid, from 1 bar to 1/16. Use it
     when a switch-up changes the patch on the same note: the note tracker does
     not see a new note there.
2. Play the bassline and press **LEARN** just before the switch-up that sits
   right in the mix. Its loudness becomes the **Target**. You can also set
   Target by hand.
3. Watch the display: one bar per part with its loudness as it came in, and a
   mark where Ballast puts it. The marks line up on the target line.
4. Lower **Amount** to keep some of the differences: 50 % halves them.

The panel shows the spread of the last 16 parts, in and out: the standard
deviation of their loudness in dB. In the editor preview four patches spread
by 7 dB come out within 0.4 dB; the rest is what Range left.

Other controls:

- **Range** is the most boost or cut a part gets.
- **Measure from**: the measurement hears only what is above this frequency;
  the gain still applies to the whole signal. When Anvil makes the sub on the
  bus, set it to Anvil's Split: Anvil replaces the sub anyway, so only the part
  above it should decide the gain.
- **Gate** is the note-start threshold (Audio). A part quieter than the gate
  keeps the last part's gain instead of being lifted, so rests and tails are
  not pulled up.
- **Output** trims the level; **Bypass** crossfades to the delayed input.

### How it measures

A part's loudness is its K-weighted level (ITU-R BS.1770, the weighting behind
LUFS) over its first 100 ms, or over all of it when it is shorter. The level is
counted in 10 ms blocks, and blocks 20 dB under the part's loudest block are
left out. Each part is weighted from rest, as if it played alone, so the last
part's level does not ring into it.

The gain glides to the new value over 5 ms and is in place on the part's first
sample, so the attack already has the new level. Later parts of a long note keep
that gain: Ballast does not follow the note's envelope.

## Timing and limits

Latency is the note tracker's lookahead (about 67 ms), the 100 ms measuring
window and the 5 ms glide, about 172 ms in all, reported to the host for delay
compensation. That is too much for playing live through Ballast: add it for the
mix.

In Grid mode the grid follows the host's beat position while it plays and runs
on at the last tempo when it stops. A note start found by a change of pitch can
come about 20 ms early, inside the gap before the note;
the block gate keeps that gap out of the measurement. Two parts closer than
10 ms are merged.

Ballast decides from the first 100 ms of a part. A patch that swells after
that, or a note whose loudness depends on what plays with it, is levelled by
its start only. It levels loudness, not brightness: two patches at the same
loudness can still differ in tone.