bass-foundry/docs/ideas.md

# Plugin ideas

A running list of plugin ideas for riddim, dubstep and bass-music sound design.
Each entry names the problem first. Entries are grouped as released or idea. Names follow the metalwork theme of the Bass Foundry suite.

## Problems seen in bass-music production

1. Every bass patch brings its own sub level and phase, so the weight of a drop
   jumps between switch-ups, and layered patches cancel in the sub.
2. Patches at the same peak level still differ in perceived loudness and
   brightness. The usual fix is hand-set gain or clipping per patch.
3. Resampling is repetitive: bounce, chop, trim, declick, normalise, find the
   root key, name, save, load into a sampler.
4. Writing wobbles: LFO shapes are drawn, synced, copied and edited for every
   variation. Triplet and dotted patterns plus per-note changes take long.
5. Unison, OTT and stereo distortion widen the mids. Parts disappear in mono or
   on club systems.
6. Kick and bass clash. Sidechain helps, but the sub phase at each note start
   changes how the kick hits.
7. Distortion chains build up harsh resonances. (Patina covers this.)
8. Comparing a drop with a reference: the difference is usually sub/mid balance
   over time, which generic meters do not show clearly.
9. Fixed-frequency tools act differently on every note. An EQ boost at 300 Hz
   lifts the 4th harmonic of one note and the 7th of another; a distortion with
   a fixed tone filter sounds brighter on low notes than on high notes.
10. Layered bass patches partly cancel in the mids, not only in the sub.
11. Texture makes a riddim patch: grit, rattle, metal, vowel, noise. It takes long
    chains (distortion, comb, formant, OTT, resample, repeat), and the result
    changes from note to note.
12. Grit and tone cannot be shaped separately. More distortion for more grit
    also changes the body, the level and the low end.
13. Resampled textures sound printed: a loop of one moment, with no movement
    inside the note.
14. Texture changes inside a note (the switch-up within one held note) need
    automation lanes or chopping.
15. There is no meter for texture. Two switch-ups can sound "the same" without
    a clear reason, and generic analysers show only level and spectrum.
16. OTT and multiband compression use fixed band edges, so the same setting
    squashes different harmonics on every note.
17. Riddim masters rely on clipping. A clipper that also clips the sub turns
    the low end into distortion.
18. Resampled basslines have no MIDI, so tools that need the notes have nothing
    to follow.

## Signal flow and suite audit (2026-11)

How the released plugins fit into one production:

```text
WRITE      Rivet (motif → storyboard) ──MIDI──► synth
DESIGN     synth → Lathe → Temper → Knurl → Patina
RESAMPLE   Crucible (capture → slice → export) ──► sampler / wavetable synth ──► DESIGN
LAYER      layer A + layer B → Weld (mids) → bass bus → Anvil (sub)
MIX        gap: loudness, clipping, OTT, mono check, kick against sub, reference
```

Writing and sound design are covered. Mixing and mastering have only Anvil and
Patina. Findings from the audit:

- **Latency adds up.** A full chain (Knurl 71 + Temper 67 + Lathe 67 + Patina
  about 45 + Anvil 80 ms) is about 330 ms. FL Studio compensates it for
  playback, but a chain this long cannot be played live.
- **MIDI mode keeps the lookahead.** `Tracker::latency()` depends on the pitch
  range only. With MIDI as the source, the note is known at its attack, so the
  lookahead could be close to zero. This needs a latency change at runtime,
  which must be checked in FL Studio first.
- **Knurl confuses every tracker after it.** Measured: Knurl output fed into
  `TrackerConfig::BASS`. From C2 (65 Hz) upwards, Double, Fry (the default),
  Gallop and Triple make the next tracker read the note one octave (Triple:
  an octave and a fifth) too low for about 85 % of the note. Below C2 the false
  sub-octave is under 30 Hz, out of range, so low notes are safe. Level and time
  jitter also cause 5–25 false note starts per second. Anvil on the bus after
  Knurl then plays the sub an octave low and restarts its phase. Until there is
  a shared tracker: put Knurl after the other tracked plugins, and use MIDI as
  the source for any tracked plugin after Knurl. See [Signal chain](chain.md).
