daniel
080a7be8ca
CC 120 -> allSoundsOff/hardStop (immediate silence, stops Trigger one-shots); CC 123 -> allNotesOff/releaseAll (release, unchanged). Mono VoiceEngine sizes voices_ to 1 structurally. Legato same-note re-press edge documented. Three new tests.
713 lines
43 KiB
C++
713 lines
43 KiB
C++
#pragma once
|
||
// sampler_core — the HEART of the Phase S MIDI-playback instrument (D3), deliberately
|
||
// free of any VST3 *and* any REAPER type so it compiles and unit-tests OUTSIDE the DAW
|
||
// and outside any plugin host. It owns the pure sampler engine: polyphonic voice
|
||
// allocation with bounded stealing, an ADSR amplitude envelope, a key/velocity keymap
|
||
// with (note, velocity) -> zone resolution, and repitch/interpolation from a root note
|
||
// with loop-point-aware sustain.
|
||
//
|
||
// PURE MODULE (CLAUDE.md §load-bearing split): NO VST3 types, NO REAPER types, NO SWELL,
|
||
// NO vendor/ includes, no include from either SDK. Standard library only. The VST3 shell
|
||
// (src/vst/reasampler_processor.cpp) marshals MIDI events + audio buffers to and from
|
||
// this core; the core never sees a VST3 ProcessData or a REAPER MediaTrack. Enforced
|
||
// structurally: sampler_core_tests links neither SDK (see CMakeLists §2i).
|
||
//
|
||
// It shares the `AudioSample` float alias from peaks — the one house precedent for a
|
||
// pure module leaning on peaks for the audio-domain type (wav_trim does the same). The
|
||
// S2 seam fields (root note, loop points) enter as plain int / frame-index inputs; the
|
||
// core does no file I/O — it is handed decoded sample frames and produces audio frames.
|
||
|
||
#include <array>
|
||
#include <cstddef>
|
||
#include <cstdint>
|
||
#include <vector>
|
||
|
||
#include "peaks.h" // AudioSample (float)
|
||
#include "pitch_shift.h" // PitchShifter (S16 Preserve engine DSP core)
|
||
#include "velocity_curve.h" // VelocityCurve (S-VIEW-9 velocity->amp transfer curve; eval at start)
|
||
|
||
namespace reasampler {
|
||
|
||
// The instrument's per-instance output channel mode (S7, D-E). MONO keeps the pre-S7
|
||
// downmix path (one channel out); STEREO negotiates a 2-channel output bus and renders
|
||
// per-channel. A PERFORMANCE choice the instrument owns (component state), never written
|
||
// to the bank. Default Mono preserves current behavior. Lives in the pure core as a plain
|
||
// value so the shell (bus negotiation, state) and the engine share one spelling; the core
|
||
// itself never branches on it — the mode only picks which render overload the shell drives.
|
||
enum class ChannelMode { Mono, Stereo };
|
||
|
||
// The instrument's per-instance VOICE MODE (Phase S voice redesign). POLY is today's
|
||
// polyphonic engine (fixed pool + bounded stealing); MONO is a single voice with LAST-NOTE
|
||
// priority over a held-note stack (classic mono synth: a new note takes the voice over; the
|
||
// release of the top note falls back to the most-recent still-held note). A PERFORMANCE
|
||
// choice the instrument owns (component state), never a bank fact. Default Poly preserves
|
||
// current behavior.
|
||
enum class VoiceMode { Poly, Mono };
|
||
|
||
// How a MONO takeover treats the envelopes (Phase S — Daniel: explicitly toggleable).
|
||
// RETRIGGER restarts the amplitude (and pitch) envelope on every new mono note. LEGATO keeps
|
||
// the envelope running when a note is taken over while another is held — pitch moves without
|
||
// a re-attack (and the fallback on top-note release glides back the same way). Legato applies
|
||
// only to a SAME-SAMPLE takeover: crossing into a zone playing a different sample restarts
|
||
// the voice (one read head cannot glide between two PCM streams; a re-attack on a sample
|
||
// change is the deterministic, documented fallback). Meaningless in Poly. Default Retrigger.
|
||
enum class MonoTrigger { Retrigger, Legato };
|
||
|
||
// The user-parameterized polyphony bound (Phase S): a per-instance persisted voice count.
|
||
// One spelling shared by the engine, the component-state (de)serializer, and the editor's
|
||
// control so the range can never drift apart. Default 16 == the pre-Phase-S fixed pool.
|
||
inline constexpr int kMinVoiceCount = 1;
|
||
inline constexpr int kMaxVoiceCount = 32;
|
||
inline constexpr int kDefaultVoiceCount = 16;
|
||
|
||
// ---------------------------------------------------------------------------
|
||
// S15/S16 per-zone play PARAMETERS (plain data). Defined up here (before SampleData) because
|
||
// SampleData carries a ZonePlayParams by value — a voice reads it at start(). The matching
|
||
// per-frame EVALUATOR classes (AHDSR AdsrEnvelope, TriggerEnvelope, PitchEnvelope) live lower
|
||
// with the rest of the engine machinery; only the value structs need to precede SampleData.
|
||
// ---------------------------------------------------------------------------
|
||
|
||
// AHDSR amplitude envelope parameters (S15 grows the S3 ADSR with a HOLD stage between Attack
|
||
// and Decay). holdFrames == 0 is EXACTLY the pre-S15 ADSR (back-compat). See AdsrEnvelope below.
|
||
struct AdsrParams {
|
||
std::int64_t attackFrames = 0;
|
||
std::int64_t holdFrames = 0; // S15: hold at 1.0 between Attack and Decay; 0 = pre-S15 ADSR
|
||
std::int64_t decayFrames = 0;
|
||
double sustainLevel = 1.0; // 0..1
|
||
std::int64_t releaseFrames = 0;
|
||
};
|
||
|
||
// S15 play mode. GATE = classic held note (AHDSR + sustain loop + note-off release, today's
|
||
// behavior grown by the hold stage). TRIGGER = one-shot: note-off-immune, no sustain loop,
|
||
// plays a % of the sample length shaped by fade-in/out. Both honor the start point. Per-zone
|
||
// (D-B); DEFAULT Gate so an instrument with no S15 params plays exactly as before.
|
||
enum class PlayMode { Gate, Trigger };
|
||
|
||
// Trigger amplitude envelope parameters (S15). Playback covers the source-frame span
|
||
// [startFrame, playEnd), playEnd = startFrame + round(lengthFraction*(frames - startFrame)),
|
||
// lengthFraction in (0,1]. 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. Note-off is a no-op in Trigger.
|
||
struct TriggerParams {
|
||
double lengthFraction = 1.0; // (0,1] of the post-start span to play
|
||
std::int64_t fadeInFrames = 0; // 0->1 ramp at the head
|
||
std::int64_t fadeOutFrames = 0; // 1->0 ramp anchored to playEnd
|
||
};
|
||
|
||
// The fade curve for Trigger's ramps. EQUAL_POWER (constant-power sin/cos) is the default
|
||
// (click-free on one-shots, per spec); LINEAR is the build-time residual. An enum (not a bool)
|
||
// so a third curve can join without a signature change.
|
||
enum class FadeCurve { EqualPower, Linear };
|
||
|
||
// The DEFAULT fade curve (S15 spec: equal-power). One constant to flip if linear is wanted.
|
||
inline constexpr FadeCurve kDefaultFadeCurve = FadeCurve::EqualPower;
|
||
|
||
// The per-zone pitch engine. VARISPEED = today's path (readPos_ += ratio_): pitch and duration
|
||
// coupled (an octave up plays half as long). PRESERVE = duration-preserving: the read advances
|
||
// at the SOURCE rate while a PitchShifter transposes the output (an octave up keeps its length).
|
||
enum class PitchEngine { Varispeed, Preserve };
|
||
|
||
// The PRODUCT DEFAULT pitch engine (S16-F1 — Daniel's "I want duration-preserving repitching"
|
||
// directive). ONE constant to flip if Varispeed should be the default instead. This is the
|
||
// default a NEW or absent-in-the-blob zone gets — APPLIED AT THE STATE BOUNDARY (sample_map's
|
||
// deserialize / editor zone-creation), NOT the pure-core struct default. The pure-core
|
||
// ZonePlayParams.pitchEngine member defaults to VARISPEED so that "no params == the pre-S16
|
||
// engine" holds for the core's own regression tests (an octave up still halves duration in the
|
||
// bare engine); the Preserve product default is layered on above at (de)serialization.
|
||
inline constexpr PitchEngine kDefaultPitchEngine = PitchEngine::Preserve;
|
||
|
||
// The OLA window (frames) the Preserve PitchShifter uses, derived from a window in milliseconds
|
||
// at the voice's sample rate. ~50 ms is the WDL quality-0 window the spec cites; larger =
|
||
// smoother on big transpositions, more onset latency. One knob, resolved at voice allocation.
|
||
inline constexpr double kPreserveWindowMs = 50.0;
|
||
|
||
// A per-voice AD pitch-modulation envelope (S16), OFF by default (enabled=false -> offset always
|
||
// 0 -> playback bit-identical to the un-modulated engine). At note-on the pitch offset rises to
|
||
// peakSemitones over attackFrames, then falls to 0 (base pitch) over decayFrames. A zero attack
|
||
// gives the pure "start high, drop to base" percussive drop. peakSemitones is signed (+/-).
|
||
struct PitchEnvParams {
|
||
bool enabled = false;
|
||
std::int64_t attackFrames = 0;
|
||
std::int64_t decayFrames = 0;
|
||
double peakSemitones = 0.0; // signed depth at the peak
|
||
};
|
||
|
||
// The bundle of S15/S16 per-zone play parameters a voice reads at start(). Lives on SampleData
|
||
// (each zone owns one SampleData in the zoned keymap). DEFAULTS are EXACTLY the pre-S15/S16
|
||
// engine: Gate mode, AHDSR with hold 0 (= the S3 ADSR), VARISPEED pitch engine, pitch envelope
|
||
// disabled — so a bare-core voice with default play is byte-identical to the pre-S15 build (the
|
||
// core regression tests rely on this). The PRODUCT default of Preserve (S16-F1) is applied one
|
||
// layer up at (de)serialization for new/absent zones — see kDefaultPitchEngine.
|
||
struct ZonePlayParams {
|
||
PlayMode playMode = PlayMode::Gate;
|
||
AdsrParams adsr; // Gate: the AHDSR envelope
|
||
TriggerParams trigger; // Trigger: %-length + fades
|
||
PitchEngine pitchEngine = PitchEngine::Varispeed;
|
||
PitchEnvParams pitchEnv; // AD pitch modulation, off by default
|
||
};
|
||
|
||
// ---------------------------------------------------------------------------
|
||
// Sample data the core plays. Plain, decoded PCM + the S2 bank intrinsics that
|
||
// govern playback. The shell decodes the on-disk WAV and fills this; the core
|
||
// never touches a file.
|
||
// ---------------------------------------------------------------------------
|
||
|
||
// A loop over [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. absent-loop is modeled by leaving hasLoop false.
|
||
struct SampleLoop {
|
||
bool hasLoop = false;
|
||
std::int64_t start = 0; // first looped frame (inclusive)
|
||
std::int64_t end = 0; // one-past-last looped frame (exclusive); start <= end
|
||
};
|
||
|
||
// One decoded audio sample the engine can voice. DEINTERLEAVED, per-channel: `frames` is
|
||
// channel 0 (always present) and `framesR` is channel 1 (present only for a STEREO sample).
|
||
// A sample is stereo iff `framesR` is non-empty AND the same length as `frames`; otherwise
|
||
// it is mono (the degenerate, byte-identical Tier 0-1 case — `framesR` stays empty). Both
|
||
// channels share `readPos_`, `rootNote`, and `loop`, so repitch/loop are per-frame identical
|
||
// across channels; only the sampled value differs. `rootNote` is the MIDI note the file was
|
||
// recorded at (S2 intrinsic) — the pitch that plays back at unity ratio.
|
||
struct SampleData {
|
||
std::vector<AudioSample> frames; // channel 0 PCM (mono, or L of a stereo sample)
|
||
std::vector<AudioSample> framesR; // channel 1 PCM (R); EMPTY for a mono sample
|
||
int sampleRate = 0; // frames per second (for reference; ratio is
|
||
// note-relative, so rate cancels for repitch).
|
||
// 0 is explicitly invalid — every consumer must
|
||
// receive a real rate before use.
|
||
int rootNote = 60; // MIDI note recorded at (plays at unity here)
|
||
SampleLoop loop; // sustain loop, if any
|
||
// Initial read position (frame offset) a voice starts playback at — frame 0 by
|
||
// default, so an unset start point is exactly the pre-S11 behavior. S11 makes this
|
||
// an instrument-side per-zone override (the "start point" marker); S15 builds on it
|
||
// (both play modes carry a modifiable start). Clamped into [0, frames) at note-on:
|
||
// a start >= the sample length is a no-op (voice starts at 0), never out of bounds.
|
||
std::int64_t startFrame = 0;
|
||
|
||
// S15/S16 per-zone play parameters (play mode, AHDSR/Trigger envelope, pitch engine, pitch
|
||
// envelope). Defaults reproduce the pre-S15 engine EXCEPT the pitch engine default is
|
||
// Preserve (S16-F1). A voice reads this at start(). Struct defined above SampleData.
|
||
ZonePlayParams play;
|
||
|
||
// 2 iff a matching-length second channel exists; else 1. A framesR of a different
|
||
// length than frames is treated as absent (mono) — a malformed pair never half-plays.
|
||
int channelCount() const {
|
||
return (!framesR.empty() && framesR.size() == frames.size()) ? 2 : 1;
|
||
}
|
||
|
||
};
|
||
|
||
// ---------------------------------------------------------------------------
|
||
// Keymap — the performance map (instrument-owned, D-B). A note+velocity resolves
|
||
// to at most one zone; a zone names which SampleData to play and the root note to
|
||
// repitch from. Tier-0 degenerate case: a single zone spanning [0,127] with the
|
||
// sample's own root. Tier-1: several zones, each a key range with its own root.
|
||
//
|
||
// TIER-2 EXTENSION (velocity layers / round-robin) — designed for, not built:
|
||
// resolution returns a zone; a zone today owns one sampleIndex. Tier 2 makes a zone
|
||
// own a *list* of (velocity-range, sampleIndex) layers (and round-robin sets), and
|
||
// resolve() gains the velocity dimension it already receives but currently ignores
|
||
// for selection. The (note, velocity) signature and the "resolve to a zone, then a
|
||
// sample within it" shape are already in place — Tier 2 fills in the second step
|
||
// without changing callers or the voice engine. See the report note.
|
||
// ---------------------------------------------------------------------------
|
||
|
||
// A key range [lowNote, highNote] (inclusive both ends) mapping to one sample, with
|
||
// the root note to repitch from (defaults to the sample's own root, overridable in
|
||
// the performance map per S5). velocityLow/High reserved for Tier-2 layers; today a
|
||
// zone accepts the full 1..127 velocity range (0 is note-off by MIDI convention).
|
||
struct KeyZone {
|
||
int lowNote = 0;
|
||
int highNote = 127;
|
||
int rootNote = 60; // repitch reference for this zone
|
||
// S-VIEW-6 key-tracking scalar: how far keyboard pitch tracks the root. 1.0 (100%) is
|
||
// standard 12-tone-ET (default; bit-identical to pre-S-VIEW-6); 0.0 = no tracking (every
|
||
// key plays root pitch); 2.0 = double-rate tracking. Scales the (note-root) semitone offset
|
||
// in the repitch math (keyTrackedRatio); rides BOTH engines via the voice's baseRatio_.
|
||
double keyTrack = 1.0;
|
||
// S-VIEW-9 velocity->amp transfer curve: maps the note-on velocity (0..127) to the voice's amp
|
||
// gain, replacing the fixed linear velocity/127. A per-zone performance characteristic (mirror
|
||
// of keyTrack), carried from PerformanceZone by resolvePerformance and eval'd ONCE in
|
||
// Voice::start (never per frame). DEFAULT flat y=1 (R10-F1 Option A) — every velocity plays at
|
||
// unity, a deliberate behavior change from the pre-r10 linear map.
|
||
vst::VelocityCurve velocityCurve = vst::VelocityCurve::flat();
|
||
std::size_t sampleIndex = 0; // index into Keymap::samples
|
||
};
|
||
|
||
// Result of resolving a (note, velocity). `matched == false` means the note falls in
|
||
// no zone (out-of-zone) — a defined no-play result, NOT an error and NOT voice 0.
|
||
struct ZoneResolution {
|
||
bool matched = false;
|
||
std::size_t zoneIndex = 0; // valid only when matched
|
||
};
|
||
|
||
// The keymap: the decoded samples plus the zones that map keys onto them. Owns
|
||
// resolution. Pure: no host types. Zones are tested first-match in order, so an
|
||
// earlier zone wins an overlap (deterministic, documented).
|
||
struct Keymap {
|
||
std::vector<SampleData> samples;
|
||
std::vector<KeyZone> zones;
|
||
|
||
// Resolves (note, velocity) to a zone. First zone (in order) whose [low,high]
|
||
// contains `note` wins. velocity is accepted now (Tier-2 seam) but does not
|
||
// affect zone choice at Tier 0-1. Returns {matched=false} when no zone contains
|
||
// the note.
|
||
ZoneResolution resolve(int note, int velocity) const;
|
||
|
||
// Convenience: build the Tier-0 degenerate keymap — one sample mapped
|
||
// chromatically across the whole keyboard from its own root note.
|
||
static Keymap singleSampleChromatic(SampleData sample);
|
||
};
|
||
|
||
// The chromatic pitch ratio to play `note` given a sample recorded at `rootNote`:
|
||
// 2^((note - rootNote) / 12). note == rootNote -> 1.0 (unity). One octave up -> 2.0,
|
||
// one octave down -> 0.5. Pure equal-temperament; no reference-frequency needed.
|
||
double pitchRatio(int note, int rootNote);
|
||
|
||
// The key-tracked pitch ratio (S-VIEW-6): 2^(((note - rootNote) * keyTrack) / 12). The
|
||
// keyTrack scalar scales the semitone offset before the ET conversion, so it governs how
|
||
// far playback pitch tracks the keyboard around the root:
|
||
// keyTrack == 1.0 -> standard 12-tone-ET (BIT-IDENTICAL to pitchRatio(note, rootNote) —
|
||
// (note-root)*1.0 is exact in IEEE-754, feeding the same std::pow call).
|
||
// keyTrack == 0.0 -> no tracking: every key plays the root pitch (ratio 1.0 for all notes).
|
||
// keyTrack == 2.0 -> double-rate tracking: each key is twice as far from the root in pitch.
|
||
// At the root note the offset is 0 regardless of keyTrack, so the root always plays at unity.
|
||
// Pure; both repitch engines (Varispeed read-rate, Preserve shift-amount) derive from it via
|
||
// the voice's baseRatio_.
|
||
double keyTrackedRatio(int note, int rootNote, double keyTrack);
|
||
|
||
// ---------------------------------------------------------------------------
|
||
// AHDSR amplitude envelope (S15 grows the S3 ADSR with a HOLD stage). Sample-based
|
||
// (times in frames), linear segments. A gate: noteOn() enters Attack; noteOff() enters
|
||
// Release from wherever it is. Asserted against a known signal in the tests (mirror of peaks).
|
||
//
|
||
// Segment math (all linear ramps):
|
||
// Attack: 0 -> 1 over attackFrames
|
||
// Hold: hold 1 over holdFrames (S15: NEW stage between A and D)
|
||
// Decay: 1 -> sustainLevel over decayFrames
|
||
// Sustain: hold sustainLevel until noteOff
|
||
// Release: currentLevel -> 0 over releaseFrames
|
||
// A zero-length attack jumps straight to 1 on the first frame; HOLDFRAMES == 0 skips Hold
|
||
// entirely, which is EXACTLY the pre-S15 ADSR (back-compat — existing Gate play is unchanged);
|
||
// zero decay jumps to sustain; a noteOff during attack/hold/decay (release-before-sustain)
|
||
// releases from the current partial level, not from sustainLevel. AdsrParams is defined above
|
||
// (with the other per-zone value structs); this section holds only the per-frame evaluator.
|
||
// ---------------------------------------------------------------------------
|
||
|
||
class AdsrEnvelope {
|
||
public:
|
||
enum class Stage { Idle, Attack, Hold, Decay, Sustain, Release, Finished };
|
||
|
||
void configure(const AdsrParams& params) { params_ = params; }
|
||
|
||
// Gate on: (re)start from Attack.
|
||
void noteOn();
|
||
// Gate off: enter Release from the current level.
|
||
void noteOff();
|
||
|
||
// Advances one frame and returns the amplitude for THIS frame (before advancing).
|
||
// Once Release completes the envelope latches Finished and returns 0.0 forever
|
||
// (until the next noteOn). A single, monotonic per-frame step — the caller pulls
|
||
// one value per output frame.
|
||
double tick();
|
||
|
||
Stage stage() const { return stage_; }
|
||
bool finished() const { return stage_ == Stage::Finished; }
|
||
double level() const { return level_; }
|
||
|
||
private:
|
||
AdsrParams params_;
|
||
Stage stage_ = Stage::Idle;
|
||
double level_ = 0.0;
|
||
std::int64_t framesInStage_ = 0;
|
||
double releaseFrom_ = 0.0; // level at the moment noteOff() was called
|
||
};
|
||
|
||
// ---------------------------------------------------------------------------
|
||
// S15 Trigger amplitude envelope (per-frame evaluator). The PlayMode / TriggerParams /
|
||
// FadeCurve value structs are defined above with the other per-zone params.
|
||
// ---------------------------------------------------------------------------
|
||
|
||
// Trigger amplitude envelope: a stateless-shape amplitude function over the play span, evaluated
|
||
// at a SOURCE-frame offset into the span. Anchoring the fades to SOURCE frames (not output
|
||
// frames) is what makes S15 compose with S16: under Preserve the read advances at source rate so
|
||
// output and source frames coincide, but under Varispeed a transposed voice consumes source
|
||
// faster — driving the fades off the read position keeps the fade-in/out anchored to the SAME
|
||
// source frames regardless of engine (the play-length end is a source-frame fact, S15×S16). The
|
||
// voice reports the read offset; this maps it to amplitude. Distinct from AHDSR — time-boxed by
|
||
// the play length and note-off-immune. Reports finished() once the offset reaches the play length.
|
||
class TriggerEnvelope {
|
||
public:
|
||
// Configure from the play span + fades. `playLengthFrames` is (playEnd - startFrame): the
|
||
// SOURCE-frame length of the play span. Fades are clamped so fadeIn + fadeOut <= playLength
|
||
// (fadeOut anchored to the end). A zero/negative play length finishes immediately.
|
||
void configure(std::int64_t playLengthFrames, std::int64_t fadeInFrames,
|
||
std::int64_t fadeOutFrames, FadeCurve curve = kDefaultFadeCurve);
|
||
|
||
// Amplitude in [0,1] at `sourceOffset` = (readPos - startFrame) source frames into the play
|
||
// span. Latches finished() once the offset reaches the play length (>= playLength). Pure over
|
||
// the offset (no internal advance) so it composes with either pitch engine's read rate.
|
||
double amplitudeAt(double sourceOffset);
|
||
|
||
bool finished() const { return finished_; }
|
||
|
||
private:
|
||
std::int64_t playLength_ = 0;
|
||
std::int64_t fadeIn_ = 0;
|
||
std::int64_t fadeOut_ = 0;
|
||
FadeCurve curve_ = kDefaultFadeCurve;
|
||
bool finished_ = false;
|
||
};
|
||
|
||
// ---------------------------------------------------------------------------
|
||
// S16 pitch envelope (per-frame evaluator). The PitchEngine / PitchEnvParams value structs
|
||
// and the kDefaultPitchEngine / kPreserveWindowMs constants are defined above.
|
||
// ---------------------------------------------------------------------------
|
||
|
||
// Per-frame AD pitch-envelope evaluator. tick() returns the CURRENT pitch offset in semitones
|
||
// (0 when disabled or past attack+decay), advancing one frame. The voice converts the semitone
|
||
// offset to a ratio multiply (Varispeed) or a shift-amount add (Preserve). Pure, unit-tested
|
||
// for offset at t=0, peak at t=attack, and 0 at t=attack+decay.
|
||
class PitchEnvelope {
|
||
public:
|
||
void configure(const PitchEnvParams& params) { params_ = params; pos_ = 0; }
|
||
void noteOn() { pos_ = 0; }
|
||
|
||
// Advance one frame, return this frame's pitch offset in semitones.
|
||
double tick();
|
||
|
||
private:
|
||
PitchEnvParams params_;
|
||
std::int64_t pos_ = 0;
|
||
};
|
||
|
||
// ---------------------------------------------------------------------------
|
||
// A single voice: one active note playing one repitched, enveloped sample. Reads
|
||
// the sample by fractional frame position with linear interpolation, advancing by
|
||
// the pitch ratio; loops the sustain region for held notes past the loop end.
|
||
// ---------------------------------------------------------------------------
|
||
|
||
class Voice {
|
||
public:
|
||
// Starts this voice on `note` at `velocity`, playing `sample` (a stable reference
|
||
// the caller must keep alive for the voice's lifetime — the Keymap owns it), repitched
|
||
// from `rootNote`. All five AHDSR fields (A/H/D/S/R) are read directly from
|
||
// sample.play.adsr — the per-zone values (in FRAMES) resolved from the stored seconds by
|
||
// buildTier0Keymap / buildZonedKeymap against the live sample rate. The S15 play MODE +
|
||
// Trigger params and the S16 pitch ENGINE + pitch envelope are read from `sample.play`.
|
||
// The Preserve shifters MUST already be pre-sized (presizePreserveShifters, off-thread) —
|
||
// start() only reset()s + warm()s them (RT-safe, no allocation) since it runs on the audio
|
||
// thread inside process(). The warm silence pass settles the OLA taps before the first
|
||
// output frame (no cold-start click). Byte-identical to the pre-S15 engine when sample.play
|
||
// is default (Gate + Varispeed + no pitch env).
|
||
// `keyTrack` (S-VIEW-6) scales the (note-root) semitone offset feeding the repitch ratio;
|
||
// 1.0 (the default) is standard 12-tone-ET, bit-identical to the pre-S-VIEW-6 baseRatio_.
|
||
// `velocityCurve` (S-VIEW-9) maps the note-on velocity to the voice's amp gain, evaluated ONCE
|
||
// here (off the per-frame path); defaults to flat y=1 (R10-F1) — every velocity plays at unity.
|
||
// `unityVarispeedBypass` (Phase S, re-scoping FA1): when TRUE, a Preserve voice started at
|
||
// UNITY shift (baseRatio_ == 1.0, pitch env off) is demoted to the Varispeed read path — at
|
||
// unity the two engines are byte-identical except the OLA shifter's structural half-window
|
||
// onset delay, which buys nothing when there is no shift to preserve duration against. The
|
||
// PREVIEW card opts in (it fires at the root, so this is its zero-added-latency path); the
|
||
// MIDI VoiceEngine does NOT (default false) — a chromatic line must not step ~25 ms faster
|
||
// at the root note than one semitone away (the FA1-review timing-step finding).
|
||
void start(int note, int velocity, const SampleData& sample, int rootNote,
|
||
double keyTrack = 1.0,
|
||
const vst::VelocityCurve& velocityCurve = vst::VelocityCurve::flat(),
|
||
bool unityVarispeedBypass = false);
|
||
|
||
// MONO LEGATO takeover (Phase S): re-pitch this ACTIVE voice to `note` without touching the
|
||
// amplitude envelope, the read position, or the shifter state — pitch moves, no re-attack.
|
||
// Both engines pick the new baseRatio_ up on the next frame (Varispeed via the read rate,
|
||
// Preserve via the per-frame setShiftRatio). No-op on an idle voice. The caller guarantees
|
||
// the voice is playing the SAME SampleData the (note-resolved) zone names — a cross-sample
|
||
// takeover must restart the voice instead (see MonoTrigger).
|
||
void retune(int note, int rootNote, double keyTrack = 1.0);
|
||
|
||
// Gate off — begins the amplitude release. In GATE mode this enters the AHDSR release; in
|
||
// TRIGGER mode it is a NO-OP (Trigger ignores note-off and plays through to its play length).
|
||
void release();
|
||
|
||
// HARD STOP — CC 120 (All Sounds Off) semantics. Immediately silences this voice regardless
|
||
// of play mode: sets active_ = false with no release ramp. Stops a ringing Trigger one-shot
|
||
// instantly (which release() cannot do). RT-safe: no allocation, no lock.
|
||
void hardStop();
|
||
|
||
// True while this voice is producing (or about to produce) sound.
|
||
bool active() const { return active_; }
|
||
// The note this voice was started on (for note-off routing). Meaningless if idle.
|
||
int note() const { return note_; }
|
||
// Monotonic age counter — higher = started earlier relative to others. The voice
|
||
// engine uses this for its stealing policy (oldest first). Set by the engine.
|
||
std::uint64_t startOrder() const { return startOrder_; }
|
||
void setStartOrder(std::uint64_t order) { startOrder_ = order; }
|
||
bool releasing() const { return releasing_; }
|
||
// The S16 pitch engine this voice is running (for the engine's Preserve-voice tally). Only
|
||
// meaningful while active(). NOTE (Phase S re-scope of FA1): the unity-shift demotion to
|
||
// Varispeed is now OPT-IN via start()'s unityVarispeedBypass — only the preview card takes
|
||
// it; a MIDI Preserve voice keeps its shifter at every note so a chromatic line has one
|
||
// uniform onset (no ~25 ms step at the root).
|
||
PitchEngine pitchEngine() const { return pitchEngine_; }
|
||
// The SampleData this voice is playing (nullptr when never started). The engine's mono
|
||
// legato path compares it against the new note's resolved sample — a same-sample takeover
|
||
// retunes; a cross-sample one restarts. Identity only; callers never mutate through it.
|
||
const SampleData* playingSample() const { return sample_; }
|
||
|
||
// Pre-SIZE this voice's Preserve pitch shifters (both channels) to `windowFrames`, OFF the
|
||
// audio thread (this allocates). The engine calls it once at construction so start() — which
|
||
// runs on the audio thread inside process() — never allocates: start() only reset()s + warm()s
|
||
// the already-sized rings. `windowFrames` <= 1 leaves the shifters as pass-through (Varispeed
|
||
// instruments pay no ring cost). Idempotent: a re-presize to the same window is a cheap no-op
|
||
// in the underlying vector.
|
||
void presizePreserveShifters(std::int64_t windowFrames);
|
||
|
||
// Renders one frame's contribution, advancing the read head and envelope by one
|
||
// output frame. Returns 0.0 (and goes idle) once the envelope finishes or the
|
||
// sample runs out with no loop. The value is already velocity- and
|
||
// envelope-scaled — the engine sums voices directly. This is the MONO path (channel
|
||
// 0 only) — byte-identical to the pre-S7 engine, so mono play is unchanged.
|
||
AudioSample renderFrame();
|
||
|
||
// STEREO render: writes THIS frame's per-channel contribution into `l`/`r` and advances
|
||
// the read head + envelope by exactly one frame (the same single advance the mono path
|
||
// performs — the envelope ticks ONCE per frame, shared across both channels). For a mono
|
||
// sample (channelCount()==1) both `l` and `r` receive the same value (dual-mono / centered).
|
||
// Both outputs are already velocity- and envelope-scaled. Goes idle on the same conditions
|
||
// as the mono path (envelope finished / sample exhausted with no loop) writing 0 to both.
|
||
void renderFrameStereo(AudioSample& l, AudioSample& r);
|
||
|
||
private:
|
||
// Shared read/advance for both render paths: computes the interpolated per-channel
|
||
// value(s) at the current read head, ticks the amplitude + pitch envelopes once, applies
|
||
// the pitch engine (Varispeed read-rate bias OR Preserve shift), advances the head, and
|
||
// latches idle on exhaustion. `stereo` selects whether the second channel is read (and
|
||
// returned in `outR`); when false `outR` is left untouched. Returns the channel-0 value.
|
||
AudioSample advanceFrame(bool stereo, AudioSample& outR);
|
||
|
||
// This frame's amplitude in [0,1] from the active envelope. GATE: the AHDSR ticks once per
|
||
// output frame (independent of the read rate — envelope time is wall-clock). TRIGGER: the
|
||
// fade shape is evaluated at the SOURCE offset (readPos - startFrame) so the fades anchor to
|
||
// source frames and compose with either pitch engine. Sets amplitudeDone_ when the envelope
|
||
// finishes (Gate: release complete; Trigger: play length reached) so advanceFrame frees the voice.
|
||
double tickAmplitude();
|
||
|
||
bool active_ = false;
|
||
bool releasing_ = false;
|
||
int note_ = 0;
|
||
double velocityGain_ = 1.0;
|
||
double baseRatio_ = 1.0; // 2^((note-root)/12): the un-modulated repitch ratio
|
||
double ratio_ = 1.0; // fractional SOURCE frames advanced per output frame (this frame)
|
||
double readPos_ = 0.0; // fractional frame index into the sample
|
||
const SampleData* sample_ = nullptr;
|
||
|
||
// S15 play mode + amplitude envelopes. Gate uses env_ (AHDSR); Trigger uses trigEnv_. Only
|
||
// one is active per voice (selected by playMode_ at start). playEnd_ is Trigger's source-frame
|
||
// stop (the voice frees when readPos_ >= playEnd_, mirroring the run-off-end idle).
|
||
PlayMode playMode_ = PlayMode::Gate;
|
||
AdsrEnvelope env_;
|
||
TriggerEnvelope trigEnv_;
|
||
std::int64_t startFrame_ = 0; // clamped initial read frame; Trigger fade offset origin
|
||
std::int64_t playEnd_ = 0; // Trigger: source-frame end; Gate: unused
|
||
bool amplitudeDone_ = false; // set when the active amplitude envelope finished
|
||
|
||
// S16 pitch engine + pitch envelope. pitchEngine_ selects Varispeed (ratio bias) vs Preserve
|
||
// (source-rate read + shifter). shiftL_/shiftR_ transpose the Preserve output per channel
|
||
// (one read head, per-channel shift — S7 compose). pitchEnv_ rides EITHER engine.
|
||
PitchEngine pitchEngine_ = PitchEngine::Varispeed;
|
||
PitchEnvelope pitchEnv_;
|
||
PitchShifter shiftL_;
|
||
PitchShifter shiftR_;
|
||
|
||
std::uint64_t startOrder_ = 0;
|
||
};
|
||
|
||
// ---------------------------------------------------------------------------
|
||
// The polyphonic voice engine: a fixed pool of voices, note-on allocation with
|
||
// bounded voice stealing, note-off routing, and block rendering (sum of voices).
|
||
//
|
||
// VOICE-STEALING POLICY (deterministic, documented): when all voices are busy and a
|
||
// new note-on arrives, steal in this priority order:
|
||
// 1. the oldest voice already in RELEASE (finishing anyway — cheapest to cut),
|
||
// 2. else the oldest voice overall (longest-held note gives way to the new one).
|
||
// "Oldest" = smallest startOrder (assigned monotonically at note-on). This is the
|
||
// standard hardware-sampler policy: prefer to sacrifice a dying tail, and failing
|
||
// that, the note that has already had the most time.
|
||
// ---------------------------------------------------------------------------
|
||
|
||
class VoiceEngine {
|
||
public:
|
||
// Builds an engine with `maxVoices` voices (the polyphony bound) playing from
|
||
// `keymap`. The keymap must outlive the engine (the engine holds a reference — it
|
||
// reads zones and sample data through it, never copies PCM). Every AHDSR field (A/H/D/S/R)
|
||
// + play mode + pitch engine rides on each zone's SampleData::play (in FRAMES, resolved
|
||
// from the stored seconds at keymap build); the engine holds no instrument-wide ADSR.
|
||
// `preserveVoiceCap` (S16) bounds how many Preserve-engine voices may sound at once (the
|
||
// shifter is materially heavier than Varispeed) — a Preserve note-on beyond the cap is
|
||
// dropped rather than glitching; 0 means "no separate Preserve cap" (bounded only by
|
||
// maxVoices). `preserveWindowFrames` is the OLA window (in OUTPUT frames) every voice's
|
||
// Preserve pitch shifters are PRE-SIZED to at construction (OFF the audio thread), so
|
||
// note-on (which runs in process()) never allocates; 0 leaves them pass-through (a
|
||
// Varispeed-only instrument pays no ring cost). The processor derives it from the host
|
||
// sample rate (kPreserveWindowMs). Defaulted so existing callers (and the pure-core tests)
|
||
// are unaffected.
|
||
//
|
||
// `voiceMode` (Phase S): POLY is the pool-with-stealing engine above; MONO drives a single
|
||
// voice (voices_[0]) with last-note priority over the held-note stack, per `monoTrigger`
|
||
// (Retrigger restarts the envelopes on every takeover/fallback; Legato retunes a same-sample
|
||
// takeover without a re-attack). Both default to today's behavior (Poly / Retrigger). The
|
||
// engine's config is immutable — a mode/count change rebuilds the engine off-thread through
|
||
// the processor's drain-slot reload, so ringing tails survive the swap.
|
||
VoiceEngine(std::size_t maxVoices, const Keymap& keymap,
|
||
std::size_t preserveVoiceCap = 0, std::int64_t preserveWindowFrames = 0,
|
||
VoiceMode voiceMode = VoiceMode::Poly,
|
||
MonoTrigger monoTrigger = MonoTrigger::Retrigger);
|
||
|
||
// MIDI note-on. Resolves the note+velocity to a zone; if none matches (out of
|
||
// zone) it is a defined no-op (no voice consumed). Otherwise allocates a free
|
||
// voice, or steals one per the policy above. Returns the index of the voice used,
|
||
// or kNoVoice for an out-of-zone (unplayed) note.
|
||
std::size_t noteOn(int note, int velocity);
|
||
|
||
// MIDI note-off. Releases the most-recently-started active, non-releasing voice
|
||
// playing `note` (so a re-triggered same note releases the newest first, leaving
|
||
// the older tail to ring — matches hardware behavior). No-op if none match.
|
||
void noteOff(int note);
|
||
|
||
// CC 123 — MIDI All-Notes-Off: clears the MONO held stack and RELEASES every active voice
|
||
// (Gate voices enter their AHDSR release tail; Trigger one-shots ignore release and play
|
||
// through their bounded play length). This is the mono stack's ONLY reset path — a phantom
|
||
// entry left by a lost note-off would otherwise be resurrected by the fallback and sustain
|
||
// forever with no key held. RT-safe (no allocation, bounded by maxVoices).
|
||
void allNotesOff();
|
||
|
||
// CC 120 — MIDI All-Sounds-Off: hard-stops EVERY voice immediately (active_ = false, no
|
||
// release ramp), clears the MONO held stack, and silences even Trigger one-shots that would
|
||
// ignore a release. Use for panic; CC 123 for the softer "let gates release" behavior.
|
||
// RT-safe (no allocation, bounded by maxVoices); callable from the audio thread.
|
||
void allSoundsOff();
|
||
|
||
// REAL-TIME render (S4): sums all active voices into the caller-provided buffer
|
||
// `out[0..frameCount)`, ADDING to whatever is there (the caller clears or mixes —
|
||
// this never touches memory it does not own and NEVER allocates). This is the
|
||
// audio-thread entry point: the VST3 process callback passes the host's own output
|
||
// channel buffer, so no allocation, resize, or heap traffic happens under process.
|
||
// Voices that finish mid-block go idle and stop contributing. `out` must point at
|
||
// at least `frameCount` writable samples; a null `out` or zero count is a no-op.
|
||
void render(AudioSample* out, std::size_t frameCount);
|
||
|
||
// REAL-TIME stereo render (S7): sums all active voices per-channel into the caller's two
|
||
// buffers `left`/`right` (each `frameCount` writable samples), ADDING to whatever is there
|
||
// (the caller clears/mixes). Same RT discipline as the mono overload — no allocation, no
|
||
// resize, no lock. A mono sample plays dual-mono (same value to both channels, centered);
|
||
// a stereo sample plays its two channels. A null buffer or zero count is a no-op. The mono
|
||
// and stereo render paths are independent output shapes over the SAME voice pool; the active
|
||
// channel mode (mono vs stereo bus) picks which one the process callback drives per block.
|
||
void render(AudioSample* left, AudioSample* right, std::size_t frameCount);
|
||
|
||
// TEST / off-thread convenience: appends `frameCount` summed frames to `out`
|
||
// (grows it — DO NOT call on the audio thread; it allocates). Delegates to the
|
||
// real-time overload after sizing the buffer, so both paths share one mix loop.
|
||
// Does not clear existing contents — appends, matching the pre-S4 contract the
|
||
// unit tests rely on.
|
||
void render(std::vector<AudioSample>& out, std::size_t frameCount);
|
||
|
||
// Count of currently active voices (for tests / diagnostics).
|
||
std::size_t activeVoiceCount() const;
|
||
|
||
std::size_t maxVoices() const { return voices_.size(); }
|
||
|
||
static constexpr std::size_t kNoVoice = static_cast<std::size_t>(-1);
|
||
|
||
private:
|
||
// Picks a voice to (re)use for a new note-on: a free voice if any, else a stolen
|
||
// one per the documented policy. Always returns a valid index (maxVoices >= 1).
|
||
std::size_t allocateVoice();
|
||
|
||
// Count of active Preserve-engine voices (for the S16 Preserve cap). Rescanned per note-on
|
||
// (cheap: bounded by maxVoices) rather than maintained as a running tally.
|
||
std::size_t activePreserveVoices() const;
|
||
|
||
// --- MONO mode (Phase S): last-note priority over a held-note stack ------------
|
||
// The stack holds every currently-held, ZONE-RESOLVING note in press order (top = most
|
||
// recent = the sounding note while the voice is gated). An out-of-zone note never joins
|
||
// (it cannot sound, so it must not later take the voice back on a fallback). Re-pressing
|
||
// a held note moves it to the top. Fixed-capacity (128 distinct MIDI notes) — no
|
||
// allocation on the audio thread. Velocity is kept per held note so a RETRIGGER fallback
|
||
// re-strikes the fallen-back-to note at ITS original velocity.
|
||
struct HeldNote { std::uint8_t note; std::uint8_t velocity; };
|
||
|
||
// Mono note-on: push to the stack and take the voice over (legato retune on a same-sample
|
||
// takeover, else a fresh start). Returns 0 (the mono voice) or kNoVoice for out-of-zone
|
||
// or out-of-range (note outside [0,127] — rejected BEFORE the stack, which stores uint8).
|
||
// The S16 Preserve cap is NOT applied in mono — a single voice runs at most one shifter,
|
||
// inherently within any cap; applying it would wrongly drop a Preserve->Preserve takeover.
|
||
std::size_t monoNoteOn(int note, int velocity);
|
||
// Mono note-off: pop from the stack; if the released note was sounding, fall back to the
|
||
// most-recent still-held note (retrigger or legato per monoTrigger_), else release.
|
||
void monoNoteOff(int note);
|
||
// Drops `note` from the held stack (order of the remaining notes preserved). No-op if absent.
|
||
void removeHeld(int note);
|
||
|
||
std::vector<Voice> voices_;
|
||
const Keymap& keymap_;
|
||
std::size_t preserveVoiceCap_ = 0; // S16: max simultaneous Preserve voices (0 = no separate cap)
|
||
std::uint64_t nextStartOrder_ = 1; // monotonic; 0 reserved for "never started"
|
||
VoiceMode voiceMode_ = VoiceMode::Poly;
|
||
MonoTrigger monoTrigger_ = MonoTrigger::Retrigger;
|
||
std::array<HeldNote, 128> heldStack_{}; // mono held notes, press order; top = heldCount_-1
|
||
std::size_t heldCount_ = 0;
|
||
};
|
||
|
||
// ---------------------------------------------------------------------------
|
||
// PREVIEW VOICE CARD (Phase S). A dedicated single voice ENTIRELY ISOLATED from the MIDI
|
||
// VoiceEngine pool: the editor's preview trigger routes ONLY here, host MIDI ONLY to the
|
||
// engine, and the two are summed by the shell — neither can steal from, drop, or cap the
|
||
// other (the FA1 "preview dropped when voices are full" bug is structurally impossible).
|
||
//
|
||
// The card plays the loaded zone through its REAL params (the same Keymap resolution and
|
||
// Voice machinery — you hear the actual sound), but with the FA1 unity-Varispeed bypass
|
||
// OPTED IN: the preview fires at the effective root (unity shift), where the Preserve
|
||
// shifter's half-window onset delay buys nothing, so the preview speaks on frame one. A
|
||
// transposed preview (if ever fired off-root) keeps the genuine shifter path — the
|
||
// shifters are pre-sized at construction (off-thread), so noteOn stays RT-safe.
|
||
//
|
||
// PLAYBACK ONLY (load-bearing principle): the card never captures, never writes the bank,
|
||
// never inserts a timeline item. Pure — no VST3/REAPER types; the shell owns the mailbox
|
||
// cadence and the output summation.
|
||
// ---------------------------------------------------------------------------
|
||
|
||
class PreviewCard {
|
||
public:
|
||
// `keymap` must outlive the card (same lifetime contract as VoiceEngine — both live on
|
||
// the shell's LoadedInstrument next to the Keymap they read). `preserveWindowFrames`
|
||
// pre-sizes the voice's Preserve shifters off-thread (0/1 = pass-through), mirroring the
|
||
// engine's constructor, so an off-root Preserve preview never allocates at note-on.
|
||
explicit PreviewCard(const Keymap& keymap, std::int64_t preserveWindowFrames = 0);
|
||
|
||
// Fire the preview note (RT-safe: no allocation). A new preview replaces the ringing one
|
||
// (single voice — the card is one finger, not a pool). Out-of-zone is a defined no-play.
|
||
void noteOn(int note, int velocity);
|
||
// Release the preview IF `note` is the one sounding (a stale off for a replaced note is a
|
||
// no-op). Gate zones enter release; Trigger zones ignore note-off and play through.
|
||
void noteOff(int note);
|
||
// CC 123 peer of VoiceEngine::allNotesOff: release the ringing preview UNCONDITIONALLY,
|
||
// whatever note it is on. Gate enters release; Trigger plays through (bounded). RT-safe.
|
||
void releaseAll();
|
||
// CC 120 peer of VoiceEngine::allSoundsOff: HARD-STOP the preview immediately (no release
|
||
// ramp, silences Trigger one-shots too). RT-safe.
|
||
void hardStop();
|
||
|
||
bool active() const { return voice_.active(); }
|
||
|
||
// Sum the card's contribution into the caller's buffer(s), ADDING (mirror of the engine's
|
||
// RT render contract — no allocation, no lock; null/zero-count is a no-op).
|
||
void render(AudioSample* out, std::size_t frameCount);
|
||
void render(AudioSample* left, AudioSample* right, std::size_t frameCount);
|
||
|
||
private:
|
||
Voice voice_;
|
||
const Keymap& keymap_;
|
||
};
|
||
|
||
} // namespace reasampler
|