reasampler/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Repo identity and current state

ReaSampler is a per-project audio sample-bank capture tool that builds two artifacts: the REAPER extension (reaper_reasampler) and ReaSampler 9000, a Windows-only VST3 sampler instrument (reasampler_9000.vst3, core/instrument/ + shell/instrument/, second CMake target reasampler_vst, gated on the vendored vendor/vst3sdk submodule slice). The pure-testable-core / REAPER-facing-shell discipline is preserved throughout: core/ never includes REAPER or VST3 SDK types, shell/ is where those hosts are actually touched, app/ is the extension entry point. Every REAPER API name cited in project docs is correct-by-intent; verify argument order, types, and flag values against vendor/reaper-sdk/sdk/reaper_plugin_functions.h before use.

Per-module detail — what each file owns, its invariants — lives in the twenty-four per-directory src/**/CLAUDE.md files; see the compact map in "Architecture: the load-bearing split" below to find the right one. Landed-phase history lives in docs/ARCHIVE.md; current work lives in docs/COMPLETED.md, docs/TODO.md, and docs/TODO-1.0.md — see "Project docs" below.

Settled decisions

• Capture modes: offline render (deterministic, the default) AND realtime record (for hardware / performed FX). The two backends deliberately share no interface — their lifecycles genuinely differ (offline is synchronous, realtime is async begin/tick/abort) — but both produce identical bank entries.
• Bank scope: per-project, travels with the .rpp. Files live in a project-relative subfolder; the index persists in project ext state. No absolute paths anywhere in the index.
• Material: must handle full-mix/stem bounces, chops/one-shots, and single-cycle/wavetable grabs equally. That means exact sample-accurate bounds, explicit tail control, correct channel handling (the exact-bounds channel rule under Precision invariants), and loop/zero-crossing handling all matter from day one.

One-time submodule setup

git submodule update --init

Vendors three submodules (see .gitmodules):

• 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
  

  The VST3 target (reasampler_vst) is gated on EXISTS .../pluginfactory.cpp — configure quietly omits it if the slice is absent.

Build and test

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

On a multi-config generator (Visual Studio, Xcode) the bare ctest command above reports every test as "Not Run" — add -C Debug (or whichever config was built) to resolve the test executables. Single-config generators (Ninja, Make) need no such flag.

On a multi-config generator, cmake --build build with no --config builds Debug — there is no CMAKE_BUILD_TYPE, no CMAKE_CXX_FLAGS, and no IPO/LTO setting anywhere in the build, so nothing is optimized or inlined at that default. The performance guardrails and structural heuristics below (header-inline hot paths, "no LTO configured") presume an optimizing build. Shipping, installing, or judging performance requires the Release config explicitly:

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

Every pure module has 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 their test targets, added via add_subdirectory from the root, which keeps only repo-global settings (version, channel, vendor paths). cmake/reasampler_targets.cmake holds the two shared declaration helpers. The two loadable-module targets are reaper_reasampler (the REAPER extension .dll/.dylib/.so) and reasampler_vst (the VST3 instrument; Windows-only, omitted if the vendor/vst3sdk slice is absent). The sample_usage_tests executable target runs the pure unit tests for sample_usage (no REAPER, no DAW).

Beta channel build

To build the fully isolated beta binary (reaper_reasampler_beta), pass the channel flag at configure time:

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

The flag threads through configure_file → version_generated.h and fans out via app_version into the binary name, ext-state namespace ("reasampler_beta"), command-id prefix (CEREBELLUM_REASAMPLER_BETA_), action-name prefix ("ReaSampler beta: "), dock ident, and version display (the configured version string with a -beta suffix appended). The default build (no flag) is byte-identical to the stable identity.

The VST3 target forks identically: REASAMPLER_CHANNEL=beta produces reasampler_9000_beta.vst3; the default produces reasampler_9000.vst3. The beta VST pairs only with the beta extension — each channel carries its own per-channel VST3 class UID, preventing a saved instance from rebinding across channels.

macOS / Linux: SWELL 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. The SWS extension build is the canonical reference for this step.

Install / reload

There is no hot-reload. Copy the Release build's binary (build/Release/ on a multi-config generator — not the default Debug/ output) into REAPER's UserPlugins/ folder (Options → Show REAPER resource path) and restart REAPER. Extensions load at startup only.

