Nota — a free DAW for macOS, Windows and Linux. No subscription, no account — just open it and make music.
C# audioaudio-unitavaloniacpp20cross-platformdawdigital-audio-workstationdspjucelinux-audiomcp-servermidimusicmusic-productionpiano-rollplugin-hostsequencersynthesizervstvst3
(fix) Aurora CPU optimization: dropout-free heavy presets, identical sound (#254)
rafi6122304e1ad5fd8
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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 getexactly their own channels; VST3 plug-ins keep the extra headroom that stops them crashingwhen 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-19diff --git a/specs/036-aurora-perf/baseline-env.md b/specs/036-aurora-perf/baseline-env.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.cppindex 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; // ± centsconst 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 / 4const 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& outLreturn;}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.hindex 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.csnew file mode 100644index 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.csindex 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.cppindex 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.