reasampler/docs/product/midi-playback.md

# MIDI playback — opportunity & design-space framing

Framing for a **MIDI-triggered audio sampler** that plays back ReaSampler's captured
banks. This is a **discussion-shaping doc, not a build plan** — no phase, no PLAN.md
points, no settled forks yet. It exists so Daniel and the-boss can react to an honest
map of the option space before anything is scoped.

Status: framed by product-designer (2026-07-26), **revised 2026-07-26** to correct a
material omission — the earlier draft missed REAPER's **VST-host bridge**: a VST/VST3
plugin *hosted inside REAPER* can call back into REAPER's own API from within the
plugin, resolving API function pointers by name over the host `audioMaster` callback.
That single fact changes the integration seam (§2), the "one product or two" question
(D6), and the JSFX-vs-native calculus (D1/D2). The corrections are made plainly
in-place, not appended as a footnote; where the prior draft was too pessimistic about
what a native instrument can reach, it is fixed and the correction is flagged. 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`) and
REAPER's published VST-extensions SDK page (`reaper.fm/sdk/vst/vst_ext.php`) — the
plugin-format claims below are checked against those, not asserted. The genuine forks
are flagged as **Daniel's to decide**; nothing here pre-decides them.

> **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 three honest options

**Option A — a real VSTi/instrument plugin (JUCE or bare VST3/CLAP SDK) that reads
ReaSampler's banks.** A separate build artifact: a VST3 (and/or CLAP) sampler plugin
that the user instantiates on an instrument track. It maps samples across the keyboard
and plays them MIDI-triggered with a real voice engine. This is the "sophisticated
sampler" answer.
- *Gives you:* everything an instrument is — polyphony, velocity, envelopes, the works,
  fully integrated into REAPER's routing/render/record path like any VSTi. **And,
  because it's hosted in REAPER, it reaches ReaSampler's project state directly via the
  VST-host bridge** — it doesn't merely parse bank JSON off disk, it can read the live
  `"reasampler"` ext-state `persist` writes, know its own host project, and follow the
  active project. The prior draft treated Option A as a divorced file-reader; that was
  the omission. A native ReaSampler instrument can be **natively, tightly integrated with
  the extension's project state**, not loosely coupled through a file format alone.
- *Costs:* a **second codebase in a second plugin format**, almost certainly a new
  dependency (JUCE is the pragmatic choice; bare VST3 SDK is more code, CLAP is leaner
  but younger). It is a real DSP/voice-engine build, not a weekend. Cross-platform DSP,
  its own build/release/signing story, its own UI toolkit. This is a **product-sized
  commitment**, not a feature. And leaning on the bridge for state means the instrument
  is **REAPER-coupled** — it stops being a portable VST that runs in any host and becomes
  a REAPER companion. That may be exactly right (see D6), but it is a real narrowing and
  must be a conscious choice, not a side effect.

**Option B — a JSFX sampler.** JSFX is REAPER's built-in scriptable plugin format
(text `.jsfx` files, JIT-compiled by REAPER, hostable as an instrument). A JSFX
instrument *can* receive live MIDI and emit audio on a track. It can load samples
(`Xen`-style file reads / the JSFX file/serialize API) and play them back.
- *Gives you:* a real in-track instrument with **zero new binary, zero new SDK, zero
  JUCE** — ships as a text file alongside the extension, cross-platform for free
  (REAPER runs the JIT everywhere it runs).
- *Costs:* JSFX is a constrained DSP scripting language, not C++. A polyphonic
  multisample engine with round-robin/velocity-layers/streaming is *doable* but you're
  writing DSP in JSFX's idiom, and large-sample streaming / disk I/O is more awkward
  than in a native plugin. Reading ReaSampler's JSON index from JSFX is friction (JSFX
  is not a general-purpose file parser). Best fit for a **minimal-to-mid** sampler, a
  real ceiling for a **sophisticated** one.
- *What JSFX can't match, now that the bridge is on the table:* the VST-host bridge is a
  **VST/VST3/CLAP capability** — it is how a *hosted plugin* resolves REAPER API pointers.
  JSFX is not a hosted VST; it has REAPER integration of its own kind (`ext_noinit`,
  `file_*` ops, the shared `gmem[]`, `slider`/parameter plumbing), but it does **not** get
  the same string-keyed REAPER-API surface a native VST does, and in particular has no
  clean, native path to read `persist`'s `"reasampler"` project ext-state the way a native
  VST can. On the JSFX path, the seam is genuinely "read a file ReaSampler wrote next to
  the bank" (hence the sidecar note in §2). This asymmetry is new information: the bridge
  makes **native meaningfully more integratable** than the prior draft assumed — it's not
  just "native is more powerful DSP," it's "native can be *part of ReaSampler's state
  model*, JSFX stays a file-coupled consumer."

**Option C — the hybrid (recommended framing to explore first).** Keep the extension
as the sole owner of **capture + organization** (which is its whole existing identity
and the load-bearing "capture and placement are separate acts" principle). Add a
**separate instrument** (Option A *or* B) that **consumes the banks** as a
shared-artifact contract. The extension never becomes an instrument; the instrument
never captures. Each does what its format is good at. This is the honest shape of the
whole thing — the two options above are really "which instrument technology" *within*
the hybrid, because the extension is staying regardless.

The real fork, then, is **not** "extension vs. plugin" (the extension stays either
way) — it is **"which instrument format consumes the banks: JSFX or native VSTi/CLAP,"**
and **"how much sampler do we actually want."** Those are §3 and §4.

---

## 2. The integration seam

The prior draft assumed one seam: **the bank folder (project-relative WAVs) + the
bank/index JSON on disk**, with the playback engine as a file-reader. That's still the
seam for *sample audio* (WAVs are files; there's no getting a live PCM stream across the
bridge, nor would you want to). But for **everything that isn't the raw audio** — the
index, the mapping data, which project's bank is active — the bridge opens a **second,
richer seam** the prior draft missed:

- **File seam (audio + a portable snapshot).** WAVs on disk; index/mapping as JSON or a
  sidecar. Tool-agnostic, host-agnostic, portable. Any instrument (JSFX or native, in
  REAPER or any other host) can consume it. This is the *only* seam JSFX gets, and the
  *fallback/export* seam for native.
- **Live-state seam (native-in-REAPER only).** 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 strictly more than the file seam and it's REAPER-coupled by construction.

The design question below — "is the JSON sufficient, or does playback need mapping the
index doesn't carry" — is unchanged. What the bridge changes is *where that mapping can
live and how the instrument gets it*: for native, the mapping can be **live shared state**
between extension and instrument, not just a file handed across.

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

**A note on format (revised for the bridge):** the friction is asymmetric, and more so
than the prior draft said.
- *Native (Option A):* doesn't just "read the bank JSON off disk" — it can read the map
  out of **live project ext-state** via the bridge (whichever of i/ii/iii you choose, the
  extension and instrument can share the *same* `"reasampler"` state rather than one
  writing a file the other re-parses). The `.wav` audio is still files; the mapping need
  not be. Cleanest possible integration.
- *JSFX (Option B):* no bridge — reading arbitrary JSON is friction, so the seam likely
  needs a **simpler sidecar** (a flat `.txt`/key-value map ReaSampler writes next to the
  bank, JSFX-parseable). On the JSFX path the seam is unavoidably file-based. That's a
  concrete cost of JSFX and a reason the seam design and the format choice stay coupled.

**Portability caveat (partly dissolved on the native path).** The bank is project-relative
and travels with the `.rpp` (M4 machinery). Any *file-seam* consumer must resolve paths
the same way — so a JSFX instrument still needs to be told the current project bank folder
(saved in its own state), a real wiring detail, don't hand-wave it. But a **native**
instance sidesteps this: via the context callback it asks REAPER which project it's in,
then reads that project's bank location straight from ext-state — no "point me at the
folder" step. What was a shared wiring cost is now a **cost only on the JSFX path.** Note
the flip side: a native instrument that resolves its bank *only* through the bridge won't
work outside REAPER at all — so if a portable/exportable instrument is ever a goal, keep
the file seam as the source of truth and treat the live-state seam as an accelerator, not
the sole path.

---

## 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 JSFX path this is a
genuinely small build; on the native path it's the skeleton of the plugin.

**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. Risks & open decisions — Daniel's to call

None of these are pre-decided here. Each is a genuine fork.

**D1 — Instrument format: JSFX vs. native VSTi (VST3/CLAP, likely via JUCE).** The
central fork. JSFX = no new binary, no JUCE, cross-platform free, real ceiling on
sophistication, awkward bank-JSON reading, **and no VST-host bridge** (file-seam only).
Native = full sophistication, clean integration, **plus the bridge**: live `"reasampler"`
ext-state, project-awareness, embedded TCP/MCP UI (see below) — at the cost of a whole
second codebase in a second format with its own build/release/dependency/signing story,
**and REAPER-coupling if it leans on the bridge.**

*What the bridge does to the native column (the honest update).* The prior draft's native
pitch was "more DSP power + parses JSON cleanly." The bridge adds a category the prior
draft didn't weigh: native can be **part of ReaSampler's live state model**, not a
file-coupled consumer. That is a real pull toward native beyond raw DSP — it's the
difference between "an instrument that reads a ReaSampler export" and "an instrument that
*is* ReaSampler's playback surface." It doesn't make JSFX wrong; it makes native's ceiling
higher and its integration tighter than I credited. Weigh it against the coupling cost: a
bridge-dependent VST is a **REAPER-only** artifact, no longer a portable VST.

*My lean, updated but unchanged in direction, for discussion only:* if the goal is
Tier 0–1, **still prototype in JSFX first** — it proves the *sampler value and the
key/velocity seam* with near-zero format commitment, and the file seam you design there is
exactly the portable/export seam a native build would keep anyway. The bridge is an
*integration* advantage, not a *does-the-sampler-work* advantage, so it doesn't change what
the cheapest proof is. Reach for native when either (a) Tier 2+ sophistication is a firm
goal, or (b) **tight live integration with ReaSampler's project state is itself the point**
— that second trigger is new, and it's the bridge's real contribution to this fork.

**D2 — Whether to take a JUCE (or any external plugin-SDK) dependency at all.** The
project today is a clean C++ extension with two vendored submodules and a proud
pure-core/shell discipline. A native instrument means a *third* major dependency and a
second build target of a fundamentally different kind. That's a real architectural
weight. JSFX sidesteps it entirely. Flagging it as its own decision because "should we
depend on JUCE" is a bigger standing commitment than "should we build a sampler."

*The bridge's bearing on D2.* Weigh two coupling costs, not one. A native instrument that
uses the bridge takes on **both** a plugin-SDK dependency (JUCE/VST3/CLAP) *and* a
REAPER-API coupling (the same `reaper_plugin_functions.h` surface the extension binds — so
the instrument would vendor and bind against it too, likely resolving pointers via `hostcb`
rather than the extension's startup path). The upside is that the pure sampler core stays
REAPER-free and testable regardless (D3); it's only the *shell* that touches the bridge, so
the coupling is contained where the project already puts REAPER coupling. The downside is
plain: choosing the bridge means choosing a REAPER-only instrument. If Daniel wants a
sampler that also runs in other hosts, the bridge is off the table and D1's native pitch
loses its integration edge — collapsing back toward "native = more DSP power only."

**D3 — Does the pure-core discipline survive the format boundary?** ReaSampler's
identity is *pure REAPER-free testable core + thin shells*. A sampler's **voice engine,
envelope math, key/velocity mapping, and repitch logic are exactly the kind of pure,
testable core** this project excels at — they could live in a REAPER-free, DAW-free,
unit-tested module (mirror of `bank_model`/`peaks`/`view_mode_model`) with the plugin
format (JSFX or VST3 wrapper) as the thin shell around it. **This is the most
ReaSampler-native way to build it** and I'd argue strongly for it regardless of D1: the
sampler DSP core is pure and tested; the format is a shell. The open question is whether
that discipline can hold across a *different plugin format* — with native it's clean C++
so yes; with JSFX the "pure core" would be JSFX code, harder to unit-test in the CTest
harness. That tension is real and feeds back into D1.

**D4 — Where the mapping lives (seam fork i/ii/iii from §2).** Bank-owned map,
instrument-owned map, or split (file-intrinsics in the bank, performance-map in the
instrument). *My lean:* **(iii) split** — it's the one that honors ReaSampler's
capture/placement instinct and keeps the bank tool-agnostic. But it's Daniel's call
whether ReaSampler should author instrument definitions at all, or stay purely a
sample library that a *separate* mapping tool arranges.

**D5 — Cross-platform.** The extension is already cross-platform (SWELL). JSFX inherits
that for free. A native plugin re-opens the full cross-platform DSP + UI + build matrix
(Win/mac/Linux, code-signing on mac, etc.) as a *separate* artifact. A cost that lands
entirely on the native path.

**D6 — Is this even one product?** The reframe worth surfacing: ReaSampler's thesis is
"a precision *capture/organize* tool; capture and placement are separate acts." A
MIDI-playback instrument is a *different act* — playback. There's a legitimate reading
where the instrument is a **companion product** that shares the bank format, not a
feature *of* ReaSampler — the way a sample library and a sampler that reads it are
related-but-distinct products. That framing might keep ReaSampler sharp (it stays the
capture tool it is) while letting the instrument evolve on its own clock and format.
The alternative reading — it's all one integrated sampler-workstation — is also
coherent.

*Re-argued with the bridge on the scale (the prior draft weighed this fork without it).*
The prior draft implicitly assumed the two products could only ever share a **file
format** — which makes "companion product" feel clean and natural, because a shared file
is exactly what independent products share. The bridge changes the terms. A native
instrument can be **tightly, live-integrated with ReaSampler's project state**: same
`"reasampler"` ext-state, same project identity, following the active project — a degree
of coupling that is *more than* "two products that happen to read the same files" and
starts to look like "two faces of one tool sharing one state model." That is a genuine
thumb toward the **one-integrated-product** reading. It's not decisive, and I won't
pretend it is:
  - It only applies if the instrument is **native** (JSFX can't reach the bridge, so a
    JSFX instrument *is* naturally a file-coupled companion — the format choice and this
    fork are entangled: pick JSFX and you've half-answered D6 toward "companion").
  - It's an *available* integration, not a *required* one — a native instrument could
    still be built to the file seam only, deliberately staying a loose companion for
    portability. The bridge widens the option, it doesn't force it.
  - The tight-integration reading buys **REAPER-coupling**; the companion reading buys
    **portability and independent evolution.** Those are real, opposed goods, and the
    bridge doesn't resolve which Daniel wants — it just makes the integrated option
    *materially more capable* than the prior draft credited, so the companion reading no
    longer wins by default on "well, they can only share a file anyway."

**Net:** the bridge strengthens "one integrated product" from a coherent-but-equal option
into the one with the stronger technical affordance — *if* native-in-REAPER is the path.
It does not pre-decide the fork. This is still the highest-order question and it's Daniel's
to answer, but he should answer it knowing the integrated option is richer than the
file-sharing picture implied — and knowing that choosing JSFX quietly tilts it the other
way.

**D7 — Embedded TCP/MCP UI (new option the bridge surfaces; native/CLAP only).** While
verifying the bridge I found a second REAPER-VST-specific affordance the prior draft never
mentioned: a hosted plugin can **draw its own embedded UI directly in the track/mixer
control panel** (`reaper_plugin_fx_embed.h`: VST2 answers `canDo("hasCockosEmbeddedUI")`
with `0xbeef0000` and draws via `effVendorSpecific/effEditDraw`; VST3 implements
`IReaperUIEmbedInterface`; CLAP exposes `cockos.reaper_embedui`). Concretely: a native
ReaSampler instrument could render a compact keymap/level strip *inline in the TCP/MCP*,
not only in its own plugin window — the same surface REAPER's own JS/embedded FX use. This
is **native/CLAP-only** (JSFX can't do it) and is pure polish, not a Tier-0 need — but it's
a real integration affordance that only exists on the native-in-REAPER path, and it
compounds the D1/D6 tilt: if "ReaSampler's playback surface, deeply woven into REAPER's UI"
is the vision, this is a lever only native reaches. Flagging it for completeness, not
recommending it — it's a Tier-3-ish nicety, deferred by default.

---

## What this doc is asking for

A direction on the two highest-order forks, in order:

1. **D6 — one product or two?** Is the instrument a feature of ReaSampler, or a
   companion product sharing the bank format? Everything else sits under this.
2. **D1 — JSFX-first prototype, or straight to native?** Given a target of Tier 0–1 to
   start, and the pure-core-as-shell discipline (D3) held either way.

Once those two are called, the seam fields (§2, D4) and the tier scope (§3) become
concrete enough to write an actual phase spec. Until then this stays a framing doc with
no PLAN.md footprint — deliberately, so we don't scope an instrument before deciding
whether we're building one.