Architecture: the load-bearing split

core/ holds pure, unit-testable logic — no REAPER or VST3 SDK types, each with a corresponding <module>_tests target that runs without a DAW. shell/ holds the REAPER/host-facing shells — where those SDK types are actually touched. app/ is the extension entry point. Each of the twenty-four directories below carries its own CLAUDE.md with the full module list and that area's invariants — open the relevant one for detail; this file states only repo-wide truth.

Directory	Scope
src/app/	REAPER extension entry point
src/core/audio/	pure audio-data math
src/core/capture/	pure logic behind the capture pillar
src/core/instrument/	pure VST3-instrument core (bake / engine / map / note / ui)
src/core/instrument/bake/	the resample bake's pure half — the programmed note resolved to a frame window, the offline render over a bake-only voice engine, and the post-bake reset
src/core/instrument/engine/filter/	pure per-voice resonant TPT/SVF filter (HP→BP→LP / HP→notch→LP morph, drive stage), run by each Voice between the pitch and amp stages
src/core/instrument/note/	the programmed capture-signal model — musical divisions, tempo resolution, anchored offsets
src/core/instrument/param/	the VST3 parameter surface's pure half — the FOREVER-FROZEN id table, the exposed set derived from the commit predicate, the plain-value layer, and the one formatter per unit category
src/core/json/	the hand-rolled JSON lexical layer
src/core/model/	the pure bank/sample index and its multi-bank container
src/core/reclaim/	pure prune orphan computation
src/core/tracking/	the consolidated file-tracking system — birth/lineage records and the one authority answering prune's protected set and the resample's replace-vs-add
src/core/ui/	pure UI geometry, palette, and interaction-decision modules
src/core/util/	small shared pure utilities
src/core/version/	version/channel identity
src/core/view/	pure Design View mode model
src/core/wire/	pure ext-state and wire-format codecs, cross-artifact contracts
src/shell/actions/	bindable REAPER actions, drag/drop shells, ingest
src/shell/bank_ops/	promptless bank-mutation verbs
src/shell/capture/	REAPER-facing capture backends and action bodies
src/shell/instrument/	ReaSampler 9000 VST3 shells
src/shell/panel/	the docked bank-panel shell + the shared LICE draw kit
src/shell/persist/	project ext-state persistence, prune filesystem I/O, usage scan
src/shell/view/	Design View mode application shell

Directory and namespace layout

The top-level split is by the pure/shell discipline: core/ never includes REAPER or VST3 SDK types; shell/ is where those host types are actually touched — the discriminator is "may this file touch a host type, REAPER or VST3 SDK." Subsystem directories sit beneath core/ (see the table above); core/instrument/ further subdivides into bake/ / engine/ / map/ / note/ / param/ / ui/. Namespaces mirror directories — reasampler::<subsystem> for core/, house style for shell/. app/ holds main.cpp only: API-pointer ownership, ReaperPluginEntry, and dispatch.

For the module list within any one directory — what lives there, its invariants — open that directory's own CLAUDE.md rather than looking here.

