Add scoped LFO modulation for synths and samplers

Author: rec

README.md

@@ -55,7 +55,15 @@ disable Python DSP to prevent a fallback. Modulated sample voices still resolve
 controls one frame at a time so evaluation stops at source exhaustion. This API
 allocates per call and does not establish live callback deadline guarantees.
 
-Decoding remains with the caller. Curved envelopes, named generators, filters,
+Named seconds-clock LFOs now drive amplitude and tuning in both instruments.
+They support sine, square, and triangle shapes, delay/fade-in, and voice, part,
+or instrument ownership as allowed by uFor. Shared sources continue through
+silence, and snapshots retain their exact phase anchors. Standalone
+`enge.lfo.lfo_samples()` also samples canonical uFor rate/reset event states.
+Prepared instrument traces do not yet carry addressed LFO events; their LFO
+rates remain authored settings. See the [LFO contract](plan/lfo-numerics.md).
+
+Decoding remains with the caller. Curved envelopes, named envelopes, filters,
 layer crossfades, delayed or offset sample starts, event bindings, other
 modulation targets, and fade
 retirements fail explicitly. The PyTorch backend is not yet implemented.
@@ -98,3 +106,9 @@ waveform, writes WAV artifacts, and verifies lossless FLAC encoding using the
 `.pytest_cache/d/audio/synth-demo-native.flac`.
 Completed demos are published with Reccy's shared `atomic_output` helper, so a
 failed copy preserves the previous demo. Reccy is a development dependency.
+
+Run `uv run pytest test/test_lfo_demo.py` for a two-second vibrato/tremolo demo,
+with a sine synth on the left and a sampled harmonic tone on the right. Both
+receive a live gain change. Listen to `.pytest_cache/d/audio/lfo-demo-numpy.flac`
+or `.pytest_cache/d/audio/lfo-demo-native.flac`; the test compares independent
+audio oracles and verifies lossless encoding before publishing either file.

plan/engine-execution.md

@@ -21,18 +21,20 @@ The current implementation in `src/enge/synth.py` provides the first dynamic
 synth reference: held linear envelopes, explicit routes, minimum hold, phase
 synchronization, static tuning, and live amplitude/tuning control routes. It
 consumes uFor trigger contexts, retains scoped smoothing trajectories, and
-restores them with voice state. Other modulation targets, named generators,
-and filters are not implemented. The Rust backend realizes
+restores them with voice state. Named seconds-clock LFOs now drive the same
+amplitude/tuning routes; other targets, named envelopes, and filters remain
+unimplemented. The Rust backend realizes
 the same numerical synth profile through explicit `backend="native"` selection;
 `"numpy"` remains the default. PyTorch compilation remains future work.
 Existing waveform start/length/period behavior remains a regression requirement
 during synth consolidation.
 
-`src/enge/sampler.py` now implements the NumPy source-traversal core with linear
+`src/enge/sampler.py` implements NumPy and Rust source traversal with linear
 interpolation, shared immutable decoded audio, live pitch arrays, fractional
 effective releases, and serializable cursor state. `SampleVoiceRenderer` and
 `src/enge/sample_instrument.py` now integrate shared envelope timing, scoped
-controls, routing, and prepared uFor actions. The Rust sampler is next.
+controls, routing, and prepared uFor actions. Both instrument renderers now share
+scoped LFO sources under the [LFO numerical contract](lfo-numerics.md).
 
 ## Ownership and existing contracts
 
@@ -238,7 +240,8 @@ is still distinct from another voice's source, even when both use one template.
 | Logical gate and retirement | Exact prepared actions; never smoothed with expression controls. Sustain decisions remain in uFor. |
 | Envelope durations derived from key/velocity | Latched at onset, following the existing uFor contract. |
 | Envelope structure, waveform shape/duty, sample identity, slice/loop bounds, direction, output layout, routing topology | Fixed for the prepared voice definition; no active-voice mutation API in this profile. |
