# ReaSampler

A native C++ REAPER extension that captures any arbitrary audio source into a
per-project **sample bank** (cached files + a docked grid), decoupled from the
arrange view, with keyboard/MIDI-bindable capture and placement. Built as a
precision tool: deterministic, non-destructive, no clutter.

## The two artifacts

**`reaper_reasampler`** — the REAPER extension. Captures audio into a named,
per-project sample bank, displays it in a docked panel, and provides bindable
actions for capture and placement.

**ReaSampler 9000** (`reasampler_9000.vst3`) — a Windows-only VST3 sampler
instrument that plays bank captures back across a MIDI keyboard. The VST3 target
(`reasampler_vst`) is gated on the vendored `vendor/vst3sdk` slice; configure
quietly omits it if the slice is absent.

A **beta channel** build is available via `-DREASAMPLER_CHANNEL=beta` at configure
time, producing `reaper_reasampler_beta` and `reasampler_9000_beta.vst3`. The two
channels coexist in one REAPER installation and do not share state.

## The load-bearing principle

Capture and placement are separate acts. Capturing audio writes a file to the bank
and adds an index entry. It **never** puts an item in the arrange view. Placement
is a distinct, on-demand action. Any code path that auto-inserts a capture into the
timeline violates the purpose of the tool.

## One-time setup

    git submodule update --init

Vendors three submodules:
- `vendor/reaper-sdk` — `sdk/reaper_plugin.h`, `sdk/reaper_plugin_functions.h`, SWELL headers
- `vendor/WDL` — WDL utilities and the SWELL cross-platform Win32 layer
- `vendor/vst3sdk` — Steinberg VST3 SDK (Windows-only; requires a nested init after the top-level init):

      git submodule update --init vendor/vst3sdk
      cd vendor/vst3sdk && git submodule update --init pluginterfaces base public.sdk

## Build and test

    cmake -B build -S .
    cmake --build build
    ctest --test-dir build

Pure modules have `<module>_tests` targets that run without REAPER or a DAW.
`CMakeLists.txt` is the authoritative list of all targets.

### Beta channel

    cmake -B build-beta -S . -DREASAMPLER_CHANNEL=beta
    cmake --build build-beta

### macOS / Linux dialog resources

`src/resource.rc` must be pre-processed by SWELL's resgen once per platform:

    php vendor/WDL/WDL/swell/mac_resgen.php src/resource.rc   # macOS; Linux reuses the output

Add the generated file to the appropriate `APPLE` / Linux `target_sources` block in
CMakeLists.txt. The SWS extension build is the canonical reference for this step.

## Install

Copy the built binary into REAPER's `UserPlugins/` folder
(Options → Show REAPER resource path), then **restart REAPER**. Extensions load at
startup only; there is no hot reload.

## Repo layout

The codebase is organized around one discipline: **pure, REAPER-free testable core
split from REAPER-facing shells**.

- `src/` — pure core modules (no REAPER types, unit-testable outside the DAW) and
  REAPER-facing shells (extension entry point, panel, actions, capture backends, etc.)
- `src/vst/` — the VST3 instrument: pure voice engine + zone payload + editor UI
  pure modules, and the VST3 shells
- `tests/` — unit tests for the pure core modules
- `vendor/` — git submodules

See `CLAUDE.md` for the full module inventory, architectural contracts, and the
precise boundary between pure core and REAPER-facing shells.

## Further reading

- `CLAUDE.md` — architecture, module inventory, and build/API contracts
- `CONTEXT.md` — the authoritative spec (large: ~186k — grep the relevant section rather than reading whole)
- `CONTEXT-ARCHIVE.md` — build detail for landed work
- `PLAN.md` — roadmap
- `COMPLETED.md` — landed milestones