Retire the zone system: one capture = one parameter set, and re-seam the engine and Sample face into bands

2026-07-30 07:15:54 -04:00
parent a689fb75eb
commit 8d4ccbf841
61 changed files with 5416 additions and 8008 deletions
@@ -0,0 +1,155 @@
+#pragma once
+// play_params.h — the instrument's one set of playback-parameter value structs plus the
+// per-instance mode enums, shared by the engine, sample_map, the ComponentState codec, and
+// the editor. Split out of the engine headers so a UI/codec TU reading a param struct
+// doesn't recompile when a Voice/VoiceEngine member changes. The per-frame evaluators live
+// in envelopes.h; the engine in voice.h / voice_engine.h.
+
+#include <cstdint>
+#include <vector>
+
+#include "core/audio/peaks.h"
+#include "core/instrument/engine/velocity_curve.h"
+
+namespace reasampler {
+
+using audio::AudioSample;
+using instrument::engine::VelocityCurve;
+
+// Decode-side downmix policy (see root CLAUDE.md — the output bus itself is permanently
+// stereo; this only picks mono-downmix vs dual-mono at decode). Never written to the bank.
+enum class ChannelMode { Mono, Stereo };
+
+// POLY is the fixed-pool engine with bounded stealing; MONO is a single voice with last-note
+// priority over a held-note stack (a new note takes over; releasing the top note falls back to
+// the most-recent still-held one). Never a bank fact. Default Poly.
+enum class VoiceMode { Poly, Mono };
+
+// How a MONO takeover treats the envelopes. RETRIGGER restarts amp/pitch envelopes on every new
+// mono note. LEGATO keeps the envelope running across a takeover (pitch moves without a
+// re-attack). With one loaded capture every takeover is same-sample, so Legato always glides.
+enum class MonoTrigger { Retrigger, Legato };
+
+// Shared range so the engine, the component-state codec, and the editor control can't drift.
+inline constexpr int kMinVoiceCount = 1;
+inline constexpr int kMaxVoiceCount = 32;
+inline constexpr int kDefaultVoiceCount = 16;
+
+// AHDSR amplitude envelope. holdFrames == 0 is exactly the pre-hold-stage ADSR (back-compat).
+struct AdsrParams {
+    std::int64_t attackFrames  = 0;
+    std::int64_t holdFrames    = 0;
+    std::int64_t decayFrames   = 0;
+    double       sustainLevel  = 1.0;   // 0..1
+    std::int64_t releaseFrames = 0;
+};
+
+// GATE = classic held note (AHDSR + sustain loop + note-off release). TRIGGER = one-shot:
+// note-off-immune, no sustain loop, plays a % of sample length shaped by fade-in/out. Both
+// honor the start point. Default Gate so an instrument with no params set plays as before.
+enum class PlayMode { Gate, Trigger };
+
+// Playback covers [startFrame, playEnd), playEnd = startFrame +
+// round(lengthFraction*(frames - startFrame)). Amplitude ramps 0->1 over fadeInFrames at the
+// head and 1->0 over fadeOutFrames anchored to playEnd; unity between. Fades clamp so
+// fadeIn + fadeOut <= play length. The voice frees when the head reaches playEnd.
+struct TriggerParams {
+    double       lengthFraction = 1.0;  // (0,1] of the post-start span to play
+    std::int64_t fadeInFrames   = 0;
+    std::int64_t fadeOutFrames  = 0;
+};
+
+// EQUAL_POWER (constant-power sin/cos) is the click-free default for Trigger's ramps; LINEAR is
+// the build-time residual.
+enum class FadeCurve { EqualPower, Linear };
+inline constexpr FadeCurve kDefaultFadeCurve = FadeCurve::EqualPower;
+
+// VARISPEED: readPos_ += ratio_, pitch and duration coupled (an octave up plays half as long).
+// PRESERVE: the read advances at the source rate while a PitchShifter transposes the output
+// (an octave up keeps its length).
+enum class PitchEngine { Varispeed, Preserve };
+
+// Product default is Preserve, but applied at the state boundary (the codec's read path /
+// the editor's default params), NOT here: PlayParams.pitchEngine itself defaults to Varispeed
+// so "no params == the bare engine" holds for the core's own regression tests (an octave up
+// still halves duration with no params set).
+inline constexpr PitchEngine kDefaultPitchEngine = PitchEngine::Preserve;
+
+// OLA window for the Preserve PitchShifter, in ms at the voice's sample rate; larger = smoother
+// on big transpositions. Onset latency is zero — start() primes the ring with the first window
+// of real source, so output frame 0 is source frame 0 regardless of window size.
+inline constexpr double kPreserveWindowMs = 50.0;
+
+// AD pitch-modulation envelope, off by default (enabled=false -> offset always 0 -> bit-identical
+// to the un-modulated engine). At note-on the offset rises to peakSemitones over attackFrames,
+// then falls to 0 over decayFrames; a zero attack gives a pure percussive pitch drop.
+struct PitchEnvParams {
+    bool         enabled       = false;
+    std::int64_t attackFrames  = 0;
+    std::int64_t decayFrames   = 0;
+    double       peakSemitones = 0.0;  // signed depth at the peak
+};
+
+// Bundle a voice reads at start(). Defaults reproduce the bare engine (Gate, hold-0 AHDSR,
+// Varispeed, pitch envelope off) — core regression tests rely on this; the Preserve product
+// default is layered on at (de)serialization, see kDefaultPitchEngine.
+struct PlayParams {
+    PlayMode       playMode = PlayMode::Gate;
+    AdsrParams     adsr;
+    TriggerParams  trigger;
+    PitchEngine    pitchEngine = PitchEngine::Varispeed;
+    PitchEnvParams pitchEnv;
+};
+
+// [start, end) frames, half-open. A zero-length loop (start == end) is the "no sustain loop"
+// marker — a held note past the sample end goes silent rather than looping a zero span.
+struct SampleLoop {
+    bool hasLoop = false;
+    std::int64_t start = 0;
+    std::int64_t end   = 0;
+};
+
+// The one loaded capture the core plays: decoded PCM plus every parameter governing playback.
+// The shell decodes the on-disk WAV and fills this; the core never touches a file.
+//
+// Deinterleaved per-channel: `frames` is channel 0 (always present), `framesR` is channel 1
+// (present only for a stereo sample). Stereo iff `framesR` is non-empty and the same length as
+// `frames`; a mismatched length is treated as absent (mono) rather than half-playing. Both
+// channels share the read head / rootNote / loop, so repitch and loop stay per-frame identical
+// across channels. `rootNote` is the MIDI note the file was recorded at — unity ratio there.
+struct SampleData {
+    std::vector<AudioSample> frames;
+    std::vector<AudioSample> framesR;  // empty for a mono sample
+    int sampleRate = 0;                // ratio math is note-relative, so rate cancels for
+                                        // repitch; still, 0 is invalid — every consumer must
+                                        // receive a real rate before use.
+    int rootNote = 60;
+    SampleLoop loop;
+
+    // Frame offset a voice starts playback at; frame 0 default is the pre-existing behavior.
+    // Clamped into [0, frames) at note-on — a start >= sample length is a no-op (starts at 0).
+    std::int64_t startFrame = 0;
+
+    // How far keyboard pitch tracks the root: 1.0 = standard 12-tone-ET (default); 0.0 = no
+    // tracking (every key plays root pitch); 2.0 = double-rate. Scales the (note-root) semitone
+    // offset in keyTrackedRatio; rides both repitch engines via the voice's baseRatio_.
+    double keyTrack = 1.0;
+
+    // Maps note-on velocity (0..127) to the voice's amp gain, eval'd once in Voice::start
+    // (never per frame). Default flat y=1 — every velocity plays at unity.
+    VelocityCurve velocityCurve = VelocityCurve::flat();
+
+    PlayParams play;
+
+    // A framesR of a different length than frames is treated as absent — a malformed pair
+    // never half-plays.
+    int channelCount() const {
+        return (!framesR.empty() && framesR.size() == frames.size()) ? 2 : 1;
+    }
+
+    // Nothing decoded -> nothing to play; the engine refuses a note-on rather than starting a
+    // voice on an empty read span.
+    bool playable() const { return !frames.empty(); }
+};
+
+} // namespace reasampler