-| LFOs, filters, richer automation, and structural transitions | Separate declared extensions with their own dynamic conformance cases before support is enabled. |
+| LFOs | Seconds-clock value/weight realization is implemented; addressed instrument rate/reset actions remain a future uFor extension. |
+| Filters, richer automation, and structural transitions | Separate declared extensions with their own dynamic conformance cases before support is enabled. |
 
 This is an initial support boundary, not a claim that structural edits can never
 be supported. Such edits need explicit state transfer or crossfade semantics.
@@ -517,7 +520,17 @@ Implementation status and remaining order:
    Sampler snapshots reject backend mismatches even when silent. Modulated
    voices retain scalar Python control resolution to stop at natural exhaustion;
    this milestone does not claim real-time callback performance.
-5. Further generators, processing, and structural changes one specified feature
+5. Named seconds-clock LFOs now render through NumPy and Rust with shared
+   conformance. They retain uFor's exact phase anchors, rate/reset semantics,
+   separate activation weight, and scope ownership. Both synth and sampler
+   consume them through existing amplitude/tuning routes and restore their
+   source identities. Tests cover silent shared sources, release tails, exact
+   duty ties, fractional timing, and large clocks. A two-second FLAC regression
+   demonstrates tremolo, vibrato, and live gain on synth and sampled tones.
+   The standalone source API accepts canonical LFO event states; prepared
+   instrument traces still need a portable addressed rate/reset action before
+   those events can be delivered through `advance`. See [details](lfo-numerics.md).
+6. Further generators, processing, and structural changes one specified feature
    at a time. Do not introduce a generic DSP graph or host to complete these steps.
 
 ### Phase consolidation timing check, 2026-09-16

plan/lfo-numerics.md

@@ -0,0 +1,93 @@
+# LFO realization
+
+## Supported profile
+
+enge renders uFor's seconds-clock LFOs for both synths and samplers, selecting
+NumPy or Rust with the instrument's existing `backend` argument. Sine, square,
+and triangle shapes retain the canonical duty-cycle equations, including duty
+zero and one. LFO values are bipolar. Delay and fade-in affect a separate
+activation weight, never the phase clock.
+
+`enge.lfo.lfo_samples(definition, state, start, frames, sample_rate, backend)`
+returns a float64 `(frames, 2)` array containing value and weight. `state` is the
+canonical `ufor.lfo.LFOState`. Frames address the same absolute seconds clock as
+its rational event anchors. Rendering observes state without re-anchoring it.
+Use `ufor.lfo.initial_lfo` and `ufor.lfo.lfo_event` to initialize and apply events;
+serialize the canonical state to restore a standalone source.
+
+Beat clocks require a host tempo mapping and remain explicitly unsupported in
+this audio profile. Named envelopes and other modulation targets remain outside
+this milestone.
+
+## Timing and numerical boundaries
+
+At time `t`, phase is exactly `(state.phase + state.rate * (t-state.at)) mod 1`.
+A rate event advances using the previous rate before installing the next one.
+It preserves phase and activation age. Zero rate freezes phase. Rate changes are
+piecewise constant; continuous rate ramps are not part of uFor's current LFO
+contract. An event affects observations at its time and later. For a fractional
+event time, render the earlier integer observations with the previous state,
+apply the event, then render from the first integer observation at or after it.
+
+Reset policies follow uFor: `free` ignores trigger/transport events, `trigger`
+responds to trigger, and `transport` responds to explicit transport events. An
+explicit reset always resets phase and activation age, retaining current rate.
+A render boundary is never a reset or transport event.
+
+The NumPy reference samples uFor's independent scalar equations. Rust evaluates
+waveforms and activation arithmetic in a detached numerical loop with owned
+input and output arrays. Python resolves rational phase, wrap/duty boundaries,
+and activation boundaries before crossing the binding. Square polarity is
+resolved before converting to float. Triangle spans use a normalized coordinate
+within the selected branch, avoiding cancellation when duty approaches zero or
+one. Complete unobserved cycles are skipped using exact rational reduction.
+The numerical kernel receives arrays, without Pydantic or Fraction operations.
+
+Phase continues during delay and fade-in. At delay's endpoint weight is zero
+when a fade exists, otherwise one. During fade it increases linearly to one.
+Route evaluation applies weight after mapping: addition fades from zero;
+multiplication fades from one. Rust bounds final observations to their declared
+bipolar/unit domains to contain floating-point roundoff at endpoints.
+
+## Instrument ownership and event boundary
+
+LFO names are local to a sound-setting definition. Repeated bindings to one
+named source observe the same state. Voice scope creates a fresh source at the
+voice's start frame. Instrument and part sources use frame zero as their clock
+origin and continue algebraically through silent intervals. A joining voice does
+not send a trigger event to an existing shared source. Part sources are separate
+for each part; instrument instances never share state. Sampler slot/group
+ownership follows uFor validation; shared sampler LFOs belong in instrument
+settings. Instrument and slot modulation still compose per voice before mixing.
+
+Both instrument snapshots include LFO anchors and their owner identities,
+alongside existing control ramps and voice-to-source references. A new onset
+using an old trigger ID cannot reassign a release tail's voice LFO.
+
+Prepared uFor instrument traces currently contain lifecycle and control actions,
+not addressed LFO rate/reset events. Instrument integration therefore realizes
+authored LFO settings and voice/shared ownership. Dynamic rate, trigger,
+transport, and explicit reset events are supported through the standalone
+canonical state API. Exposing those events through prepared instrument traces
+requires a later uFor contract extension; this implementation adds no private
+trace vocabulary and does not reinterpret control observations as LFO events.
+
+## Acceptance
+
+Shared tests compare float arrays before writing at least one second of 48 kHz
+WAV audio, using `atol=1e-10`, `rtol=1e-9`. Coverage includes shapes/duty endpoints,
+fractional delay/fade boundaries, irregular partitions, rational rate events,
+zero rate, all reset policies, exact duty ties, large frame coordinates, scoped
+silent advancement, release tails, reused trigger IDs, and JSON restores.
+Native checks disable scalar reference evaluation and reject invalid span layouts.
+
+The two-second listening regression combines vibrato, tremolo, and a live gain
+ramp: a sine synth on the left and a sampled harmonic tone on the right. Expected
+pitch is integrated independently at higher precision; the sampler oracle uses
+linear interpolation of the supplied asset. Both backends publish verified
+lossless FLAC through reccy's existing atomic-output helper. This establishes
+numerical behavior, not live callback performance.
+
+## Additional work beyond the prompt
+
+None.

