# Palora preset authoring — recipe for AI assistants

`preset-spec: 2026-09-17.15` — the version of this specification.

> Self-contained brief. Paste this entire file into the AI's context, then ask for a preset. The AI emits a complete `.palora` JSON file plus a short design rationale.

> **⚠️ READ TO THE END BEFORE AUTHORING — a partial read produces broken presets.** This document has 11 sections (§0–§10) and ends with **"## 10. Final instructions for the AI."** If you have not reached §10, you have seen only part of the spec — keep reading, or request the rest of the file, before emitting anything. Do **not** assume a section is missing or "removed" because you didn't see it on a first pass; §5.2b (`melody`) and §9 (banks) sit past the midpoint and are exactly the parts a truncated read skips. The single most common failure is authoring a `melody` block from a partial read and nesting it **inside** `params` — it is a sibling of `params`, never a key within it (§5.2b).

> **Asked for multiple presets?** If the user wants a "pack", "bank", "batch", or "N presets" (e.g. *"a preset pack of 10"*), do **NOT** emit N separate `.palora` files — emit **ONE** `bank` document with a `presets[]` array (see **§9**). One paste, and all presets land together as a navigable pack.

> **Critical engine facts:** Mod matrix is 11 × 24 (slot 22 = Vibrato depth; slot 23 = AmpRelease; slot 24 = TransPunch). **Init ships ONE default routing — `ModWheel → Vibrato` (`modAmt_6_22` = 50%)** — so the mod wheel adds vibrato on every preset out of the box; set it to 0 to suppress wheel-vibrato on a patch. Envelope and Filter envelope have wide common-synth ranges (Envelope Attack/Decay/Release 32 s; Filter Attack/Release 32 s, Filter Decay 16 s; both Sustains 0-100%). Both are ADSR (no Hold stage; `ampCurve` < 50 gives the "stay high then fall" decay-hold character). Filter has a full ADSR. **Sub + Click go through the Filter** — Osc A+B + Sub + Click are mixed before the filter, so filter cutoff shapes the sub buzz and click transient too. `clickReso` is fixed and not exposed in the plugin — do not emit it.

---

## 0. What this doc is for

Palora is a subtractive synthesizer plugin. Its presets are JSON files in the v1.0 `.palora` format — the `{format, version, plugin, meta, params}` shape described below, and the same format the plugin's own factory presets use. This doc gives an AI everything needed to author one — without access to the plugin's source code, internal Claude skills, or the plugin UI.

The receiving AI's job is to:

1. Pick a category (or use the one the user requests).
2. Pick a name + 1-sentence character description + 3-6 tags.
3. Pick parameter values that produce the intended character.
4. Pick 3-6 modulation-matrix routings that give it life and expression.
5. Output one complete `.palora` JSON file plus 2-3 sentences explaining the design intent (what character, what the macro knob does, what makes it musically usable).

A human reviewer drops the file into the factory-presets folder, loads it in the plugin, and audits it by ear. Many round-trips happen — your job is to get the **first draft good**, not perfect.

**Your full output procedure + don't-list is §10, at the end of this document.** Everything between here and there exists to make that procedure produce good first drafts.

---

## 1. Instrument overview

Palora is a **versatile subtractive synth** — plucks, basses, leads, pads, keys, stabs, bells, drones, and evolving textures — with a signature click-transient + transient-shaper attack engine that most soft-synths lack. There is no global genre target: the user can make whatever they want with it. Each category recipe in §6 carries its own craft context (what makes a deep-house bass read as one, what makes a pad bloom, etc.).

**Architecture:**

- **Two oscillators** (A + B) with shape morph (saw → triangle → sine), independent octave/cents/pulse.
- **One sub-oscillator** locked at MIDI pitch × 0.5 (always one octave below the played note, **independent of `oscOctave`**).
- **Click transient engine** (sub / FM / noise body).
- **4-pole ladder low-pass filter** with envelope, velocity, key-tracking.
- **Envelope** (ADSR amplitude envelope with decay-shape control: attack, decay, curve, sustain, release — param IDs `amp*`; no Hold stage — `ampCurve` < 50 covers that character).
- **Transient shaper** (post-filter dynamic shaping: attack/sustain/sense).
- **FX chain**: Drive (4 types) → Chorus → Delay (synced) → Reverb (4 types) → master HP/LP.
- **Modulation matrix**: 11 sources × 24 destinations = 264 cells. Each cell is signed % (-100..+100). Most destinations are *additive* against the knob (slot adds an offset). Ten destinations are *knob-relative* — `|slot|=100%` sweeps the destination knob's full range across its skew curve (OscBPulseWidth, OscBPitch, AmpAttack, FilterCutoff, FilterAttack, AmpDecay, TransAttack, DelayFeedback, AmpRelease, TransPunch — see §4.2).
- **Mod sources** (UI matrix labels): LFO1, LFO2, LFO3, ENV1 (per-note ADSR), MCR1, MCR2 (macros), KT (KeyTrack), RND (per-voice S&H at noteOn), MW (ModWheel), Vel (Velocity), AT (Aftertouch). *In the routing-notation examples below, macros are written `Macro1`/`Macro2` and the random source `Random` for readability — same sources; the labels are display-only and don't change the `modAmt_*` data keys.*

**Default note about polyphony:** `mono = false` (Poly, 8 voices), glide = 0. Don't override unless the preset's character needs it. Set `mono: true` for legato basses/leads.

---

## 2. Output specification — what the AI must hand back

Two artifacts:

### 2A. A complete `.palora` JSON file

- UTF-8, valid JSON, no comments, no trailing commas.
- Wrapper: `{"format":"preset","version":"1.0","plugin":"palora","meta":{...},"params":{...}}`.
- `meta` has `name`, `category`, `author`, `description`, `tags`.
- `params` is **sparse** — only include parameters whose value should differ from Init/default. The loader resets every unmentioned param to its Init value, so omitting a param means "use the Init value here." **Never emit an `apvts` block — it is not a key in this format and the importer rejects it.**
- All choice parameters use **semantic strings** (`"Plate"`, `"Square"`, `"1/8"`) or, where indicated, integers (`oscOctave`, `unisonVoices`).
- **All human-readable text is English — always, regardless of the prompt's language.** `meta.name`, `meta.description`, and `meta.tags` must be written in English even when you are prompted in another language (Danish, German, etc.). The shipped library is English; a non-English prompt should still produce English names/descriptions/tags. (Parameter keys and choice strings are fixed English tokens and are never translated.) You may write the §2B rationale in the prompt's language, but the preset content itself stays English.

> **Structure decides — `format` is a label.** The importer classifies by **shape**: a document with a top-level **`params`** object is a single preset; a document with a **`presets[]` array** is a bank/pack (see §9). Always include `version:"1.0"` and `plugin:"palora"` as shown — the importer rejects a file whose `plugin` isn't `palora`. Get the **shape** right: single = `{meta, params}`, bank = `{meta, presets:[{meta, params}, …]}`. Do **not** stamp `created`/`modified` — those are library-owned (the plugin stamps `created` on import; an AI doesn't know real time).

### 2B. A short design rationale (2-3 sentences, plain prose)

Cover:
- The intended character / mood / use-case.
- What the macro knob is for ("Macro1 opens the filter and adds drive — the 'open up' macro").
- One thing about the modulation strategy ("LFO1 → Filter Cutoff at 0.25 Hz gives a slow breathing motion under sustained notes").

Don't write design philosophy paragraphs. The rationale is for the human reviewer to triage quickly.

---

## 3. Full parameter reference

All parameters live in one flat namespace. Range/default/unit columns below are **the plugin's live values**. The plugin auto-fills defaults for any param you omit.

### 3.1 Oscillator A

| ID | Type | Range | Default | Notes |
|---|---|---|---|---|
| `oscShape` | Float | 0..100 | 0 | Saw → Triangle → Sine morph (0 = saw, 50 = triangle, 100 = sine). For a square, use Pulse (`oscAPulse` true, Width 50). |
| `oscOctave` | Int (choice) | -2, -1, 0, +1, +2 | 0 | Register shift. Stay 0 for Bass (sub anchors). |
| `oscAFine` | Float | -50..50 | 0 | Cents. Cap ≤10 unless deliberately wide. |
| `unisonVoices` | Int (choice) | 1, 2, 3, 4 | 1 | More voices = stereo width. |
| `unisonDetune` | Float | 0..80 | 3 | Total unison spread in cents (outermost voices sit at ±half this). 3 = subtle; 40+ = properly wide supersaw. |
| `unisonSpread` | Float | 0..100 | 70 | Stereo spread for unison voices. |
| `analogDrift` | Float | 0..100 | 0 | Random per-voice pitch drift (analog feel). |
| `oscSat` | Float | 0..100 | 0 | Pre-filter osc saturation. 0-20 clean / 50-70 character grit. |

### 3.2 Oscillator B (silent unless `oscABMix > 0`)

| ID | Type | Range | Default | Notes |
|---|---|---|---|---|
| `oscABMix` | Float | 0..100 | 0 | A↔B blend. 30-80 = standard mix. 0 = A only. |
| `oscBShape` | Float | 0..100 | 0 | Same morph as A. |
| `oscBPulseWidth` | Float | 5..95 | 50 | Only audible if `oscBPulse = true`. |
| `oscBPwmDepth` | Float | 0..100 | 0 | Pulse-width modulation depth. |
| `oscBOctave` | Int (choice) | -2, -1, 0, +1, +2 | 0 | Register shift relative to A. |
| `oscBSemi` | Int | -12..12 | 0 | **AVOID non-zero** for melodic presets — fixed semitone clashes with chord/scale playing. Reserve for niche FX/drone. |
| `oscBFine` | Float | -50..50 | 0 | Sub-semitone detune. **WARNING — beat trap:** if `oscBOctave = 0` and `oscBFine` ∈ [1, 7], A+B beat at sub-audio rates and read as amplitude pumping. Use 0, or jump to 12+ cents. |
| `oscBPhase` | Float | 0..100 | 0 | Where B's cycle starts on each note. **Ignored while `oscBSync` is on** — B then starts in step with A. |
| `oscBSync` | Bool | — | false | Hard-sync B to A (lead character). Click-free onset: B starts in step with A, so no note begins with a reset jump. |
| `oscBPulse` | Bool | — | false | Engage pulse waveform on B. |

### 3.3 Oscillator A — Pulse + Phase

| ID | Type | Range | Default | Notes |
|---|---|---|---|---|
| `oscAPulse` | Bool | — | false | Engage pulse waveform on A. |
| `oscAPulseWidth` | Float | 5..95 | 50 | |
| `oscAPwmDepth` | Float | 0..100 | 0 | |
| `oscAPhase` | Float | 0..100 | 0 | |

### 3.4 Sub oscillator

| ID | Type | Range | Default | Notes |
|---|---|---|---|---|
| `subLevel` | Float | 0..100 | 0 | Bass: 50-65. Pluck: 5-30. Lead: ≤14. |
| `subShape` | Choice | "Sine", "Tri", "Square" | "Sine" | Vary across batch. |

### 3.5 Click transient (the first ~10ms of every note)

| ID | Type | Range | Default | Notes |
|---|---|---|---|---|
| `clickLevel` | Float | 0..100 | 0 | 50-70 when click is featured character. |
| `clickTone` | Float | 200..8000 | 1264.9111 | The lowpass corner in **Hz**, exponential (200 x 40^t). 730-1520 = warm/round; 1830+ = bright/glassy only. |
| `clickDecay` | Float | 2..20 | 8 | 8-18ms = "thunk/body"; <8 = "tick". |
| `clickBody` | Choice | "Sub", "FM", "Noise" | "Noise" | Vary across batch — Sub = woody, FM = metallic, Noise = breath/air. |

> **`clickReso` is not AI-controllable.** It is fixed and not exposed in the plugin. **Do not emit `clickReso` in new presets** — let the default apply.

### 3.6 Filter (4-pole LP, dual topology)

Filter has a full ADSR envelope. Defaults: `filterAttack` 0 (1 ms cosine floor), `filterSustain` 0 (decay falls to zero), `filterRelease` 0 (no release stage runs).

**Two topologies selectable via `filterTopology` Choice — see §3.6.1 for character guidance.**

| ID | Type | Range | Default | Notes |
|---|---|---|---|---|
| `filterTopology` | Choice | "Analog", "Modern" | "Analog" | See §3.6.1. Analog = warm, nonlinear (adds harmonics). Modern = clean, near-linear, transparent; cutoff + resonance follow the envelope and matrix exactly. |
| `filterCutoff` | Float | 20..20000 (Hz) | 20000 | See category recipes for typical zones. |
| `filterResonance` | Float | 0..100 | 0 | High res with rich body = singing. On **Analog**, resonance is capped at 95% — the top 5% of the knob does nothing. On **Modern**, no cap — full 0..100 reaches self-oscillation cleanly. |
| `filterEnvAmount` | Float | 0..100 | 0 | Filter envelope depth. **This is the mechanism for envelope-driven cutoff — see §4.5d.** The FilterEnvAmount matrix destination (dst 12) is clamped to this same 0..100 and **cannot** drive it negative; for an inverted sweep use `ENV1 → FilterCutoff` with a negative amount. |
| `filterAttack` | Float | 0..32000 (ms) | 0 (=1ms floor) | Filter env attack. 0 = 1 ms cosine floor. Skew 0.3 (most usable values in lower third). |
| `filterEnvDecay` | Float | 20..16000 (ms) | 180 | Filter envelope decay. Skew 0.3, so the 20–250 ms zone most presets live in sits in the bottom ~28% of the control. Decay is the ONLY stage that moves the cutoff *while the key is held* — Attack opens, Release closes after note-off — so it is what a sustained sweep needs. Above ~1 s is a sustained sweep rather than a pluck contour; read the topology rule below before going there. |
| `filterSustain` | Float | 0..100 | 0 | Filter env sustain. 0 = decay falls to zero. >0 = filter holds open under held notes — load-bearing for pads and evolving textures. |
| `filterRelease` | Float | 0..32000 (ms) | 0 | Filter env release. 0 = no release stage. >0 = filter tail after note-off — useful for pads, leads with sustained closes. Skew 0.3. |
| `filterTilt` | Bool | — | false | +6dB low-shelf @ 250Hz post-filter. |
| `filterBassComp` | Bool | — | false | +6dB low-shelf @ 350Hz pre-filter (bass-loss compensation). |

#### 3.6.1 Choosing topology: Analog vs Modern

Palora's Filter has two filter topologies behind the `filterTopology` Choice. They are NOT clean-vs-distorted variants — they are two genuinely different filter characters with structural implications for how the rest of the engine interacts with them.

**Headline rule.** Filter Decay × topology is the dominant interaction.

> ⚠ **Every "long"/"short" threshold below is ABSOLUTE MILLISECONDS.** Read the figures
> literally. `filterEnvDecay` spans 20–16000 ms, so a threshold expressed as a proportion of
> the control would land near 1600 ms — far outside the pluck contour these rules describe.

- **Long `filterEnvDecay` (≈300–1000 ms) → Analog territory.** Tanh saturation inside the feedback loop compresses the resonance ring musically; long ring-out gives "bite" and character.
- **Near-zero `filterEnvDecay` (≲100 ms) → Modern territory.** Clean attack, sharp peak, no aftertaste.
- **Long `filterEnvDecay` on Modern → "oil drum" effect.** The clean ladder feedback rings unmusically because nothing internal limits it. **Avoid.**

**Sustained sweeps — `filterEnvDecay` above ~1000 ms.** A different gesture from the pluck
contour the rules above describe: a slow downward sweep across a *held* note, for pads,
drones and long basses. On a swelling pad it is what gives the sound somewhere to go *after*
the attack has risen. **Listen before shipping one — this is not a setting to dial by number.**

**Three parameters set the gesture, and getting one wrong wastes the other two.**

1. **The travel is set by Env Amount AND Sustain together — not by Decay.** Decay only sets
   how *long* the move takes; how *far* it moves is

       travel (octaves) = EnvAmount/100 × 4 × (1 − filterSustain/100)

   `filterSustain` 65 with Env Amount 40 travels **0.56 oct** and then holds there for the
   rest of the note — barely a timbre change, however long the decay. Drop the sustain to 25
   and the same patch travels **1.20 oct**. **Long decay + high sustain is the classic
   mistake:** it sounds like nothing is happening, because almost nothing is.
2. **Put the base cutoff LOW.** The sweep *lands* on the base cutoff, and a ladder is close to
   transparent in its top octaves — so a sweep that ends at 2.5 kHz has spent its travel where
   the filter is barely acting. A low base is what makes the downward move read as the note
   closing rather than merely dimming.
3. **The amp envelope must still be sounding when the filter arrives.** With the default
   300 ms `ampDecay` and 0 sustain, the note is long gone before a multi-second filter decay
   has moved at all. Pair a long filter decay with a real `ampSustain` and a long `ampDecay`.

⚠ Use **Analog**, not Modern. The "oil drum" failure above gets *worse* with length — a
multi-second decay on Modern with real resonance is that same unmusical ring, stretched out.

Counter-intuitive but empirically grounded: for **bite / pluck / attack** character, the default move is **Analog with longer Decay** — NOT Modern, despite Modern's sharper theoretical resonance peak. Modern is the "clean-and-short" choice, not the "snappy attack" choice.

**Practical decision tree:**
1. Does the preset want long Filter Decay (resonance that rings)? → **Analog.** Don't even consider Modern.
2. Does the preset want a clean, transparent character AND can keep Filter Decay short (**≤ ~100 ms**, absolute)? → **Modern.**
3. Moderate Decay AND no strong clean-vs-warm intent? → **Analog** (safer default).

---

**Analog** (the default):
- Saturates inside the resonance loop, so it adds harmonics that grow with input level and resonance
- Self-compresses at high resonance — peaks stay lower than Modern's (about -12 dB against -9 dB at Res 100%)
- Resonance is capped at 95% (the top 5% of the knob does nothing)
- A pluck's attack comes through slightly softer than on Modern
- Its harmonics give the Transient Shaper rich material to amplify above cutoff — **noisy, characterful transients** when `transAttack` is up
- Level-matched to Modern, so switching topology does not change loudness
- Pick for: warm/vintage character — pads, leads, basses with harmonic richness; anything that wants nonlinear color; presets that depend on the Transient Shaper for noisy attack character

**Modern** (clean ladder):
- Near-linear — the filter itself adds no harmonics
- Clean -24 dB/oct rolloff above cutoff
- Sharper resonance peak at high Q (matches modern clean filters)
- **Cutoff + resonance follow the filter envelope and mod matrix exactly**, so click + attack transients come through intact
- No saturation inside the filter; the full 0..100 Resonance range is live, up to self-oscillation
- **Transient Shaper effect is weaker** when the Punch corner sits above cutoff, because there's no harmonic content above it for the detector to grab — on a dark, sub-heavy patch with the corner at 3200 Hz it can have nothing to act on at all. If a Modern preset needs noisy transients: either lower `transPunch` so the corner sits inside cutoff's passband, OR turn up `oscSat` to inject pre-filter harmonics that survive Modern's clean filtering
- Pick for: clean/modern character — transparent plucks, modern leads, presets that want clarity over warmth, anything where attack faithfulness matters more than harmonic color

**AI guidance:**
- **Apply the headline rule first.** Pick topology based on intended `filterEnvDecay`, then check character intent as a secondary filter.
- **Default to "Analog"** when: long Decay, warm/vintage character, prompts containing "warm" / "fat" / "vintage" / "analog" / "bite" / "snappy" / "pluck" / "punch" / "muscular"
- **Pick "Modern"** ONLY when ALL of: (a) Decay can be kept short (near-zero), (b) character intent is explicitly clean — prompts containing "clean" / "modern" / "crystal" / "pure" / "transparent" / "studio" / "glassy"
- **Never pair Modern with long Filter Decay.** This is the #1 mistake. Even a "clean modern bass" with long Decay sounds like an oil drum on Modern. Either shorten the Decay or switch to Analog.
- **When in doubt → "Analog".** It has the wider sweet-spot and tolerates the full Decay range.
- Don't combine Modern with very high `transAttack` expecting a noisy transient — it won't deliver the same harmonic snap as Analog. Use Modern when the preset's character intent is clean attack, not character snap.

### 3.7 Envelope (the amplitude ADSR — UI label: **Envelope**, param IDs `amp*`)

Full ADSR with wide common-synth ranges: 32 s ceiling on Attack/Decay/Release, 0-100% Sustain. There is no Hold stage — `ampCurve` < 50 (decay-hold shape) is how a note stays near peak before falling. ⚑ **Do not treat `ampCurve` 50 as "the neutral choice" just because it is the default.** At 50 both branches of the law collapse to a straight line in amplitude, and nothing physical decays that way — strings, mallets and plates all fall exponentially, at constant dB per second, which is the `> 50` side. **55-65 is the natural-decay region**; start there for anything meant to read as struck or plucked, and move away deliberately. The full range supports the entire category map, not just Pluck/Bass — most categories stay in a narrow zone, but the headroom is there when Pad/Drone (and atmosphere-leaning Pads) need it.

