# Measure, don't guess

Every sound decision in FaustWave can be a number before it is an opinion. The Analysis tools record what reaches the master, or read a sample from the store, and return one report: loudness, crest, energy per band, where the root sits, mono-compatibility, onsets with a click score, single-sample steps, and a tonality verdict. Optionally the numbers are placed against a **reference window** — what professional material measures — and each window comes back as *inside / below / above*.

This book exists because of one project. *Around the World* (the bundled trap demo) was built in a day where every "the bass is too thick", "something clicks", "these hats sound like an alarm clock" was answered by a measurement first. Three findings the ear had misread and the numbers caught:

- a click on every second 808 note that was a **runtime** bug, not the patch (half a block of exact zeros at each note start);
- a "feel" problem that was the ducker taking -8 dB exactly where the 808 notes landed;
- a sample pack whose 36 "hats" were all a 7 kHz line (one FFT bin carried 10 % of the energy; a real 909 hat measures 2–3 %).

## Where it lives

The **Analysis** pane sits in two shipped views. In **Build** it is under the Inspector — the knob you turn and the number it changes in one column. In **Signal** it is the audio half of "is something wrong" beside the MIDI half (Devices, MIDI Monitor, Routing). It is not in Perform: a set is played, not measured.

```yaml
actions:
  - action_id: view.open
    input: { view: build }
    label: "▶ Open the Build view (Analysis under the Inspector)"
  - action_id: surface.open
    input: { surface: analysis }
    label: "▶ Or put the Analysis pane on the current view"
```

The pane has three controls: a **take picker** (every recording, newest first), **Measure** (analyse the picked take), and **Capture** (record the next bars and analyse them). The **vs trap-808** chip toggles the reference window.

## The four actions

| Action | What it measures | When |
|---|---|---|
| `analysis.capture { bars, seconds, reference }` | Records the master for `bars` (default 8, at the live BPM; ceiling 60 s), stops, returns the report **and** the new recording id. Start the transport first — a silent take returns an error. | The loop while you tweak: change a knob, capture four bars, compare. |
| `analysis.recording { recording_id, reference }` | A finished take from the Recorder library (`recordings.list`), the whole file, offline. Leading and trailing silence trimmed; the first 120 s measured. | A take you already have. |
| `analysis.sample { sha256, reference }` | A sample from the store (`samples.list`). PCM WAV only. | **Before** wiring a sample into a kit — the tonality verdict is the alarm-clock detector. |
| `analysis.references` | The reference profiles: id, provenance, every window with its question, lo/hi and unit. | Read once, so "inside" means something when you quote it. |

All four return the same report shape; the next chapter reads it line by line.

```yaml
actions:
  - action_id: analysis.references
    input: {}
    label: "▶ What does the trap-808 window contain?"
  - action_id: transport.play
    input: {}
    label: "▶ 1. Play"
  - action_id: analysis.capture
    input: { bars: 4, reference: trap-808 }
    label: "▶ 2. Capture four bars and judge them against the pro window"
```

> 🟦 **THE REFERENCE IS A WINDOW, NOT A LAW.** `trap-808` is what five commercial 808 loops measured — an 808 *alone*, on B0. The Around-the-World bass sat inside every window at B0 and sounded wrong ("too thick, the tone is too low"); an octave up it reads *above* on the fundamental band and is right. A verdict tells you where you are relative to a reference, and the ear decides whether that is where you want to be.