instrument: one VELOCITY deck for all three velocity curves, bipolar and off by default for pitch and filter

Payload v12 appends the new velocity->pitch curve and folds the retired filter velAmount into its now-bipolar curve, so pre-v12 projects reopen sounding identical. Preview button takes a drawn play triangle.

src/core/instrument/engine/play_params.h

@@ -110,31 +110,32 @@ struct PitchEnvParams {
 // normalized control positions verbatim rather than a parallel set, so no control range is
 // re-derived here; `filter_params.h` owns every law that maps them to Hz/Q/depth.
 //
-// The three modulation depths below land in that same normalized cutoff domain and sum
-// before a single clamp; all three are zero/neutral by default.
+// The modulation depths below land in that same normalized cutoff domain and sum before a
+// single clamp; all are zero/neutral by default.
 struct FilterParams {
     bool enabled = false;
     instrument::engine::filter::FilterSettings settings;
     double modAmount = 0.0;   // bipolar [-1,+1], envelope -> cutoff
-    double velAmount = 0.0;   // bipolar [-1,+1], velocity -> cutoff
     double keyTrack  = 0.0;   // octaves of cutoff per octave of (note - root)
     // The filter envelope takes the same shape the amp does under the active play mode:
     // AHDSR in Gate, AHD in Trigger. Both are stored, so a mode flip cannot lose either
     // mode's dialled values (see core/instrument/CLAUDE.md).
     AdsrParams env;           // Gate: the same staged AHDSR the amp runs; frames
     AhdParams  trigEnv;       // Trigger: the same staged AHD the amp runs; frames
-    // Shapes velocity before velAmount scales it. Linear rather than the amp's flat() default
-    // because a flat curve under a depth control would make every velocity the same offset;
-    // the no-op at rest is velAmount == 0, not the curve. NOTE: this default only governs a
-    // FRESH FilterParams — the shared codec's corrupt/truncated-point-list repair
-    // (VelocityCurve::fromPoints, used for both this curve and the amp's) still degrades to
-    // flat() regardless, since that repair has no curve-specific fallback.
-    VelocityCurve velocityCurve = VelocityCurve::linear();
+    // Velocity -> cutoff, in the normalized cutoff domain. BIPOLAR, so the curve is both the
+    // shape and the amount — there is no separate depth knob behind it (the retired velAmount
+    // was exactly that, and a signed depth multiplying a signed curve made the sign unreadable).
+    VelocityCurve velocityCurve = VelocityCurve::zero();
 };
 
+// Full-scale of the velocity->pitch curve: y = +/-1 transposes by this many semitones. Shared
+// with the pitch envelope's own depth throw so the two pitch modulators speak one range.
+inline constexpr double kVelocityPitchRangeSemitones = 24.0;
+
 // Bundle a voice reads at start(). Defaults reproduce the bare engine (Gate, hold-0 AHDSR,
-// Varispeed, pitch envelope off, filter off) — core regression tests rely on this; the
-// Preserve product default is layered on at (de)serialization, see kDefaultPitchEngine.
+// Varispeed, pitch envelope off, filter off, no velocity->pitch) — 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;      // Gate amp
@@ -142,6 +143,10 @@ struct PlayParams {
     AhdParams      trigAhd;   // Trigger amp
     PitchEngine    pitchEngine = PitchEngine::Varispeed;
     PitchEnvParams pitchEnv;
+    // Velocity -> pitch offset, scaled by kVelocityPitchRangeSemitones. Bipolar and flat at 0
+    // by default, so it transposes nothing until a curve is drawn. Folded into the voice's
+    // baseRatio_ at note-on — it is fixed for the note's lifetime, so it costs no per-frame work.
+    VelocityCurve  pitchVelocityCurve = VelocityCurve::zero();
     FilterParams   filter;
 };
 

src/core/instrument/engine/velocity_curve.cpp

@@ -11,19 +11,19 @@ namespace reasampler::instrument::engine {
 namespace {
 
 double clampVelocity(double v) { return std::clamp(v, kVelMin, kVelMax); }
-double clampAmp(double a) { return std::clamp(a, kAmpMin, kAmpMax); }
+double clampValue(double a, CurveDomain d) { return std::clamp(a, curveYMin(d), kCurveYMax); }
 
-// X spans the width for [0,127]; Y spans (height-1) rows for amp [0,1] with amp 1 at the TOP
-// (pixel y increases downward, so this axis is inverted relative to amp).
+// X spans the width for [0,127]; Y spans (height-1) rows for the domain's range with its max at
+// the TOP (pixel y increases downward, so this axis is inverted relative to the value).
 double velPerPixel(const VelocityCurve::Box& box) {
     const int w = std::max(0, box.width);
     if (w <= 0) return 0.0;
     return (kVelMax - kVelMin) / static_cast<double>(w);
 }
-double ampPerPixel(const VelocityCurve::Box& box) {
+double valuePerPixel(const VelocityCurve::Box& box, CurveDomain d) {
     const int h = std::max(0, box.height);
     if (h <= 1) return 0.0;
-    return (kAmpMax - kAmpMin) / static_cast<double>(h - 1);
+    return (kCurveYMax - curveYMin(d)) / static_cast<double>(h - 1);
 }
 int velToX(const VelocityCurve::Box& box, double velocity) {
     const int w = std::max(0, box.width);
@@ -31,10 +31,11 @@ int velToX(const VelocityCurve::Box& box, double velocity) {
     const double frac = (clampVelocity(velocity) - kVelMin) / (kVelMax - kVelMin);
     return box.left + static_cast<int>(frac * static_cast<double>(w) + 0.5);
 }
-int ampToY(const VelocityCurve::Box& box, double amp) {
+int valueToY(const VelocityCurve::Box& box, double value, CurveDomain d) {
     const int h = std::max(0, box.height);
     if (h <= 1) return box.top;
-    const double frac = (clampAmp(amp) - kAmpMin) / (kAmpMax - kAmpMin);
+    const double lo = curveYMin(d);
+    const double frac = (clampValue(value, d) - lo) / (kCurveYMax - lo);
     return box.top + static_cast<int>((1.0 - frac) * static_cast<double>(h - 1) + 0.5);
 }
 
@@ -42,39 +43,49 @@ int ampToY(const VelocityCurve::Box& box, double amp) {
 
 VelocityCurve VelocityCurve::flat() {
     VelocityCurve c;
-    c.points_ = {{kVelMin, kAmpMax}, {kVelMax, kAmpMax}};
+    c.points_ = {{kVelMin, kCurveYMax}, {kVelMax, kCurveYMax}};
     return c;
 }
 
 VelocityCurve VelocityCurve::linear() {
     VelocityCurve c;
-    c.points_ = {{kVelMin, kAmpMin}, {kVelMax, kAmpMax}};
+    c.points_ = {{kVelMin, 0.0}, {kVelMax, kCurveYMax}};
     return c;
 }
 
-VelocityCurve VelocityCurve::fromPoints(std::vector<VelocityPoint> pts) {
+VelocityCurve VelocityCurve::zero() {
+    VelocityCurve c;
+    c.domain_ = CurveDomain::Bipolar;
+    c.points_ = {{kVelMin, 0.0}, {kVelMax, 0.0}};
+    return c;
+}
+
+VelocityCurve VelocityCurve::fromPoints(std::vector<VelocityPoint> pts, CurveDomain domain) {
     // Stable sort so coincident-X points keep their wire order (eval stays well-defined for
     // duplicate-X knots).
     for (VelocityPoint& p : pts) {
         p.velocity = clampVelocity(p.velocity);
-        p.amp = clampAmp(p.amp);
+        p.value = clampValue(p.value, domain);
     }
     std::stable_sort(pts.begin(), pts.end(),
                      [](const VelocityPoint& a, const VelocityPoint& b) {
                          return a.velocity < b.velocity;
                      });
-    if (pts.size() < 2) return flat();
+    if (pts.size() < 2) {
+        return domain == CurveDomain::Bipolar ? zero() : flat();
+    }
     if (pts.front().velocity > kVelMin) {
-        pts.insert(pts.begin(), VelocityPoint{kVelMin, pts.front().amp});
+        pts.insert(pts.begin(), VelocityPoint{kVelMin, pts.front().value});
     } else {
         pts.front().velocity = kVelMin;
     }
     if (pts.back().velocity < kVelMax) {
-        pts.push_back(VelocityPoint{kVelMax, pts.back().amp});
+        pts.push_back(VelocityPoint{kVelMax, pts.back().value});
     } else {
         pts.back().velocity = kVelMax;
     }
     VelocityCurve c;
+    c.domain_ = domain;
     c.points_ = std::move(pts);
     return c;
 }
@@ -84,7 +95,8 @@ namespace {
 // Fritsch-Carlson monotone-cubic tangent: a sign change (or flat) neighbour is a local extremum,
 // so the tangent pins to 0 to avoid overshoot; otherwise the weighted-harmonic-mean tangent,
 // which for collinear knots (dPrev==dNext) reduces exactly to the shared secant — this is what
-// makes the spline reproduce a straight line to ~1e-15 for linear()-style input.
+// makes the spline reproduce a straight line for linear()-style input. Homogeneous of degree 1
+// in the secants, which is what makes eval homogeneous in y (see the header).
 double fritschCarlsonTangent(double dPrev, double dNext, double spanPrev, double spanNext) {
     if (dPrev * dNext <= 0.0) return 0.0;
     const double w1 = 2.0 * spanNext + spanPrev;
@@ -95,29 +107,29 @@ double fritschCarlsonTangent(double dPrev, double dNext, double spanPrev, double
 }  // namespace
 
 double VelocityCurve::eval(double velocity) const {
-    if (points_.empty()) return kAmpMax;
-    if (points_.size() == 1) return clampAmp(points_[0].amp);
+    if (points_.empty()) return curveNeutral(domain_);
+    if (points_.size() == 1) return clampValue(points_[0].value, domain_);
     const double v = clampVelocity(velocity);
-    if (v <= points_.front().velocity) return clampAmp(points_.front().amp);
-    if (v >= points_.back().velocity) return clampAmp(points_.back().amp);
+    if (v <= points_.front().velocity) return clampValue(points_.front().value, domain_);
+    if (v >= points_.back().velocity) return clampValue(points_.back().value, domain_);
     for (std::size_t i = 0; i + 1 < points_.size(); ++i) {
         const VelocityPoint& a = points_[i];
         const VelocityPoint& b = points_[i + 1];
         if (v >= a.velocity && v <= b.velocity) {
             const double span = b.velocity - a.velocity;
             // Coincident-X neighbours (a step): zero-width segment, no interior to blend.
-            if (span <= 0.0) return clampAmp(b.amp);
+            if (span <= 0.0) return clampValue(b.value, domain_);
 
-            // Monotone cubic Hermite (Fritsch-Carlson): provably stays within [a.amp, b.amp]
+            // Monotone cubic Hermite (Fritsch-Carlson): provably stays within [a.value, b.value]
             // between the two knots (no overshoot), reproducing a straight line for collinear input.
-            const double d = (b.amp - a.amp) / span;
+            const double d = (b.value - a.value) / span;
 
             double mA = d;
             if (i > 0) {
                 const VelocityPoint& prev = points_[i - 1];
                 const double spanPrev = a.velocity - prev.velocity;
                 if (spanPrev > 0.0) {
-                    const double dPrev = (a.amp - prev.amp) / spanPrev;
+                    const double dPrev = (a.value - prev.value) / spanPrev;
                     mA = fritschCarlsonTangent(dPrev, d, spanPrev, span);
                 } else {
                     mA = 0.0;
@@ -128,7 +140,7 @@ double VelocityCurve::eval(double velocity) const {
                 const VelocityPoint& next = points_[i + 2];
                 const double spanNext = next.velocity - b.velocity;
                 if (spanNext > 0.0) {
-                    const double dNext = (next.amp - b.amp) / spanNext;
+                    const double dNext = (next.value - b.value) / spanNext;
                     mB = fritschCarlsonTangent(d, dNext, span, spanNext);
                 } else {
                     mB = 0.0;
@@ -142,15 +154,15 @@ double VelocityCurve::eval(double velocity) const {
             const double h10 = t3 - 2.0 * t2 + t;
             const double h01 = -2.0 * t3 + 3.0 * t2;
             const double h11 = t3 - t2;
-            const double y = h00 * a.amp + h10 * span * mA + h01 * b.amp + h11 * span * mB;
-            return clampAmp(y);
+            const double y = h00 * a.value + h10 * span * mA + h01 * b.value + h11 * span * mB;
+            return clampValue(y, domain_);
         }
     }
-    return clampAmp(points_.back().amp);  // unreachable (v is between the endpoints)
+    return clampValue(points_.back().value, domain_);  // unreachable (v is between the endpoints)
 }
 
-std::size_t VelocityCurve::addPoint(double velocity, double amp) {
-    const VelocityPoint p{clampVelocity(velocity), clampAmp(amp)};
+std::size_t VelocityCurve::addPoint(double velocity, double value) {
+    const VelocityPoint p{clampVelocity(velocity), clampValue(value, domain_)};
     // First index strictly greater, so a duplicate-X point lands immediately after the existing one.
     std::size_t i = 0;
     while (i < points_.size() && points_[i].velocity <= p.velocity) ++i;
@@ -158,12 +170,12 @@ std::size_t VelocityCurve::addPoint(double velocity, double amp) {
     return i;
 }
 
-VelocityPoint VelocityCurve::movePoint(std::size_t index, double velocity, double amp) {
+VelocityPoint VelocityCurve::movePoint(std::size_t index, double velocity, double value) {
     if (index >= points_.size()) return VelocityPoint{};  // no-op (out of range)
     const bool isFirst = (index == 0);
     const bool isLast  = (index + 1 == points_.size());
 
-    double newAmp = clampAmp(amp);
+    double newValue = clampValue(value, domain_);
     double newVel;
     if (isFirst) {
         newVel = kVelMin;
@@ -174,7 +186,7 @@ VelocityPoint VelocityCurve::movePoint(std::size_t index, double velocity, doubl
         const double hi = points_[index + 1].velocity;
         newVel = std::clamp(clampVelocity(velocity), lo, hi);
     }
-    points_[index] = VelocityPoint{newVel, newAmp};
+    points_[index] = VelocityPoint{newVel, newValue};
     return points_[index];
 }
 
@@ -185,12 +197,13 @@ bool VelocityCurve::deletePoint(std::size_t index) {
     return true;
 }
 
-VelocityCurve::CurvePixel VelocityCurve::pixelFromPoint(const Box& box, const VelocityPoint& p) {
-    return CurvePixel{velToX(box, p.velocity), ampToY(box, p.amp)};
+VelocityCurve::CurvePixel VelocityCurve::pixelFromPoint(const Box& box,
+                                                       const VelocityPoint& p) const {
+    return CurvePixel{velToX(box, p.velocity), valueToY(box, p.value, domain_)};
 }
 
-VelocityPoint VelocityCurve::pointFromPixel(const Box& box, int x, int y) {
-    // Exact inverse of velToX/ampToY (within one pixel); degenerate dims collapse the same way.
+VelocityPoint VelocityCurve::pointFromPixel(const Box& box, int x, int y) const {
+    // Exact inverse of velToX/valueToY (within one pixel); degenerate dims collapse the same way.
     VelocityPoint p;
     const int w = std::max(0, box.width);
     const int h = std::max(0, box.height);
@@ -198,17 +211,19 @@ VelocityPoint VelocityCurve::pointFromPixel(const Box& box, int x, int y) {
         ? kVelMin
         : clampVelocity(kVelMin + static_cast<double>(x - box.left) / static_cast<double>(w) *
                                       (kVelMax - kVelMin));
-    p.amp = (h <= 1)
-        ? kAmpMax
-        : clampAmp(kAmpMax - static_cast<double>(y - box.top) / static_cast<double>(h - 1) *
-                                 (kAmpMax - kAmpMin));
+    const double lo = curveYMin(domain_);
+    p.value = (h <= 1)
+        ? kCurveYMax
+        : clampValue(kCurveYMax - static_cast<double>(y - box.top) / static_cast<double>(h - 1) *
+                                      (kCurveYMax - lo),
+                     domain_);
     return p;
 }
 
 int VelocityCurve::pointAtPixel(const Box& box, int x, int y) const {
     for (std::size_t i = 0; i < points_.size(); ++i) {
         const int px = velToX(box, points_[i].velocity);
-        const int py = ampToY(box, points_[i].amp);
+        const int py = valueToY(box, points_[i].value, domain_);
         if (std::abs(x - px) <= kCurveNodeGrabRadius && std::abs(y - py) <= kCurveNodeGrabRadius) {
             return static_cast<int>(i);
         }
@@ -221,22 +236,24 @@ VelocityCurve VelocityCurve::resolvePointDrag(const VelocityCurve& grabCurve, st
     VelocityCurve out = grabCurve;
     if (index >= out.points_.size()) return out;  // out of range -> no motion
     const double velPerPx = velPerPixel(box);
-    const double ampPerPx = ampPerPixel(box);
-    if (velPerPx <= 0.0 || ampPerPx <= 0.0) return out;  // degenerate box -> no motion
+    const double valPerPx = valuePerPixel(box, grabCurve.domain_);
+    if (velPerPx <= 0.0 || valPerPx <= 0.0) return out;  // degenerate box -> no motion
 
     const VelocityPoint& grab = grabCurve.points_[index];
     const double newVel = grab.velocity + static_cast<double>(dxPixels) * velPerPx;
-    // Y increases downward but amp increases upward, so a downward drag (positive dy) LOWERS amp.
-    const double newAmp = grab.amp - static_cast<double>(dyPixels) * ampPerPx;
-    out.movePoint(index, newVel, newAmp);  // applies box + neighbour-X + endpoint-pin clamps
+    // Y increases downward but the value increases upward, so a downward drag (positive dy)
+    // LOWERS the value.
+    const double newValue = grab.value - static_cast<double>(dyPixels) * valPerPx;
+    out.movePoint(index, newVel, newValue);  // applies box + neighbour-X + endpoint-pin clamps
     return out;
 }
 
 bool VelocityCurve::equals(const VelocityCurve& other, double eps) const {
+    if (domain_ != other.domain_) return false;
     if (points_.size() != other.points_.size()) return false;
     for (std::size_t i = 0; i < points_.size(); ++i) {
         if (std::fabs(points_[i].velocity - other.points_[i].velocity) > eps) return false;
-        if (std::fabs(points_[i].amp - other.points_[i].amp) > eps) return false;
+        if (std::fabs(points_[i].value - other.points_[i].value) > eps) return false;
     }
     return true;
 }

src/core/instrument/engine/velocity_curve.h

@@ -1,7 +1,8 @@
-// velocity_curve.h — velocity->amp transfer curve. eval(velocity) is called once per note-on
-// in Voice::start(), never per frame. Editor hit-test/inverse-map take an explicit pixel Box
-// rather than a Rect: this module sits below sampler_core in the link graph and must not gain
-// a transitive dependency on editor-layout types.
+// velocity_curve.h — the velocity->modulation transfer curve, shared by all three
+// destinations (amp gain, pitch offset, filter cutoff offset). eval(velocity) is called once
+// per note-on in Voice::start(), never per frame. Editor hit-test/inverse-map take an explicit
+// pixel Box rather than a Rect: this module sits below sampler_core in the link graph and must
+// not gain a transitive dependency on editor-layout types.
 
 #pragma once
 
@@ -10,17 +11,29 @@
 
 namespace reasampler::instrument::engine {
 
-// The MIDI velocity domain [0,127] and the amp range [0,1] — the box every point clamps into.
+// The MIDI velocity domain [0,127] — the X span every point clamps into.
 inline constexpr double kVelMin = 0.0;
 inline constexpr double kVelMax = 127.0;
-inline constexpr double kAmpMin = 0.0;
-inline constexpr double kAmpMax = 1.0;
+inline constexpr double kCurveYMax = 1.0;
+
+// The curve's Y range. UNIPOLAR [0,1] is a GAIN — the amp's domain, where the do-nothing
+// curve is flat at 1. BIPOLAR [-1,1] is a SIGNED modulation depth — the pitch and filter
+// domains, where the do-nothing curve is flat at 0 and the sign picks the direction. A
+// bipolar curve is therefore both the shape and the amount: there is no separate depth
+// control behind it.
+enum class CurveDomain { Unipolar, Bipolar };
+
+constexpr double curveYMin(CurveDomain d) { return d == CurveDomain::Bipolar ? -1.0 : 0.0; }
+
+// The value that changes nothing in each domain — unity gain, or zero modulation. Every
+// defensive fallback lands here so a corrupt blob loses the shaping rather than inventing one.
+constexpr double curveNeutral(CurveDomain d) { return d == CurveDomain::Bipolar ? 0.0 : 1.0; }
 
 // A raw-constructed point is NOT auto-clamped (the mutators own that invariant) — build curves
 // through the named constructors / addPoint rather than pushing raw points.
 struct VelocityPoint {
     double velocity = 0.0;   // X, [0,127]
-    double amp      = 0.0;   // Y, [0,1]
+    double value    = 0.0;   // Y, in the owning curve's domain
 };
 
 // Pick radius (px) around a node's drawn point for the editor hit-test.
@@ -28,44 +41,50 @@ inline constexpr int kCurveNodeGrabRadius = 6;
 
 // An X-ordered list of control points spanning [0,127], evaluated by a monotone cubic Hermite
 // spline (Fritsch-Carlson slope limiting) — a genuine curve, not a polyline, that provably never
-// overshoots a segment's amp range. For collinear knots the tangents reduce to the secant slope,
-// so the spline reproduces linear()'s straight line to within ~1e-15. The two endpoints (velocity
-// 0 and 127) are load-bearing: they keep eval total over the domain and are never deletable.
+// overshoots a segment's value range. For collinear knots the tangents reduce to the secant
+// slope, so the spline reproduces linear()'s straight line to within ~1e-15. The two endpoints
+// (velocity 0 and 127) are load-bearing: they keep eval total over the domain and are never
+// deletable. eval is HOMOGENEOUS in y — scaling every knot's value by k scales the whole curve
+// by k exactly, which is what lets the codec fold a retired depth control into stored knots.
 class VelocityCurve {
 public:
-    // flat() (endpoints (0,1)/(127,1), every velocity -> unity) is the default — see
+    // flat() (endpoints (0,1)/(127,1), every velocity -> unity) is the unipolar default — see
     // velocity_curve in the directory CLAUDE.md for why this isn't bit-identical to the
     // pre-existing linear() response.
     static VelocityCurve flat();
     static VelocityCurve linear();
+    // The bipolar default: flat at 0, so velocity modulates nothing until a curve is drawn.
+    static VelocityCurve zero();
 
     // Rebuilds from a deserialized point list, repairing the invariant defensively: box-clamps
-    // each point, stable-sorts by velocity, forces both endpoints present (synthesized if
-    // missing), falls back to flat() if fewer than 2 usable points remain. A corrupt/truncated
-    // blob yields a well-formed curve, never an invariant-violating one.
-    static VelocityCurve fromPoints(std::vector<VelocityPoint> pts);
+    // each point into `domain`, stable-sorts by velocity, forces both endpoints present
+    // (synthesized if missing), falls back to the domain's neutral curve if fewer than 2 usable
+    // points remain. A corrupt/truncated blob yields a well-formed curve, never an
+    // invariant-violating one.
+    static VelocityCurve fromPoints(std::vector<VelocityPoint> pts, CurveDomain domain);
 
+    CurveDomain domain() const { return domain_; }
     const std::vector<VelocityPoint>& points() const { return points_; }
     std::size_t size() const { return points_.size(); }
 
-    // Degenerate cases (shouldn't occur post-construction): empty curve returns kAmpMax; a
-    // one-point curve returns that point's amp.
+    // Degenerate cases (shouldn't occur post-construction): empty curve returns the domain's
+    // neutral; a one-point curve returns that point's value.
     double eval(double velocity) const;
 
     // Inserted at a velocity duplicating an existing point lands immediately after it, so a
     // subsequent move can separate them. Returns the inserted index.
-    std::size_t addPoint(double velocity, double amp);
+    std::size_t addPoint(double velocity, double value);
 
     // Box-clamped and X-clamped between immediate neighbours (monotonic-X grammar). The two
-    // endpoints are pinned in X (only their amp moves); out-of-range index is a no-op.
-    VelocityPoint movePoint(std::size_t index, double velocity, double amp);
+    // endpoints are pinned in X (only their value moves); out-of-range index is a no-op.
+    VelocityPoint movePoint(std::size_t index, double velocity, double value);
 
     // Endpoints (index 0 and last) are not deletable; that or an out-of-range index is a no-op
     // returning false.
     bool deletePoint(std::size_t index);
 
-    // The drawn box, in pixels: X = velocity across the width, Y = amp UP the height (amp 1 at
-    // top). Passed explicitly rather than a Rect — see header preamble.
+    // The drawn box, in pixels: X = velocity across the width, Y = value UP the height (the
+    // domain's max at top). Passed explicitly rather than a Rect — see header preamble.
     struct Box {
         int left = 0;
         int top = 0;
@@ -82,14 +101,15 @@ public:
         int x = 0;
         int y = 0;
     };
-    static CurvePixel pixelFromPoint(const Box& box, const VelocityPoint& p);
+    CurvePixel pixelFromPoint(const Box& box, const VelocityPoint& p) const;
 
-    // Exact inverse of pixelFromPoint (within the one-pixel quantum) — where an empty-space click
-    // lands as a new point. Degenerate box: zero-width reads velocity 0; height <= 1 reads amp 1.
-    static VelocityPoint pointFromPixel(const Box& box, int x, int y);
+    // Exact inverse of pixelFromPoint (within the one-pixel quantum) — where an empty-space
+    // click lands as a new point. Degenerate box: zero-width reads velocity 0; height <= 1
+    // reads the domain's max (the top row is what a collapsed box draws).
+    VelocityPoint pointFromPixel(const Box& box, int x, int y) const;
 
     // `grabCurve` is the curve as of mouse-down (shell snapshots it so the delta is absolute).
-    // Maps the pixel delta to velocity/amp over the box, then applies movePoint's clamp. Zero
+    // Maps the pixel delta to velocity/value over the box, then applies movePoint's clamp. Zero
     // width/height box or out-of-range index returns grabCurve unchanged.
     static VelocityCurve resolvePointDrag(const VelocityCurve& grabCurve, std::size_t index,
                                           const Box& box, int dxPixels, int dyPixels);
@@ -100,6 +120,7 @@ private:
     // Always X-ordered with an endpoint at 0 and 127; constructors + deserialize establish the
     // invariant, mutators preserve it.
     std::vector<VelocityPoint> points_;
+    CurveDomain domain_ = CurveDomain::Unipolar;
 };
 
 }  // namespace reasampler::instrument::engine

src/core/instrument/engine/voice.cpp

@@ -49,12 +49,14 @@ void Voice::start(int note, int velocity, const SampleData& sample, bool declick
     // Velocity->amp mapped once at note-on; the per-frame render just multiplies the cached
     // velocityGain_.
     velocityGain_ = sample.velocityCurve.eval(static_cast<double>(velocity));
-    // Feeds both engines through baseRatio_ (Varispeed read-rate bias and Preserve shift
-    // amount both derive from it below).
-    baseRatio_ = keyTrackedRatio(note, sample.rootNote, sample.keyTrack);
     sample_ = &sample;
 
     const PlayParams& p = sample.play;
+    // Velocity->pitch is fixed for the note's lifetime, so it folds into baseRatio_ here rather
+    // than costing a per-frame multiply. Feeds both engines through baseRatio_ (Varispeed
+    // read-rate bias and Preserve shift amount both derive from it below).
+    velPitchRatio_ = velocityPitchRatio(p.pitchVelocityCurve, velocity);
+    baseRatio_ = keyTrackedRatio(note, sample.rootNote, sample.keyTrack) * velPitchRatio_;
     playMode_ = p.playMode;
     pitchEngine_ = p.pitchEngine;
 
@@ -129,8 +131,7 @@ void Voice::start(int note, int velocity, const SampleData& sample, bool declick
         filterCutoffNorm_ = static_cast<double>(p.filter.settings.cutoffNorm);
         filterModAmount_ = p.filter.modAmount;
         filterKeyTrack_ = p.filter.keyTrack;
-        filterVelOffset_ =
-            p.filter.velAmount * p.filter.velocityCurve.eval(static_cast<double>(velocity));
+        filterVelOffset_ = p.filter.velocityCurve.eval(static_cast<double>(velocity));
         filterRate_ = static_cast<double>(sample.sampleRate);
         rModAmount_.set(p.filter.modAmount);
         rResonance_.set(static_cast<double>(p.filter.settings.resonanceNorm));
@@ -281,7 +282,9 @@ void Voice::retune(int note) {
     // Changes baseRatio_ without re-converting pitchEnv_'s already-configured span (the
     // baseRatio_ division in the note-on setup above), so a slide leaves that envelope on the
     // first note's domain — consistent with "touch nothing else," but the drift lives here.
-    baseRatio_ = keyTrackedRatio(note, sample_->rootNote, sample_->keyTrack);
+    // The velocity->pitch factor rides through the slide unchanged, matching velocityGain_ —
+    // one gesture, one strike.
+    baseRatio_ = keyTrackedRatio(note, sample_->rootNote, sample_->keyTrack) * velPitchRatio_;
     // Filter key-tracking follows the pitch: it is a function of the note, so a slide moves it
     // too. The velocity offset deliberately stays the first note's, matching velocityGain_.
     if (filterOn_) updateFilterCutoffBase(note);

src/core/instrument/engine/voice.h

@@ -48,6 +48,14 @@ inline double keyTrackedRatio(int note, int rootNote, double keyTrack) {
     return std::pow(2.0, semis / 12.0);
 }
 
+// 2^(curve(velocity) * kVelocityPitchRangeSemitones / 12): the velocity->pitch transpose, which
+// the voice folds into baseRatio_ once at note-on. A curve flat at 0 — the default — yields
+// EXACTLY 1.0 at every velocity and skips the pow, so an undrawn curve transposes nothing.
+inline double velocityPitchRatio(const VelocityCurve& curve, int velocity) {
+    const double semis = curve.eval(static_cast<double>(velocity)) * kVelocityPitchRangeSemitones;
+    return (semis == 0.0) ? 1.0 : std::pow(2.0, semis / 12.0);
+}
+
 // One octave expressed in the cutoff control's normalized domain, read out of the filter
 // module's OWN inverse rather than re-derived from its endpoints — the log law belongs to
 // filter_params, and a second copy here could drift from it. Evaluated at note-on only.
@@ -561,7 +569,8 @@ private:
     bool releasing_ = false;
     int note_ = 0;
     double velocityGain_ = 1.0;
-    double baseRatio_ = 1.0;     // 2^((note-root)/12): the un-modulated repitch ratio
+    double baseRatio_ = 1.0;     // key-tracked repitch ratio, with velocity->pitch folded in
+    double velPitchRatio_ = 1.0; // the velocity->pitch factor alone; retune re-applies it
     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;
@@ -593,7 +602,7 @@ private:
     double filterRate_ = 0.0;
     double filterCutoffNorm_ = 1.0;
     double filterModAmount_ = 0.0;
-    double filterVelOffset_ = 0.0;   // velAmount * velocityCurve.eval(velocity), fixed per note
+    double filterVelOffset_ = 0.0;   // velocityCurve.eval(velocity), fixed per note
     double filterKeyTrack_ = 0.0;
     instrument::engine::filter::FilterSettings filterSettings_{};  // the note's tone controls
     float filterBaseCutoff_ = 1.0f;    // cutoff before the envelope, clamped