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.

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.

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.
• 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.
• 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.

• Radio exclusivity + default. "Radio" implies exactly one envelope is overlay-active at a time across all decks — confirm that reading, and confirm the Amp AHDSR remains the default selection on open.
• Which segments are "sloped." Per envelope type, which segments carry a curve dial? (E.g. Attack/Decay/Release obviously slope; Hold and Sustain presumably do not — needs Daniel's confirmation per stage.)
• Curve default and neutral point. Is exponent 1.0 the linear/neutral default, and should existing saved instances load with all curves at the linear-equivalent so their sound is unchanged? (Persistence extension is implied; the product requirement is only "old instances sound identical.")
• Curve editing in the overlay. Is the curve exponent editable from the overlay itself (e.g. dragging a segment's belly), or is the inner dial the sole curve-edit affordance and the overlay edits node positions only? Daniel's ask specifies the dial; overlay curve-drag is not stated either way.

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.
• 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.
• 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

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).
• Deck reorder. The knob deck row is relaid out in signal-flow order: pitch → filter → amp.

Open questions.

• Mode list. Is mode a discrete selector, and over exactly which entries? "Resonant high and lowpass" confirms HP and LP; whether band-pass/notch or multiple slopes exist depends on the Cortex-M4 source and Daniel's intent.
• Ranges and units. Cutoff range (Hz), Q range, and mod-amt range/polarity (unipolar or bipolar?) are unstated — likely settled by the Cortex-M4 code plus a Daniel call at implementation time.
• Mod routing. "Mod amt" presumably scales the filter AHDSR's modulation of cutoff — confirm the target is cutoff and whether any other mod sources (velocity, key-tracking) are in scope now or deferred.
• Scope: per-zone or per-instance. Existing playback parameters live per-zone with Sample/Zone panel parity; VOICE and MASTER are per-instance exceptions. Which side does the filter 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?
• Display name. Is "MM Preamp Filter" the user-facing label for the deck group, or working shorthand?

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 filter deck group; the filter AHDSR gets the full item-1 treatment (curve inner dials, corner radio switch, tertiary-purple overlay editing).
• High Q audibly emphasizes the cutoff region (resonance) in both HP and LP modes.
• 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).

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.
• 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.

• Staged↔Spline toggle semantics. What happens to a Staged EG's values when toggling to Spline mode and back? (Convert the staged shape into an initial spline? Keep two independent per-mode states? Discard?) Daniel has not said — this materially shapes both UX and persistence and needs his call.
• Gate-mode sustain/release. A Staged Gate envelope holds at Sustain and releases on note-off; a spline contour drawn "over the full sample length" is a pure time function. How do note-off, sustain, and looped playback map onto a Spline EG in Gate mode? (Trigger/one-shot is the natural fit; Gate needs a stated rule.)
• Time axis. Is the contour's time axis normalized to the sample length (so it rescales with the sample) or absolute seconds? "Over the full sample length" suggests sample-relative — confirm, especially for looped sustain.
• Monotonicity meaning. The velocity spline is monotone to prevent overshoot on a transfer curve. An EG contour must rise and fall; presumably "monotonic" here means the per-segment no-overshoot property (values never exceed the segment's endpoints), not a globally monotone function — confirm the intended guarantee.
• 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.
• Interaction with item-1 curve dials. In Spline mode, do the staged segment knobs/inner dials go inert (shape comes wholly from the spline), or is some hybrid intended? Presumably the former — confirm.

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.
• The velocity→amp transfer-curve editor supports the same control-click hard/smooth toggle with identical rendering behavior.
• Staged↔Spline toggling behaves per the answered open question above (that answer gates this item's completion definition).