Files

T

daniel 5a859cc9bf docs(phase-s): fold velocity->amp transfer-curve editor into S-VIEW (r10)

Per-PerformanceZone state home, new pure velocity_curve module, application at
Voice::start(), Sample-view editor UI. New PLAN points S-VIEW-9 (foundation,
blocked by Wave 1 T-KEYTRK) + S-VIEW-10 (Wave 2 shell). Fork R10-F1 (flat-y=1
default is a non-back-compat behavior change) left open for Daniel.

2026-07-27 13:35:01 -04:00

94 KiB

Raw Blame History

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):

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.
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.)
Win32 / GDI / Direct2D directly — Windows-only makes this viable; you own an HWND in the IPlugView.
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):

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.
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.
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}).
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).
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):

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.
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.
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.
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):

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.
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.
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.
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.
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).
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):

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.
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 #ifdefs (the V4 invariant).
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.
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).

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.
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.
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.

Addendum — velocity → amp transfer-curve editor (Daniel, 2026-07-27, r10)

Framing. Folds one more control into the S-VIEW redesign: a visual velocity → amp transfer-curve editor. Today the engine maps velocity to gain linearly (velocityGain_ = velocity / 127.0, sampler_core.cpp:261), applied once at note-on in Voice::start(). Daniel wants that mapping to become an editable transfer curve — a bezier from a default flat line to an arbitrary multi-point curve — so velocity dynamics are fully shapeable per sound.

Directive, verbatim (Daniel, 2026-07-27): "By default any velocity plays at full level. Add a visual transfer-curve editor: an editable curve from the default flat y=1 to any bezier curve with arbitrary points, where x = velocity (0–127) and y = amp scalar (0–1). Enables very dynamic control over velocity → level."

The reference grammar. A 2-D transfer-curve editor is the standard sampler/synth velocity- response surface — Kontakt's velocity/mod curve editor, Serum's env/curve nodes, Ableton's velocity device, any DAW's automation-curve editor. X is the input (velocity, 0–127), Y is the output multiplier (amp scalar, 0–1), and draggable control points bend the mapping. It is the same direct-manipulation, one-source-multiple-views instinct as the r9 envelope overlay — and it reuses the r9 envelope_edit house pattern almost verbatim (a pure geometry/clamp module + a LICE shell that draws handles and routes the mouse).

The four calls (r10).

