daniel/reasampler
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: queue TODO-1.0 — post-1.0 specs for envelope curve dials/overlay radio, MM preamp filter stage, and hard-point Spline EGs

Browse Source
This commit is contained in:
Daniel Harvey
2026-07-28 17:58:19 -04:00
parent 57e509c64f
commit b06b226182
1 changed files with 252 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
TODO-1.0.md
+252
View File
@@ -0,0 +1,252 @@
# 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).