feat(sample): SF2 LFO pitch modulation — modLfoToPitch + vibLfoToPitch

V1 wires the pitch targets only; modLfoToFilterFc /
modLfoToVolume / modulation envelope are deferred follow-ups.

SF2 loader parses 6 generators (delayModLFO=21, freqModLFO=22,
modLfoToPitch=5, plus the matching vibLfo trio 23/24/6) into
SfzRegion fields with the standard SF2 unit conversions
(absolute cents → Hz, timecents → seconds, cents passthrough).

SampleInstrument audio thread gains a RegionLfos Copy block in
TriggerShape + per-slot state (phase + delay countdown for each
LFO). Both LFOs advance independently per sample, emit a sin-
wave cents offset (only after their delay elapsed), and sum
into a rate factor via the small-angle approximation
(1 + cents · ln(2)/1200) the Mellotron flutter path uses.

sf2_loader.rs crossed the 1000-line cap during this ship —
extracted the GEN_ constants + Generators struct + absorb()
into a sibling sf2_generators.rs (1105 → 874 lines). Defaults
in audio path are inert (0 cents depth → no audible LFO) so SF2
patches without these generators are bit-identical to V1. +4
tests; suite 2301 → 2305.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: Tok

PLAN.md

@@ -13,11 +13,13 @@ Pick from the top down; each row is one focused commit.
 
 ### SF2 follow-up
 
-- [ ] **Modulator / LFO generators**.  Volume envelope + filter
-  shipped.  Remaining: modulation envelope (modEnvToPitch /
-  modEnvToFilterFc), modulation LFO (modLfoToPitch /
-  modLfoToFilterFc / modLfoToVolume), vibrato LFO
-  (vibLfoToPitch).
+- [ ] **Modulator / LFO generators — remaining targets**.  Pitch
+  targets shipped (modLfoToPitch + vibLfoToPitch).  Remaining:
+  modLfoToFilterFc, modLfoToVolume, modulation envelope
+  (modEnvToPitch / modEnvToFilterFc).  Each requires per-slot
+  state + per-sample apply in the SampleInstrument voice; mod
+  envelope also needs the AHDSR state machine (5 timecents fields:
+  delay/attack/hold/decay/release + sustain attenuation).
 
 ---
 

docs/features.md

@@ -4,6 +4,61 @@ A detailed log of what's built.
 
 ---
 
+### SF2 LFO pitch modulation — modLfoToPitch + vibLfoToPitch
+
+The SF2 loader and SampleInstrument audio thread now honour the
+per-region pitch-LFO generators (modLfoToPitch=5,
+vibLfoToPitch=6) along with their timing (delay + frequency).
+SF2 patches that ship sustained / vocal / string samples with
+natural breath / vibrato now wobble per spec instead of holding
+dead-flat pitch.
+
+V1 scope is **pitch targets only** — modLfoToFilterFc /
+modLfoToVolume / modEnvToPitch / modEnvToFilterFc are deferred
+to a follow-up (PLAN entry).
+
+**SF2 loader.**  Six new generator opcodes parsed:
+`delayModLFO=21` (timecents), `freqModLFO=22` (absolute cents,
+`hz = 8.176 × 2^(cents/1200)`), `modLfoToPitch=5` (cents),
+plus the matching vibrato-LFO trio (23, 24, 6).  All round-trip
+via `Generators.absorb()`; `build_region` emits the converted
+Hz / seconds / cents into the new SfzRegion fields.
+
+**SfzRegion fields.**  `mod_lfo_freq_hz`, `mod_lfo_delay_s`,
+`mod_lfo_to_pitch_cents`, `vib_lfo_freq_hz`, `vib_lfo_delay_s`,
+`vib_lfo_to_pitch_cents`.  Defaults: 8.176 Hz (SF2 spec
+default), 0 s delay, 0 cents depth — so regions without these
+generators are bit-identical to pre-LFO behaviour.
+
+**Audio thread.**  New `RegionLfos` Copy struct + per-slot
+state in `SampleInstrumentSlot`:
+- `mod_lfo_phase`, `mod_lfo_delay_remain_s`
+- `vib_lfo_phase`, `vib_lfo_delay_remain_s`
+
+`fire_slot` resets phases + seeds delays from the region.  In
+`process_slot`, after the existing rate calc + Mellotron flutter,
+each LFO advances its phase, decrements its delay, and emits a
+sin-wave cents offset (only after delay elapsed).  Both depths
+sum into a single rate factor via the small-angle approximation
+`1 + cents · ln(2)/1200` (same trick the Mellotron flutter
+path uses; accurate to <0.01 % within the ±1200 cents clamp
+applied at trigger time).
+
+**Tests.**  +4: SF2 loader's `Generators::absorb` round-trips
+all 6 LFO + sample-modes opcodes (2 tests); audio-thread
+behaviour — modLfoToPitch perturbs the rendered output vs a
+zero-depth baseline; vibLfoToPitch's delay generator suppresses
+modulation early in the trace.  Suite **2301 → 2305**.
+
+This entry partially closes the SF2 wishlist line in PLAN.md
+(pitch targets shipped; filter / volume / mod envelope deferred).
+
+Files: `src/audio/sf2_loader.rs`, `src/state/sfz.rs`,
+`src/audio/dsp/sample_instrument.rs`,
+`src/tests/sample_instrument_sfz_tests.rs`.
+
+---
+
 ### SF2 sample loop modes — per-region loop honour
 
 The SF2 loader and SampleInstrument audio thread now honour per-

