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
(ci) Performance gate for engine changes (#227)
Chris Laupama779d65fad0f8
diff --git a/.github/workflows/perf.yml b/.github/workflows/perf.ymlnew file mode 100644index 00000000..97e4801d--- /dev/null+++ b/.github/workflows/perf.yml@@ -0,0 +1,137 @@+name: Performance++# Engine performance regression gate (specs/034-engine-perf-gate). For every pull+# request that touches the engine:+# - Work: builds the engine at the PR's base and with the PR applied, renders the+# same scenarios with both under Valgrind and fails if any scenario does more+# than 1% more CPU instructions than the base (scripts/perf-gate.sh). Instruction+# counts repeat exactly between runs, so the limit can be tight without flaky runs.+# Wall time is checked too (base and PR back to back, >15% and re-confirmed with+# more rounds) for slowdowns that add no instructions.+# - Idle CPU: an engine left idle must use (almost) no CPU, on all three OSes.+# A regression a maintainer has decided to accept is approved by adding the+# `perf-regression-accepted` label to the PR: the report still lists it.+#+# Runs on `pull_request`, never `pull_request_target` (see ci.yml).++on:+ pull_request:+ branches: [develop, main]+ types: [opened, synchronize, reopened, labeled, unlabeled]+ paths:+ - 'src/native/**'+ - 'tests/perf/**'+ - 'scripts/perf-gate.*'+ - '.github/workflows/perf.yml'+ workflow_dispatch:+ inputs:+ base:+ description: 'Base ref to compare against'+ default: 'develop'++permissions:+ contents: read++concurrency:+ group: perf-${{ github.event.pull_request.number || github.ref }}+ cancel-in-progress: true++env:+ CPM_SOURCE_CACHE: ${{ github.workspace }}/.cpm-cache++jobs:+ work:+ name: Engine work (instructions)+ runs-on: ubuntu-latest+ timeout-minutes: 60+ steps:+ - uses: actions/checkout@v5+ with:+ fetch-depth: 0 # the base commit is built from a worktree+ - name: Install build deps+ run: |+ sudo apt-get update -qq+ sudo apt-get install -y --no-install-recommends \+ cmake ninja-build build-essential valgrind ccache \+ libasound2-dev libx11-dev libxext-dev libxrandr-dev libxinerama-dev \+ libxcursor-dev libfreetype6-dev libfontconfig1-dev+ - uses: actions/cache@v4+ with:+ path: |+ ~/.cache/ccache+ .cpm-cache+ key: perf-${{ runner.os }}-${{ github.sha }}+ restore-keys: perf-${{ runner.os }}-+ - name: Compare against the base+ env:+ PERF_ACCEPT: ${{ contains(github.event.pull_request.labels.*.name, 'perf-regression-accepted') && '1' || '' }}+ run: |+ base="${{ github.event.pull_request.base.sha }}"+ [ -n "$base" ] || base="origin/${{ inputs.base || 'develop' }}"+ bash scripts/perf-gate.sh "$base"+ - uses: actions/upload-artifact@v4+ if: always()+ with:+ name: perf-report+ path: |+ build/perf/report.md+ build/perf/results-*.tsv+ build/perf/*.log+ if-no-files-found: ignore++ idle:+ name: Idle CPU (${{ matrix.name }})+ runs-on: ${{ matrix.os }}+ timeout-minutes: 45+ strategy:+ fail-fast: false+ matrix:+ include:+ - { name: macOS, os: macos-26 }+ - { name: Windows, os: windows-2022 }+ - { name: Linux, os: ubuntu-latest }+ steps:+ - uses: actions/checkout@v5+ - uses: ilammy/msvc-dev-cmd@v1+ if: runner.os == 'Windows'+ with:+ arch: x64+ - name: Install build tools+ shell: bash+ run: |+ case "$RUNNER_OS" in+ macOS) brew install cmake ninja ;;+ Windows) choco install ninja --no-progress -y ;;+ Linux) sudo apt-get update -qq && sudo apt-get install -y --no-install-recommends \+ cmake ninja-build build-essential libasound2-dev libx11-dev libxext-dev \+ libxrandr-dev libxinerama-dev libxcursor-dev libfreetype6-dev libfontconfig1-dev ;;+ esac+ - uses: actions/cache@v4+ with:+ path: .cpm-cache+ key: perf-cpm-${{ runner.os }}-${{ hashFiles('src/native/nota.engine/CMakeLists.txt', 'src/native/nota.engine/cmake/**') }}+ - name: Build engine + tools+ shell: bash+ run: |+ cmake -G Ninja -S src/native/nota.engine -B build/engine -DCMAKE_BUILD_TYPE=Release+ cmake --build build/engine --target nota_engine+ cmake -G Ninja -S tests/perf -B build/perf-tools -DCMAKE_BUILD_TYPE=Release \+ -DNOTA_ENGINE_DIR="$PWD/src/native/nota.engine" -DNOTA_ENGINE_BUILD_DIR="$PWD/build/engine"+ cmake --build build/perf-tools --target nota_idle_cpu+ - name: Idle CPU check+ id: idle+ # TEMPORARY: develop's engine spins its thread-pool workers while idle (#223), so+ # this check fails on every PR until that is fixed. Until then it reports the+ # failure as a warning instead of failing the job. Remove `continue-on-error`+ # (and the warning step below) in the PR that fixes #223.+ continue-on-error: true+ shell: bash+ # Windows finds the engine DLL next to the tool or on PATH.+ run: PATH="$PWD/build/engine:$PATH" build/perf-tools/nota_idle_cpu 5 5+ - name: Report idle CPU failure (allowed until #223 is fixed)+ if: steps.idle.outcome == 'failure'+ shell: bash+ run: |+ msg="Idle engine CPU is over the 5% limit (known issue #223). Allowed to fail until #223 is fixed."+ echo "::warning title=Idle CPU (${{ matrix.name }})::$msg"+ echo "**Idle CPU (${{ matrix.name }})**: $msg" >> "$GITHUB_STEP_SUMMARY"diff --git a/BUILD.md b/BUILD.mdindex 7a15ff15..4b53cf3b 100644--- a/BUILD.md+++ b/BUILD.md@@ -44,6 +44,41 @@ and runs the smoke test.dotnet run --project src/managed/Nota.App```+## Performance gate++`scripts/perf-gate.sh` checks that an engine change does not make Nota slower. It builds+the engine at two commits, renders the same scenarios with both and compares the CPU+instructions each render does, counted by Valgrind across every engine thread:++- each built-in instrument on one track, and each built-in effect (its own share, eight+ instances on a Synth track) — new devices are picked up automatically;+- busy mixes of 1, 4, 8, 16 and 32 tracks (Volt + EQ-8 + Compressor + Auto Filter);+- a sparse session (32 tracks, one in four playing) and a silent one (32 tracks, no clips).++Instruction counts repeat exactly from run to run, unlike timings on shared CI machines,+so any scenario more than 1% above the base fails. Some slowdowns add no instructions+(denormals, cache misses, threads waiting on each other: EQ-8 in #212 ran 35% fewer+instructions yet took 38% longer), so wall-clock time is checked too. Base and change are+timed back to back over 5 rounds, and the fastest round of each is compared. A scenario+more than 15% slower is re-timed with 10 more rounds, and fails only if it is still+slower. A scenario that renders sound on the base but silence with the change fails too. `tests/perf/nota_idle_cpu` separately checks that an idle engine (created,+transport stopped) stays under 5% of one core; it runs on macOS, Windows and Linux. Until #223 (idle+worker threads spinning) is fixed, it reports a failure as a warning instead of failing CI.++Linux only (Valgrind), with the Linux build requirements plus `valgrind` (and `ccache`+to speed up the second build):++```bash+scripts/perf-gate.sh develop # your working tree against develop+scripts/perf-gate.sh 82babfe 64250a5 # any two commits+```++The report lands in `build/perf/report.md`. Knobs: `PERF_LIMIT_PCT` (default 1),+`PERF_TIME_LIMIT_PCT` (default 15), `PERF_ROUNDS` (5), `PERF_CONFIRM_ROUNDS` (10),+`PERF_SECONDS` (audio per scenario, default 1). The scenario harness is+`tests/perf/nota_perf.cpp`; it uses only the public C ABI and is always taken from the+newer commit, so both engines run the same scenarios.+## Stress test`scripts/stress-test.py` measures how much DSP headroom the engine has as a projectdiff --git a/CHANGELOG.md b/CHANGELOG.mdindex 558849e7..30b893cb 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -58,6 +58,15 @@ Entry categories: `Added`, `Changed`, `Fixed`, `Removed`.- **Settings → Updates** can turn the automatic checks off, and shows the last check with a**Check now** button. Nothing downloads until you click Update.+- **Performance gate for engine changes**: every pull request that touches the engine is+ compared with its base branch on the same machine. Each built-in instrument and effect,+ busy mixes of 1 to 32 tracks, and sparse and silent sessions are rendered with both, and+ the change fails if any of them does more than 1% more work (CPU instructions, counted by+ Valgrind, so the result does not depend on how busy the CI machine is) or takes more than+ 15% longer (timed back to back, re-checked before failing). An idle engine+ must also stay under 5% CPU on macOS, Windows and Linux. Run it locally with+ `scripts/perf-gate.sh develop` (Linux).+### Fixed- **⌘D in the piano roll no longer piles copies at the clip's end** when the selection islonger than the room left after it: copies continue into the next open clip of the track,diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 2d136dba..a8a24ffc 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -121,6 +121,13 @@ Every pull request is built on macOS, Windows and Linux, and the smoke test runs(`.github/workflows/ci.yml`). All three must pass before a pull request can be merged.If this is your first contribution, a maintainer approves the CI run before it starts.+A pull request that touches the engine also runs the performance gate+(`.github/workflows/perf.yml`, see [BUILD.md](BUILD.md#performance-gate)). It fails when+any engine scenario does more than 1% more work (CPU instructions) or takes more than+15% longer than on the base branch, or when an idle engine uses CPU. If a slowdown is the price of a deliberate change (a better-sounding+default, say), say why in the PR; a maintainer accepts it by adding the+`perf-regression-accepted` label, and the report still lists it.+## Pull requests- Target `develop`.diff --git a/FEATURES.md b/FEATURES.mdindex cadfcf2a..e95092e2 100644--- a/FEATURES.md+++ b/FEATURES.md@@ -1206,6 +1206,9 @@ Coverage:- **Release CI**: a GitHub Actions workflow builds and packages every target (x64 + arm64across macOS, Windows and Linux) on a `vX.Y.Z` release tag, and drafts the GitHub releasewith the matching `CHANGELOG.md` section as its body.-- **Tests**: an engine smoke test after every build.+- **Tests**: an engine smoke test after every build, and a performance gate on engine+ pull requests: instruction counts (fails above 1%) and timing (above 15%) per scenario+ against the base branch, plus an idle-CPU check on all three OSes+ (`scripts/perf-gate.sh`).- **Third-party notices**: bundled/linked dependencies and their copyrights are recorded in[`LICENSES/THIRD-PARTY-NOTICES.md`](LICENSES/THIRD-PARTY-NOTICES.md).diff --git a/scripts/perf-gate.py b/scripts/perf-gate.pynew file mode 100755index 00000000..f973386e--- /dev/null+++ b/scripts/perf-gate.py@@ -0,0 +1,145 @@+#!/usr/bin/env python3+# SPDX-License-Identifier: AGPL-3.0-only+#+# Compares two perf-gate result sets (scripts/perf-gate.sh) and decides the gate.+# Work rows: id, label, instructions, peak. Timing rows: id, wall_ms_per_s (one per+# round; the fastest is used: noise only ever adds time). Effect scenarios are compared on the effect's own work:+# (scenario - Synth baseline) / copies, so a slower effect is not hidden behind the+# synth that feeds it. Timing compares whole scenarios, base and head medians.++import argparse+import os+import sys++EFFECT_COPIES = 8 # must match kEffectCopies in tests/perf/nota_perf.cpp+SILENT = 1e-6+TIME_FLOOR_MS = 0.25 # ignore timing changes smaller than this (ms per second of audio)+++def load(path):+ rows = {}+ with open(path) as f:+ for line in f:+ p = line.rstrip("\n").split("\t")+ if len(p) < 4:+ continue+ ok = p[1] != "error"+ rows[p[0]] = {"label": p[1], "instr": int(p[2]) if ok else 0, "peak": float(p[3]), "ok": ok}+ return rows+++def load_timing(path):+ runs = {}+ if path:+ with open(path) as f:+ for line in f:+ p = line.split()+ if len(p) == 2:+ runs.setdefault(p[0], []).append(float(p[1]))+ return {k: min(v) for k, v in runs.items()}+++def work(rows, sid):+ """Instructions attributed to the scenario's subject."""+ r = rows[sid]+ if sid.startswith("effect-") and sid != "effect-base" and "effect-base" in rows:+ return (r["instr"] - rows["effect-base"]["instr"]) / EFFECT_COPIES+ return r["instr"]+++def main():+ ap = argparse.ArgumentParser()+ ap.add_argument("base")+ ap.add_argument("head")+ ap.add_argument("--limit", type=float, default=1.0, help="allowed growth in instructions, percent")+ ap.add_argument("--timing", nargs=2, metavar=("BASE", "HEAD"))+ ap.add_argument("--time-limit", type=float, default=15.0, help="allowed growth in median wall time, percent")+ ap.add_argument("--accept", action="store_true", help="regressions approved for this change")+ ap.add_argument("--base-label", default="base")+ ap.add_argument("--head-label", default="head")+ ap.add_argument("--markdown")+ ap.add_argument("--time-suspects", action="store_true",+ help="only print the ids whose timing is over the limit (for a confirmation pass)")+ a = ap.parse_args()++ base, head = load(a.base), load(a.head)+ tbase, thead = (load_timing(a.timing[0]), load_timing(a.timing[1])) if a.timing else ({}, {})+ if a.time_suspects:+ for sid in sorted(set(tbase) & set(thead)):+ tb, th = tbase[sid], thead[sid]+ if tb > 0 and (th - tb) / tb * 100 > a.time_limit and th - tb > TIME_FLOOR_MS:+ print(sid)+ return 0+ rows, failures = [], []+ for sid in sorted(set(base) | set(head)):+ label = (head.get(sid) or base.get(sid))["label"]+ if sid not in base:+ rows.append((sid, label, None, None, None, None, None, "new"))+ continue+ if sid not in head:+ rows.append((sid, label, None, None, None, None, None, "removed"))+ continue+ b, h = base[sid], head[sid]+ if not b["ok"] or not h["ok"]:+ verdict = "error" if not h["ok"] else "base error"+ rows.append((sid, label, None, None, None, tbase.get(sid), thead.get(sid), verdict))+ if not h["ok"]:+ failures.append(sid)+ continue+ wb, wh = work(base, sid), work(head, sid)+ pct = (wh - wb) / wb * 100 if wb > 0 else 0.0+ tb, th = tbase.get(sid), thead.get(sid)+ tpct = (th - tb) / tb * 100 if tb and th else 0.0+ verdict = "ok"+ if b["peak"] > SILENT and h["peak"] <= SILENT:+ verdict = "went silent"+ elif pct > a.limit and tpct > a.time_limit and th - tb > TIME_FLOOR_MS:+ verdict = "SLOWER (work + time)"+ elif pct > a.limit:+ verdict = "SLOWER (work)"+ elif tpct > a.time_limit and th - tb > TIME_FLOOR_MS:+ verdict = f"SLOWER (time {tpct:+.0f}%)"+ if verdict != "ok":+ failures.append(sid)+ rows.append((sid, label, wb, wh, pct, tb, th, verdict))++ def order(r):+ bad = r[7] not in ("ok", "new", "removed", "base error")+ return (not bad, -(r[4] or 0))++ rows.sort(key=order)+ out = [f"## Engine performance: {a.base_label} → {a.head_label}", ""]+ if failures:+ state = "accepted for this change" if a.accept else "**FAIL**"+ out.append(f"{state}: {len(failures)} scenario(s) slower than the base: more than {a.limit:g}% more CPU "+ f"instructions, or more than {a.time_limit:g}% more wall time (or now silent / erroring).")+ else:+ out.append(f"PASS: no scenario does more than {a.limit:g}% more work or takes more than "+ f"{a.time_limit:g}% longer than the base.")+ out += ["", "Work = CPU instructions per render, all engine threads (Valgrind, deterministic; effects: the "+ "effect's own share). Wall = fastest of the interleaved rounds, ms to render 1 s of audio on this machine; a scenario over the time limit is re-timed with more rounds before it fails.", "",+ "| Scenario | | Work base | Work PR | Change | Wall base | Wall PR | Verdict |",+ "| --- | --- | ---: | ---: | ---: | ---: | ---: | --- |"]++ def num(v):+ return "" if v is None else f"{v / 1e6:,.2f} M"++ for sid, label, wb, wh, pct, tb, th, verdict in rows:+ change = "" if pct is None else f"{pct:+.2f}%"+ walls = ["" if t is None else f"{t:.2f} ms" for t in (tb, th)]+ out.append(f"| `{sid}` | {label} | {num(wb)} | {num(wh)} | {change} | {walls[0]} | {walls[1]} | {verdict} |")+ md = "\n".join(out) + "\n"++ print(md)+ if a.markdown:+ with open(a.markdown, "w") as f:+ f.write(md)+ summary = os.environ.get("GITHUB_STEP_SUMMARY")+ if summary:+ with open(summary, "a") as f:+ f.write(md)+ return 1 if failures and not a.accept else 0+++if __name__ == "__main__":+ sys.exit(main())diff --git a/scripts/perf-gate.sh b/scripts/perf-gate.shnew file mode 100755index 00000000..dca2a459--- /dev/null+++ b/scripts/perf-gate.sh@@ -0,0 +1,123 @@+#!/usr/bin/env bash+# SPDX-License-Identifier: AGPL-3.0-only+#+# Engine performance regression gate (specs/034-engine-perf-gate).+# Builds the engine at two commits and renders the same scenarios with each. Two checks:+# - work: CPU instructions per render (Valgrind Callgrind, all engine threads). They+# repeat exactly between runs, so any scenario more than PERF_LIMIT_PCT (default 1)+# percent above the base fails.+# - time: wall-clock render time, base and head interleaved over PERF_ROUNDS rounds,+# fastest round, re-timed with more rounds before failing. Catches what instruction counts cannot see (denormals, cache misses, thread+# hand-offs); timing is noisy on shared machines, so its limit is PERF_TIME_LIMIT_PCT+# (default 15).+#+# Usage: scripts/perf-gate.sh <base-ref> [head-ref]+# head-ref defaults to the working tree as it is.+# Env: PERF_LIMIT_PCT=1 allowed growth in instructions per scenario+# PERF_TIME_LIMIT_PCT=15 allowed growth in median wall time per scenario+# PERF_ROUNDS=5 interleaved timing rounds+# PERF_CONFIRM_ROUNDS=10 extra rounds for a scenario over the time limit+# PERF_SECONDS=1 audio rendered per scenario+# PERF_ACCEPT=1 report regressions but exit 0 (an approved regression)+# PERF_WORK=build/perf scratch dir (worktrees, builds, results)+# Needs: Linux, valgrind, cmake, ninja, python3 (+ the engine's own build deps).++set -euo pipefail+cd "$(dirname "$0")/.."+ROOT=$PWD++BASE_REF=${1:?usage: scripts/perf-gate.sh <base-ref> [head-ref]}+HEAD_REF=${2:-}+WORK=${PERF_WORK:-$ROOT/build/perf}+SECONDS_PER=${PERF_SECONDS:-1}+JOBS=$(getconf _NPROCESSORS_ONLN 2>/dev/null || echo 2)+mkdir -p "$WORK"++command -v valgrind >/dev/null || { echo "perf-gate: valgrind is required (Linux: apt install valgrind)"; exit 2; }++LAUNCHER=()+command -v ccache >/dev/null && LAUNCHER=(-DCMAKE_C_COMPILER_LAUNCHER=ccache -DCMAKE_CXX_COMPILER_LAUNCHER=ccache)++# Checks out <ref> into a detached worktree (or uses the working tree) and echoes its path.+checkout() {+ local side=$1 ref=$2 dir="$WORK/src-$1"+ if [ -z "$ref" ]; then echo "$ROOT"; return; fi+ git worktree remove --force "$dir" >/dev/null 2>&1 || rm -rf "$dir"+ git worktree add --detach "$dir" "$ref" >&2+ if [ -f "$dir/.gitmodules" ]; then (cd "$dir" && git submodule update --init --recursive --depth 1 >&2); fi+ echo "$dir"+}++build_side() {+ local side=$1 src=$2+ echo "==> [$side] engine at $(git -C "$src" rev-parse --short HEAD)"+ cmake -G Ninja -S "$src/src/native/nota.engine" -B "$WORK/engine-$side" \+ -DCMAKE_BUILD_TYPE=Release "${LAUNCHER[@]}" >"$WORK/configure-$side.log"+ cmake --build "$WORK/engine-$side" --target nota_engine >"$WORK/build-$side.log"+ # The harness always comes from the head checkout, so both sides run identical scenarios.+ cmake -G Ninja -S "$ROOT/tests/perf" -B "$WORK/tools-$side" -DCMAKE_BUILD_TYPE=Release \+ -DNOTA_ENGINE_DIR="$src/src/native/nota.engine" -DNOTA_ENGINE_BUILD_DIR="$WORK/engine-$side" \+ >"$WORK/tools-configure-$side.log"+ cmake --build "$WORK/tools-$side" >"$WORK/tools-build-$side.log"+}++# One scenario on one side under Callgrind: id, label, instructions, peak.+run_one() {+ local side=$1 id=$2 tool="$WORK/tools-$1/nota_perf" out="$WORK/cg/$1-$2"+ local instr+ valgrind --tool=callgrind --instr-atstart=no --cache-sim=no --callgrind-out-file="$out.cg" \+ "$tool" run "$id" "$SECONDS_PER" >"$out.vg.out" 2>"$out.vg.err" || { echo -e "$id\terror\t0\t0"; return; }+ instr=$(sed -n 's/.*Collected : \([0-9]*\).*/\1/p' "$out.vg.err" | tail -1)+ # nota_perf prints: id, label, wall_ms_per_s, peak+ awk -F'\t' -v n="${instr:-0}" 'BEGIN{OFS="\t"} {print $1, $2, n, $4}' "$out.vg.out"+}+export -f run_one+export WORK SECONDS_PER++BASE_SRC=$(checkout base "$BASE_REF")+HEAD_SRC=$(checkout head "$HEAD_REF")+build_side base "$BASE_SRC" || { echo "perf-gate: the BASE engine failed to build; cannot compare (see $WORK/build-base.log)"; exit 2; }+build_side head "$HEAD_SRC"++mkdir -p "$WORK/cg"+"$WORK/tools-head/nota_perf" list >"$WORK/scenarios-head.txt"+"$WORK/tools-base/nota_perf" list >"$WORK/scenarios-base.txt"++for side in base head; do+ echo "==> [$side] running $(wc -l <"$WORK/scenarios-$side.txt") scenarios on $JOBS cores"+ xargs -P "$JOBS" -I{} bash -c "run_one $side {}" <"$WORK/scenarios-$side.txt" | sort >"$WORK/results-$side.tsv"+done++# Timing: one scenario at a time (no contention), base and head back to back, each round.+: >"$WORK/timing-base.tsv"; : >"$WORK/timing-head.tsv"+ROUNDS=${PERF_ROUNDS:-5}+echo "==> timing $ROUNDS interleaved rounds"+for r in $(seq "$ROUNDS"); do+ while read -r id; do+ for side in base head; do+ grep -qx "$id" "$WORK/scenarios-$side.txt" || continue+ "$WORK/tools-$side/nota_perf" run "$id" "$SECONDS_PER" | cut -f1,3 >>"$WORK/timing-$side.tsv" || true+ done+ done <"$WORK/scenarios-head.txt"+done++# Confirmation: a scenario over the time limit gets PERF_CONFIRM_ROUNDS more rounds; the+# fastest of all rounds decides. Noise only adds time, so a real slowdown survives this.+SUSPECTS=$(python3 "$ROOT/scripts/perf-gate.py" "$WORK/results-base.tsv" "$WORK/results-head.tsv" \+ --timing "$WORK/timing-base.tsv" "$WORK/timing-head.tsv" --time-limit "${PERF_TIME_LIMIT_PCT:-15}" --time-suspects)+if [ -n "$SUSPECTS" ]; then+ echo "==> re-timing $(wc -w <<<"$SUSPECTS") scenario(s) over the time limit"+ for r in $(seq "${PERF_CONFIRM_ROUNDS:-10}"); do+ for id in $SUSPECTS; do+ for side in base head; do+ "$WORK/tools-$side/nota_perf" run "$id" "$SECONDS_PER" | cut -f1,3 >>"$WORK/timing-$side.tsv" || true+ done+ done+ done+fi++python3 "$ROOT/scripts/perf-gate.py" "$WORK/results-base.tsv" "$WORK/results-head.tsv" \+ --timing "$WORK/timing-base.tsv" "$WORK/timing-head.tsv" --time-limit "${PERF_TIME_LIMIT_PCT:-15}" \+ --limit "${PERF_LIMIT_PCT:-1}" ${PERF_ACCEPT:+--accept} \+ --base-label "$(git -C "$BASE_SRC" rev-parse --short HEAD)" --head-label "$(git -C "$HEAD_SRC" rev-parse --short HEAD)" \+ --markdown "$WORK/report.md"diff --git a/specs/034-engine-perf-gate/plan.md b/specs/034-engine-perf-gate/plan.mdnew file mode 100644index 00000000..7631c479--- /dev/null+++ b/specs/034-engine-perf-gate/plan.md@@ -0,0 +1,46 @@+# Implementation Plan: Engine Performance Regression Gate++**Branch**: `perf/engine-regression-gate` | **Date**: 2026-10-20 | **Spec**: [spec.md](spec.md)++## Summary++Add a CI gate that fails an engine pull request when any render scenario does more work+than the base branch, or when an idle engine burns CPU. Work = CPU instructions counted+by Valgrind Callgrind across all engine threads, which repeat to ~0.001% between runs+(measured on #212: 4,655,546,929 vs 4,655,546,967), so a 1% limit is safe from noise.++## Technical Context++- **Harness**: `tests/perf/nota_perf.cpp`, C++20, public C ABI only (AR-7). Scenarios are+ discovered by probing built-in kinds 0..63, so new devices are covered automatically.+ The render loop is bracketed by `CALLGRIND_START/STOP_INSTRUMENTATION`, so engine+ setup does not dilute the count; outside Valgrind the macros are no-ops.+- **Idle check**: `tests/perf/nota_idle_cpu.cpp`, process CPU over 5 s of an idle engine+ (`getrusage` / `GetProcessTimes`); limit 5% of one core.+- **Driver**: `scripts/perf-gate.sh <base> [head]` builds both engines (worktree for a+ ref, ccache when present), builds the harness from the head checkout against each,+ runs every scenario under Callgrind and natively in parallel, then+ `scripts/perf-gate.py` compares and writes the Markdown report (and the GitHub step+ summary). Effect scenarios compare the effect's own share:+ (scenario − Synth baseline) / 8 instances.+- **CI**: `.github/workflows/perf.yml`. Job `work` (ubuntu, Valgrind) runs the driver+ against `pull_request.base.sha`; job `idle` runs the idle check on macOS, Windows and+ Linux. Path filter: engine sources, perf tools, workflow. The+ `perf-regression-accepted` label turns failures into a reported pass (FR-009).+- **Dependencies**: Valgrind and ccache are CI/developer tools, not linked or shipped.++## Constitution Check++- I Real-time safety: no engine code changes.+- II Boundary discipline: harness uses only `nota_engine.h`.+- III Licensing: new files carry the SPDX header; no new linked dependency.+- IV Verification gate: adds a gate, weakens none.+- VIII Safety rules never weakened: the acceptance label is visible on the PR and in the+ report; the gate is never skipped silently.++## Rollout++The idle check fails on develop until #223 is fixed (an idle engine is at ~(cores−1)×100%+CPU today). The `Performance` workflow is a separate check, not one of the three required+CI checks, so it does not block merges until a maintainer marks it required in the branch+ruleset. That should happen once #223 is fixed and the gate is green on develop.diff --git a/specs/034-engine-perf-gate/spec.md b/specs/034-engine-perf-gate/spec.mdnew file mode 100644index 00000000..360dab3a--- /dev/null+++ b/specs/034-engine-perf-gate/spec.md@@ -0,0 +1,195 @@+# Feature Specification: Engine Performance Regression Gate++**Feature Branch**: `perf/engine-regression-gate`++**Created**: 2026-10-20++**Status**: Draft++**Input**: User description: "Write tests to ensure that any engine changes don't hinder performance at all. Any form of regression should be a fail." Context: benchmarking #212 (engine rebuild) found two regressions that CI did not catch — an idle engine keeping every core but one at 100% (#223) and EQ-8 / Prism / Auto Filter rendering 1.7–2.9× slower (#224).++## Nota Context *(fill in — drives plan and tasks)*++**Feature area** *(pick the main one)*:++- [ ] 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+- [x] 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 - A slower engine change fails its pull request (Priority: P1)++A contributor opens a pull request that changes engine code. CI renders a fixed set of+engine scenarios with the PR's engine and with the engine of the PR's base, measures+how much work each does, and fails the PR if any scenario does more work than the base+beyond a small tolerance. The failure names each slower scenario and by how much.++**Why this priority**: This is the request: no engine change may make Nota slower+without someone noticing. It would have caught #224 (EQ-8 2.9× slower) before merge.++**Independent Test**: Push a branch that adds a deliberate busy loop to one effect's+processing. The gate fails and names that effect's scenario. Revert it, and the gate+passes.++**Acceptance Scenarios**:++1. **Given** a PR that makes EQ-8 do 2× the work per block, **When** CI runs, **Then**+ the performance check fails and its summary lists the EQ-8 scenario with its+ before, after and % change.+2. **Given** a PR that changes only C# or docs, **When** CI runs, **Then** the+ performance check passes (or is skipped) without building a second engine.+3. **Given** a PR that makes rendering faster, **When** CI runs, **Then** the check+ passes and the summary shows the improvement.++---++### User Story 2 - An idle engine that burns CPU fails on every OS (Priority: P1)++CI creates an engine, leaves it idle (transport stopped, nothing rendering) and+measures process CPU over a few seconds on macOS, Windows and Linux. Above a small+absolute limit, the check fails.++**Why this priority**: #223 (idle engine at 892% CPU on an M4) is the costliest+regression found so far: hot machines and drained batteries for every user. It is an+absolute property, so it needs no comparison against the base.++**Independent Test**: On current develop (with #223 unfixed) the check fails with a+clear message; with #223 fixed it passes.++**Acceptance Scenarios**:++1. **Given** an engine whose worker threads spin while idle, **When** the idle check+ runs, **Then** it fails and reports the measured CPU %.+2. **Given** an engine that parks its workers, **When** the idle check runs, **Then**+ it passes on all three OSes.++---++### User Story 3 - Contributors can see and reproduce the numbers (Priority: P2)++The check publishes a readable table in the CI run summary (scenario, base, PR,+change, verdict) and wall-clock timings for information. The same comparison runs+locally with one script so a contributor can reproduce a failure before pushing.++**Why this priority**: A gate nobody can read or reproduce gets disabled. The timings+also give marketing-grade speed numbers for each release.++**Independent Test**: Run the local script against two commits; it prints the same+table as CI.++**Acceptance Scenarios**:++1. **Given** a finished CI run, **When** a reviewer opens its summary, **Then** they see+ every scenario's work count and timing for base and PR.+2. **Given** a contributor's machine, **When** they run the local script with two+ commits, **Then** it builds both engines and prints the same comparison.++---++### Edge Cases++- A PR that intentionally makes a device heavier (for example, a new oversampling+ option on by default): the gate fails, and a maintainer can approve the regression+ explicitly in a visible, reviewable way (a label or a line in the PR), which the+ summary records. The gate is never silently disabled.+- A new device with no base counterpart: reported as "new", never a failure.+- A removed device: reported as "removed", never a failure.+- Base engine fails to build (broken base): the check reports that it could not compare+ and fails, rather than passing silently.+- Rendering output changes (not just speed): out of scope here; output correctness+ stays with the smoke test.+- Multi-threaded rendering: total work is counted across all threads, so moving work+ to more cores is neutral and spinning threads count as extra work.++## Requirements *(mandatory)*++### Functional Requirements++- **FR-001**: CI MUST compare the PR's engine against the engine built from the PR's+ base commit, in the same job, on the same machine, with the same build settings.+- **FR-002**: The comparison MUST use a measure of work that repeats within 0.5%+ between identical runs on CI (deterministic instruction counting), so that a small+ tolerance does not cause random failures.+- **FR-003**: A scenario MUST fail when its work exceeds the base by more than 1%.+ A failure of any scenario MUST fail the check.+- **FR-004**: The scenario set MUST cover each built-in instrument on one track, each+ built-in audio effect on one track, busy mixes of 1, 4, 8, 16 and 32 tracks, a+ sparse session (1 track in 4 playing) and a silent session (tracks, no clips).+- **FR-005**: Work MUST be counted across all engine threads, including thread-pool+ workers.+- **FR-006**: An idle-engine check MUST run on macOS, Windows and Linux and fail when+ an idle engine uses more than 5% of one core over 5 seconds.+- **FR-007**: Wall-clock timings MUST be measured for every scenario, base and PR+ interleaved over several rounds on the same machine. A scenario MUST fail when its+ fastest time grows by more than 15% (and by more than 0.25 ms per second of audio)+ and still does after a confirmation pass with more rounds.+ This catches slowdowns that do not add instructions (denormals, cache misses, thread+ hand-offs): measuring #212 showed EQ-8 running 2.9× slower on an M4 while executing+ 35% fewer instructions.+- **FR-008**: The check MUST write a summary table (scenario, base, PR, % change,+ verdict) to the CI run summary.+- **FR-009**: A maintainer MUST be able to accept a known regression on a specific PR+ through a visible, reviewable action; the summary MUST record that it was accepted.+- **FR-010**: The check MUST run only when engine sources, the engine build or the+ benchmark itself change.+- **FR-011**: A local script MUST reproduce the comparison between any two commits.+- **FR-012**: Each scenario MUST also check that its output is not silent where sound+ is expected, so a "faster" result from a broken render cannot pass.++### Key Entities++- **Scenario**: a named engine setup (tracks, devices, notes) rendered for a fixed+ length of audio. Has a work count and a wall time for base and PR.+- **Result table**: one row per scenario with base, PR, change and verdict.+- **Regression acceptance**: a maintainer's explicit approval of named regressions on+ one PR.++## Success Criteria *(mandatory)*++### Measurable Outcomes++- **SC-001**: Re-running the check on an unchanged commit gives the same verdict 20+ times out of 20 (no flaky failures).+- **SC-002**: A deliberate 2% slowdown in any single device fails the check.+- **SC-003**: Run against #212 (`82babfe` → `64250a5`), the check fails and names the+ EQ-8, Prism and Auto Filter scenarios, and the idle check fails.+- **SC-004**: The performance job adds no more than 25 minutes of CI time, and runs in+ parallel with the existing build jobs.+- **SC-005**: A contributor can reproduce a CI failure locally with one command.++## Assumptions++- Work is measured by counting executed CPU instructions on Linux (Valgrind+ Callgrind). Instruction counts are steady on shared CI runners, where timing swings+ 10–30%, so they can gate at 1%. They miss slowdowns that don't add instructions, which+ is why timing gates too, at a looser limit (FR-007). A slowdown smaller than 15% that+ adds no instructions can still slip through. That is the price of not failing PRs at+ random.+- Valgrind is a CI-only tool. It is not linked or shipped, so it adds no runtime+ dependency (CONTRIBUTING dependency policy).+- Instruction-count scenarios run on Linux only. The idle check runs on all three OSes.+- The benchmark program drives the engine only through the public C ABI+ (`nota_engine.h`, AR-7). It reuses the harness written for the #212 benchmarks.+- 1% and 5% are starting thresholds and can be tuned in one place.+- Until #223 and #224 are fixed, the gate fails on develop. It lands together with,+ or after, the #223 fix, so that develop stays green.++## Nota Compliance Checklist *(review before implementation; re-check in tasks.md)*++- [x] Every new source file will carry the AGPL-3.0-only SPDX header (two lines, see CONTRIBUTING.md)+- [x] No new dependency — or: license checked, AGPL-compatible, `LICENSES/third-party.md` row planned (Valgrind is a CI tool only, not linked or shipped)+- [x] 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) (no engine change)+- [x] Managed/native crossings go through the pure C ABI in `nota_engine.h` only (AR-7); no JUCE outside `pluginhost/`+- [x] Smoke-test impact assessed: engine behaviour change → extend `tests/Nota.SmokeTest` (no behaviour change; the idle check could also live in the smoke test)+- [ ] 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) (CI-only: FEATURES.md "platform/build/CI capability" entry)+- [x] UI change → follows `DESIGN.md` (Studio design language) (no UI)diff --git a/specs/034-engine-perf-gate/tasks.md b/specs/034-engine-perf-gate/tasks.mdnew file mode 100644index 00000000..3dc019df--- /dev/null+++ b/specs/034-engine-perf-gate/tasks.md@@ -0,0 +1,16 @@+# Tasks: Engine Performance Regression Gate++**Spec**: [spec.md](spec.md) | **Plan**: [plan.md](plan.md)++- [x] T001 Prototype: confirm Callgrind instruction counts repeat between runs with the thread pool (0.001%)+- [x] T002 [US1] `tests/perf/nota_perf.cpp`: scenario discovery (`list`) and `run <id>` with instrumentation bracketing+- [x] T003 [US2] `tests/perf/nota_idle_cpu.cpp`: idle-engine CPU check, macOS/Linux/Windows+- [x] T004 `tests/perf/CMakeLists.txt`: build both tools against any prebuilt engine+- [x] T005 [US1] `scripts/perf-gate.sh`: build base + head engines, run scenarios in parallel under Callgrind and natively+- [x] T006 [US1][US3] `scripts/perf-gate.py`: effect-share comparison, 1% limit, silence check, Markdown report + step summary, accept flag+- [x] T007 [US1][US2] `.github/workflows/perf.yml`: `work` job (Linux) + `idle` matrix (3 OSes), label acceptance+- [x] T008 [US3] Docs: BUILD.md "Performance gate", CONTRIBUTING.md CI note, CHANGELOG, FEATURES+- [x] T008b [US1] Timing check alongside instructions (EQ-8 in #212: −35% instructions, +38% time): interleaved rounds, fastest, confirmation pass+- [x] T009 Verify SC-003: `scripts/perf-gate.sh 82babfe 64250a5` fails on EQ-8, Prism, Auto Filter; idle check fails on 64250a5+- [x] T010 Verify SC-001: the same commit against itself passes, twice, with identical counts+- [ ] T011 Verify in CI: the workflow runs on the PR and posts its summarydiff --git a/tests/perf/CMakeLists.txt b/tests/perf/CMakeLists.txtnew file mode 100644index 00000000..f7c9c779--- /dev/null+++ b/tests/perf/CMakeLists.txt@@ -0,0 +1,32 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright (c) 2026 Egor Khindikaynen (Nota). See LICENSES/ for license terms.+#+# Engine performance gate tools (specs/034-engine-perf-gate). Built against an+# already-built engine, so the same sources can be compiled against the base and the+# PR engine:+# cmake -S tests/perf -B <out> -DNOTA_ENGINE_DIR=<repo>/src/native/nota.engine \+# -DNOTA_ENGINE_BUILD_DIR=<engine build dir>++cmake_minimum_required(VERSION 3.22)+project(nota_perf LANGUAGES CXX)++set(CMAKE_CXX_STANDARD 20)+set(CMAKE_CXX_STANDARD_REQUIRED ON)+if(NOT CMAKE_BUILD_TYPE)+ set(CMAKE_BUILD_TYPE Release)+endif()++set(NOTA_ENGINE_DIR "" CACHE PATH "Engine source dir (holds include/nota/nota_engine.h)")+set(NOTA_ENGINE_BUILD_DIR "" CACHE PATH "Engine build dir (holds the nota_engine library)")+if(NOT NOTA_ENGINE_DIR OR NOT NOTA_ENGINE_BUILD_DIR)+ message(FATAL_ERROR "Set NOTA_ENGINE_DIR and NOTA_ENGINE_BUILD_DIR")+endif()++find_library(NOTA_ENGINE_LIB nota_engine PATHS "${NOTA_ENGINE_BUILD_DIR}" NO_DEFAULT_PATH REQUIRED)++foreach(tool nota_perf nota_idle_cpu)+ add_executable(${tool} ${tool}.cpp)+ target_include_directories(${tool} PRIVATE "${NOTA_ENGINE_DIR}/include")+ target_link_libraries(${tool} PRIVATE "${NOTA_ENGINE_LIB}")+ set_target_properties(${tool} PROPERTIES BUILD_RPATH "${NOTA_ENGINE_BUILD_DIR}")+endforeach()diff --git a/tests/perf/nota_idle_cpu.cpp b/tests/perf/nota_idle_cpu.cppnew file mode 100644index 00000000..f4a236d5--- /dev/null+++ b/tests/perf/nota_idle_cpu.cpp@@ -0,0 +1,56 @@+// SPDX-License-Identifier: AGPL-3.0-only+// Copyright (c) 2026 Egor Khindikaynen (Nota). See LICENSES/ for license terms.+//+// Idle-engine CPU check for the CI regression gate (specs/034-engine-perf-gate).+// Creates an engine, leaves it idle (transport stopped, nothing rendering) and measures+// process CPU time over a few seconds. An idle engine must cost next to nothing: a+// worker pool that spins between jobs (#223) shows up here as whole cores.+//+// nota_idle_cpu [limit_percent_of_one_core=5] [seconds=5]+// exit 0 = within the limit, 1 = over it++#include "nota/nota_engine.h"++#include <chrono>+#include <cstdio>+#include <cstdlib>+#include <thread>++#ifdef _WIN32+#define WIN32_LEAN_AND_MEAN+#include <windows.h>+static double processCpuSeconds() {+ FILETIME created, exited, kernel, user;+ GetProcessTimes(GetCurrentProcess(), &created, &exited, &kernel, &user);+ auto secs = [](FILETIME f) { return (double)(((unsigned long long)f.dwHighDateTime << 32) | f.dwLowDateTime) * 1e-7; };+ return secs(kernel) + secs(user);+}+#else+#include <sys/resource.h>+static double processCpuSeconds() {+ rusage u{};+ getrusage(RUSAGE_SELF, &u);+ return u.ru_utime.tv_sec + u.ru_utime.tv_usec * 1e-6 + u.ru_stime.tv_sec + u.ru_stime.tv_usec * 1e-6;+}+#endif++int main(int argc, char** argv) {+ const double limit = argc > 1 ? std::atof(argv[1]) : 5.0;+ const double seconds = argc > 2 ? std::atof(argv[2]) : 5.0;++ NotaEngine* e = nota_engine_create();+ std::this_thread::sleep_for(std::chrono::seconds(1)); // let startup work settle++ const double c0 = processCpuSeconds();+ const auto t0 = std::chrono::steady_clock::now();+ std::this_thread::sleep_for(std::chrono::duration<double>(seconds));+ const double cpu = processCpuSeconds() - c0;+ const double wall = std::chrono::duration<double>(std::chrono::steady_clock::now() - t0).count();+ nota_engine_destroy(e);++ const double pct = 100.0 * cpu / wall;+ const bool ok = pct <= limit;+ std::printf("idle engine CPU: %.1f%% of one core over %.1f s (limit %.1f%%): %s\n", pct, wall, limit,+ ok ? "PASS" : "FAIL");+ return ok ? 0 : 1;+}diff --git a/tests/perf/nota_perf.cpp b/tests/perf/nota_perf.cppnew file mode 100644index 00000000..d5212431--- /dev/null+++ b/tests/perf/nota_perf.cpp@@ -0,0 +1,218 @@+// SPDX-License-Identifier: AGPL-3.0-only+// Copyright (c) 2026 Egor Khindikaynen (Nota). See LICENSES/ for license terms.+//+// Engine performance scenarios for the CI regression gate (specs/034-engine-perf-gate).+// Drives the engine through the public C ABI only: builds a session, plays it and+// renders offline. Under Valgrind Callgrind (started with --instr-atstart=no) only the+// measured render loop is instrumented, across every engine thread, so the instruction+// count is the render's work and nothing else. Outside Valgrind the client requests are+// no-ops and the wall time is the useful number.+//+// nota_perf list one scenario id per line+// nota_perf run <id> [seconds] prints: id <TAB> label <TAB> wall_ms_per_s <TAB> peak++#include "nota/nota_engine.h"++#include <algorithm>+#include <chrono>+#include <cmath>+#include <cstdio>+#include <cstdlib>+#include <cstring>+#include <string>+#include <vector>++#if defined(__has_include)+#if __has_include(<valgrind/callgrind.h>)+#include <valgrind/callgrind.h>+#endif+#endif+#ifndef CALLGRIND_START_INSTRUMENTATION+#define CALLGRIND_START_INSTRUMENTATION+#define CALLGRIND_STOP_INSTRUMENTATION+#endif++namespace {++constexpr double kSampleRate = 48000.0;+constexpr int kBlock = 512;+constexpr int kMaxKind = 64; // probe built-in kinds 0..63; new devices are picked up automatically+constexpr int kEffectCopies = 8; // instances per effect scenario, so the effect dominates the count++// A 4-bar loop of 4-note chords plus 8th-note stabs: realistic polyphony.+void fillClip(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][4] = {{48, 55, 60, 64}, {45, 52, 57, 60}, {41, 48, 53, 57}, {43, 50, 55, 59}};+ std::vector<NotaNoteData> notes;+ for (int bar = 0; bar < (int)(lengthBeats / 4); ++bar) {+ const int* c = chords[bar % 4];+ for (int k = 0; k < 4; ++k) notes.push_back({c[k] + transpose, bar * 4.0, 4.0, 0.7f, 0});+ for (int s = 0; s < 8; ++s) notes.push_back({c[s % 4] + 12 + transpose, bar * 4.0 + s * 0.5, 0.4, 0.8f, 0});+ }+ nota_clip_set_notes(e, track, clip, notes.data(), (int)notes.size());+}++int instrumentTrack(NotaEngine* e, int kind) {+ const int t = nota_engine_add_instrument_track(e);+ if (kind != 0 && nota_track_set_builtin_instrument(e, t, kind) != NOTA_OK) return -1;+ return t;+}++// Display names for the report; the scenario id (the kind number) is what is compared.+std::string instrumentName(int kind) {+ switch (kind) {+ case 0: return "Synth";+ case 1: return "Sampler (no sample)";+ case 2: return "Physical";+ case 5: return "Aurora";+ case 6: return "Volt";+ case 7: return "Bass";+ case 8: return "Pendulum";+ case 9: return "Operator";+ case 10: return "Grain";+ case 11: return "Flux";+ case 12: return "Rhythm Machine";+ case 13: return "Monolith";+ case 14: return "Pentad";+ case 15: return "Consort";+ case 16: return "Keys";+ case 17: return "Mosaic (no program)";+ default: return "Instrument kind " + std::to_string(kind);+ }+}++bool instrumentKindExists(int kind) {+ if (kind == 0) return true;+ NotaEngine* e = nota_engine_create();+ const int t = nota_engine_add_instrument_track(e);+ const bool ok = nota_track_set_builtin_instrument(e, t, kind) == NOTA_OK && nota_track_instrument_kind(e, t) == kind;+ nota_engine_destroy(e);+ return ok;+}++std::string effectName(int kind) {+ NotaEngine* e = nota_engine_create();+ const int t = nota_engine_add_instrument_track(e);+ const int idx = nota_track_add_builtin_device(e, t, kind);+ std::string name = idx >= 0 ? nota_device_name(e, t, idx) : "";+ nota_engine_destroy(e);+ return name;+}++struct Scenario {+ std::string id, label;+};++std::vector<Scenario> scenarios() {+ std::vector<Scenario> s;+ char id[64];+ for (int k = 0; k < kMaxKind; ++k)+ if (instrumentKindExists(k)) {+ std::snprintf(id, sizeof id, "instrument-%02d", k);+ s.push_back({id, instrumentName(k) + ", one track"});+ }+ s.push_back({"effect-base", "Synth alone (effect baseline)"});+ for (int k = 0; k < kMaxKind; ++k) {+ const std::string name = effectName(k);+ if (name.empty()) continue;+ std::snprintf(id, sizeof id, "effect-%02d", k);+ s.push_back({id, name + " x" + std::to_string(kEffectCopies) + " on Synth"});+ }+ for (int n : {1, 4, 8, 16, 32}) s.push_back({"mix-" + std::to_string(n), std::to_string(n) + " tracks, all playing"});+ s.push_back({"sparse-32", "32 tracks, 1 in 4 playing"});+ s.push_back({"silent-32", "32 tracks, no clips"});+ return s;+}++// Builds the scenario into a fresh engine. Returns false for an unknown id.+bool build(NotaEngine* e, const std::string& id) {+ nota_transport_set_bpm(e, 120);+ int kind = -1;+ if (std::sscanf(id.c_str(), "instrument-%d", &kind) == 1) {+ const int t = instrumentTrack(e, kind);+ if (t < 0) return false;+ fillClip(e, t, 0, 0, 16);+ return true;+ }+ if (id == "effect-base" || std::sscanf(id.c_str(), "effect-%d", &kind) == 1) {+ const int t = instrumentTrack(e, 0);+ fillClip(e, t, 0, 0, 16);+ if (id != "effect-base")+ for (int i = 0; i < kEffectCopies; ++i)+ if (nota_track_add_builtin_device(e, t, kind) < 0) return false;+ 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.+ for (int i = 0; i < n; ++i) {+ const int t = instrumentTrack(e, 6);+ fillClip(e, t, (i % 5) * 2 - 4, 0, 16);+ nota_track_add_builtin_device(e, t, 0);+ nota_track_add_builtin_device(e, t, 1);+ nota_track_add_builtin_device(e, t, 7);+ }+ return n > 0;+ }+ if (id == "sparse-32" || id == "silent-32") {+ for (int i = 0; i < 32; ++i) {+ const int t = instrumentTrack(e, 6);+ if (id == "sparse-32") fillClip(e, t, 0, (i % 4) * 4.0, 4); // one bar in four+ nota_track_add_builtin_device(e, t, 0);+ nota_track_add_builtin_device(e, t, 1);+ nota_track_add_builtin_device(e, t, 3);+ }+ return true;+ }+ return false;+}++int run(const std::string& id, double seconds) {+ std::string label = id;+ for (const auto& s : scenarios())+ if (s.id == id) label = s.label;++ NotaEngine* e = nota_engine_create();+ if (!build(e, id)) {+ std::fprintf(stderr, "nota_perf: unknown or unsupported scenario '%s'\n", id.c_str());+ nota_engine_destroy(e);+ return 2;+ }+ nota_transport_set_loop(e, 1, 0.0, 16.0);+ nota_transport_seek(e, 0.0);+ nota_transport_play(e);++ std::vector<float> buf((size_t)kBlock * 2);+ for (int i = 0; i < (int)(0.25 * kSampleRate / kBlock); ++i) // warm-up: voices, caches, pool threads+ nota_engine_render_offline_at(e, buf.data(), kBlock, kSampleRate);++ const int blocks = std::max(1, (int)(seconds * kSampleRate / kBlock));+ float peak = 0.0f;+ const auto t0 = std::chrono::steady_clock::now();+ CALLGRIND_START_INSTRUMENTATION;+ for (int i = 0; i < blocks; ++i) {+ nota_engine_render_offline_at(e, buf.data(), kBlock, kSampleRate);+ for (float v : buf) peak = std::max(peak, std::fabs(v));+ }+ CALLGRIND_STOP_INSTRUMENTATION;+ const auto t1 = std::chrono::steady_clock::now();++ nota_transport_stop(e);+ nota_engine_destroy(e);+ const double audio = blocks * (double)kBlock / kSampleRate;+ const double wallMs = std::chrono::duration<double, std::milli>(t1 - t0).count() / audio;+ std::printf("%s\t%s\t%.3f\t%.4f\n", id.c_str(), label.c_str(), wallMs, peak);+ return 0;+}++} // namespace++int main(int argc, char** argv) {+ if (argc >= 2 && std::strcmp(argv[1], "list") == 0) {+ for (const auto& s : scenarios()) std::printf("%s\n", s.id.c_str());+ return 0;+ }+ if (argc >= 3 && std::strcmp(argv[1], "run") == 0) return run(argv[2], argc >= 4 ? std::atof(argv[3]) : 1.0);+ std::fprintf(stderr, "usage: nota_perf list | nota_perf run <scenario> [seconds]\n");+ return 2;+}