reasampler/TODO-1.0.md

# TODO-1.0

Post-1.0 enhancement queue for the ReaSampler 9000 instrument. Three items, in
Daniel's ordering (2026-07-28). Deliberately specified at the level of product
intent, user-visible behavior, and acceptance criteria — **no implementation
design, no file/module references**. These were authored while Phase Q was
restructuring the tree; the implementing engineer maps each spec onto the
post-Q layout at execution time. Each item preserves Daniel's raw ask verbatim
as the source of truth, then breaks it into behavior, open questions, and an
observable acceptance gate.

A follow-up answer round from Daniel (2026-07-28) settled most of the open
questions. Each item now carries his follow-up verbatim alongside the original
ask; settled answers are folded into **Behavior** (marked *settled by
follow-up*), and only the genuinely unresolved remainder stays under **Open
questions**.

Ordering note: item 1's curve/overlay treatment explicitly anticipates item 2's
filter envelope ("filter to be added"), and item 3 layers on both. They can land
in sequence or together, but 1 and 2 are prerequisites for 3's full surface.

---

## 1 — Envelope editor: per-deck radio switch, segment curve dials, overlay recolor

**Daniel's ask (verbatim, 2026-07-28).**

> The VST envelope editor visual is a great start but we need to add some
> features. The Amp AHDSR is currently always displayed. We need to add a radio
> switch to the corner of each env knob deck which makes THAT envelope editable
> via the graphic waveform overlay. This is currently the amp and pitch
> envelopes, with filter to be added (see below). All envelopes (amp AHDSR,
> Pitch AD, Filter AHDSR) should be enhanced to have editable segment curve
> values. This should be an exponential function with the exponent scalar
> parameter for each sloped segment having possible values from 0.1 to 10. The
> knob deck radial knobs for the sloped curvable segments will have an INNER
> dial, with its own inner arc, hover accent (tertiary purple), needle, and
> numerical label which controls the curve for that sloped segment. Also the
> graphical envelope editor draws its segments in secondary blue, which
> contrasts poorly against the primary green waveform display. Change those to
> tertiary purple.

**Daniel's follow-up (verbatim, 2026-07-28).**

> yes, one overlay (or none). Everything besides Hold and Sustain, right? "is
> 1.0 the linear neutral" CLAUDE, y=x^1.0 is linear!! of course! yes dragging
> on the segment (add a round knot midsegment) adjusts the curve.

**Intent.** Grow the envelope-overlay editor from an amp-only fixture into the
shared graphical surface for every envelope in the instrument, and give every
envelope shapeable (non-linear) segments — while fixing the blue-on-green
contrast failure.

**Behavior.**

- **Radio switch per envelope deck.** Each envelope knob-deck group (currently
  AMP ENVELOPE and PITCH ENV; the filter envelope joins when item 2 lands)
  gains a radio switch in the corner of its deck. Selecting a deck's radio
  makes *that* envelope the one displayed and editable in the graphic waveform
  overlay — replacing today's behavior where the Amp AHDSR is always the
  displayed envelope. The switch is exclusive: **one overlay-active envelope at
  a time, or none** — no-envelope-shown is a valid state, not an error.
  *(Settled by follow-up.)*
- **Segment curve values on all envelopes.** Amp AHDSR, Pitch AD, and Filter
  AHDSR all gain an editable curve value per *sloped* segment. The curve is an
  exponential function; the per-segment parameter is the exponent scalar,
  range **0.1 to 10**.
- **Which segments are sloped.** **Every stage except Hold and Sustain** — for
  an AHDSR that is Attack, Decay, and Release; for the Pitch AD, both stages.
  *(Settled by follow-up.)*
- **Linear neutral.** Exponent **1.0 is the linear neutral** (y = x^1.0 is
  linear). *(Settled by follow-up — emphatically.)*
- **Curve editing in the overlay.** Dragging on a segment in the overlay
  **adds a round mid-segment knot** whose drag adjusts that segment's curve —
  the overlay is a curve-edit surface in its own right, alongside (not instead
  of) the inner dial. *(Settled by follow-up.)*
