Skip to content

armgit / nota

Public Imported from GitHub
0

Nota — a free DAW for macOS, Windows and Linux. No subscription, no account — just open it and make music.

10.4 KB
Raw Blame

Implementation Plan: Nota Twin — a morphing two-filter analog poly

Branch: feat/morph-poly-synth | Date: 2026-10-30 | Spec: spec.md

Input: Feature specification from specs/055-morph-poly-synth/spec.md

Summary

A new built-in instrument, Nota Twin (kind 18): up to 12 analog-modelled voices — two polyBLEP oscillators with a continuous Wave and a wavefolding Metal, noise, a new Steiner-Parker-style multimode filter and the shared ladder, a series ↔ parallel route, Brute feedback, three envelopes, three LFOs and seeded drift. Every sound parameter has an A and a B value per part, exposed as separate plugin-params (lo.a.cut1, lo.b.cut1), so the Morph between them — and automation that writes to the edited side — uses the existing param, automation, preset and undo machinery unchanged. A 64-slot matrix per part, eight macros, an internal FX chain built from Nota's Chorus / Flanger / Phaser / Delay / Reverb devices, a transport-locked polyphonic sequencer / arpeggiator with motion lanes (pattern data as an immutable snapshot, edited through the existing instrument action channel), and Single / Layer / Split with the 12 voices shared between two parts. One new C ABI function. Delivered in three slices (P1 → P2 → P3), each a shippable state. Decisions: research.md.

Nota: Read Before Planning

Consulted: ARCHITECTURE.md AR-4/5/6/7/9; the nota-instrument skill (DSP class, registration, card design); DESIGN.md + nota-design for the card; CONTRIBUTING.md for headers and dependencies.

Technical Context

Language/Version: C++20 (engine DSP, registration, C ABI); C# / .NET 10 (interop, catalog, presets, MCP, Remote, device card in Avalonia).

Primary Dependencies: none new. Reuses pentad:: oscillator core + HIIR decimators (already a listed dependency, fetched by CPM for Pentad / Consort), dsp::LadderFilter, dsp::SvfFilter (fallback), dsp/poly voice management, and the Chorus / Flanger / Phaser / Delay / Reverb devices.

Storage: project file and presets as for other built-ins — normalized params by id; Twin adds a pattern block to its state blob and to its presets' StateBase64 (research R11).

