reasampler/README.md

# ReaSampler

Version 1.5.0 · License: GNU AGPL v3 (see `LICENSE`)

A per-project audio sample-bank capture tool for REAPER, built as two artifacts: a
native C++ REAPER extension (`reaper_reasampler`) and a Windows-only VST3 sampler
instrument (`reasampler_9000.vst3`, ReaSampler 9000). It 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. It is
designed as a precision tool: deterministic captures, non-destructive by
construction, no auto-inserted clutter.

## Status

Under active development, not yet formally released.

## The two artifacts

**`reaper_reasampler`** — the REAPER extension. Captures audio into a named,
per-project sample bank and provides bindable actions across the workflow: offline
and realtime capture (with cancel), batch capture (per selected item or per razor
area), recapture-from-source, capture-and-assign to a live instrument instance,
insert with an opt-in tempo-conform variant, the resample-bake landing action,
multi-bank management (pool, activate, evacuate, move, copy, delete), prune/reclaim,
provenance and lineage tracking, Design View, and ingest via drag-out, arrange-drop,
and instrument-drop. All of it surfaces in a docked bank panel.

**ReaSampler 9000** (`reasampler_9000.vst3`) — a Windows-only VST3 sampler
instrument that plays bank captures back across a MIDI keyboard. Since
`ComponentState` v10 it is self-contained: it decodes samples from its own
persisted references and plays with the extension absent, treating the bank as a
browsing source rather than a runtime dependency. The VST3 target
(`reasampler_vst`) is gated on `WIN32 AND EXISTS .../pluginfactory.cpp` — omitted
on macOS/Linux even when the vendored `vendor/vst3sdk` slice is present, and
quietly omitted anywhere the slice itself 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.

## Prerequisites

- CMake ≥ 3.19
- A C++17 compiler
- Windows + MSVC to build the VST3 target (`reasampler_vst`) — the REAPER extension
  itself is cross-platform
- PHP, to run the SWELL resource-generation step on macOS/Linux (below)

## Platform support

The REAPER extension targets Windows, macOS, and Linux; ReaSampler 9000 (the VST3
instrument) is Windows-only.

| Platform | Extension | VST3 instrument |
|---|---|---|
| Windows | Builds with no extra steps | Builds when `vendor/vst3sdk` is present |
| macOS | Builds, but dialogs need the manual SWELL resgen step below plus hand-uncommenting the `APPLE` `target_sources` block in `src/app/CMakeLists.txt` | Not built (Windows-only gate) |
| Linux | Same manual resgen + hand-uncomment requirement as macOS, against its own commented block | Not built (Windows-only gate) |

A macOS/Linux build that skips the resgen-and-uncomment step compiles cleanly
without dialogs and without a warning — this is expected, not a bug.

## One-time setup

A plain `git clone --recursive` also works, but it pulls every nested submodule of
`vendor/vst3sdk` (including `vstgui4`, `tutorials`, `doc`, `cmake` — none of which
this project links against). The steps below pull only the three submodules
actually needed:

    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 -C Debug

On a multi-config generator (Visual Studio, Xcode), `cmake --build build` with no
`--config` builds **Debug** — nothing in this build sets `CMAKE_BUILD_TYPE` or an
optimization flag, so that's the default. The `-C Debug` above is required on a
multi-config generator too: without it, `ctest` silently reports every test as "Not
Run" instead of running them. Single-config generators (Ninja, Make) need neither
flag.

Pure `core/` modules each have a corresponding `<module>_tests` executable target
that runs without REAPER or a DAW. Targets are declared per-directory — each
`src/**/CMakeLists.txt` owns its own libraries and test targets, pulled in via
`add_subdirectory` from the root `CMakeLists.txt`, which itself declares no targets
directly.

Installing or judging performance requires the Release config explicitly:

    cmake --build build --config Release
    ctest --test-dir build -C Release

### 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/swell_resgen.php src/resource.rc   # macOS; Linux reuses the output

Add the generated file to the appropriate `APPLE` / Linux `target_sources` block in
`src/app/CMakeLists.txt` (both are commented out by default). The SWS extension
build is the canonical reference for this step.

## Install

There is no hot reload; REAPER loads extensions at startup only.

**Extension** — copy the **Release** build's `reaper_reasampler` binary
(`build/Release/` on a multi-config generator — not the default `Debug/` output)
into REAPER's `UserPlugins/` folder (Options → Show REAPER resource path), then
restart REAPER.

**VST3 instrument** — copy the **Release** build's `reasampler_9000.vst3` into the
system VST3 folder (`C:\Program Files\Common Files\VST3` on Windows) — a different
destination from the extension, not `UserPlugins/`. REAPER picks it up on its next
plugin rescan.

## Repo layout

The codebase is organized around one discipline: **pure, REAPER/VST3-SDK-free
testable core, split from the REAPER- and VST3-facing shells that touch those host
types.**

- `src/app/` — the REAPER extension's entry point (`main.cpp` only)
- `src/core/` — pure modules, no REAPER or VST3 SDK types, each with a
  `<module>_tests` target: `audio/`, `capture/`, `instrument/` (further split into
  `bake/`, `engine/filter/`, `engine/loop/`, `map/`, `note/`, `ui/`), `json/`,
  `model/`, `reclaim/`, `tracking/`, `ui/`, `util/`, `version/`, `view/`, `wire/`
- `src/shell/` — REAPER/VST3-facing shells: `actions/`, `bank_ops/`, `capture/`,
  `instrument/` (the ReaSampler 9000 VST3 shells), `panel/`, `persist/`, `view/`
- `src/resource.rc`, `src/resource.h`, `src/ext_keys.h` — root-level build inputs
  not claimed by any one subdirectory
- `tests/` — unit test sources for the pure `core/` modules
- `cmake/` — shared CMake target-declaration helpers
- `docs/` — plan-style docs and product-design docs (see Further reading, below)
- `vendor/` — git submodules

See `CLAUDE.md` for the full module inventory, architectural contracts, and the
precise boundary between pure core and REAPER/VST3-facing shells; each `src/**/`
directory also carries its own `CLAUDE.md` with that area's own module list and
invariants.

## License

GNU AGPL v3, copyright Daniel Harvey. See `LICENSE`.

## Further reading

- `CLAUDE.md` — architecture, module inventory, and build/API contracts
- `docs/PLAN.md` — the active roadmap
- `docs/COMPLETED.md` — landed milestones for the current (1.x) cycle
- `docs/TODO.md` — deferred follow-ups, with the reason each was deferred
- `docs/TODO-1.0.md` — the raw 1.x work list this cycle's plan was structured from
- `docs/ARCHIVE.md` — pre-1.0 history
- `docs/cmake-cheatsheet.md` — a standalone build-system reference
- `docs/product/` — the product-design reasoning behind each phase