bass-foundry/docs/crucible/README.md

# Crucible

Crucible melts the bars you just played into ready-to-use samples. Current version
**0.4.0**.

Resampling is the core loop of riddim sound design: bounce, open in Edison, chop,
trim, declick, normalise, find the key, name, save, load into a sampler. Crucible
does all of it from one button. It always records its input, so the take you
liked is already there when you press **Capture**.

![Crucible](assets/editor.png)

## Install on Windows

Copy `Crucible.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 Crucible in a mixer slot at the end of the chain you want
to resample. Keep the font license with redistributed packages.

## Work with it

1. Play the pattern or song section.
2. Choose **Bars** (1–16) and press **Capture**. Crucible takes the newest complete
   bars on FL's bar grid. With the transport stopped, it takes the newest audio at
   the last known tempo instead.
3. Choose how to slice: **Grid** (1/4, 1/8, 1/16, 1/8T, 1/16T) or **Transients**
   with a Sensitivity. Double-click the waveform to add a cut, right-click to remove
   the nearest one.
4. Click a slice to hear it. Untick **Export** to leave it out.
5. Press **Export**.

Each export creates a folder named after the date, time and tempo, holding:

- `loop.wav`: the whole take, for Slicex or Edison;
- `s01_F1.wav`, `s02_G#1.wav`, …: one file per slice, named by its detected root
  note. The root is also stored in the file's sampler chunk. A slice gets a
  note only when most of it holds one clear pitch; a growl, a slide or noise is
  saved as `s03.wav`, because a wrong note name is worse than none. Choose the
  song's **Key** to spell the names in it: in F minor a slice is `s02_Ab1.wav`,
  not `s02_G#1.wav`. Without a key, names use sharps;
- `wavetable.wav` when **Wavetable** is on: up to 256 single-cycle frames of 2048
  samples from the selected slice. Each frame starts on a rising zero crossing, so
  frames morph without phase jumps. Serum reads the frame size from the file; in
  Vital, import it as a wavetable with 2048-sample frames.

Every slice is cleaned on export: **Trim silence** removes leading silence below
−60 dBFS, **Declick** fades both ends (default 2 ms), **Normalize** peaks it at
−0.3 dBFS. Files are 32-bit float WAV at the session rate.

Add the export folder to FL's browser once (Options → File settings → Browser extra
search folders). New exports then appear there and can be dragged into channels,
the playlist or Edison. **Open folder** shows the latest export in Explorer.

## Timing and limits

Crucible adds no latency and passes audio through untouched. Auditioned slices are
mixed into its output only while they play. The history holds 72 s, enough for
16 bars at 60 BPM. The newest eight takes stay in memory until the plugin is
removed; they are not saved with the project. With **Keep takes** on (the
default), every capture's loop is also written at once to
`takes/<date>_<time>_<tempo>bpm_<bars>bars.wav` in the export folder, so a reload
or a crash loses nothing. Existing files are never overwritten.

Bar alignment follows the host's song position and time signature. Root notes are
detected between 35 Hz and 1 kHz. The pitch is read at up to 12 points across
each slice after its attack; at least three reads in five must be clear and on
the same note. Unpitched slices, such as drums
or noise, get no note in their name. Transient slicing finds hits that rise out of quieter
audio; for legato basses, slice on the grid.