- **Inner dial on curvable-segment knobs.** Every knob-deck radial knob that
  controls a sloped, curvable segment gains an **inner dial**: its own inner
  arc, its own hover accent (tertiary purple), its own needle, and its own
  numerical label. The inner dial controls the curve exponent for that
  segment; the outer knob keeps controlling the segment's time/level value as
  today.
- **Overlay recolor.** The graphical envelope editor's segments change from
  secondary blue to **tertiary purple** (secondary blue contrasts poorly
  against the primary green waveform behind it).

**Open questions.**

- **Default overlay selection on open.** Exclusivity and the none-state are
  settled; what is the default when the editor opens — the Amp AHDSR (today's
  behavior) or none?
- **Pre-existing instances.** Should saved instances from before this change
  load with every curve at the linear equivalent (exponent 1.0) so their sound
  is unchanged? (The neutral point itself is settled; this is only the
  load-behavior half. The product requirement is "old instances sound
  identical.")

**Acceptance criteria.**

- Each envelope deck shows a corner radio switch; activating one puts that
  envelope in the overlay, editable there, and the overlay tracks the switch
  immediately. At most one envelope is overlay-active; with none active, the
  overlay draws no envelope.
- Every curvable-segment knob shows the inner dial (inner arc, tertiary-purple
  hover accent, needle, numeric label); sweeping it through 0.1 → 10 visibly
  reshapes the overlay segment and audibly reshapes the envelope on played
  notes. Hold and Sustain knobs carry no inner dial.
- Dragging on an overlay segment adds a round mid-segment knot; dragging the
  knot adjusts that segment's curve, and the segment's inner dial reflects the
  same value.
- Overlay envelope segments render in tertiary purple and are clearly legible
  against the primary green waveform.
- A project saved before this change reopens with unchanged audible envelope
  behavior.

---

## 2 — MM preamp Filter: resonant HP/LP stage in the voice pipeline

**Daniel's ask (verbatim, 2026-07-28).**

> MM preamp Filter: We must implement a new processing point in the sampler
> audio pipeline, after pitch env, before amp, for filtering. The processor for
> this will be based on code I wrote for the cortex M4 for resonant high and
> lowpass filtering. The filter will have parameters for mode, cutoff, Q, and
> mod amt, then the AHDSR controls as described above. The knob deck row will
> then be relaid out in signal flow order: pitch -> filter -> amp

**Daniel's follow-up (verbatim, 2026-07-28).**

> modes beyond the pass filters will be added later. cutoff range full audio
> spectrum, log scaled, fully open to fully closed, Q should go from 0.1 to 10
> again, scaled around root 2 at the center. mod amt targets cutoff, -100% -
> +100% to cover full range from either end. per-voice. label it "Filter"

**Intent.** Add the instrument's first filter stage — resonant high-pass and
low-pass — as a new fixed point in the per-voice signal path, with its own
AHDSR envelope, and make the knob-deck row read in signal-flow order.

**Behavior.**

- **Pipeline position.** A new processing point in the sampler audio pipeline:
  **after the pitch envelope, before the amp stage.**
- **DSP source.** The filter processor is based on Daniel's own Cortex-M4
  resonant high/lowpass filter code. **That code is an input Daniel supplies at
  implementation time** — it is not in this repo and this spec does not
  characterize it beyond "resonant high and lowpass."
- **Parameters.** Mode, cutoff, Q, and mod amt — then the AHDSR controls,
  treated exactly as item 1 specifies (curvable sloped segments with inner
  dials, overlay editability via the filter deck's radio switch).
  *(Ranges settled by follow-up:)*
  - **Mode:** high-pass and low-pass now; **modes beyond the pass filters are
    explicitly deferred to later.**
  - **Cutoff:** the **full audio spectrum, log scaled**, from fully open to
    fully closed.
  - **Q:** **0.1 to 10** (the curve-exponent range again), scaled so **√2 sits
    at the center** of the control.
  - **Mod amt:** **bipolar, −100% to +100%**, targeting **cutoff** — covering
    the full range from either end.
- **Per-voice.** The filter processes **per voice** — each sounding voice runs
  its own filter with its own envelope state. *(Settled by follow-up.)*
- **Label.** The user-facing deck-group label is **"Filter"**. "MM preamp" is
  working shorthand for the DSP lineage, not UI text. *(Settled by
  follow-up.)*
- **Deck reorder.** The knob deck row is relaid out in signal-flow order:
  **pitch → filter → amp**.

**Open questions.**

- **Other mod sources.** Mod amt targeting cutoff is settled; whether any
  other mod sources (velocity, key-tracking) are in scope now or deferred is
  unstated.
- **Parameter storage: per-zone or per-instance.** Per-voice *processing* is
  settled, but it is compatible with either storage side. Existing playback
  parameters live per-zone with Sample/Zone panel parity; VOICE and MASTER are
  per-instance exceptions. Which side do the filter *parameters* fall on?
- **Neutral default.** Should the filter default to a bypass/neutral state so
  pre-existing saved instances (and freshly loaded captures) sound unchanged
  until the user engages it?

**Acceptance criteria.**

- With the filter engaged, played notes are audibly filtered at the specified
  pipeline point: the filter acts on pitched (post-pitch-envelope) signal, and
  the amp envelope still shapes the filtered result (audible ordering:
  pitch → filter → amp).
- Mode, cutoff, Q, and mod-amt controls appear in a deck group labeled
  **"Filter"**; the filter AHDSR gets the full item-1 treatment (curve inner
  dials, corner radio switch, tertiary-purple overlay editing).
- Cutoff sweeps the full audio spectrum on a log scale, from fully open to
  fully closed; Q spans 0.1 → 10 with √2 at the control's center; mod amt at
  −100% and at +100% each drive cutoff across the full range, from opposite
  ends.
- High Q audibly emphasizes the cutoff region (resonance) in both HP and LP
  modes.
- Two simultaneously sounding voices at different envelope phases are filtered
  independently (per-voice processing is audible, not a shared instance-wide
  filter).
- The deck row reads pitch → filter → amp left-to-right.
- A project saved before this change reopens sounding identical (pending the
  neutral-default confirmation above).

---

## 3 — Alternative Spline EGs: hard/smooth multi-segment monotonic splines

**Daniel's ask (verbatim, 2026-07-28).**

> Alternative Spline EGs: Every processor which has an envelope will have the
> ability to change the Staged EG to a Spline EG, based on the monotonic
> splines for the velocity curve. HOWEVER, we will need to enhance the (singly
> implemented, multi referenced) spline algorithm to support multiple segments
> that DON'T minimally smooth the spline, so that hard points are possible. In
> other words, the contour of the EG will be defined by 1 or more monotonic
> spline functions which together form the full time function for that
> processor, such that the first three points could make a curved segment,
> which connects at a sharp angle to the next three points, finishing out the
> contour over the full sample length. Control-clicking a point makes it a
> "hard" or "smooth" point (toggled, smooth by default) which when hard does no
> curve smoothing on either side segment, forming the natural sharp angle
> instead of a continuous derivative. This enhanced spline drawing will be used
> for the velocity-amp transfer curve as well as the pitch, filter, and amp EGs
> (if they are in spline mode).

**Daniel's follow-up (verbatim, 2026-07-28).**

> dual state, save but inactive. Default Curve Spline is a smooth y=1-x. Gate
> mode is not available when the Spline is used, spline always covers the full
> sample length. The spline curves don't have to rise AND fall, they also
> aren't globally monotone, the default curve is a smooth downward slope over
> the length. all the soft points between any hard points will be
> smooth/monotone.

**Intent.** Offer a free-drawn alternative to every staged envelope: the user
switches any EG from Staged to Spline mode and draws the contour directly, with
the monotonic-spline machinery already proven by the velocity curve — enhanced
so sharp corners are possible, not everything smoothed.

**Behavior.**

- **Mode toggle per EG.** Every processor that has an envelope (pitch, filter,
  amp) can switch its Staged EG to a **Spline EG**.
- **Dual state — save but inactive.** Both the Staged and the Spline state are
  persisted; switching modes keeps the inactive one **saved but inactive**. No
  conversion, no discard — round-tripping Staged↔Spline restores the other
  mode's shape untouched. *(Settled by follow-up.)*
- **Gate unavailable in Spline mode.** Gate mode is **not available while a
  Spline EG is active**; the spline **always covers the full sample length** —
  a pure time function over the sample, i.e. the Trigger/one-shot playback
  model. *(Settled by follow-up.)*
- **Not globally monotone.** Spline contours **don't have to rise and fall and
  are not globally monotone**; the monotone guarantee is per-segment — **all
  soft points between any hard points are smooth/monotone** (no overshoot
  between adjacent points). *(Settled by follow-up.)*
- **Default contour.** A new Spline EG defaults to a **smooth y = 1 − x** — a
  smooth downward slope over the full sample length. (Read as the Spline-EG
  default contour; not a change to the velocity→amp transfer curve's existing
  default.) *(Settled by follow-up.)*
- **Spline foundation.** The Spline EG is based on the monotonic splines used
  for the velocity curve. The spline algorithm is singly implemented and
  multi-referenced; the enhancement below applies to that one implementation
  and flows to every consumer.
- **Hard points.** The algorithm is enhanced to support **multiple segments
  that don't minimally smooth the spline**, so hard points are possible: the
  EG contour is defined by **one or more monotonic spline functions** which
  together form the full time function for that processor — e.g. the first
  three points form a curved segment that connects **at a sharp angle** to the
  next three points, finishing the contour over the **full sample length**.
- **Hard/smooth gesture.** **Control-clicking a point toggles it hard/smooth
  (smooth by default).** A hard point does no curve smoothing on either
  adjacent segment — the natural sharp angle stands instead of a continuous
  derivative.
- **Shared across consumers.** The enhanced spline drawing serves the
  **velocity→amp transfer curve** as well as the pitch, filter, and amp EGs
  (when those are in spline mode). The velocity curve gains hard-point support
  by the same enhancement.

**Open questions.**

- **Time-axis storage.** Full-sample coverage is settled ("spline always
  covers the full sample length"); what remains is only whether the stored
  contour is normalized to the sample length (so it rescales when a
  different-length capture loads) or anchored some other way.
- **Point-editing grammar.** Point add/delete gestures and any point-count
  bound are unstated. The velocity-curve popup already established right-click
  node delete — reuse of that grammar seems natural but is Daniel's call.
- **Staged controls while Spline is active.** Sound-wise the staged EG is
  inactive in Spline mode (settled by dual-state). Still open at the UI level:
  do the staged segment knobs/inner dials stay editable (editing the dormant
  staged state) or go inert/greyed until the user switches back?

**Acceptance criteria.**

- Each of the pitch, filter, and amp EGs offers a Staged/Spline mode switch;
  in Spline mode the overlay (via the item-1 radio switch) shows and edits the
  drawn contour, and played notes audibly follow it.
- Control-click toggles any point hard/smooth; points are smooth by default; a
  hard point renders a visible sharp angle with no smoothing on either
  adjacent segment, and the discontinuous slope is audible where the
  modulation target makes it so (e.g. a pitch EG corner).
- A contour of several segments joined at hard points plays back over the full
  sample length exactly as drawn — including contours that rise and fall
  freely (no globally-monotone restriction), with no overshoot between any
  adjacent pair of points.
- A freshly created Spline EG shows the smooth y = 1 − x default contour.
- While a Spline EG is active, Gate mode is not selectable; the spline plays
  as a pure time function over the full sample length.
- Staged↔Spline round-trip preserves both states: switch to Spline, draw,
  switch back — the staged values are exactly as left; switch forward again —
  the spline contour is exactly as drawn. Both survive save/reload.
- The velocity→amp transfer-curve editor supports the same control-click
  hard/smooth toggle with identical rendering behavior.