# MIDI playback — opportunity & design-space framing Framing for a **MIDI-triggered audio sampler** that plays back ReaSampler's captured banks. This began as a discussion-shaping doc; with all forks now settled it has become the **product framing behind a scoped phase**. Its build roadmap lives in **PLAN.md §Phase S** and its authoritative spec in **CONTEXT.md §Phase S** — this doc holds the *why* (the plugin-format reasoning, the bare-VST3-vs-JUCE assessment, the settled decision record). Status: framed by product-designer (2026-07-26), **revised 2026-07-27 (r9)**. r9 records the **three-view editor redesign** (Sample / Browse / Zone) and its follow-up settlements: the S-VIEW-F1 and S-VIEW-F2 forks are now **SETTLED** (2026-07-27) — **preview velocity persists** via the instrument's own VST3 component state (envelope bump to v6, *not* the extension's project ext-state), and the **envelope overlay's nodes are draggable** via a new pure `envelope_edit` module — and S-VIEW builds **directly on the finished, merged Phase L L3 look-and-feel** in a **single implementation pass** (no two-pass restyle-after; L3 landed 2026-07-27, commit `c53683e`). Only S-VIEW-F3 (Browse modal presentation) remains open. Full r9 record in the Addendum below. r8 records Daniel's **duration-preserving correction** (2026-07-26, verbatim: *"isn't that ratio stuff going to change the playback rate? I want duration-preserving repitching"*): the ratio path is **varispeed** (pitch/duration coupled), so S16 is reshaped from "pitch envelope only" into a **pitch-engine mode — Varispeed vs Preserve — plus the pitch envelope** riding either engine. The WDL verdict flips: `WDL_SimplePitchShifter` (duration-preserving OLA), previously dismissed as the wrong tool, is **now the Preserve-engine candidate** and got a real per-voice RT viability assessment. Two S16 forks flagged: **S16-F1** (engine default — lean Preserve) and **S16-F2** (Preserve implementation — WDL shifter first, hand-rolled pure module held). See the r8 Addendum in §4. r7 records the **sampling-modes engine directive** (Daniel, 2026-07-26): Trigger vs Gate play modes (Gate = AHDSR, Trigger = one-shot with %-length + fades), a modifiable start point in both, and an off-by-default AD pitch envelope — specced as **new Phase S points S15/S16**, with the WDL pitch surface swept and reported. See the "sampling modes" Addendum in §4. r6 records the **workflow-first reframe of S10** (Daniel, 2026-07-26): the editor's default face becomes a **capture browser + guided single-capture setup**, a fresh instance is **silent with a "pick a capture" empty state** (reversing the S4 first-sample auto-play), and multi-zone editing is demoted to an opt-in Zones panel — see the r6 Addendum in §4. r6 also settles **S-NAME-1** (rename the binary filename too, UID locked). r5 records the post-DAW-test directives on the S1–S6 instrument: the product name **ReaSampler 9000** and the **"better than RS5K" UX overhaul** (Phase S points S10–S13) — see the r5 Addendum in §4. r4 (below) settled the four residual forks D-A..D-D. The "no PLAN.md footprint" era is **over** — with D-A through D-D settled (below), the instrument was scoped into **Phase S** (codename Daniel's: "S" for Sampler, because "D" collides with the existing Design View phase). **PLAN.md §Phase S is now the authoritative roadmap; CONTEXT.md §Phase S is the authoritative spec.** This doc is the framing/decision record they point back to. Prior revisions (a) established that a REAPER *extension* cannot be a MIDI instrument, (b) corrected a material omission — REAPER's **VST-host bridge**, which lets a VST3 plugin *hosted inside REAPER* call back into REAPER's own API by resolving function pointers by name over the host callback — (c) [r3] folded in **Daniel's locked decisions** (D1, D5, D6) and added the honest **bare-VST3 assessment** (§1a). This revision [r4] records **Daniel's calls on the four residual forks D-A..D-D** (all settled 2026-07-26) and points to the now-live phase docs. Grounded in the vendored REAPER SDK headers (`vendor/reaper-sdk/sdk/reaper_plugin.h`, `reaper_plugin_functions.h`, `video_processor.h`, `reaper_plugin_fx_embed.h`), REAPER's published VST-extensions SDK page (`reaper.fm/sdk/vst/vst_ext.php`), and the Steinberg VST3 SDK documentation (portal + class reference — cited inline in §1a). Where a claim is **experienced estimate** rather than a **verified-from-source** fact, it is flagged as such in §1a. The genuine remaining forks are flagged as **Daniel's to decide**; nothing here pre-decides them. > ## Locked decisions (SETTLED — do not re-present as open) > > Daniel has nailed these down. Everything downstream assumes them. > > - **D6 → DECIDED: two products, but integrated.** The instrument is a *separate* > product/artifact from the ReaSampler extension, but *tightly integrated* via the > VST-host bridge — it reads live `"reasampler"` project ext-state and is project-aware. > **Not** a divorced, file-only companion. (The old §4 D6 reasoning is preserved below, > marked decided.) > - **D1 → DECIDED: native VST3.** JSFX is off the table. The instrument is a native VST3 > plugin. (The old JSFX option and its whole-doc entanglement are retired below, marked > decided; the JSFX reasoning is kept as the record of *why* it was considered and set > aside.) > - **D5 → DECIDED: no cross-platform, no multiformat. REAPER-specific, Windows-only.** > The existing extension is Windows-only; Daniel does not work on other platforms. So: > **no mac/Linux DSP/build/signing matrix, no CLAP-for-portability argument, no > "runs standalone in other hosts" concern.** REAPER-coupling via the bridge is fine and > intended. This collapses several costs the prior draft carried (§1a, §4). > > **What these lock-downs do to the shape:** the doc is no longer weighing "extension vs. > plugin," "JSFX vs. native," or "portable vs. coupled." It is weighing **how to build one > native, Windows-only, REAPER-coupled VST3 instrument** — and the single biggest live > question inside that is now **bare Steinberg VST3 SDK vs. JUCE** (§1a, D-A below). > **The bridge, stated once, up front (the correction).** A hosted VST is not limited to > scraping bank WAVs + JSON off disk. REAPER hands the plugin its host callback; calling > `hostcb(&effect, 0xdeadbeef, 0xdeadf00d, 0, "FunctionName", 0.0)` resolves *any* REAPER > API function by name — the same string-keyed API surface the extension uses (verified: > `video_processor.h` line 44 imports `video_CreateVideoProcessor` exactly this way; > `GetProjExtState`/`SetProjExtState`/`EnumProjExtState` are ordinary entries in that same > string-keyed table, `reaper_plugin_functions.h` lines 8376/8796/9969). The plugin can > also fetch its **host context** — the track/take/project it's instantiated in (sibling > opcode `0xdeadf00e`, `video_processor.h` line 40; CLAP has `clap_get_reaper_context`, > `reaper_plugin.h` line 142). **Consequence:** a native ReaSampler instrument can read > the *same* `"reasampler"` project ext-state that `persist` writes — live, project-aware, > following the active project — not a file it re-parses off disk. This is a > REAPER-VST-specific capability (it exists because the plugin is hosted *in REAPER*), and > it is the thumb on the scale the prior draft failed to weigh. The cost of leaning on it > is stated honestly in D1/D2: it makes the native plugin **REAPER-coupled.** --- ## The need, stated plainly ReaSampler today **captures and organizes** audio into per-project banks (on-disk 32-bit float WAVs + a JSON index, multi-bank via `bank_book`). It has **no way to play those samples back from a MIDI keyboard.** The panel can *audition* a sample on click — but a one-shot, one-voice audition is not an instrument. There is no key→sample mapping, no velocity response, no polyphony, no envelope, no round-robin. The ask: *what would let me play my captured banks MIDI-triggered, and what does the REAPER surface actually allow toward that?* The rest of this doc is organized as the task framed it: (1) the plugin-format reality, honestly; (2) the integration seam between capture and playback; (3) product shape and scope tiers; (4) the forks that are Daniel's to call. --- ## 1. The plugin-format reality (the honest part) **The load-bearing fact: a REAPER extension cannot be a MIDI-triggered instrument.** This is not a limitation we can engineer around by trying harder — it is what the plugin *format* is. ReaSampler today is a `reaper_*.dll` loaded at startup via the extension API (`ReaperPluginEntry`). That format gives an extension enormous reach over the *project* — tracks, items, actions, rendering, project state — but it is **not a node in any track's audio signal chain.** An instrument track's "read live MIDI, emit audio per-voice" contract belongs to VST/VST3/CLAP/JSFX plugins, which REAPER hosts through an entirely different mechanism. What the extension SDK *does* expose near audio/MIDI, verified in the headers, and why none of it is "be an instrument": - **`Audio_RegHardwareHook` + `audio_hook_register_t::OnAudioBuffer`** (`reaper_plugin.h` ~1228). This is a real-time callback into the audio thread, called pre- and post-REAPER-processing, handing you `GetBuffer(isOutput, idx)` for the **hardware I/O** channels. It is a *hardware tap*, not a track insert. You could technically mix sample playback into the hardware output buffer here — but you'd be bypassing REAPER's entire routing, metering, recording, and rendering path. Output from this hook **cannot be recorded, rendered, routed, or FX-processed** as track audio. It is the wrong tool for an instrument by construction, and it runs in the audio thread with all the real-time-safety hazards that implies. Rejected on sight for this purpose — noting it only to be complete. - **`kbd_OnMidiEvent` / `kbd_OnMidiList`** (`reaper_plugin_functions.h` ~4138). REAPER *informs* the extension of MIDI events (for action-triggering — this is how MIDI can fire the capture/insert actions we already plan to bind). It is **notification, not a routable MIDI input** feeding a synth voice allocator. Great for "MIDI note fires the capture-to-slot action"; useless as an instrument's note input. - **`PlayPreview` / `PlayTrackPreview` + `preview_register_t`** (`reaper_plugin.h` ~1302). This is REAPER's **preview-playback** mechanism, and **ReaSampler already uses it** — `bank_panel.cpp` streams a bank WAV through a caller-owned `preview_register_t` for click-audition (`PCM_Source_CreateFromFile` + `PlayPreview`). This is the one audio-emitting surface the extension already drives, and it is load-bearing for the hybrid option below. But note its shape: it plays *a* source at *a* position with *a* volume — it is a fire-and-forget preview, **not a polyphonic, per-note, velocity-scaled, envelope-shaped voice engine.** You do not get MIDI→voice allocation for free; you'd be building a sampler engine on top of a preview primitive. - **`pcmsrc` registration + `PCM_source` subclassing** (`reaper_plugin.h` ~804, the `PCM_SOURCE_EXT_*` surface). An extension *can* register a custom `PCM_source` type. This is the surface REAPER itself and extensions like SWS use for custom media. It is a real seam — but it produces a *media source* (something an item plays), not a *live-MIDI instrument*. Interesting for "a bank-backed media source" but not the keyboard-instrument ask. **Conclusion, stated for the record:** to get a genuine MIDI-triggered instrument — play a note, hear the mapped sample, velocity-scaled, polyphonic, with an envelope — the playback engine must be a **standard instrument plugin** (VST3 / CLAP / JSFX), *not* the extension. The extension SDK is the wrong format for that job, and this is the single most important thing for Daniel to internalize before scoping anything. ### The shape, now that D1/D6 are locked The old three-way option set (native VSTi / JSFX / hybrid) has collapsed to a single resolved shape: **A separate native VST3 instrument that consumes ReaSampler's banks, tightly integrated via the bridge.** The extension stays the sole owner of **capture + organization** (its whole existing identity and the load-bearing "capture and placement are separate acts" principle). The instrument is a *separate build artifact* — a native VST3 sampler the user instantiates on an instrument track — that maps samples across the keyboard and plays them MIDI-triggered with a real voice engine. It reaches ReaSampler's project state directly via the VST-host bridge: it reads the live `"reasampler"` ext-state `persist` writes, knows its own host project, and follows the active project. This is the "two products, but integrated" shape D6 locked in. The extension never becomes an instrument; the instrument never captures. *What this gives:* everything an instrument is — polyphony, velocity, envelopes, the works, fully in REAPER's routing/render/record path like any VSTi — **plus** live, project-aware integration with the extension's state, not a divorced file-reader. *What it costs:* a **second codebase**, the Steinberg VST3 SDK (or JUCE) as a dependency, and a real DSP/voice-engine build — a product-sized commitment, not a feature. The Windows-only + VST3-only + REAPER-only lock-downs (D5) *remove* the costs the prior draft carried around cross-platform DSP, code-signing, and multi-format wrappers — a material simplification. The remaining cost question is almost entirely **"how much scaffolding does the VST3 surface demand, and do we take JUCE to get it"** — answered honestly in §1a. > **JSFX — retired (D1 DECIDED: native VST3).** Prior drafts weighed a JSFX sampler > (REAPER's built-in scriptable format: zero new binary, zero SDK, cross-platform free) as > the cheap-prototype path. It is off the table. The reasons it lost, for the record: (1) > JSFX is a constrained DSP scripting language — a polyphonic multisample engine with > round-robin/velocity-layers/streaming is doable but fights the idiom, and large-sample > disk streaming is awkward; (2) JSFX gets **no VST-host bridge**, so it could never read > `persist`'s live `"reasampler"` ext-state — it would be a permanently file-coupled > consumer needing a sidecar seam, which is exactly the *loose* companion D6 rejected; (3) > its "pure core" would be JSFX code, outside the CTest harness (see D3). With D5 locking > Windows-only, JSFX's one real edge — cross-platform-for-free — is worth nothing here. > Native VST3 wins cleanly given the locks. --- ## 1a. How crazy is bare VST3 without JUCE? (the honest assessment) Daniel's question, directly: *how crazy is it to comply with the VST3 surface without something like JUCE?* Short answer: **not crazy — the audio-processing side is a few-hundred-lines-of-ceremony-you-write-once problem, not a tar pit. The one genuine question is the editor UI, and ReaSampler is unusually well-positioned to answer it without JUCE.** The detail, honestly, with estimate-vs-verified flagged. ### What the raw Steinberg VST3 SDK actually demands A working VST3 instrument must present these interfaces (all VST3 interfaces descend from `FUnknown`, a COM-like base with `queryInterface` / `addRef` / `release` — **verified**, Steinberg VST3 SDK class reference): - **`IComponent`** — the plugin's identity and bus/state setup: `initialize`, `setActive`, `getBusCount` / `getBusInfo`, `activateBus`, `setState` / `getState`. - **`IAudioProcessor`** — the DSP contract: `setBusArrangements`, `setupProcessing` (`ProcessSetup`: sample rate, block size, symbolic sample size), `setProcessing`, and the hot path **`process(ProcessData&)`** — where you read MIDI events off the event input bus and write audio to the output bus. For an *instrument* you declare an **event input bus** (MIDI in) and an **audio output bus**, no audio input. (**Verified**: `IAudioProcessor` reference; the instrument bus topology is standard.) - **`IEditController`** — parameter model + editor: `getParameterCount` / `getParameterInfo`, `getState` / `setState`, `setComponentState`, normalized↔plain parameter conversion, and `createView("editor")` returning an `IPlugView` if you have a GUI. - **`IPluginFactory`** (via the module's exported **`GetPluginFactory`**) — enumerates the classes the module offers (the processor and, in the two-component model, the controller), keyed by class UIDs. On Windows the module also exports **`InitDll` / `ExitDll`** (bundle entry points differ per-OS, but D5 makes Windows the only target, so it's just these two plus `GetPluginFactory`). (**Experienced estimate** on the exact Windows export names — the SDK's `dllmain.cpp` / `public.sdk` main glue provides these; I have not re-read the header this session, so treat the exact symbol names as to-verify-against-`public.sdk/source/main/` before build, not as a load-bearing claim.) **The COM plumbing is real but bounded.** `queryInterface`/`addRef`/`release` plus the class-factory macros (`BEGIN_FACTORY` / `DEF_CLASS2` / `END_FACTORY`, and the `DECLARE_FUNKNOWN_METHODS` / `IMPLEMENT_REFCOUNT` helper macros) are **provided by the SDK's `pluginterfaces` and `public.sdk` layers** — you do not hand-write refcounting; you invoke macros. (**Experienced estimate** on the exact macro names — these are the long-standing VST3 SDK factory macros; verify spelling against the vendored SDK headers at build time.) This is the "ceremony you write once" — it is copy-adapt-from-the-example work, not design work. **And the SDK hands you base classes that absorb most of it.** The critical fact for Daniel's question: you do **not** implement those four interfaces from scratch. The SDK's `public.sdk` layer provides: - **`AudioEffect`** (with `Component` / `AudioEffect` base) — implements `IComponent` + `IAudioProcessor` boilerplate; you override `initialize` (declare busses), `setupProcessing`, `setActive`, `setState`/`getState`, and `process`. - **`EditControllerEx1`** — implements `IEditController` boilerplate; you override parameter registration and state. - **`SingleComponentEffect`** — **combines processor and controller into one class** (descends from `EditControllerEx1` and the component hierarchy). You override `initialize` (call `addAudioOutput` + `addEventInput`), `setupProcessing`, and `process`. (**Verified**: Steinberg SDK `SingleComponentEffect` class reference — "default implementation for a non-distributable Plug-in that combines processor and edit controller in one component." The SDK cautions to prefer the two-component split for distributable plugins, but for a **REAPER-only, non-distributable** instrument (D5/D6), `SingleComponentEffect` is exactly the sanctioned shortcut and cuts the interface surface roughly in half.) **Honest quantification of the audio side:** with `SingleComponentEffect` + the factory macros, a *silent-but-loading* VST3 instrument skeleton — factory, class registration, module entry, bus setup, empty `process` — is on the order of **~200–400 lines of adapt-from-example ceremony**, written once, then largely untouched. The AGain / Note Expression Synth examples that ship with the SDK are exactly this skeleton and are the copy-source. This is **not** a tar pit. The tar-pit reputation VST3 has comes from (a) multi-format wrappers (AU/AAX/VST2 — **not our problem**, D5) and (b) the GUI, addressed next. (**Experienced estimate** on the line-count band — grounded in the shape of the SDK examples, not a line-counted measurement; treat as an order-of-magnitude honest estimate, not a promise.) ### What JUCE buys — and whether ReaSampler needs it JUCE exists largely to solve problems D5 has already deleted for us. Weighed against the locked constraints: | What JUCE provides | Do we need it, given the locks? | |---|---| | **Multi-format wrapper** (one codebase → VST3/AU/AAX/VST2/standalone) | **No.** Single format, VST3 only, REAPER only. This is JUCE's biggest reason to exist and it's moot here. | | **Plugin boilerplate / `AudioProcessor`** | Marginal. The Steinberg SDK's `SingleComponentEffect` already absorbs the VST3 boilerplate; JUCE's abstraction sits *on top of* the same SDK. | | **Parameter management** (`AudioProcessorValueTreeState`) | Nice-to-have. Genuinely convenient, but a sampler's parameter set (envelope, gain, tuning) is small; hand-rolling over `IEditController` is bounded. | | **DSP utilities** (`juce::dsp`, filters, oscillators, interpolators) | Nice-to-have for Tier 3 (filters/LFOs). For Tier 0–2 the sampler DSP — repitch interpolation, envelopes, voice allocation — is exactly the pure core we *want* to write and test ourselves (D3). | | **Editor/UI framework** (`juce::Component`, graphics, widgets) | **The one real pull.** VST3 gives you `IPlugView` and *no toolkit whatsoever*. Something has to draw the editor. This is the crux — see below. | **Costs of JUCE, honestly:** it is a large dependency (a whole framework, not a library); it brings its own build system (Projucer / CMake integration) and idioms that would sit oddly beside ReaSampler's lean two-submodule CMake discipline; and its **licensing** is a real standing commitment. JUCE 8 is **dual-licensed AGPLv3 or commercial**. The free tier (Starter) is usable below **~$20K/yr revenue** and — notably in JUCE 8 — **no longer requires a splash screen**. Above that, **Indie (~$200K/yr revenue limit) is a paid license (~$3,500 as of JUCE 8)**, and Pro above that. (**Verified via web**, JUCE forum + license pages — see Sources.) For a personal/ReaSampler-scale tool the free Starter tier likely applies today, but taking JUCE means accepting AGPL-or-pay as a permanent posture on the instrument. That's a bigger standing commitment than the Steinberg SDK, which is a **permissive** (proprietary-but-royalty-free, GPLv3-optional) license with no revenue gate. ### The UI is the real question — and ReaSampler is unusually well-armed Strip everything else away and the honest "reach for JUCE?" decision reduces to one thing: **who draws the editor?** VST3 gives you an `IPlugView` seat and nothing to fill it with. The options on Windows-only (D5): 1. **JUCE** — for its `Component` graphics stack alone. This is the *usual* reason indie devs take JUCE, and if ReaSampler had no UI competence it'd be the default. 2. **VSTGUI** — the UI toolkit that **ships with the Steinberg SDK itself**. Lighter than JUCE, purpose-built for VST editors, no extra dependency beyond the SDK you already took. A real middle option. (**Experienced estimate** — VSTGUI is bundled with the VST3 SDK; verify the vendored SDK includes it before relying on it.) 3. **Win32 / GDI / Direct2D directly** — Windows-only makes this viable; you own an HWND in the `IPlugView`. 4. **The same LICE/SWELL stack the extension already uses.** — **This is the one worth staring at for Daniel specifically.** **Why option 4 changes the calculus for *this* project.** ReaSampler's `bank_panel` is **already a LICE-drawn UI** — a real, working, docked, custom-drawn panel (grid, thumbnails, tab strip, hit-testing) built on LICE/SWELL, the same stack REAPER itself and SWS use. That's **67 LICE call-sites in `bank_panel.cpp`** today. The team (Daniel + the implementers) has already paid the learning cost of drawing a custom audio-tool UI in LICE. The usual "take JUCE because hand-rolling a plugin GUI from nothing is miserable" argument is **much weaker here than for a typical indie dev**, because ReaSampler is not starting from nothing — it has demonstrated LICE UI competence and a house style. A VST3 `IPlugView` that hosts a LICE-drawn surface would (a) reuse existing UI muscle, (b) keep the instrument's look consistent with the panel, and (c) avoid the JUCE dependency and its license posture entirely. There's even the **embedded-UI affordance** (D7 below) that lets a REAPER-hosted plugin draw inline in the TCP/MCP using this same Cockos surface. *The honest caveat:* wiring LICE into a VST3 `IPlugView` (window creation, sizing, event routing from the host into your draw/hit-test loop) is **integration work with real edges** — you're bridging the SDK's view lifecycle to a LICE `HWND`/bitmap. It's not free, and it's less trodden than "drop in a JUCE editor." But it is *the same class of work ReaSampler already did* to dock `bank_panel`, not a new competence. (**Experienced estimate** on the difficulty band — grounded in how `IPlugView` and LICE each work, not a built prototype. Flag: the exact `IPlugView`↔LICE bridge should be spiked before it's promised in a plan.) ### The pure-core discipline (D3) lands cleanly here **Confirmed: the discipline holds, and JUCE-vs-bare doesn't change it.** The sampler's voice engine, envelope math, key/velocity mapping, repitch/interpolation, and keymap resolution are pure DSP + data — **exactly the kind of REAPER-free, DAW-free, unit-tested core** this project already excels at (`bank_model` / `peaks` / `view_mode_model` are the template). They live in a pure module, tested in the CTest harness outside any host. The VST3 wrapper — `SingleComponentEffect` subclass, bus setup, `process` marshalling MIDI→core and core→audio-buffer, the `IPlugView` editor, and the bridge calls that read `"reasampler"` ext-state — is the **thin shell**, the only part that touches VST3 or REAPER at all. This is precisely ReaSampler's load-bearing split, transplanted to a new format. Native VST3 makes this *cleaner* than the retired JSFX path would have (JSFX's "core" would be JSFX script, un-unit-testable in CTest). And **JUCE-vs-bare doesn't move it**: whether the shell is a bare-SDK `SingleComponentEffect` or a `juce::AudioProcessor`, the pure core underneath is identical, REAPER-free, and tested the same way. The format choice is a *shell* choice; the core is invariant. That's a reassuring result — it means D-A (bare vs. JUCE, below) can be decided on shell ergonomics and dependency posture alone, without risking the part of the architecture Daniel most cares about. ### Bottom line for Daniel's question Complying with the VST3 surface without JUCE is **reasonable, not crazy** — the audio-processing scaffolding is bounded, example-driven ceremony that `SingleComponentEffect` cuts down further, and the D5 lock-downs delete JUCE's biggest justification (multi-format). The **only** place JUCE earns its weight is the editor UI — and ReaSampler's existing LICE competence makes even *that* argument weaker than it would be for a typical indie. My honest lean (D-A below): **bare Steinberg SDK + LICE editor**, with JUCE as the fallback if the `IPlugView`↔LICE bridge proves gnarlier than the panel work suggests. But it's a genuine fork and it's Daniel's — laid out in §4. --- ## 2. The integration seam There are two seams, and with native VST3 locked (D1) the instrument gets **both**: - **File seam (audio, always).** The sample **audio** is WAVs on disk — there's no getting a live PCM stream across the bridge, nor would you want to. WAVs are project-relative and travel with the `.rpp` (M4 machinery). This is the permanent seam for sample audio. - **Live-state seam (the mapping / index, via the bridge).** For **everything that isn't the raw audio** — the index, the mapping data, which project's bank is active — a native VST instance reads the `"reasampler"` project ext-state directly via the bridge (`GetProjExtState` / `EnumProjExtState`, resolved by name over `hostcb`), and knows its own host project via the context callback. It sees what `persist` last wrote, follows the active project, and needs no "point me at the right bank folder" wiring — it *asks REAPER* which project it's in. This is the tight integration D6 locked in. So: **audio comes across as files; the mapping comes across as live shared state.** The design question below — "is the ext-state/index sufficient, or does playback need mapping it doesn't carry" — is unchanged. What the bridge settles is *where that mapping lives*: between extension and instrument as **live shared `"reasampler"` state**, not a file one writes and the other re-parses. **What the current index carries** (from `bank_model`'s `Sample`, per CONTEXT.md §Data model): id, display name, relative path, source range, channel count, sample rate, length, capture tempo, an **optional key**, peak/RMS/LUFS, content hash, tier, provenance, timestamp. Notably it *already* has an optional key field and capture tempo — the seeds of pitch-mapping are there. **What a playback engine additionally needs** — none of which the index carries today: - **Root note** (the pitch the sample was recorded at, so it can be repitched across the keyboard). The optional `key` is close but is "musical key," not "root MIDI note" — different thing. - **Key range / zone** (low note, high note) — which keys trigger this sample. - **Velocity layers** (which sample plays at which velocity band; a mapping of samples to velocity zones). - **Round-robin groups** (cycle through N samples on repeated same-note hits). - **Loop points** (sustain loop start/end for held notes; sample-accurate, zero-crossing-aware — CONTEXT already flags loop/zero-crossing handling as day-one-relevant for wavetable material). - **Amplitude envelope** (ADSR) and optionally filter/pitch envelopes. - **Tuning/gain trim** per sample. **The design decision this forces:** does the *mapping* (key ranges, velocity layers, round-robin, envelopes) live — - **(i) in the bank index** (ReaSampler owns the instrument definition; the plugin is a dumb player of a ReaSampler-authored map), or - **(ii) in the instrument plugin's own state** (the plugin owns the map; the bank is just a WAV+metadata pool it maps *over*), or - **(iii) split** — the bank carries per-sample *intrinsics* (root note, loop points — facts about the file), and the instrument carries the *arrangement* (zones, layers, envelopes — a performance choice)? **(iii) is the principled answer and worth leading with.** It mirrors ReaSampler's own deepest instinct — the *capture/placement separation*. Root note and loop points are **facts about the captured file** (analogous to sample rate, length, peaks) and belong in the bank, computed or set at/after capture. Key zones, velocity layers, envelopes, round-robin are a **performance mapping** — a creative arrangement of those facts — and belong in the instrument. This keeps the bank a clean, portable, tool-agnostic library (a bank is still just WAVs + facts, readable by anything) while the instrument owns the opinionated part. It also means **the bank index grows only by file-intrinsic fields** (root note, loop points), which is a small, safe, additive change — exactly the kind of seam ReaSampler already knows how to add (mirror of how `provenance` was added as a field in M1 and populated later). **Wiring note (native, the locked path).** The native instance sidesteps the "point me at the right bank folder" problem entirely: via the context callback it asks REAPER which project it's in, then reads that project's bank location straight from `"reasampler"` ext-state — no user wiring, no saved folder path in the instrument's own state. This is the cleanest possible integration and it's the one D6 chose. The one thing to keep deliberate: the WAV **audio** still resolves via the project-relative path machinery (M4), so the instrument must resolve those paths the same way `persist` does — a shared convention, not a hand-wave. Since D5 locks REAPER-only/Windows-only, the old "but it won't run in other hosts" concern is **moot by design** — the bridge dependency is intended, not a narrowing to regret. --- ## 3. Product shape & scope tiers Sketched as tiers, minimal → sophisticated. The point of tiering is that **Tier 0 delivers the core promise** ("play my captured banks from a MIDI keyboard") and each tier above is optional depth, not a prerequisite for the one below. **Tier 0 — "the bank plays."** One sample mapped chromatically across the keyboard from a root note; monophonic-or-basic-polyphony; a simple amp envelope; velocity → volume. Point one bank sample at a MIDI track and play it repitched. *This is the smallest thing that delivers the promise* and is the honest MVP. On the native path this is the skeleton of the VST3 plugin — the `SingleComponentEffect` shell (§1a) plus a single-voice core, with the editor deferrable behind a parameters-only default view. **Tier 1 — "a keymap."** Multiple samples zoned across the keyboard (key ranges), each with its own root note. Now a captured *kit* (several one-shots) or a *multisampled instrument* (same instrument sampled at several pitches) plays correctly. This is where the **root-note + key-range** seam fields (§2) earn their place. Still one sample per key-region. **Tier 2 — "expressive."** Velocity layers (soft vs. hard hits pick different samples), round-robin (repeated hits cycle samples — the anti-machine-gun feature), full ADSR, per-sample tuning/gain trim, sustain loops for held notes. This is a *real* sampler and where "sophisticated" lives. It's also where the mapping data (§2) gets rich enough that the "who owns the map" fork (i/ii/iii) really bites. **Tier 3 — "instrument polish."** Filter + filter envelope, LFOs, per-voice pan, choke groups (hi-hat open/closed), maybe a modest built-in FX slot. Standard sampler feature creep. Explicitly *not* needed to deliver value; a direction to leave room for, not commit to. **The recommended reading:** Tier 0–1 is the "does this even belong in ReaSampler's world" proof. If the answer is yes, Tier 2 is where it becomes a tool people reach for. Tier 3 is optional forever. **Scope the decision at Tier 0–1 first** and treat 2/3 as held futures — don't let a Tier-3 feature list drive the format choice. ### The one-source-multiple-views angle Worth flagging because it recurs in Daniel's work: the bank is **one source** (WAVs + facts). The panel is one view (organize/audition). A MIDI instrument is **another view of the same source** (play). That's a clean framing — the instrument doesn't fork the bank, it consumes it — and it argues for keeping the bank as the single authoritative artifact and the instrument as a pure consumer (seam option ii/iii, never "the instrument keeps its own copy of the samples"). --- ## 4. Decisions — settled and residual ### Settled (DECIDED — reasoning preserved, not re-opened) These are locked. The reasoning is kept as the record of *why*, so the choices don't get silently re-litigated. **D1 — Instrument format → DECIDED: native VST3.** JSFX is off the table (retirement reasoning in §1, in the JSFX box). Native VST3 gives full sampler sophistication, clean integration, and the VST-host bridge (live `"reasampler"` ext-state, project-awareness, embedded-UI affordance). The cost — a second codebase in a plugin format — is accepted. The old "JSFX-first cheap prototype" lean is withdrawn: with D5 locking Windows-only, JSFX's one advantage (cross-platform-for-free) is worthless here, and its inability to reach the bridge makes it the wrong tool for the *integrated* product D6 chose. **D5 — Cross-platform / multiformat → DECIDED: none. Windows-only, VST3-only, REAPER-only.** The extension is Windows-only; Daniel does not work on other platforms. This *removes* costs prior drafts carried: no mac/Linux DSP/build/signing matrix, no multi-format wrapper, no "runs standalone in other hosts" concern, no CLAP-for-portability argument. REAPER-coupling via the bridge is intended, not a narrowing to regret. This is the single biggest simplifier — it is *why* bare VST3 is reasonable (§1a): most of what makes VST3 painful (multi-format, cross-platform) is deleted. **D6 — One product or two → DECIDED: two products, but tightly integrated.** The instrument is a *separate artifact* from the extension (the extension stays the pure capture/organize tool; the instrument is the playback surface — capture and placement, and now playback, stay distinct acts). But it is **not** a divorced file-only companion: via the bridge it reads the live `"reasampler"` project ext-state and is project-aware — "two faces of one tool sharing one state model." The prior draft's open question ("could they only ever share a file?") is resolved: no, and the shared-live-state integration is the chosen shape. The retired reasoning for why the loose-companion reading lost: it only ever looked clean because the prior draft under-weighted the bridge; once the bridge is on the scale, the integrated reading has the stronger technical affordance, and Daniel took it. **D3 — Pure-core discipline across the format boundary → CONFIRMED holds (see §1a).** Not a fork so much as a checked assumption: the sampler's voice engine, envelope math, key/velocity mapping, and repitch/interpolation live in a pure REAPER-free, DAW-free, unit-tested core (mirror of `bank_model`/`peaks`/`view_mode_model`); the VST3 wrapper is the thin shell. Confirmed clean for native, and — importantly — **invariant under bare-vs-JUCE** (§1a): the shell choice doesn't touch the core. This is the most ReaSampler-native way to build it and it's assumed, not debated, going forward. ### Residual forks — SETTLED (Daniel, 2026-07-26; reasoning preserved, not re-opened) All four residual decisions are now called. Each is marked **SETTLED** with Daniel's choice and the reasoning kept as the record of *why* — do not re-litigate. They are scoped into **PLAN.md §Phase S** / **CONTEXT.md §Phase S**. **D-A — SETTLED: bare Steinberg VST3 SDK + LICE editor (no JUCE).** *(The central fork. §1a is the assessment that fed it. The sub-question — who draws the editor? — was the whole fork, because §1a showed the audio-processing scaffolding is bounded either way.)* Daniel took **Option A**: bare Steinberg SDK, `SingleComponentEffect` for the bounded audio scaffolding, editor drawn in the **same LICE/SWELL stack `bank_panel` already uses** — no JUCE dependency, no AGPL-or-pay posture, house-consistent UI. The `IPlugView`↔LICE bridge (the one real unknown) is **not** a gate on the decision (the decision is made) but remains the right *first implementation step*: it is scheduled as **Phase S's opening spike (S1)** to convert §1a's experienced-estimates — Windows module-export names, factory-macro spellings, exact bridge marshalling — into verified fact before the engine build leans on them. (The stale §1a "is VSTGUI even bundled" question is dropped as moot under Option A; VSTGUI remains a noted fallback rung only if the LICE bridge proves gnarlier than the panel work suggests, with JUCE the last resort behind that.) The full option analysis (A/B/C, the JUCE license posture, the LICE-bridge caveat) is preserved below as the record. - *Option A — bare Steinberg SDK + LICE editor.* Take only the VST3 SDK (permissive, royalty-free, no revenue gate). Use `SingleComponentEffect` for the ~200–400 lines of once-written audio scaffolding, and draw the editor in **LICE/SWELL — the stack `bank_panel` already uses** (67 LICE call-sites today). *Pro:* no JUCE dependency, no AGPL-or-pay posture, house-consistent UI, reuses existing UI muscle, lean CMake discipline preserved. *Con:* the `IPlugView`↔LICE bridge is real integration work with edges (window lifecycle, sizing, event routing) — less trodden than dropping in a JUCE editor, and it should be **spiked before it's promised**. - *Option B — JUCE.* Take JUCE for its editor framework + parameter management + DSP utilities. *Pro:* the editor is a solved problem, `AudioProcessorValueTreeState` is convenient, `juce::dsp` helps at Tier 3. *Con:* a large framework dependency with its own build system and idioms sitting oddly beside the two-submodule discipline; and the **license posture** — AGPLv3-or-commercial, free Starter tier below ~$20K/yr revenue (no splash screen in JUCE 8), Indie ~$3,500 with a ~$200K/yr limit above that. For most of what JUCE solves (multi-format), **D5 already deleted the need.** - *Option C — bare SDK + VSTGUI (the SDK's own bundled toolkit).* A middle path: no JUCE, but a purpose-built VST editor toolkit instead of hand-bridging LICE. Lighter than JUCE, no extra dependency beyond the SDK. Worth a look if the LICE bridge proves gnarly. *My honest lean:* **Option A (bare SDK + LICE editor)**, precisely because ReaSampler is the atypical case where the "take JUCE for the GUI" default is weakest — it already has working LICE UI competence and a house style. JUCE's headline value (multi-format) is moot under D5. Fall back to JUCE (Option B) *only if* the `IPlugView`↔LICE spike shows the bridge is genuinely painful; consider VSTGUI (Option C) as the middle rung before conceding to a full framework. **Concrete ask: greenlight a small `IPlugView`↔LICE spike before committing** — it's the one unknown that decides A vs. B, and §1a's LICE-bridge and Windows-export-name claims are experienced estimates that a spike would convert to fact. **D-B — SETTLED: split seam (option iii), and the intrinsic fields are added NOW.** *(The mapping-ownership fork, old D4. Options were: (i) bank-owned map, (ii) instrument-owned map, or (iii) split.)* Daniel took **(iii) split** — and, critically, called that the `Sample` intrinsic fields land **now**, not deferred. **Root note + loop points become bank intrinsics on `Sample`** (facts about the captured file, like sample rate/length/peaks) — a small additive change, the same shape as adding `provenance` in M1. **Zones, velocity layers, round-robin, envelopes are the instrument's performance map** (a creative arrangement, not a file fact). The live-state seam (§2) means the instrument reads even the performance-map out of shared `"reasampler"` state, so "who owns which field" is a data-ownership decision, not a transport one. Adding the fields now closes the **backfill cliff** (the *design-the-seam-even-if-you-defer-the-feature* instinct, same as Fork R-D's owned-file manifest): every sample captured before the fields exist would otherwise lack a root note / loop points and need hand-backfilling. The field addition touches the **extension** codebase, is independently shippable, and is scheduled as an **early Phase S point (S2)** ahead of the instrument that consumes it. **D-C — SETTLED: Tier 0–1 scoped now; Tier 2 held; Tier 3 optional-forever.** *(The tier-scope fork, §3. Tiers: 0 "the bank plays" / 1 "a keymap" / 2 "expressive" / 3 "polish".)* Daniel took the recommended scope: **Tier 0** ("the bank plays" — one sample, chromatic, amp envelope, velocity→volume) then **Tier 1** ("a keymap" — zoned multisamples with per-sample root notes) are the committed scope and the "does this belong in ReaSampler's world" proof (Phase S points S4/S5). **Tier 2** ("expressive" — velocity layers, round-robin, ADSR, loops) is held as an explicit follow-on — **noted, not specified** (its points are not drawn up). **Tier 3** ("polish" — filters, LFOs, choke groups) is optional-forever. The Tier-0–1 editor and DSP needs are modest, which is part of why the D-A "no JUCE" call is comfortable. **D-D — SETTLED: embedded TCP/MCP UI is SCHEDULED (not deferred).** *(The inline-in-REAPER-UI lever.)* A REAPER-hosted VST3 can draw its own UI *inline in the track/mixer control panel* (`reaper_plugin_fx_embed.h`: VST3 implements `IReaperUIEmbedInterface`; the same Cockos surface REAPER's own JS/embedded FX use) — a compact keymap/level strip inline in the TCP/MCP, not only in its own window. Because it uses the **same LICE-class drawing as the D-A editor path**, it composes naturally with the bare-SDK-plus-LICE build. **Daniel's call: schedule this, don't defer it** — it is a real, in-phase later point on the Phase S roadmap (**S6**), sequenced *after* the main `IPlugView` editor exists (it composes with that LICE path), not a someday-note. It is polish rather than a Tier-0 need, so it sequences last — but it is on the roadmap. ### Addendum — two directions set post-scoping (Daniel, 2026-07-26) After Phase S was scoped (D-A..D-D), Daniel set two further directions. These are **settled directions**, not open forks — specced as new Phase S points (S7–S9), not re-litigated. Recorded here per the doc's settled-decisions convention. **D-E — Channel mode: mono | stereo, per-instance, bus-negotiated (→ PLAN.md S7).** Captures are often stereo; the current mono downmix is a Tier-0 simplification. The engine gets a **per-instance channel-mode toggle (1 mono / 2 stereo)** that "works with the REAPER audio bus automatically" — the VST3 declares/negotiates its output bus arrangement (`setBusArrangements`) so mono/stereo just works in REAPER's routing. Honest scope: **this is an S3-core extension, not a shell hack** — the core is mono-per-sample by design today, so stereo mode grows a channel dimension (2-channel sample data, per-voice stereo render, per-channel loop/interp). Mono mode keeps the existing downmix path. Cross-mode policy: mono-source-in-stereo → dual-mono; stereo-source-in-mono → downmix (existing). The toggle is instrument-owned per-instance state (D-B: a performance choice, never a bank fact). Sequenced **first after the editor/embed work** because it touches the engine Daniel smoke-tests. **Ingest routes through the bank — "option 1"; the extension owns ingest (→ PLAN.md S8 + S9).** Loading a sample into the sampler is **one gesture**: capture/import-into-bank + auto-assign to the active instance. The **extension owns ingest** (it has arrange access, Media-Explorer access, and the drop-target surface on its own panels); the **instrument stays a read-only bank consumer** — it never captures or imports. Sub-parts, with the honest SDK reality verified against the vendored headers: - *(a) Arrange capture → bank → assign* — a one-click action reusing the existing capture path; **never inserts a timeline item** (capture/placement separation intact). - *(b) Media Explorer import → bank → assign* — the ME surface is **thin** (`OpenMediaExplorer` + `MediaExplorerGetLastPlayedFileInfo` are the whole contract; no enumerate-selected, no ME-drop-handler), so ME import is **single-file, pull-on-action**, not a push/drop from inside the ME. Spike: does the last-played-file read work for a merely-*selected* file? - *(c) Drag-and-drop* — REAPER exposes **no** drag-drop registration API; drop handling is SWELL/Win32 on ReaSampler's *own* panel HWNDs. Drop *onto the VST3 editor window* relayed to the extension as a bank-ingest request is a genuine **cross-artifact spike**, not a promise (drop-onto-panel is the shipped path if it proves gnarly). - *(d) Recapture / ingest auto-refresh (→ S9)* — because instances reference sample **ids**, a recapture landing under the same id (M10) or an ingest touching the active bank should refresh live instances **hands-free**. The missing trigger is a **bank-generation counter** in `"reasampler"` ext-state: the extension bumps it on any bank-content mutation; the instrument polls it **off the audio thread** on a safe cadence and calls its existing `reloadFromBank()` on change (reusing S4's atomic handoff). This seam serves both S8 ingest and M10 recapture. *The genuine spikes flagged (not decisions Daniel owes, just build-time unknowns):* the ME merely-selected-file read (b), and the drop-onto-editor cross-artifact relay (c). Both are honestly-flagged as spikes in PLAN.md S8, not promised. ### Addendum — product name + UX overhaul (Daniel, 2026-07-26, post-S1–S6 DAW test) Daniel DAW-tested the S1–S6 instrument and set two directives. These are **settled directions**, specced as new Phase S points (S10–S13) and a product-name convention — not open forks (the two flagged forks below are the only calls left to Daniel). **The instrument's product name is `ReaSampler 9000`.** The extension stays **ReaSampler** (capture + organization); the instrument is **ReaSampler 9000** (playback). Propagation is a checklist item (PLAN.md §Phase S — product name; CONTEXT.md §Product name): the VST3 class **display name** string, the `IPlugView` editor title band (today "ReaSampler Instrument"), the S6 embed-strip label, and the docs. **Compat guard (load-bearing):** the **VST3 class UID must NOT change** — instances in saved projects key off it; a UID change orphans every existing instance. The name change is **display-string-only** on the code side. *Fork S-NAME-1 (Daniel's call):* the on-disk **binary filename** — renaming it (`reasampler_9000.vst3`) carries compat weight (REAPER keys a saved project's plugin reference partly by filename), so the r5 lean was **keep the filename, change only display strings**; flagged, not decided. *(Now SETTLED in r6, below: rename the filename too, UID locked, compat is a DAW-verify — the r5 lean is superseded.)* **The UX bar is "better than ReaSamplOMatic5000."** Verdict verbatim: "okay it works, but the UX is awful." The S1–S6 editor was spike-grade — a clickable list, zone rows with **seven ±1 nudge/delete mini-buttons** each, text labels, **no keyboard, no waveform, no drag, no scroll.** Setting a zone range by ±1 clicks is the catastrophe. The overhaul (S10–S13) makes "better than RS5K" *specific*: - **RS5K's strengths, matched or beaten.** Drag-a-file-onto-it load (→ S13 relay); note-range + a visual keyboard (→ S10 — RS5K uses two *number fields*, so a **draggable keyboard strip** beats it); waveform with draggable start/end/loop markers (→ S11); ADSR sliders (→ S12). Velocity layers / round-robin stay Tier 2 (held). - **RS5K's weaknesses, our opening.** RS5K is **one-sample-per-instance** (forcing track sprawl — one instance per drum) with **no multi-zone view in a single instance**. ReaSampler 9000 is **multi-zone in one instrument** (S5), so the keyboard-strip editor showing *every* zone at once is a capability RS5K structurally lacks. That is the sharpest "better than RS5K" claim, and it's free — it falls out of the existing model. The overhaul honors every settled constraint: **LICE/SWELL only** (D-A), **pure geometry modules** for all layout/hit-test (mirror of `mode_switch`/`editor_geometry`/`embed_strip`), **RT discipline untouched** (edits commit off-thread), the instrument stays a **read-only bank consumer** (loop/root/ADSR edits are the instrument's performance map, D-B — never written to the bank). Component-state persistence and read-only-over-bank stay settled. *Sequencing (product recommendation).* **S10 leads** — the nudge-button zone editor is the friction Daniel hits on every test pass, so removing it buys the most felt improvement per unit of work and de-risks the drag-state machine S11/S12 reuse. Against the queued **S7 (stereo)**: S10 should land **before or interleaved with** S7 — S7 is real engine work but the *reason* Daniel keeps smoke-testing is the editor, and every test pass is currently taxed by the UX; the two are orthogonal (S7 = engine/bus, S10 = editor/geometry), so there is no hard ordering, but the live wound is the editor. Honest counter: if the stereo *sound* is what blocks real use, S7-first is defensible — but "it works, the UX is awful" names the editor as the wound. ### Addendum — S10 workflow-first reframe + S-NAME-1 settled (Daniel, 2026-07-26, r6) After the r5 UX-overhaul directive was specced (keymap-first S10), Daniel reframed the workflow before S10 was implemented. This **revises S10** and settles S-NAME-1. Settled directions, not open forks — recorded here per the doc's settled-decisions convention; PLAN.md §S10 and CONTEXT.md §Phase S (workflow hierarchy) carry the spec. **The reframe, verbatim (Daniel, 2026-07-26):** *"We need to think hard about the workflow with this plugin. Have a giant list of 'item' blocks is visually useless. When the plugin is loaded, we should not have any samples selected. We also need to show the peaks for each capture. Filters for a specific bank would be useful. We need to be graphic and descriptive with the controls, and guide the user QUICKLY towards setting up a sampler. Most of the time the zones won't be used, but it's a nice-to-have. So we should optimize the UX for working with individual captures, not a huge list of everything."* **What changed in S10 (the hierarchy is Daniel's; details are product judgment):** 1. **Primary flow = one capture, fast.** The metric is **time-to-first-note**: open → pick a capture → see it → play it. The default face serves the single capture, not a keymap. 2. **Fresh instance is SILENT — nothing auto-selected (policy reversal of S4).** The S4 "first sample plays" convenience is **removed**: open with no stored selection → the instrument plays nothing and shows a **"pick a capture" empty state**, not auto-play of sample #1. Concretely retires the `selectSample` first-sample fallback (`sample_map.cpp`) and the processor's Tier-0 fallback that resolved it (an empty stored id → silence). This is a deliberate reversal of the S4 default, recorded as such — not a regression. 3. **Capture browser, not an item list.** Scannable cards with **peak thumbnails** (the `Sample` peaks bank_model already carries — the same data the dock panel thumbnails draw), name, root/key badge, and a **bank filter** (bank_book named banks). "A giant list of item blocks" is the named anti-pattern; the browser is designed for scanning by eye. `SampleChoice` grows to carry the peaks + badge + bank (today it is only `{id, displayName}`). 4. **Graphic, descriptive controls with a guided fast path.** Once a capture is picked, a prominent single-capture setup surface (root note, play-mode basics, level); the keyboard strip serves the single-capture case first (shows the capture's root). 5. **Zones demoted to an opt-in "Zones" panel (S10-Z), not the default face.** "Most of the time the zones won't be used." The keyboard-strip drag machinery is still built (it serves both the single-capture root-set and the opt-in zoning), but multi-zone editing is behind a toggle. Some S12 list ergonomics **pulled into S10**: the browser card layout, peak thumbnails, and bank filter are S10's; S12 keeps **scroll** + **type-to-filter search** layered over the S10 browser. S11's waveform is the same surface S10 shows for the picked capture ("see it"). No renumber — S11/S12/S13 keep their numbers and their boundaries were annotated, not moved wholesale. **S-NAME-1 → SETTLED: rename the binary filename too.** The r5 lean (keep the filename, display-strings-only) is superseded. The on-disk module is renamed to match the product (e.g. `reasampler_9000.vst3`) — full surface: **CMake `OUTPUT_NAME`**, factory vendor/name strings, editor title, embed label. The **VST3 class UID stays locked** as the compat anchor. **Compat is a DAW-verify, not an asserted fact:** the working assumption is REAPER rebinds a saved instance by class UID (not filename), so a rename with an unchanged UID keeps saved projects working — but a web check surfaced a JUCE/VST3-replace-VST2 case suggesting REAPER's binding can be more nuanced than "UID only" (an FXID match is involved), so UID-only rebinding is **not** safe to assert from source. Verify by save-rename-reopen in the DAW; if REAPER keys partly on filename, fall back to keeping the filename and record that as shipped. ### Addendum — sampling modes (Trigger/Gate) + pitch envelope (Daniel, 2026-07-26) > **Superseded in part by the r8 Addendum below (2026-07-26).** Daniel's duration-preserving > correction reshaped S16 from "pitch envelope only" into a Varispeed/Preserve pitch-engine > mode, and **flipped this addendum's WDL verdict** — `WDL_SimplePitchShifter` (called the > "wrong tool" in item 3 below) is now the Preserve-engine candidate. Read this as the r7 > point-in-time record; the r8 Addendum carries the current S16 shape. Daniel directed a set of engine features for the sampler, specced as **new Phase S points S15 (Trigger vs Gate) and S16 (pitch envelope)**. **The feature set is settled** — recorded here per the doc's settled-decisions convention; PLAN.md §S15/S16 and CONTEXT.md §Sampling modes carry the spec. Two forks are flagged with leans (S15-F1 choke, S15-F2 param granularity); the WDL question was resolved by inspection. **Directive, verbatim (Daniel, 2026-07-26):** *"let's have product spec out some features for the sampler: Sampling mode: Trigger vs Gate. Gate has an AHDSR envelope. Trigger has fade in, % length, and fade out. Both modes have modifiable start point, Gate has modifiable loop points too. In addition to amp env, there will be a pitch envelope/curve (AD?) which is off by default. Explore using WDL pitch capabilities."* **What was specced (the shape is product judgment; the feature set is Daniel's):** 1. **Play mode — Gate vs Trigger (S15), per-sample/per-zone, instrument-owned (D-B).** - **Gate** = classic held note: the current ADSR grows a **Hold** stage → **AHDSR** (hold=0 is exactly today's ADSR, back-compat); note-off → release; **sustain loop applies** (S11's loop markers become Gate-mode UI). - **Trigger** = one-shot drum-pad: note-on fires a **% of sample length** with a **fade-in** and **fade-out**, **ignores note-off**, **no loop**. Fade default **equal-power** (click-free); note-off is a no-op (choke held, fork S15-F1). - **Both:** a **modifiable start point** (non-zero initial read position). - **Confirmed from `sampler_core.cpp`:** the read loop already advances by an arbitrary per-frame ratio with linear interp and applies a per-frame amp tick, so both envelopes are per-frame amplitude functions and the start point is a non-zero initial `readPos_` — no resampler or voice-lifecycle rewrite. 2. **Pitch envelope — AD, off by default (S16).** A per-voice AD curve biasing the read increment (the classic pitch drop). **RT clean, confirmed:** the resampler is already an arbitrary per-frame `readPos_ += ratio_`, so the envelope is a per-frame multiply of `ratio_` by `2^(semitones/12)` — **hand-rolled, no new resampler, no WDL dependency**. Off by default → bit-identical to pre-S16. 3. **WDL pitch capabilities — verified, not lore (full surface swept).** The whole vendored WDL pitch/resample surface is two headers: **`resample.h`** (`WDL_Resampler`, a real sinc/linear RT-suitable resampler — its sinc mode *beats* the core's 2-point linear interp for base-repitch quality at a CPU cost; **held as an optional quality upgrade**, not needed for S15/S16) and **`simple_pitchshift.h`** (`WDL_SimplePitchShifter`, a time-domain OLA *duration-preserving* pitch shifter — wrong tool for a sampler; `set_formant_shift` is an **empty stub**). **No elastique / formant-preserving / time-stretch exists in WDL** — REAPER's elastique is licensed (zplane), not in the vendored tree. **Recommendation:** S16 modulation stays hand-rolled; `WDL_Resampler` (sinc) is the only WDL piece worth adopting and only as a held base-repitch quality upgrade. 4. **Sequencing.** S15 before S16 (S16 reuses S15's param plumbing). Both are S3-core extensions but **channel-count-agnostic by construction** (per-frame amplitude + read-rate, pre-mix), so they **compose with S7 stereo** rather than conflicting. Core halves land in CTest independently of the editor; the mode toggle / Trigger handles / AD control surface through the S10/S11 waveform + setup work. **Forks flagged (leans given):** *S15-F1 (choke on note-off)* — **held**, out of S15 scope (Trigger ignores note-off; choke-groups are Tier-3-adjacent). *S15-F2 (param granularity)* — **lean per-zone only** (the single capture is already a one-zone map), flagged because it touches S10's single-capture setup surface. ### Addendum — duration-preserving correction: S16 becomes pitch-engine modes (Daniel, 2026-07-26, r8) **Correction, verbatim (Daniel, 2026-07-26):** *"isn't that ratio stuff going to change the playback rate? I want duration-preserving repitching."* Daniel is right about the mechanics. The r7 S16 spec modulated pitch by biasing the per-frame read ratio (`readPos_ += ratio_`) — that is **varispeed**: pitch and duration are coupled (an octave up halves the note's duration). Daniel wants **duration-preserving** repitch (a transposed note keeps its length). This reshapes S16 and **flips the r7 WDL verdict** on `WDL_SimplePitchShifter`. **What changed (the reframe, then the spec):** 1. **The reframe — this is a mode, not a replacement.** Both behaviors are musically legitimate, so the answer is not "swap varispeed for preserve" but **a per-zone/per-capture pitch-engine mode**: - **Varispeed** (current path, cheap, zero-latency) — pitch/duration coupled. The **classic sampler / RS5K** default; right for **drums / one-shots** (pitch-down-lengthens- the-hit is a feature there). - **Preserve** (duration-preserving) — a pitch shifter transposes the output while the read holds the source duration. Right for **tempo-locked loops and phrases** (a transposed loop still lines up to the bar) — which is what captured banks skew toward (project slices). The pitch envelope (r7's S16 body) then rides **either** engine: under Varispeed it biases the read ratio (as specced); under Preserve it biases the shifter's shift amount. So the envelope is preserved, re-homed onto the engine seam. 2. **Fork S16-F1 (Daniel's call): the default engine. Lean Preserve.** Argued honestly: Preserve because Daniel asked for it **unprompted** (reads as his expectation) and the capture workflow is **loop/phrase-heavy**; but Varispeed is the **classic-sampler expectation**, is **cheaper + zero-latency**, is **bit-identical to today's shipped feel**, and is what percussive one-shots want. Recommendation: **default Preserve, prominent cheap per-zone toggle to Varispeed.** Daniel's call. 3. **WDL verdict corrected — `WDL_SimplePitchShifter` is now the right category.** Under "duration-preserving is the requirement," r7's dismissal ("wrong tool, duration-preserving OLA") inverts: **duration-preserving is exactly what we need.** A real per-voice RT viability assessment (from `vendor/WDL/WDL/simple_pitchshift.h`): - **API:** push/pull block (`GetBuffer`/`BufferDone`/`GetSamples`); `set_shift(2^(semi/12))` for pitch with an **independent** `set_tempo(1.0)` duration knob — pitch and duration separately controllable, exactly Preserve. - **Per-voice:** modest memory (OLA ring ≈ window·srate ≈ a few KB/voice at the 50 ms quality-0 window). CPU cheap (O(length), a few mults + one OLA crossfade/frame, **no FFT**) → **N polyphonic voices each running one is feasible** in RT discipline. - **Costs owned:** (i) **onset latency** ~half-window (~25 ms @ 50 ms) — the load-bearing cost; pre-warm at voice-allocation, and it lands on sustained/loop material (Varispeed serves tight one-shots); (ii) **queue-growth** allocation in `BufferDone` — settled by a silence pre-warm so no `process`-thread allocation in steady state; (iii) **basic quality** (SimpleWindowed warble on big transpositions; `set_formant_shift` is an empty stub → no formant preservation) — acceptable for loops, replaceable by route (b). - **Fork S16-F2:** **route (a)** `WDL_SimplePitchShifter` (low-cost proof) vs **route (b)** a hand-rolled pure `pitch_shift` OLA/granular module (house pattern, CTest-testable, full control). **Lean (a) first, (b) held** as the quality/latency upgrade — same `PitchEngine::Preserve` contract behind the seam. 4. **Not proposed / restated ceilings.** `WDL_Resampler` is a *resampler* (couples duration) — a held **Varispeed-quality** upgrade, **not** a Preserve engine. **elastique is NOT available** (licensed zplane, not vendored). JUCE / rubberband / signalsmith are each a **new-dependency fork carrying full D-A weight** (bare-VST3-no-framework is the locked D-A choice) — **not proposed**. 5. **S15 interaction (cleaner under Preserve).** Trigger's **%-length** becomes **pitch- independent** under Preserve (wall-clock stable under transpose — cleaner than Varispeed, where transposing a Trigger also scales its length); Gate's **sustain loop** contract under Preserve is *loop the source read, shift the output* (loop points stay source-frame facts); the **start point** is engine-independent (a source-frame offset). Channel-agnostic for S7 (the shifter is `set_nch`-aware; one instance per voice carries all channels). 6. **RT/CPU honesty.** Preserve is **meaningfully heavier** than varispeed — a per-voice DSP object with its own budget, pre-warm, and a possible **Preserve-mode-specific voice cap** (below the Varispeed cap) if per-voice cost demands it. Put in Verify: pre-warm → no `process` allocation; measure per-voice CPU + onset latency against the polyphony cap. Treat S16's Preserve-engine point as the phase's next real DSP spike, not a thin envelope add-on. **Where the spec lives:** PLAN.md §S16 (reshaped to "pitch engine modes + pitch envelope", with forks S16-F1/F2 and the corrected WDL finding) and the S15 × S16 interaction note; CONTEXT.md §Pitch engine modes — Varispeed vs Preserve + the corrected WDL surface finding. ### Addendum — VST channel isolation (Daniel, 2026-07-26) **Daniel's directive (2026-07-26, settled):** *"support the beta/stable channels for the VST as well. The VST in beta should talk to the beta extension only."* This extends Phase V's V4 beta/stable split — which fully isolated the **extension** per channel — to the **ReaSampler 9000 VST3 instrument**. Spec'd as **S18**, an immediate Phase S wave, dispatchable in parallel with or right after the in-flight waves (S9 ext_keys, S15/S16 processor/editor) — it touches `vst_entry.cpp` / `reasampler_vst.h` / the CMake VST3 block, mostly disjoint from those. **Established honestly from the tree — what already works vs. what's missing:** - **Already isolated (the V4↔S4 reconcile did this): data pairing.** A beta-built VST already *reads* the beta namespace — `ext_keys.h`'s `kProjExtNamespace()` delegates to `app_version::extStateNamespace()`, and every wire key (`banks`, `assign_request`, S9's generation key, S17's blob key, any future key) is a plain constant *under* that namespace. Channel data-isolation is therefore **structural, not per-key** — new keys inherit it for free. No S18 work here. - **Missing: the VST's *plugin identity*.** Its class UID, binary filename, and display strings are single-valued (same for both channels), so two installed channels would collide on UID and filename. S18 closes exactly this. **The shape of S18 (mirrors V4's philosophy — one channel per binary, one bit drives it):** 1. **A UID pair.** The stable class UID is locked forever (S-NAME-1). Beta needs its own forever-stable UID (a second constant, minted once, locked identically). Both frozen forever; the channel bit selects which is compiled in. **One class per binary, not both** — the V4 fully-isolated-binary philosophy, so a beta build never presents the stable identity. Saved-project isolation follows: a beta-saved instance rebinds only to the beta VST. *Fork S18-F1 (Daniel's call):* mint the beta UID **now** (lean — mirrors the stable UID minted at the S1 spike, removes a pre-ship landmine, zero cost unused) vs. defer to first beta release behind a locked-once placeholder. 2. **Channel-derived binary + display identity.** `reasampler_9000` / `reasampler_9000_beta` filename (mirror the extension's `OUTPUT_NAME` fork); "ReaSampler 9000" / "ReaSampler 9000 beta" display; editor title + embed label channel-aware — all from the ONE bit via `app_version` accessors, no scattered `#ifdef`s (the V4 invariant). 3. **The pairing guarantee, stated as an invariant.** A channel's VST talks to that channel's extension only, because identity keeps the plugins distinct and the channel-derived namespace keeps the data distinct. **Structural, not per-key** — S8/S9/S17's cross-artifact keys all inherit it; a future key that forgets to isolate is impossible by construction. 4. **DAW-verify contract.** Both channels installed side-by-side; each browser sees only its channel's banks; stable-project + beta-VST = clean empty (not error); the S-NAME-1 rename/rebind test extends to the beta UID. **Where the spec lives:** PLAN.md §S18; CONTEXT.md §VST3 channel identity — the UID pair + the pairing surface. The pairing surface's data half is already load-bearing V4 machinery; S18 adds only the identity fork on top. --- ### Addendum — three-view editor model + drop-to-FX + default window size (Daniel, 2026-07-27, r9) **Framing.** Daniel opened a fresh design pass on the ReaSampler 9000 **editor** after living with the S10–S18 UX in the DAW. The instrument *works* and the capture browser is genuinely good — but the two-view editor (today's "Browser" + "Zones" toggle) misallocates its space, the default window is undersized for a 1080p world, and the drop-a-capture-onto-FX gesture is broken in practice. The directive: **make the one job — pick a capture, tune it, play it — fast, easy, and fun. Style is a critical ingredient. No spreadsheet aesthetics.** These are the `r9` calls. Authoritative spec: **CONTEXT.md §Phase S — editor view-model redesign (S-VIEW)**; build roadmap: **PLAN.md §Phase S — editor view-model redesign**. **The reference devices (the north star for control density).** Daniel named Ableton **Simpler** and a Kilohearts/Phase-Plant **sampler group** as the composition targets. Both share one grammar, and it is the grammar the redesign adopts: - **A large waveform up top is the hero**, with markers and the envelope drawn *over it at accurate time* — not a separate abstract envelope box. Simpler shades the sustain-loop region teal directly on the waveform; Phase Plant traces the amp envelope as a bright curve across the sample. The waveform is where the eye lives. - **A thin, dense value-strip of labelled controls** sits under the waveform (Simpler's Gain/Start/Loop/Length/Fade ribbon; Phase Plant's LEVEL/SEMI/HARMONIC/SHIFT/PHASE row) — bold ALL-CAPS micro-labels over a value, compact, scannable in one pass. - **Root note is fenced off as its own affordance** (Phase Plant boxes "Root C 4 +00" and an "Offset" knob to the right; Simpler puts Key% and Transp in the pitch cluster). Root is not buried in a list of sliders — it is a first-class, always-visible control. - **Modular horizontal bands.** Each concern (sample/pitch, then envelope) is its own band with its own drawn visual. This is how both devices avoid the spreadsheet look: every band leads with a *picture* (waveform, filter curve, envelope shape), and the numbers hang off it. **The three calls (r9).** 1. **Three views, not two — and they are NOT a flat toggle.** Today "Browser" and "Zone" sit as two equal segments. That framing is wrong: it implies the browser and the zone editor are peers, when in truth **the loaded sample is the home** and browsing/zoning are things you *reach for*. So: **Sample is the home view** (the default face — the hero waveform, the envelope overlay, all the per-sample controls). **Browse** is a **modal page layered over Sample** — a full-window overlay you summon to change the loaded capture (select + confirm), the way a file-open sheet layers over a document. **Zone** is a **dedicated editing surface** opened by its own button when you want to map across the keyboard. This is a *document-with-modal-picker* model (Simpler's own shape: the device face is the sample, and loading a new one is a distinct act), not a three-way radio. *Why the reframe matters:* it makes "I just want to play this capture" the zero-click default, and "I want a different one" a single deliberate gesture, instead of making the user re-choose their whole stance every time. See CONTEXT.md §S-VIEW for the precise navigation model. 2. **The Sample view earns the hero treatment; Browse gets ruthlessly cut.** Browse today carries a waveform preview, root-note piano-roll, loop-point labels, a track-root message, and a Mono/Stereo toggle — all of which are *tuning* concerns, not *choosing* concerns. Browse's only job is **pick a capture**; the grid thumbnails already show the waveform, so every one of those tuning affordances moves to Sample (where the hero waveform lives) and Browse shrinks to filters + grid + select/confirm. Conversely, Sample **gains a new envelope overlay** drawn on the hero waveform at accurate time (the Simpler/Phase-Plant move), a **preview-trigger button + velocity knob** (audition the sample at its root without a MIDI controller — the single most "fun/fast" affordance the current editor lacks), and inherits the Mono/Stereo toggle and every "Modes-and-down" control that lives on Zone today. 3. **Two engineering prerequisites, framed but routed to implementation.** The **drop-to-FX bug** (dropping a capture onto a track's FX chain does not instantiate + init ReaSampler 9000) and the **undersized default window** are not design decisions — they are a bug and a one-line default. Both are framed in CONTEXT.md §S-VIEW with the SDK reality swept (drop-to-FX: the S17 machinery is SDK-correct, so this is a *diagnosis* task, not a redesign; window size: the `getSize`/`checkSizeConstraint` mechanism is verified), and both are flagged for staff-engineer, not for a product fork. **New parameters this introduces (both instrument performance state, D-B — never bank facts):** - **Key-tracking (Zone view).** A 0%–200% scalar on how sample pitch tracks the keyboard around the root note. **100% (default) = standard 12-tone equal-temperament tracking** (a semitone up the keyboard = a semitone of repitch — exactly today's behavior). 0% = the sample plays at root pitch on every key (a fixed, un-tracked one-shot — the classic drum-machine "no tracking" mode). 200% = double-rate tracking (an octave of keyboard spans two octaves of pitch — an intentional special effect). This is a *per-zone performance choice*, additive on `PerformanceZone`, defaulting to 100% so existing playback is bit-identical. It is the sampler idiom every serious sampler has (RS5K's "Pitch for start/end note", Kontakt's "Tracking", Simpler's "Key %" — visible in the reference screenshot at "Key 100%"). *Why 200% and not higher:* the useful musical range is 0–200%; past 200% it is noise, and a bounded slider reads cleaner than an open one. - **Preview velocity (Sample view).** The velocity level the preview-trigger button fires at, set by an adjacent knob. It is a *utility* setting for the audition button (like a metronome level), not a musical parameter of the sample — but **it PERSISTS across reloads** (S-VIEW-F1 SETTLED, Daniel 2026-07-27). The seam matters and was verified against the existing VST source, not recalled: it lives in the **instrument's own VST3 component state** (the envelope-versioned `ComponentState` blob the processor round-trips through `getState`/`setState`, bumped to v6 for a new top-level `previewVelocity` field), **not** the extension's `persist` project ext-state — that module is REAPER-project-scoped and extension-owned, so it would make the level project-global instead of per-instance and route an instrument concern through a bank-read-only seam. See CONTEXT.md §S-VIEW for the round-trip and back-compat lift. This is what makes the preview button *fun*: tap it hard or soft without reaching for a controller — and it remembers. **Two visual components the redesign commits to:** - **The envelope overlay — with DRAGGABLE nodes** — on the Sample view's hero waveform: the amp envelope (AHDSR for Gate, the fade/%-length shape for Trigger) drawn as a curve *at accurate wall-clock time* across the waveform, the way Simpler draws its amp envelope over the sample and Phase Plant traces it in bright blue. This is the single biggest "reads like a real sampler, not a spreadsheet" move — the envelope stops being four abstract sliders and becomes a *shape you see over the sound*. And it is **directly editable** (S-VIEW-F2 SETTLED, Daniel 2026-07-27 — in scope, not deferred): the breakpoints are **draggable handles** (X → segment time, Y → level on the sustain node; monotonic-in-time, range-clamped), the exact ADSR-editor grammar Simpler / Phase Plant / Serum all use. The sliders stay as the precise numeric-entry surface, and **both surfaces read/write the same envelope params** — one source of truth, so a drag moves the sliders and a slider edit re-lays the nodes with no divergence. The geometry/hit-test math lives in a new pure `envelope_edit` module (mirror of `card_drag`, unit-tested at the clamp/monotonic boundaries); the shell only draws the handles and routes the mouse. This is the affordance that makes envelope-shaping *feel* like a sampler instead of a form. - **The real piano-keyboard pattern** on the Zone view's keyboard strip. Today's spectral strip is pretty but does not *read as a keyboard* — Daniel's note. The redesign keeps the pastel spectral hue but overlays the **actual alternating white/black key pattern** (bright/dark per the palette) so the strip is instantly identifiable as a keyboard. It need not be *shaped* like a keyboard (no protruding black keys) — just carry the pattern as an overlay, so a glance reads "this is C, this is F#" without counting. **What does NOT change (guardrails restated).** The instrument stays a **read-only bank consumer** — every new control (key-tracking, preview velocity, the loop/start markers Sample inherits) is *performance map*, never written to `Sample` or the bank (D-B). LICE/SWELL drawing only, all layout/hit-test in pure geometry modules (D-A). RT discipline untouched — the preview-trigger fires a note through the same voice engine off the audio-thread commit path, no new audio-thread work. The VST3 class UID is unchanged — a view reorganization plus additive persisted fields is not a compat event; saved instances rebind and restore. And this is an *editor* redesign: the S3 voice engine, the keymap resolution, and the component-state format (extended additively — `keyTrack` per-zone, `previewVelocity` per-instance via an envelope bump to v6, both with back-compat defaults on read) are the same load-bearing core. **Where the spec lives:** CONTEXT.md §Phase S — editor view-model redesign (S-VIEW); PLAN.md §Phase S — editor view-model redesign. This Addendum is the *why*; those are the *what/how*. --- ## Where this landed With D1/D5/D6 locked and **D-A..D-D all settled (2026-07-26)**, the instrument is scoped into **Phase S** — a native VST3 sampler as a **second build artifact** alongside the `reaper_reasampler` extension. The settled set: 1. **D-A → bare Steinberg VST3 SDK + LICE editor** (no JUCE). The `IPlugView`↔LICE bridge is the opening implementation spike (**S1**), not a decision gate. 2. **D-B → split seam; root note + loop points added to `Sample` now** (**S2**, in the extension) to close the backfill cliff. 3. **D-C → Tier 0–1 committed** (**S4/S5**); Tier 2 held (noted, not specified); Tier 3 optional-forever. 4. **D-D → embedded TCP/MCP UI scheduled** (**S6**), after the main editor exists — on the roadmap, not deferred. Two further directions set post-scoping (2026-07-26; see the Addendum in §4): 5. **D-E → channel mode (mono | stereo), per-instance, bus-negotiated** (**S7**) — an S3-core channel-dimension extension, sequenced first after the editor/embed work. 6. **Ingest through the bank ("option 1"), extension-owned** (**S8**) + **bank-generation hands-free refresh** (**S9**) — one-gesture capture/import + assign; the instrument stays a read-only consumer. Post-DAW-test directives (2026-07-26; see the "product name + UX overhaul" Addendum in §4): 7. **Product name → `ReaSampler 9000`** (VST3 class UID unchanged; **binary filename renamed too — S-NAME-1 SETTLED r6**, compat is a DAW-verify). 8. **UX overhaul → workflow-first, "better than RS5K"** (**S10–S13**; S10 **reframed r6**): S10 = **capture browser (peak thumbnails + bank filter) + guided single-capture setup**, **silent-on-open / no auto-select** (reverses S4), multi-zone editing demoted to an opt-in Zones panel (S10-Z); S11 waveform + draggable loop points; S12 scroll/search over the S10 browser + numeric entry + ADSR; S13 drop-to-load folding in the S8 relay. Metric: time-to-first-note. 9. **Visual design language → modern/sleek, system-wide — moved to its own Phase L (2026-07-26).** The look-and-feel work (a shared LICE drawing kit + the surfaces that adopt it) was originally drafted here as Phase S points S0-DS + S14; it has been **lifted out of Phase S into its own Phase L** (Look-and-feel) on `dev`, taken up by a parallel team so Phase S feature work proceeds ungated. S0-DS → **L1** (shared kit); S14 → **L2** (expanded to a thorough dock-panel layout redesign per DS-3); VST editor + embed restyle → **L3** (gated on Phase S landing on dev). Forks DS-1 (LICE + WDL free game, no external frameworks), DS-2 (Direction B "Neon Console" + Direction C's spectral keyboard strip), and DS-3 (thorough panel layout) are all **SETTLED (2026-07-26)**. Framing + palette + the three visual directions + forks: `docs/product/visual-design-language.md` (on `dev`); roadmap + spec: **PLAN.md §Phase L + CONTEXT.md §Phase L** (on `dev`). **S10–S13 build with the current drawing and adopt the L1 kit when it lands — not gated on Phase L.** Answers Daniel's "the VST is dogshit / temple os / does Cockos have a toolkit" (2026-07-26, post-S1–S6 DAW test). 10. **Sampling modes + pitch engine → engine features** (**S15** Trigger vs Gate, **S16** pitch-engine modes + pitch envelope; see the "sampling modes" r7 + "duration-preserving" r8 Addenda in §4). Gate = AHDSR held note (hold added to today's ADSR); Trigger = one-shot with %-length + fade-in/out, ignores note-off; both carry a modifiable start point; Gate keeps loop points. **S16 reshaped (r8, Daniel's duration-preserving correction):** a per- zone **pitch-engine mode — Varispeed** (current, cheap, pitch/duration coupled — classic sampler, right for drums) **vs Preserve** (duration-preserving via a per-voice pitch shifter — right for tempo-locked loops/phrases). Pitch envelope = per-voice AD, off by default, riding either engine (biases `ratio_` under Varispeed, the shift amount under Preserve). WDL verdict corrected: **`WDL_SimplePitchShifter` is the Preserve-engine candidate** (duration-preserving OLA — RT-viable per-voice with pre-warm; the load-bearing cost is onset latency), `WDL_Resampler` (sinc) held as a Varispeed-quality upgrade only; no formant-preserving/elastique in WDL. Forks: **S16-F1** (engine default — lean Preserve, Daniel's call), **S16-F2** (Preserve impl — WDL shifter first / hand-rolled held), plus S15-F1 (choke, held) / S15-F2 (param granularity, lean per-zone). Feature set settled; the engine default is Daniel's fork. **Authoritative from here:** **PLAN.md §Phase S** is the roadmap (S1–S6 the original dependency chain: spike → `Sample` fields → pure sampler core → Tier 0 → Tier 1 → embedded UI; then **S7** stereo, **S8** ingest, **S9** change-detection, **S10–S13** the ReaSampler 9000 UX overhaul, **S15/S16** the Trigger-vs-Gate + pitch-engine-modes engine features); **CONTEXT.md §Phase S** is the spec (seam-field semantics, scope contracts, the channel-mode / ingest / bank-generation / sampling-mode / pitch-engine contracts, the UX-overhaul spec, the product-name convention, the pure/shell split, the WDL finding, the must-verify SDK/bridge surfaces). This doc is the framing/decision record they point back to. The "no PLAN.md footprint" era is over. --- ## Sources (for §1a's verified claims) - Steinberg VST3 SDK — `SingleComponentEffect` class reference (combined processor + controller; "non-distributable" caveat): https://steinbergmedia.github.io/vst3_doc/vstsdk/classSteinberg_1_1Vst_1_1SingleComponentEffect.html - Steinberg VST3 SDK — `IAudioProcessor` class reference (process/setupProcessing/bus contract): https://steinbergmedia.github.io/vst3_doc/vstinterfaces/classSteinberg_1_1Vst_1_1IAudioProcessor.html - VST3 Developer Portal (overview, tutorials, example plugins — AGain / Note Expression Synth as the skeleton copy-source): https://steinbergmedia.github.io/vst3_dev_portal/ - JUCE 8 EULA (dual AGPLv3 / commercial; tier structure): https://juce.com/legal/juce-8-licence/ - JUCE forum — revenue limits & JUCE 8 pricing (Starter ~$20K/yr free, Indie ~$200K/yr limit, ~$3,500): https://forum.juce.com/t/revenue-limits-for-juce-tiers/61058 *Estimate-vs-verified honesty note:* the interface list, `SingleComponentEffect`'s role, the instrument bus topology, and the JUCE license terms are **verified** from the sources above. The **line-count band (~200–400)**, the **exact Windows module-export symbol names** (`InitDll`/`ExitDll`/`GetPluginFactory`), the **factory-macro spellings** (`BEGIN_FACTORY`/`DEF_CLASS2`), **VSTGUI being bundled in the vendored SDK**, and the **`IPlugView`↔LICE bridge difficulty** are **experienced estimates** grounded in how the SDK is shaped — each flagged inline in §1a and each cheap to convert to fact by reading the vendored SDK headers / running a spike before any of it lands in a plan.