Performance guardrails (HARD CONSTRAINT — Daniel's non-negotiable)

The reorg must cost zero runtime. The two hot paths must keep their exact call/inline shape; the following are acceptance criteria on every point:

• peaks envelope compute (computeEnvelope / lastFrameAboveThreshold over full PCM): NO virtual dispatch, NO peaks interface, NO added header→TU indirection. computeEnvelope stays a free function on const std::vector<float>& so it inlines as today. Relocate + namespace only; never wrap in an abstraction.
• Audition / preview: panel_audition may be its own TU, but the call stays a direct call-through, not virtual.
• Realtime-capture tick: keep the idle fast-path a single pointer test; realtime_lifecycle must not change the tick's branch shape.
• JSON extraction is off all hot paths — safe to abstract freely.
• FxBypassGuard runs per-capture, not per-frame — keep it stack RAII; never heap-allocate or virtualize it.

Net: every recommended split falls on a cold path or preserves call/inline shape on the two hot ones. A split that would add a hot-path indirection is out of scope — rework it or drop it.

Structural heuristics (Daniel, 2026-07-28 — acceptance criteria phase-wide)

Three heuristics postdate the original framing and bind every wave. They generalize the three-hot-path performance guardrail above — they do not replace it:

1. More directories is a must; more files is good; ~600-line file ceiling. SRP applies to namespaces, encapsulation, and file organization alike. The ceiling is the bar, the audit's named seams are the method: a file landing over ~600 needs a responsibility seam, not an arbitrary bisection (bisection-to-hit-the-number is rejected). A documented hot-path exception (sampler_core.cpp) is legitimate; silent overshoot is not.
2. Templates are the right tool for compile-time dedup — use them where earned. The LE byte-codec putLE/readLE is earned: compile-time dispatch, zero runtime cost, off the hot paths. The rect family is NOT: the types differ in name only, so one concrete ui::Rect — a template there would model nothing.
3. SOLID is great, but saved CPU is better. No dispatch-stack blowouts anywhere — not just the three named hot paths; prefer static polymorphism where the types are compile-time-known. A by-class sampler_core split that would put virtual envelope tick()s on the per-voice-per-sample path is exactly the blowout this forbids.

Comment conventions (Daniel, 2026-07-29 — driving the tree-wide comment-reduction pass)

Comments carry why, and context where non-obvious — never what the code already says.

• File headers stay brief (~5 lines); no titled prose sections inside them.
• Don't restate invariants a directory's own src/**/CLAUDE.md already owns — those files are the home for area invariants.
• No wave/ticket/milestone IDs in comments. A one-line "do not reintroduce X" warning is fine without the ticket number.
• Keep: RT-safety, allocation, and threading constraints; SDK facts confirmed by experiment; compressed regression history; format/version-ladder semantics; warnings against a plausible-but-wrong change.
• When unsure whether a comment is load-bearing, keep it.

REAPER extension contract (src/app/main.cpp)

• Exactly one translation unit defines REAPERAPI_IMPLEMENT — that is main.cpp. Every other .cpp includes reaper_plugin_functions.h without the define and gets extern declarations for the global API function pointers.
• REAPER dlopen()s any reaper_*.dll|dylib|so found in UserPlugins/ and calls the ReaperPluginEntry export (produced by REAPER_PLUGIN_ENTRYPOINT). rec->GetFunc resolves API pointers; rec->Register plugs extension callbacks in.
• Action registration pattern (preserve this for all new actions). Since Q-W6, main.cpp's own action family (capture scopes, panel toggle, insert, batch, realtime, recapture, version) is driven by a data-driven table in shell/actions/action_registry (ActionTableRow: suffix, phrase, flat function-pointer handler) — registration, hookcommand dispatch, and the unload mirror-unregister all iterate that SAME table, so adding an action touches one table row rather than three separate mechanisms. The other action families (shell/actions/design_view_actions, bank_actions, prune_action) register through their own TUs the same way. The per-step contract below is unchanged:
  1. rec->Register("command_id", (void*)"STABLE_FOREVER_STRING") — mints a persistent command id. Never change this string after shipping; user keybindings key off it. Since Phase V (V4), ids and display names are composed via channelCommandId(suffix) and channelActionName(phrase) from app_version — the FOREVER-STABLE contract applies per channel (stable and beta each have their own permanent id family).
  2. rec->Register("gaccel", &accel) — puts the action in the Actions list.
  3. rec->Register("hookcommand", ...) — receives every action fired; claim only your own id, return false otherwise.
  4. On unload (rec == nullptr), mirror-unregister everything with the same strings prefixed by '-'.
• Non-main sections use a different mechanism. gaccel_register_t carries no section field — command_id + gaccel can only ever produce a Main-section action. To publish into another section (Media Explorer = 32063, MIDI editor = 32060, MIDI event list = 32061, MIDI inline = 32062), register a custom_action_register_t{uniqueSectionId, idStr, name, extra} under "custom_action"; it returns the command id, or 0 on failure (e.g. a duplicate idStr) — which the caller must tolerate rather than half-register. idStr must be unique across all sections, so an action published into both Main and a non-main section needs a SECOND id string; the FOREVER-STABLE contract binds it identically from the moment it ships. custom_action_register_t has no ACCEL, so a non-main entry ships no default keybinding. Dispatch for these ids arrives through "hookcommand2" (bool(KbdSectionInfo*, int command, int val, int val2, int relmode, HWND)) — "hookcommand" runs for the main section only. The two hooks must partition the ids between them; what happens when a command is claimed by both is unspecified by the SDK (hookcommand2's doc says a true return prevents further hooks/actions from running, which is in tension with a clean double-fire either way), so nothing may rely on either outcome. On unload, mirror with "-custom_action" [verify — DAW] (the header confirms the - prefix for "most" registration types and spells out only -pcmsrc by name; custom_action itself is unconfirmed) and "-hookcommand2".

Product design docs

docs/product/ holds the product-design reasoning behind each phase — the "why we chose this" that predates the spec. They are large; grep for the cited section rather than reading a file whole. docs/cmake-cheatsheet.md is a standalone build-system reference.

Files: capture-tail.md, code-organization.md, design-view.md, midi-playback.md, multi-bank.md, provenance.md, removal-and-prune.md, versioning-and-release.md, visual-design-language.md.

Project docs

Plan-style docs live under docs/:

• docs/ARCHIVE.md — pre-1.0 history, rarely read, not a source of context for current work.
• docs/COMPLETED.md — 1.x landed items.
• docs/TODO.md — deferred follow-ups with recorded rationale.
• docs/TODO-1.0.md — the raw 1.x work list, not yet structured into a plan.

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 (insert module / InsertMedia). Any code path that auto-inserts a capture into the timeline violates the purpose of the tool and must be rejected in review.

Precision invariants — required before any feature ships

• Null test: a dry offline capture of a range, re-inserted at its source position, nulls to silence against the source — the tool's trust anchor. Ship as a verification action. (Verification action cut per docs/product/provenance.md — manual verification only.)
• Bit-identical repeats: identical offline capture requests produce identical files.
• Non-destructive: capture never mutates source items or tracks; the realtime backend's temp track is created and removed cleanly, and source routing is restored.
• Exact bounds: no rounding of the requested range; no added silence unless a tail is explicitly requested; no lossy channel fold — summing or averaging differing channels is forbidden. The one permitted collapse is lossless: a new capture whose channels are bit-identical per frame (float bit patterns, never an epsilon) lands as a 1-channel file, with Sample::channelCount and the file's fmt written together so the two can never disagree. Frame count, sample rate and bit depth are untouched by it. Never retroactive — existing entries and files are never rewritten — and ingest is excluded, because an imported file is the user's bytes, not our capture. The superseded wording ("channel count preserved") was already untrue in the other direction: a mono source renders at RENDER_CHANNELS = 2. [verify — DAW] "lossless" here is a file-bytes property; whether REAPER sums a 1-channel item on a stereo track at the same unity gain as a dual-mono 2-channel item (pan law, mono spread) — the null test's actual playback-chain property — is unconfirmed.
• Relative paths only in the persisted BankIndex.
• Capture FX scope: two scopes only — item = item/take FX only; track = item FX + the selected track's own track FX. There is no master scope (to capture the master, render a track instead). For both scopes, the out-of-scope chain (ancestors + master track, plus the item's own track for item scope) has its FX, gain, and pan/width/pan-law/mode neutralized to unity — the master track is bypassed as out-of-scope chain, not captured as a scope. Range (time selection or razor) is orthogonal.

The resample bake — the one crossing from instrument into bank

A click inside the ReaSampler 9000 editor bakes the dialed sound into a bank capture. The split is: the instrument renders, the extension banks. The instrument produces the audio on its own voice path in its own process (so the bake is the object code that made the sound the user approved, immune to engine-version skew between the two artifacts), stages it outside the bank folder, and invokes ONE extension action over the VST3 host bridge; the extension lands it and answers over the same per-instance key, synchronously, inside that call. Consequences that bind:

• The extension's link graph does not gain the voice engine. sampler_core / pitch_shift / the filter are NOT linked into reaper_reasampler — a link edge to any of them means the design drifted back to an extension-side render.
• No arrange mutation and no deletion. The bake writes a file plus an index entry, like every other capture. "Replace" means the bank entry now denotes the recapture; the superseded file survives on disk until a prune reclaims it — the iterate loop's recovery floor.
• The bake adds nothing to process(). It renders on the UI thread over a separate VoiceEngine, with the live-parameter block detached.

Non-goals / guardrails

• No auto-insertion of captures into the arrange (see the load-bearing principle).
• Do not depend on REAPER's peak API for thumbnails; compute from the captured file.
• Do not silently time-stretch on insert; conform is opt-in.
• Do not trust cited REAPER API names blindly — verify against the SDK header.