src/audio/dsp/sample_instrument.rs

@@ -33,6 +33,20 @@ pub struct SfzRegionRuntime {
     pub samples: Arc<Vec<f32>>,
 }
 
+/// SF2 LFO modulation block — copied per-trigger when the region
+/// declares non-zero `mod_lfo_to_pitch_cents` or `vib_lfo_to_pitch_cents`.
+/// V1 wires only the pitch targets; filter / volume targets and the
+/// SF2 modulation envelope are deferred follow-ups.
+#[derive(Clone, Copy, Debug)]
+pub(crate) struct RegionLfos {
+    pub(crate) mod_freq_hz: f32,
+    pub(crate) mod_delay_s: f32,
+    pub(crate) mod_to_pitch_cents: f32,
+    pub(crate) vib_freq_hz: f32,
+    pub(crate) vib_delay_s: f32,
+    pub(crate) vib_to_pitch_cents: f32,
+}
+
 /// Polyphony cap.  Default per PLAN.md — 8 slots covers chord stabs,
 /// release-tail overlap, and short stutters without over-allocating
 /// state.  When every slot is busy, the trigger steals the oldest.
@@ -67,6 +81,12 @@ struct TriggerShape {
     /// single-WAV / no-region path, which keeps consuming the
     /// global knobs so the user's loop window stays live.
     region_loop: Option<(crate::state::sfz::SfzLoopMode, usize, usize)>,
+    /// Per-region LFO config — `(mod_freq_hz, mod_delay_s,
+    /// mod_to_pitch_cents, vib_freq_hz, vib_delay_s,
+    /// vib_to_pitch_cents)`.  `Some` only when at least one pitch
+    /// depth is non-zero (no point running an LFO that doesn't
+    /// modulate anything).  V1 wires the pitch targets only.
+    region_lfos: Option<RegionLfos>,
 }
 
 /// Convert a cutoff frequency in Hz into the 0..1 knob value the
@@ -134,6 +154,18 @@ struct SampleInstrumentSlot {
     region_filter: Option<(f32, f32, u8)>,
     /// Per-slot loop override — see `TriggerShape.region_loop`.
     region_loop: Option<(crate::state::sfz::SfzLoopMode, usize, usize)>,
+    /// Per-slot SF2 LFO modulation — see `TriggerShape.region_lfos`.
+    region_lfos: Option<RegionLfos>,
+    /// Mod LFO running phase (0..1).  Reset on trigger.
+    mod_lfo_phase: f32,
+    /// Mod LFO delay countdown in samples.  Counts down to 0; the
+    /// LFO depth is silent until then (the spec's per-LFO delay
+    /// generator).
+    mod_lfo_delay_remain_s: f32,
+    /// Vib LFO running phase (0..1).
+    vib_lfo_phase: f32,
+    /// Vib LFO delay countdown in samples.
+    vib_lfo_delay_remain_s: f32,
     /// Monotonic counter set at trigger time — lowest = oldest slot.
     age: u64,
     /// Per-slot SVF state for the per-voice filter.  Each slot keeps
@@ -183,6 +215,11 @@ impl SampleInstrumentSlot {
             region_adsr: None,
             region_filter: None,
             region_loop: None,
+            region_lfos: None,
+            mod_lfo_phase: 0.0,
+            mod_lfo_delay_remain_s: 0.0,
+            vib_lfo_phase: 0.0,
+            vib_lfo_delay_remain_s: 0.0,
             age: 0,
             filter: Svf::new(),
             formant: FormantShifter::new(),
@@ -447,6 +484,23 @@ impl SampleInstrumentVoice {
                     }
                     _ => None,
                 };
+                // SF2 LFOs — Some only when at least one pitch
+                // depth is non-zero.  V1 wires the pitch targets only;
+                // filter / volume / mod-env follow-ups are deferred.
+                let region_lfos = if r.region.mod_lfo_to_pitch_cents.abs() > 0.5
+                    || r.region.vib_lfo_to_pitch_cents.abs() > 0.5
+                {
+                    Some(RegionLfos {
+                        mod_freq_hz: r.region.mod_lfo_freq_hz.clamp(0.05, 20.0),
+                        mod_delay_s: r.region.mod_lfo_delay_s.clamp(0.0, 5.0),
+                        mod_to_pitch_cents: r.region.mod_lfo_to_pitch_cents.clamp(-1200.0, 1200.0),
+                        vib_freq_hz: r.region.vib_lfo_freq_hz.clamp(0.05, 20.0),
+                        vib_delay_s: r.region.vib_lfo_delay_s.clamp(0.0, 5.0),
+                        vib_to_pitch_cents: r.region.vib_lfo_to_pitch_cents.clamp(-1200.0, 1200.0),
+                    })
+                } else {
+                    None
+                };
                 pending[count] = Some(TriggerShape {
                     samples: r.samples.clone(),
                     root_freq: midi_to_hz_tuned(r.region.pitch_keycenter, tuning).max(20.0),
@@ -455,6 +509,7 @@ impl SampleInstrumentVoice {
                     region_adsr,
                     region_filter,
                     region_loop,
+                    region_lfos,
                 });
                 count += 1;
             }
@@ -475,6 +530,7 @@ impl SampleInstrumentVoice {
                 region_adsr: None,
                 region_filter: None,
                 region_loop: None,
+                region_lfos: None,
             };
             self.fire_slot(&shape, accent);
         }
