bass-foundry/docs/knurl/README.md

# Knurl

Knurl gives every cycle of the note its own level, timing and grit. Current
version **0.2.0**.

Knurling presses a ridged pattern into metal. Riddim and dubstep basses get their
character the same way, from surface texture: rattle, growl, fry, grit. Usually
that texture comes from long chains of distortion, comb filters, formants and
resampling, and it changes from note to note. Knurl works on single cycles of the
wave instead. It follows the played note and treats each cycle on its own, and
every amount is counted in cycles, not in Hz or tempo. So the texture has the
same grain on F1 and on C2.

![Knurl](assets/editor.png)

## Install on Windows

Copy `Knurl.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 Knurl in a mixer slot of the bass. Keep the font license with
redistributed packages.

## Work with it

1. Play the bass. The note readout shows what Knurl tracks; the scope overlays
   the last eight cycles of the output, so the texture is visible cycle by cycle.
2. Choose a **Pattern**. The pattern sets the level of each cycle and repeats:
   - **Double** (0, −9 dB): every second cycle quieter. This makes a sub-octave
     growl, exactly in tune, about 8 dB under the fundamental.
   - **Triple** (0, −12, −12 dB): a growl an octave and a fifth down.
   - **Fry** (0, −14, −5, −14 dB, the default): an uneven vocal-fry rattle.
   - **Gallop** and **Stutter**: rhythmic patterns over six and eight cycles.
   - **Off**: every cycle at full level.
3. Draw your own pattern on the bars: drag a bar to set the level of that cycle,
   double-click to reset it. **Steps** sets the length (1–16 cycles).
4. Add surface:
   - **Level** gives every cycle a random level (standard deviation in dB).
   - **Time** moves every cycle a little in time (percent of a period): rattle
     and scrape.
   - **Grit** adds a short noise burst inside every cycle. **Tone** sets its
     lowest frequency in harmonics of the note, **Position** where in the cycle
     it sits, and **Length** how long it is. The squares under the pattern bars
     switch the burst per step.
5. **Edge** sets how soft each step change is. Low values are sharper and
   buzzier; high values smoother.

**Random**: **Same every note** (default) restarts every random sequence at each
note, so identical notes sound identical, which keeps a riddim line tight.
**Free** lets the sequences run on, so every note differs.

**Mix** blends with the delayed dry signal; **Output** trims the level.

### Pitch from MIDI

For basses whose fundamental is unclear (heavy FM, formant or noise patches),
select **MIDI** and route the bass's MIDI notes to Knurl. In FL Studio, set the
bass channel's MIDI output port and Knurl's input port to the same number.
**Gate** sets the input level that counts as a note in AUDIO mode; **Snap to
semitone** rounds the detected pitch (turn it off for slides).

## Timing and limits

Knurl delays the audio by about 71 ms: 67 ms of pitch-detection lookahead plus
4 ms of room for the timing jitter. The delay is reported to the host for delay
compensation, so the cycle clock knows every note before its attack leaves the
plugin. The cycle clock restarts at every note start, so the pattern always
begins with step 1 on the attack. Pitch range is 30–500 Hz, one note at a time.
Between notes the effects fade out over 20 ms, so tails stay clean.

Knurl works per cycle of the tracked pitch; it does not look for cycle borders in
the waveform. With a stable pitch that is the same thing. With heavy pitch
modulation inside a note the pattern follows the tracked pitch, which can lag a
fast bend. Both channels get the same treatment, so the effect is mono-safe.

Knurl's patterns put a real sub-octave into the signal. A pitch detector after
Knurl (Anvil, Lathe or Temper in Audio mode) then reads notes from C2 upwards
an octave too low. Put Knurl after the other tracked plugins, or use MIDI as
their source. See [Signal chain](../chain.md).

## How it works

A note tracker (shared with Anvil, Lathe and Temper) detects pitch and note
starts ahead of the delayed audio. A cycle clock starts at 0 on every note and
advances by f0 / sample rate. Each cycle gets its step gain and its random level
and time offset from a hash of the cycle number, so the result is deterministic.
Step changes are raised-cosine crossfades over the last **Edge** of a cycle;
level jitter crossfades over half a cycle and time jitter over the whole cycle,
read from the delay line with cubic interpolation. The grit is white noise
through a state-variable highpass at **Tone** × f0, shaped by a sin² window and
scaled to the input level. There is no nonlinearity, so no oversampling is
needed.