src/enge/_native.pyi

@@ -2,6 +2,9 @@ from typing import Literal
 
 import numpy as np
 
+def render_lfo(
+    waveform: int, phases: np.ndarray, envelope: np.ndarray, frames: int
+) -> np.ndarray: ...
 def render(
     waveform: int,
     duty: float,

src/enge/lfo.py

@@ -0,0 +1,95 @@
+"""Sample uFor LFO observations without changing their exact event anchors."""
+
+from fractions import Fraction
+from math import ceil
+from typing import Literal
+
+import numpy as np
+from ufor import lfo
+from ufor.oscillator import Waveform
+
+
+def lfo_samples(
+    definition: lfo.LFO,
+    state: lfo.LFOState,
+    start: int,
+    frames: int,
+    sample_rate: int,
+    backend: Literal["numpy", "native"] = "numpy",
+) -> np.ndarray:
+    """Return bipolar value and activation weight columns on the seconds clock.
+
+    Use uFor's lfo_event to apply rate/reset events before their addressed sample.
+    Rate changes retain phase and activation age. Rendering does not re-anchor
+    state, so silent intervals, partitions, and restores share the same timeline.
+    """
+    if definition.clock != "seconds" or sample_rate <= 0 or frames < 0:
+        raise ValueError(
+            "LFO rendering requires a seconds clock and valid frame layout"
+        )
+    at = Fraction(start, sample_rate)
+    if at < state.at or at < state.started_at:
+        raise ValueError("LFO query precedes its current state")
+    if backend == "numpy":
+        observations = [
+            lfo.lfo_at(definition, state, Fraction(start + i, sample_rate))
+            for i in range(frames)
+        ]
+        return np.array(
+            [[v.value, v.weight] for v in observations], dtype=np.float64
+        ).reshape(frames, 2)
+    if backend != "native":
+        raise ValueError(f"Unknown LFO backend: {backend}")
+    from . import _native
+
+    # Resolve discontinuities exactly before converting phase arithmetic to float.
+    # Spans never straddle a wrap or duty edge. This also handles rates above the
+    # output rate without iterating through unobserved cycles.
+    phase = lfo.phase_at(state, at)
+    step = (state.rate / sample_rate) % 1
+    spans: list[list[float]] = []
+    first = 0
+    while first < frames:
+        rising = phase < definition.duty_cycle
+        boundary = definition.duty_cycle if rising else Fraction(1)
+        count = (
+            min(frames - first, ceil((boundary - phase) / step))
+            if step
+            else frames - first
+        )
+        origin, increment = phase, step
+        if definition.waveform == Waveform.triangle:
+            width = definition.duty_cycle if rising else 1 - definition.duty_cycle
+            origin = (
+                phase / width if rising else (phase - definition.duty_cycle) / width
+            )
+            increment = step / width if count > 1 else Fraction(0)
+        spans.append(
+            [first, first + count, float(origin), float(increment), float(rising)]
+        )
+        phase = (phase + count * step) % 1
+        first += count
+    age = at - state.started_at - definition.delay
+    weights: list[list[float]] = [[0, frames, 1, 0, 0, 1, 0]]
+    delayed = min(frames, max(0, ceil(-age * sample_rate)))
+    weights.append([0, delayed, 0, 0, 0, 1, 0])
+    if definition.fade_in:
+        last = min(frames, ceil((definition.fade_in - age) * sample_rate))
+        if delayed < last:
+            weights.append(
+                [
+                    delayed,
+                    last,
+                    float((age + Fraction(delayed, sample_rate)) / definition.fade_in),
+                    float(1 / (definition.fade_in * sample_rate)),
+                    0,
+                    1,
+                    delayed,
+                ]
+            )
+    return _native.render_lfo(
+        [Waveform.sine, Waveform.square, Waveform.triangle].index(definition.waveform),
+        np.array(spans, dtype=np.float64).reshape(-1, 5),
+        np.array(weights, dtype=np.float64),
+        frames,
+    )

src/enge/sample_instrument.py

@@ -36,6 +36,7 @@ class SamplerSnapshot(Model, frozen=True):
     frame: int
     voices: list[SampleVoiceSnapshot]
     contexts: list[synth.ControlContext]
+    lfos: list[synth.LFOSource]
     backend: Literal["numpy", "native"]
 
 
@@ -133,6 +134,7 @@ def __init__(
             definition.sample_rate,
             definition.document.body.settings.controls,
             [definition.document.body.settings, *definition.settings.values()],
+            backend,
         )
 
     def advance(
@@ -157,6 +159,7 @@ def snapshot(self) -> SamplerSnapshot:
             frame=self.frame,
             voices=list(self.voices.values()),
             contexts=self.controls.contexts,
+            lfos=self.controls.lfos,
             backend=self.backend,
         ).model_copy(deep=True)
 
@@ -176,6 +179,7 @@ def restore(self, snapshot: SamplerSnapshot) -> None:
         self.frame = snapshot.frame
         self.voices = {v.voice_id: v for v in snapshot.voices}
         self.controls.contexts = snapshot.contexts
+        self.controls.lfos = snapshot.lfos
 
     def _apply(self, action: instrument_trace.TraceAction) -> None:
         if self.controls.apply(action) or isinstance(
@@ -327,10 +331,7 @@ def _validate_settings(settings: processing.SoundSettings) -> None:
         raise synth.EngineError(
             "Only sample volume and tuning processing are implemented"
         )
-    if settings.envelopes or settings.lfos:
-        raise synth.EngineError("Named sample generators are not implemented")
-    if any(not isinstance(b, processing.ControlBinding) for b in settings.bindings):
-        raise synth.EngineError("Only control bindings are implemented")
+    synth.validate_generators(settings)
     if any(
         p.target.name != "processing"
         or p.target.parameter not in ("amplitude", "tuning_cents")