# VST3 automation parameters — the Phase Γ specification > Daniel, 2026-08-01: *"we need to scope the whole parameter system for automation, which > will require redesigning the existing wiring."* And, on Rate being latched at note-on: > *"we will need to analyze ALL the controls for LIVE use/automation use."* **Superseding ruling, Daniel 2026-08-01 (later the same day):** *"correct the phase gamma plan to account for complying with the VST3 standard for parameter reporting… by the end of gamma we have the automatable params reported. Make the parameter order logical."* **This IS Phase Γ work.** It ships as **Γ-W4-T1 `vst3-parameter-set`**, the phase's last track. This doc was written as scoping and has been promoted in place: §§1–5 are the original analysis (still correct, still the reasoning), and **§§6–10 are the specification** — the ID scheme and its freeze invariant, the per-control classification, the one-way-door sweep, the resample interaction, and the build shape. Two things that were open in the scoping pass are now **decided** rather than deferred: the storage architecture (§3.3, decided in §6.1) and the ID space (§3.1, decided in §6.2). One thing is **open and wants Daniel** before Γ-W4 dispatches: **Γ-F7**, the parameter *order* (§6.4). It is not urgent — three waves sit in front of it — but it is a forever commitment, so it is not mine to close silently. --- ## 1. Current state, verified **The instrument has zero VST3 automatable parameters.** - `ReaSamplerProcessor::initialize` never populates the parameter list, so `getParameterCount()` returns the SDK default **0**. A host sees no parameters at all. - All state lives in the **`ComponentState` blob** — envelope v1…v11, params payload v1…v13 (`core/instrument/map/component_state_io.h`), a cross-artifact contract the extension's `instrument_drop` and the instrument's processor both read and write. - `DeckParam` ids are **runtime-only and explicitly free to reorder** — the editor's `ParamControl` is an alias of the same enum, and nothing persists an id. Consequently the instrument today has: no host automation, no MIDI learn, no parameter linking, no host-side modulation, and no generic FX panel. Everything is reached through the plugin's own editor. --- ## 2. What is actually on the table (name the prize properly) Framing this as "automation" undersells it. **REAPER gives every exposed VST3 parameter a parameter-modulation block for free** — an LFO, an envelope, an audio-follower/sidechain, MIDI link, and parameter linking, per parameter, with no plugin-side work beyond declaring the parameter. So exposing parameters is not primarily about drawing automation lanes. It is the instrument **gaining a modulation system it would otherwise have to design, build, persist and draw itself.** A sampler with a host-provided LFO on filter cutoff, an envelope-follower on drive, and MIDI-CC on pitch offset is a materially different instrument, and none of that is our code. That is the reason this is worth a phase. It is also the reason the parameter list's design matters more than the plumbing: the list *is* the modulation matrix's rows. --- ## 3. The hard problems, in the order they bite ### 3.1 Parameter IDs become FOREVER-STABLE A VST3 `ParamID` is recorded in the project file. Once shipped, the id ↔ meaning mapping is **frozen forever** — the same discipline the extension's command-id strings and the VST3 class UIDs already carry, and the same discipline the params-payload version ladder carries. **`DeckParam`'s "free to reorder" property dies the day parameters ship.** Anything that wants to renumber, regroup or reorder that enum has to happen first. This is not a theoretical concern: Phase Γ adds two entries to it. **DECIDED — §6.2: an independent id space with an explicit frozen table.** Direct `DeckParam` values were simpler and were rejected: they would freeze an enum whose own header declares it *"runtime-only… free to change"*, and they cannot express the cases where the two spaces genuinely differ (a `DeckParam` that is not a parameter, a parameter with no deck cell). The reasoning is the command-id family's: display order and wire identity should not be the same number. ### 3.2 The taper becomes the host-facing contract VST3 parameters are normalized `[0,1]` with the plugin owning the taper (`toPlain`/`toNormalized`). An automation envelope a user draws in REAPER is drawn against the **normalized** value. **Therefore: re-tapering a parameter after it ships silently re-interprets every recorded automation point in every saved project.** A 40 %-of-travel node on an attack knob means 16 ms under a log taper and 800 ms under a linear one. There is no version ladder that can fix this, because the data is in the host's project file, not ours. Today, re-tapering is **free** — normalization exists only in `ui/deck_values.cpp` as a display/interaction layer, and the payload stores raw engine values as doubles. That is a property worth spending while we still have it. See §4. ### 3.3 Two sources of truth VST3 saves parameter values *and* calls `setState`/`setComponentState`. A value that lives in both can drift — a project reloaded with automation could restore the blob's value and then have it immediately overwritten by the host's parameter value, or the reverse, depending on call order. Two coherent answers, both viable, neither obviously right: - **(a) Parameters are the source of truth** for everything automatable; the blob carries only non-automatable structure — sample refs, velocity curves, spline contours, mode selections, the loaded capture. Cleanest host semantics; largest rewrite; and it splits the parameter set across two storage mechanisms, which the "one parameter set" invariant went out of its way to unify. - **(b) The blob stays authoritative; parameters are a projection** with one defined sync direction and a defined precedence at load. Smallest change; preserves the cross-artifact blob contract intact; risks exactly the drift class above if the precedence is not airtight. **DECIDED — (b), the blob stays authoritative. See §6.1 for the reasoning, the two findings that settled it, and the precedence rule that closes the drift risk.** This was going to be handed to the track as its opening architecture decision, the way Ξ-W2-T1's crossing decision was. It is not, because two verified facts collapse the fork rather than balancing it — a fork with a dominated option in it is not a fork. ### 3.4 Which controls can be parameters at all — three classes The good news: **this analysis is already done once, in one place.** `isLiveDeckParam` / `liveCommitFor` (`ui/deck_groups`) is exactly "which controls can change without a rebuild," which is the same question automation asks. Phase Γ widens it from two states to three (§3.5). The parameter work should widen the *same* decision point again rather than start a second table — that is the standing rule (`core/instrument/CLAUDE.md`: *"which controls are live is ONE decision, recorded in ONE place"*). | Class | Examples | Automatable? | |---|---|---| | **Continuous, live-safe** | filter cutoff/Q/morph/drive/mod amt/key-track, every stage time and level, pitch env depth, master gain, pitch offset | **Yes** — the live tier already delivers them at block boundaries | | **Discrete / rebuild-tier** | voice count, Poly/Mono, Retrig/Legato, Gate/Trigger, Staged/Spline, pitch engine, filter law | **Only if** each gains a live path, or is exposed as a stepped parameter that is explicitly *not* safe to automate at rate. Today they route through `rebuildVoiceEngine` or a full reload — neither is RT-safe at automation rates | | **Structural** | the loaded capture, `SampleRefs`, the three velocity curves, the three spline contours, loop points, root note | **No.** These are not scalars; they stay in the blob | | **Latency-changing** | the **limiter enable** | **No** — and for a reason unrelated to the live tier. Flipping it changes reported latency, which the SDK defines as a host deactivate/reactivate. §3.8 | The awkward middle class is the second row, and it is where the design work is. ### 3.5 Live vs. latched is a per-parameter decision, and Γ opens the seam Phase Γ settles that **Rate is latched at note-on**, and — importantly — settles it as a *third commit class* (`Live` / `NoteOnLatched` / `Reload`) recorded in the same `deck_groups` predicate, rather than as a special case at a call site. See `docs/product/instrument-control-surface.md` §2.3. That is exactly the vocabulary the parameter system needs. A VST3 parameter has to declare what it means to move it mid-note, and the answer is per parameter: - **Live** — the sounding voice follows (the φ-holding `applyLive` rule). - **Note-on latched** — published, but read only by `snapLive`. Automation still works; it just takes effect on the next note. Rate is here, and the *reason* it is here is recorded: loop resolution and contour mapping are note-on folds, so live rate means re-folding a resolved loop mid-note without a discontinuity. - **Not automatable** — rebuild or structural. **Lifting Rate from latched to live is a real feature with a named cost, not a flag flip.** When someone proposes it, that is the paragraph to read first. ### 3.6 Parameter count, grouping, and the generic panel ~60 `DeckParam`s plus the non-deck controls (voice count, master gain, key-track, preview velocity, limiter — though the limiter enable is **excluded** from the automatable set, see §3.8). REAPER's generic FX panel and every automation-lane picker will list all of them flat unless they are grouped. VST3's answer is `IUnitInfo` — a unit tree that maps naturally onto the deck's own group structure (PITCH/RATE, FILTER, VELOCITY, VOICE, the three envelopes, MASTER). Also needed per parameter: a display name that survives truncation, `ParameterInfo::units`, `stepCount` for discretes, and the right flags (`kCanAutomate`, `kIsBypass` — the limiter toggle is emphatically **not** the plugin's bypass parameter). Open: does the unit tree mirror the deck's *visual* grouping (which Phase Γ has just reflowed into two rows) or the engine's signal flow? They currently agree. Keeping them agreeing is a constraint worth stating before they diverge. ### 3.7 Sample-accurate automation vs. block-boundary observation The live-parameter seqlock is observed **once per `render()` and once per note-on** — block boundaries, by design, and that design is what keeps the per-sample path free of indirection. VST3's `IParameterChanges` can carry multiple points inside one block. Block-boundary application is standard, acceptable, and what most instruments do. Reading the points sample-accurately would put a per-sample "has a parameter changed" question on the hot path, which the phase-wide guardrail forbids in its current form. **Lean: block boundary, explicitly, and say so — then revisit only if a user reports audible stepping on a fast automation curve.** ### 3.8 Latency reporting — SETTLED, and it removes one control from the parameter list **Fork Γ-F2 is ruled (Daniel, 2026-08-01): the limiter has lookahead and the plugin reports latency DYNAMICALLY** — zero when the limiter is off, the lookahead when it is on. Do not plan against a zero-latency instrument. The consequence for this doc is concrete and it is a **subtraction from the parameter list**: > **The limiter enable is NOT automatable.** It goes in §3.4's third class, and the reason > is not that it lacks a live path — it is that changing it changes the plugin's reported > latency, and the vendored SDK defines `restartComponent(kLatencyChanged)` as *"the host > has to deactivate and reactivate the plug-in"* > (`pluginterfaces/vst/ivsteditcontroller.h:105-108`). In this plugin a deactivate frees > every sounding voice and a reactivate re-decodes the WAV. **An automation lane toggling > that parameter would deactivate the plugin on every flip.** Two corollaries the parameter work must carry rather than rediscover: - **It is also not the plugin's `kIsBypass` parameter.** A safety limiter is not a bypass; binding it to `kIsBypass` would hand the host a control that restarts the component. - **Latency reporting must be derived from persisted state, not from a transient.** The SDK states the new latency is what `getLatencySamples` returns *after* `setActive(true)` — and this plugin's `setActive(false)` frees essentially everything. Whatever holds the limiter flag must survive that cycle. Full reasoning, the SDK quotes, and the required verification steps are in `docs/product/instrument-control-surface.md` §3.1.1. **Fork Γ-F6 is now RULED (Daniel, 2026-08-01): dynamic latency ships as specced and the deactivate/reactivate is accepted.** There is no constant-reported-latency fallback — that option is closed, not shelved — so **this section does not shrink to a footnote and the limiter enable does not become automatable.** Plan against the not-automatable classification; it is settled. **One future condition could reopen it, and it is worth knowing about.** The restart is only expensive because *this plugin's* `setActive(true)` re-decodes the WAV — not because the SDK requires it. `docs/TODO.md` ("Decouple the instrument reload from VST3 activation") files that reduction, and **"the limiter enable is wanted automatable" is one of its named trigger conditions.** If the parameter work genuinely needs that lane, the answer is to do the decoupling first, not to re-litigate the classification. --- ## 4. The sequencing assertion — now satisfied inside one phase **The knob-taper work (Phase Γ item D) must land before the parameter system. Not alongside; before.** - Re-tapering is **free today** — normalization is a UI layer, the payload stores raw engine doubles, and a re-taper moves the needle angle and nothing else (saved projects reload bit-identical). - Re-tapering is **permanently expensive after parameters ship** — the taper becomes the host-facing normalization, and changing it re-interprets recorded automation in project files we do not own and cannot migrate (§3.2). The same argument, weaker but real, applies to `DeckParam` additions and reordering (§3.1): Phase Γ adds Rate and Pitch to that enum, and doing it now costs one exhaustive-switch update; doing it after parameters ship costs a frozen-id decision. **So the tension the brief flags is real, and it resolves in Γ's favour.** Both item D and the parameter system touch `deck_values.cpp` and `editor_controls.cpp`, and the ordering is not a coin flip: item D first, by a wide margin. **What changed when the parameter system moved INTO Phase Γ.** The assertion above was written to justify Γ running before a later phase. It now governs **wave order inside one phase**: Γ-W1-T1 lands the taper, Γ-W4-T1 lands the parameters, and two whole waves of new controls sit between them so that every parameter exists before any parameter is declared. The argument is unchanged; only its blast radius shrank, which is strictly better — the two halves are now reviewed against each other rather than across a phase boundary. **And it grew a second clause.** Daniel's ruling *"extend the stage lengths to 10 s"* reverses Γ-F3 and moves `kEnvTimeMaxSeconds` 2.0 → 10.0 into **Γ-W1-T1, beside the taper**, for exactly the reason stated here: a range endpoint is part of the host-facing normalization every bit as much as the curve between the endpoints is. §8 sweeps for every other constant with that property. --- ## 5. Open questions — status after the promotion The scoping pass collected eight. Seven are closed below; one is open and is a Daniel call. | # | Question | Status | |---|---|---| | 1 | Blob vs. parameters as the source of truth (§3.3) | **CLOSED — (b), blob authoritative.** §6.1 | | 2 | `ParamID` space (§3.1) | **CLOSED — independent frozen table.** §6.2 | | 3 | The discrete/rebuild-tier controls (§3.4) | **CLOSED — omitted from the list entirely**, not exposed-and-flagged. §7.2 | | 4 | Per-parameter live/latched classification (§3.5) | **CLOSED — the list is DERIVED from the three-state predicate**, never hand-maintained. §7 | | 5 | Unit tree shape (§3.6) | **CLOSED — the deck's groups, in signal-flow order**, layout-independent. §6.4 | | 6 | Sample-accurate vs. block-boundary (§3.7) | **CLOSED — block boundary, stated explicitly.** §6.5 | | 7 | Does the extension's `instrument_drop` need to know? | **CLOSED — no.** It was the sharpest cost of option (a), and (a) is not taken. The blob a drop writes still fully determines the sound. §6.1 | | 8 | Migration | **CLOSED as a design question, OPEN as a verification.** §6.6 | | **Γ-F7** | **Parameter ORDER — signal flow, or the editor's visual rows?** | **OPEN — Daniel.** Recommendation and reasoning at §6.4. Must close before Γ-W4 dispatches; blocks nothing before then. | --- ## 6. The specification — architecture, identity, order ### 6.1 Storage: the blob stays authoritative; parameters are a projection (option (b)) **Decided, not deferred.** Two verified facts collapse §3.3's fork: 1. **This plugin is a `SingleComponentEffect`, so there is only ONE state.** The SDK's own header `#define`s `setState`/`getState` to `setEditorState`/`getEditorState` around its include of `vsteditcontroller.h`, *"work around for the name clash of IComponent::setState and IEditController::setState"* (`public.sdk/source/vst/vstsinglecomponenteffect.h:41-47`). `setComponentState` exists to feed a **separate** controller in a split-component plug-in; we have no separate controller. §3.3's "a value that lives in both can drift, depending on call order" describes a hazard of a design we do not use. **The drift class it warns about is substantially smaller than the scoping pass assumed.** 2. **The blob is a cross-artifact contract.** The extension's `instrument_drop` writes the identical bytes to build a transient `.vstpreset` (`map/component_state_io.h`). Under option (a) a blob the extension writes would no longer fully determine the sound — a shipped seam would silently become partial. That is not a trade, it is a regression. Add the repo's own invariant — *"the instrument holds ONE loaded capture and ONE set of playback parameters… every playback parameter edits in exactly one place"* — and option (a), which splits the parameter set across two storage mechanisms, is arguing against the invariant Θ-W1-T1 was run to establish. **The rule, stated so it cannot drift:** > **`InstrumentParams` / `PlaySeconds` is THE model. The `ComponentState` blob is its only > persistence. A VST3 parameter is a THIRD SURFACE onto that model — a peer of the deck > knob and the overlay node, not a second copy of the value.** > > - **Load:** the blob restores the model; every exposed parameter's normalized value is > then *derived* from the model and pushed to the controller. The SDK is explicit that > this push must not be reflected back to the host: *"The controller must never pass this > value-change back to the host via the IComponentHandler. It should update the according > GUI element(s) only"* (`ivsteditcontroller.h:430-433`). > - **Host → plugin:** a parameter change writes the model through the **existing commit > tiers** (`shell/instrument/CLAUDE.md`) — live publish or note-on latch. It never takes a > fourth route. > - **Plugin → host:** an editor gesture writes the model AND notifies the host, bracketed > `beginEdit` / `performEdit` / `endEdit` (`ivsteditcontroller.h:175-185`), on the UI > thread as the SDK requires. > - **Save:** `getState` serializes the model. Nothing new is persisted. > > **The residual risk is not drift, it is authority:** a host automation lane, once written, > outranks anything the plugin sets, because the host replays it. That is inherent to > automation and is not a defect to design away — but it has one sharp consequence for the > resample bake, and that is §9. **[verify] at the track, before wiring:** that REAPER calls `setState` (not `setComponentState`) on a single-component plug-in, and the ordering of `setState` against the first `IParameterChanges` block after a project load. Verify against the vendored SDK and in the DAW — do not build on the paragraph above without it. ### 6.2 The ID space: hand-assigned constants in one frozen table **`ParamID` is an independent space from `DeckParam`, defined by a hand-written table of named constants in one pure module.** Not derived, not computed, not an enum cast. **Why hand-assigned rather than derived.** A derived id is a function of something else — enum position, group index, a hash of a name — and every one of those inputs is a thing that must then never change. Deriving does not remove the freeze; it hides it behind a mechanism, and the day someone reorders the source enum the ids move silently. A literal table makes the freeze **visible at the point of change**: you cannot renumber it by accident, because renumbering it means editing the numbers. **The layout — blocks of 100 per deck group, steps of 10 within a block:** | Block | Group | Reserved | |---|---|---| | `1000` | PITCH/RATE | 1000–1099 | | `1100` | PITCH ENV | 1100–1199 | | `1200` | FILTER | 1200–1299 | | `1300` | FILTER ENV | 1300–1399 | | `1400` | AMP ENVELOPE | 1400–1499 | | `1500` | VELOCITY | 1500–1599 (reserved; empty today — §7.3) | | `1600` | VOICE | 1600–1699 (reserved; empty today — §7.2) | | `1700` | MASTER | 1700–1799 | - **Within a block, ids step by 10** in the group's own left-to-right cell order. Nine free slots sit between every pair of neighbours, so **a control added later lands numerically adjacent to its siblings instead of appended at the end of the whole table.** That is the concrete content of "make the parameter order logical": the order is a property of the numbering scheme, maintained by construction, not by remembering to re-sort. - **A curve-exponent inner dial takes its outer knob's id + 1.** The dial is a property of the knob it sits inside — the codebase already says so (`curveParamFor`, "each is the INNER DIAL of the stage knob it shapes") — so its id says so too. This is why the step is 10 and not 2: it leaves room for the dial *and* for a future sibling knob. - **Blocks start at 1000, not 0.** `0` is a plausible accident (a default-initialised `ParamID`), and a scheme whose first legitimate id is also its most likely bug value is a scheme that cannot tell them apart. - **An empty block is still reserved.** VELOCITY and VOICE expose nothing today. Their blocks exist so that if either ever gains an automatable control it lands in its own group's range rather than in whatever range happened to be free. ### 6.3 The freeze invariant State this in the ID table's header, with the same force as its three siblings. > **THE PARAMETER-ID TABLE IS FOREVER-FROZEN.** A VST3 `ParamID` is recorded by the host > into automation lanes inside project files this repo does not own and cannot migrate. > From the first shipped build that exposes parameters: > > - **No id is ever reassigned, reused, or re-pointed.** If a control's meaning genuinely > changes, it takes a NEW id and the old one is **retired** — marked dead in the table, > never re-issued. > - **No exposed parameter's normalization ever changes** — not its taper, not either range > endpoint, not its `stepCount`. The normalization *is* the meaning of every recorded > automation point. §8 enumerates every constant this now freezes. > - **A parameter's meaning never depends on a mode.** The Gate-face and Trigger-face stage > times are separate stored fields and take separate ids; an id whose plain value means > one thing in Gate and another in Trigger is unautomatable by construction. > - **A new control takes the next free slot inside its own group's block**, never the next > number at the end of the table. > > This sits on the same footing as the extension's `"STABLE_FOREVER_STRING"` command ids > (root `CLAUDE.md`, "REAPER extension contract"), the two VST3 class UIDs > (`core/wire/reasampler_uid.h`, FOREVER-FROZEN), and the params-payload field order > (`map/component_state_io.h`, "EVERY wire format below is FROZEN"). It is the fourth > member of that family, not a new kind of rule. **One property the table BUYS, and it is the reason to prefer it over deriving:** `DeckParam`'s header says the enum is *"runtime-only… free to change."* With an independent table that stays true — the reflow, a future regrouping, a new deck can all reorder the enum freely. Deriving ids from it would have quietly repealed that sentence. ### 6.4 Order and grouping — Γ-F7, OPEN Two orders exist and they are not the same thing: - **Identity order** — the id numbers, frozen by §6.3. - **Presentation order** — the sequence `getParameterInfo(index)` reports, which is what a host's FX-parameter list and every automation-lane picker display. They should agree (a list whose numbering runs backwards against its display is a trap), so this is one decision, and it is a forever one on both counts. **Recommendation: signal-flow order — PITCH/RATE → PITCH ENV → FILTER → FILTER ENV → AMP → VELOCITY → VOICE → MASTER**, which is the deck's own documented ordering rule (`sampleDeckGroups`, *"left to right, in SIGNAL-FLOW order: pitch → filter → amp, then the two instance-wide groups"*), with each group's cells in their own left-to-right order. **The alternative is the editor's visual rows** after Γ-W3-T1 — row 1 PITCH/RATE, FILTER, VELOCITY, VOICE; row 2 PITCH ENV, FILTER ENV, AMP; MASTER spanning. Same membership, different sequence. **Why the recommendation goes to signal flow:** the visual layout is a canvas-constrained artifact that has already moved twice (Θ-W6-T1 grew the floor 840 → 980, Γ-W3-T1 takes it to 1190 and re-rows every group), and within-row order is decided by *width fitting*, not by meaning. Freezing the host-facing order to a layout that demonstrably moves is the wrong coupling; signal flow has never moved and is the deck's own stated rule. §3.6 asked whether the unit tree mirrors the visual grouping or the signal flow and noted "they currently agree" — the reflow is exactly what makes them stop agreeing, so the question has to be answered rather than deferred again. **Why it is nonetheless Daniel's:** the counter-argument is real — a user hunting a parameter in REAPER's flat list finds it fastest if the list reads in the order their eyes scan the plugin window. If Daniel weights find-it-on-screen over layout-independence, visual order is the right answer and it is not a mistake; it just also means the parameter order stops being free the next time the deck is re-laid. **Grouping is settled either way: `IUnitInfo`, one unit per deck group**, mirroring the group inventory (not the rows). Only the sequence is at issue. ### 6.5 What the plugin must implement, as behaviour Not architecture — the engineer's call is *how*. These are the observable contracts: - **`getParameterCount` / `getParameterInfo`** report exactly the §7 list, in §6.4's order, each with: the frozen `id`; a `title` that survives truncation and a distinct `shortTitle`; `units` (`"ms"`, `"st"`, `"%"`, `"dB"`, `""` for exponents) matching what the editor prints, so the host's readout and the knob's label never disagree; `stepCount = 0` (every exposed parameter is continuous — §7.2 is why); `defaultNormalizedValue` per §8's exactness rule; the group's `unitId`; and `kCanAutomate`. - **`kIsBypass` is not set on anything.** The limiter is a safety device, not a bypass, and binding it to `kIsBypass` would hand the host a control that restarts the component (§3.8). The plugin exposes **no** bypass parameter — it is an instrument. - **`setParamNormalized` / `getParamNormalized`** are the model projection of §6.1, not a cached shadow value. - **`normalizedParamToPlain` / `plainParamToNormalized` / `getParamStringByValue` / `getParamValueByString` all route through the ONE taper module Γ-W1-T1 extracts.** This is the structural point of that extraction: the host's normalization, the knob's needle angle, and the overlay node's position must be the *same function*, not three functions that agree today. `getParamStringByValue` reuses the editor's own formatters (`formatEnvTimeMs` and its peers) for the same reason. - **`IParameterChanges` is observed at BLOCK boundaries** — the last point in the block wins for that block (§3.7). Sample-accurate application would put a per-sample "did anything change" question on the per-voice-per-sample path, which the phase-wide guardrail forbids. **State it in the header rather than leaving it to be discovered**; revisit only if audible stepping is reported on a fast curve. - **A host parameter change takes the control's existing commit tier and no other.** Live parameters publish; note-on-latched parameters publish and are read by `snapLive`. Nothing on the automation path may reach `reloadInstrument` or `rebuildVoiceEngine` — which is precisely what §7.2's omissions guarantee. - **`IMidiMapping` is in scope and nearly free** (`ivsteditcontroller.h:558-568`): declaring a CC → `ParamID` map costs one function and gives every exposed parameter MIDI control. **[propose at review]** whether to ship a default map in this track or leave it to REAPER's host-side MIDI learn; do not silently skip it without saying so. - **`IParameterFunctionName` is assessed and NOT implemented** (`ivstparameterfunctionname.h`). Its vocabulary is compressor/panner/dry-wet semantics (`Comp:GainReduction`, `DryWetMix`, `Randomize`); none of it names anything this instrument exposes. Recorded so it is not re-surveyed. - **`IAutomationState` is assessed and NOT implemented** (`ivstautomationstate.h`). It reports the host's automation mode for the **whole plug-in** (`kNoAutomation` / `kReadState` / `kWriteState`), not per parameter — so it cannot answer "is THIS parameter automated," which is the only question §9 would have wanted it for. ### 6.6 Migration — the verification, not a design Every saved project predates parameters, and under §6.1 that is a non-event: the blob restores the model and the parameters are derived from it. Three things are nonetheless **[verify], not assume**: 1. A pre-parameter project opens with every parameter reading the blob's value, and sounds identical. 2. A project saved by the new build and opened by an **older** binary still restores fully — the blob carries everything, so it should; prove it. 3. A project with automation drawn on a parameter, saved and reopened, replays that automation against the same plain values — the round trip through the frozen taper is exact at both ends. --- ## 7. The classification — which controls become parameters **The list is DERIVED, never hand-maintained.** Its rule is one line: > **A control is an exposed VST3 parameter if and only if its commit class is `Live` or > `NoteOnLatched`.** Everything else is omitted from the parameter list entirely. That makes `isLiveDeckParam` / `liveCommitFor` — already *"THE home for why each excluded control is excluded"* — the single source for the parameter list too, which is the standing rule (`core/instrument/CLAUDE.md`: *"which controls are live is ONE decision, recorded in ONE place"*) applied once more rather than a second table opened beside it. ### 7.1 Exposed — 44 parameters Counts are against the control inventory as it stands at the end of Γ-W3; the track asserts the count against the predicate rather than against this table. | Group | Parameters | Class | |---|---|---| | **PITCH/RATE** (3) | Rate; Pitch offset; Key-track | Rate **NoteOnLatched** (Γ, settled); Pitch **Live**; Key-track **NoteOnLatched** (see §7.4) | | **PITCH ENV** (6) | attack, hold-fraction, decay, depth + attack/decay curve exponents | **Live** | | **FILTER** (7) | morph, cutoff, Q, drive, mod amount, velocity amount, key-track | **Live** | | **FILTER ENV** (13) | AHDSR A/H/D/S/R; Trigger AHD A/H/D; five curve exponents | **Live** | | **AMP ENVELOPE** (14) | AHDSR A/H/D/S/R; Trigger AHD A/H/D; Trigger length; five curve exponents | **Live**, except Trigger length **NoteOnLatched** (§7.4) | | **VELOCITY** (0) | — | its three cells are curve popups, not scalars (§7.3) | | **VOICE** (0) | — | rebuild tier (§7.2) | | **MASTER** (1) | Master gain | **Live** | **Both play-mode faces are exposed simultaneously**, because both are stored simultaneously and always have been. A Trigger stage time is a real parameter whose effect is silent while Gate is selected — which is the same relationship a disabled filter's cutoff already has, and far better than an id whose meaning depends on a mode (§6.3). ### 7.2 Omitted — the reload and rebuild tiers, and why "omit" beats "expose read-only" **Discrete / reload tier:** play mode (Gate|Trigger), pitch engine (Varispeed|Preserve), filter enable, filter morph law, pitch-envelope enable, the three Staged|Spline mode toggles. **Rebuild tier:** voice count, Poly|Mono, Retrigger|Legato. **Latency-changing:** the limiter enable (§3.8 — settled, and its one reopening condition is named there). The scoping pass left three options (gain a live path / expose non-automatable / omit). **Omit.** An exposed-but-not-automatable parameter is still listed in the host's generic panel and is still *settable from it*, which would let a generic-panel drag reach `reloadInstrument` from a host thread — strictly worse than the control being absent. VST3's `kIsReadOnly` would prevent that, at the cost of a visible row the user cannot move, in a list whose whole purpose is things you can move. Neither beats absence. **Named limitation, stated rather than discovered:** the user cannot automate filter on/off, play mode, the pitch engine, Staged↔Spline, or polyphony. The unlock is written down and is not this track's: **give the control a live path first, then it qualifies by the same rule that excluded it.** Nothing about the parameter system needs to change to admit it. **One door this closes by omission** — if voice count were exposed, its 1–32 ceiling would become a frozen `stepCount` and could never be raised. It is not exposed, so it is not frozen; a future "expose voice count" proposal must accept that freeze as part of the price. ### 7.3 Omitted — structural state The loaded capture and `SampleRefs`; root note; loop start/end, the loop crossfade, and **the new loop enable** (Γ-W2-T2, user-owned from that track on); start frame; channel mode; the three velocity transfer curves; the three spline contours; the three overlay-select radios (view state, never persisted); preview velocity (a utility, not a musical parameter). None of these are scalars with a taper, and several are not scalars at all. They stay in the blob, which is exactly what §6.1's split is for. ### 7.4 Two promotions the three-state predicate makes available Γ-W2-T1 introduces `NoteOnLatched` for Rate. Two controls that are excluded from the live set **for the note-on-latch reason** currently route through the reload tier, and the new state fits them exactly: - **Key-track** — `isLiveDeckParam`'s header already says it *"feed[s] values a voice latches at note-on by design (the pitch ratio…), so live delivery would retune… a note already struck."* That sentence describes `NoteOnLatched`, not `Reload`. - **Trigger length** — *"resolves `playEnd_`, a fact about the note, not a setting of it."* Same shape. **[propose at review, Γ-W4-T1]** promote both. The promotion aligns the routing with the predicate's own stated semantics — and it is what makes them automatable, since today they would re-decode a WAV per automation point. **If either promotion is refused, that control simply drops out of the parameter list.** The list follows the predicate; the predicate is never bent to fill the list. **Not promoted, and not proposed for promotion: Rate to Live.** §3.5 records the cost; that paragraph is the first thing to read if it is ever proposed. --- ## 8. One-way doors — the sweep **Deliverable, run 2026-08-01 against `dev`.** Once parameters ship, anything that participates in a parameter's normalization is frozen as hard as the id itself. This is the complete list of such constants, with a disposition for each. **Two were already known; five are new; three are already frozen for an unrelated reason and are recorded so they are not "tidied" later.** **Scheduled ahead of the parameter track — action required:** | # | Constant / property | Disposition | |---|---|---| | 1 | **The ms and semitone tapers** (`ui/deck_values`) | Γ-W1-T1. Known. The taper *is* the host normalization. | | 2 | **`kEnvTimeMaxSeconds` / `kGateStageMaxSeconds` 2.0 → 10.0** | Γ-W1-T1, per Daniel's ruling. A range endpoint is normalization. Γ-F3 reversed. | | 3 | **Every default must have an EXACT normalized preimage** — NEW | Γ-W1-T1 acceptance criterion. `ParameterInfo::defaultNormalizedValue` is normalized, so a host's reset-to-default arrives as `toPlain(defaultNorm)`. Γ-W1-T1 makes `resetDeckParam` **bypass** the taper, which fixes the editor's reset and **cannot fix the host's** — the host has no bypass. The taper must therefore be designed so every default round-trips exactly, or the host's reset lands a hair off and the "double-click lands exactly on its default" criterion holds on one surface and not the other. **This is the sharpest new finding in the sweep.** | | 4 | **Do NOT re-taper the filter's four normalized controls** — NEW | Γ-W1-T1 exclusion. Cutoff/Q/morph/drive persist as `cutoffNorm`/`resonanceNorm`/`morphNorm`/`driveNorm` in the **v9 payload** — their laws are *already* wire-frozen today, and re-mapping them would re-tune every saved project independently of automation. §4.2's snap-unit table names them, which is a display concern; nothing in the taper pass may touch their norm↔plain law. | **Frozen by this work — record only, no change wanted:** | # | Constant | Note | |---|---|---| | 5 | `kKeyTrackMax` = 2.0 (0–200 %) | NEW. Becomes the frozen normalization of both key-track parameters. If 0–200 % is ever going to be thought wrong, now is when it is free. Recommendation: **no change.** | | 6 | The curve-exponent domain 0.1 … 10 and its log travel (`core/util/curve_law.h`) | NEW. Twelve exposed inner dials. Recommendation: **no change.** | | 7 | Master gain's dB taper, −∞ … +24 dB, unity ≈ 0.714 norm (`engine/master_gain`) | NEW. Already a shared pure module, which is why the needle and the audio cannot drift; the host joins as a third consumer. Unity is a default → it is a **#3 case**, and the sharpest one, because a host reset that lands a hair off unity is audible as a gain error. | | 8 | `kPitchDepthMaxSemis` / `kVelocityPitchRangeSemitones` = 24.0 | Already frozen — the v12 wire format stores the pitch curve's y as a fraction of it. Now doubly frozen. The plan already forbids minting a second ±24 constant. | | 9 | Rate's 50–200 % (±12 st linear) and Pitch's ±24 st centre-expanded laws | Set at birth in Γ-W2-T1, two waves before parameters. **Closed by ordering** — recorded so nobody "tunes Rate's range" in a later phase. | | 10 | The parameter INDEX order and the `IUnitInfo` unit ids | NEW, softer than the id freeze but user-facing and cached by some hosts. Set once, at Γ-W4-T1. §6.4. | **Swept and clear — not doors:** - **The params-payload ladder.** Under §6.1 the blob stays authoritative, so payload growth continues on its own independent axis exactly as before. Automation adds no constraint to it. - **`stepCount`.** No discrete parameter is exposed (§7.2), so no step count is frozen. - **Hold fractions, sustain level, Trigger length.** Natural `[0,1]`, identity taper, nothing to freeze beyond the identity. - **The limiter's −0.3 dBTP ceiling, `kMaxCurvePoints` = 128, the editor floor/budget constants, loop and crossfade frame domains.** None participate in a parameter normalization. **Nothing further was found.** The sweep covered: every constant `ui/deck_values` reads or writes; every `*Norm` field in the payload ladder; `core/util/curve_law.h`; `engine/master_gain`; `engine/play_params.h`'s range constants; and the two range constants Phase Γ itself introduces. --- ## 9. What automation does to the resample bake — and it is not small Ξ-W2's bake ends by **resetting the baked-in parameters to default**, "destructive to the dialled settings by design." Exposing those same values as VST3 parameters changes that step in two ways. Both are **Γ-W4-T1's** to carry, because Γ-W4-T1 is what creates them. 1. **The reset must notify the host.** After §6.1, writing the model without a `beginEdit`/`performEdit`/`endEdit` bracket leaves the host displaying — and, on the next touch, re-imposing — the pre-bake value. **Every internal writer of a model value that is an exposed parameter must go through the one notification path**, and the bake's reset is the first non-gesture writer in the codebase. Enumerating those sites is part of the track, not a follow-up. 2. **A host automation lane outranks the reset, and we cannot clear it.** An automation lane lives in the host's project data. If a reset-class parameter carries one, the lane replays its curve onto audio that already has that processing baked in — **double processing**, and Ξ-W2-T1's own acceptance criterion ("after the click… sounds as the dialled instrument sounded just before the click") does not hold in that case. **There is no detection available.** `IAutomationState` reports the host's automation mode for the whole plug-in, not per parameter (`ivstautomationstate.h:43-53`), and nothing else in the SDK's edit-controller surface answers "is this parameter automated." So "refuse the bake when an automated parameter would be reset" and "reset only the un-automated ones" are both unbuildable, not merely unattractive. **Disposition: a named, documented limitation.** The bake resets the plugin's values; it cannot clear the host's lanes, and the user's remedy is to remove the lane. Stated in the product doc and in the track's acceptance criteria as a *known* boundary of the bake's fidelity claim — **not discovered later as a bug report against Ξ.** --- ## 10. Build shape **Γ-W4-T1 `vst3-parameter-set`** — one track, the last in Phase Γ, specified in `docs/PLAN.md`. It depends on all three earlier waves: on Γ-W1-T1 for the taper module that becomes the host normalization, on Γ-W2-T1 for the three-state predicate and the two new controls, and on Γ-W3 for the final control inventory and a bake whose reset list is already complete (`docs/PLAN.md`, Γ-W3-T2). **It takes no rung of the params-payload ladder under §6.1** — nothing new is persisted. A rung is nonetheless **reserved** for it in case the architecture verification (§6.1's `[verify]`) forces a persisted field; if unspent, the rung falls through to the next phase.