- **Each tracked plugin needs its own MIDI route.** Four plugins in MIDI mode
  are four FL routing setups.
- **Weld and delay compensation are untested together.** If the main layer's
  chain has more latency than the sidechain layer and FL does not compensate
  the sidechain route, the main layer arrives late, which an allpass cannot
  fix. Put Weld after every plugin with latency on that track.
- **Crucible lost takes on reload.** Takes are not saved with the project.
  Fixed: Keep takes writes every capture's loop to disk at once.
- **Settings handling differs.** Patina has presets and A/B; the others do not.
  Lathe's drawn gains and Knurl's drawn pattern cannot be automated.

## Released

### Anvil — sub anchor (problems 1, 6)

Replaces the band below a split frequency with a clean mono sine that follows
the bass pitch, at one level and one start phase for every note. Pitch comes
from detection with 80 ms lookahead or from MIDI. See [Anvil](anvil/README.md).

### Crucible — resampler (problem 3)

Records the input continuously. One click captures the last bars on the host
bar grid, slices on a grid or on hits, trims, declicks, normalises, detects the
root key and exports labelled WAVs, a full loop and an optional Serum/Vital
wavetable. See [Crucible](crucible/README.md).

### Lathe — harmonic EQ (problem 9)

EQ bands placed on harmonics 1–32 of the detected note instead of fixed
frequencies. "+4 dB on harmonic 3, −6 dB on harmonic 7" sounds the same on F1
and on C2. Odd/even balance, tilt over harmonic number, and a Focus control
that lifts or cuts everything between the harmonics. Uses Anvil's pitch
tracker, or MIDI. See [Lathe](lathe/README.md).

### Temper — note-tracked distortion (problem 9)

A waveshaper whose tone filters before and after the shaper follow the note, so
every note distorts with the same character and the same harmonic content.
Input level is normalised before the shaper, so drive does not depend on how
loud the patch is, and the output is gain-matched. Oversampled to keep aliasing
(which is never harmonic) out. See [Temper](temper/README.md).

### Weld — layer phase alignment (problem 10)

Takes a second bass layer through the sidechain. It fits polarity and a chain
of up to four allpass sections to the measured cross-spectrum (no added
delay), so the layers sum instead of cancel. A display shows how much level the
cancellation cost and how much Weld recovered. Anvil solves the sub band; Weld
solves the mids. See [Weld](weld/README.md).

### Knurl — cycle texture (problems 11, 13)

Follows the played note and treats every cycle on its own: a repeating level
pattern (in-tune subharmonics), random level and timing per cycle, and a noise
burst per cycle tuned to the note. Amounts are counted in cycles, so the texture
is the same on every note. Slow per-harmonic drift is postponed. See
[Knurl](knurl/README.md).

### Planish — harmonic OTT (problem 16)

Upward and downward compression in four bands whose edges are harmonic numbers
of the tracked note (default 1, 2–4, 5–16, 17 and up), so the same setting
squashes the same harmonics on every note. Each band's level is measured over
one period of the note, so heavy settings do not ripple at f0. Built, not yet
released. See [Planish](planish/README.md).

## Next for released plugins

- **Anvil**: *Kick lock*: the kick through the sidechain ducks the sub on each
  hit and restarts its phase so kick and sub sum (problem 6). A sub shape from
  sine to rounded triangle. A note attack counted in cycles.
- **Lathe**: A/B gain snapshots with one automatable Morph parameter. A
  keyswitch note that selects the drawn shape (EQ switch-ups without
  automation). A dynamic mode per harmonic.
- **Temper**: a harmonic split: harmonics 1–2 clean, 3 and up driven. More than
  one Push band. A bias that changes per cycle from Knurl's cycle clock.
- **Knurl**: velocity or note selects the pattern. Stereo grit above a split
  only. Drift (planned for 0.3).
- **Patina**: Tone guard (done, unreleased). MIDI as its pitch source. M/S
  processing.