Audio-Thread Impact: new per-voice DSP in render(), allocation-free after construction (voices, FX devices, matrix tables, pattern storage pre-sized; the delay / reverb buffers are allocated in the constructor like Consort's). Param values arrive as atomics through the plugin-param interface; pattern edits publish an immutable snapshot (AR-5) the audio thread picks up with an atomic pointer load; retired snapshots are freed on the message thread (RackCore scheme). Musical time only from setTransport / TransportInfo (AR-9). No locks, no I/O.

Testing: tests/Nota.SmokeTest (new Twin section, contract items 1–5); render-comparison tests on deterministic (seeded) output; tests/perf/nota_perf.cpp scenarios (instrument-18, twin-full-12, twin-layer-6x6, pentad-full-16) and scripts/perf-gate.sh for the shared-ladder change; managed unit tests where the preset remap / "To clip" logic lives.

Target Platform: macOS (arm64 + x86_64), Windows x64, Linux x64 — as every built-in.

Project Type: desktop app (native engine + managed app).

Performance Goals: SC-001 — 12 voices, everything on, no dropouts at 128 samples on the reference Mac and ≤ 2 × Pentad at 16 voices; SC-006 — idle ≈ empty track; SC-009 — step onsets on the sample grid.

Constraints: append-only param order and action / scope ids; per-voice morph without per-sample param interpolation (R3); ≤ 1 050 params must not slow the app's param lists (R2a).

Scale/Scope: ≈ 5–6 k lines of engine C++ (Consort ≈ 2.3 k is the reference for one voice architecture; Twin adds parts, matrix, sequencer), one large device card, ≥ 40 presets, ≈ 38 registration sites.

Constitution Check

GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.

Principle Status How
I. Real-time safety ✅ pre-sized everything; params as atomics; patterns as immutable snapshots (AR-5); no lock / alloc / I/O in render(); transport from setTransport (AR-9)
II. Boundary discipline ✅ one new C function nota_engine_add_twin_track; everything else through existing generic param / action / state / scope calls; no JUCE
III. Licensing ✅ no new dependency; HIIR is already a listed dependency (LICENSES/third-party.md); every new file gets the two-line SPDX header; no Arturia names or material
IV. Verification gate ✅ smoke test extended (5 contract checks); perf scenarios added
V. One logical change per PR ⚠️ → ✅ the feature is large: shipped as three PRs, one per slice (P1 / P2 / P3), each green and usable on its own; the ladder 12 dB tap ships with P1 (no other instrument uses that primitive)
VI. Docs in sync ✅ CHANGELOG, FEATURES.md (nota-features), user docs EN + RU (nota-docs), shortcuts if the card adds any (nota-shortcuts) — per slice
VII. Spec-first ✅ this spec / plan / tasks
VIII. Rules not weakened ✅ no exceptions requested

Post-design re-check (after Phase 1): still passes. The design added no ABI beyond the one function, no shared mutable state with the audio thread beyond atomics and snapshots, and the param-per-side model keeps automation / undo inside existing mechanisms.

Delivery slices

Slice Stories Ships PR
0 — LadderFilter 12 dB tap — no instrument uses the primitive yet, so it ships with P1 (in PR 1)
P1 US1, US2, US3 Twin with one part: voice, A/B morph, expression, fixed routes, a first card (Osc · Filter · Env · LFO · Morph strip, pad), ~12 starter presets, kind registration everywhere, smoke + perf PR 1
P2 US4, US5, US6, US7 64-slot matrix + macros, FX section, ≥ 40 presets, full card (Matrix · FX tabs, S size, graphs, themes), MCP read_twin / set_twin_route / side tools PR 2
P3 US8, US9 sequencer / arp / motion lanes / patterns in presets / "To clip"; Lower / Upper parts, Split / Layer, voice share, load-into-part; MCP pattern tools PR 3

The param layout is designed for P3 from P1: P1 already declares both parts and both sides (Upper silent in Single) so no P1 project needs migration — later slices only append.

Project Structure

Documentation (this feature)

specs/055-morph-poly-synth/
├── spec.md
├── plan.md              # this file
├── research.md          # R1–R15 decisions
├── data-model.md        # params, routes, patterns, state blob
├── quickstart.md        # validation guide
├── contracts/
│   ├── c-abi.md         # new ABI function, action ids, scope layout, smoke contract
│   └── mcp-tools.md
├── checklists/requirements.md
└── tasks.md             # /speckit-tasks

Source Code (repository root)

src/native/nota.engine/
├── include/nota/nota_engine.h                 # + nota_engine_add_twin_track
├── src/abi/nota_engine_track.cpp              # + the ABI function
├── src/engine/Engine.h, Engine_Devices.cpp    # add track, clone, makeBuiltinInstrument
├── src/devices/DeviceFactory.cpp              # kind 18
├── src/devices/racks/RackCore.{h,cpp}         # makeInstrument kind 18
├── src/devices/instruments/
│   ├── Twin.h / Twin.cpp                      # instrument: params, parts, voice pool, render, state
│   ├── TwinVoice.h / TwinVoice.cpp            # one voice: oscs, Metal, mixer, filters, Brute, envs
│   ├── TwinMod.h / TwinMod.cpp                # morph evaluation, matrix, LFOs, sources/dests tables
│   └── TwinSeq.h / TwinSeq.cpp                # patterns snapshot, sequencer, arp, motion (P3)
├── src/dsp/primitives/
│   ├── SteinerFilter.h / .cpp                 # new multimode filter (R5)
│   └── LadderFilter.h / .cpp                  # + 12 dB tap (slice 0)
├── src/devices/midi_fx/Arpeggiator.*          # factor note-order helper if needed (R10)
└── CMakeLists.txt

src/managed/
├── Nota.Infrastructure/Interop/NativeMethods.Tracks.cs, NotaEngine.Tracks.cs
├── Nota.Infrastructure/Persistence/
│   ├── FactoryPresetCatalog.cs                # Twin presets (+ TwinSeq text form)
│   ├── PresetService.cs                       # Twin: NamedParams + pattern StateBase64; load into part
│   └── ProjectService.cs
├── Nota.Infrastructure/Audition/PresetAudition.cs
├── Nota.Application/Engine/IAudioEngine.cs
├── Nota.Application/Palette/BuiltinDeviceCatalog.cs, DeviceCategories.cs
├── Nota.Application/Twin/                     # side / part copy, pattern → clip (pure logic, unit-testable)
├── Nota.Presentation/DeviceInsertService.cs, Racks/RackKeyParams.cs
├── Nota.App/DeviceCards/InstrumentCardFactory.cs
├── Nota.App/DeviceCards/Instruments/TwinInstrumentCard.cs   # the card (tabs, A/B, parts)
├── Nota.App/Controls/TwinViews.cs             # waveform, dual-filter response, matrix grid, step grid, pad
├── Nota.App/DeviceCards/Rack/*, DeviceChainView.Shell.cs, NotaDocs.cs, PreferencesWindow.cs, Theme/NotaGeometry.cs
├── Nota.Mcp/Tools/InstrumentTools.cs (+ TwinTools.cs)
└── Nota.Remote/RemoteParams.cs

tests/
├── Nota.SmokeTest/Program.cs (+ TwinTests.cs)
└── perf/nota_perf.cpp

Structure Decision: one instrument split across four engine translation units (instrument / voice / modulation / sequencer) so each slice touches its own files; managed logic that is not view code (side copy, part remap, pattern → clip) goes to Nota.Application/Twin/ so it is unit-testable without the UI. Every registration site mirrors Consort's.

Complexity Tracking

Violation Why Needed Simpler Alternative Rejected Because
~1 050 params on one instrument (others ≤ 160) per-side params are what makes FR-024 (automation per side), presets, undo and CV work with no new mechanism a hidden B-side blob would need a parallel automation / undo / preset path for side B
Three PRs for one feature (Principle V) P1 alone is a full instrument; P3's sequencer and parts are each large one PR would be unreviewable; finer splits would ship unplayable intermediate states