State home → per-zone (PerformanceZone), sibling of the amp envelope + keyTrack. Velocity response is a per-sound performance characteristic, exactly like the AHDSR envelope, the pitch engine, and the r9 key-tracking scalar — all of which already live on PerformanceZone (D-B, instrument-owned, never a bank fact). A punchy drum wants a different velocity curve than a sustained pad, so the curve must vary per zone, not per instance. This rules out ComponentState (per-instance, where preview velocity correctly lives — that is a utility setting, one per instrument; the transfer curve is a musical setting, one per sound). The curve is an additive field on PerformanceZone, defaulting to the flat identity, and rides the zones-payload version axis — NOT the envelope version axis (contrast preview velocity's envelope-v6 bump, which is a per-instance top-level field). The single-capture Sample face reads/writes the same one-zone storage site (S15-F2), so the Sample view and the Zone view share one curve store.
Default → flat y=1 (all velocities full level), which is a DELIBERATE behavior change — fork R10-F1. Daniel's verbatim default is "any velocity plays at full level" — a flat curve at y=1. That is not bit-identical to today's shipped linear velocity/127 map: today a soft hit is quieter; under a flat-y=1 default every hit plays at unity. This is the one genuine fork the feature carries, and it is Daniel's call:
- Option A (Daniel's stated default): flat y=1. Honors the verbatim directive; velocity is inert until the user draws a curve. Con: not back-compat — already-saved instances (and new captures) get louder/flatter dynamics than today's build until a curve is drawn. Every existing zone's felt response changes.
- Option B: default = the current linear ramp (y = x/127). Bit-identical to today's engine; the editor's "flat y=1" is then one drawn state among many, not the default. Con: contradicts the verbatim "by default … full level" — the default line would be a diagonal, not flat.
- Recommendation: Option A (flat y=1) as the stored default, because it is what Daniel asked for and the feature's whole point is that velocity is opt-in dynamics — but flag it loudly as a shipped-behavior change so it is a decision, not a silent regression. If the changed feel on existing projects is unwanted, Option B is the safe fallback and costs only the default curve's control-point values. Daniel's call. (Whichever wins, the stored default is a curve the editor can draw and the core can evaluate — the two options differ only in which curve is seeded.)
Pure module → velocity_curve (REAPER/LICE-free, unit-tested). Mirror of envelope_edit / card_drag. Two responsibilities: (a) evaluation — eval(velocity 0–127) → amp scalar 0–1 for the voice engine (a bezier through the control points, clamped to the 0–127 × 0–1 box, monotonic-in-x by construction so a given velocity has exactly one output); and (b) editing — add / move / delete control points, each clamped into the box, x-ordered (a point cannot cross its neighbours in x, same monotonic grammar as the envelope nodes), with a point hit-test (point → which control point, pick radius) and a pixel-delta → clamped-point inverse map. Both halves are unit-tested at the boundaries: a known curve + known velocity asserts the eval output; a known drag asserts the clamped point set and the box/order constraints. The flat identity curve (whichever default R10-F1 picks) is a named constructor. No RT concern in the module — evaluation is called at note-on, not per frame (see call 4).
Voice-engine application point → Voice::start(), replacing the linear velocity/127. Confirmed from source: sampler_core.cpp:261 computes velocityGain_ = velocity / 127.0 once at note-on inside Voice::start(); the per-frame render path (advanceFrame, line 408: gain = amp * velocityGain_) then just multiplies the cached scalar. So the transfer curve slots in at exactly one line: velocityGain_ = curve.eval(velocity) at note-on — off the audio-thread-hostile per-frame path, evaluated once per voice, honoring the house RT discipline (no new per-frame work, no allocation in process). The curve travels to the voice the same way the AHDSR/keyTrack params do: on the zone's SampleData::play bundle (resolved from the stored PerformanceZone at keymap build), read by the voice at start(). The pure core owns the eval; the voice reads it.

The curve-editor UI — Sample view, near the envelope overlay. It lives on the Sample view (the r9 home face), as a compact band adjacent to the hero-waveform envelope overlay — the two are the same grammar (a drawn 2-D curve with draggable handles) and reading them side by side is natural (amp-over-time next to amp-over-velocity). Draws through the L1 kit like every S-VIEW surface: a bordered box (X = velocity 0–127, Y = amp 0–1), the bezier traced in an accent hue, small draggable node markers at each control point (hover/drag-lit via kit states), add-point on click in empty space, delete on a modifier-click or drag-off. The shell (reasampler_editor.cpp) does the LICE draw + mouse routing; all geometry/hit-test/clamp math is in the pure velocity_curve module. On the Zone view the same editor appears in the per-zone param panel (one curve per zone). Additive and bit-identical-for-existing-projects only under R10-F1 Option B; under Option A (the lean) it is additive-but-behavior-changing, per call 2.

What does NOT change (guardrails). Instrument stays a read-only bank consumer — the curve is performance map on PerformanceZone, never written to Sample or the bank (D-B). LICE/SWELL drawing only; all math in the pure velocity_curve module (D-A). RT discipline untouched — eval is at note-on, not per frame. VST3 class UID unchanged — an additive per-zone field is not a compat event. Zones-payload version bump only; the envelope version axis (preview velocity's v6) is independent and untouched.

Wave-plan slot (concurrency-aware — six engineers are in worktrees now). Because the curve lands on PerformanceZone, it is blocked by Wave 1 track T-KEYTRK (which owns the PerformanceZone schema + the zones-payload version bump right now). The velocity-curve field must sequence as a LATER additive payload bump AFTER T-KEYTRK merges, so the two do not collide on a single payload version number — T-KEYTRK's keyTrack field and this velocityCurve field are sequential additive extensions of the same zones-payload record, not simultaneous ones. It is not blocked by T-STATE (that track owns the per-instance ComponentState v5→v6 envelope bump for preview velocity — a different struct on a different version axis). Concretely this is:

a follow-on foundation track (pure velocity_curve module + the core application point at Voice::start + the additive PerformanceZone field + payload bump), gated on T-KEYTRK; plus
a Wave 2 shell-integration item (the Sample-view + Zone-panel curve-editor UI drawn through the L1 kit, routing mouse through velocity_curve), gated on the foundation track and composing with the S-VIEW-2 Sample face + S-VIEW-3 envelope-overlay work.

Where the spec lives: CONTEXT.md §Phase S — editor view-model redesign (S-VIEW), velocity-curve sub-section; PLAN.md §Phase S — editor view-model redesign (S-VIEW-9/S-VIEW-10 + fork R10-F1). 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:

D-A → bare Steinberg VST3 SDK + LICE editor (no JUCE). The IPlugView↔LICE bridge is the opening implementation spike (S1), not a decision gate.
D-B → split seam; root note + loop points added to Sample now (S2, in the extension) to close the backfill cliff.
D-C → Tier 0–1 committed (S4/S5); Tier 2 held (noted, not specified); Tier 3 optional-forever.
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):

D-E → channel mode (mono | stereo), per-instance, bus-negotiated (S7) — an S3-core channel-dimension extension, sequenced first after the editor/embed work.
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):

Product name → ReaSampler 9000 (VST3 class UID unchanged; binary filename renamed too — S-NAME-1 SETTLED r6, compat is a DAW-verify).
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.
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).
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.

94 KiB Raw Blame History Unescape Escape