| ID | Type | Range | Default | Notes |
|---|---|---|---|---|
| `ampAttack` | Float | 0..32000 (ms) | 0.5 | Plucks: 0.1-4 ms (pick icy 0.1-0.5 or soft 2.5-4, middle rarely right). Pads: 500-3000 ms (true bloom). Atmosphere/Drone: 3000-10000 ms. Skew 0.3 (most usable in lower third). |
| `ampDecay` | Float | 50..32000 (ms) | 300 | Pluck: 400-700. Bass: 200-350. Lead: 250-600. Pad: 800-3000. Long-evolving: 5000+. Skew 0.3. |
| `ampCurve` | Float | 0..100 | 50 | **Bipolar decay shape. 50 = linear. <50 = decay-hold** (stays near peak then falls — use 20-40 to keep a note loud for a moment before it decays). **>50 = plucky** (fast initial drop, 60-85 for snappy plucks). ⚑ **55-65 is the NATURAL-DECAY region — reach for it before the default.** 50 is a straight line in *amplitude*, which is the one decay shape no acoustic source produces; a struck or plucked thing decays exponentially (constant dB per second), which is what >50 approximates. |
| `ampSustain` | Float | 0..100 | 100 | 0-15 reads pluck-like; 15-30 starts feeling pad-adjacent; 30-100 holds the note. Pads: 60-80. Drones: 80-100. The ≤30 character heuristic for Pluck/Bass/Lead is just a heuristic — full 0-100 range is available. |
| `ampRelease` | Float | 0..32000 (ms) | 20 | Post-note-off tail. 20 ms = gentle default (click-free note-off). 200-1000 ms = audible release tail (Leads, Keys). 1000-5000 ms = pad/drone sustain into silence. Skew 0.3. |

### 3.8 Transient shaper (post-filter dynamic shaping)

| ID | Type | Range | Default | Notes |
|---|---|---|---|---|
| `transAttack` | Float | -100..100 | 0 | Positive = punchier attack. **Signature Palora tool — reach for it on plucks** (Click + Transient have no direct equivalent in a plain subtractive layout). Don't leave at 0 on a pluck: dial a base ~25-50 (see §6.1), then route `Vel → TransAttack` for dynamics. Strongest on Analog topology. |
| `transSustain` | Float | -100..100 | 0 | Positive = longer sustain. |
| `transSense` | Float | 0..100 | 50 | Detection sensitivity. |
| `transPunch` | Float | 200..5000 (Hz) | 1500 | ⚑ **A HIGH-PASS CORNER, not a band centre — it decides both what gets shaped and which notes react.** The shaper listens to, and shapes, the part of each note above the corner (a gentle 12 dB/oct slope, not a wall). **Lower = more punch, always.** **Register:** a note with little energy above the corner barely triggers — raising the corner makes low notes, and dark or sine-like sounds, react less while high notes still punch. It fades over about two octaves of corner movement; it does not switch off. **Spectrum:** below the corner is shaped less, never left untouched. **Guide:** 200 Hz — almost every note reacts, across the whole note. 700-1500 Hz — low notes and dark sounds react weakly, high or bright notes fully. 2200 Hz and up — mainly high notes and bright, saw-like sounds. |
| `transMix` | Float | 0..100 | 100 | Wet/dry of shaper. |

### 3.9 FX

| ID | Type | Range | Default | Notes |
|---|---|---|---|---|
| `drive` | Float | 0..100 | 0 | 0-30 = clean/light. 40-70 = featured. |
| `fxDriveType` | Choice | "Warm", "Soft", "Hard", "Wild" | "Soft" | Pick per character — don't default. |
| `chorusRate` | Float | 0..100 | 30 | |
| `chorusDepth` | Float | 0..100 | 50 | |
| `chorusMix` | Float | 0..100 | 0 | |
| `delayTime` | Choice | "1/16", "1/16d", "1/8", "1/8d", "1/4", "1/4d", "1/2" | "1/8" | Lead/Pad: use "1/16" (color, not rhythm). |
| `delaySync` | Bool | true/false | true | true = tempo-synced via `delayTime`; false = free time via `delayFreeMs`. |
| `delayFreeMs` | Float | 1..2000 (ms) | 250 | Free delay time — only audible when `delaySync` is false. 1-20 ms reads as thickening/comb color, not echo. |
| `delayFeedback` | Float | 0..95 | 30 | |
| `delayMix` | Float | 0..100 | 0 | Pluck: 0-15. Bass: 0-10. |
| `reverbType` | Choice | "Room", "Hall", "Plate", "Spring" | "Room" | Pick per character — see recipes. |
| `reverbSize` | Float | 0..100 | 50 | |
| `reverbMix` | Float | 0..100 | 0 | Bass: 5-18 (deep house = nearly dry). Pluck: per-character. |
| `reverbPreDelay` | Float | 0..200 (ms) | 20 | |
| `fxHpFreq` | Float | 20..2000 (Hz) | 20 | Master HP cutoff. Default 20 Hz = effectively no cut (below most fundamentals). **Leave at default 20 for sub-anchor Bass and Pad presets** — raising it kills fundamentals. Raise to 80-100 for standard EDM mix cleanup, 200+ for aggressive HP. |
| `fxLpFreq` | Float | 200..20000 (Hz) | 20000 | Master LP cutoff. |
| `fxEnabled` | Bool | — | true | Master FX bypass. Don't usually touch. |

### 3.10 LFOs

| ID | Type | Range | Default | Notes |
|---|---|---|---|---|
| `lfo1Rate` | Float | 0.01..20 (Hz) | 0.5 | Free-running rate (used whenever `lfo1Sync` is "Free"). **HARD RULE: when matrix-routed, 0.2-0.5 Hz**. 1-2 Hz only for explicit visible motion. **Ignored when `lfo1Sync` = "Tempo"** — use `lfo1Division` instead. |
| `lfo1Shape` | Choice | "Sine", "Triangle", "Saw", "Square", "S&H" | "Sine" | |
| `lfo1Sync` | Choice | "Free", "Tempo" | "Free" | **Free** = free-running Hz (`lfo1Rate`). **Tempo** = host-tempo-locked, rate from `lfo1Division`. |
| `lfo1Restart` | Choice | "Never", "Retrig", "Single" | "Never" | When the LFO phase resets. **Every preset load** starts all three LFOs from phase 0, whatever this is set to, so a preset always opens on the same point of its curve. **Never** = free-runs from there. **Retrig** = resets on every note. **Single** = resets only on the FIRST note of a phrase (nothing already held) — one sweep across a whole melodic line. Sustain-pedal-held keys keep the phrase open; under the ARP the reset lands on the arp's first step. Independent of `lfo1Sync`, so a tempo-synced LFO can restart too. |
| `lfo1Division` | Choice | "1/32T","1/32","1/16T","1/16","1/8T","1/8","1/4T","1/4","1/2T","1/2","1/1T","1/1","2/1","4/1" | "1/4" | Tempo-synced rate — **only active when `lfo1Sync` = "Tempo"**. `T` = triplet. No dotted divisions. |
| `lfo2Rate` | Float | 0.01..20 (Hz) | 2.0 | Same hard rule. Ignored when `lfo2Sync` = "Tempo". |
| `lfo2Shape` | Choice | (5 above) | "Triangle" | |
| `lfo2Sync` | Choice | (2 above) | "Free" | (semantics as `lfo1Sync`) |
| `lfo2Restart` | Choice | (3 above) | "Never" | (semantics as `lfo1Restart`) |
| `lfo2Division` | Choice | (14 above) | "1/4" | Active only when `lfo2Sync` = "Tempo". |
| `lfo3Rate` | Float | 0.01..20 (Hz) | 1.0 | Same hard rule. Ignored when `lfo3Sync` = "Tempo". |
| `lfo3Shape` | Choice | (5 above) | "Sine" | |
| `lfo3Sync` | Choice | (2 above) | "Free" | (semantics as `lfo1Sync`) |
| `lfo3Restart` | Choice | (3 above) | "Never" | (semantics as `lfo1Restart`) |
| `lfo3Division` | Choice | (14 above) | "1/4" | Active only when `lfo3Sync` = "Tempo". |
| `randomRate` | Float | 0..20 (Hz) | 0 | 0 = one roll per note, held. >0 = re-rolls within the note (§4.5c). |
| `randomGlide` | Float | 0..100 (%) | 0 | Slew between rolls: 0 = stepped, higher = smooth wander. Only matters when `randomRate` > 0. |

**Restart, and the rate rule.** `Never` is the default and right for most presets — an LFO that free-runs is *ambient* motion, and the preset sounds the same whenever you come in. Reach for the others deliberately:

- **`Retrig`** per-note-locks the LFO to the attack. Use it when the LFO is doing envelope-ish work — a per-note filter blip, a per-note width flick — where the shape needs to start from the same place on every note. On a Saw or Triangle at 1-2 Hz this reads as a second envelope.
- **`Single`** is the *phrase* move: the phase resets only on the first note played with nothing already held, so one slow sweep arcs across a whole melodic line instead of resetting under every note. This is what makes a demo melody open up. Pairs naturally with a long shape (Sine/Triangle/Saw) on Filter Cutoff, Drive, or Reverb Mix.

Three things that catch people out:

1. **The HARD RULE above still applies.** A `Single` sweep is *meant* to be slow — 0.2-0.5 Hz, sometimes slower. Restart changes *where the phase starts*, never how fast it runs. Don't raise the rate to "make the restart audible."
2. **Restart is independent of `Sync`.** A tempo-synced LFO can restart too — `lfoNSync` = "Tempo" + `lfoNRestart` = "Single" is a legal, musical combination: locked to the grid, but starting at your phrase.
3. **Restart is not a substitute for a routing.** Motion still comes from the matrix cell. If a preset feels static, add or deepen a routing — don't switch Restart on and hope.

### 3.11 ENV1 (per-note ADSR — matrix source)

| ID | Type | Range | Default | Notes |
|---|---|---|---|---|
| `env1Attack` | Float | 0.5..2000 (ms) | 5 | Shape ADSR to match the routing's role — see "ENV1 shapes" below. |
| `env1Decay` | Float | 5..16000 (ms) | 2072.3267 | TRUE time to the envelope's exit, not a time constant. See the note below. |
| `env1Sustain` | Float | 0..100 | 30 | |
| `env1Release` | Float | 5..16000 (ms) | 1381.551 | TRUE time from FULL level. See the note below. |

**ENV1 shapes — pair the ADSR to the routing role:**
- **"Brief attack bite"** (envelope-only attack window): `env1Attack` 0.5-5ms, `env1Decay` 350-1000ms, `env1Sustain` 0, `env1Release` 350-700ms. Use for FM-edge attack ornaments, brief filter sweeps at note-on.
- **"Body-shape morph"** (slower envelope, lingers into sustain): `env1Attack` 10-30ms, `env1Decay` 1400-3500ms, `env1Sustain` 20-50, `env1Release` 1400-2800ms. Use for evolving timbre across the note's body.
- **"Long bloom"** (slow open, fade across body): `env1Attack` 50-200ms, `env1Decay` 3500-10000ms, `env1Sustain` 0-20, `env1Release` 2000-5500ms. Use for atmospheric/pad-adjacent presets.

**ENV1 Decay/Release are TRUE time — the convention, stated once:**

`env1Decay` and `env1Release` name the time the stage actually takes, not an
internal time constant. Two consequences worth knowing before you pick numbers:

- **Decay is exact at `env1Sustain` 0 and becomes a CEILING above it.** The stage
  ends when the level reaches its target, and a high sustain is reached sooner —
  so at sustain 50 the decay finishes in roughly 90 % of the labelled time. Author
  against the label; it is the longest the stage can take, never longer.
- **Release is time from FULL level.** A note released from a lower level gets
  there proportionally sooner, so a key lifted during a decay releases faster than
  the label. This is the universal ADSR convention — Vital, Serum and every
  hardware ADSR behave identically — and it is stated here only so the number is
  not mistaken for a promise about every note.

### 3.12 Global

| ID | Type | Range | Default | Notes |
|---|---|---|---|---|
| `glide` | Float | 0..500 (ms) | 0 | Portamento. Use sparingly. |
| `mono` | Bool | `true` / `false` | `false` (Poly = 8 voices) | Set `true` for mono Lead/Bass character (legato, 1 voice). |
| `pitchBendRange` | Float | 0..24 (semitones) | 2 | Semitones of full pitch-wheel deflection. **Leave at 2** (industry standard) unless the preset's performance character needs a wider sweep — e.g. 12 for octave dive-bomb Leads. UI: Bend statbar on the Performance bar. |
| `pan` | Float | -1..+1 | 0 (center) | Master stereo placement (equal-power). Per-preset — part of a sound's identity. Header statbar by Volume. |
| `vibratoRate` | Float | 0.1..12 (Hz) | 5.5 | Dedicated coherent sine vibrato speed. Musical range ~4-7 Hz. |
| `vibratoDepth` | Float | 0..100 (cents) | 0 | Always-on vibrato amount (0 = none at rest). The **mod wheel** brings vibrato in via a **default matrix cell** — `ModWheel → Vibrato` (`modAmt_6_22` = 50% in Init, ≈ +50¢ at full wheel), inherited by every preset unless you explicitly set it to 0. The matrix Vibrato destination (slot 22) also takes aftertouch/macro/env (additive). Set >0 only for presets that want baked-in shimmer (strings/pads); leave 0 for plucks/leads and let the wheel bring it in. |
| `macro1` | Float | -100..+100 | 0 | Macro knob 1 starting position (bipolar, like all macros). Default 0. |
| `macro2` | Float | -100..+100 | 0 | Macro knob 2 starting position (bipolar, like all macros). Default 0. |

**Never set:** `masterVolume`, `masterTune`, `globalTranspose`, `matrixBypass`, `modRowBypass_1`…`modRowBypass_11` (host/session state — excluded from presets and ignored on load), or any `audition_*` param.

---

### 3.13 Arpeggiator (matrix ARP lens)

| Param | Range / choices | Default | Notes |
|---|---|---|---|
| `arpOn` | bool | `false` | Held keys stop sounding directly; the arp fires them per the pattern. **Only once the pattern can actually fire** — `arpOn` with an empty grid is ARMED, and your keys keep sounding normally (see §5.2c). |
| `arpHold` | bool | `false` | Latch — keeps arping after key release; a fresh chord replaces the latched one. |
| `arpSync` | `Free` / `Tempo` | `Tempo` | Tempo locks steps to host BPM via `arpDivision` (PPQ-aligned while the transport rolls); Free runs at `arpRateHz`. |
| `arpRateHz` | 0.5–50 Hz | 8 | Steps per second in Free mode. |
| `arpDivision` | same list as `lfo1Division` | `1/16` | Beats per step. Triplet feels come from the `T` divisions — NOT from per-note gates. |
| `arpLoopLen` | 1–24 | 16 | Pattern length in steps (automatable — live loop-shortening is a real performance move). Default 16 = 4 beats (§7.2 rule 23). |
| `arpSwing` | 0–60 % | 0 | Delays every 2nd step (60 % ≈ full triplet feel). |

The pattern itself is the top-level `arp` block (§5.2c), never a param. There is
**no octave param**: the grid's 9 ladder rows auto-wrap the held notes through
ascending octaves until every row is filled — the grid IS the octave control
(§5.2c).

## 4. Modulation matrix — sources × destinations × signed amount

The matrix is encoded as two flat parameter families.

**Amount (always meaningful):**

```
modAmt_<srcIdx>_<dstIdx>
```

where `<srcIdx>` is 1-11 and `<dstIdx>` is 1-24 (slot 22 = Vibrato depth; slot 23 = AmpRelease; slot 24 = TransPunch). Value range is **-100..+100** (signed). 0 = inactive cell. For the 15 *additive* destinations, the slot adds an offset to the knob. For the 10 *knob-relative* destinations (OscBPulseWidth, OscBPitch, AmpAttack, FilterCutoff, FilterAttack, AmpDecay, TransAttack, DelayFeedback, AmpRelease, TransPunch), `|slot|=100%` sweeps the destination knob's full range across its skew curve.

**Polarity (LFO + Random source rows):**

```
modPol_<srcIdx>_<dstIdx>
```

Boolean. **Only meaningful when `<srcIdx>` is an LFO (1, 2, or 9) or Random (11).** The engine ignores it on Macro/ENV1/MW/Vel/AT rows (ENV1 and Velocity are intrinsically unipolar; Macros are already bipolar at the knob; MW/AT are physical-controller unipolar).

