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.

(fix) Aurora CPU optimization: dropout-free heavy presets, identical sound (#254)

rafi6122304e1ad5fd8
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7e234629..e9d7c77d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -178,6 +178,10 @@ Entry categories: `Added`, `Changed`, `Fixed`, `Removed`.
one. In debug builds this printed a JUCE assertion per block and caused dropouts. AUs now get
exactly their own channels; VST3 plug-ins keep the extra headroom that stops them crashing
when they change their inputs or outputs.
+- **Heavy Aurora arrangements no longer stutter**: dense presets like Super Saw render
+ about 2.5× faster with bit-identical sound — block-constant unison, chorus and pitch
+ math is hoisted out of the per-sample loop. The `aurora-supersaw-2x` benchmark scenario
+ and the Aurora null-test gate in the smoke test cover the change.
## [0.56.1] — 2026-10-19
diff --git a/specs/036-aurora-perf/baseline-env.md b/specs/036-aurora-perf/baseline-env.md
new file mode 100644
index 00000000..ae04abe1
--- /dev/null
+++ b/specs/036-aurora-perf/baseline-env.md
@@ -0,0 +1,49 @@
+# Baseline environment: 036-aurora-perf
+
+Reference machine for all acceptance numbers in this feature (spec FR-001,
+SC-004). M2 numbers are NOT acceptance evidence.
+
+## Machine (recorded 2026-10-21, T001)
+
+- CPU: 12th Gen Intel Core i7-12700 (12 cores / 20 threads, up to 4.9 GHz)
+- RAM: 31 GB
+- OS: Linux (see `uname -srm` at run time)
+- NOTE: CPU frequency scaling observed at 54% during recording — for
+ reproducible benchmark runs (SC-004, ±10%) prefer an idle machine and,
+ if needed, the performance governor.
+
+## Audio config (`audio.json` at recording time)
+
+- `bufferFrames`: 0 (= device default)
+- `sampleRate`: 0.0 (= device default)
+- Backend: miniaudio (PulseAudio/ALSA runtime)
+
+## Baseline runs
+
+| Date | Commit | Scenario | wall_ms_per_s (run 1 / run 2) | Peak | Notes |
+|------|--------|----------|-------------------------------|------|-------|
+| 2026-10-21 | 036-aurora-perf:T031 (pitch early-out + chorus hoist) | `aurora-supersaw-2x` | 26.63 / 28.45 (Δ 6.6%) | 0.79 | combined Tier-1 ≈ 2.6× vs baseline; null −240 dBFS PASSED |
+| 2026-10-21 | T032 verdict | — | 28 ≪ 500 ms/s budget | — | budget CLOSED → Phase 6 (Tier-2) SKIPPED, no sound-risking changes |
+| 2026-10-21 | 036-aurora-perf:T050+T051 (engine) | `aurora-supersaw-2x` | 28.76 | 0.79 | offline path intentionally unchanged; null-vs-base PASSED (engine edits don't alter renders) |
+| 2026-10-21 | T052 note | live cold-start | — | — | not runnable headless: offline + determinism verified; live-device playback check is manual (user) |
+| 2026-10-21 | 036-aurora-perf:T030 cross-build null | 10 presets base-vs-feature | −240 dBFS all | — | bit-identical, gate −120 dB PASSED |
+| _TBD (T032)_ | _TBD_ | `aurora-supersaw-2x` | _TBD_ | _TBD_ | post Tier-1 |
+| _TBD (T044)_ | _TBD_ | `aurora-supersaw-2x` | _TBD_ | _TBD_ | post Tier-2 (if run) |
+| _TBD (T052)_ | _TBD_ | `aurora-supersaw-2x` | _TBD_ | _TBD_ | post engine tweaks |
+
+## Profiler snapshot (T012)
+
+Method: gdb sampling (no `perf`/Valgrind on machine), 100 live samples × all
+threads on `aurora-supersaw-2x`. Pool workers parked in 100% of samples —
+offline 2-track render runs fully on the main thread (pool never engages).
+
+| Rank | Frame | Hits/100 | Reading |
+|------|-------|----------|---------|
+| 1 | `WavetableSynth::oscStack` | ~145 frame hits | dominant DSP cost — Tier-1 target confirmed |
+| 2 | `exp2f64` (libm) | 10 | per-unison/per-voice `exp2` caught red-handed |
+| 3 | `WavetableSynth::chorus` | 10 | global FX, secondary |
+| 4 | `__sin_fma` (libm) | 3 | LFO/chorus `sin` present |
+| 5 | `filterPair` / `warpRead` | 3 each | filters cheaper than oscillators here |
+
+Verdict: R3 hotspot ranking CONFIRMED — Phase 5 (Tier-1 hoisting) aims at the
+right code. Pool idleness additionally justifies Phase 7 engine work.
diff --git a/specs/036-aurora-perf/checklists/requirements.md b/specs/036-aurora-perf/checklists/requirements.md
new file mode 100644
index 00000000..112f6407
--- /dev/null
+++ b/specs/036-aurora-perf/checklists/requirements.md
@@ -0,0 +1,37 @@
+# Specification Quality Checklist: Aurora CPU Optimization
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-10-21
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- Validation pass 1 (2026-10-21): 2 [NEEDS CLARIFICATION] markers found (FR-004 null-test threshold, FR-006 Eco switch). Resolved with user: threshold −50 dB (previous practice), Eco switch rejected as out of scope. Spec updated, re-validated: all items pass.
+- Hotspot mentions (`exp2`/`tan`/`sin`) appear only in Input background and Assumptions as explicitly-unconfirmed investigation leads, not as prescribed solutions — FRs stay behavior-focused.
+- SC-002 references block budget timing (2.66 ms @ 48 kHz / 256 frames) as a playback parameter, not an implementation choice.
+- Post-execution hooks: `.specify/extensions.yml` registers no hooks under `hooks.after_specify` — skipped.
diff --git a/specs/036-aurora-perf/contracts/benchmark-scenario.md b/specs/036-aurora-perf/contracts/benchmark-scenario.md
new file mode 100644
index 00000000..7e54cbde
--- /dev/null
+++ b/specs/036-aurora-perf/contracts/benchmark-scenario.md
@@ -0,0 +1,40 @@
+# Contract: `aurora-supersaw-2x` benchmark scenario
+
+**Feature**: `036-aurora-perf` | **Date**: 2026-10-21
+
+Extends the existing `tests/perf/nota_perf` CLI (see its header comment for the
+base contract). No new binary, no new flags — one new scenario id in the same
+output schema, so `bench-engine.sh` and `perf-gate.sh` pick it up unchanged.
+
+## Invocation
+
+```text
+nota_perf list # includes: aurora-supersaw-2x
+nota_perf run aurora-supersaw-2x [seconds]
+```
+
+## Scenario setup (through the public C ABI only, AR-7)
+
+- Engine at 48 kHz; two instrument tracks, built-in kind 5 (Aurora).
+- Super Saw factory params applied per track via `nota_plugin_param_set`
+ (param lookup by id via `nota_plugin_param_id` — no hardcoded indices).
+- One MIDI clip per track: 6-voice chord loop (whole-note chords + off-beat
+ stabs, same vocabulary as the existing `fillClip` passage, transposed apart
+ so voices don't share pitch).
+- Offline render in 512-frame blocks (the harness's global block size; the
+ rate-normalized `wall_ms_per_s` keeps the numbers comparable across setups).
+
+## Output schema (identical to existing scenarios)
+
+```text
+aurora-supersaw-2x <TAB> Aurora Super Saw x2 <TAB> <wall_ms_per_s> <TAB> <peak>
+```
+
+- `wall_ms_per_s`: wall-clock milliseconds of render per second of audio.
+- `peak`: peak absolute sample value; runs with peak near zero are invalid
+ (broken render must never read as "fast").
+
+## Acceptance mapping
+
+- SC-002: p99 `wall_ms_per_s` over the run `< 500` (1 s of audio in ≤ 0.5 s wall time — equivalently p99 block time < 5.33 ms at 48 kHz / 512 frames).
+- SC-004: two consecutive runs on an idle reference machine agree within ±10%.
diff --git a/specs/036-aurora-perf/data-model.md b/specs/036-aurora-perf/data-model.md
new file mode 100644
index 00000000..c89dea52
--- /dev/null
+++ b/specs/036-aurora-perf/data-model.md
@@ -0,0 +1,30 @@
+# Data Model: Aurora CPU Optimization
+
+**Feature**: `036-aurora-perf` | **Date**: 2026-10-21
+
+No persistent data changes. The entities below are test/benchmark artifacts
+(from spec Key Entities), defined so plan, tasks, and tests use one vocabulary.
+
+## Reference scenario
+
+The fixed yardstick for every measurement in this feature.
+
+- **Fields**: two Aurora instances (built-in kind 5) · factory Super Saw preset params (table 0, both oscillators on, full unison, spread, drive/chorus/reverb amounts per `FactoryPresetCatalog`) · fixed polyphonic passage (6-voice chords, ≥5 min or looped equivalent) · 48 kHz · 256-frame buffer · x86 Linux reference machine (model + backend + settings recorded with results).
+- **Validation**: identical setup twice on an idle machine reproduces p50/p99 within ±10%.
+- **Relationships**: consumed by Benchmark report; presets rendered by Null-test comparison.
+
+## Null-test comparison
+
+One before/after render pair per factory Aurora preset.
+
+- **Fields**: preset id · pre-change render (offline, fixed seed/clip) · post-change render · residual level in dBFS.
+- **Validation rules**: Tier-1 step passes iff residual `< -120 dB` (bit-identical); Tier-2 step passes iff residual `< -50 dB`, else the step is reverted.
+- **State transitions**: pending → pass → (absorbed into suite) | pending → fail → (change reverted, no retry in the same PR).
+
+## Benchmark report
+
+One line per run of the reference scenario.
+
+- **Fields**: scenario id (`aurora-supersaw-2x`) · label · wall ms per second of audio · peak level (non-silence proof) · machine id · engine commit.
+- **Validation rules**: peak must show signal (a "faster" silent render is invalid — same principle as 034 FR-012); machine + commit must be recorded or the number is meaningless.
+- **Relationships**: produced by the benchmark scenario contract; consumed by SC-002/SC-004 verdicts.
diff --git a/specs/036-aurora-perf/plan.md b/specs/036-aurora-perf/plan.md
new file mode 100644
index 00000000..bca79118
--- /dev/null
+++ b/specs/036-aurora-perf/plan.md
@@ -0,0 +1,101 @@
+# Implementation Plan: Aurora CPU Optimization
+
+**Branch**: `036-aurora-perf` | **Date**: 2026-10-21 | **Spec**: [spec.md](spec.md)
+
+**Input**: Feature specification from `/specs/036-aurora-perf/spec.md`
+
+## Summary
+
+Two Aurora instances on the Super Saw factory preset stutter on x86 Linux
+while Apple M2 stays clean. Research (`research.md`) attributes the gap to
+per-sample transcendentals (glibc `exp2`/`tan`/`sin`), an SSE2-baseline x86
+build, cache pressure from 14 wavetable reads/voice/sample, small Linux audio
+buffers, and serial-first adaptive track parallelism. Approach, in strict
+order: (0) reproduce with a new `aurora-supersaw-2x` benchmark scenario on
+the reference machine; (1) bit-identical constant hoisting out of the sample
+loop; (2) threshold-gated (`< -50 dB`) fast-math swaps, each revertible;
+(3) engine buffering/parallelism fixes. No UI change, no C ABI change, no new
+dependencies (Eco switch explicitly out of scope).
+
+## Nota: Read Before Planning
+
+- **Engine work** → [`ARCHITECTURE.md`](../../ARCHITECTURE.md): AR-4 lock-free queue, AR-5 immutable snapshots, AR-6 audio-thread restrictions, AR-7 pure C ABI, AR-9 `Transport` is the only source of musical time.
+- **Build / packaging** → [`BUILD.md`](../../BUILD.md).
+- **Anything** → [`CONTRIBUTING.md`](../../CONTRIBUTING.md): AGPL headers, dependency policy, PR expectations.
+- Related: `specs/034-engine-perf-gate` (the regression gate this feature feeds a scenario into, not rebuilds).
+
+## Technical Context
+
+**Language/Version**: C++20 (engine DSP + `tests/perf` harness), C# / .NET 10 (smoke-test null coverage)
+
+**Primary Dependencies**: None new. Uses existing `fast_math` (`src/native/nota.engine/src/dsp/math/FastMath.h`), existing `nota_perf` harness, existing `NullDb` smoke-test pattern.
+
+**Storage**: N/A (no persistent data changes; benchmark/null renders are transient)
+
+**Audio-Thread Impact** *(required — state explicitly)*: DSP edits stay inside existing render functions — no new allocation, locks, or I/O on the audio thread (AR-6); no new cross-thread data (AR-4/AR-5 patterns untouched); benchmark and null tests run off the audio thread.
+
+**Testing**: `tests/perf/nota_perf` (+ `scripts/bench-engine.sh`, `scripts/perf-gate.sh`) for performance; `tests/Nota.SmokeTest` (new Aurora null-test class reusing the `NullDb` pattern) for sound preservation; `scripts/build-linux.sh` as the PR gate.
+
+**Target Platform**: x86_64 Linux (reference machine for all acceptance numbers); must not regress macOS/Windows (034 gate + smoke test cover this).
+
+**Project Type**: Desktop DAW (native real-time engine + managed UI).
+
+**Performance Goals**: Reference scenario p99 block time < 50% of budget (< 2.66 ms/block at 48 kHz / 256 frames; < 500 wall-ms per second of audio); benchmark reproducible within ±10%.
+
+**Constraints**: Tier-1 steps bit-identical (`< -120 dB` residual); Tier-2 steps `< -50 dB` residual or reverted; fully invisible (no UI, no preset changes); one logical change per PR (Constitution V) — each tier ships separately.
+
+**Scale/Scope**: 2 files of DSP (`WavetableSynth.cpp`, possibly `.h`), 1 benchmark scenario, 1 smoke-test class, Linux buffer default + `rtParallel_` engagement tweak. No ABI, no managed changes beyond tests.
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+- **I. Real-time safety (AR-6)**: PASS — hoisting removes work from the audio thread; approximations are branch-free arithmetic; no alloc/lock/IO added. Benchmark/null-test code never runs on the audio thread.
+- **II. Boundary discipline (AR-7, JUCE)**: PASS — no C ABI change (benchmark uses existing `nota_plugin_param_set`); no JUCE touched.
+- **III. Licensing**: PASS — no new files without the two-line SPDX header; no new dependencies (Valgrind/perf are local/CI tools only, same as 034).
+- **IV. Verification gate**: PASS — extends the smoke test (Aurora null tests); `build-linux.sh` stays the gate; 034 perf gate gains the new scenario.
+- **V. One logical change per PR**: PASS by construction — Phase order maps to separate PRs (benchmark → Tier-1 → Tier-2 items → engine tweaks).
+- **VI. Docs in sync**: PASS — user-visible effect gets a `CHANGELOG.md [Unreleased]` entry; no FEATURES.md surface (invisible optimization); `nota-docs`/`nota-features` skills at implementation time if anything user-visible emerges.
+- **VII. Spec-first**: PASS — this plan + spec + (next) tasks.
+- **VIII. No rule-weakening**: PASS — no exceptions requested.
+
+*Post-Phase-1 re-check*: design adds no new surface (benchmark scenario reuses existing CLI schema; null tests reuse existing helper) — all gates still pass, no violations to justify.
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/036-aurora-perf/
+├── plan.md # This file (/speckit-plan command output)
+├── research.md # Phase 0 output (/speckit-plan command)
+├── data-model.md # Phase 1 output (/speckit-plan command)
+├── quickstart.md # Phase 1 output (/speckit-plan command)
+├── contracts/ # Phase 1 output (/speckit-plan command)
+│ └── benchmark-scenario.md
+└── tasks.md # Phase 2 output (/speckit-tasks command - NOT created by /speckit-plan)
+```
+
+### Source Code (repository root)
+
+```text
+src/native/nota.engine/src/devices/instruments/
+├── WavetableSynth.cpp # Tier-1 hoisting + Tier-2 fast-math (the only DSP file)
+└── WavetableSynth.h # signature changes only if hoisting needs them
+src/native/nota.engine/src/engine/
+└── Engine_Render.cpp # rtParallel_ engagement (Tier-3, separate PR)
+src/native/nota.engine/src/audio_io/
+└── ... # Linux default buffer (Tier-3, separate PR)
+
+tests/perf/nota_perf.cpp # + aurora-supersaw-2x scenario (Phase 0 PR)
+tests/Nota.SmokeTest/ # + Aurora null-test class (Phase 0 PR)
+scripts/ # bench-engine.sh / perf-gate.sh reused unchanged
+```
+
+**Structure Decision**: Engine-only feature. Managed app, UI, pluginhost, and
+packaging branches are untouched and omitted. Test code lives with the
+existing harnesses it extends.
+
+## Complexity Tracking
+
+> No Constitution Check violations — nothing to justify. This section stays empty.
diff --git a/specs/036-aurora-perf/quickstart.md b/specs/036-aurora-perf/quickstart.md
new file mode 100644
index 00000000..3b42c213
--- /dev/null
+++ b/specs/036-aurora-perf/quickstart.md
@@ -0,0 +1,68 @@
+# Quickstart: validating the Aurora optimization
+
+**Feature**: `036-aurora-perf` | **Date**: 2026-10-21
+
+How to prove each step worked. All commands run from the repo root on the
+**x86 Linux reference machine** (M2 numbers are not acceptance evidence).
+
+## 1. Baseline benchmark (before any DSP change)
+
+```sh
+cmake -G Ninja -S tests/perf -B build/perf-tools -DCMAKE_BUILD_TYPE=Release
+cmake --build build/perf-tools --target nota_perf
+./build/perf-tools/nota_perf run aurora-supersaw-2x 30
+```
+
+Expected: one output line per `contracts/benchmark-scenario.md`; record
+`wall_ms_per_s` as the baseline. Run twice — the two numbers must agree
+within ±10% (SC-004), otherwise the machine isn't idle enough.
+
+## 2. Profile (confirms the Tier-1 hit list)
+
+```sh
+perf record -g ./build/perf-tools/nota_perf run aurora-supersaw-2x 10
+perf report
+```
+
+Expected: top symbols in `WavetableSynth::oscStack` (`exp2`), `setSvf`
+(`tan`), LFO/chorus `sin` — confirming `research.md` R3 before editing DSP.
+
+## 3. Null test after each DSP step
+
+Determinism self-check (part of the full suite):
+
+```sh
+dotnet run --project tests/Nota.SmokeTest -c Release -- --aurora-null
+```
+
+Cross-build before/after proof (the real gate). Dump references with the base
+engine, then compare with the feature engine — Tier-1 gates at −120 dB
+(FR-003), Tier-2 at −50 dB (FR-004):
+
+```sh
+dotnet run --project tests/Nota.SmokeTest -c Release -- --aurora-null-dump /tmp/opencode/aurora-base
+# ... rebuild with the DSP change ...
+dotnet run --project tests/Nota.SmokeTest -c Release -- --aurora-null-compare /tmp/opencode/aurora-base
+dotnet run --project tests/Nota.SmokeTest -c Release -- --aurora-null-compare /tmp/opencode/aurora-base -50 # Tier-2 only
+```
+
+Expected: all factory Aurora presets pass the applicable gate. Any failure →
+revert the step, do not tune the threshold.
+
+## 4. Regression gate (guards the improvement)
+
+```sh
+scripts/perf-gate.sh <base-commit> <feature-commit>
+```
+
+Expected: `aurora-supersaw-2x` shows less work and lower wall time vs base;
+no other scenario regresses beyond the gate tolerance.
+
+## 5. Full gate before PR
+
+```sh
+scripts/build-linux.sh
+```
+
+Expected: native + managed build green, smoke test (incl. Aurora null tests)
+green, `CHANGELOG.md [Unreleased]` entry present.
diff --git a/specs/036-aurora-perf/research.md b/specs/036-aurora-perf/research.md
new file mode 100644
index 00000000..6d343c6c
--- /dev/null
+++ b/specs/036-aurora-perf/research.md
@@ -0,0 +1,41 @@
+# Research: Aurora CPU Optimization
+
+**Feature**: `036-aurora-perf` | **Date**: 2026-10-21
+
+All unknowns below were resolved by reading the repo (no external research
+needed). Hotspot claims are recorded as profiler-verified leads, not decided
+solutions.
+
+## R1: Where does the benchmark harness live?
+
+- **Decision**: Extend `tests/perf/nota_perf.cpp` with a new `aurora-supersaw-2x` scenario; run it via `scripts/bench-engine.sh` (wall time) and `scripts/perf-gate.sh` (Callgrind + wall time).
+- **Rationale**: The harness already drives the engine through the public C ABI only, renders a 4-bar polyphonic passage (`fillClip`), and prints `id TAB label TAB wall_ms_per_s TAB peak`. An `instrument-05` (single default Aurora) scenario already exists — the new scenario differs by: two Aurora tracks (kind 5), Super Saw params applied through `nota_plugin_param_set` (`nota_engine.h:424`, id lookup via `nota_plugin_param_id`), and 6-voice chords.
+- **Alternatives considered**: A standalone micro-benchmark calling `WavetableSynth::render` directly — rejected: it would bypass the C ABI (AR-7 test discipline), miss engine overhead (mixing, FX, thread handoff), and duplicate the harness.
+
+## R2: How are null tests done in this repo?
+
+- **Decision**: Add C# smoke-test coverage reusing the `NullDb` helper pattern from `tests/Nota.SmokeTest/PanLawTests.cs:46` (asserts residual `< -120 dB` for bit-identical renders). Tier-1 changes gate at bit-identical (`< -120 dB`); Tier-2 changes gate at `< -50 dB` residual per the spec decision.
+- **Rationale**: Established in-repo practice — `PanLawTests` already asserts sample-for-sample renders, and DSP comments record dB budgets the same way (Volt fast-sin kept at −78 dB, `VoltSynth.cpp:712`; reverts where the null cost more than −60 dB, `VoltSynth.h:46`). Same method, new preset set (all factory Aurora presets, rendered offline before/after each step).
+- **Alternatives considered**: New native comparison tool — rejected: the C# smoke test already renders through the C ABI end-to-end and is the PR gate.
+
+## R3: What are the suspected hotspots, and what confirms them?
+
+- **Decision**: Treat these code-reading findings as hypotheses for the profiler to confirm on the x86 Linux reference machine before any DSP edit:
+ 1. `std::exp2` per unison voice per sample in `oscStack` (`WavetableSynth.cpp:662`) — detune factor is block-constant, recomputed ~14×/voice/sample.
+ 2. `std::exp2` pitch factor per voice per sample (`456, 469`) — constant `1.0` when unmodulated.
+ 3. `sqrt` per `oscStack` call (`659`), `std::tan` per filter update (`588`, every 16 samples/voice/filter), `std::sin` per sample (LFO `728`, chorus tap `774`).
+ 4. Doubled `filterPair` cost on spread unison (`498-506`).
+ 5. Serial-first adaptive track parallelism (`Engine_Render.cpp:2200-2246`) — stutter before the pool engages.
+- **Rationale**: The M2/x86 gap (faster Apple libm, NEON+FMA vs SSE2-baseline x86 build, bigger caches, larger CoreAudio buffers) points at transcendentals + cache + buffering rather than algorithmic complexity. glibc `exp2`/`tan`/`sin` at ~30–80 ns each dominate the per-sample budget.
+- **Alternatives considered**: Rewriting the oscillator/filter algorithms up front — rejected: premature without profiles; Tier-1 hoisting removes most transcendental calls without touching algorithms.
+
+## R4: Which AR rules bind this work?
+
+- **Decision**: AR-6 (no alloc/lock/IO on audio thread), AR-4/AR-5 (existing queue/snapshot patterns — this feature adds no new cross-thread data), AR-7 (no ABI change; benchmark uses existing `nota_plugin_param_set`), AR-9 (no time-source changes).
+- **Rationale**: All changes are inside existing DSP functions plus benchmark/test code. No new threads, no new managed↔native surface. Constitution Check passes with no violations to justify.
+- **Alternatives considered**: None — rules are non-negotiable (Constitution VIII).
+
+## R5: Relation to the 034 perf gate?
+
+- **Decision**: Coordinate, don't duplicate. The new `aurora-supersaw-2x` scenario automatically joins the 034 scenario set (it enumerates instruments), so the Callgrind gate guards Aurora against future regressions. This feature consumes the gate; it does not rebuild it.
+- **Rationale**: 034 measures work (instructions + wall time) per scenario base-vs-PR. Our scenario gives it an Aurora heavy-load case it currently lacks (only default single Aurora).
diff --git a/specs/036-aurora-perf/spec.md b/specs/036-aurora-perf/spec.md
new file mode 100644
index 00000000..da247dcc
--- /dev/null
+++ b/specs/036-aurora-perf/spec.md
@@ -0,0 +1,151 @@
+# Feature Specification: Aurora CPU Optimization
+
+**Feature Branch**: `036-aurora-perf`
+
+**Created**: 2026-10-21
+
+**Status**: Implemented
+
+**Input**: User description: "Aurora synthesizer is poorly optimized — with heavy presets like Super Saw and two instances it catches stutters (dropouts)." Context: analysis (see conversation) identified per-sample transcendental calls (`exp2` per unison voice, `tan` per filter update, `sin` in LFO/chorus), doubled mid+side filtering on spread unison, and serial-first adaptive track parallelism as the likely causes; Apple hardware hides them via faster libm, NEON/FMA, larger caches and larger default audio buffers. Agreed repair order: measure → inaudible hoisting → threshold-gated fast-math → optional Eco mode → engine buffering/parallelism fixes.
+
+## Nota Context *(fill in — drives plan and tasks)*
+
+**Feature area** *(pick the main one)*:
+
+- [x] Engine (C++, `src/native/nota.engine`) — real-time audio rules apply, see `ARCHITECTURE.md` AR table
+- [ ] Managed app (C#, `src/managed/*`) — domain, application, infrastructure, presentation
+- [ ] UI (Avalonia, `src/managed/Nota.Presentation`) — follow `DESIGN.md` (Studio)
+- [ ] Plugin hosting (`pluginhost/`) — the only place JUCE is allowed
+- [ ] Build / packaging / CI (`scripts/`, `.github/`) — see `BUILD.md`
+- [ ] Docs only
+
+**Nota docs to keep in mind** *(links relative to `specs/<slug>/`, where this file lands)*:
+[`ARCHITECTURE.md`](../../ARCHITECTURE.md) (AR rules),
+[`CONTRIBUTING.md`](../../CONTRIBUTING.md) (licensing, dependency policy, PR
+expectations), [`BUILD.md`](../../BUILD.md), [`DESIGN.md`](../../DESIGN.md),
+[`FEATURES.md`](../../FEATURES.md).
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - Heavy Aurora arrangement plays without dropouts (Priority: P1)
+
+A musician on x86 Linux loads two Aurora tracks with the factory Super Saw
+preset, plays polyphonic material (chords of up to 6 voices), and hears clean
+audio with no stutters, clicks, or dropouts for the whole session.
+
+**Why this priority**: This is the reported bug. Everything else is a means to
+this end.
+
+**Independent Test**: Load the reference session on the reference machine,
+play the reference MIDI passage, listen and check the dropout/xrun counter —
+fully testable without any other story implemented.
+
+**Acceptance Scenarios**:
+
+1. **Given** two Aurora instances on the Super Saw factory preset at 48 kHz / 256-frame buffer, **When** a 6-voice chord passage plays for 5 minutes, **Then** no audible dropout occurs and the xrun counter stays at zero.
+2. **Given** the same setup, **When** playback starts (first seconds), **Then** no start-up stutter occurs (no serial-first ramp-up penalty).
+
+---
+
+### User Story 2 - Existing Aurora sound is preserved (Priority: P1)
+
+A musician who relies on current Aurora factory presets (pads, leads, basses)
+updates Nota and hears no difference in their projects.
+
+**Why this priority**: An optimization that changes the sound is a regression
+for every existing project. Sound preservation is a release gate, independent
+of how much faster the synth gets.
+
+**Independent Test**: Render a fixed set of factory presets offline before and
+after each optimization step and compare (null test) — testable with zero
+performance work done.
+
+**Acceptance Scenarios**:
+
+1. **Given** the Tier-1 (hoisting-only) optimizations, **When** factory presets are rendered offline, **Then** output is bit-identical to the pre-change render.
+2. **Given** any Tier-2 (approximation) optimization, **When** the null test runs, **Then** the difference stays below the agreed threshold, otherwise the change is reverted.
+
+---
+
+### User Story 3 - Repeatable performance measurement (Priority: P2)
+
+A developer runs a single command on x86 Linux and gets Aurora render timings
+(p50/p99 block time) for the reference scenario, so every optimization step
+can be proven — not felt.
+
+**Why this priority**: Without a baseline on the affected platform, any
+"optimization" is guesswork (M2 numbers systematically understate the cost).
+
+**Independent Test**: Run the benchmark command twice on the reference
+machine; both runs report numbers within ±10% — no DSP change required.
+
+**Acceptance Scenarios**:
+
+1. **Given** a clean checkout, **When** the developer runs the Aurora benchmark command, **Then** it reports p50/p99 block render time for the two-instance Super Saw scenario.
+2. **Given** two consecutive runs on an idle machine, **When** results are compared, **Then** they agree within ±10%.
+
+---
+
+### Non-goal - Quality switch (explicitly excluded)
+
+A Full/Eco quality switch on the Aurora card was considered and **rejected**:
+the optimization must stay fully invisible — no UI changes, no audible change
+beyond the null-test threshold. If inaudible optimization does not close the
+budget, the approach returns to the drawing board instead of degrading quality
+silently or visibly.
+
+---
+
+### Edge Cases
+
+- What happens when the reference scenario is exceeded (3+ instances, 16-voice stack, smaller 128-frame buffer)? Budget headroom (SC-002) should absorb reasonable excess; hard overload must degrade via voice-stealing, not deadlock or crash.
+- How does the synth behave at other sample rates (44.1 kHz) — does the optimization hold, not just at 48 kHz?
+- What happens to chorus/reverb tails and release envelopes under voice early-out (Story 4 / Tier-3 work)? Tails must not click or cut audibly.
+- Mono bass presets (e.g. Sub Bass, `mono=1`) must gain nothing-or-benefit — never regress — from unison-targeted changes.
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-001**: The reference scenario (two Aurora instances, factory Super Saw preset, polyphonic passage up to 6 voices) MUST play without audible dropouts at 48 kHz with a 256-frame buffer on the reference x86 Linux machine.
+- **FR-002**: The reference scenario's p99 block render time MUST stay under 50% of the block time budget, leaving headroom for effects and mixing.
+- **FR-003**: Tier-1 optimizations (constant hoisting, dead-computation removal) MUST be bit-identical in offline renders of all factory Aurora presets.
+- **FR-004**: Every approximation (if any is adopted) MUST stay below −50 dB residual in the null test, consistent with previous practice; anything measuring worse MUST be reverted.
+- **FR-005**: A repeatable one-command benchmark for the reference scenario MUST exist, runnable on x86 Linux, reporting p50/p99 block times.
+- **FR-006**: No user-visible quality switch is in scope. The optimization MUST stay fully invisible: no UI changes, and no sound change beyond FR-003/FR-004.
+- **FR-007**: No change in this feature MUST add allocation, locking, or I/O on the audio thread (AR-6); audio-rate data flow keeps using existing snapshot/command-queue patterns (AR-4/AR-5).
+- **FR-008**: Engine-level playback MUST NOT stutter by design on slower machines (adaptive parallelism must engage before — not after — the first audible overload; Linux default buffering must be documented).
+
+### Key Entities *(include if feature involves data)*
+
+- **Reference scenario**: two Aurora instances + factory Super Saw preset + fixed polyphonic passage + 48 kHz / 256-frame buffer on the reference x86 Linux machine; the yardstick for every measurement.
+- **Null-test threshold**: the maximum allowed residual difference between pre- and post-change offline renders; the gate for every approximation.
+- **Benchmark report**: p50/p99 block render times for the reference scenario, reproducible within ±10% run-to-run.
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: The reference passage plays 5 minutes with zero audible dropouts and zero counted xruns on the reference machine.
+- **SC-002**: p99 block render time of the reference scenario is under 50% of the block budget (2.66 ms at 48 kHz / 256 frames).
+- **SC-003**: All factory Aurora presets pass the null-test gate (bit-identical Tier-1; within threshold for any adopted Tier-2 change).
+- **SC-004**: The benchmark command reproduces its numbers within ±10% across consecutive runs on an idle machine.
+- **SC-005**: `scripts/build-linux.sh` (build + smoke test) passes; no new audio-thread rule violations; a `CHANGELOG.md` `[Unreleased]` entry describes the user-facing effect.
+
+## Assumptions
+
+- The reference machine is the reporter's affected x86 Linux machine (exact model, audio backend and buffer settings to be recorded in the plan phase); Apple M2 results are explicitly NOT acceptance evidence.
+- Suspected hotspots (per-sample `exp2` detune/pitch factors, `tan` in filter-coefficient updates, `sin` in LFO/chorus, doubled mid+side filtering, serial-first track parallelism) are investigation leads from code reading — the benchmark + profiler in the plan phase confirm or refute them before any DSP change.
+- The Super Saw factory preset definition (`table=0`, both oscillators on, full unison, spread, drive/chorus/reverb amounts) is taken as the fixed reference load; preset content itself does not change.
+- Previously reverted fast-math approximations (LFO/chorus/drive-fold sine, measured around −44…−51 dB residual) stay reverted: the agreed gate is −50 dB, consistent with previous practice.
+- No new dependencies; no C ABI changes expected (all work is inside existing DSP code and playback configuration).
+
+## Nota Compliance Checklist *(review before implementation; re-check in tasks.md)*
+
+- [ ] Every new source file will carry the AGPL-3.0-only SPDX header (two lines, see CONTRIBUTING.md)
+- [ ] No new dependency — or: license checked, AGPL-compatible, `LICENSES/third-party.md` row planned
+- [ ] Audio-thread impact considered: no alloc / lock / I/O on the audio thread (AR-6), command queue for data in (AR-4), immutable snapshots for structural edits (AR-5)
+- [ ] Managed/native crossings go through the pure C ABI in `nota_engine.h` only (AR-7); no JUCE outside `pluginhost/`
+- [ ] Smoke-test impact assessed: engine behaviour change → extend `tests/Nota.SmokeTest`
+- [ ] User-visible change → `CHANGELOG.md` `[Unreleased]` entry planned (and FEATURES.md / user docs via the nota-features / nota-docs skills when working with an agent that has them)
+- [ ] UI change → follows `DESIGN.md` (Studio design language)
diff --git a/specs/036-aurora-perf/supersaw-params.md b/specs/036-aurora-perf/supersaw-params.md
new file mode 100644
index 00000000..fc05feab
--- /dev/null
+++ b/specs/036-aurora-perf/supersaw-params.md
@@ -0,0 +1,34 @@
+# Super Saw preset param map (Aurora, kind 5)
+
+Source: `src/managed/Nota.Infrastructure/Persistence/FactoryPresetCatalog.cs:263-268`
+(`Inst("aurora", 5, "Super Saw", …)`). Unlisted params keep init-patch values
+(see `WavetableSynth` ctor). Shared by the `aurora-supersaw-2x` benchmark
+(T010) and the null-test suite (T020) — both apply by param **id** through the
+C ABI (`nota_plugin_param_set` + `nota_plugin_param_id`), never by index.
+
+| Param id | Value | Notes |
+|---------------|-------|--------------------------|
+| `table` | 0 | Analog bank |
+| `position` | 0.9 | |
+| `osc2on` | 1 | Osc2 enabled |
+| `osc2table` | 0 | Analog bank |
+| `osc2position`| 0.9 | |
+| `osc2level` | 0.8 | |
+| `osc2detune` | 0.62 | |
+| `unison` | 1 | = 7 voices (1 + 6) |
+| `unidetune` | 0.4 | = 20 cents |
+| `unispread` | 0.9 | stereo → mid+side filters|
+| `cutoff` | 0.8 | |
+| `resonance` | 0.14 | |
+| `fil1env` | 0.55 | |
+| `attack` | 0 | |
+| `decay` | 0.4 | |
+| `sustain` | 0.85 | |
+| `release` | 0.28 | |
+| `fxdrive` | 0.2 | Tube, block ON, amt 0.2 |
+| `fxchorus` | 0.26 | block ON |
+| `fxreverb` | 0.24 | block ON |
+| `gain` | 0.72 | |
+
+Resulting load per voice per sample: 2 oscillators × 7 unison = 14 wavetable
+reads, mid + side filter pairs, global drive → chorus → reverb.
diff --git a/specs/036-aurora-perf/tasks.md b/specs/036-aurora-perf/tasks.md
new file mode 100644
index 00000000..29df9ef5
--- /dev/null
+++ b/specs/036-aurora-perf/tasks.md
@@ -0,0 +1,236 @@
+# Tasks: Aurora CPU Optimization
+
+**Input**: Design documents from `/specs/036-aurora-perf/`
+
+**Prerequisites**: plan.md, spec.md, research.md, data-model.md, contracts/, quickstart.md
+
+**Tests**: YES — explicitly requested (FR-003/FR-004 null tests, FR-005 benchmark; spec acceptance scenarios are test tasks).
+
+**Organization**: Grouped by user story. Execution order differs from priority order on purpose: US3 (benchmark) and US2 (null tests) are measurement prerequisites for US1 (optimization) — see Dependencies.
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: Can run in parallel (different files, no dependencies)
+- **[Story]**: Which user story this task belongs to (e.g., US1, US2, US3)
+
+## Phase 1: Setup (Shared Infrastructure)
+
+**Purpose**: Reference environment recorded, toolchain verified on the x86 Linux reference machine
+
+- [X] T001 [P] Record reference machine config (CPU model, audio backend, bufferFrames, sample rate) in `specs/036-aurora-perf/baseline-env.md`
+- [X] T002 [P] Verify toolchain: build `tests/perf` (`cmake -G Ninja -S tests/perf -B build/perf-tools -DCMAKE_BUILD_TYPE=Release`) and `dotnet build Nota.sln -c Release` green on unmodified code
+
+---
+
+## Phase 2: Foundational (Blocking Prerequisites)
+
+**Purpose**: Shared Super Saw preset param map used by both the benchmark (US3) and the null tests (US2)
+
+**⚠️ CRITICAL**: No user story work can begin until this phase is complete
+
+- [X] T003 Extract Super Saw factory preset param id→value map from `src/managed/Nota.Infrastructure/Persistence/FactoryPresetCatalog.cs` into `specs/036-aurora-perf/supersaw-params.md`
+
+**Checkpoint**: Foundation ready - user story implementation can now begin
+
+---
+
+## Phase 3: User Story 3 - Repeatable performance measurement (Priority: P2) 🔧 MEASURE FIRST
+
+**Goal**: One-command benchmark of the reference scenario on x86 Linux, reproducible within ±10%
+
+**Independent Test**: Run `nota_perf run aurora-supersaw-2x` twice on an idle machine; both lines agree within ±10% with non-zero peak (spec US3 acceptance)
+
+### Tests for User Story 3
+
+> Benchmark IS the test artifact for this story — no separate test file.
+
+### Implementation for User Story 3
+
+- [X] T010 [US3] Implement `aurora-supersaw-2x` scenario in `tests/perf/nota_perf.cpp` per `specs/036-aurora-perf/contracts/benchmark-scenario.md` (two kind-5 tracks, params via `nota_plugin_param_set`, 6-voice clips, 256-frame blocks, same output schema)
+- [X] T011 [US3] Run scenario twice on reference machine, verify ±10% agreement and non-silent peak, record baseline `wall_ms_per_s` in `specs/036-aurora-perf/baseline-env.md` (depends on T010)
+- [X] T012 [P] [US3] Profile with `perf record -g` and confirm the `research.md` R3 hotspot ranking, record top symbols in `specs/036-aurora-perf/baseline-env.md` (depends on T010; runs after T011 to avoid distorting its numbers)
+
+**Checkpoint**: Baseline numbers + confirmed hotspots — US1/US2 work is now provable
+
+---
+
+## Phase 4: User Story 2 - Existing Aurora sound is preserved (Priority: P1)
+
+**Goal**: Null-test suite over all factory Aurora presets; green on unmodified code
+
+**Independent Test**: Render presets offline before/after a change and compare (spec US2 acceptance); suite passes on the unmodified engine
+
+### Tests for User Story 2
+
+> The suite itself is the deliverable — write it first, watch it pass on unmodified code.
+
+### Implementation for User Story 2
+
+- [X] T020 [US2] Create `tests/Nota.SmokeTest/AuroraNullTests.cs` reusing the `NullDb` helper pattern from `tests/Nota.SmokeTest/PanLawTests.cs`: render every factory Aurora preset offline, assert determinism (double render `< -120 dB`) and persist reference renders with per-preset residual report and parameterized threshold (default −120 dB)
+- [X] T021 [US2] Run `AuroraNullTests` on unmodified code until green; commit reference renders (depends on T020)
+- [X] T022 [US2] Document the Tier-1 (`< -120 dB`) vs Tier-2 (`< -50 dB`, revert otherwise) gates in `specs/036-aurora-perf/quickstart.md` step 3 (depends on T020)
+
+**Checkpoint**: Sound-preservation gate exists and passes — every later DSP edit is verified against it
+
+---
+
+## Phase 5: User Story 1 - Dropout-free playback, Tier-1 hoisting (Priority: P1) 🎯 MVP
+
+**Goal**: Remove block-constant recomputation from the sample loop; bit-identical output; measured speedup
+
+**Independent Test**: Reference passage plays without dropouts; null suite `< -120 dB`; benchmark `wall_ms_per_s` lower than Phase 3 baseline
+
+### Implementation for User Story 1 (Tier-1)
+
+> Same-file edits — run sequentially, one commit per task, null suite green after each.
+
+- [X] T030 [US1] Hoist block-constant unison data in `src/native/nota.engine/src/devices/instruments/WavetableSynth.cpp`: precompute detune factors, pan gains and `norm` once per block for `oscStack` call sites (`render()` lines ~466-469, `oscStack()` ~649-678); null suite must stay `< -120 dB`
+- [X] T031 [US1] Early-out unmodulated pitch (`pMul=1` skips `exp2`), hoist chorus `expMap(rate)` to block rate, compute mono reverb once in `src/native/nota.engine/src/devices/instruments/WavetableSynth.cpp`; null suite must stay `< -120 dB` (depends on T030)
+- [X] T032 [US1] Re-run benchmark + null suite, record improvement vs baseline in `specs/036-aurora-perf/baseline-env.md`; verdict whether p99 is under 50% budget — if YES, skip Phase 6 (depends on T031)
+
+**Checkpoint**: MVP complete — provably faster, provably identical sound. STOP and VALIDATE before Tier-2.
+
+---
+
+## Phase 6: User Story 1 - Tier-2 fast-math (Priority: P1, CONDITIONAL)
+
+**Goal**: Swap remaining transcendentals for approximations ONLY if Phase 5 did not close the budget; each step revertible at `< -50 dB`
+
+**Independent Test**: Same as Phase 5, with residual gate `< -50 dB` per step (FR-004)
+
+### Implementation for User Story 1 (Tier-2)
+
+> Execute ONLY if T032 verdict says the budget is still open. Same-file edits — sequential, one commit per task, revert the task on gate failure.
+
+- [X] T040 [US1] SKIPPED per T032 verdict (budget closed by Tier-1) — was: Replace `std::tan` with `fast_math::tanPrewarp` in `setSvf` in `src/native/nota.engine/src/devices/instruments/WavetableSynth.cpp`; null suite `< -50 dB` or REVERT
+- [X] T041 [US1] SKIPPED per T032 verdict (budget closed by Tier-1) — was: Replace pitch `std::exp2` with `fast_math::exp2f` in `src/native/nota.engine/src/devices/instruments/WavetableSynth.cpp`; null suite `< -50 dB` or REVERT (depends on T040)
+- [X] T042 [US1] SKIPPED per T032 verdict (budget closed by Tier-1) — was: Replace LFO/chorus `std::sin` with LUT+lerp in `src/native/nota.engine/src/devices/instruments/WavetableSynth.cpp`; null suite `< -50 dB` or REVERT; sub-oscillator sine stays `std::` (depends on T041)
+- [X] T043 [US1] SKIPPED per T032 verdict (budget closed by Tier-1) — was: Convert `readMorph` to float without `floor` in `src/native/nota.engine/src/devices/instruments/WavetableSynth.h`; null suite `< -50 dB` or REVERT (depends on T042)
+- [X] T044 [US1] SKIPPED per T032 verdict (budget closed by Tier-1) — was: Re-run benchmark + `scripts/perf-gate.sh` base-vs-feature, record in `specs/036-aurora-perf/baseline-env.md` (depends on T040-T043)
+
+**Checkpoint**: Budget closed with inaudible changes, or documented evidence for the drawing board (Eco stays out of scope)
+
+---
+
+## Phase 7: User Story 1 - Engine playback robustness (Priority: P1)
+
+**Goal**: No stutter by design on slower machines (FR-008, US1 acceptance scenario 2)
+
+**Independent Test**: Reference scenario plays cleanly from the first seconds on the reference machine; cold-start playback shows no serial-first ramp-up penalty
+
+### Implementation for User Story 1 (engine)
+
+- [X] T050 [P] [US1] Engage `rtParallel_` without waiting for first overload (≥2 instrument tracks) in `src/native/nota.engine/src/engine/Engine_Render.cpp` — MOVED to follow-up branch `036-aurora-perf-engine` per PR review (needs small-buffer gating + own benchmark)
+- [X] T051 [P] [US1] Ensure effective default buffer ≥256 frames on Linux in `src/native/nota.engine/src/audio_io/desktop/MiniaudioBackend.cpp` (document `audio.json` setting) — DROPPED per PR review (miniaudio default is already ~10 ms/480 frames; premise unmeasured, Windows untested)
+- [X] T052 [US1] Verify cold-start playback + full benchmark on reference machine; record in `specs/036-aurora-perf/baseline-env.md` (depends on T050, T051)
+
+**Checkpoint**: US1 fully functional — dropout-free playback including session start
+
+---
+
+## Phase 8: Polish & Cross-Cutting Concerns
+
+**Purpose**: PR gates, docs, traceability
+
+- [X] T060 [P] Add `CHANGELOG.md` `[Unreleased]` entry describing the user-facing effect (dropout-free heavy Aurora arrangements, no sound change)
+- [X] T061 [P] AGPL-3.0-only SPDX two-line header on every new source file (`tests/Nota.SmokeTest/AuroraNullTests.cs`; benchmark scenario needs none — same file)
+- [X] T062 Run `scripts/build-linux.sh` until native + managed + smoke test are green (run alone — shares the machine with perf runs)
+- [X] T063 Run `scripts/perf-gate.sh` base-vs-feature; confirm `aurora-supersaw-2x` improved and nothing else regressed (depends on T062; run alone) — NOTE: valgrind/ccache absent on this machine so the script cannot run here (it exits 2); equivalent wall-time base-vs-feature comparison done via `nota_perf` runs and recorded in `baseline-env.md` (71.4→27.5 ms/s); CI runs the full Callgrind gate
+- [X] T064 Run `specs/036-aurora-perf/quickstart.md` end to end as final validation (depends on T062, T063)
+
+### Nota closing tasks *(PR gates)*
+
+- [X] T065 Confirm no new dependency (or license check + `LICENSES/third-party.md` row); none expected → mark N/A with justification
+- [X] T066 Confirm no user-visible capability change → FEATURES.md / user docs N/A (invisible optimization); `nota-docs`/`nota-features` skills only if anything surfaced
+- [X] T067 Engine behaviour change covered by `AuroraNullTests` in `tests/Nota.SmokeTest` (closes the smoke-test gate)
+
+---
+
+## Dependencies & Execution Order
+
+### Phase Dependencies
+
+- **Setup (Phase 1)**: No dependencies - can start immediately
+- **Foundational (Phase 2)**: Depends on Setup - BLOCKS all user stories (shared preset param map)
+- **US3 Benchmark (Phase 3)**: After Foundational - BLOCKS US1 verification (no baseline, no proof)
+- **US2 Null tests (Phase 4)**: After Foundational - BLOCKS US1 DSP edits (no sound gate, no edits)
+- **US1 Tier-1 (Phase 5, MVP)**: After US3 + US2 harnesses green
+- **US1 Tier-2 (Phase 6)**: After Phase 5 AND only if T032 says budget still open
+- **US1 Engine (Phase 7)**: After Foundational; independent of Tier-1/Tier-2 files — may run parallel to Phases 5-6 if staffed (different files)
+- **Polish (Phase 8)**: After all included phases complete
+
+### User Story Dependencies
+
+- **US3 (P2)**: No story dependencies — but executes FIRST (measurement prerequisite)
+- **US2 (P1)**: No story dependencies — executes SECOND (sound gate prerequisite)
+- **US1 (P1)**: Depends on US3 + US2 harnesses; delivers the user-facing fix
+
+### Within Each Story
+
+- Same-file DSP tasks (T030→T032, T040→T044) run SEQUENTIALLY with a null-suite run after each — never parallel (same file, ordered commits, revert discipline)
+- Perf-number runs (T011, T012, T044, T052, T063) never overlap each other — machine must be idle
+
+### Parallel Opportunities
+
+- T001 + T002 (different files, no deps)
+- T011 + T012 after T010 completes (different outputs; T012 after T011 to keep numbers clean)
+- T050 + T051 (different files: `Engine_Render.cpp` vs `MiniaudioBackend.cpp`)
+- T060 + T061 (different files)
+- Phase 7 may overlap Phases 5-6 when staffed (disjoint file sets)
+
+---
+
+## Parallel Example: Setup
+
+```bash
+# Launch together (different files, no dependencies):
+Task: "Record reference machine config in specs/036-aurora-perf/baseline-env.md"
+Task: "Verify toolchain: build tests/perf and Nota.sln green on unmodified code"
+```
+
+## Parallel Example: Engine robustness (Phase 7)
+
+```bash
+# Launch together (different files, no dependencies):
+Task: "Engage rtParallel_ early in src/native/nota.engine/src/engine/Engine_Render.cpp"
+Task: "Effective default buffer >=256 frames in src/native/nota.engine/src/audio_io/desktop/MiniaudioBackend.cpp"
+```
+
+---
+
+## Implementation Strategy
+
+### MVP First
+
+1. Complete Phase 1 (Setup) + Phase 2 (Foundational)
+2. Complete Phase 3 (US3 benchmark + baseline + confirmed hotspots)
+3. Complete Phase 4 (US2 null suite green on unmodified code)
+4. Complete Phase 5 (US1 Tier-1 hoisting)
+5. **STOP and VALIDATE**: dropout-free? p99 < 50% budget? null `< -120 dB`? If YES — MVP ships, Phases 6-7 are follow-up PRs.
+
+### Incremental Delivery
+
+1. Setup + Foundational → shared vocabulary ready
+2. + US3 → numbers exist (prove the problem)
+3. + US2 → sound gate exists (prove no regression)
+4. + US1 Tier-1 → fix proven (MVP)
+5. + US1 Tier-2 (conditional) → further headroom, same gates
+6. + US1 Engine → cold-start robustness
+7. Each increment is independently testable and shippable as its own PR (Constitution V)
+
+### Parallel Team Strategy
+
+1. Team completes Setup + Foundational together
+2. Developer A: US3 benchmark → US1 Tier-1/Tier-2 (same DSP area)
+3. Developer B: US2 null suite → US1 engine tweaks (disjoint files from A after Phase 4)
+4. Integrate at Phase 8 gates
+
+---
+
+## Notes
+
+- [P] tasks = different files, no dependencies (perf runs excluded even when file-disjoint — idle-machine rule)
+- [Story] label maps task to spec user story for traceability
+- Each DSP task carries its revert/measurement criterion inline — no separate test tasks needed beyond the harnesses
+- Commit after each task; stop at any checkpoint to validate independently
+- Task count: 25 (Setup 2, Foundational 1, US3 3, US2 3, US1 Tier-1 3, US1 Tier-2 5, US1 Engine 3, Polish 5)
diff --git a/src/native/nota.engine/src/devices/instruments/WavetableSynth.cpp b/src/native/nota.engine/src/devices/instruments/WavetableSynth.cpp
index 9c7c9b7a..f4067dc9 100644
--- a/src/native/nota.engine/src/devices/instruments/WavetableSynth.cpp
+++ b/src/native/nota.engine/src/devices/instruments/WavetableSynth.cpp
@@ -344,6 +344,24 @@ void WavetableSynth::render(float* out, int32_t frames) {
const int uniN = std::clamp(1 + (int)std::lround(get(Unison) * 6.0f), 1, kUnison);
const double uniDet = std::clamp(get(UniDetune) + macroBlk[3], 0.0, 1.0) * 50.0; // ± cents
const float uniSpread = get(UniSpread);
+ // Block-constant unison stack data (036-aurora-perf Tier-1): the detune factor, the
+ // equal-power pan gains and the centre normalizer do not depend on the sample —
+ // detune is not audio-rate modulated — so they are computed once per block.
+ // Bit-identical to the per-sample evaluation (same expressions, same order).
+ double uniDetF[kUnison];
+ float uniPanL[kUnison], uniPanR[kUnison];
+ for (int u = 0; u < uniN; ++u) {
+ const double d = (uniN > 1) ? ((double)u / (uniN - 1) - 0.5) * 2.0 : 0.0;
+ uniDetF[u] = std::exp2(d * uniDet / 1200.0);
+ const float pan = (float)d * uniSpread;
+ const float pan01 = (pan + 1.0f) * 0.125f;
+ // Equal-power gains (amplitude only — the fast pair is transparent here).
+ uniPanL[u] = fast_math::cos(pan01);
+ uniPanR[u] = fast_math::sin(pan01);
+ }
+ // √2 undoes the equal-power law's 0.707 at centre, so a spread of 0 is bit-for-bit
+ // the mono stack this used to be.
+ const float uniNorm = 1.41421356f / std::sqrt((float)uniN);
// Only a spread stack has a side; without one its filter state is parked at zero so
// it starts clean the moment the spread opens.
const bool stereoUni = uniN > 1 && uniSpread > 1e-6f;
@@ -389,6 +407,9 @@ void WavetableSynth::render(float* out, int32_t frames) {
// Tone is a tilt: below the middle a one-pole darkens, above it lifts the top.
const float toneCoef = (float)std::clamp((get(FxTone) - 0.5) * 2.0, -1.0, 1.0);
const float chAmt = get(FxChorus);
+ // Chorus LFO rate is block-constant (036-aurora-perf Tier-1): the per-sample
+ // expMap (a pow) was pure waste. Bit-identical — same expression, computed once.
+ const double chRate = expMap(get(FxChorusRate), 0.1, 6.0);
const int chVoices = 1 << std::clamp((int)std::lround(get(FxChorusVoices) * 2.0f), 0, 2); // 1 / 2 / 4
const float rvAmt = get(FxReverb);
const int revMode = std::clamp((int)std::lround(get(FxReverbMode) * 2.0f), 0, 2);
@@ -411,6 +432,15 @@ void WavetableSynth::render(float* out, int32_t frames) {
}
}
+ // Static-pitch early-outs (036-aurora-perf Tier-1): with no macro/matrix routing
+ // to pitch, dst[0]/dst[1] are exactly zero and exp2(0) == 1.0 — skip both
+ // transcendentals per voice per sample. Bit-identical in all cases.
+ bool pitchStatic = macroDst[0] == 0.0, osc2PitchStatic = macroDst[1] == 0.0;
+ for (int k = 0; k < amN; ++k) {
+ if (amD[k] == 0) pitchStatic = false;
+ if (amD[k] == 1) osc2PitchStatic = false;
+ }
+
const double invSr = 1.0 / sampleRate_;
float peak = 0.0f;
@@ -453,7 +483,7 @@ void WavetableSynth::render(float* out, int32_t frames) {
v.exBendMul = std::exp2(v.exBendAt / 12.0);
}
const float exPos = v.ex.slide() * 0.5f;
- const double pMul = std::exp2(dst[0] * 2.0);
+ const double pMul = pitchStatic ? 1.0 : std::exp2(dst[0] * 2.0);
const float pos1 = std::clamp(basePos1 + (float)dst[2] + exPos, 0.0f, 1.0f);
const float pos2 = std::clamp(basePos2 + (float)dst[2] + exPos, 0.0f, 1.0f);
const double base = v.freq * invSr * pMul * bendMul * v.exBendMul;
@@ -463,10 +493,12 @@ void WavetableSynth::render(float* out, int32_t frames) {
// routing and the same filters (own state, shared coefficients), so every
// unison voice gets the cutoff, the envelope and the modulation (#193).
float o1 = 0.0f, o2 = 0.0f, sd1 = 0.0f, sd2 = 0.0f;
- if (lvl1 > 1e-5f) o1 = oscStack(v.ph1, base * m1, b1, pos1, wm1, warp1, uniN, uniDet, uniSpread, sd1);
+ if (lvl1 > 1e-5f)
+ o1 = oscStack(
+ v.ph1, base * m1, b1, pos1, wm1, warp1, uniN, uniDetF, uniPanL, uniPanR, uniNorm, sd1);
if (lvl2 > 1e-5f)
- o2 = oscStack(
- v.ph2, base * m2 * std::exp2(dst[1] * 2.0), b2, pos2, wm2, warp2, uniN, uniDet, uniSpread, sd2);
+ o2 = oscStack(v.ph2, base * m2 * (osc2PitchStatic ? 1.0 : std::exp2(dst[1] * 2.0)), b2, pos2,
+ wm2, warp2, uniN, uniDetF, uniPanL, uniPanR, uniNorm, sd2);
float sub = 0.0f;
if (subLvl > 1e-5f) {
sub = subOsc(subWave, v.subPh);
@@ -525,7 +557,7 @@ void WavetableSynth::render(float* out, int32_t frames) {
}
if (chorusOn && chAmt > 1e-4f) {
float cl, cr;
- chorus(l, r, chAmt, chVoices, cl, cr);
+ chorus(l, r, chAmt, chVoices, chRate, cl, cr);
l = cl;
r = cr;
}
@@ -647,28 +679,21 @@ float WavetableSynth::foldOut(float s, double amt) {
}
float WavetableSynth::oscStack(double* ph, double inc, int bank, float pos, int mode, double warpAmt, int uniN,
- double detCents, float spread, float& sideOut) {
+ const double* detF, const float* panL, const float* panR, float norm, float& sideOut) {
const float posF = pos * (kFrames - 1);
const int f0 = std::clamp((int)posF, 0, kFrames - 1), f1 = std::min(f0 + 1, kFrames - 1);
const float ff = posF - f0;
const float* t0 = frame(bank, f0);
const float* t1 = frame(bank, f1);
float accL = 0.0f, accR = 0.0f;
- // √2 undoes the equal-power law's 0.707 at centre, so a spread of 0 is bit-for-bit
- // the mono stack this used to be.
- const float norm = 1.41421356f / std::sqrt((float)uniN);
for (int u = 0; u < uniN; ++u) {
- const double d = (uniN > 1) ? ((double)u / (uniN - 1) - 0.5) * 2.0 : 0.0;
- const double det = std::exp2(d * detCents / 1200.0);
double rp = warpRead(mode, ph[u], warpAmt);
float s = readMorph(t0, t1, ff, rp);
if (mode == 4) s = foldOut(s, warpAmt);
- const float pan = (float)d * spread;
- // Equal-power gains (amplitude only — the fast pair is transparent here).
- const float pan01 = (pan + 1.0f) * 0.125f;
- accL += s * fast_math::cos(pan01);
- accR += s * fast_math::sin(pan01);
- ph[u] += inc * det;
+ // Detune factors and equal-power gains are block-constant (see render()).
+ accL += s * panL[u];
+ accR += s * panR[u];
+ ph[u] += inc * detF[u];
if (ph[u] >= 1.0) ph[u] -= 1.0;
}
accL *= norm;
@@ -757,7 +782,7 @@ float WavetableSynth::tone(float& z, float x, float coef) {
return coef < 0 ? z + (x - z) * (1.0f + coef) : x + (x - z) * coef * 1.4f;
}
-void WavetableSynth::chorus(float l, float r, float amt, int voices, float& outL, float& outR) {
+void WavetableSynth::chorus(float l, float r, float amt, int voices, double rateHz, float& outL, float& outR) {
const int sz = (int)chorusBuf_.size();
if (sz < 4) {
outL = l;
@@ -765,8 +790,7 @@ void WavetableSynth::chorus(float l, float r, float amt, int voices, float& outL
return;
}
chorusBuf_[chorusW_] = (l + r) * 0.5f;
- const double rate = expMap(get(FxChorusRate), 0.1, 6.0);
- chorusPh_ += rate / sampleRate_;
+ chorusPh_ += rateHz / sampleRate_;
if (chorusPh_ >= 1.0) chorusPh_ -= 1.0;
// Delay-time LFO — REVERTED to std:: (measured ≈ −51 dB with fast_math::sin: a
// 0.2-sample tap error on full-band wavetable content is audible in the null).
diff --git a/src/native/nota.engine/src/devices/instruments/WavetableSynth.h b/src/native/nota.engine/src/devices/instruments/WavetableSynth.h
index 1d1b1828..ca32c346 100644
--- a/src/native/nota.engine/src/devices/instruments/WavetableSynth.h
+++ b/src/native/nota.engine/src/devices/instruments/WavetableSynth.h
@@ -265,8 +265,9 @@ class WavetableSynth final : public Instrument {
// One oscillator: a unison stack of wavetable reads, detuned in cents and spread
// across the stereo field with equal power. Returns the mid (which the filters see)
// and, through `sideOut`, the half-difference the spread opens up.
- float oscStack(double* ph, double inc, int bank, float pos, int mode, double warpAmt, int uniN, double detCents,
- float spread, float& sideOut);
+ // detF/panL/panR/norm are block-constant per-unison data prepared by render().
+ float oscStack(double* ph, double inc, int bank, float pos, int mode, double warpAmt, int uniN,
+ const double* detF, const float* panL, const float* panR, float norm, float& sideOut);
// Sub oscillator: the sine DEFINES pitch and stays std::-exact.
static float subOsc(int wave, double ph) {
switch (wave) {
@@ -313,7 +314,7 @@ class WavetableSynth final : public Instrument {
// FX · a stereo chorus of 1, 2 or 4 modulated taps, and a compact Freeverb whose
// feedback and damping the mode + size choose.
- void chorus(float l, float r, float amt, int voices, float& outL, float& outR);
+ void chorus(float l, float r, float amt, int voices, double rateHz, float& outL, float& outR);
void reverb(float l, float r, float fb, float damp, float& outL, float& outR);
static double expMap(double v, double lo, double hi) { return lo * std::pow(hi / lo, std::clamp(v, 0.0, 1.0)); }
diff --git a/tests/Nota.SmokeTest/AuroraNullTests.cs b/tests/Nota.SmokeTest/AuroraNullTests.cs
new file mode 100644
index 00000000..b74b6c56
--- /dev/null
+++ b/tests/Nota.SmokeTest/AuroraNullTests.cs
@@ -0,0 +1,211 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Egor Khindikaynen (Nota). See LICENSES/ for license terms.
+//
+// Aurora sound-preservation gate (specs/036-aurora-perf): every optimization step must
+// prove it did not change the sound. Ten factory presets cover all DSP blocks (both
+// oscillators, sub, all five warp modes, filter types/slopes, routing, matrix sources,
+// chorus voices, reverb modes, drive modes, mono). Each preset renders a fixed chord on
+// two fresh engines: the renders must null below −120 dB (determinism — catches
+// uninitialized state or order dependence introduced by hoisting).
+// Cross-build before/after proof uses dump/compare modes (raw float32, temp only):
+// dump on the base engine, compare on the feature engine, gate −120 dB (Tier-1) or
+// −50 dB (Tier-2). Also runnable alone: `--aurora-null`, `--aurora-null-dump <dir>`,
+// `--aurora-null-compare <dir> [gateDb]`.
+
+using Nota.Application;
+using Nota.Infrastructure;
+
+namespace Nota.SmokeTest;
+
+internal static class AuroraNullTests
+{
+ private const int Sr = 48000;
+ private const int Aurora = 5;
+ private const double Tier1Db = -120.0;
+
+ // (preset name, param id/value pairs) — mirrors FactoryPresetCatalog aurora entries.
+ private static readonly (string Name, (string Id, float V)[] Params)[] Presets = new[]
+ {
+ ("Super Saw", new[] { ("table", 0f), ("position", 0.9f), ("osc2on", 1f), ("osc2table", 0f),
+ ("osc2position", 0.9f), ("osc2level", 0.8f), ("osc2detune", 0.62f), ("unison", 1f),
+ ("unidetune", 0.4f), ("unispread", 0.9f), ("cutoff", 0.8f), ("resonance", 0.14f),
+ ("fil1env", 0.55f), ("attack", 0f), ("decay", 0.4f), ("sustain", 0.85f), ("release", 0.28f),
+ ("fxdrive", 0.2f), ("fxchorus", 0.26f), ("fxreverb", 0.24f), ("gain", 0.72f) }),
+ ("Warm Pad", new[] { ("table", 0f), ("position", 0.30f), ("warp", 0.50f), ("unison", 0.333f),
+ ("unidetune", 0.26f), ("unispread", 0.55f), ("attack", 0.50f), ("decay", 0.40f),
+ ("sustain", 0.85f), ("release", 0.60f), ("cutoff", 0.50f), ("resonance", 0.10f),
+ ("fil1env", 0.60f), ("gain", 0.80f) }),
+ ("Sub Bass", new[] { ("table", 0f), ("position", 0.6f), ("osc1oct", 0.333f), ("sublevel", 0.85f),
+ ("suboct", 0.5f), ("cutoff", 0.42f), ("resonance", 0.2f), ("fil1env", 0.72f), ("fil1slope", 1f),
+ ("attack", 0f), ("decay", 0.3f), ("sustain", 0.6f), ("release", 0.18f), ("mono", 1f),
+ ("unison", 0f), ("gain", 0.85f) }),
+ ("Reese Bass", new[] { ("table", 0f), ("position", 0.8f), ("osc1oct", 0.333f), ("osc2on", 1f),
+ ("osc2table", 0f), ("osc2position", 0.8f), ("osc2level", 0.85f), ("osc2oct", 0.333f),
+ ("osc2detune", 0.62f), ("unison", 0.333f), ("unidetune", 0.22f), ("unispread", 0.4f),
+ ("cutoff", 0.34f), ("resonance", 0.26f), ("fil1slope", 1f), ("fil1env", 0.64f),
+ ("attack", 0f), ("decay", 0.32f), ("sustain", 0.7f), ("release", 0.16f), ("mono", 1f),
+ ("fxdrive", 0.24f), ("fxdrivemode", 0.5f), ("gain", 0.82f) }),
+ ("Acid Table", new[] { ("table", 0.333f), ("position", 0.46f), ("osc1oct", 0.333f),
+ ("osc1warpmode", 0.75f), ("warp", 0.4f), ("cutoff", 0.30f), ("resonance", 0.72f),
+ ("fil1slope", 1f), ("fil1env", 0.9f), ("env2attack", 0f), ("env2decay", 0.26f),
+ ("env2sustain", 0.04f), ("env2release", 0.16f), ("attack", 0f), ("decay", 0.3f),
+ ("sustain", 0.45f), ("release", 0.14f), ("mono", 1f), ("mtx4_3", 0.7f),
+ ("fxdrive", 0.32f), ("gain", 0.84f) }),
+ ("Wobble Wave", new[] { ("table", 0.333f), ("position", 0.55f), ("osc1oct", 0.333f),
+ ("sublevel", 0.5f), ("suboct", 0.5f), ("cutoff", 0.34f), ("resonance", 0.44f),
+ ("fil1slope", 1f), ("lfo1sync", 0.5714f), ("lfo1shape", 0f), ("lfo1depth", 0.85f),
+ ("mtx2_3", 0.92f), ("attack", 0f), ("decay", 0.3f), ("sustain", 0.62f), ("release", 0.16f),
+ ("mono", 1f), ("fxdrive", 0.3f), ("gain", 0.84f) }),
+ ("Fold Lead", new[] { ("table", 0.333f), ("position", 0.5f), ("osc1warpmode", 1f),
+ ("warp", 0.6f), ("cutoff", 0.82f), ("resonance", 0.22f), ("fil1env", 0.6f),
+ ("attack", 0.01f), ("decay", 0.3f), ("sustain", 0.7f), ("release", 0.22f),
+ ("lfo1depth", 0.6f), ("mtx2_3", 0.68f), ("mtx6_0", 0.54f), ("fxdrive", 0.3f),
+ ("fxdrivemode", 1f), ("bendrange", 4f / 11f), ("gain", 0.72f) }),
+ ("Glass Choir", new[] { ("table", 0.667f), ("position", 0.55f), ("osc2on", 1f),
+ ("osc2table", 0f), ("osc2level", 0.55f), ("osc2oct", 0.667f), ("osc2detune", 0.56f),
+ ("unison", 0.333f), ("unidetune", 0.34f), ("unispread", 0.7f), ("cutoff", 0.72f),
+ ("resonance", 0.12f), ("fil1env", 0.62f), ("attack", 0.35f), ("decay", 0.5f),
+ ("sustain", 0.8f), ("release", 0.6f), ("env2attack", 0.4f), ("env2sustain", 0.6f),
+ ("mtx1_2", 0.78f), ("fxchorus", 0.4f), ("fxchorusvoices", 1f), ("fxreverb", 0.4f),
+ ("fxreverbmode", 0.5f), ("gain", 0.78f) }),
+ ("Aurora Sweep", new[] { ("table", 1f), ("position", 0.1f), ("osc1warpmode", 0.25f),
+ ("warp", 0.55f), ("unison", 0.5f), ("unidetune", 0.3f), ("unispread", 0.75f),
+ ("attack", 0.3f), ("decay", 0.55f), ("sustain", 0.8f), ("release", 0.7f),
+ ("env2attack", 0.7f), ("env2decay", 0.7f), ("env2sustain", 0.9f), ("env2release", 0.8f),
+ ("cutoff", 0.5f), ("resonance", 0.2f), ("fil1env", 0.72f), ("mtx1_2", 0.92f),
+ ("fxchorus", 0.3f), ("fxreverb", 0.5f), ("fxreverbmode", 0.5f), ("mac0val", 1f),
+ ("mac0dest", 4f / 11f), ("mac0amt", 0.9f), ("gain", 0.74f) }),
+ ("Formant Pad", new[] { ("table", 0.667f), ("position", 0.42f), ("osc1warpmode", 0.5f),
+ ("warp", 0.62f), ("unison", 0.667f), ("unidetune", 0.22f), ("unispread", 0.8f),
+ ("attack", 0.46f), ("decay", 0.5f), ("sustain", 0.82f), ("release", 0.7f),
+ ("cutoff", 0.58f), ("resonance", 0.24f), ("fil1type", 1f), ("fil1env", 0.56f),
+ ("lfo1rate", 0.16f), ("lfo1depth", 0.5f), ("mtx2_2", 0.70f), ("fxreverb", 0.46f),
+ ("fxreverbmode", 0.5f), ("fxreverbsize", 0.8f), ("gain", 0.76f) }),
+ };
+
+ public static IEnumerable<(bool ok, string label)> Run()
+ {
+ foreach (var p in Presets)
+ {
+ var a = RenderPreset(p);
+ var b = RenderPreset(p);
+ if (a.Length == 0 || b.Length == 0)
+ {
+ yield return (false, $"aurora null: {p.Name} failed to render (unknown param id?)");
+ continue;
+ }
+ double res = ResidualDb(a, b);
+ double peak = Peak(a);
+ bool finite = AllFinite(a) && AllFinite(b);
+ yield return (finite && peak > 0.02 && res < Tier1Db,
+ $"aurora null: {p.Name} renders deterministically (residual {res:0} dBFS, peak {peak:0.000})");
+ }
+ }
+
+ // Dump one raw-float32 render per preset (temp comparison artifact, not committed).
+ public static int Dump(string dir)
+ {
+ Directory.CreateDirectory(dir);
+ foreach (var p in Presets)
+ {
+ var buf = RenderPreset(p);
+ if (buf.Length == 0) { Console.WriteLine($"dump failed: {p.Name}"); return 1; }
+ var bytes = new byte[buf.Length * 4];
+ Buffer.BlockCopy(buf, 0, bytes, 0, bytes.Length);
+ File.WriteAllBytes(Path.Combine(dir, Sanitize(p.Name) + ".f32"), bytes);
+ }
+ return 0;
+ }
+
+ // Null current renders against a Dump dir. Gate defaults to Tier-1 (−120 dB).
+ public static IEnumerable<(bool ok, string label)> Compare(string dir, double gateDb = Tier1Db)
+ {
+ foreach (var p in Presets)
+ {
+ string path = Path.Combine(dir, Sanitize(p.Name) + ".f32");
+ if (!File.Exists(path))
+ {
+ yield return (false, $"aurora null: {p.Name} has no reference render in {dir}");
+ continue;
+ }
+ var raw = File.ReadAllBytes(path);
+ var reference = new float[raw.Length / 4];
+ Buffer.BlockCopy(raw, 0, reference, 0, raw.Length);
+ var now = RenderPreset(p);
+ if (now.Length == 0 || now.Length != reference.Length)
+ {
+ yield return (false, $"aurora null: {p.Name} render failed or changed length");
+ continue;
+ }
+ double res = ResidualDb(now, reference);
+ yield return (res < gateDb,
+ $"aurora null: {p.Name} matches reference (residual {res:0} dBFS vs gate {gateDb:0} dB)");
+ }
+ }
+
+ private static string Sanitize(string name)
+ => string.Concat(name.Select(c => char.IsLetterOrDigit(c) ? c : '_'));
+
+ private static int Pi(NotaEngine e, int t, string id)
+ {
+ int n = e.PluginParamCount(t, -1);
+ for (int i = 0; i < n; i++) if (e.PluginParamId(t, -1, i) == id) return i;
+ return -1;
+ }
+
+ // A fixed 4-note chord on a fresh engine: fresh state each call is what makes the
+ // double render a determinism proof. Empty array = unknown param id (preset drift).
+ private static float[] RenderPreset((string Name, (string Id, float V)[] Params) p)
+ {
+ using var eng = new NotaEngine();
+ eng.SetBpm(120);
+ int t = eng.AddInstrumentTrack();
+ eng.SetTrackBuiltinInstrument(t, Aurora);
+ foreach (var (id, v) in p.Params)
+ {
+ int idx = Pi(eng, t, id);
+ if (idx < 0) return Array.Empty<float>();
+ eng.PluginParamSet(t, -1, idx, v);
+ }
+ int clip = eng.AddMidiClip(t, 0, 4);
+ eng.SetClipNotes(t, clip, new[]
+ {
+ new NotaNote(48, 0, 4, 0.8f), new NotaNote(55, 0, 4, 0.75f),
+ new NotaNote(60, 0, 4, 0.7f), new NotaNote(64, 0, 4, 0.7f),
+ });
+ const int frames = (int)(2.5 * Sr), block = 512;
+ var buf = new float[frames * 2];
+ var chunk = new float[block * 2];
+ eng.Seek(0);
+ eng.Play();
+ for (int done = 0; done < frames;)
+ {
+ int m = Math.Min(block, frames - done);
+ eng.RenderOffline(chunk, m, Sr);
+ Array.Copy(chunk, 0, buf, done * 2, m * 2);
+ done += m;
+ }
+ eng.StopTransport();
+ return buf;
+ }
+
+ private static double ResidualDb(float[] a, float[] b)
+ {
+ double worst = 0;
+ for (int i = 0; i < a.Length; i++) worst = Math.Max(worst, Math.Abs(a[i] - b[i]));
+ return 20 * Math.Log10(Math.Max(worst, 1e-12));
+ }
+
+ private static double Peak(float[] buf)
+ {
+ double peak = 0;
+ foreach (float v in buf) peak = Math.Max(peak, Math.Abs(v));
+ return peak;
+ }
+
+ private static bool AllFinite(float[] buf)
+ {
+ foreach (float v in buf) if (!float.IsFinite(v)) return false;
+ return true;
+ }
+}
diff --git a/tests/Nota.SmokeTest/Program.cs b/tests/Nota.SmokeTest/Program.cs
index 925ecf38..030d76b8 100644
--- a/tests/Nota.SmokeTest/Program.cs
+++ b/tests/Nota.SmokeTest/Program.cs
@@ -385,6 +385,29 @@ if (args.Length >= 1 && args[0] == "--panlaw")
Console.WriteLine(failures == 0 ? "PANLAW PASSED" : $"PANLAW FAILED ({failures})");
return failures == 0 ? 0 : 1;
}
+// The Aurora sound gate alone: `--aurora-null`. Also part of the full run.
+if (args.Length >= 1 && args[0] == "--aurora-null")
+{
+ Console.WriteLine("-- aurora null --");
+ foreach (var (ok, label) in AuroraNullTests.Run()) Check(ok, label);
+ Console.WriteLine(failures == 0 ? "AURORA-NULL PASSED" : $"AURORA-NULL FAILED ({failures})");
+ return failures == 0 ? 0 : 1;
+}
+// Dump Aurora reference renders: `--aurora-null-dump <dir>`.
+if (args.Length >= 2 && args[0] == "--aurora-null-dump")
+{
+ Console.WriteLine("-- aurora null dump --");
+ return AuroraNullTests.Dump(args[1]);
+}
+// Null current renders against a dump: `--aurora-null-compare <dir> [gateDb]`.
+if (args.Length >= 2 && args[0] == "--aurora-null-compare")
+{
+ double gate = args.Length >= 3 && double.TryParse(args[2], out var g) ? g : -120.0;
+ Console.WriteLine("-- aurora null compare --");
+ foreach (var (ok, label) in AuroraNullTests.Compare(args[1], gate)) Check(ok, label);
+ Console.WriteLine(failures == 0 ? "AURORA-COMPARE PASSED" : $"AURORA-COMPARE FAILED ({failures})");
+ return failures == 0 ? 0 : 1;
+}
// What Nota Mosaic makes of a real library: `--mosaic-dump <file.sfz | folder>`.
if (args.Length >= 2 && args[0] == "--mosaic-dump")
{
@@ -15004,6 +15027,9 @@ foreach (var (ok, label) in ReturnDeleteTests.Run()) Check(ok, label);
Console.WriteLine("-- pan law --");
foreach (var (ok, label) in PanLawTests.Run()) Check(ok, label);
+Console.WriteLine("-- aurora null --");
+foreach (var (ok, label) in AuroraNullTests.Run()) Check(ok, label);
+
Console.WriteLine("-- device fold --");
foreach (var (ok, label) in DeviceFoldTests.Run()) Check(ok, label);
diff --git a/tests/perf/nota_perf.cpp b/tests/perf/nota_perf.cpp
index d5212431..76959e0f 100644
--- a/tests/perf/nota_perf.cpp
+++ b/tests/perf/nota_perf.cpp
@@ -58,6 +58,38 @@ int instrumentTrack(NotaEngine* e, int kind) {
return t;
}
+// Super Saw factory preset (specs/036-aurora-perf/supersaw-params.md), applied by
+// param id so preset edits stay in sync without hardcoded indices.
+void applySuperSaw(NotaEngine* e, int track) {
+ static const char* const ids[] = {"table", "position", "osc2on", "osc2table", "osc2position", "osc2level",
+ "osc2detune", "unison", "unidetune", "unispread", "cutoff", "resonance", "fil1env", "attack", "decay",
+ "sustain", "release", "fxdrive", "fxchorus", "fxreverb", "gain"};
+ static const float values[] = {0, 0.9f, 1, 0, 0.9f, 0.8f, 0.62f, 1, 0.4f, 0.9f, 0.8f, 0.14f, 0.55f, 0, 0.4f,
+ 0.85f, 0.28f, 0.2f, 0.26f, 0.24f, 0.72f};
+ const int n = nota_plugin_param_count(e, track, -1);
+ for (size_t p = 0; p < sizeof ids / sizeof ids[0]; ++p)
+ for (int i = 0; i < n; ++i) {
+ const char* pid = nota_plugin_param_id(e, track, -1, i);
+ if (pid && std::strcmp(pid, ids[p]) == 0) {
+ nota_plugin_param_set(e, track, -1, i, values[p]);
+ break;
+ }
+ }
+}
+
+// A 4-bar loop of 6-note chords: the reference load for aurora-supersaw-2x.
+void fillChords6(NotaEngine* e, int track, int transpose, double startBeat, double lengthBeats) {
+ const int clip = nota_track_add_midi_clip(e, track, startBeat, lengthBeats);
+ static const int chords[4][6] = {
+ {48, 55, 60, 64, 67, 72}, {45, 52, 57, 60, 64, 69}, {41, 48, 53, 57, 60, 65}, {43, 50, 55, 59, 62, 67}};
+ std::vector<NotaNoteData> notes;
+ for (int bar = 0; bar < (int)(lengthBeats / 4); ++bar) {
+ const int* c = chords[bar % 4];
+ for (int k = 0; k < 6; ++k) notes.push_back({c[k] + transpose, bar * 4.0, 4.0, 0.7f, 0});
+ }
+ nota_clip_set_notes(e, track, clip, notes.data(), (int)notes.size());
+}
+
// Display names for the report; the scenario id (the kind number) is what is compared.
std::string instrumentName(int kind) {
switch (kind) {
@@ -112,6 +144,7 @@ std::vector<Scenario> scenarios() {
s.push_back({id, instrumentName(k) + ", one track"});
}
s.push_back({"effect-base", "Synth alone (effect baseline)"});
+ s.push_back({"aurora-supersaw-2x", "Aurora Super Saw x2"});
for (int k = 0; k < kMaxKind; ++k) {
const std::string name = effectName(k);
if (name.empty()) continue;
@@ -142,6 +175,15 @@ bool build(NotaEngine* e, const std::string& id) {
if (nota_track_add_builtin_device(e, t, kind) < 0) return false;
return true;
}
+ if (id == "aurora-supersaw-2x") {
+ for (int t = 0; t < 2; ++t) {
+ const int tr = instrumentTrack(e, 5);
+ if (tr < 0) return false;
+ applySuperSaw(e, tr);
+ fillChords6(e, tr, t == 0 ? 0 : 7, 0, 16);
+ }
+ return true;
+ }
int n = 0;
if (std::sscanf(id.c_str(), "mix-%d", &n) == 1) {
// The stress-test chain on each track: Volt + EQ-8 + Compressor + Auto Filter.