- **Weld**: alignment slots per note or per switch-up. The External
  sender/receiver fallback if FL's sidechain does not arrive.
- **Crucible**: a switch-up slicer that cuts where the spectrum changes, for
  legato basses. Optional retune of slices to one root. Reopening saved takes
  from the `takes` folder in the take list.
- **Rivet**: more than two sound roles, one per switch-up patch. Its MIDI
  output as the one note source for the tracked plugins.
- **Suite**: presets and A/B in `common-ui` for every plugin.

## Ideas

### Order

1. Small fixes from the audit. Done: chain-order guide
   ([Signal chain](chain.md)), Crucible Keep takes. Open: Weld test with delay
   compensation (in FL), MIDI mode without lookahead (needs an FL check that a
   latency change at runtime is accepted).
2. Patina pitch-aware mode. Done as **Tone guard** (unreleased): bumps that
   follow the note are protected, bumps fixed in Hz are cut. Measured first:
   Patina already cut fixed formants on every note, but it also cut a boosted
   harmonic as hard (5.7 dB), at a position that moved with the note.
   Open: MIDI as the pitch source.
3. Planish (done, unreleased), then Quench and Ballast: they fill the mix and
   master gap.
4. Forge, when enough modules exist.
5. Assay, one plugin for the display-only ideas.
6. Texture plugins (Anneal, Swarf, Etch, Bellows) and the note-keyed sequencer.

Merges: Gauge, Loupe and Drop compare share one analysis core and one display,
so they become one plugin, **Assay**. The wobble sequencer, Damascus and Chase
are all "step grid, note selects the pattern", so they become one sequencer.

### Forge — one tracked channel strip (problems 9, 11, latency)

One tracker, one latency, and Lathe, Temper, Knurl and later Anneal as modules
in an order you choose. It removes the stacked lookahead, the trackers that
disagree (Knurl's sub-octave cannot confuse a tracker that reads the input
before Knurl) and the repeated MIDI routing. The standalone plugins stay.
Sharing one tracker between separate `.clap` files would need named shared
memory across DLLs, which is fragile; one strip is simpler.

### Quench — sub-safe clipper (problem 17)

Quenching hardens hot metal in one fast step. Quench clips only above a split
frequency and adds the clean sub back with its own headroom, so the master can
be clipped hard without distorting the low end. Pairs with Anvil's split.

### Scribe — audio to MIDI (problem 18)

A scribe marks lines on metal. Scribe runs the note tracker on a bass and
outputs MIDI notes and a `.mid` file. A resample from Crucible then gets its
notes back, so the other plugins can use MIDI as their source.

### Bevel — mono-safe harmonic widener (problem 5)

Pans harmonics of the note alternately (for example odd left, even right) with
complementary filters, so the mono sum stays flat. Pairs with Assay.

### Peen — note-start transient shaper

Peening hardens a surface with hammer blows. Attack and sustain shaping on
every note start, with times counted in cycles, so each switch-up gets the same
punch on every note. Could become part of Ballast.

### Ballast — switch-up loudness leveller (problem 2)

Measures short-term perceived loudness per note or per switch-up against a
target or a reference patch and adjusts gain only, so each switch-up lands at
the same loudness without compression changing its character. Earlier working
name: Hit Leveler. Pairs with Anvil: Anvil levels the sub, Ballast the whole
patch.

### Bellows — pitch-tracked resonator

A comb or Karplus-style resonator tuned to the detected note. It turns noise,
distortion or drums into pitched metallic tone that is in key on every note.
Damping, harmonic spread, single or multiple combs.

### Gauge — low-end mono check (problem 5)

Shows phase correlation and mono-sum loss per band and per note in the bass
range, and marks the notes where widening breaks the mono sum. Optional fixes:
mono below a chosen frequency and phase rotation on the mids. Display-first, so
it is a small build. Earlier working name: Bass Mono Check.

### Wobble sequencer (problem 4)

Step patterns for volume, filter, formant and pitch with triplet and dotted
grids built in. Each MIDI note selects a different pattern, so a switch-up is a
different note in the piano roll. ShaperBox overlaps, but it has no note-keyed
patterns. No name yet.