- `true` = source sweeps **bipolar around the knob** (LFO: slot adds and subtracts across the cycle; Random: per-note roll lands ±|amt| around the parked value — every note brighter AND darker depending on the roll). **The slot is read as UNSIGNED WIDTH in this mode (the engine takes `|amt|`)** — a negative amount is legal in the file but its sign is ignored. Emit positive amounts on bipolar cells.
- `false` = source **shifts unipolar** from the knob (LFO: one-direction offset, cycle stays on one side; Random: per-note roll pushes the parked value in the slot's sign direction — every note brighter OR darker, never both).

Per-destination defaults — these 10 default `true`: **OscMix, OscBPulseWidth, OscBPitch, AmpAttack, FilterCutoff, FilterAttack, AmpDecay, TransAttack, AmpRelease, TransPunch**. The other 14 default `false`. **Omit `modPol_*_*` for default behavior — only emit when overriding (it's sparse like every other param).**

### 4.1 Sources

| Index | Source | Notes |
|---|---|---|
| 1 | LFO1 | Default 0.5 Hz Sine |
| 2 | LFO2 | Default 2.0 Hz Triangle |
| 3 | ENV1 | Per-note ADSR |
| 4 | Macro1 | User macro 1 |
| 5 | Macro2 | User macro 2 |
| 6 | ModWheel | MIDI CC1 |
| 7 | Velocity | Per-note velocity |
| 8 | Aftertouch | Mono channel pressure |
| 9 | LFO3 | Default 1.0 Hz Sine |
| 10 | KeyTrack | **The sounded MIDI note.** `(note - 60) / 60`, so it is **bipolar around middle C**: zero offset at C4, positive above, negative below. DAW automation: "Mod KeyTrack -> X"; the UI row label is "KT". This is how every key-tracking gesture is written — see §4.2b. |
| 11 | Random | Per-voice random, bipolar -1..+1. At the default `randomRate` 0 it rolls once at noteOn and holds for the note; above 0 it re-rolls within the note at that rate, and `randomGlide` smooths between rolls (§4.5c). Independent per note. Polarity-bit aware (see §4 intro). |

### 4.2 Destinations

24 destinations. Slot numbers (used in `modAmt_*_*` keys) are FIXED engine indices and do not change. Note: the UI matrix column order diverges from slot order — it shows Click Lv, Sub Lvl, Unison (matching the Sources strip left-to-right) while slots stay 6=Unison, 7=Sub, 8=ClickLevel. The UI also groups the envelope as Env Atk / Env Dec / Env Sus / Env Rel straight across and the transient as Trns Pnch then Trns Atk, which is neither slot order (9, 14, 15, 23 and 24, 16). **The slot number is the wire format — always write the SLOT, never the column position.**

| Index | Destination | Notes |
|---|---|---|
| 1 | OscShape (A) | Saw → Triangle → Sine morph |
| 2 | OscMix | A↔B blend |
| 3 | OscBShape | B shape morph |
| 4 | OscBPulseWidth | **Osc B width ONLY.** UI label 'B Width'. Audible only if `oscBPulse = true`. **Knob-relative** — ±100% sweeps full 5..95%. |
| 5 | OscBPitch | **DON'T MODULATE** (pitch — see Tier 3 below). If overridden, **knob-relative** ±50 cents at ±100%. |
| 6 | Unison | Unison spread (cents) — outer voices sweep around a stable center: ensemble warble, not pitch. **Silent no-op at unisonVoices 1.** Slow + small only (see Tier 3 exception). |
| 7 | Sub | Sub level |
| 8 | ClickLevel | Click level |
| 9 | AmpAttack | **Envelope ATTACK time (ms).** Per-voice. Knob-relative and **TRUE LOG** across 1..32000 ms, so equal amounts buy equal time ratios in both directions. Bipolar by default — a slot makes the attack faster *or* slower around the parked value rather than ramping from a rail. This is one of the three destinations `KeyTrack` needs to reach each envelope stage independently (see §4.2b). |
| 10 | FilterCutoff | Most-used destination. **Knob-relative TRUE-LOG sweep** — ±100% spans the full 20 Hz..20 kHz, and equal amounts move equal OCTAVES in both directions (9.97 oct end to end, so 10% ≈ 1 octave). |
| 11 | FilterResonance | adds to base knob, clamped 0..100% |
| 12 | FilterEnvAmount | additive, **clamped to the knob's 0..+1 — cannot go negative.** A negative slot reduces env depth toward zero, it does not invert the sweep. For an inverted env use `ENV1 → FilterCutoff` (dst 10) with a negative amount; see §4.5d |
| 13 | FilterAttack | **Knob-relative TRUE-LOG** — ±100% sweeps 1 ms..32 s in equal ratios (≈15 oct, so 10% ≈ 1.5 octaves of time). The MOD range floors at 1 ms where the knob floors at 0. Only audible during the Attack stage. |
| 14 | AmpDecay | **Knob-relative TRUE-LOG**, and the MOD range floors at **1 ms** where the ampDecay KNOB floors at 50 ms — a downward sweep reaches single-digit ms. **Cap \|amount\| ≤ 5%** — envelope shape is structural, and 10% ≈ 1.5 octaves of time. |
| 15 | AmpSustain | adds to base sustain, clamped 0..1, retargets in Decay/Sustain |
| 16 | TransAttack | additive ±1, full creative range (knob-relative scaling). |
| 17 | Drive | FX drive amount |
| 18 | ChorusMix | |
| 19 | DelayFeedback | |
| 20 | DelayMix | |
| 21 | ReverbMix | |
| 22 | Vibrato | **Vibrato DEPTH (cents)** — the depth of the dedicated coherent sine vibrato (Rate + Depth live on the Performance strip). **ENCOURAGED, unlike raw pitch (slot 5):** this is a musical, in-tune vibrato. **The mod wheel reaches vibrato THROUGH this slot** — Init ships a default `ModWheel → Vibrato` cell (`modAmt_6_22` = 50%, ≈ +50¢ at full wheel), so the wheel works on every preset; set it to 0 to suppress wheel-vibrato on a patch. Add *other* expression sources too — **Aftertouch → Vibrato** (press for vibrato), **Macro → Vibrato**, **ENV1 → Vibrato** (vibrato fades in after the attack). Unipolar, additive (+100¢ at +100%). Slow musical motion. |
| 23 | AmpRelease | **Envelope RELEASE time (ms).** Per-voice. Knob-relative and **TRUE LOG** across 1..32000 ms. Bipolar by default, same family as AmpAttack (9) and AmpDecay (14). |
| 24 | TransPunch | **Transient PUNCH frequency (Hz).** Per-voice. Knob-relative and **TRUE LOG** across the 200..5000 Hz Punch window, so equal amounts buy equal octaves. Bipolar by default — a slot moves the corner up and down around the parked value. ⚑ The corner decides both what is shaped and how strongly each note reacts (§3.8), so modulating it changes which notes punch. Only audible when `transMix > 0`. |

**Example:** `"modAmt_3_10": 35.0` routes ENV1 → FilterCutoff at +35%.
**Vibrato example:** `"modAmt_8_22": 60.0` routes Aftertouch → Vibrato depth (press a held note for vibrato). Aftertouch is source **8**; source 9 is LFO3.


### 4.2b Key tracking and velocity ARE matrix routings — there are no dedicated knobs

Palora has no dedicated key-tracking or velocity knobs: every such gesture is an
ordinary matrix cell. **Do not invent parameter ids for them** — an id the plugin
does not have is silently discarded.

| the gesture | write this | notes |
|---|---|---|
| cutoff tracks pitch | `modAmt_10_10` | KeyTrack → FilterCutoff |
| amp envelope tracks pitch | `modAmt_10_9`, `modAmt_10_14`, `modAmt_10_23` | one cell per stage — Attack, Decay, Release. Write a cell for each stage that should track. |
| punch band tracks pitch | `modAmt_10_24` | KeyTrack → TransPunch |
| velocity → brightness | `modAmt_7_10` | Velocity → FilterCutoff |
| velocity → decay length | `modAmt_7_14` | negative = harder hits decay shorter (percussion convention) |
| velocity → transient attack | `modAmt_7_16` | Velocity → TransAttack |

**KeyTrack has TWO reference points and they compose.** The source is `(note-60)/60`,
so on a bipolar cell the offset is **zero at middle C** — that is the pivot, the note
where the routing does nothing. The **parked knob is the anchor**: the offset is added
to the knob's own norm, so at C4 you hear exactly what you dialled and every other note
moves away from it in proportion to its distance from C4.

⛔ **NEVER build a value by parking it wrong and cancelling it with a cell.** The
parked knob is what you hear at middle C — dial the value you want there. A short
attack is `ampAttack` set short, never a long attack pulled down by a `KeyTrack` cell.

⚠ **The pivot is PER CELL, and one-way is not a shaping technique.** Flipping
`modPol_10_<dst>` to one-way moves the pivot to note 0, so the parked knob stops being
the middle-C value. Do not reach for it to bend what a knob means.

⛔ **Downward envelope key tracking is NOT expressible.** On a bipolar cell the engine
takes `abs(amt)`, so -40 renders identically to +40 and the destination always RISES
with pitch: higher notes get the LONGER attack, decay and release. If a patch wants
"higher notes ring shorter", leave the routing out — do not fake it with a one-way
cell and multiplied times.

**Calibration:** `modAmt_10_10 = 25.1` makes cutoff track at 0.50 octave per octave,
and `50.2` tracks 1:1.
⚠ `KeyTrack → TransPunch` cannot reach 1:1 pitch tracking: the Punch window spans 4.64
octaves against KeyTrack's 10, so amount 100 gives 0.929 oct/oct.

### 4.3 Audible-amount thresholds

Below these magnitudes, a routing is silently inert and counts as cosmetic only:

| Destination | Min \|amount\| to be audible |
|---|---|
| FilterCutoff | ≥15 |
| FilterResonance | ≥20 |
| FilterEnvAmount | ≥15 |
| FilterAttack | ≥20 (only audible during Attack stage) |
| AmpSustain | ≥10 (high-leverage on amp env tail) |
| TransAttack | ≥15 |
| AmpAttack | ≥20 (log time; below this the attack ratio is inside the 1 ms anti-click floor on short attacks) |
| AmpRelease | ≥20 (log time; and inaudible on a preset whose notes are cut before the release runs) |
| TransPunch | ≥15 (only audible when transMix > 0) |
| Drive | ≥20 |
| ChorusMix / DelayMix / ReverbMix | ≥15 |
| OscMix | ≥15 |
| AmpDecay | ≥25 |
| Unison | ≥4 — and only audible at unisonVoices ≥ 2 |

A preset must have **3-6 audible routings** above these thresholds.

### 4.4 Source groupings — what each source is for

**Group 1 — Modulators (autonomous, give the preset *life*):**

`LFO1`, `LFO2`, `LFO3`, `ENV1`, `Random`. These are the only sources that sculpt the sound autonomously — they run on their own without user input. LFOs deliver continuous timbral motion across the cycle; ENV1 sculpts each note's attack/body shape; Random gives per-note *variation* (every note rolls slightly differently). **Prefer LFO/ENV1 to satisfy the Group-1 rule below — Random is occasional spice, not a go-to (use it sparingly, never on cutoff; see §4.5c).**

**HARD RULE: every preset must have ≥1 Group-1 routing.** Without one, the preset is static — the user gets no motion on sustained notes. Velocity routings DO NOT satisfy this rule.

> **Random caveat: at the default `randomRate` 0 it gives per-note variation, not within-note motion.** On a single held note Random is a static value. It satisfies the Group-1 floor only when the preset is actually played with multiple notes (which is the normal case — a sustained drone preset that wants within-note motion still needs an LFO or ENV1 routing).

**Group 2 — Performance / Macro (user-actuated, give the preset *gestures*):**

`Macro1`, `Macro2`, `ModWheel`. Only audible when the user moves the knob/wheel. Great as featured "macro = the open-up knob" gestures, but they don't satisfy the autonomous-life requirement.

- **Macros are bipolar at the knob.** Center (12 o'clock) = no mod; full clockwise = +slot; full counter-clockwise = −slot. A macro knob covers `[base − amount, base + amount]` across its sweep — both endpoints matter.
- **ModWheel is unipolar.** 0 = no mod; full = +slot (or −slot if the slot value is negative).
- **One bold target per macro** — Drive, FilterCutoff, ReverbMix, ChorusMix, OscMix. Users expect a satisfying big move at the endpoints.
- **No macro clones** — Macro1 and Macro2 must NOT route to the same destination.
- **Dramatic amounts** — both endpoints of a macro's sweep should be audibly distinct from center. If `OscMix` base is 50 and Macro1→OscMix amount is 30, the sweep covers [20, 80] — usable, but the swing on each side is modest. Use amount ≥50 when you want a *dramatic* macro on a mid-based knob, or pick a destination where ±30 reads as a big move (Drive, ReverbMix, ChorusMix).

**Group 3 — Per-note response (give the preset *responsiveness*):**

`Velocity`, `Aftertouch`. Make the preset *responsive*, not *alive*.

- **Don't lean on Velocity as the differentiator.** Four Vel routings + zero Group-1 = static-feeling preset.
- **Aftertouch:** light use only. Many keyboards lack channel pressure, so AT can't be the primary anchor.

### 4.5 Destination tiers

**Tier 1 — modulate freely (timbre-shaping workhorses):**
`FilterCutoff` (10), `OscMix` (2), `OscShape` (1), `OscBShape` (3), `AmpDecay` (14, with ≤5% cap), `TransAttack` (16), `ClickLevel` (8), `Sub` (7), `FilterEnvAmount` (12, clamped 0..+1 — no inversion; see §4.5d), `AmpSustain` (15), `FilterAttack` (13, only acts during Attack stage), `AmpAttack` (9), `AmpRelease` (23), `TransPunch` (24, only audible when `transMix` > 0).

Modulating these *is* the expression. **A preset without ≥1 Tier-1 routing feels static.** No cap on Tier-1 routing count — 3-4 per preset is normal. See §4.5b for category-coverage notes on FilterResonance, FilterEnvAmount, FilterAttack, AmpSustain, and TransAttack — they unlock non-pluck categories.

**Tier 2 — modulate with care (level- or loudness-affecting):**
`Drive` (17), `FilterResonance` (11, self-osc risk; capped at 95% on Analog, uncapped on Modern), `DelayFeedback` (19), `ChorusMix` (18), `DelayMix` (20), `ReverbMix` (21).

**≤1 *featured* Tier-2 routing per preset.** Stacking Tier-2 routings (e.g. ModWheel → Drive AND ReverbMix AND DelayFeedback) makes the preset feel out of control.

**Tier 3 — DO NOT MODULATE:**
- `Unison` (dst 6) — fast/large spread warble reads as detune chaos. ONE exception: the slow ensemble-warble (LFO, ≤0.5 Hz, ±4..14, unisonVoices ≥ 2) — legal on any sustained category; never on Arps.
- `OscBPitch` (dst 5) — same reason.
- `OscBPulseWidth` (dst 4) — only when PWM is the preset's defining thing; requires `oscBPulse = true` (B only).

**For static "tonal interest"**, set base parameters: `oscAFine`, `unisonDetune`, `oscBFine` (sub-semitone, ±5..30), `analogDrift`. NEVER `oscBSemi` (fixed semitone — clashes with chord/scale playing).

### 4.5b Filter / Pluck / Trans expressive destinations — what they unlock

These five dests broaden Palora from pluck-focused into common subtractive-synth coverage. Use them deliberately:

- **`FilterResonance` (dst 11, Tier 2)** — adds to base knob (clamped 0..100; on **Analog** resonance is capped at 95%, on **Modern** there is no cap and the knob reaches full self-oscillation). Pluck: `ENV1 → FilterResonance +20..40` for self-singing bite on the transient. Pad/Atmosphere: `LFO → FilterResonance ±15..30 slow` for vowel-y morph. Acid Lead: `Vel → FilterResonance +40..70`. Most leads invert (-): soft hits get singier reso, hard hits stay focused.
- **`FilterEnvAmount` (dst 12, Tier 1)** — additive, **clamped to the knob's own 0..+1 range**. Modulating it scales how deep the filter envelope sweeps; it cannot flip the sweep's direction, and a negative slot only walks the depth down toward zero. Pad: `LFO2 → FilterEnvAmount ±20..40 slow` for evolving filter character. Stab: `Macro1 → FilterEnvAmount +60` to dial in stab snap. **For an env that *closes* the filter, see §4.5d — that needs `ENV1 → FilterCutoff` with a negative amount.**
- **`FilterAttack` (dst 13, Tier 1)** — knob-relative TRUE LOG over 1 ms..32 s (10% ≈ 1.5 octaves of time, see §4.2), only audible during the Attack stage. Brass: negative `Vel → FilterAttack` for soft attack on quiet notes, fast attack on loud. Pad: positive `Macro1 → FilterAttack` to user-dial the bloom speed. Drone/Cinematic: a very slow `LFO → FilterAttack` for breathing attack rates across notes. For the amount, see §4.7 — on this log range even ±20 is a big move.
- **`AmpSustain` (dst 15, Tier 1)** — adds to base Envelope sustain, clamped 0..1. Retargets mid-Decay endpoint or jumps the held Sustain level mid-stage. Pad: `LFO1 → AmpSustain ±15..25 slow` for breathing sustain. Atmosphere: `Macro2 → AmpSustain +40..+60` to morph note from pluck-like (Sustain 0) to held (Sustain 60-80) under user control. Snaps back to base when mod returns to 0.
- **`TransAttack` (dst 16, Tier 1)** — adds to base Transient Attack ±1, full creative range. Pluck/Bass: `Vel → TransAttack +30..+50` for harder-hits-bite-more. Pad: leave alone (transient shaper is character, not motion).

### 4.5c Random source — occasional per-note spice (use sparingly)

`Random` (source 11) is a per-voice random value, bipolar -1..+1 — by default one fresh roll per note, held (see Rate + Glide below). It can add subtle note-to-note variation, but treat it as **spice, not a staple: most presets need ZERO Random routings.** Reach for an LFO or ENV1 to give a preset its motion first; add Random only when you specifically want gentle per-note unpredictability, and then only in **small amounts (≤ ~15)** on a **subtle target**. A preset must never lean on Random for its core character — that's the #1 Random mistake.

**Rate + Glide.** Random has two shaping params (`randomRate`, `randomGlide`). At the **default `randomRate` 0** it behaves exactly as the note-on S&H described above (one roll per note, held). Set `randomRate` > 0 (Hz) and it **free-re-rolls within the held note** — a per-voice random LFO; `randomGlide` (0–100 %) slews between rolls (0 = stepped S&H, higher = smooth "drunk-walk" wander). A Random with `randomRate` > 0 is genuine autonomous motion (it can satisfy the Group-1 floor), but the cautions still hold — keep it subtle and **never on cutoff**.

> **NEVER route `Random → FilterCutoff`.** Per-note brightness jitter reads as unmusical and unstable — *"why is every note a different tone?"* — not "alive." Cutoff is the one destination where Random almost always sounds wrong, and it's the most common misuse. Keep per-note brightness variation out of Random entirely; if you want hit-to-hit brightness, use `Vel → FilterCutoff` (musical, player-controlled).

Polarity bit (engine semantics in §4 intro; Random is polarity-bit-aware alongside LFOs): **bipolar** (`modPol=true`) rolls ±|amount| around the parked knob; **unipolar** (`modPol=false`) pushes the parked value one direction by `roll × amount` (parked value is the floor/ceiling, never the center).

**If you use Random at all (rarely), keep it tiny and subtle:**

| Routing | Amount + polarity | Role |
|---|---|---|
| `Random → ClickLevel` (modAmt_11_8) | +5..15, **unipolar** | Faint per-note onset variation — some notes a touch harder. |
| `Random → Drive` (modAmt_11_17) | +5..12, **unipolar** | Barely-there per-note grit jitter. |

**Don't:**
- **Never** route Random to `FilterCutoff` (above), and never to `OscBPitch` (dst 5) — per-note brightness/pitch jitter reads as out-of-tune and unstable, not "alive." (Random → Unison dst 6 would jitter stereo width per note, not pitch — legal, but rarely worth a slot.)
- Don't make Random a preset's primary or only modulation — it gives per-note variation, not within-note motion; an LFO or ENV1 must carry the autonomous motion.
- Don't pair Random with mono + glide — the per-note roll reads as instability, not variation.
- Cap any Random amount at ~15; past that it's "wrong notes," not "varied."

### 4.5d Cutoff envelopes — use the dedicated filter envelope, not ENV1

Palora has a **dedicated filter envelope**: `filterAttack` / `filterEnvDecay` /
`filterSustain` / `filterRelease`, scaled by `filterEnvAmount`. That is the
mechanism for envelope-driven cutoff. **Do not spend a matrix slot on
`ENV1 → FilterCutoff` (`modAmt_3_10`) to do the same job** — ENV1 is a
general-purpose modulator and its slots are better spent on destinations that
have no dedicated envelope of their own.

**The one exception — an inverted sweep.** `filterEnvAmount`'s knob range is
0..100, and the FilterEnvAmount matrix destination (dst 12) is clamped to that
same `[0, +1]`. Neither can express an envelope that *closes* the filter. When a
preset needs the envelope to sweep cutoff **downward**, `ENV1 → FilterCutoff`
with a **negative** amount is the prescribed route and the only one that works.
ENV1 ignores the per-cell polarity bit, so the sign is a true signed inversion
regardless of FilterCutoff's bipolar default.

**Two things this rule does not change:**

- **It does not satisfy the Group-1 rule.** The filter envelope is not a matrix
  routing, so it never counts toward §4.4's "≥1 Group-1 routing" floor. A preset
  whose cutoff motion comes from the filter envelope still needs at least one
  Group-1 routing elsewhere.
- **The two paths do not obey the same law.** `filterEnvAmount` is octave-space
  (`env × amount × 4`); the `ENV1 → FilterCutoff` matrix route is norm-space
  across the cutoff mod range, which is TRUE LOG (equal amount = equal octaves).
  You can match the *peak* per preset,
  but the trajectory between base and peak is not identical — so converting one
  to the other is a re-voicing, not a rewrite.

### 4.6 Sign-flip patterns

Most matrix routings are positive (more source = more dest). For polarity-bit-ignored sources (Vel, Macro, MW, ENV1, AT), a negative `modAmt_*_*` value is the inversion mechanism. For polarity-bit-aware sources (LFOs + Random), a negative slot inverts **only in unipolar mode** (bit `false`: one-direction shift downward). In **bipolar mode the slot's sign is ignored** — the engine reads `|amt|` as swing width, so "inverting" a bipolar cell is meaningless; choose the mode with the `modPol_*_*` bit (see §4 intro) and keep bipolar amounts positive. One rule: **unipolar = signed push, bipolar = unsigned width.** Caution: 10 destinations default the bit to `true` (OscMix, OscBPulseWidth, OscBPitch, AmpAttack, FilterCutoff, FilterAttack, AmpDecay, TransAttack, AmpRelease, TransPunch) — a negative LFO/Random amount written to those without a `modPol` override does nothing different from positive.

Common inversions:

| Routing | Sign | Why |
|---|---|---|
| `Vel → AmpDecay` (modAmt_7_14) | **negative** | Harder hit = shorter, snappier note. Standard percussion convention. |
| `Vel → FilterResonance` (modAmt_7_11, most leads) | **negative** | Soft hits get singier resonance, hard hits stay focused. |
| `Vel → FilterResonance` (modAmt_7_11, acid leads) | **positive** | Harder hits get squelchier. |
| `Vel → FilterAttack` (modAmt_7_13) | **negative** | Soft hits get slower attack (gentle), hard hits snap open. Brass-y. |
| `LFO → FilterEnvAmount` (modAmt_X_12) | either | Walks the filter env's *depth* up and down across the LFO cycle. It does **not** flip the sweep — dst 12 is clamped at 0, so the negative half-cycle bottoms out at "no filter envelope," never at an inverted one. |
| `Macro → Drive` (modAmt_4_17) | positive | Standard "more grit" knob. (Macro is bipolar at the knob — negative slot makes counter-clockwise = more grit instead.) |

### 4.7 Routing depth — how deep should a routing be?

§4.3 gives the *floor* (below which a routing is silently inert). This section is the procedure for picking the amount above it. The single most common authoring failure isn't the wrong destination — it's the wrong *amount*. Two principles, then three steps.

**Principle 1 — the matrix is binary: right lever or filler.** When a routing is the right lever, push it into its working range. When it's not, don't include it at all. **Avoid 30-40% middling values** — neither audible nor wisely chosen. Timid amounts on performance levers are the #1 authoring mistake.

**Principle 2 — knob-relative depth on 10 destinations.** For OscBPulseWidth, OscBPitch, AmpAttack, FilterCutoff, FilterAttack, AmpDecay, TransAttack, DelayFeedback, AmpRelease, TransPunch, the slot is read against the destination's **full mod range** — `|slot|=100%` sweeps the whole range. For FilterCutoff, FilterAttack, AmpDecay, AmpAttack, AmpRelease and TransPunch that range is TRUE LOG, so equal amounts buy equal octaves (or equal time ratios) up and down; the other four follow their knob's own curve. The same number means a different musical depth depending on **where the knob is parked**; the more extreme the park, the *smaller* the amount you need. A bipolar source sweeps both directions, so the swing toward the extreme can run clean off the audible end.

**Step 1 — start from the source's role.**

| Source role | Sources | Base depth | Why |
|---|---|---|---|
| Modulator (character motion) | LFO1/2/3, ENV1 | **±5..30** | Timbral *life*, not a sweep. Subtle is right. |
| Macro (performance lever) | Macro1/2, ModWheel | **50..100** | Both endpoints must read as a *big* move (see §4.4). |
| Per-note response | Velocity, Aftertouch | **+25..45** (sign per role) | Responsive, not the differentiator. |
| Random (spice) | Random | **≤15** | Per-note variation only; never on cutoff (§4.5c). |

**Step 2 — adjust for the destination type.**

- **Additive destinations** (OscMix, OscShape/BShape, FilterResonance, FilterEnvAmount, AmpSustain, ClickLevel, Sub, Drive, the FX mixes): use the Step-1 band as-is. Fine ranges: `AmpSustain` ±10..30 (high-leverage on the amp-env tail), `FilterEnvAmount` +15..50 (**depth only — cannot flip the env's sign**; see §4.5d), `FilterResonance` +20..+70, `TransAttack` ±15..50 and `TransPunch` ±15..40 (knob-relative; both only audible when `transMix > 0`). **`AmpDecay`: ≤5% hard cap** — envelope shape is structural; more "totally bites off the sound", and at ±100% the knob-relative slot would sweep the full 50 ms..32 s range.
- **Knob-relative destinations**: scale to the park. Worked example — `LFO → FilterCutoff` (bipolar by default):

  | Cutoff parked at | Use roughly | Because |
  |---|---|---|
  | ~400-600 Hz (dark / drone) | **±5..10** | The negative half-cycle sweeps toward 20 Hz, *below the fundamental* → the sound briefly disappears. The #1 cause of "my filter LFO makes the sound vanish." |
  | ~1200-2000 Hz (mid) | **±12..20** | Headroom in both directions. |
  | ~3500+ Hz (bright/open) | **±25..40** | Lots of room below, and a bigger swing is needed against an already-open filter. |

  The same scale-to-the-park logic applies (inverted) to `FilterAttack` (±20..60, only audible during the Attack stage) and `AmpDecay` parked near floor or ceiling. ⚠ Both are TRUE LOG — a given amount buys the same RATIO of time wherever the knob is parked, so ±20..60 is a big gesture even near the floor.

**Step 3 — confirm it clears the audible floor (§4.3).** If Steps 1-2 land you *below* the floor, the routing is wrong for this preset — **drop it, don't pad it to 30-40 "to be safe."**

**One-line version:** Macros big (50-100); modulators small (±5-30) and *smaller still* on knob-relative dests parked near an extreme; velocity medium (±25-45); Random tiny (≤15) — and never let a bipolar LFO on a low/dark cutoff exceed single digits.
---

## 5. `.palora` file format

### 5.1 Wrapper structure

```json
{
  "format": "preset",
  "version": "1.0",
  "plugin": "palora",
  "meta": {
    "name": "Preset Name",
    "category": "Pluck",
    "author": "Segment CPH",
    "description": "One sentence about this sound only, in plain everyday English.",
    "tags": ["pluck", "warm", "atmospheric"],
    "generator": "ChatGPT"
  },
  "params": {
    "oscShape": 30.0,
    "oscABMix": 50.0,
    "subShape": "Tri",
    "fxDriveType": "Hard",
    "modAmt_3_10": 35.0
  },
  "melody": {
    "bpm": 120,
    "loopBeats": 8,
    "notes": [ [0.0, 0.25, 74, 103], [0.75, 0.25, 77, 103] ]
  }
}
```

This is the **complete top-level shape** — seven sibling keys at the root: `format`, `version`, `plugin`, `meta`, `params`, and the optional `melody` and `arp`. Note the structure: `params` **closes** (`}`) before `melody`/`arp` **open** — they are never keys inside `params`. `melody` and `arp` are the only optional ones; omit `melody` — **the default**, unless the user explicitly asked for one (§5.2b) — to fall through to the audition fallback library, omit `arp` unless the preset is an arp patch (§5.2c). Each key's rules follow.

### 5.2 Wrapper field rules

| Field | Required | Notes |
|---|---|---|
| `format` | yes | Always `"preset"` (shape label). |
| `version` | yes | Always `"1.0"` (string, not integer). |
| `plugin` | yes | Always `"palora"`. The importer rejects a file whose `plugin` isn't `palora`. |
| `meta.name` | yes | Display name in browser. **English**, regardless of the prompt's language. |
| `meta.category` | recommended | **Closed vocabulary (7).** Exactly one of: `Pluck`, `Bass`, `Lead`, `Pad`, `Keys`, `Stab`, `Drone` — or omit/empty for Uncategorized. The plugin's category picker offers only these, and **import snaps any other string to a canonical match (plurals tolerated) or to Uncategorized** if unrecognized. Don't invent categories (e.g. `Arp`, `Bell`, `Synthwave`, `Lo-Fi`) — they import as Uncategorized. |
| `meta.author` | recommended | `"Segment CPH"` for factory presets. **NOT the AI tool's name** — author is the human/team responsible for the preset, even when the values were AI-generated. |
| `meta.description` | recommended | One sentence, **English**, in plain everyday words, about **this** sound only. Evocative ("Round warm pluck with subtle detune"), not parametric ("OscMix=50, drive=15"). **Never compare or rank it against other presets** — not "The darkest pad in the bank", "the snappiest note here" or "sibling to Twin Hum": the library changes and the claim goes stale. **Use words a non-native English reader knows** — not "Blown-bottle hollow pluck — a clay formant with a breath of chiff", but "Hollow, breathy pluck, like blowing across a bottle". |
| `meta.tags` | recommended | 3-6 lower-case **English** tags for search. |
| `meta.generator` | **REQUIRED for AI** | The name of the AI tool emitting this preset. Use a short canonical form: `"ChatGPT"`, `"Claude"`, `"Gemini"`, `"DeepSeek"`, `"Mistral"`, etc. Surfaces in the preset browser as provenance so users can build an ear for which tools produce which characters. **Always populate this when you (the AI) author a preset.** Leave absent only if the preset is human-authored. |
| `params` | yes | Sparse map of parameter overrides (diff from Init). Keys not present resolve to their Init value. |
| `melody` | **omit unless explicitly requested** | The preset's **audition** preview phrase — a 2, 4 or 8 bar loop that plays when the user arms ♪ on this preset. Top-level sibling of `meta`/`params`; never affects sound. **Default is to omit it** and use the per-category fallback library — write one ONLY when the user asks for it in so many words (§5.2b). |
| `arp` | optional | The preset's **arpeggiator pattern** (matrix ARP lens). Top-level sibling of `meta`/`params` — same placement rule as `melody`. Only include when the preset is an arp patch; pair it with `arpOn: true` in `params` (§5.2c). |

**Never write `created` or `modified`** — they are library-owned. The plugin stamps
`created` on import; `modified` appears only after a content edit. An AI doesn't know
real time, so it must not invent these.

### 5.2b Audition `melody` — ONLY ON EXPLICIT REQUEST

**⛔ DEFAULT: DO NOT WRITE A `melody` BLOCK.** Omit it and the preset falls through to
the built-in per-category audition library, which is tuned per category and is what the
whole factory bank uses. Add one **only when the user has explicitly asked for it** —
"give this preset its own melody", "author a melody for each preset in the pack". A
request to write a preset, a category batch, or a whole pack is **not** such a request,
and neither is a preset whose character seems to invite one. The same rule covers the
**pack-level** `melody` (`pack.meta.melody`), which overrides the fallback for every
preset in the pack and so is the more damaging one to add uninvited.

Why the default is off: a per-preset melody **overrides** the category fallback, so a
mediocre phrase actively makes the preset audition worse than writing nothing would
have. The fallback is one place that can be fixed for the entire bank at once; a baked-in
melody is 254 places. Silence on the subject is a decision, not an omission.

When it *is* asked for: the phrase is purely a preview — it never touches parameters or
live playback. The essentials:

**Placement (the #1 error to avoid):** `melody` is a **top-level sibling of `params`** — it sits *beside* `params`, never *inside* it. Nesting `melody` under `params` breaks the audition parser. See the ✅/❌ contrast at the end of this section.

```json
"melody": {
  "bpm": 120,
  "loopBeats": 8,
  "notes": [ [0.0, 0.25, 74, 103], [0.75, 0.25, 77, 103], [7.5, 0.25, 72, 103] ]
}
```

- Each note is `[startBeats, durationBeats, midiNote, velocity]` — **absolute** MIDI notes (60 = C4), beat-relative timing (quarter = 1.0), velocity 1–127.
- Keep it **2–8 bars**, musical, and in a **register that flatters the patch** (a bass phrase low, a lead line singing, a pad sustained). Match the role.
- **Length is a closed set: 2, 4 or 8 bars** (`loopBeats` 8, 16 or 32) — nothing in
  between. Notes must reach the **final bar**: an ending rest shorter than one bar is part
  of the phrase, but a whole bar of silence means the loop is longer than the melody. **8 bars is the ceiling everywhere**, including a MIDI
  file dropped in to make a custom melody, which is truncated past that point.
- ⚠ **A NOTE MUST OUTLAST THE PATCH'S OWN GESTURE, or the audition previews a fade-in.**
  This is the rule slow patches break. Work out roughly how long the sound takes to
  arrive and settle — `max(ampAttack, filterAttack) + filterEnvDecay` — and make at least
  one note in the phrase last longer than that. A pad with a 4 s attack and a 6 s filter
  decay needs a 10-second note somewhere; give it a half-bar chord and the listener
  hears the patch still swelling when it is cut off, judges it as thin or slow, and
  never hears the tone it actually settles into. **Loop length costs the listener
  nothing** — the phrase repeats and they move on whenever they like — so on a slow
  patch, err long.
- **The layered fix, when you want movement AND length:** hold a low root (and fifth)
  for the whole phrase and move the upper voices above it. The sustained voice runs the
  full gesture; the moving voices show how the patch behaves under changing harmony.
  Both at once, and it costs about 8 simultaneous voices out of 16.
- Playback follows host BPM; `bpm` is the Standalone fallback rate. `loopBeats` optional (derived from the last note if omitted).
- **Optional** — omit it and the preset falls through to the built-in category library (matched to `meta.category`) or the universal default.
- Never put `created`/`modified` inside it; no third-party names anywhere (house rule).

**Where it goes — sibling of `params`, not inside it:**

```jsonc
// ✅ CORRECT — melody beside params
{ "meta": { … }, "params": { "oscShape": 30.0 }, "melody": { "bpm": 120, "notes": [ … ] } }

// ❌ WRONG — melody nested in params (audition parser breaks / ignores it)
{ "meta": { … }, "params": { "oscShape": 30.0, "melody": { … } } }
```

### 5.2c Optional arpeggiator `arp` block

A preset MAY ship an arpeggiator pattern. The ARP is a lens on the mod-matrix
grid: **rows are held-position ladder indices** — **NOT fixed pitches**. The
same pattern arpeggiates whatever chord the player holds.

**Row map (11 rows, bottom to top):**

- **Rows 0–8 = the auto-wrap ladder.** Row 0 = the LOWEST held note. The held
  notes fill upward and then **wrap through ascending octaves until all 9 rows
  are full** — 1 held note gives 9 octave-stacked rows of it, a held triad
  gives 3 octaves of the triad. There is no octave param; the grid IS the
  octave control. Entries above MIDI 127 drop, and the ladder is contiguous —
  every row always sounds.
- **Row 9 = LFO 2 wildcard. Row 10 = LFO 1 wildcard.** A lit step on a
  wildcard row fires ONE note picked from the wrapped ladder by that LFO's
  global output at fire time (−1..+1 sweeps low→high). The LFO **shape** is
  the movement's character: S&H = a random ladder pick per step, a slow
  triangle sweeps the picks up and down the ladder, a fast sine skitters.
  Wildcard rows are where arp patches get their life — pair them with
  deliberate `lfo1Shape`/`lfo1Rate` (or `lfo2Shape`/`lfo2Rate`) choices in
  `params`. Shapes are `Sine` / `Triangle` / `Saw` / `Square` / `S&H`.
  **`lfo1Shape` defaults to `Sine` but `lfo2Shape` defaults to `Triangle`** —
  writing `"lfo2Shape": "Triangle"` is not sparse.
  **Before setting an LFO's shape/rate to serve a wildcard row, check that the
  preset does not route that LFO in the matrix** (`modAmt_1_*` = LFO 1,
  `modAmt_2_*` = LFO 2). Retuning a routed LFO changes the preset's sound;
  retuning an unrouted one is silent until the wildcard row uses it.

**Placement:** `arp` is a **top-level sibling of `params`** — beside it, never
inside it (same rule as `melody`).

```json
"arp": {
  "v": 1,
  "tmpl": "Up",
  "steps": [ { "r": 0,  "c": 0, "g": 0.5, "v": 1.0 },
             { "r": 1,  "c": 1, "g": 0.5, "v": 0.72 },
             { "r": 10, "c": 3, "g": 0.75, "v": 0.9, "m": 1 } ],
  "off": [ 4 ]
}
```

- `steps` is **sparse** — lit cells only. `r` = row 0–10 (see row map), `c` =
  step column 0–23, `g` = gate/length as a fraction of the step (use the
  ladder 0.25 / 0.5 / 0.75 / 1.0), `v` = velocity 0–1.
- `"m": 1` (optional, **wildcard rows only**) marks a **mirror** step: the
  pick inverts to 1−x — contrary motion against the LFO's sweep. Omit the key
  entirely for a normal step.
- `"off"` (optional, sparse) lists **bypassed row indices** — the row keeps
  its dots but is skipped by the engine. Omit when no row is bypassed.
- `tmpl` is a display label for the Template dropdown (`Up`, `Down`,
  `Up-Down`, `Pedal`, `Converge`, `Diverge`, `Random`, `As-Played`, `Chord`,
  `Strum`, `Stabs`) — the `steps` are the truth; the label just restores the
  menu (an unknown label is ignored, steps still load).
- The scalars live in `params`, NOT here: `arpOn` (bool), `arpHold` (bool),
  `arpSync` (`"Free"`/`"Tempo"`), `arpRateHz` (0.5–50, Free mode),
  `arpDivision` (same choice list as `lfo1Division`, default `"1/16"`),
  `arpLoopLen` (1–24), `arpSwing` (0–60 %).
- An arp preset should set `"arpOn": true` in `params`; a preset with no `arp`
  block loads with a blank pattern. A drawn pattern round-trips through save
  even with `arpOn` off.
- **When to flip `arpOn`.** Author the
  pattern with `arpOn` **false** and leave it off through the draft. It gets
  flipped to true **per preset, during that category's ear pass**, once the
  pattern has actually been heard against the patch. Two reasons: an unheard
  pattern should never ship engaged, and if every preset carrying a pattern
  loaded arping, the bank would read as an all-arp library rather than a
  synth whose presets happen to have arps.
- **`arpOn` true requires a COMPOSED pattern.** A `tmpl` key means the pattern
  was painted from the template roster; a composed one carries no `tmpl`. Never
  emit `arpOn` true with a `tmpl` present, or `arpOn` true with no `arp` block at
  all. Draw template patterns freely — just don't engage one until the pattern has
  been composed against the patch. A template pattern left engaged is consistently
  the weakest thing in a set.
- **`arpOn` is sparse-default false — never write `false`, drop the key.**
- **Read row numbers against how many notes are HELD.** Rows are ladder
  positions, not pitches: with a 4-note chord held, rows 0-3 are four chord
  tones in ONE octave and the figure never lifts. Rows 0/1/2/3 read as
  "very low" for exactly this reason, where 0/4/8 genuinely climbs; staying low
  is right *on purpose* for a bass. A pattern that wants octave motion must reach
  past the number of notes the player is likely holding.
- **ARMED vs ON.** `arpOn` alone does not take the keyboard. The
  arp only ENGAGES when the pattern can actually fire — at least one lit step
  **inside `arpLoopLen`**, on a ladder row or a wildcard row that is not
  switched off. `arpOn` with anything less is **ARMED**: the clock runs, the
  playhead sweeps, and the player's keys sound normally. Draw one step and it
  takes over. Consequences for authoring:
  a step drawn past `arpLoopLen` is *stored* but does not engage the arp, and
  neither does a lit step on a wildcard row you also switched off.
- **Free accent bonus:** each step's `v` reaches the matrix **Vel source** —
  route Vel → Cutoff and accent steps open the filter, no extra wiring.

### 5.3 Value rules

Three value kinds in `params`:

- **Numeric** (float / int): direct values in the parameter's documented range and units. Out-of-range silently falls back to default.
- **Boolean**: `true` / `false`.
- **Choice**: **store the LABEL, never the internal index.** `"Plate"` not `2`, `"Square"` not `2`, `"+1"` not `3`. This holds for **every** choice param with no exceptions — including the ones whose labels look numeric: `oscOctave` / `oscBOctave` are `"-2" "-1" "0" "+1" "+2"` (**the sign is part of the label** — write `"+1"`, not `"1"` and not `1`), and `unisonVoices` is `"1" "2" "3" "4"`. The loader matches the label exactly, then retries trimmed and case-insensitively, recording a warning — so a correct label always resolves and a near-miss is reported rather than silently defaulting.
  > ⚠ **Saved presets may show integers here.** The plugin can store `oscOctave` / `oscBOctave` as signed integers (`-1`); both forms load to the same octave. Authors write labels. **Never write a bare index** — for an octave the integer `2` means `"+2"`, not the third entry.

**The format is sparse — a preset is its diff from Init.** Include only params whose
value should differ from Init/default; omit everything else (the loader resets unset
params to their Init value). Omitting a param is an explicit "use the Init value
here," not "leave whatever was loaded before." Sparse files are smaller and easier to
review — and the `apvts` key is gone for good; emitting it gets the file rejected.

### 5.4 Modulation matrix encoding

Flat keys: `modAmt_<srcIdx>_<dstIdx>`. See §4.

Only include cells with non-zero amounts. A "blank" preset has no `modAmt_*` keys at all.

---

## 6. Category recipes

Each category has aesthetic rules, default ranges, signature mod-matrix routings, and a forbidden list. Pluck and Bass are the two most-detailed; the others give you mandatory rules and signature routings.

**Recipes are starting points, not templates** — each preset should still differentiate on tone-variety levers (`subShape`, `analogDrift`, `oscSat`, click engine settings, drive type, reverb type, filter cutoff zone) so the bank doesn't feel same-y.

> **The recipes pull every preset toward the category centroid — that pull is the enemy when authoring a batch.** A recipe describes the *prototypical* member of a category; following it faithfully for N presets produces N copies of the prototype. Before drafting any multi-preset batch, read **§7.0 (Divergence mandate)** and start from N distinct *archetypes*, using the recipe only to keep each one category-legal — not to shape them all alike.

> **About the mod-matrix amounts below.** The slot ranges in each category recipe (e.g. "Macro1 → FilterCutoff +60..+100") are reasonable starting points. On the ten knob-relative destinations the *musical depth* of a given amount depends on where the knob is parked (§4.7), and macros are bipolar. Audition is the source of truth — adjust slot values where the swing doesn't match the intended character.

### 6.0 Defining handle — the one lever per category

Before reaching for a recipe, know the **single lever that makes each category read correctly**. Get this one thing wrong and the preset reads as a different category no matter what else you do. Everything in the per-category recipes below serves the defining handle.

| Category | Defining handle | Gets it wrong → reads as |
|---|---|---|
| **Pluck** | Fast attack + short decay + featured Click/Transient (`transAttack` base ≥25) | leave Transient at 0 → flat, generic |
| **Bass** | Sub-dominant architecture (`oscOctave: 0`, sub carries weight) + filter-envelope bite (`filterEnvAmount` with `filterAttack` / `filterSustain`) | `oscOctave: -1` → mud |
| **Lead** | Audible release tail (`ampRelease` 100–500) + `Vel → FilterResonance` (negative) | no tail → cuts dry like a pluck |
| **Pad** | Multi-second `ampAttack` (500–3000ms) + high sustain + filter-ADSR bloom | <50ms attack → "soft pluck", not a pad |
| **Keys** | Moderate release tail (200–600ms) + velocity expression (≥2 Vel routings) | no velocity response → lifeless / not a keyboard |
| **Stab** | `filterEnvAmount` SNAP (50–80, short `filterEnvDecay`) + very low sustain + played POLY/chordal | long sustain → key/pad; mono → not a stab |
| **Drone** | ∞ sustain (`ampSustain` 85–100) + ultra-slow autonomous LFO morph (<0.12 Hz, ≥2 dests) | no LFO morph → static held note (the #1 drone failure) |

(Drone is a category recipe at **§6.8**. **§6.7** covers other voicings/styles — arp, bell, mallet, and the genre tints — which are *not* categories: each is authored under one of the 7.)

### 6.1 Pluck — the signature category

**Mood:** Percussive, decay-focused, atmospheric. Not pad. Not lead. Plucks are where the click + transient engine earns its keep — the category the synth grew up around.

**Mandatory rules:**
- `oscABMix` 30..80 (A-only is boring).
- `unisonDetune ≤ 10`, `oscAFine ≤ 10`, `LFO→Unison ≤ 10` (cap detune unless deliberately wide).
- `subLevel` 5..30 (don't drown the pluck).
- `delayMix` 0..30 — a small tail (0-15) OR an audible rhythmic color (15-30) when the pluck wants delay as a feature, not just ambience.
- `fxHpFreq` ~50-150 Hz — unlike Bass (which protects its fundamentals at 20 Hz), plucks want the master high-pass raised to clean low mud and tighten the attack. Plucks don't carry the sub weight, so there's nothing to protect down there.
- `ampSustain` 0..15 (>15 starts feeling pad-adjacent; >30 reads pad — character heuristic, not a hard cap).
- `ampAttack` ≤ 5 ms (loses the snap above 5; the full range to 32 s is reserved for Pad/Atmosphere/Drone — Pluck specifically lives at the bottom).
- `ampRelease` ≤ 50 ms (Plucks shouldn't have an audible release tail; default 20 ms is right).
- `filterCutoff` static ≥ 600 Hz (kills body below 600).

**Default ranges:**

| Param | Range | Notes |
|---|---|---|
| `ampDecay` | 400-700ms | Reserve <300 for explicitly "snap" character. |
| `ampAttack` | 2.5-4 (soft/wire) OR 0.1-0.5 (icy/glassy) | Pick a side — middle (1-2) is rarely right. |
| `ampRelease` | 8-30 ms | Keep tight. >50 ms reads as Lead/Key territory. |
| `ampSustain` | 0-15 | Plucks are tail-shaped, not held — keep low. |
| `filterCutoff` | 800-3000 Hz | 4000+ is a deliberate "icy" choice, NOT a default. |
| `filterAttack` | 0 (default) | Plucks want instant filter open — leave at 0. |
| `clickTone` | 730-1520 Hz (warm/round) | 1830 Hz+ for explicitly bright/glassy only. |
| `clickLevel` | 50-70 when click is featured | Don't default at 30-45. |
| `clickDecay` | 8-18ms for "thunk/body" | Short <8ms = "tick". |
| `transAttack` | 25-50, default ~30 | **Signature pluck tool — set a base value, don't leave at 0.** The Transient shaper is one of Palora's defining tools (Click + Transient have no direct equivalent in a plain subtractive layout). Soft/felt/wire plucks lean 25-35; snappy/percussive 35-50. On **Analog** topology it bites hardest (harmonics for the detector); on **Modern** it's weaker — lower `transPunch` into the passband or lean on `oscSat`. Then route `Vel → TransAttack` on top for dynamics. |
| `transPunch` | 200 (default for Pluck) | High-pass corner (§3.8): 200 Hz lets every note snap. Raise the corner only when low notes should be left alone — the higher it goes, the more low notes and dark sounds stop reacting. |
| `oscSat` | 0-20 clean OR 50-70 grit | Don't cluster at 30-40. |
| `unisonVoices + unisonDetune` | 2 voices + 6-8 detune for bright/wide/playful | Stereo width is a "presence" signal. |
| `lfo1Rate` (when matrix-routed) | 0.2-0.5 Hz | 1-2 Hz reads as wobble, not breath. |

**Signature mod-matrix (≥4 routings, no pitch):**

| Routing | Amount | Role |
|---|---|---|
| `Vel → TransAttack` (modAmt_7_16) | +30..+50 | Harder hits bite more |
| `Vel → AmpDecay` (modAmt_7_14) | -25..-50 | Harder = shorter |
| `Vel → ClickLevel` (modAmt_7_8) | +20..+40 | Harder = punchier transient |
| `Vel → FilterCutoff` (modAmt_7_10) | +25..+50 | Harder = brighter |
| `Vel → FilterResonance` (modAmt_7_11) | -20..-40 (or + for acid Plucks) | Soft hits get singy reso, hard hits stay focused |
| `LFO1 → FilterCutoff` (modAmt_1_10) | ±15..30 (slow ≤0.5 Hz) | Slow shimmer |
| `LFO2 → OscBShape` (modAmt_2_3) | ±10..20 (slow) | Body morph |
| `LFO3 → FilterResonance` (modAmt_9_11) | ±15..25 (slow) | Vowel-y filter morph under the pluck |
| `ENV1 → FilterCutoff` (modAmt_3_10) | +20..+40 (env1Decay 350-1400ms) — **NOT signature** | Brief attack bite, but the dedicated filter envelope (`filterEnvAmount` + `filterAttack`/`filterEnvDecay`/`filterSustain`) is the preferred engine for this — see §4.5d. Reach for the matrix route only when the filter ADSR is not enough, or when the sweep must go DOWNWARD (which `filterEnvAmount` cannot express). |
| `ENV1 → FilterResonance` (modAmt_3_11) | +20..+40 (env1Decay 200-700ms) | self-singing bite on the transient, drops out by sustain |
| `ENV1 → OscMix` (modAmt_3_2) | +15..+30 | Brief B-blend over attack |
| `Macro1 → FilterCutoff / Drive / ChorusMix / FilterResonance` (modAmt_4_10/17/18/11) | +60..+100 | The macro knob |
| `MW → ReverbMix / DelayMix / ChorusMix` (modAmt_6_21/20/18) | +30..+50 | Wash on demand |
| `AT → FilterCutoff / TransAttack / OscMix` (modAmt_8_10/16/2) | +20..+40 | Pressure expression |

**Reverb-type character map:**
- "Room" — intimate wood/mallet plucks
- "Hall" — shimmer/glass/lush plucks
- "Plate" — classic ambient pluck
- "Spring" — metallic/synthetic

**Don't:**
- `ampSustain > 30` (that's a pad — character rule, not a range cap).
- `ampAttack > 5 ms` (Plucks live at the bottom of the now-32 s range).
- `ampRelease > 50 ms` (audible tail reads as Lead/Key).
- `oscShape ≈ oscBShape` AND same octave AND same pulse settings — that's wasted second oscillator.

### 6.2 Bass — sub-anchor deep-house bass

**Aesthetic anchor:** Deep-house tradition — warm and round low end, snappy/short envelopes, no mud.

**Architecture (load-bearing):**

Palora Bass uses a **sub-dominant architecture**. Sub is locked at MIDI × 0.5 (one octave below played note), independent of `oscOctave`. The bass anchor lives in the SUB; oscillators provide harmonic edge.

| Setup | Result |
|---|---|
| **`oscOctave: 0`, `subLevel` high** | Bass anchor in sub, harmonic edge in osc — **deep house** ✓ |
| `oscOctave: -1`, `subLevel` high | Doubled mid-bass, no harmonic edge — **mud** ✗ |
| `oscOctave: -2` | Too deep for melodic playing |

**Mandatory rules:**
- `oscOctave: 0` (NEVER -1 or -2 — sub carries the bass weight).
- `subLevel: 50..65` (raise to 65-70 for sub-anchor variants).
- `oscABMix: 30..55`.
- `unisonDetune ≤ 10`, `oscAFine ≤ 10`.
- `ampDecay: 200..350` (deep house never sustains long).
- `ampAttack: 0.3..1.5` (quick, NOT click-y; soft 1.5-2.5 for "round/intimate").
- `ampSustain ≤ 25` (bass not pad — but real basses carry more body than a pluck; ear-checks landed most around 15-20, not near zero).
- `filterCutoff: 600..1200` (warm round) OR `1300..1600` (bright/clean punch). Avoid <600 (mud) and >1600 (loses bass-class identity). The warm zone centres LOW in practice (~600-700).
- `reverbMix: 5..18` (deep house = nearly dry).
- `delayMix: 0..10` (subtle color, not rhythmic feature).
- `drive: 6..18` for clean (most), `30-60` only for explicit grit-bass character.
- Leave `fxHpFreq` at default 20 Hz for sub-anchor presets — don't kill the fundamentals by raising the master HP.
- **`filterBassComp: true`** — turn the +6dB low-shelf ON. Bass reliably wants it; it replaces the low end the ladder eats.
- `fxLpFreq: 1500..3000` — roll the master low-pass DOWN to tame fizz/hiss up top (the default 20000 is too open for bass).
- `oscSat: 5..15` — a little pre-filter oscillator grit for weight and harmonic edge; **essential under Modern topology** (survives the clean filter, which has none of the ladder's own saturation).
- **When the preset uses the Transient shaper:** `transPunch` at its lowest, **200 Hz** — the corner then sits below the whole bass, so the punch lands on the full note. For bite, run `transMix` **high**, not restrained.
- **The filter's OWN ADSR is the per-note motion engine on bass** (not the matrix — see the signature note on ENV1→FilterCutoff): `filterAttack` up to ~150 ms for a soft filter-onset swell, `filterSustain 40..65` so the filter env holds a floor instead of slamming shut, `KeyTrack → FilterCutoff` (`modAmt_10_10`) +30..+48 so cutoff tracks pitch, and `Vel → FilterCutoff` (`modAmt_7_10`) +25..+40 for velocity→brightness dynamics.
- Click voicing for bass: `clickBody: Sub`, `clickTone: 200` (dark, the 200 Hz floor), audible `clickLevel` (~40-55) — a sub-thump attack, not a noisy tick.
- **Consider `mono: true`** for performance-bass character (legato, single-voice, glide-friendly). Bass that gets played as a melodic line (deep-house bass, sub-bassline, dub-bass) usually wants Mono — overlapping voices on a sub-dominant preset compound into rumble and obscure note articulation. `mono: true` lets `glide` (8-30ms) read as expressive portamento between notes. Default Poly (`mono: false`) is fine for arpeggiated/chord-stab basses where multiple notes ring simultaneously. Decide per-character: is this bass played as a LINE (Mono) or as STACKED HITS (Poly)?

**Forbidden:**
- `oscOctave: -1` or `-2`.
- `ampSustain > 25` (that's pad territory).
- `ampDecay > 400` (that's a pluck-bass, not deep-house bass).
- `filterCutoff < 600` static.
- `reverbMix > 20` (smears low end).
- Pulse-osc + dotted-delay combinations (reads as EDM).
- `oscBFine` 1-7 with `oscBOctave: 0` — **BEAT TRAP** (see §3.2). Use 0 or 12+.

**Signature mod-matrix (≥1 Group-1 routing HARD floor):**

| Routing | Amount | Role |
|---|---|---|
| `LFO1 → FilterCutoff` (modAmt_1_10) at 0.2-0.4 Hz | ±10..18 | Slow filter motion under fingers — THE deep-house bass move |
| `LFO1 → Sub` (modAmt_1_7) at 0.20 Hz | ±6..12 | Subtle "heartbeat" on the sub |
| `ENV1 → FilterCutoff` (modAmt_3_10) | +10..+25 (NOT signature) | Per-note attack-bite — but the filter's OWN ADSR (see mandatory rules) is the preferred engine for this on bass. Deep values on a closed-cutoff bass turn to mud; auditions routinely ZEROED this route in favour of `filterAttack`/`filterSustain`. Reach for it only when the filter ADSR isn't enough and you want the extra sweep. |
| `ENV1 → FilterResonance` (modAmt_3_11) | +20..+35 (env1Decay 350-1000ms) | per-note reso bite, drops by sustain (acid-house adjacent without going acid) |
| `ENV1 → OscMix` (modAmt_3_2) | +18..+30 | B blends in for attack body |
| `ENV1 → FilterEnvAmount` (modAmt_3_12) | +20..+40 | env-shape modulation, deeper attack sweep per note |
| `Macro1 → Drive` (modAmt_4_17) | +30..+50 | The "more growl" macro |
| `Macro1 → FilterCutoff` (modAmt_4_10) | +30..+50 (or +60..+100) | The "open up" macro |
| `Vel → FilterCutoff` (modAmt_7_10) | +25..+45 | Per-note dynamics |
| `Vel → TransAttack` (modAmt_7_16) | +30..+50 | Harder = punchier |
| `Vel → FilterResonance` (modAmt_7_11) | -20..-35 | Soft hits get singy bass, hard hits stay focused |
| `Vel → ClickLevel` (modAmt_7_8) | +20..+35 | Harder = sharper attack |

### 6.3 Lead

**Mandatory rules:**
- `oscOctave` = 0 or +1 (never -2).
- `subLevel ≤ 14` (Leads aren't basses).
- `delayTime: "1/16"` (color, not rhythm); `delayMix ≤ 15`.
- `ampSustain` 25..40 (Leads hold a bit more than Plucks, but still snap-forward, not full-pad).
- `ampDecay` 250..600ms.
- `ampRelease` 100..500ms (audible tail is what makes a Lead sustain into the mix vs. cut dry).
- LFO matrix rates ≤2 Hz, often 0.3-0.5 Hz.
- `unisonDetune ≤ 10`.
- **Click/Transient OFF by default — never the every-preset reflex.** The mistake that reads as "too much attack" is putting Click + Transient on *every* lead; the click-transient engine belongs primarily to **Pluck, Keys, Stab, and (lightly) Bass**. A lead is a *line*, not a struck note, and its articulation comes mainly from the **amp/filter envelope**. **But "mostly off" is literal, not "never"** — reach for them *intentionally, per-preset*: a touch of Click for a bright anthem's pick attack (e.g. an FM click on a supersaw), light **positive** `transAttack` for brass bite, or **negative** `transAttack` to *soften/round* an attack that's too hard. The default state is off; engaging them is a deliberate character choice, not a template field.
- **Soft brass-swell attack is the 80s-anthem default** — `ampAttack` 5-14 ms reads as a warm brass/poly swell. Reserve 2-4 ms for explicitly bright/fast saw fanfares. Never 0.5 ms (that's pluck territory and just sounds abrupt without Click).
- **Glide ≈ 5 ms on mono leads** (NOT 40-60). High glide smears articulation and sounds seasick on moving lines. ~5 ms reads as gentle note-connection; reserve obviously-audible glide for a deliberate "slide lead" and even then keep it modest. Often the better move is **poly + wide unison instead of mono+glide** — ensemble width reads richer than a slurred mono.
- **Osc B an octave DOWN (`oscBOctave` -1, occasionally -2) for body** — drops weight under the lead. Octave-UP (+1) reads thin; use it only for an explicit bright shimmer/bell layer.
- **Leads want space + EQ shaping**: `reverbMix` **40-65** (often Hall), and engage the post-FX EQ — `fxHpFreq` **75-175 Hz** to cut low mud (leads aren't basses) and `fxLpFreq` **6-14 kHz** to tame fizz. (Shipping these flat/dry reads as a thin, in-your-face lead.)
- **Wide unison is the lead default** — `unisonVoices` 2-4, `unisonDetune` 8-20, high `unisonSpread`. Pair with the slow `LFO1 → Unison` ensemble warble.

**Signature mod-matrix:**
- `LFO1 → Unison` (modAmt_1_6) ±4..14, slow (≤0.5 Hz) — **Lead-signature ensemble warble**: unison voices breathe apart/together around a stable center. Reads as gentle vibrato-like motion with zero center-pitch wobble. **Requires unisonVoices ≥ 2 — silent no-op on single-voice presets.** (Also legal on other sustained categories — see §4.5 Tier 3 exception.)
- `Aftertouch → Vibrato` (modAmt_8_22) +35..+60 — **the 80s-lead expressive gesture**: press into a held note and it blooms into a singing vibrato (dedicated coherent vibrato, ~5.5 Hz; bake a small always-on `vibratoDepth` 3-6 ct for motion at rest). `ModWheel → Vibrato` (modAmt_6_22) is the wheel-driven alternative. This *replaces* the old pressure-adds-punch transient gesture.
- `Vel → FilterResonance` (modAmt_7_11) **negative** -20..-50 for most leads, **positive** for acid leads.
- `Aftertouch → FilterResonance` (modAmt_8_11) +20..+40 — singing reso under pressure (Lead-signature gesture).
- `ENV1 → FilterAttack` (modAmt_3_13) negative, amount per §4.7 — env can pull filter attack faster on its own envelope shape (use for snap-then-relax leads).
- `ENV1 → FilterCutoff` (modAmt_3_10) +35..+55 — **NOT signature.** The per-note filter flick that gives an articulate lead its "flick open" without any Click. ⚠ the dedicated filter envelope (`filterEnvAmount` + `filterAttack`/`filterEnvDecay`/`filterSustain`) is the preferred engine for this — see §4.5d; use the matrix route when the flick must close rather than open, or when the Group-1 floor needs filling.
- `Macro1 → FilterAttack` (modAmt_4_13) positive, amount per §4.7 — user-controlled "attack speed" macro for performance (turn it up to soften, down to snap).

**Default ranges:**

| Param | Range | Notes |
|---|---|---|
| `ampAttack` | 5-14 (soft/brassy 80s default) OR 2-4 (bright saw fanfare) | The lead's articulation lives in the *envelope*, not a transient. Never 0.5 ms. |
| `ampDecay` | 250-600 ms | Longer than a pluck — the line needs to sing. |
| `ampSustain` | 25-40 | Holds more than a Pluck, less than a Pad. |
| `ampRelease` | 100-500 ms | **The defining Lead tail** — what makes the line sustain into the mix vs. cut dry. |
| `filterCutoff` | 1000-3500 Hz | Bright enough to cut, not icy. |
| `subLevel` | ≤14 | Leads aren't basses. |
| `vibratoDepth` | 3-6 ct baked, +35..+60 via AT/Wheel | Always-on shimmer + expressive bloom. The signature lead motion now that Transient is off. |
| `delayTime` / `delayMix` | "1/16" / ≤15 | Color, not a rhythmic tap. |

**Topology:** **Analog** for warm/vintage/brassy/throaty leads (the default — harmonic richness suits sustained lines). **Modern** only for an explicitly clean/glassy lead AND when Filter Decay stays short.

**Don't:**
- **Default Click/Transient onto every lead** (the every-preset reflex is what reads as "too much attack" — off by default, intentional per-preset only; see mandatory rules).
- `glide > ~15 ms` unless it's a deliberate slide-lead (40-60 ms smears the line).
- `oscBOctave +1` for body (reads thin — octave DOWN adds weight; +1 is for shimmer layers only).
- Ship leads bone-dry (`reverbMix < 30`) or with flat post-EQ — leads want space + a low-mud high-pass.
- `ampAttack < 2 ms` (without Click it just sounds abrupt; with Click it's a Pluck).
- `subLevel > 14` (muddy lead).
- `ampRelease < 80 ms` (cuts dry — loses the lead-into-mix sustain that defines the category).
- `ampSustain > 50` (becomes a pad-lead).
- `delayMix > 15` as a rhythmic feature (that's Arp/dub territory).
- Any fast LFO in the matrix — including fast `LFO → Unison` (fast spread warble = detune chaos). The slow ensemble-warble above is the only exception.

### 6.4 Pad

**Mandatory rules:**
- `delayTime: "1/16"`, `delayMix` 0..15.
- LFO rates very slow (often <0.3 Hz — Pads should be SLOWER than Leads).
- **`ampAttack` 500..3000 ms for "soft swell" pads, 3000..8000 ms for "full bloom" pads.** The `ampAttack` range goes to 32000 ms. The default 0.5 ms is pluck territory; even 50 ms still reads "soft pluck" not "pad." A Pad's defining gesture is "the note arrives late, swelling into the texture" — that takes seconds, not milliseconds. For an extra moment at peak before decay starts, use `ampCurve` 30-45 (decay-hold).
- `ampSustain` 60..90 (Pads ARE pad-sustain — without high sustain even a slow attack just decays into nothing).
- `ampCurve` 40..55 (near-linear decay; below 50 holds the peak a moment, the bloom-friendly direction; stay well under 60 so it doesn't turn plucky).
- `ampRelease` 1000..5000 ms (the note has to fade *out* of the texture, not cut).
- `oscABMix` 40..70 (thick sound).
- **Use the filter envelope's full ADSR** — pads should engage all four stages:
  - `filterAttack` 500..3000 ms (timbre bloom matches amplitude bloom — filter opens *with* the swell)
  - `filterSustain` 30..70 (holds the filter open under the held note — otherwise it decays to zero and the pad goes dark mid-note)
  - `filterRelease` 500..3000 ms (filter closes alongside the amplitude release)
- Heavy reverb: `reverbSize` 60..80, `reverbMix` 25..40.
- Unison `unisonVoices: 2` with detune 6-10 + spread 70-90 + drift 30-50 for proper Pad width (rule #13 — chorus-only width is too thin for Pads).

**Signature mod-matrix:**
- `LFO1 → FilterCutoff` (modAmt_1_10) ±20..40 SLOW.
- `LFO2 → OscMix` (modAmt_2_2) ±15..30 SLOW.
- `LFO3 → AmpSustain` (modAmt_9_15) ±10..20 SLOW — breathing sustain across the note (subtle, audible on held chords).
- `LFO1 → FilterResonance` (modAmt_1_11) ±15..25 SLOW — vowel-y filter morph, hugely effective on Pads.
- `LFO2 → FilterEnvAmount` (modAmt_2_12) ±15..30 SLOW — env-shape sign flips across the LFO cycle.
- `ModWheel → ReverbMix` (modAmt_6_21) +30..+50.
- `Macro1 → FilterAttack` (modAmt_4_13) positive, amount per §4.7 — user-controlled bloom speed. Combined with the slow `ampAttack`, the macro turns "instant pluck → slow pad" under one knob.
- `ENV1 → FilterCutoff` (modAmt_3_10) +25..+45 — **NOT signature**, the dedicated filter envelope (`filterEnvAmount` + `filterAttack`/`filterEnvDecay`/`filterSustain`) is the preferred engine for this — see §4.5d — with **"long bloom" ENV1 ADSR** (`env1Attack` 50-200 ms, `env1Decay` 3500-10000 ms, `env1Sustain` 0-20). The amp Envelope handles the AMPLITUDE bloom; ENV1 routed to filter handles the TIMBRE bloom — together they give you a slowly-opening cloud of sound.

### 6.5 Keys

**Mood:** Struck-and-rings keyboard instruments — electric piano, FM keys, clav, soft synth-keys. Shape-wise **between Pluck (percussive onset) and Pad (sustained body)**: a clear attack that rings into a moderate tail, played as chords/comping. **The defining trait is velocity expression** — a keyboard instrument that doesn't respond to how hard you play reads as lifeless.

**Mandatory rules:**
- `ampAttack` 0.5..8 ms — a struck onset, a touch softer than the icy Pluck attack but still an *attack*, not a swell.
- `ampDecay` 400..1500 ms — rings longer than a pluck.
- `ampSustain` 20..50 — holds under the fingers, but not a pad.
- `ampRelease` 200..600 ms — **the defining Keys tail.** <150 ms reads as a Pluck; >800 ms drifts into Lead/Pad.
- `ampCurve` 50..65 (linear to mildly plucky — EP/Rhodes decay has a gentle initial drop).
- `subLevel` ≤ 20 — Keys aren't basses; a touch of sub for EP/Rhodes low-end body is fine up to ~20.
- `oscABMix` 30..70 — two oscillators give the keyboard body (EP tine + body, FM operator pair).
- `filterCutoff` 1200..4000 Hz — EPs sit warmer (1200..2200), FM/clav brighter (2500..4000).
- `reverbMix` 10..30 — Keys want a room/plate space; rarely dry.
- `delayMix` 0..15.
- **Velocity matters** — route `Vel → FilterCutoff` (`modAmt_7_10`) and/or ≥2 other velocity destinations (see signature matrix). Keys are velocity instruments.

**Topology:** **Analog** for warm electric-piano / Rhodes / vintage keys (harmonic richness, soft attack suits the EP body). **Modern** for clean digital / FM / glassy keys where attack faithfulness and clarity matter.

**Default ranges:**

| Param | Range | Notes |
|---|---|---|
| `ampAttack` | 0.5-8 ms | EP/soft 3-8, brighter FM/clav 0.5-2. |
| `ampDecay` | 400-1500 ms | Longer ring than a pluck. |
| `ampRelease` | 200-600 ms | The keyboard tail — the load-bearing trait. |
| `ampSustain` | 20-50 | Held but not a pad. |
| `filterCutoff` | 1200-4000 Hz | Warm EP low end, bright FM/clav high end. |
| `transAttack` | 10-30 | A keyboard's onset has body, not a heavy transient snap. |
| `chorusMix` | 12-30 | Classic EP/Rhodes shimmer — chorus is at home here. |

**Signature mod-matrix (velocity-forward — ≥2 Vel routings + ≥1 Group-1):**

| Routing | Amount | Role |
|---|---|---|
| `Vel → AmpDecay` (modAmt_7_14) | -25..-50 (or +25..+50 for "harder = longer") | Velocity shapes the ring — the core keyboard response |
| `Vel → FilterCutoff` (modAmt_7_10) | +25..+45 | Harder = brighter (struck-harder = more tine/harmonics) |
| `Vel → TransAttack` (modAmt_7_16) | +25..+40 | Pressure-keyed attack bite |
| `LFO1 → FilterCutoff` (modAmt_1_10) | ±12..25 (≤0.4 Hz) | Slow shimmer under sustained chords (Group-1 floor) |
| `ENV1 → FilterCutoff` (modAmt_3_10) | +20..+40 (env1Decay 700-2000 ms) — **NOT signature** | Per-note timbre bloom on the strike, but the dedicated filter envelope (`filterEnvAmount` + `filterAttack`/`filterEnvDecay`/`filterSustain`) is the preferred engine for this — see §4.5d. |
| `ModWheel → ChorusMix` (modAmt_6_18) | +30..+60 | Performance "add the EP shimmer" |
| `Aftertouch → FilterCutoff` (modAmt_8_10) | +20..+40 | Pressure expression (light — many keyboards lack AT) |

**Reverb-type map:** "Room" — intimate EP/clav. "Plate" — classic EP ballad sheen. "Hall" — lush ambient keys. "Spring" — vintage/retro electric piano.

**Don't:**
- `ampRelease < 150 ms` (loses the keyboard tail → reads as a Pluck).
- `ampSustain > 60` (becomes a Pad).
- `ampAttack > 10 ms` (loses the struck onset).
- Ignore velocity — a Keys preset with zero velocity routings is the #1 Keys failure.

### 6.6 Stab

**Mood:** The house/dance **chord stab** — short, sharp, played as chords on the off-beats. The defining gesture is a **fast filter-envelope SNAP** (open-and-close) over a very short note: organ stab, brass stab, pluck-stab. Punchy, rhythmic, percussive-but-pitched. Stabs are **chordal** — they're played as stacked notes, so they stay **Poly**.

**Mandatory rules:**
- `ampAttack` 0.3..2 ms — sharp onset.
- `ampDecay` 120..350 ms — short; the stab cuts off fast.
- `ampSustain` 0..15 — very low; stabs don't hold.
- `ampRelease` ≤ 80 ms — tight cutoff. The stab must end cleanly so the rhythmic gaps between stabs stay open.
- **`filterEnvAmount` 50..80** — **THE stab handle.** A sharp filter-env open-and-close gives the snap.
- **`filterEnvDecay` 100..300 ms** — the snap closes quickly (pairs with the short amp decay).
- `filterCutoff` 1000..3000 Hz base — the env sweeps *up* from here.
- `oscABMix` 30..70 — pulse on an oscillator (`oscAPulse`/`oscBPulse`) adds classic organ-stab bite.
- **`mono: false`** — stabs are chordal. Don't set mono.
- `reverbMix` 10..30 (a short plate/room tail flatters stabs); `delayMix` 0..20 — an eighth or dotted delay is a classic stab move, but watch the EDM-cheese line.

**Topology:** **Modern is a genuine fit here** — stabs want short Filter Decay, which is exactly Modern's "clean-and-short" territory; the clean ladder gives a sharp, clean snap. Use **Analog** when the stab wants warmth/grit instead of clean snap. (This is one of the few categories where Modern is a first-choice rather than a niche pick.)

**Default ranges:**

| Param | Range | Notes |
|---|---|---|
| `ampDecay` | 120-350 ms | Short. >400 stops reading as a stab. |
| `ampSustain` | 0-15 | Percussive, not held. |
| `filterEnvAmount` | 50-80 | The snap depth — the category's signature. |
| `filterEnvDecay` | 100-300 ms | How fast the snap closes. |
| `filterCutoff` | 1000-3000 Hz | Base; env sweeps up from here. |
| `clickLevel` | 40-65 | A defined onset sharpens the stab attack. |

**Signature mod-matrix (≥1 Group-1 floor):**

| Routing | Amount | Role |
|---|---|---|
| `Vel → FilterCutoff` (modAmt_7_10) | +40..+70 (heavy) | Harder = brighter snap |
| `Vel → FilterEnvAmount` (modAmt_7_12) | +30..+50 | Harder hits get a deeper env sweep |
| `Vel → AmpDecay` (modAmt_7_14) | -30..-50 | Snappier on hard hits |
| `ENV1 → FilterCutoff` (modAmt_3_10) | +30..+50 (env1Decay 550-1400 ms) — **NOT signature** | Per-note bite, and it satisfies the Group-1 floor — which the filter envelope does NOT, since it is not a matrix routing. That is the one structural reason to prefer it here; otherwise the dedicated filter envelope (`filterEnvAmount` + `filterAttack`/`filterEnvDecay`/`filterSustain`) is the preferred engine for this — see §4.5d. |
| `Macro1 → FilterEnvAmount` (modAmt_4_12) | +50..+70 | Dial the snap in/out — performance "intensity" macro |
| `Macro1 → ChorusMix` (modAmt_4_18) | +20..+40 | Width macro |
| `ModWheel → DelayMix` (modAmt_6_20) | +30..+60 | Rhythmic-wash performance move |

**Don't:**
- `ampSustain > 20` (loses the stab punch → becomes a Key/Pad).
- `ampDecay > 400 ms` (too long — not a stab).
- `ampRelease > 100 ms` (smears the rhythmic gaps between stabs).
- `mono: true` (stabs are chordal — mono collapses the chord).
- Long Filter Decay on Modern topology (oil-drum — but stabs want short decay anyway, so this rarely bites).

#### 6.6.1 Dub Stab — a named archetype (overrides the §6.6 defaults by design)

A Palora **Dub Stab** is a specific resonant, squelchy chord-stab archetype, not a generic dub-flavoured stab. It deliberately sits **outside** the §6.6 default ranges for `filterCutoff`, `filterResonance` and `filterEnvAmount` — that is the identity, not a mistake, so do not "correct" it back into range.

- **Filter — the identity.** `filterTopology: "Modern"`. A **very low base `filterCutoff` (≈250–400 Hz)** with **very high `filterResonance` (≈90–100)** and **`filterEnvAmount` near 100**, closed by a **very short `filterEnvDecay` (≈80–140 ms)**. The result is a pronounced resonant "boing" / squelch — a rubbery, pitch-like sweep at the start of every chord.
- **Envelope.** Short: `ampSustain` 0 (or near zero), `ampDecay` ≈120–220 ms. `ampAttack`/`ampRelease` as §6.6.
- **Body.** `drive` moderate-to-high (the 40–70 "featured" band of §3.9) for weight and character. Two oscillators contributing **noticeably different harmonic material** (shape, pulse, octave — not a near-copy); `unisonVoices` 2–4 for body and width.
- **Space — the defining element.** A **strong rhythmic delay**: `delaySync: true`, `delayTime: "1/8d"`, `delayFeedback` ≈35–50, `delayMix` ≈55–70. Support it with a restrained `reverbType` "Hall" or "Plate" at `reverbMix` ≈10–20.
- **FX filtering, controlled.** `fxHpFreq` ≈100–150 Hz, `fxLpFreq` ≈6000–9000 Hz.
- **Modulation.** Small amounts to `FilterResonance` (dst 11) or `FilterCutoff` (dst 10) can animate the squelch further — keep them small; the archetype is already extreme.

**The essential identity is the combination:** low cutoff + extreme resonance + fast filter-envelope snap + prominent rhythmic delay. Drop any one and it is a different stab.

### 6.7 Other voicings & styles — authored under the 7 categories

These are sound *styles*, not categories. **Category is a closed set** (Pluck, Bass, Lead, Pad, Keys, Stab, Drone — or Uncategorized; see §5), so a preset in one of these styles takes the **closest role category**. The craft below still applies — just file the result under the mapped category. (Arp, Bell, Mallet, FX, Atmosphere, Cinematic, Lo-Fi and Synthwave are not category values — they live on here as styles.)

- **Arp** → category **Pluck** (or **Lead**). The arpeggiation lives in the melody/playing, not the patch — the *sound* is a pluck or a lead. Signature: `ModWheel → DelayMix` (modAmt_6_20) +30..+60; `Macro1 → FilterCutoff` (modAmt_4_10) +30..+60; `LFO1 → FilterResonance` (modAmt_1_11) ±15..25 SLOW (0.1-0.2 Hz, so each note in the pattern gets a slightly different filter color). **Don't** route `LFO → Unison` — width breathing across an arpeggiated pattern reads as instability (and is a no-op on single-voice patches).

- **Bell** → category **Keys** (or **Pluck**) — struck-and-rings. Signature: `Vel → TransAttack` (modAmt_7_16) +30..+50; `LFO3 → AmpAttack` (modAmt_9_9) ±20 SLOW — breathes the strike's attack time; `ENV1 → FilterResonance` (modAmt_3_11) +25..+45 with a **decay-only ENV1** (`env1Sustain` = 0, env1Decay 350-1000 ms) — resonant ping on note-on that drops out fast.

- **Mallet** → category **Pluck**. Pluck-adjacent, shorter attack, percussive body emphasis. `ampRelease` 8-30 ms (tight, like Plucks).

- **FX** → category **Drone**/**Pad** (or Uncategorized). Everything LFO-chained, macros fully assigned, textural not melodic. Free to push extreme `ampAttack` (10+ s) or `ampDecay` for drone/wash. Heavy `Macro → FilterAttack` and `Macro → AmpSustain` for performance morphing. Even here: no pitch routings — static `oscBFine` for dissonance.

- **Atmosphere** → category **Pad** (or **Drone**). Pad-adjacent, even slower modulation, unusual tonal centers. **Push `ampAttack` to 3000-10000 ms for full drone-bloom onsets** — later than Pads. Pair with `ampSustain` 80-95, `ampRelease` 3000-8000 ms; filter follows (`filterAttack` 3000-8000 ms, `filterSustain` 50-80, `filterRelease` 3000-5000 ms).

- **Cinematic** → category **Pad** or **Lead**. Hall reverb dominant; late `ampAttack` 1500-5000 ms paired with matching `filterAttack` 1500-5000 ms (amplitude + timbre bloom together = the cinematic-arrival gesture).

- **Lo-Fi** → category of the underlying role (often **Keys**/**Pluck**). A *treatment*: lower `fxLpFreq` (~3-5 kHz), higher `analogDrift` (50+), Plate or Spring reverb, slower pluck attack (`ampAttack` 5-20 ms reads as "tape transient softening").

- **Synthwave** → category **Lead** (or **Pad**/**Bass** by role). Bright, saw-leaning, chorus-heavy, Hall/Plate reverb, gentle ensemble warble via `LFO1 → Unison` (modAmt_1_6, unisonVoices ≥ 2) for center-stable shimmer. For true pitch vibrato Palora now has a dedicated coherent vibrato — bake it with `vibratoDepth` (>0) or route it expressively via the Vibrato depth dest (slot 22), e.g. `Aftertouch → Vibrato`.

### 6.8 Drone — sustained, evolving, non-resolving texture

**Mood:** A sustained tone that simply *is* and slowly morphs — **motion-within-stasis**. No perceptible attack transient, no decay-to-silence: the pitch holds and the timbre breathes. **Distinct from an Atmosphere-style Pad** (§6.7 — pad-adjacent and tonally wandering): a Drone is even more static and sustained, often anchored on one tonal center, and its whole character lives in the slow timbral evolution of a held note rather than in arrival/onset gestures.

**The defining handle — autonomous slow LFO morph is NON-NEGOTIABLE.** A held note with no LFO morph is a static drone, which is the #1 Drone failure. Use **≥2 slow LFOs on different destinations at different rates** (e.g. Cutoff + OscMix, or Cutoff + FilterResonance) so the morph never feels periodic or phase-locked. ENV1 (per-note shaping) is largely irrelevant on a drone — the notes are held, not struck.

**Mandatory rules:**
- `ampAttack` 2000..10000 ms — a slow bloom into the texture. (A deliberately "instant-on, just-there" drone can use a short attack, but the slow bloom is the signature.)
- `ampDecay` 5000..32000 ms — effectively never decays within musical time.
- **`ampSustain` 85..100** — **load-bearing.** The note must hold indefinitely; below ~80 it collapses into a pad-decay.
- `ampCurve` 40..55 (near-linear; with sustain this high the decay shape barely matters, but keep it ≤55 so a held note doesn't develop a plucky dip).
- `ampRelease` 2000..8000 ms — fades *out* of the texture, never cuts.
- **Engage the full filter ADSR:** `filterAttack` 2000..8000 ms, `filterSustain` 60..90 (holds the filter open under the endless note — without it the drone goes dark mid-note), `filterRelease` 2000..6000 ms.
- `oscABMix` 40..80 + `unisonVoices` 2+ (detune 6-10, spread 70-90) — drones need body and width.
- **`analogDrift` 40..70** — organic per-voice drift is hugely effective on a sustained note (keeps it alive without an LFO doing all the work).
- LFO rates **ULTRA slow (<0.12 Hz** — 8-30+ second periods; drones are slower than even Atmosphere).
- **`reverbSize` 70..95, `reverbMix` 45..80 — don't be timid with drone reverb.** Drones live in a big wash and tolerate far more reverb than any other category; a drone that sounds dry is usually under-reverbed. Push it.
- `subLevel` 30..60 for a tonal-anchor drone, or low (≤15) for an airy/spectral drone.
- `mono: false` — let multiple held notes layer into a chord-drone.

**Topology:** **Analog** — sustained, harmonically-rich, tolerant of long Filter Decay (Modern's clean feedback rings unmusically — "oil drum" — over the long decay a drone uses; avoid).

**Default ranges:**

| Param | Range | Notes |
|---|---|---|
| `ampAttack` | 2000-10000 ms | Slow bloom; the note arrives over seconds. |
| `ampSustain` | 85-100 | The endless hold — the category's load-bearing param. |
| `ampRelease` | 2000-8000 ms | Fades out, never cuts. |
| `filterSustain` | 60-90 | Keeps the filter open under the held note. |
| `analogDrift` | 40-70 | Organic motion that complements the LFO morph. |
| `reverbMix` | 45-80 | Big sustained wash — push it; drones tolerate far more reverb than any other category. |

**Signature mod-matrix (≥2 slow LFOs, different dests + rates):**

| Routing | Amount | Role |
|---|---|---|
| `LFO1 → FilterCutoff` (modAmt_1_10) | **±5..10 (single digits)** (<0.12 Hz) | The primary slow breath. **Keep it tiny on a drone** — cutoff is parked low and the routing is knob-relative + bipolar, so a large slot swings the negative half-cycle down below audibility and the sound *disappears*. ±25+ is the #1 mistake here. |
| `LFO2 → OscMix` (modAmt_2_2) | ±20..40 (different rate from LFO1) | Timbral drift — avoids phase-lock with LFO1. (OscMix is additive, not knob-relative — safe at this depth.) |
| `LFO3 → FilterResonance` (modAmt_9_11) | ±15..30 (ultra slow) | Vowel-y morph across the held note |
| `LFO → FilterEnvAmount` (modAmt_X_12) | ±15..30 | Env-shape breathing across the cycle |
| `LFO → AmpSustain` (modAmt_X_15) | ±10..20 | Subtle amplitude breathing |
| `Macro1 → FilterCutoff / AmpSustain` (modAmt_4_10/15) | +60..+100 | Performance "open / intensify the drone" |

**Don't:**
- `ampSustain < 80` (the drone collapses into a pad or decays away).
- Any LFO faster than ~0.2 Hz (drones are slower than Atmosphere — fast motion breaks the stasis).
- Lean on velocity or per-note response — drones aren't played percussively. (A subtle `Vel → FilterCutoff` for "louder = brighter" is fine, but it's not the character.)
- Use only ONE LFO — single-LFO morph reads as obvious periodic wobble. Two at different rates is the minimum.
- Forget the autonomous morph entirely — a held note with no LFO/drift motion is a dead drone.

---

## 7. Quality rules — load-bearing checklist

Run through this for every preset before declaring it done.

### 7.0 Divergence mandate — the batch default is maximal difference

**This is the single most important rule when authoring more than one preset at a time, and it overrides the gravitational pull of every category recipe below.**

When the user asks for N presets, the default intent is **N genuinely different sounds** — distinct *species*, each describable with a different set of adjectives, each tellable apart on a single held note. Author a *similar-sounding* batch ONLY when the user explicitly asks for a family / matched set / "variations on X" / "same character, different Y". If a request is ambiguous, assume **maximally different** and say so; do not default to a cluster.

**The AI failure mode this exists to counter (name it, because it is invisible from the inside).** Asked for "10 deep-house basses," an AI anchors on the single most-prototypical deep-house bass and emits 10 points clustered tightly around that centroid, then "diversifies" by small symmetric perturbations of ONE shared skeleton (same architecture, same dominant engine, same routing shape, values nudged ±15%). The centroid and the structure remain shared, so the batch reads as one patch rendered ten times. **Spreading numeric values around a shared centroid does not fix this** — it is the trap, not the escape.

**The fix is archetype-first, not value-spread:**

1. **List N distinct ARCHETYPES before touching a parameter.** Different *organizing ideas*, not different numbers. The archetype is the sound's species; the parameters are downstream of it. Example archetype sets:
   - *Deep-house bass:* pure sine sub · detuned-wide (Reese-ish) · FM/click-attack plucky · overdriven growl · hollow square/reed · stacked-octave organ · round filtered-saw classic · noisy/breath-attack · rubbery ultra-short · resonant acid-squelch.
   - *Pluck:* woody-dark · icy-glass · gritty-saturated · wide-airy-ensemble · snappy-percussive · bell/FM-edge · hollow-PWM · acid-squelch · metallic-thin · neutral-macro-morph.
   Pick one archetype per preset; no archetype repeats in a batch.
2. **Build each preset around ONE bold hook** and subordinate the rest of the patch to it. A balanced "touches every section evenly" patch always reads as the category default. A hook-driven patch (this one IS its square-sub growl; that one IS its slow chorus bloom) reads as a distinct object. Decide the hook first, then let it dictate the filter, the envelope, the FX, the one defining routing.
3. **Commit to the edges of the range.** Diversity requires presets at the extremes, not all in the safe middle third. Across a batch, *something* must be the brightest, the darkest, the dirtiest, the cleanest, the shortest, the longest. Each preset should push at least one parameter near an edge of its category-legal range. All-middle values are the surest cause of convergence.
4. **Vary STRUCTURE, not just values.** mono vs poly · which engine dominates (sub / osc / click / transient / filter-motion) · how many oscillators actually carry the sound · how many routings (a bold 2-routing preset beside a 5-routing evolving one) · autonomous-motion source (LFO vs Env vs Macro vs Random vs Velocity vs none). Two presets with the same structure and different numbers are siblings.

**The Divergence Check — run it after drafting a batch, before declaring it done:**

- [ ] **Pairwise adjective test.** For every pair of presets: could you tell them apart on a single held note, AND would you reach for a *different* set of adjectives to describe them? If two share their adjective set ("warm round sub"), one is a duplicate — **redesign it to a different archetype**, do not nudge its values.
- [ ] **Range coverage.** Does the batch reach both ends of the category's brightness, grit, and density/decay ranges? If everything sits in the middle third, push presets outward until the extremes are occupied.
- [ ] **No shared fingerprint.** No two presets share the same `(archetype × filter-zone × grit-level × dominant-engine × motion-source)` signature. A printed table (one row per preset, those columns) makes a flat column obvious at a glance.
- [ ] **Structural spread.** The batch contains both mono and poly, both clean and gritty, and at least two genuinely different *dominant engines* — not ten variations on "sub + filter-env bite".

If the batch fails any check, the fix is **categorical (swap an archetype)**, never **incremental (tweak a value)**. See §7.2 #18: when a preset is too close to another, redesign the concept — don't iterate the values.

### 7.1 Per-preset audit

- [ ] Category is one of the 7 closed-vocabulary categories (Pluck, Bass, Lead, Pad, Keys, Stab, Drone).
- [ ] Description is one sentence about this sound only, in plain everyday English — no comparison with other presets, no rare words.
- [ ] At least one Osc setting moved from default.
- [ ] Filter cutoff + resonance both meaningful for the role.
- [ ] Envelope (decay + curve at minimum) tuned to the character.
- [ ] At least one FX slot with `Mix > 0` (drive / chorus / delay / reverb).
- [ ] **≥1 Group-1 modulator routing (LFO1/2/3, ENV1, or Random)** — HARD floor.
- [ ] **3-6 audible mod-matrix routings** above the thresholds in §4.3.
- [ ] **≥1 Tier-1 routing** (Cutoff / OscMix / OscShape / OscBShape / AmpDecay / TransAttack / ClickLevel / Sub / FilterEnvAmount / FilterAttack / AmpSustain / AmpAttack / AmpRelease / TransPunch).
- [ ] **≤1 *featured* Tier-2 routing** (Drive / FilterResonance / DelayFeedback / ChorusMix / DelayMix / ReverbMix).
- [ ] **No RAW center-pitch modulation** — never to OscBPitch (modAmt_*_5; detunes/out-of-tune). Unison (modAmt_*_6) only as the slow ensemble-warble (≤0.5 Hz, unisonVoices ≥ 2; never on Arps). **For musical pitch vibrato, use the Vibrato depth destination (slot 22)** — it's coherent + in-tune. Aftertouch/Macro/ENV1 → Vibrato are all good; the mod wheel already rides vibrato depth built-in.
- [ ] No fast LFO routed to matrix (rates ≤2 Hz, ideally 0.2-0.5 Hz).
- [ ] Category-appropriate `ampSustain` (Pluck ≤ 15, Bass ≤ 25, Stab 0..15, Lead 25..40, Keys 20..50, Pad 60..95, Drone 85..100). These are character heuristics, not range caps.
- [ ] Category-appropriate `ampAttack` (Pluck ≤ 5 ms, Bass 0.3..1.5 ms, Stab 0.3..2 ms, Lead 0.5..5 ms, Keys 0.5..8 ms, Pad 500..3000 ms — atmosphere-leaning Pads 3000..10000 ms, Drone 2000..10000 ms).
- [ ] Category-appropriate `ampRelease` (Pluck ≤ 50 ms, Stab ≤ 80 ms, Bass tight, Keys 200..600 ms, Lead 100..500 ms, Pad/Drone 1000..8000 ms).
- [ ] Keys have ≥2 velocity routings; Stabs are Poly (`mono: false`) with a `filterEnvAmount` snap; Drones have ≥2 ultra-slow LFOs on different destinations.
- [ ] `subLevel ≤ 30` unless it's a Bass.
- [ ] No `oscOctave: -2` for Bass class.

### 7.2 Authoring rules from human ear-checks (load-bearing — these are why the rules exist)

**1. No macro clones.** Macro1 and Macro2 must NOT route to the same destination.

**2. ≤5% on LFO/Env → AmpDecay** (or any envelope-shape param). Envelope-shape params define the silhouette of every note; modulating them >5% totally bites off the sound.

**3. Mod matrix is binary: right lever or filler.** If you add a routing, set amount to a *useful working range* (often 60-100% for performance macros, 5-30% for character motion). Do NOT default to 30-40% "for safety" — that's noise.

**4. Drive type per-character, not per-category.** Some Bass wants Hard, some Soft. Some Pluck wants Warm, some Hard. Pick by character; never default to Soft.

**5. Sub level + sub shape are per-preset.** Don't template-default `"Sine"`. Vary across the bank.

**6. Dual-osc differentiation.** `oscShape` and `oscBShape` should differ by ≥15 points OR `oscBOctave ≠ 0` OR pulse settings differ. Identical shapes + same octave = wasted second oscillator. Much of the instrument's depth lives in mixing two different oscillators — use it.

**7. Pluck sustain shorter than instinct.** Sustain >15 starts feeling pad-like — keep plucks tight unless explicitly going pad-adjacent.

**8. Filter cutoff shouldn't default too open on Plucks.** 4000+ Hz is "no filter" not "bright pluck". Pick a real cutoff that does timbral work.

**9. Macro routings must produce DRAMATIC moves.** Check: `base_value + amount` should be audibly distinct from `base_value`. Macro1 → OscMix amount 30 with OscMix base 50 = 80 at full turn = barely audible. Use amount ≥50 for that case.

**10. Don't lean on Velocity as the differentiator.** Vel routings make the preset *responsive*; modulators make it *alive*. A preset with 4 Vel routings + 0 modulators is still static — it just gets brighter on hard hits.

**11. ENV1 is underused — use it deliberately.** ENV1 is a Group-1 source, equal weight to LFOs. When using ENV1, shape its ADSR to match the routing role (don't leave at defaults). See §3.11.

**12. "Playful" reads as *tactile*, not *bright*.** Bigger click, more saturation, darker filter, more body-weight — not "small reverb + bright filter."

**13. Unison gives width and depth that chorus can't replicate.** When a preset wants stereo width OR harmonic body, reach for `unisonVoices: 2+` with `unisonDetune` 5-10 cents (subtle) up to ~40-80 for aggressive supersaw width and `unisonSpread` 60-90 — typically with `analogDrift` 30-60 for organic per-voice motion. Cranking `chorusMix` on a `unisonVoices: 1` preset adds a thin modulated stereo image but the harmonic content stays single-voiced — chorus is **sheen / movement**, unison is **body / thickness**. Use them together when you want both: unison for body + chorus for animation. Single-voice + heavy chorus = thin width, not depth. The modern-melodic-house wide-pluck signal is unison-driven, not chorus-driven.

**14. Late `ampAttack` is the Pad / Atmosphere / Drone signature — use it.** `ampAttack` runs 0..32000 ms. Plucks live at the bottom (0.1-4 ms). **Pads should live at 500-3000 ms (soft swell)** or **3000-8000 ms (full bloom)** — multi-second swell territory, not milliseconds. A common mistake is leaving Pads at 5-50 ms, which still reads as "soft pluck," not "actual pad." Pair late attack with `ampSustain` 60-90 (so the swelled note actually holds), `ampCurve` 40-55 (near-linear; below 50 holds the peak a beat before decaying), `ampRelease` 1000-5000 ms (the note has to fade *out* of the texture, not cut). For Atmosphere and Drone-leaning Cinematic, push `ampAttack` to 3000-10000 ms — the note arrives several seconds late and blooms in.

**14b. Match the filter envelope to the amplitude envelope on Pads.** The filter has a full ADSR (`filterAttack`, `filterSustain`, `filterRelease`) — pads should use them. Default `filterAttack` 0 + decay-only filter env is pluck-shaped. For a true pad bloom, set `filterAttack` 500-3000 ms (timbre opens *with* the amplitude swell), `filterSustain` 30-70 (filter holds open under the held note — otherwise it decays to zero and the pad goes dark mid-note), `filterRelease` 500-3000 ms. Combined with a "long bloom" ENV1 routed to FilterCutoff, you get amplitude bloom + timbral bloom together — the slowly-opening cloud-of-sound character that defines pad/atmosphere identity.

**15. Vary the modulation *strategy* across presets — don't reuse one fingerprint.** The biggest sameness trap when authoring multiple presets (even in different categories) is reaching for the *same mod template* every time: `LFO1 → FilterCutoff` as the autonomous-life routing, at ~the same rate, at ~the same depth, on every preset. Different oscillators can't rescue it — three presets that all breathe via LFO→Cutoff at ~0.1 Hz read as variations of one patch. **The destination that carries the autonomous motion is a bigger fingerprint than the amount.** Break the template three ways:
  - **Vary LFO rates widely** preset-to-preset — 0.05 Hz, 0.15 Hz, and 0.4 Hz are different worlds. Don't cluster every preset at one rate.
  - **Don't default the motion to cutoff.** Carry it on whatever suits the character: `OscMix` / `OscShape` / `OscBShape` (timbre morph), `OscBPulseWidth` (PWM-pad breath — needs `oscBPulse = true`), `ChorusMix` (string-ensemble swell), `FilterEnvAmount` or `AmpSustain` (evolving envelope), `Sub` (heartbeat bass). A string pad breathes via ensemble/chorus; an evolving texture via osc morph; only a filter-forward sound breathes via cutoff. And note: a pad's bloom can come entirely from the **filter ADSR** (`filterAttack`) with *no* cutoff LFO at all.
  - **Vary the matrix shape** — which source drives which dest, how many routings, and whether cutoff is modulated at all. Putting cutoff under a **Macro** (player-controlled brightness) instead of an LFO is itself a differentiator from a preset whose cutoff breathes autonomously.

**16. Contrast comes from texture, not brightness.** Gritty vs. clean, wide vs. focused, slow-morph vs. static. Don't ship a preset whose only differentiation from the rest of a bank is "much brighter than the others."

**17. "Percussive / dry / grounded" intents usually belong in Stab or Mallet, not Pluck.** Scrutinize percussive intents against the category map (§6.0) before authoring them as Plucks.

**18. When a preset is rejected, redesign the concept — don't iterate the values.** Names + intents matter; iterating on a failed character rarely rescues it. Draft a different concept instead.

**19. The recurring draft-correction checklist — pre-apply these.** These biases surface in *every* AI-drafted batch and are corrected the same way across categories. Catch them at draft time:
  - **Master low-pass:** never leave `fxLpFreq` at 20 kHz — it reads fizzy/harsh on nearly every voiced preset. Roll it down by category: Bass ~1.5-3 kHz, Pluck ~5-8 kHz, brighter voices higher — but move it off 20 k.
  - **Transient-punch frequency:** don't leave `transPunch` at its 1500 Hz default by reflex — it is a high-pass corner (§3.8), and lower means more punch. On Bass: 200 Hz with `transMix` high (§6.2). Elsewhere, pick the corner from §3.8's bands.
  - **Filter envelope needs a floor + a fast decay:** `filterSustain 0` (slams shut) plus a slow `filterEnvDecay` reads as a dead blip. Land `filterSustain` ~50 and `filterEnvDecay` ~30-45 ms so the filter env keeps timbre alive through the note.
  - **Velocity→Filter is routinely omitted:** add `Vel → FilterCutoff` (`modAmt_7_10`) ~25-40 so the sound plays dynamically rather than static — the one Vel routing worth near-defaulting (cf. rule 10).
  - **Don't draft `ampSustain` near zero:** near-0 reads as a lifeless blip even on plucks. Land ~15-20 (stay under the ~30 pad-threshold on tight categories, rule 7).
  - **Prefer the filter's own ADSR over `ENV1→FilterCutoff`:** the matrix ENV1→Cutoff route gets zeroed again and again in favour of `filterAttack`/`filterSustain`. Use `filterAttack`/`filterSustain`/`filterEnvDecay` for per-note filter motion; reach for the matrix route only for extra sweep on top.
  - **Base cutoff is drafted ~1.5-2× too bright:** pick a real working cutoff that does timbral work (generalizes rule 8 beyond Plucks).

**20. Be careful mixing LFO `Restart: Retrig` with a long `ampRelease`.** Not a
prohibition — Retrig is often exactly right, and this is a caution about one
specific combination.

**Why it matters:** the LFOs are **global, one shared phase for all voices**
(not per-voice — the conventional shared-LFO model). `Retrig` zeroes that shared phase on **every** note-on, so the
jump lands on *every sounding voice at once* — **including voices already
released and still ringing out their tail**. A new note audibly steps the notes
you already let go of. FX tails (reverb/delay) are unaffected, because they sit
downstream of the voices — that asymmetry is the tell if you are diagnosing it by
ear.

**When Retrig is what you want:** a long-hold Pad **with a pause before the next
note**. Each note then starts with a rising cutoff — a real and desirable
character, and the reason the mode exists.

**When it bites:** when the previous note's release tail is still sounding as the
new note arrives. So the risk is not "Pad" — it is **release length versus the gap
between notes**. Judge `ampRelease` against how the preset will actually be
played: multi-second release plus overlapping or closely-spaced notes is where the
step becomes obvious, and the deeper the LFO routing the harsher it is.

⚠ **The audibility thresholds in §4.3 do NOT apply to this.** Those are calibrated
for *continuous modulation depth* — whether a slow drift is perceptible. A phase
reset is a **discontinuity**, and a step is audible at far lower depth than a
sweep of the same amount. An LFO1 → FilterCutoff cell of 10-12 reads as inert
drift at 0.08 Hz and still produces a clearly audible step under Retrig. When
judging Retrig exposure, count **any nonzero** routing from that LFO, not the
audible ones.

⚠ **`Single` does not rescue this on Pads.** Single restarts only on the note that
opens a phrase, but a phrase counts **keys held down + pedal-held keys only** —
released voices still ringing do *not* hold the phrase open. So the usual pad
gesture (play a chord, lift it, let it bloom, play the next) is a *new phrase every
time*, and the tail gets stepped anyway. Single helps legato playing and little
else here.

---

**21. Macros have no fixed job — each preset decides, and an empty macro beats an
arbitrary one.**

Do not invent speculative performance macros. A macro that does something
arbitrary is worse than an empty one — it teaches the player that macros are noise.

- ⚠ **A macro's depth is a two-sided compromise — one amount serves both directions.**
  Macros are bipolar (−100..+100, default 0), so centre is the authored sound,
  above it opens and below it closes. You cannot tune the two halves apart.
  **Smaller is not safer:** you sometimes need a setting that goes too low in
  order to get it high enough above zero. A preset sitting low in the cutoff range has plenty of room
  above and almost none below, so the amount that buys a worthwhile opening also
  shuts the bottom — and that is accepted, not a defect. Set the depth by how far
  the sound needs to **open**, then live with wherever the bottom lands. Do not
  reduce a depth because full-left goes silent; check first that the top is worth
  having.
- **On Filter Cutoff, scale depth to headroom, not a fixed number**, so the knob
  delivers a similar perceived sweep rather than a similar number: 75 below 800 Hz,
  65 to 1500, 55 to 2500, 45 to 4000, 35 above. 15 less where a Modern ladder sits
  at res ≥ 30 (no resonance cap — opening a resonant Modern filter gets shrill),
  10 less where res ≥ 45 on either topology.

⚠ A macro routing is NOT a substitute for self-animation. The preset must still
sound alive at the macro's resting position, so pair a macro with an LFO or Env
routing rather than leaning on the macro to supply all the movement.

**22. NEVER mono on a Drone or a Pad.** Both categories are held, layered,
chord-played sounds with multi-second attacks — and Palora's mono transition does
NOT continue the envelope: the outgoing note fades out and the new note starts a
FRESH envelope, so every note change restarts the whole swell from zero. On a mono
drone with a 3.3 s attack, the output drops about **48 dB** at each note change and
crawls back up over the whole attack; the same patch in poly holds its level.
Legato does not save it — mono never continues the envelope, so the drop is the
same when the new note overlaps the old.

That behaviour is CORRECT for the categories mono belongs to — Bass, Lead, Pluck —
where attacks are milliseconds and a clean retrigger is the point. It is only ruinous
where the attack is long.

⚠ **This is the classic defect when adapting a patch from one category to another.**
Voice mode travels with the patch and survives any check that only looks at routing
count and resonance. **Whenever a patch changes category, check voice mode against
the destination category's norm.**

**23. An arp loop is an EVEN number of beats — never an odd one.** `arpLoopLen`
counts 1/16 steps, so beats = `arpLoopLen / 4`, and that must itself be even:
**8 steps (2 beats) or 16 steps (4 beats)**. 12 steps is 3 beats — it re-phases
against everything else in the session, drifting a beat every bar.

**24. A bass arp should RARELY land on beat 1 — and nothing should land on it
every bar.** The downbeat is usually already occupied by a kick, so a bass arp
that hits it fights the drum instead of weaving through it; leaving it open is
what makes the pattern sit in a track. More generally, a pattern that restates
the downbeat every single bar announces itself and then stops developing. Displace
it, or let a bar go by without one.

⚠ "Rarely", not "never". This is a rule about the DEFAULT reach — a bass arp that
lands on beat 1 is not wrong, it just should not be the automatic choice.

## 8. Worked example — Anchor

Based on the factory preset Anchor — a sub-anchor deep-house bass that ships as an arp bass.

### 8.1 The `.palora` file

Note how **sparse** it is: 35 params listed, everything else inherits Init.

```json
{
  "format": "preset",
  "version": "1.0",
  "plugin": "palora",
  "meta": {
    "name": "Anchor",
    "category": "Bass",
    "author": "Segment CPH",
    "description": "Deep-house bass built on a strong sub, with just a little edge on top — it sits under chord stabs.",
    "tags": ["bass", "sub", "deep", "clean"]
  },
  "params": {
    "oscShape": 25.0,
    "analogDrift": 15.0,
    "oscABMix": 30.0,
    "oscBShape": 25.0,
    "oscBOctave": "+1",
    "clickLevel": 64.5,
    "clickTone": 812.5,
    "clickDecay": 7.0,
    "clickBody": "Sub",
    "subLevel": 66.5,
    "filterCutoff": 528.9,
    "filterResonance": 2.0,
    "filterEnvAmount": 35.0,
    "ampDecay": 345.0,
    "ampCurve": 58.0,
    "ampSustain": 5.0,
    "ampRelease": 8.0,
    "transAttack": 14.0,
    "transSustain": 18.0,
    "transMix": 50.0,
    "transPunch": 200,
    "drive": 59.5,
    "fxDriveType": "Hard",
    "reverbSize": 30.0,
    "reverbMix": 8.0,
    "lfo1Rate": 0.25,
    "env1Attack": 4.0,
    "env1Decay": 1105.24,
    "env1Sustain": 0.0,
    "env1Release": 690.78,
    "modAmt_1_10": 8.4,
    "modAmt_5_10": 9.1,
    "modAmt_10_10": 25.1,
    "modAmt_7_16": 14.0,
    "arpOn": true
  },
  "arp": {
    "v": 1,
    "steps": [ { "r": 0, "c": 1,  "g": 0.25, "v": 0.72 },
               { "r": 0, "c": 2,  "g": 0.5,  "v": 0.72 },
               { "r": 0, "c": 3,  "g": 0.25, "v": 0.72 },
               { "r": 0, "c": 5,  "g": 0.25, "v": 0.72 },
               { "r": 0, "c": 7,  "g": 0.25, "v": 0.72 },
               { "r": 1, "c": 9,  "g": 0.25, "v": 0.72 },
               { "r": 0, "c": 10, "g": 0.75, "v": 0.72 },
               { "r": 9, "c": 14, "g": 0.5,  "v": 0.72 } ]
  }
}
```

### 8.2 Why this works (rationale)

- **Sub-anchor architecture.** `subLevel: 66.5` carries the bass weight; `oscShape: 25` / `oscBShape: 25` (halfway from saw to triangle) take the edge off the saw. `subShape` and `oscOctave` aren't listed — they sit at their Init values (Sine / 0). Pure-fundamental low end, no mud.
- **Minimal osc edge.** `oscABMix: 30` keeps A dominant; `oscBOctave: "+1"` differentiates B from A (rule 6); low `analogDrift: 15` keeps it stable.
- **Short bass envelope.** `ampDecay: 345` (deep-house short), `ampSustain: 5` (very low), `ampCurve: 58`, `ampRelease: 8` for a tight end. `ampAttack` is unset → quick Init attack. Bass-class shape.
- **Per-note bite from the dedicated filter envelope.** `filterEnvAmount: 35` at `filterCutoff: 528.9` with very low `filterResonance: 2` — warm-round mid, the filter env adds attack snap, minimal reso lets the sub speak.
- **Featured click body.** `clickBody: "Sub"` adds woody onset; `clickLevel: 64.5` + `clickDecay: 7` — present but not the focus.
- **Hard drive at 59.5 with type "Hard"** — this preset wants growl, not warmth (rule 4). Picks the harder shaper deliberately.
- **Transient punch.** `transAttack: 14` / `transSustain: 18` / `transMix: 50` add post-filter snap; `transPunch: 200` is the lowest corner, so every note reacts (§3.8).
- **Modulation: 4 stored routings** (plus Init's ModWheel → Vibrato, inherited because it is not overridden):
  - `LFO1 → FilterCutoff @ +8.4` at 0.25 Hz: slow filter motion under held notes (Group 1 — autonomous life).
  - `KeyTrack → FilterCutoff @ +25.1`: cutoff follows the played note at 0.5 octave per octave (§4.2b).
  - `Velocity → TransAttack @ +14`: harder hits punch more.
  - `Macro2 → FilterCutoff @ +9.1`: a small brightness nudge under the player's hand.
- **Arp.** `arpOn: true` with a composed `arp` block (no `tmpl`) on the default 16-step loop: ladder rows 0-1 carry the figure, and one step on row 9 is an LFO 2 wildcard (§5.2c).

### 8.3 What's deliberately NOT included

- No reverb wash beyond a small room (`reverbSize: 30`, `reverbMix: 8`), no chorus, no delay (`delayMix` unset → Init). Deep-house bass = nearly dry.
- No Tier-2 *featured* routings — keeps the preset focused on its one job.
- No pitch modulation, no fast LFO, no AmpDecay routing — all forbidden per §4.5.
- **Most params aren't listed at all** — that's the format working as intended: a preset owns only its diff from Init.
- **No `melody`** — Anchor auditions on the built-in Bass fallback phrase. To give it a signature phrase instead, add a top-level `melody` block **beside** `params` (an optional root key, exactly as in §5.1/§5.2b) — never inside `params`.

---

## 9. Authoring a bank — multiple presets in one document

When the user asks for **multiple presets at once** ("make me 5 Pads", "author a Pluck batch", "give me a bank", "a preset pack of 10", "10 presets"), emit ONE JSON document with the `bank` wrapper instead of multiple separate `.palora` files. The user pastes once, all presets land — and if `meta.name` is set, they land as a **navigable pack** in the browser left rail (not a flat dump into the user bank).

**Filename when saving to disk:** `<PackName>.palorapack` (the canonical extension for shareable banks). The plugin's *Import ▾ → From File* picker accepts `.palora` and `.palorapack`. If the user pastes via *Import ▾ → From Clipboard* instead, the extension doesn't matter — only the JSON content does.

> **What actually makes it a bank: the `presets[]` array — not the label.** The importer detects banks by structure, so a `presets[]` array imports as a pack. Write `"format":"bank"`, `"version":"1.0"`, `"plugin":"palora"` as shown — the importer rejects a file whose `plugin` isn't `palora`. (File extension is a separate namespace: save banks as `.palorapack`. The plugin's internal on-disk bundles use `"format":"pack"` — that's the plugin's business, not something you author.)

### 9.0 Plan the whole set before authoring any preset (do this first)

> **A preset is defined by its musical purpose, macro behavior, and modulation behavior — not by its parameter values.** A bank is N *distinct purposes*, not one purpose with N parameter variations.

The #1 bank failure: author one good architecture, then rename-and-nudge it N times. The variety checks in §9.2 are a back-end scan — too late to catch this. So before you write a single parameter value, produce a **set plan** and keep it in front of you:

1. **List every preset as a one-line musical role** — its job in a producer's session, not its sound: "warm fingered piano-pluck", "glassy FM bell", "detuned organic mallet", "wide chord stab". If two lines could describe the same role, merge or replace one.
2. **Decompose large counts into sub-roles yourself.** If the user asks for "16 plucks" with no sub-roles, *you* invent the breakdown before authoring — e.g. 3 piano / 3 glass / 3 organic / 3 chord / 2 bell / 2 experimental. Never author 16 presets against the single role "pluck". (If the user gave sub-roles, use theirs.)
3. **For each role, commit one line each to:** sonic identity (how it's *built* — osc construction, filter topology, click body), macro philosophy (what the one macro does for *this* preset), modulation philosophy (what carries its autonomous motion). These must differ across roles — see §9.2 for the axes.
4. **Only now author parameter values**, one preset at a time, against its committed plan.

**The producer gate — apply per preset as you author:** *"Why would a producer reach for this instead of the previous one in the bank?"* If the only honest answer is "brighter / darker / more reverb / less reverb", it's a clone — redesign its role, don't nudge its numbers.

Scaling note: the variety axes in §9.2 (reverb ×4, drive ×4, sub shape ×3, click body ×3) can't combinatorially carry a large bank alone. Past ~8 presets in one category, distinctness must come from the *roles* in step 1, with the axes as support — not the reverse.

### 9.1 The `bank` wrapper format

```json
{
  "format": "bank",
  "version": "1.0",
  "plugin": "palora",
  "meta": {
    "name": "Pack Name",
    "description": "One-sentence character description of what unifies this pack.",
    "author": "Segment CPH",
    "tags": ["lead", "nostalgic"]
  },
  "presets": [
    {
      "meta": { "name": "...", "category": "...", "author": "Segment CPH",
                "description": "...", "tags": [...], "generator": "ChatGPT" },
      "params": { ... },
      "melody": { "bpm": 120, "loopBeats": 8, "notes": [ [0.0, 0.25, 74, 103] ] }
    },
    {
      "meta": { ... },
      "params": { ... }
    },
    ...
  ]
}
```

> **Per-preset `melody` in a bank — ONLY ON EXPLICIT REQUEST (§5.2b).** Do not add melodies to a pack because it is a pack; the default is to omit them and let every preset use the per-category fallback library. The same goes for the **pack-level** `pack.meta.melody`, which overrides that fallback for the whole pack. When a user *has* asked for "a melody for each preset," each entry's `melody` is a **sibling of that entry's `params`** (as shown on the first entry above) — exactly as in §5.2b for a single file. It is never a key inside `params`. Entries that don't need a custom phrase simply omit `melody` and fall through to the category fallback library.

**Top-level `meta` (bank identity, all fields OPTIONAL but recommended):**

| Field | Purpose | Example |
|---|---|---|
| `name` | Pack display name — surfaced in the import-success toast (`Imported 5 presets from "Pack Name"`). Pick a memorable evocative name, not a numbered title. | `"Nostalgic Lights"` |
| `description` | One-sentence character of what unifies the pack — what makes these presets feel like a coherent collection. | `"Three bright nostalgic leads exploring different textures."` |
| `author` | Pack-level attribution. Defaults to `"Segment CPH"` for first-party. | `"Segment CPH"` |
| `tags` | Pack-level descriptors for browse/search. May overlap with per-preset tags. | `["lead", "nostalgic", "bright"]` |

The bank `meta` MIRRORS the per-preset `meta` shape for consistency. **Do not write
`created`** — the plugin stamps it on import (it's a library fact, not authored data).

**Per-preset entries inside `presets[]`** have the **same `{meta, params}` (+ `melody`, only if explicitly requested) shape** as a single `.palora` file — minus the per-entry `format`/`version`/`plugin` fields, which the wrapper carries. Every per-preset rule from §6–§7 still applies, including **sparse** params (diff from Init).

**Pack identity persists.** When `meta.name` is non-empty, the imported bank creates `packs/<sanitizedName>/pack.palorapack` and surfaces as a navigable pack — its own row in the browser left rail, its own scope for ◀▶ prev/next, its own column in the cascade dropdown. When `meta.name` is empty/absent, the wrapper falls through to a flat dump into the user bank — keep `meta.name` populated unless the user explicitly wants individual presets.

### 9.2 Bank-level discipline (don't make 5 of the same preset)

> **This is the back-end scan; the front-end plan is §9.0.** The set plan (§9.0) is what prevents clones; the axes below are how you verify the plan held and how you support role-distinctness with parameter spread. Don't rely on this scan alone — by the time you're scanning, the architectures are already written.

A bank's job is to give the user **variety**. Five presets that all sound similar is a bad bank. The per-preset rules in §7 ensure each preset is good in isolation; the rules below ensure the bank as a whole has texture and range.

**The governing principle: diversify the *method*, not just the *value*.** The trap an AI falls into across a pack is reusing one approach and only nudging numbers — same synthesis recipe, same modulation fingerprint, different cutoff/decay settings. That reads as one preset with variations. Deliberately reach for *different methods* on two fronts:

- **How the sound is built** — vary the *synthesis approach* preset-to-preset, not just parameter values: saw-ensemble vs. pulse/PWM vs. FM-click-forward vs. sub-dominant vs. hard-sync vs. dual-octave-stack. Two presets built from genuinely different oscillator construction sound like different instruments; two built the same way with different filter cutoffs sound like one instrument played twice.
- **How it moves** — vary the *modulation method* (§7.2 rule 15): the motion's *carrier* (Cutoff vs. OscShape vs. ChorusMix vs. PWM vs. filter-ADSR-only vs. player-controlled Macro) and its *LFO rate band* are bigger fingerprints than the amount. Don't give every preset the same `LFO→Cutoff`-at-0.1-Hz heartbeat.

Before finishing a pack, scan it on both axes: if you can describe two presets' construction *and* their movement the same way, redesign one of them. The per-axis checklist below is the concrete form of this principle.

**Variety axes — vary widely across the bank:**

- **Reverb type** — mix of Room / Hall / Plate / Spring. No quota, but a 5-preset Pluck bank with all Plates is suspicious.
- **Drive type** — mix Warm / Soft / Hard / Wild. Picked per-character, not per-category.
- **Sub shape** — Sine / Tri / Square mix. Don't default everything to Sine.
- **Filter cutoff zones** — push to extremes. Some presets 600-1000 Hz dark, some 5000-8000 Hz bright. Don't cluster all in 1500-3500 mid-range.
- **Click body** — Sub / FM / Noise mix. Same click body across the bank = same first-impression on every note.
- **`oscOctave` / `oscBOctave`** — mix of -1 / 0 / +1 across presets gives stack character variety.
- **`unisonVoices`** — mostly 1 (focused), some 2 (stereo width) — the wide-stereo presets become the differentiators.
- **`delayTime`** — vary 1/16, 1/8, 1/4, 1/8d, 1/4d, 1/2 across the bank for rhythmic variety.

**Bank-level mod-source soft targets** (not hard floors):
- ≥1 preset uses `ModWheel` somewhere.
- ≥1 preset uses `Aftertouch` somewhere (light — many keyboards lack AT).
- ≥3 different LFOs appear across the bank (don't only use LFO1).
- Macro1, Macro2 each appear in ≥2 presets; ENV1 in roughly a third of the bank (it's the most-underused Group-1 source).

**No mod-matrix clones across presets.** Two presets with the SAME 5 routings at the same amounts (just different osc settings) feels like the same preset. Each preset's matrix should reflect its own character.

**Vary the motion CARRIER and LFO rates, not just the amounts.** A subtler clone than identical routings: every preset breathing via `LFO→FilterCutoff` at the same ~0.1 Hz rate. Spread LFO rates widely across the set, and move the autonomous motion onto *different destinations* per preset (one on OscMix, one on ChorusMix, one on OscBPulseWidth (B pulse on), one purely on the filter ADSR with no cutoff LFO). The carrier of the motion is the fingerprint — see §7.2 rule 15.

**Naming variety.** Don't use a numbering convention (`Lead 1`, `Lead 2`, ...). Each name should be evocative and memorable in isolation. Avoid theme-collisions (don't have both `Crystal` and `Glass` in the same bank — pick one). For a 5-12 preset bank, pull names from different metaphor families: weather, materials, light, motion, abstract emotion, mythology.

**Description variety.** No two presets should have descriptions that read alike. Each is a one-sentence character description; vary the syntactic shape, not just the words.

### 9.3 Bank shape + variety analysis

A bank document is the wrapper plus per-preset entries shaped exactly like §8's worked example:

```json
{
  "format": "bank",
  "version": "1.0",
  "plugin": "palora",
  "meta": {
    "name": "Halflight Trio",
    "description": "Three nostalgic-leaning leads — bright vibrato, thin clean, brassy throat — sharing a late-night dreamy space.",
    "author": "Segment CPH",
    "tags": ["lead", "nostalgic", "varied"]
  },
  "presets": [
    { "meta": { "name": "Halflight",  "category": "Lead", "description": "…", "tags": ["…"] }, "params": { "…": 0 } },
    { "meta": { "name": "Filament",   "category": "Lead", "description": "…", "tags": ["…"] }, "params": { "…": 0 } },
    { "meta": { "name": "Brass Wire", "category": "Lead", "description": "…", "tags": ["…"] }, "params": { "…": 0 } }
  ]
}
```

**What made this trio work as a bank** — the variety analysis you should be able to write about your own output:

- Three reverb types across the set, picked per character — not "one of each at all costs."
- Three drive types (`Warm` / `Soft` / `Hard`), each chosen for the preset's character.
- Three distinct macro strategies: one preset's Macro1 → Drive (more grit), another's Macro1 → Cutoff (open up), the third on ModWheel → ReverbMix (wash on demand). Each preset has its own performance gesture.
- Filter cutoffs at 1100 / 2400 / 3200 Hz — wide spread, no clustering.
- Three different osc constructions: saw + B an octave up at 12 cents (chorus shimmer), triangle-leaning morph + pulse on B (thin/clean), saw + saturation + drift (throaty grit).
- Names from different metaphor families (light, material, body) — no theme collision.

### 9.4 When to use a single preset vs a `bank`

| User asks for | Use |
|---|---|
| "make me a Lead" / "one preset" / "I want to try X" | Single `.palora` |
| "make me 3 Pads" / "give me a Pluck batch" / "author a bank" | `bank` |
| "fill out the Keys category" / "I need 8 presets for X" | `bank` |

When the user is iterating on character, a single `.palora` is fast (one paste per draft). When they want variety to audition against a track, a `bank` saves clicks.

Either way, **the per-preset rules in §1–§8 still apply to every preset** — banking is additive, never an excuse to lower per-preset quality.

---

## 10. Final instructions for the AI

When the user requests a preset (e.g. "make me a bright Lead" or "author a Pad called Glacier"):

1. **Pick the category.** If the user named one, use it; else infer from intent. It is a closed set: Pluck, Bass, Lead, Pad, Keys, Stab, Drone.
2. **Pick a name.** One word or two short words. Evocative, not parametric. Avoid generic ("Lead 1", "Bass 03") and avoid the names of Palora's factory presets (the user will list these if relevant).
3. **Pick a description.** One sentence. What does it *feel* like, not what does it *do* — in plain everyday words, about this sound only (never compared with other presets).
4. **Pick parameter values** following the category recipe in §6 plus the load-bearing rules in §7.2.
5. **Pick 3-6 modulation routings.** ≥1 must be Group-1 (LFO/ENV1/Random). ≥1 must be Tier-1. ≤1 should be *featured* Tier-2. No pitch modulation.
6. **Self-audit against §7.1** before emitting.
7. **Emit two artifacts:**
   - **Single preset** (most asks): the complete `.palora` JSON (`{format:"preset", version:"1.0", plugin:"palora", meta, params}`) in a fenced code block. If the user wants to save it as a file, the extension is `.palora`.
   - **Bank** (when user asks for "multiple", "a batch", "N presets", or "fill out a category"): a single `bank` JSON document (see §9) containing all presets in one `presets[]` array. ONE paste = the whole bank. **If the user saves the bank to a file, the extension is `.palorapack`** — that's what the plugin's *Import ▾ → From File* picker accepts. Always populate `meta.name` so the bank lands as a navigable pack.
   - In both cases, follow with a 2-3 sentence design rationale. For banks, the rationale covers the bank-level variety strategy (what makes these N presets distinct from each other), not per-preset details — the user can audition individually.

**Don't:**
- Output non-English `meta.name` / `meta.description` / `meta.tags`. Preset content is **always English**, even when the prompt is in another language (the rationale §2B may match the prompt's language; the preset itself stays English).
- Output partial JSON or pseudocode.
- Use internal indexes for choice parameters (`"reverbType": 2` is wrong — it's `"Plate"`).
- Set parameters to their defaults (waste — leave them out).
- Set `masterVolume`, `matrixBypass`, `modRowBypass_*`, `audition_*`, `mod_*` (anim-mod), or `anim_*_mod` / `anim_*_aud` parameters.
- Modulate OscBPitch (dst 5), OscBPulseWidth (dst 4 except for explicit PWM presets), or Unison (dst 6) fast/large, on Arps, or on single-voice presets.
- Default to `fxDriveType: "Soft"` without thinking about character.
- Put `mono: true` on a Pad or a Drone (§7.2 rule 22).
- Set non-zero `oscBSemi` for melodic-instrument presets.
- Set `oscBFine` between 1 and 7 when `oscBOctave: 0` (BEAT TRAP).
- Use LFO rates >2 Hz when matrix-routed.
- Use mod-matrix amounts in the 30-40 range for performance levers — push 60-100 or don't include.

**One paragraph at the end of your output should answer:** if the user plays a sustained chord with this preset, does it have *autonomous motion*? (If only Vel and Macro routings are used, the answer is "no" and the preset fails the Group-1 rule. Random alone passes the rule for normal multi-note playing but, at the default `randomRate` 0, does NOT deliver within-note motion — if the preset is meant to evolve on a single held note, add an LFO or ENV1 routing too.)

For banks: **plan the whole set before authoring any preset (§9.0)** — list each preset as a distinct musical role, decompose large counts into sub-roles yourself, and commit each role's identity/macro/modulation philosophy *before* writing parameter values. Then apply the producer gate per preset as you author: *"Why would a producer reach for this instead of the previous one?"* If the only honest answer is "brighter / darker / more reverb / less reverb", it's a clone — redesign its role, don't nudge its numbers. Finally answer in one sentence — "would a listener auditioning these N presets in sequence hear meaningful variety, or would they all blur together?" If the second, redo with stronger differentiation on the variety axes in section 9.2.