Skip to content

armgit / nota

Public Imported from GitHub
0

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

(ci) Performance gate for engine changes (#227)

Chris Laupama779d65fad0f8
diff --git a/.github/workflows/perf.yml b/.github/workflows/perf.yml
new file mode 100644
index 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.md
index 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 project
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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 is
longer than the room left after it: copies continue into the next open clip of the track,
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 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.md
index 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 + arm64
across macOS, Windows and Linux) on a `vX.Y.Z` release tag, and drafts the GitHub release
with 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.py
new file mode 100755
index 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.sh
new file mode 100755
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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 summary
diff --git a/tests/perf/CMakeLists.txt b/tests/perf/CMakeLists.txt
new file mode 100644
index 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.cpp
new file mode 100644
index 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.cpp
new file mode 100644
index 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;
+}