@@ -494,6 +550,13 @@ impl SampleInstrumentVoice {
         slot.region_adsr = shape.region_adsr;
         slot.region_filter = shape.region_filter;
         slot.region_loop = shape.region_loop;
+        slot.region_lfos = shape.region_lfos;
+        // Reset LFO phases + delay countdowns on every trigger so
+        // each new note starts the LFO cycle from zero.
+        slot.mod_lfo_phase = 0.0;
+        slot.vib_lfo_phase = 0.0;
+        slot.mod_lfo_delay_remain_s = shape.region_lfos.map(|l| l.mod_delay_s).unwrap_or(0.0);
+        slot.vib_lfo_delay_remain_s = shape.region_lfos.map(|l| l.vib_delay_s).unwrap_or(0.0);
         slot.pos = 0.0;
         slot.adsr_stage = AdsrStage::Attack;
         slot.adsr_value = 0.0;
@@ -670,6 +733,55 @@ impl SampleInstrumentVoice {
             rate *= flutter_factor;
         }
 
+        // SF2 LFO pitch modulation — modLfoToPitch + vibLfoToPitch.
+        // Each LFO has its own delay (silent until elapsed) +
+        // frequency; the depths sum into a single cents offset that
+        // converts to a multiplicative rate factor via the same
+        // `1 + cents · ln(2)/1200` small-angle approximation
+        // Mellotron uses.  Independent state per slot so polyphonic
+        // notes don't lock-step their wobble.
+        if let Some(lfos) = slot.region_lfos {
+            let dt = 1.0 / sr;
+            // Mod LFO.
+            let mod_active = if slot.mod_lfo_delay_remain_s > 0.0 {
+                slot.mod_lfo_delay_remain_s -= dt;
+                false
+            } else {
+                true
+            };
+            slot.mod_lfo_phase += lfos.mod_freq_hz * dt;
+            if slot.mod_lfo_phase >= 1.0 {
+                slot.mod_lfo_phase -= 1.0;
+            }
+            let mod_cents = if mod_active {
+                (slot.mod_lfo_phase * std::f32::consts::TAU).sin() * lfos.mod_to_pitch_cents
+            } else {
+                0.0
+            };
+            // Vib LFO.
+            let vib_active = if slot.vib_lfo_delay_remain_s > 0.0 {
+                slot.vib_lfo_delay_remain_s -= dt;
+                false
+            } else {
+                true
+            };
+            slot.vib_lfo_phase += lfos.vib_freq_hz * dt;
+            if slot.vib_lfo_phase >= 1.0 {
+                slot.vib_lfo_phase -= 1.0;
+            }
+            let vib_cents = if vib_active {
+                (slot.vib_lfo_phase * std::f32::consts::TAU).sin() * lfos.vib_to_pitch_cents
+            } else {
+                0.0
+            };
+            let total_cents = mod_cents + vib_cents;
+            // ln(2) / 1200 — same Taylor-series approximation used in
+            // the Mellotron flutter path.  Accurate to <0.01 % within
+            // ±1200 cents (the clamp range applied at trigger time).
+            let lfo_factor = 1.0 + total_cents * 0.000_577_6;
+            rate *= lfo_factor;
+        }
+
         // Resolve loop bounds + active flag.  Per-region override
         // (SFZ / SF2 path) wins when present; falls back to the
         // global `sample_loop_*` knobs for the single-WAV path.

src/audio/mod.rs

@@ -7,6 +7,7 @@ pub mod audio_load;
 pub mod dsp;
 pub mod gr_levels;
 pub mod onset;
+pub(crate) mod sf2_generators;
 pub mod sf2_loader;
 pub mod sfz_loader;
 pub mod spectrum;