### Drop compare (problem 8)

Loudness-matched A/B of a drop against a reference, with sub, low-mid, mid and
high energy over time: for example "your sub is 3 dB under the reference in
bars 2–4". No name yet.

## Texture ideas

These ideas target problems 11–15; Knurl, the first of them, is released above.
Most of them reuse the note tracker in
`common-dsp`, so a texture setting means the same thing on every note, the same
way Lathe and Temper work.

### Anneal — tone and grit split (problem 12)

Annealing changes how a metal behaves without changing its shape. Anneal
splits the signal into three parts: the harmonic part (energy on the harmonics
of the tracked note), the residual noise and grit between the harmonics, and
the transients. Each part has a level fader, a drive and a tilt.

- Turn the grit up 6 dB and keep the body and the sub unchanged.
- Take all the grit out of a layer and leave a clean tone for further design.
- Listen to each part solo, or send the grit to a second output for its own
  chain.

DSP: an STFT with the note tracker; harmonic masks at k·f0, with a width that
follows the pitch; a transient mask from spectral flux. Latency is one FFT
frame. The display shows the three parts in different colours on Lathe's
harmonic strip.

### Swarf — in-key granular shavings (problems 11, 13)

Swarf is the shavings that machining leaves. Swarf records the bass itself and
sprays short grains of it back as a layer. Grain lengths are whole pitch
periods, and every grain is retuned to the note playing now, so the shredded
layer stays in key across a riddim line. Controls are density, spray (position
spread back in time), grain size in cycles, reverse probability, and a
harmonic-only filter for the layer. It is useful for the "shredded metal" top
layer, and works on a resample from Crucible as well.

### Etch — texture imprint (problem 11)

Etching transfers a pattern onto metal with acid. Etch takes a texture source
through the sidechain or from a loaded sample (a metal scrape, a vocal, a field
recording) and imprints its fine structure on the bass. The bass keeps its
pitch and its harmonic levels; between and on the harmonics, the source's
noise, roughness and movement come through. A "harmonic lock" mode samples the
source's spectral envelope only at the bass harmonics, so the imprint is always
in key. It differs from a vocoder: a vocoder transfers the envelope, and Etch
transfers the surface.

### Chase — talking formants that hit harmonics (problems 11, 14)

Chasing shapes metal by hammering it from the front. Chase is a formant filter
with a 2D vowel pad (a, e, i, o, u, plus "yoi" and "wub" shapes). You draw a
path over the pad and sync it to the tempo, or let each MIDI note select a path.
The formants stay in Hz, so a vowel stays a vowel on every note. A **snap**
control moves each resonant peak onto the nearest harmonic of the tracked
note, so a narrow formant never falls into the gap between two harmonics and
vanishes on some notes. Gain-matched, so a vowel change does not change the
level.

### Damascus — texture step sequencer (problem 14)

Damascus steel is folded from layers into a visible pattern. Damascus holds up
to four texture slots (for example a formant, a comb, a sample-rate reducer and
a Knurl-type rattle) and a tempo-synced step grid that chooses a slot, or a mix
of two, per step. Steps have their own crossfade time, so changes can be hard
cuts or smears. Each slot is gain-matched, so the steps change texture and not
level. Each MIDI note can select its own pattern, which is a texture switch-up
inside one held note. This overlaps with the wobble sequencer above; both could
become one plugin.

### Loupe — texture meter (problem 15)

A loupe is the lens used to inspect engraving. Loupe measures texture per note
over time:

- roughness and fluctuation strength (psychoacoustic models);
- harmonic-to-noise ratio, which shows how gritty a sound is;
- inharmonicity, which shows how metallic a sound is;
- brightness relative to the note (harmonic centroid, not centroid in Hz).

It places every switch-up of a drop as a point on a texture map. Two patches
that sit on the same point are why a drop sounds repetitive. A reference track
can be loaded for comparison. Display only, so it is a small build, and it fits
with Gauge and Drop compare.