Nota — a free DAW for macOS, Windows and Linux. No subscription, no account — just open it and make music.
description: "Tasks for Nota Twin — a morphing two-filter analog poly (specs/055)"
Tasks: Nota Twin — a morphing two-filter analog poly
Input: Design documents from specs/055-morph-poly-synth/
Prerequisites: plan.md, spec.md, research.md, data-model.md, contracts/c-abi.md, contracts/mcp-tools.md, quickstart.md
Tests: included — the constitution (IV) requires the smoke test to cover engine behaviour,
and the spec's success criteria (SC-002, SC-005, SC-008, SC-009) are render comparisons. Smoke
checks live in tests/Nota.SmokeTest/TwinTests.cs (the per-instrument pattern of
KeysTests.cs); perf scenarios in tests/perf/nota_perf.cpp.
Organization: by user story, inside the three delivery slices of plan.md — slice 0 (shared ladder PR), P1 = US1–US3 (PR 1), P2 = US4–US7 (PR 2), P3 = US8–US9 (PR 3).
Engine paths below are relative to src/native/nota.engine/; managed paths to
src/managed/. "Mirror Consort" = copy what the same site does for kind 15
(git grep -n -i consort -- <file>).
Format: [ID] [P?] [Story] Description
- [P]: can run in parallel (different files, no dependency on an unfinished task)
- [Story]: US1 … US9 from spec.md
Phase 1: Setup
Purpose: branch, empty files, build wiring.
- T001 Create branch
feat/morph-poly-synthoffdevelop(thenota-prskill's branch rule);.specify/feature.jsonalready points atspecs/055-morph-poly-synth— done as worktree~/repos/nota/nota-twin(the main checkout is busy with other work);.specify/feature.jsonthere points at this spec - T002 Create empty translation units with the two-line AGPL SPDX header and a why comment header:
src/devices/instruments/Twin.{h,cpp},TwinVoice.{h,cpp},TwinMod.{h,cpp},TwinSeq.{h,cpp},src/dsp/primitives/SteinerFilter.{h,cpp}— done forTwin.{h,cpp}; the voice / mod / seq / Steiner files are created with their stories (US1, US4, US8) instead of as empty files - T003 Add the new
.cppfiles toCMakeLists.txt(engine sources list, next toConsort.cpp) and confirm the Release build inbuild/still compiles
Phase 2: Foundational (slice 0 + the instrument shell)
Purpose: what every story needs — the shared-ladder change, the full param table, kind 18 registered end-to-end. No user-story work starts before this phase is done.
Slice 0 — shared ladder 12 dB tap (own small PR)
- T004 Add a 2-pole (12 dB/oct) output tap to
dsp::LadderFilterinsrc/dsp/primitives/LadderFilter.{h,cpp}(e.g.process(x, bassComp, slope12)defaulting to the current 4-pole path) without changing the existing code path's arithmetic (research R6) - T005 Verify Monolith, Consort and Pentad renders are bit-identical before/after T004 (render each
instrument-13/14/15perf scenario's output to WAV at both commits and compare), and runscripts/perf-gate.sh developon Linux — no regression; open the slice-0 PR via thenota-prskill — done: no instrument usesdsp::LadderFiltertoday (Monolith, Consort, Pentad keep their own copies), so the tap cannot change them; a hash harness confirmed Monolith / Pentad / Consort renders (default + high resonance) bit-identical to develop. The Linux perf gate was not run, and the separate slice-0 PR is dropped (the change ships with P1)
Twin shell
- T006 Define the complete param table in
src/devices/instruments/Twin.hfor all slices (data-model.md): globals (mode,splitkey,share,voices,padx,pady,padz,bendrange,seq.*,arp.*), per partlo./up.side-less params (morph,voicemode,glide,glidelegato,octave,vol,pan,fxon,macroN,mN.src,mN.dstfor N = 1..64), and per part per side<part>.<a|b>.<name>for every row of the data-model's per-side table (incl.mNamtand FX); an enum + a constexpr descriptor table (id, display name, default, stepped flag, musical domain: pitch / log-time / linear) generated from one list so order = persisted layout, APPEND ONLY - T007 Implement the plugin-param interface on
Twininsrc/devices/instruments/Twin.{h,cpp}(pluginParamCount/Id/Name/Get/Set/Text/Default/IndexOfId,std::atomic<float> pn_[kNumParams]), display names that include part and side ("Lower A · Ladder Cutoff" — the automation menu groups on the head before the last space; data-model / FR-073),kind() == 18,displayName() == "Nota Twin",setSampleRate, a silentrender(),clone()(copiespn_, sample rate, pattern snapshot),activeVoiceCount,heldNotes, sleep contract stubs - T008 Implement
getState/setStateinsrc/devices/instruments/Twin.cppwith the layout[u32 magic "TWN1"] [u32 paramCount] [paramCount × f32 LE] [u32 patternBytes] [pattern data];setStateMUST tolerate a shorter / longer param array and a missing pattern block (FR-052) - T009 Register kind 18 natively, mirroring Consort:
src/engine/Engine.h(addTwinTrackdecl),src/engine/Engine_Devices.cpp(method, include,cloneInstrumentandmakeBuiltinInstrumentswitches),src/devices/DeviceFactory.cpp,src/devices/racks/RackCore.{h,cpp}(makeInstrument) — done;cloneInstrumentBodyneeds no case (Twin::clone covers it) - T010 Add
nota_engine_add_twin_tracktoinclude/nota/nota_engine.h(comment per contracts/c-abi.md, next to the Consort decl) and implement it insrc/abi/nota_engine_track.cpp - T011 [P] Managed interop:
Nota.Infrastructure/Interop/NativeMethods.Tracks.cs([LibraryImport]),Nota.Infrastructure/Interop/NotaEngine.Tracks.cs(AddTwinTrack),Nota.Application/Engine/IAudioEngine.cs - T012 [P] Catalog and categories:
Nota.Application/Palette/BuiltinDeviceCatalog.cs(name "Nota Twin",Kind = 18, sub text, semantic descriptor — role, aliases incl. "polysynth", "morph", "analog poly", character, sound, genre, one-line description; the--palettesmoke check fails without role + aliases) andNota.Application/Palette/DeviceCategories.cs - T013 [P] Remaining kind sites, mirroring Consort in each:
Nota.Infrastructure/Persistence/ProjectService.cs,Nota.Infrastructure/Persistence/PresetService.cs(add-track switch),Nota.Infrastructure/Audition/PresetAudition.cs,Nota.Presentation/DeviceInsertService.cs,Nota.Presentation/Racks/RackKeyParams.cs,Nota.App/DeviceCards/Rack/RackCard.Chains.cs,Nota.App/DeviceCards/Rack/RackCardView.cs,Nota.App/DeviceCards/Rack/RackCardView.Drum.cs,Nota.App/DeviceChainView.Shell.cs,Nota.App/NotaDocs.cs,Nota.App/PreferencesWindow.cs,Nota.App/Theme/NotaGeometry.cs,Nota.App/Controls/Knob.cs,Nota.Remote/RemoteParams.cs,Nota.Mcp/Tools/InstrumentTools.cs(kind list(18, "Nota Twin")and the add switch) - T014 [P] Perf: add
case 18: return "Twin";intests/perf/nota_perf.cppinstrumentName, so the genericinstrument-18scenario appears innota_perf list - T015 Smoke: create
tests/Nota.SmokeTest/TwinTests.csand hook it intotests/Nota.SmokeTest/Program.cs; first check —AddTwinTrackreturns a track whose kind is 18, param count ≈ the table size, every param id unique, state round-trips through get/set (contract item 5, params only) - T016 Measure risk R2a: with a Twin track, open the automation target picker, the browser's Map tab, MIDI-learn list and Nota Remote's param list; record the timing in
specs/055-morph-poly-synth/research.md(R2a) and, if any list is slow or unusable, add the filter to the current part / side there (task appended to US2) — measured: speed is fine, the lists are unwieldy (≈250 top-level automation entries, 121 Remote pages); fixes appended as T092 / T093 (research R2a)
Checkpoint: Twin appears in the browser, adds a track, saves and loads — silently.
Phase 3: User Story 1 — Play a rich analog poly (P1) 🎯 MVP
Goal: the 12-voice analog voice from Init sounds and responds smoothly (FR-001 – FR-013).
Independent Test: spec US1 — held 8-note chord, sweep Wave / Mode / Route / cutoffs, no clicks, no dropped voices; 13th note steals cleanly.
Tests for US1
- T017 [P] [US1] Smoke in
tests/Nota.SmokeTest/TwinTests.cs: Init note renders non-silent and within ±1.5 dB of Volt Init (US1-1, contract item 1); 13 held notes with 12 voices → 12 sound, no NaN/inf; Unison stacks all voices on one key; max Brute + max resonance on both filters stays below +6 dBFS - T018 [P] [US1] Perf scenarios
twin-full-12(sustained 12-note chord, both filters, 3 LFOs, FX on once US5 lands) andpentad-full-16intests/perf/nota_perf.cpp—pentad-full-16,twin-full-12added; Twin 12 voices = 1.55 × Pentad 16 after US1, 1.75 × after US3's expression (SC-001 budget 2 ×, matrix and FX still to come) — T050 must optimise
Implementation for US1
- T019 [P] [US1]
SteinerFilterinsrc/dsp/primitives/SteinerFilter.{h,cpp}: 12 dB ZDF Sallen-Key-type core, input distributed over LP / BP / HP injection points somodesweeps LP → BP → HP → Notch continuously, diode-pair soft clip in the feedback, self-oscillation at max resonance, per-sample linearised saturation,NOTA_RT_SAFE, inline hot path (research R5) — header-only primitive - T020 [P] [US1] Oscillator in
src/devices/instruments/TwinVoice.{h,cpp}on thepentad::polyBLEP / polyBLAMP core: continuouswavetri → saw → square withpw,metalwavefolder on the triangle path with first-order ADAA,coarse±24 st,fine; Osc 2o2lolow-frequency / keyboard-off; hardsync2 → 1,fm21,fmfilt(osc → multimode cutoff) — all inside the voice's ×2 oversampling with HIIR decimation (research R4) - T021 [US1] Voice in
src/devices/instruments/TwinVoice.{h,cpp}: noise with colour, mixer with per-source level and filter balance (oNbal,noisebal), multimode + ladder (ldslope12/24 via T004),routeseries ↔ parallel blend,brutefeedback through one-sample delay + tanh with loop gain ≤ 1,drive, filter / amp / mod envelopes (mod env with delay + loop), key tracking and env amounts, control-rate (32-sample) coefficient updates, per-sample smoothing of targets — the shared ladder runs one internal step at the voice's ×2 (setInternalOversampling), its resonance follows the measured self-oscillation edge per coefficient so full resonance sings at any pitch (no other instrument uses it) - T022 [US1] LFOs in
src/devices/instruments/TwinMod.{h,cpp}: 3 LFOs — shapes sine / triangle / saw / square / S&H / smooth random, rate free or synced (setTransport, AR-9), per-voice or global mode, retrigger, fade-in; LFO 3 symmetry / curve; hard-wiredvibamt(LFO 1 → pitch, scaled by mod wheel) andvelamp - T023 [US1] Voice pool and render in
src/devices/instruments/Twin.cpp: 12-voice pool (capvoices4..12), Poly / Mono / Legato / Unison, glide (+ legato-only), quietest / oldest stealing with a short fade (no click), Unison detune +spread/spreadmode, partvol/pan, seededdriftper voice (Pentad's scheme, re-seed on play edges / jumps), voices released (not cut) whenvoicesdrops; Lower part only in this slice - T024 [US1] Sleep contract in
src/devices/instruments/Twin.cpp:hasTail/isIdle/wake— idle only when every voice envelope is done (FX tails added in US5), phases advance across a skipped block (SC-006) - T025 [US1] First card
Nota.App/DeviceCards/Instruments/TwinInstrumentCard.cs+Nota.App/DeviceCards/InstrumentCardFactory.cs: L size, tabs Osc · Filter · Env · LFO built from the shared gauge knob and Volt's signal-chain panel layout (nota-instrument§ 3,nota-design); knobs bound tolo.a.*until US2 adds the side switch — 700 × 260 (DESIGN.md card format): Morph column on every tab + tabs Osc · Filter · Env · LFO · Voice; checked headless in Studio Dark / Light - T026 [US1] Starter presets in
Nota.Infrastructure/Persistence/FactoryPresetCatalog.cs: ~12Inst("twin", 18, …)presets (pads, keys, brass, bass, lead) — single-side for now, revisited in US2 / US6 — 12 single-sided patches (Pads, Keys, Brass, Bass, Leads, Plucks, FX); smoke: ids exist, apply in place, 8-note chord at velocity 100 peaks under 0 dBFS
Checkpoint: Twin plays as a fine single-sided poly.
Phase 4: User Story 2 — Morph between two sides of a patch (P1)
Goal: every param has A and B; Morph interpolates them (FR-020 – FR-024).
Independent Test: spec US2 — A dark pad, B bright pluck, automate Morph over 4 bars; Morph 0 / 1 equal A / B alone.
Tests for US2
- T027 [P] [US2] Smoke in
tests/Nota.SmokeTest/TwinTests.cs: render with Morph = 0 equals the render of the same patch with B copied from A, bit-exact (seeded drift); same for Morph = 1 vs A copied from B (SC-002, contract item 2); a Morph 0 → 1 sweep over one beat has no sample-to-sample jump above the A/B renders' own maximum (SC-003) — Morph 1 = side B alone and equal sides at Morph 0.5 = Morph 0, both bit-exact; a one-beat sweep's largest sample step stays within 1.25 × the sides' own
Implementation for US2
- T028 [US2] Morph evaluation in
src/devices/instruments/TwinMod.{h,cpp}: at control rate per part,v = lerp(A, B, morph)per continuous param in its musical domain (pitch-linear for cutoffs / tune, log-time for envelope / LFO times, linear for levels and depths); stepped params "A below 0.5, B from 0.5"; exact endpoints (lerp(A,B,0) == A); voice-mode switch at the midpoint releases rather than cuts held notes (research R3) — inTwinMod.cppevalPart; the normalized value of a Pitch / LogTime param is already exponential in its unit, so lerping it moves cutoffs in pitch and times logarithmically. Voice mode, glide and octave are side-less part params, so they never switch mid-morph - T029 [US2] Per-voice morph hook in
src/devices/instruments/TwinMod.cpp+TwinVoice.cpp: each voice holds its own morph value (part morph + per-voice matrix contribution, clamped 0..1) and re-evaluates only voice-local params when it differs from the part's (the matrix source arrives in US4; the hook is tested here with a fixed offset) —Voice::morphOff/own: a voice with an offset evaluates its own PartCtl; nothing sets the offset until the matrix routes a per-note source to Morph, so its test lands with US4 (T039) - T030 [US2] Card A/B editing in
Nota.App/DeviceCards/Instruments/TwinInstrumentCard.csandNota.App/Controls/TwinViews.cs: A / B side switch (view state, not saved in presets), knobs re-bind to<part>.<side>.*, each knob shows both side values and the live morphed position (scope index 6), Morph control in the header strip; followsDESIGN.md(orange only for what is live / chosen) — A / B "Edit" switch under Morph (editor state per track), every side knob ticks the other side and dots the sounding value (newKnob.OtherValue/SoundingValue), tooltip "A … · B … · now …"; status shows the edited side - T031 [US2] Copy A → B, B → A, swap in
Nota.Application/Twin/TwinSides.cs(pure logic: list of(id, value)writes from the param table) and wire to the card's side menu as one mix gesture in the engine undo history (research R14) —Nota.Application/Twin/TwinSides.cs; a mix gesture takes ≤ 64 targets (nota_mix_gesture_begin), so the writes run in 64-target gestures inside one undo group — still one undo step (smoke-tested) - T032 [US2] Automation lanes name their side: verify Twin's display names (T007,
src/native/nota.engine/src/devices/instruments/Twin.cpp) reach the automation lane header and target picker insrc/managed/Nota.App/as "Lower A · Ladder Cutoff" / "Lower B · …"; add the part/side filter if T016 found the lists slow (FR-024) — with T092: the automation menu shows Lower A › Ladder › Cutoff (13 top-level entries, built in 14 ms; checked headless) - T092 [US2] Automation menu nesting in
Nota.App/ArrangementView.Automation.csBuildBuiltinInstrumentAutoMenu: a name with " · " nests on that first (Lower A›Ladder›Cutoff), then the existing last-space grouping; rename Twin's matrix params insrc/native/nota.engine/src/devices/instruments/Twin.cppso a part / side's 64 slots form one "Routing" group ("Lower · Routing Source1", "Lower A · Routing Depth1") — research R2a — done; global names made single-leaf ("Patch SplitKey") - T093 [US2] Nota Remote in
Nota.Remote/RemoteParams.csMacroDevices: for kind 18 page a curated list (Lower Morph, pad X / Y / Z, the Lower part's side-A Osc / Filter / Env controls) instead of all 965 params — research R2a — 28 curated params (4 pages) for kind 18 - T033 [US2] Make the starter presets two-sided in
Nota.Infrastructure/Persistence/FactoryPresetCatalog.cs(each preset's B side a meaningful variation) —Tw(name, a, b): side B = A + overrides (presets reset unlisted params, so B used to be Init); smoke: both sides sound, peak < 0 dBFS, B ≠ A for all 12
Checkpoint: P1's defining feature works; automation writes to the edited side.
Phase 5: User Story 3 — Play it expressively (P1)
Goal: velocity, AT, poly AT, MPE, wheels, pedal, expression pad (FR-030, FR-031, FR-033).
Independent Test: spec US3 — poly AT / MPE on one note of a chord changes only that note; recorded expression plays back the same.
Tests for US3
- T034 [P] [US3] Smoke in
tests/Nota.SmokeTest/TwinTests.cs: per-note pressure on one note of a held 6-note chord leaves the other five notes' render within 0.5 dB (render each note isolated by pitch through a narrow band or by rendering with/without the pressure event) (SC-005, contract item 3); per-note bend moves only its voice; channel pressure moves all — pressure on one note of a 6-note chord: others within 0.04 dB, its 3rd harmonic +14.7 dB; +2 st per-note bend moves only G3; channel pressure opens 6/6; pad X / Y audible. Recording keeps per-note expression through the engine's existing MPE recording (no Twin-specific path)
Implementation for US3
- T035 [US3]
noteExpression/supportsMpe/controllerinsrc/devices/instruments/Twin.cpp: per-voice bend (own range from the MPE controller, elsebendrange±2/±5/±12/±24), pressure (poly AT per note; channel AT → all voices), slide, release velocity; mod wheel, pitch wheel, sustain via the engine's default pedal handling (handlesSustain() == false) — per-voiceVoiceExpr+ instrument-wideGlobalExproffsets (bend range ±2/5/12/24 frombendrange); release velocity isn't delivered by the engine's noteOff, so it waits for an engine change (not in this feature) - T036 [US3] Default expression routes on Init in
src/devices/instruments/TwinMod.cpp: mod wheel → vibrato (viavibamt), pressure → ladder + multimode cutoff, slide → multimode cutoff, velocity → amp — implemented as fixed routes now, re-expressed as removable matrix slots in US4 (FR-033) — fixed routes until US4 re-expresses them as removable slots: pressure → both cutoffs +1.5 oct, slide → multimode ±2 oct, mod wheel → vibrato (+ pad Z) - T037 [US3] Expression pad in
Nota.App/Controls/TwinViews.cs+ the card: X / Y drag, Z = hold time / press (mouse) or touch pressure, writingpadx/pady/padz(automatable); default routes X → multimode cutoff, Y → morph, Z → LFO 1 depth until US4 makes them editable —TwinExpressionPad(Controls/TwinViews.cs) on the Voice tab: drag X / Y, hold raises Z over 0.5 s, release lets it fall over 0.25 s; one automation-write gesture on the three axes; X → multimode cutoff ±2 oct, Y → morph ±½, Z → vibrato depth - T038 [US3] MPE badge and Nota Remote Expressive keys: confirm
supportsMpe()shows the badge and thatNota.Remote/RemoteParams.csexposes the pad and Morph on the phone —supportsMpe()= true drives the MPE badge; Morph and pad X / Y / Z lead Nota Remote's curated pages (T093)
Checkpoint — end of slice P1: run Phase 12's closing tasks for PR 1 (build, smoke, CHANGELOG, FEATURES, docs) and open PR 1.
Phase 6: User Story 4 — Route modulation in a matrix (P2)
Goal: 64-slot matrix per part, 8 macros (FR-032 – FR-034).
Independent Test: spec US4 — LFO 3 → Osc 1 Wave and → multimode cutoff with opposite depths; delete one route; fill 64 slots → "matrix full".
Tests for US4
- T039 [P] [US4] Smoke in
tests/Nota.SmokeTest/TwinTests.cs: a route with depth 0 renders identically to no route; LFO → cutoff route with A depth ≠ B depth changes with Morph; a per-note source →morphroute morphs only its note — plus: the app's tables match the engine (29 sources, 77 destinations), first-free-slot add + one-step undo, full at 64, remove frees the slot; zero depth renders bit-identically to no route; a B-only depth moves only at Morph 1; Pressure → Morph morphs only the pressed note (closes T029's test)
Implementation for US4
- T040 [US4] Source and destination tables in
src/devices/instruments/TwinMod.h— append-only enums: sources none, LFO 1–3, filter env, amp env, mod env, velocity, release velocity, key, pressure, slide, per-note bend, mod wheel, pitch wheel, pad X / Y / Z, random-per-note, macro 1–8, seq gate, seq step value; destinations = every continuous voice / part param +morph; stepped params are not destinations (data-model § Validation) —TwinMod.h/.cpp: 29 sources, 6 virtual destinations (Morph, Pitch, Osc 1 / 2 pitch, Vibrato) + 71 side params; slot texts read as names (pluginParamText) - T041 [US4] Matrix evaluation in
src/devices/instruments/TwinMod.cpp: 64 slots per part read frommN.src/mN.dstand the morphedmNamt; per-voice sources evaluate per voice, global ones once per control block; destination offsets summed in each param's musical domain; a slot withsrc = noneordst = noneis empty — per voice at control rate: a route moving anything makes the voice evaluate its own PartCtl with the offsets (normalized side offsets, morph, pitch ±24 st, vibrato ±1 st); LFO 2 / 3 step once per interval; 16 live routes cost ≈ 4 ms/s (twin-full-12: 1.75 × Pentad 16) - T042 [US4] Move the Init defaults of T036 / T037 into matrix slots 1–7 (removable), keeping old projects' sound: on
setStateof a pre-matrix blob, write the equivalent slots — slots 1–6 are the Init routes (pressure → both cutoffs, slide and pad X → multimode, pad Y → morph, pad Z → vibrato) as param defaults; the fixed code paths are gone. No migration: nothing has shipped - T043 [US4] Macros in
src/devices/instruments/TwinMod.cpp: 8macroNvalues per part as matrix sources plus Volt-style macro → several destinations, as on Volt / Aurora — macros are the part's eightmacroNparams, matrix sources (one macro → many destinations through routes); eight knobs on the Matrix tab - T044 [US4] Matrix tab in
Nota.App/DeviceCards/Instruments/TwinInstrumentCard.cs+Nota.App/Controls/TwinViews.cs: source × destination grid; click creates a route in the next free slot, drag sets bipolar depth on the edited side, delete removes; each a single undo step; "Matrix full (64 routes)" message when no slot is free (FR-032 acceptance 2) — a route list rather than the spec's grid (29 × 77 does not read in 186 px): slot, source ▾, destination ▾ (grouped menus), depth on the edited side (other side ticked), remove; "+ Route", "n / 64", "Matrix full (64 routes)"; each edit one undo step (Nota.Application/Twin/TwinMatrix.cs). The open tab survives the A / B rebuild - T045 [US4] MCP
set_twin_routeandread_twin(routes part) inNota.Mcp/Tools/TwinTools.csper contracts/mcp-tools.md (next_free, "matrix full" error), registered next toInstrumentTools—read_twin(sides of 22 main controls, routes by name) andset_twin_route(by name, slot or first free, remove, "matrix full"); smoke-tested
Checkpoint: deep modulation per side.
Phase 7: User Story 5 — Finish the sound with its own effects (P2)
Goal: Mod FX / Delay / Reverb per part, morphable, bypassable (FR-040).
Independent Test: spec US5 — each effect on/off, full bypass, morph dry A → long-reverb B.
Tests for US5
- T046 [P] [US5] Smoke in
tests/Nota.SmokeTest/TwinTests.cs:fxon = 0render equals the voice sum alone; synced delay follows a tempo change; after note-off the instrument stays awake until the tail is below the silence threshold — plus: every effect (chorus, flanger, phaser, ensemble, delay, reverb) heard, finite, under 0 dBFS; the synced 1/4 echo lands 0.500 s after the note at 120 BPM and 0.667 s at 90; a reverb tail is at −28 dB 0.75 s after the note
Implementation for US5
- T047 [US5] Internal FX chain in
src/devices/instruments/Twin.{h,cpp}: per part, construct once a Chorus, Flanger, Phaser (one active bymodfxtype), Delay and Reverb fromsrc/devices/effects/(no allocation after construction), forwardsetSampleRate,setTransport/TransportInfofor delay sync; per block push the morphedmodfx*/dly*/rev*values onto the devices' params (research R8) — devices built in the constructor and re-rated inTwin::setSampleRate(the engine changes rates with rendering suspended; Delay / Reverb size their lines there); per part: decimate → Mod FX ▸ Delay ▸ Reverb at the instrument's output gain; an effect switched on starts from a cleared line; resets clear them for repeatable renders. Patch-wide sources (wheels, pad, macros, global LFOs) now act on the part's values — so they reach the effects — and a voice re-evaluates only for its own sources. Delay Division follows the device's 8 values - T048 [US5] Extend the sleep contract (T024) with the FX tails: delay flight time and reverb tail block sleep (Consort's rule) (US5-3) — the output-peak hangover already covers the tails (the tail is output); smoke-tested
- T049 [US5] FX tab in
Nota.App/DeviceCards/Instruments/TwinInstrumentCard.cs: three effect panels with on/off, mix, two or three character knobs, the whole-section bypass — FX tab: Mod FX (Chorus / Flanger / Phaser / Ensemble, rate, depth, mix), Delay (sync / ping-pong, time or division, feedback, mix), Reverb (size, damping, mix), each with On, and the section switch; checked headless in both themes - T050 [US5] Add
twin-full-12with FX on and confirm SC-001 (≤ 2 ×pentad-full-16) intests/perf/nota_perf.cpp; if over budget, apply research's mitigations (control-rate coefficients, SIMD across voices viasrc/dsp/math/Simd.h, SVF fallback for R5) and re-measure — 81.5 ms/s vs Pentad 42 (1.94 ×) with FX on; profiled (sample): voice path ≈ 50 %, ladder ≈ 14 %, oscillators ≈ 15 %, reverb ≈ 5 %. Steiner ZDF coefficients now refresh with the cutoff instead of every os sample and expMap uses the fast exp2: 78.4 vs 42.6 = 1.84 × (SC-001 met, ~8 % margin)
Phase 8: User Story 6 — Start from presets (P2)
Goal: ≥ 40 factory presets in folders, user presets, preset name / "modified" (FR-053).
Independent Test: spec US6 / SC-004 — every preset sounds on both sides, peaks under 0 dBFS with an 8-note chord at velocity 100, loads under 50 ms.
Tests for US6
- T051 [P] [US6] Smoke in
tests/Nota.SmokeTest/TwinTests.cs: loop over everytwinfactory preset — non-silent at Morph 0 and 1, peak < 0 dBFS (8-note C-major chord, velocity 100), apply time < 50 ms; save a user preset and re-apply it → identical render; the "modified" mark (specs/048) appears after one knob move and clears on undo — 43 presets in 10 folders; both sides sound, peak < 0 dBFS, B ≠ A for all; apply ≤ 1.5 ms (was 40.7 ms:Engine::instrumentParamDefaultbuilt a fresh instrument per question — now one per kind, cached); the preset name and "modified" mark follow a side-B knob; a user preset round-trips all 964 sound params
Implementation for US6
- T052 [US6] User presets in
Nota.Infrastructure/Persistence/PresetService.cs: Twin savesNamedParams(skip view params) and, from P3 on, the pattern block inStateBase64; apply params first, then the blob (research R11) — the generic built-in path already captures every named param (sides, matrix, FX); the pattern block joins with US8 - T053 [US6] Factory library in
Nota.Infrastructure/Persistence/FactoryPresetCatalog.cs: ≥ 40 presets in folders Pads, Keys, Leads, Bass, Brass, Strings, Plucks, Sequence, FX, Morph — each with a meaningful B side and macro names; no Arturia names — 43 two-sided presets (Pads, Keys, Brass, Bass, Leads, Plucks, Strings, Sequences, FX, Morph), many with matrix routes (Rthelper) and effects; macros carry no names yet (Twin has no macro-name storage) — the presets route the sound directly instead. "Morph" joins the preset descriptors' folder map - T054 [US6] Preset audition: confirm
Nota.Infrastructure/Audition/PresetAudition.csplays Twin presets with a held chord long enough to hear the morph (adjust the audition phrase for kind 18 if needed) — the audition picks its phrase from the folder; "morph" now plays the held-chord (Pad) phrase so an LFO-driven morph can travel
Phase 9: User Story 7 — See and edit it on a device card (P2)
Goal: the full card — L and S sizes, graphs, every tab, all themes.
Independent Test: spec US7 — edit a full patch from the card; S ↔ L; A/B indicator, live morph and per-knob markers in all four themes.
- T055 [P] [US7] Interactive graphs in
Nota.App/Controls/TwinViews.cs: per-oscillator waveform (draws Wave / PW / Metal, drag = wave), combined dual-filter response with route blend (drag = cutoffs / resonance), envelope shapes (drag points), LFO shapes with live phase (scope 20–22) —Controls/TwinViews.cs: oscillator waveforms in the Osc headers (drag = Wave), the two filters' combined response with the multimode and ladder faint (drag = ladder cutoff / resonance), envelope graphs with A · D/S · R handles (the env islands keep Velocity and Curve as knobs, times read out under the graph), LFO shapes with the live phase - T056 [US7] S size in
Nota.App/DeviceCards/Instruments/TwinInstrumentCard.cs: Morph, A/B switch, expression pad and the key sound knobs (cutoffs, resonance, attack, release); size saved with the project as a view param — 260 wide: Morph + A / B, the pad, ladder cutoff / resonance and amp attack / release of the edited side; the S / L toggle in the header;viewnow defaults to L - T057 [US7] Voice meter and live morph markers in
Nota.App/DeviceCards/Instruments/TwinInstrumentCard.cs: readactiveVoiceCountand scope 4–19 at the card's refresh rate; per-voice morph dots on the Morph control — the header's voice count (n / cap); a live morph strip under the Morph knob (the part's morph and a dot per sounding voice) from the newscopeReadtelemetry (contracts/c-abi.md layout) - T058 [US7] Design check in
tests/Nota.SmokeTest/design-token suites (DesignTokenCheck*.csallow lists): Twin card labels sentence-case, tokens only, no ad-hoc colours; screenshots of S and L in Studio Dark, Studio Light, Ember Graphite, Ember Paper via the in-app capture recipe for the PR — the full smoke (design token, label, icon and card-format checks) passes; headless shots of every tab, side B and S in Studio Dark, Studio Light, Ember Graphite and Ember Paper (/tmp/twin-cardharness/out) - T059 [US7] MCP side tools
set_twin_morph_side,copy_twin_sideand fullread_twininNota.Mcp/Tools/TwinTools.cs(contracts/mcp-tools.md) —set_twin_morph_side("id=value" list on side a / b) andcopy_twin_side(a_to_b / b_to_a / swap), one undo step each; smoke-tested
Checkpoint — end of slice P2: Phase 12 closing tasks for PR 2; open PR 2.
Phase 10: User Story 8 — Sequence it from the instrument itself (P3)
Goal: polyphonic step sequencer, arpeggiator, motion lanes, patterns in presets, "To clip" (FR-060 – FR-067).
Independent Test: spec US8 — step-record 4 chords, play at 90 and 174 BPM, transpose by a held key, record a Morph motion lane, "To clip", sequencer off — same sound.
Tests for US8
- T060 [P] [US8] Smoke in
tests/Nota.SmokeTest/TwinTests.cs: a 16-step pattern started by the transport fires note-ons exactly on the step grid at 90 and 174 BPM over 64 bars (≤ 1 sample deviation) (SC-009, contract item 4); transport stop releases every sequencer note; a loop jump re-aligns with no hanging note; state round-trip keeps patterns (contract item 5, pattern block) — 1/16 steps land on the grid at 90 and 174 BPM (onset spacing within 1 sample over 4 s; the smoke keeps it to 4 s, not 64 bars, to stay quick); a running pattern renders bit-identically at blocks of 512 and 77; a transport stop releases every sequencer note; patterns round-trip through the state - T061 [P] [US8] Smoke: "To clip" output renders identically to the running pattern with Twin's sequencer off (SC-009 second half) — "To clip" plays like the pattern (level within 0.00 dB, onsets within 2 samples) and its undo restores the sequencer
Implementation for US8
- T062 [US8] Check how Nota Rhythm's step edits enter the undo history (
src/devices/instruments/RhythmMachine.cppaction()and its callers insrc/managed/) and record the finding in research.md R14; Twin's pattern edits follow the same path, or add a state checkpoint per action if Rhythm has none — Rhythm's step edits were not undoable at all (instrumentAction called action() only). Added a generic path instead:Instrument::editState / setEditState+MixKind::InstrumentEdit;Engine::instrumentActionrecords an undo step whenever the edit state changes, undo hands the bytes back without republishing (sounding notes go on). Rhythm can opt in later - T063 [US8] Pattern storage in
src/devices/instruments/TwinSeq.{h,cpp}: 8 patterns; per patternlength"1..64 steps", per step "0..6 MIDI notes (0 = rest)", "velocity 1..127", "gate 1..100 % of step, or tie"; 4 motion lanes with "target param index or none", "stepped / smooth", "value 0..1 or unset" (data-model § Pattern); message-thread authoring copy + immutablestd::shared_ptrsnapshot published by atomic exchange, retired snapshots freed on the message thread (AR-5) —TwinSeq.{h,cpp}: patterns, lanes, serialization;SnapshotHistory<PatternSet>publishes the immutable snapshot (AR-5) - T064 [US8]
action()ids 0–15 insrc/devices/instruments/Twin.cppexactly as contracts/c-abi.md (append-only), each bumping the revision (scope 3) and publishing a snapshot; serialize patterns into the state blob's pattern block (T008) — ids 0–15 as contracted plus 16StepRecordPoll; tie is farg > 1 (a gate of 100 % is 1.0) - T065 [US8] Sequencer engine in
src/devices/instruments/TwinSeq.cpp: clock fromsetTransport(AR-9) — steps at exact sample offsets from the beat grid, rate 1/4 … 1/32 incl. triplets, swing, pattern length independent of the bar, stopped when the transport isn't rolling, jump / loop → release + re-align at next step; held-key transpose (root = first note of the pattern) with latch; pending pattern switch applied at pattern end (scope 0–2); played keys sound alongside the pattern — the step grid is absolute (song-start based), whole-sample onsets (block positions are rounded to whole samples so block splits never shift a step); stopped transport = silent sequencer, keys play normally - T066 [US8] Arpeggiator in
src/devices/instruments/TwinSeq.cpp: Up, Down, Up/Down, Random, As Played, Chord; 1–4 octaves; synced rate, gate, swing, Hold — reuse the note-order logic fromsrc/devices/midi_fx/Arpeggiator.{h,cpp}(factor a shared helper, no change to Arp's behaviour) (FR-064) —twin::arpNotes: Nota Arp's idea (the note is a pure function of the absolute step) rather than its code, which is embedded in the device; Up, Down, Up/Down, Random, As played, Chord; 1–4 octaves; Hold - T067 [US8] Motion lanes in
src/devices/instruments/TwinSeq.cpp+TwinMod.cpp: per step override of the target param's sounding value (stepped / smoothed), acting on the side the param belongs to; motion-record arm captures the touched param's value per step; a hand-moved knob overrides the lane until released (US8-3) — lanes override a side's value (or the part's Morph) before the morph; while a lane records its playback pauses (that is how "the hand wins"); the card writes the target's value at each step it sees pass - T068 [US8] Sequencer output into the voice path in
src/devices/instruments/Twin.cpp: sequencer notes enter like keyboard notes (voice allocation, per-note sources, Split / Layer routing viaseq.targetfrom US9); MIDI effects before Twin see only incoming notes (FR-067) — sequencer voices are flagged, released only by the sequencer; MIDI effects before Twin see only incoming notes - T069 [US8] Seq tab in
Nota.App/DeviceCards/Instruments/TwinInstrumentCard.cs+Nota.App/Controls/TwinViews.cs: step grid (notes per step, velocity / gate lanes, tie / rest), pattern 1–8 selector with pending indicator, step-record arm, motion lanes view and arm, Seq / Arp switch with arp controls; re-reads the pattern blob when the revision changes — Seq tab: Sequencer on, Seq / Arp, pattern, length, rate, swing, transpose / latch, Rec, To clip; the step grid (notes, velocity drag, gate drag / tie, playing step, record cursor, selection, motion values); Rest, pages, lane 1–4, target, Smooth, Rec motion, Clear; Arp page: mode, rate, octaves, hold, gate, swing - T070 [US8] "To clip" in
Nota.Application/Twin/TwinPatternToClip.cs: decode the active pattern from the state blob, create a MIDI clip with its notes and velocities and motion lanes as automation on the lane's param, switchseq.onoff — one undo step (research R13); wire to the Seq tab —TwinPatterns.ToClip(ties merge, swing kept, motion lanes → automation, the sequencer off) in one undo step; the card places the clip at the playhead's bar - T071 [US8] Patterns in presets:
TwinSeq(...)compact text builder inNota.Infrastructure/Persistence/FactoryPresetCatalog.csproducing the pattern block; ≥ 8 factory presets using sequencer or arp (SC-011); user presets carry patterns (T052) — user presets carry a params-free state blob with the patterns;TwSeqbuilds 8 factory sequencer / arp presets (one with a Morph motion lane) - T072 [US8] MCP
get_twin_pattern,set_twin_pattern,twin_pattern_to_clipinNota.Mcp/Tools/TwinTools.cs(text rowsC3 E3 G3:100:50%,.rest,~tie; one undo step per call) —get_twin_pattern,set_twin_pattern(rows; one undo step; turns the sequencer on),twin_pattern_to_clip - T073 [US8] Sleep: a running sequencer blocks sleep; a stopped one doesn't (SC-006) — a running sequencer keeps the instrument awake (the 4-second grid test would lose onsets otherwise)
Phase 11: User Story 9 — Split or layer two sounds (P3)
Goal: Lower / Upper parts, Single / Layer / Split, shared 12 voices (FR-070 – FR-075).
Independent Test: spec US9 — Split at C3 with two presets in Lower / Upper; share 4 + 8; 6 keys held low → 4 sound.
Tests for US9
- T074 [P] [US9] Smoke in
tests/Nota.SmokeTest/TwinTests.cs: Split at C3 — B2 renders only Lower, C3 only Upper; share 4 + 8 with 6 low keys → 4 Lower voices, Upper keeps 8; Layer plays both parts per key; mode change with held notes leaves no hanging note - T075 [P] [US9] Perf scenario
twin-layer-6x6intests/perf/nota_perf.cppwithin SC-001's budget (SC-010)
Implementation for US9
- T076 [US9] Parts in
src/devices/instruments/Twin.cpp: run the Upper part's morph / matrix / FX / voices (already in the param table, T006);modeSingle / Layer / Split;splitkey"MIDI 0..127" (first key of Upper);share"Lower 2..10 (step 2)", "Upper = 12 − Lower", "Single → all 12 to Lower"; per-part allocator over its slice, stealing only within the part; share / mode changes release surplus voices (research R12) - T077 [US9] Per-part
octavetranspose (Split),vol/panbalance (Layer), per-part voice mode and glide; performance controls and expression reach both parts;seq.targetLower / Upper / Both (FR-072, FR-074) - T078 [US9] Card part switch in
Nota.App/DeviceCards/Instruments/TwinInstrumentCard.cs: Lower / Upper switch next to A / B (shown in Layer / Split), mode selector, split-key control (click "learn" from a played key), share slider; param names carry the part (FR-073) - T079 [US9] Copy part and load preset into part in
Nota.Application/Twin/TwinParts.cs: remaplo.*↔up.*ids; "Load into Lower / Upper" from the preset picker; loading into Upper of a Single patch turns it to Layer with the current sound as Lower; one undo step each (FR-075, US9-4) - T080 [US9] ≥ 6 Split / Layer factory presets in
Nota.Infrastructure/Persistence/FactoryPresetCatalog.cs(SC-011);read_twinreports mode / split / share (Nota.Mcp/Tools/TwinTools.cs)
Checkpoint — end of slice P3: Phase 12 closing tasks for PR 3; open PR 3.
Phase 12: Polish & Cross-Cutting (run per slice PR)
- T081 Run quickstart.md sections 1–4 for the slice and record results in the PR description
- T082 [P] Determinism: render the same project twice and after save / load — identical output (SC-008), including drift and sequencer
- T083 [P] Edge cases from spec § Edge Cases not already covered: sample-rate change, offline render at another rate, clone / copy-paste / freeze / Instrument Rack chain of a Twin (both sides, matrix, FX, patterns come along)
- T084 SC-007 walkthrough: build a two-sided morphing pad from Init in < 5 min using only the card; write it as the docs walkthrough (feeds T089)
Nota closing tasks (PR gates — per slice)
- T085 Run
scripts/build.sh(orscripts/build-linux.sh/scripts/build-win.ps1) until native + managed + smoke test are green - T086 AGPL-3.0-only SPDX two-line header on every new source file (
Twin*.{h,cpp},SteinerFilter.{h,cpp},TwinInstrumentCard.cs,TwinViews.cs,TwinTools.cs,Nota.Application/Twin/*.cs,TwinTests.cs) - T087 New dependency: N/A (none added; HIIR already listed in
LICENSES/third-party.md) - T088
CHANGELOG.md[Unreleased]entry for the slice (Added: Nota Twin …) - T089 FEATURES.md via the
nota-featuresskill; user docs EN + RU vianota-docs(new instrument page, screenshots); shortcuts vianota-shortcutsif the card adds any (else N/A) - T090 Smoke coverage confirmed for every engine behaviour the slice changed (
tests/Nota.SmokeTest/TwinTests.cs) - T091
/speckit-convergereports Converged for the slice's stories before the PR (constitution quality gate)
Dependencies & Execution Order
Phase dependencies
- Setup (1) → Foundational (2) → stories. T004–T005 (slice 0) can merge on their own before anything else; T021 needs T004.
- P1: US1 → US2 → US3 (US2 morphs US1's params; US3's pressure → morph needs US2's per-voice hook).
- P2: US4 needs US2 (per-side depths) and US3 (expression sources). US5 needs US1 only. US6 needs US2 + US4 + US5 (presets use them). US7 needs US4 + US5 (its tabs).
- P3: US8 needs US4 (seq sources), US6's preset blob path (T052). US9 needs US8's
seq.targetonly for T077; otherwise independent of US8. - Polish (12) closes each slice.
Story dependency graph
Setup → Foundational ─┬─ US1 → US2 → US3 ──(PR 1)
│ │ │
│ └──┬───┘
│ US4 ─┐
├─ (US1) → US5 ───┼─ US6 → US7 ──(PR 2)
│ │
│ US8 ─────────────┐
└─ (US4) ────────────────── US9 ──┴─(PR 3)
Within each story
Tests first (they should fail), then engine DSP → engine wiring → managed → card → presets / MCP.
Parallel opportunities
- Foundational: T011, T012, T013, T014 touch different files — parallel after T010.
- US1: T019 (filter) ∥ T020 (oscillator) ∥ T017 / T018 (tests); T021 joins them.
- US5 ∥ US4 once P1 is merged (different files: FX in
Twin.cppsections vsTwinMod.*— coordinate onTwin.cpp). - US8 ∥ US9 engine work (
TwinSeq.*vs part logic inTwin.cpp) — US9's T077 waits for T068. - Tests marked [P] in each story are independent of each other.
Parallel Example: User Story 1
Task: "SteinerFilter in src/native/nota.engine/src/dsp/primitives/SteinerFilter.{h,cpp}" # T019
Task: "Oscillator in src/native/nota.engine/src/devices/instruments/TwinVoice.{h,cpp}" # T020
Task: "Smoke Init / steal / unison / bounded-level checks in tests/Nota.SmokeTest/TwinTests.cs" # T017
Task: "Perf scenarios twin-full-12 and pentad-full-16 in tests/perf/nota_perf.cpp" # T018
Implementation Strategy
MVP first
- Phase 1 + 2 (with slice 0 merged as its own PR).
- US1 → validate: a good single-sided poly.
- US2 + US3 → PR 1: the MVP is the morphing, expressive poly — US1 alone would ship "another two-oscillator poly", which the spec explicitly calls insufficient.
Incremental delivery
- PR 1 (P1): US1–US3. PR 2 (P2): US4–US7. PR 3 (P3): US8–US9.
- Each PR keeps the param layout append-only, so projects from an earlier PR open unchanged.
Notes
- 93 tasks (T092 / T093 appended after the R2a measurement); [P] = different files, no unfinished dependency.
- Commits in the repo's style — the user reviews and commits; do not push.
- Stop at each checkpoint to validate the story on its own.
Phase 13: Convergence
- T094 Deliver release velocity to Twin: the matrix source "Release velocity" reads 0 (
Twin.cpp"not delivered yet") becauseInstrument::noteOffcarries no velocity; pass note-off velocity through the engine's note-off path (clips, live MIDI, MPE) into Twin and add a smoke check that a route from it moves a release-stage param, per FR-030 (partial) - T095 Strengthen the sequencer timing proof in
tests/Nota.SmokeTest/TwinTests.cs: step onsets over 64 bars at 60, 120 and 200 BPM within one sample of the grid, and "To clip" rendering identically to the running pattern (today: 4 s at 90 / 174 BPM, clip compared by onsets ±2 samples and level ±0.5 dB), per SC-009 (partial) - T096 "Load into Lower / Upper" (
TwinInstrumentCard.csParts menu) lists only factory presets: add the user's Twin presets (PresetService.List of kind 18) so two saved sounds can be combined, per FR-075 (partial) - T097 Motion-lane targets in the card's Seq tab cover Morph and the side params but not the expression pad: add Pad X / Y / Z to the lane target list (the engine already accepts any param index), per FR-063 (partial)
- T098 Add a smoke check that an idle Twin (no notes, effect tails gone) reports idle and costs no render time, with and without a stopped sequencer, per SC-006 (partial)
- T099 Review and justify in the PR the engine additions beyond the plan:
Delay::A_Reset/Reverb::A_Reset(fresh-device reset for Twin's silent-start re-seed, SC-008) andnota_audition_instrument_state(preset audition plays a Twin preset's pattern); record them incontracts/c-abi.md, per plan: C ABI contract (unrequested)
Phase 14: Hand test of PR #406 (2026-11-06)
- T100 Matrix tab as a grid, as Nota Consort's patch matrix (
TwinPatchMatrixinNota.App/Controls/TwinViews.cs, the card's Matrix tab): sources × destinations, drag a cell for the edited side's depth (a new route is the same on both sides for that drag), double-click / Clear removes, ⌥-click types; rows and columns from the routes first (6 × 5, up to 8 × 6), then the last picked per track and part; the route list goes, per US4 / FR-032 - T101 Seq and Arp from a held key with the transport stopped (
Twin::freeStart/freeStop,clockAt): the free clock runs at the host tempo from the key, the last key up stops it, Latch / Hold keeps it; the transport starting hands over to the song grid; the Seq / Arp hint says what to do next (On, an empty pattern, a key); smoke check, per FR-061 - T102 60 more factory presets (117 in all): classic pads, keys, brass, basses, leads, plucks and strings, and creative morph, FX, sequence, arpeggio and split / layer ones; the smoke test requires ≥ 110, per FR-053