Skip to content

armgit / nota

Public Imported from GitHub
0

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

(fix) Engine rebuild follow-ups: idle CPU, scratch use-after-free, pool ordering (#223) (#232)

Egor Khindikaynen791511645d05
diff --git a/.agents/skills/nota-pr/SKILL.md b/.agents/skills/nota-pr/SKILL.md
new file mode 100644
index 00000000..93bc0634
--- /dev/null
+++ b/.agents/skills/nota-pr/SKILL.md
@@ -0,0 +1,125 @@
+---
+name: nota-pr
+description: Open a Nota pull request the project's way — branch off develop, commit in the repo's style under the maintainer's identity, push over HTTPS, and write the description from the PR template. Evidence is part of the PR, attached through the pr-assets branch: a user-visible UI change carries before/after screenshots; a performance change (engine, DSP, threading, render path, CPU/memory) carries a before/after benchmark with charts. Use whenever the user asks to open, create or prepare a PR, or to "push this for review".
+user-invocable: true
+---
+
+# Opening a pull request
+
+A Nota PR is reviewed by reading its description, so the description carries the proof: what
+changed, why, and what it looks like or costs before and after. Images and benchmark charts
+never go into `develop` — they live on the orphan **`pr-assets`** branch (see
+`CONTRIBUTING.md` § Images for pull requests) and are embedded by raw URL.
+
+## 1. Branch and commit
+
+- Branch from `develop` (never `main`): `git checkout -b <type>/<slug>` — `fix/…`, `feat/…`,
+ `docs/…`, `chore/…`. If the work is already on `develop` uncommitted, create the branch
+ first; the working tree comes along.
+- `scripts/build.sh` (or `build-linux.sh` / `build-win.ps1`) must pass — it runs the smoke test.
+- Commit message: `(fix) Summary`, `(feat) …`, `(docs) …`, `(refactor) …`, `(style) …`; a body
+ that says what and why in plain words. **No AI attribution** (no `Co-Authored-By`, no
+ "Generated with" line) in commits or the PR body.
+- Author and committer: `Egor Khindikaynen <[email protected]>`:
+ `git -c user.name="Egor Khindikaynen" -c [email protected] commit …`
+ (and `--author` the same, if the local identity differs).
+- Spec and bug artifacts (`specs/<slug>/`, `.specify/bugs/<slug>/`) ship with the change they
+ describe. Never commit build dirs, `.cpm-cache/`, benchmark output or harness binaries.
+
+## 2. Decide what evidence the PR needs
+
+| The change… | Attach |
+|---|---|
+| alters anything the user sees (a window, panel, device card, menu, theme, layout, custom-drawn view) | **before / after screenshots**, same size, theme and content |
+| aims at or may affect performance (engine render path, DSP, threads, allocation, CPU, memory, startup) | **benchmark**: before vs after (and vs the last good build when fixing a regression), with charts + a table |
+| both | both |
+| neither (docs, refactor with no runtime effect, CI) | nothing — say so in the Summary |
+
+When unsure whether a change is user-visible, run the app and look.
+
+## 3. Screenshots (UI changes)
+
+1. Capture **before** on the base commit and **after** on the branch, with the same window size,
+ theme (default Studio Dark unless the change is theme-specific — then one pair per theme),
+ interface scale and project content. Reuse the capture tooling the `nota-design` /
+ `nota-docs` skills describe (headless Avalonia render or the app's own capture hook) rather
+ than hand screenshots, so both shots are pixel-comparable.
+2. Name them `<what>-before.png` / `<what>-after.png`; a side-by-side `<what>-both.png` is
+ welcome for small changes.
+
+## 4. Benchmarks (performance changes)
+
+Two layers, and a performance change needs both:
+
+- **Regression guards** — `tests/Nota.SmokeTest/RenderPoolTests.cs`, part of every smoke run
+ (`scripts/build.sh`, CI on all three platforms; alone: `dotnet run --project
+ tests/Nota.SmokeTest -c Release -- --perf`). Hardware-independent checks: render threads
+ idle at ~0 CPU (their own thread clocks), parallel vs single-thread CPU ratios while playing
+ and bouncing, bounce not slower than one thread, bit-identical output, tracks edited while
+ rendering. When you touch the render path, threading or allocation, keep these green; when
+ you fix a performance bug, add a guard here that fails on the old code (prove it: put the
+ old behaviour back briefly and watch the check fail).
+- **Benchmark numbers** for the PR description, below.
+
+The engine benchmark is in the repo:
+
+- `scripts/bench-engine.sh [-r runs] <out-dir> <label>=<engine-lib-dir> ...` — links
+ `scripts/bench/engine-bench.cpp` against each Release `libnota_engine` and runs idle, offline
+ render (bounce) and real-time-paced scenarios for audio and synth tracks, interleaving the
+ builds run by run. Writes `results.csv` + `machine.txt`.
+- `scripts/bench-chart.py <out-dir> <label>="Display name" ...` — medians, three charts
+ (`cpu-playing`, `bounce-time`, `bounce-cpu`; SVG + 2x PNG) and `summary.md` (tables + machine).
+
+Recipe:
+
+1. Build each revision you compare **in Release**, each in its own checkout so nothing is shared:
+ `git worktree add --detach /tmp/nota-<label> <commit>`, then configure + `ninja nota_engine` in
+ its `src/native/nota.engine/build`. Revisions before the CPM switch (#212) need
+ `git submodule update --init --recursive --depth 1` first. The branch itself can use the main
+ `build/` dir (it must stay Release).
+2. Copy each `libnota_engine.*` into its own folder (`/tmp/bench/libs/<label>/`) so later rebuilds
+ don't change what you measured.
+3. Run on a quiet machine, on power, ≥3 runs: `scripts/bench-engine.sh -r 3 /tmp/bench/out
+ before=… after=…`. Look at the spread in `results.csv`; rerun if runs disagree a lot.
+4. Chart it: `scripts/bench-chart.py /tmp/bench/out before="Before" after="This PR"`. Open the
+ PNGs and check them (labels, overlap) before attaching.
+5. Report honestly: put regressions in the table too and say why they're acceptable or what
+ follows up. A benchmark also needs the commits measured and the machine (from `machine.txt`).
+
+If the change needs a scenario the harness lacks, extend `engine-bench.cpp` (stick to C ABI
+functions every compared build exports) and the scenario list in `bench-engine.sh`, in the same PR.
+
+## 5. Put the assets on pr-assets
+
+One folder per PR, named after the change or issue (`fix-pr212-review/`, `issue-223/`). Commit on
+top of `pr-assets` — never force-push or rewrite it; old PRs link to its files.
+
+```sh
+git fetch origin pr-assets
+git worktree add /tmp/nota-assets origin/pr-assets -B pr-assets
+mkdir -p /tmp/nota-assets/<folder> && cp <pngs> <results.csv> <summary.md> /tmp/nota-assets/<folder>/
+git -C /tmp/nota-assets add <folder>
+git -C /tmp/nota-assets -c user.name="Egor Khindikaynen" -c [email protected] commit -m "Images for <change>"
+git -C /tmp/nota-assets -c credential.helper= -c credential.helper='!gh auth git-credential' \
+ push https://github.com/nota-daw/nota.git HEAD:pr-assets
+git worktree remove /tmp/nota-assets
+```
+
+For benchmarks commit the CSV and `summary.md` next to the charts, so the numbers stay checkable.
+Embed with `https://raw.githubusercontent.com/nota-daw/nota/pr-assets/<folder>/<file>.png`.
+
+## 6. Push and open the PR
+
+- Push over HTTPS (SSH push to nota-daw/nota is denied):
+ `git -c credential.helper= -c credential.helper='!gh auth git-credential' push -u https://github.com/nota-daw/nota.git <branch>`,
+ then `git fetch origin <branch> && git branch -u origin/<branch>`.
+- `gh pr create --repo nota-daw/nota --base develop --head <branch> --title "<commit-style title>" --body-file <file>`.
+- Body: follow `.github/PULL_REQUEST_TEMPLATE.md` (Summary, Spec, Checklist — tick only what was
+ actually done; leave platforms you didn't build unticked). Add sections as needed:
+ - **Screenshots** — a table, before | after:
+ `| Before | After |` / `|---|---|` / `| ![before](raw-url) | ![after](raw-url) |`
+ - **Benchmark** — the charts, the `summary.md` tables, the commits measured, the machine, and
+ a sentence on how to reproduce (`scripts/bench-engine.sh …`).
+ - **Testing** — what was run and what was not.
+ - Link the issue (`Fixes #N` / `Refs #N`) and, for review follow-ups, the PR being followed up.
+- Base is `develop`. Don't enable auto-merge; don't merge.
diff --git a/.claude/skills/nota-pr/SKILL.md b/.claude/skills/nota-pr/SKILL.md
new file mode 100644
index 00000000..93bc0634
--- /dev/null
+++ b/.claude/skills/nota-pr/SKILL.md
@@ -0,0 +1,125 @@
+---
+name: nota-pr
+description: Open a Nota pull request the project's way — branch off develop, commit in the repo's style under the maintainer's identity, push over HTTPS, and write the description from the PR template. Evidence is part of the PR, attached through the pr-assets branch: a user-visible UI change carries before/after screenshots; a performance change (engine, DSP, threading, render path, CPU/memory) carries a before/after benchmark with charts. Use whenever the user asks to open, create or prepare a PR, or to "push this for review".
+user-invocable: true
+---
+
+# Opening a pull request
+
+A Nota PR is reviewed by reading its description, so the description carries the proof: what
+changed, why, and what it looks like or costs before and after. Images and benchmark charts
+never go into `develop` — they live on the orphan **`pr-assets`** branch (see
+`CONTRIBUTING.md` § Images for pull requests) and are embedded by raw URL.
+
+## 1. Branch and commit
+
+- Branch from `develop` (never `main`): `git checkout -b <type>/<slug>` — `fix/…`, `feat/…`,
+ `docs/…`, `chore/…`. If the work is already on `develop` uncommitted, create the branch
+ first; the working tree comes along.
+- `scripts/build.sh` (or `build-linux.sh` / `build-win.ps1`) must pass — it runs the smoke test.
+- Commit message: `(fix) Summary`, `(feat) …`, `(docs) …`, `(refactor) …`, `(style) …`; a body
+ that says what and why in plain words. **No AI attribution** (no `Co-Authored-By`, no
+ "Generated with" line) in commits or the PR body.
+- Author and committer: `Egor Khindikaynen <[email protected]>`:
+ `git -c user.name="Egor Khindikaynen" -c [email protected] commit …`
+ (and `--author` the same, if the local identity differs).
+- Spec and bug artifacts (`specs/<slug>/`, `.specify/bugs/<slug>/`) ship with the change they
+ describe. Never commit build dirs, `.cpm-cache/`, benchmark output or harness binaries.
+
+## 2. Decide what evidence the PR needs
+
+| The change… | Attach |
+|---|---|
+| alters anything the user sees (a window, panel, device card, menu, theme, layout, custom-drawn view) | **before / after screenshots**, same size, theme and content |
+| aims at or may affect performance (engine render path, DSP, threads, allocation, CPU, memory, startup) | **benchmark**: before vs after (and vs the last good build when fixing a regression), with charts + a table |
+| both | both |
+| neither (docs, refactor with no runtime effect, CI) | nothing — say so in the Summary |
+
+When unsure whether a change is user-visible, run the app and look.
+
+## 3. Screenshots (UI changes)
+
+1. Capture **before** on the base commit and **after** on the branch, with the same window size,
+ theme (default Studio Dark unless the change is theme-specific — then one pair per theme),
+ interface scale and project content. Reuse the capture tooling the `nota-design` /
+ `nota-docs` skills describe (headless Avalonia render or the app's own capture hook) rather
+ than hand screenshots, so both shots are pixel-comparable.
+2. Name them `<what>-before.png` / `<what>-after.png`; a side-by-side `<what>-both.png` is
+ welcome for small changes.
+
+## 4. Benchmarks (performance changes)
+
+Two layers, and a performance change needs both:
+
+- **Regression guards** — `tests/Nota.SmokeTest/RenderPoolTests.cs`, part of every smoke run
+ (`scripts/build.sh`, CI on all three platforms; alone: `dotnet run --project
+ tests/Nota.SmokeTest -c Release -- --perf`). Hardware-independent checks: render threads
+ idle at ~0 CPU (their own thread clocks), parallel vs single-thread CPU ratios while playing
+ and bouncing, bounce not slower than one thread, bit-identical output, tracks edited while
+ rendering. When you touch the render path, threading or allocation, keep these green; when
+ you fix a performance bug, add a guard here that fails on the old code (prove it: put the
+ old behaviour back briefly and watch the check fail).
+- **Benchmark numbers** for the PR description, below.
+
+The engine benchmark is in the repo:
+
+- `scripts/bench-engine.sh [-r runs] <out-dir> <label>=<engine-lib-dir> ...` — links
+ `scripts/bench/engine-bench.cpp` against each Release `libnota_engine` and runs idle, offline
+ render (bounce) and real-time-paced scenarios for audio and synth tracks, interleaving the
+ builds run by run. Writes `results.csv` + `machine.txt`.
+- `scripts/bench-chart.py <out-dir> <label>="Display name" ...` — medians, three charts
+ (`cpu-playing`, `bounce-time`, `bounce-cpu`; SVG + 2x PNG) and `summary.md` (tables + machine).
+
+Recipe:
+
+1. Build each revision you compare **in Release**, each in its own checkout so nothing is shared:
+ `git worktree add --detach /tmp/nota-<label> <commit>`, then configure + `ninja nota_engine` in
+ its `src/native/nota.engine/build`. Revisions before the CPM switch (#212) need
+ `git submodule update --init --recursive --depth 1` first. The branch itself can use the main
+ `build/` dir (it must stay Release).
+2. Copy each `libnota_engine.*` into its own folder (`/tmp/bench/libs/<label>/`) so later rebuilds
+ don't change what you measured.
+3. Run on a quiet machine, on power, ≥3 runs: `scripts/bench-engine.sh -r 3 /tmp/bench/out
+ before=… after=…`. Look at the spread in `results.csv`; rerun if runs disagree a lot.
+4. Chart it: `scripts/bench-chart.py /tmp/bench/out before="Before" after="This PR"`. Open the
+ PNGs and check them (labels, overlap) before attaching.
+5. Report honestly: put regressions in the table too and say why they're acceptable or what
+ follows up. A benchmark also needs the commits measured and the machine (from `machine.txt`).
+
+If the change needs a scenario the harness lacks, extend `engine-bench.cpp` (stick to C ABI
+functions every compared build exports) and the scenario list in `bench-engine.sh`, in the same PR.
+
+## 5. Put the assets on pr-assets
+
+One folder per PR, named after the change or issue (`fix-pr212-review/`, `issue-223/`). Commit on
+top of `pr-assets` — never force-push or rewrite it; old PRs link to its files.
+
+```sh
+git fetch origin pr-assets
+git worktree add /tmp/nota-assets origin/pr-assets -B pr-assets
+mkdir -p /tmp/nota-assets/<folder> && cp <pngs> <results.csv> <summary.md> /tmp/nota-assets/<folder>/
+git -C /tmp/nota-assets add <folder>
+git -C /tmp/nota-assets -c user.name="Egor Khindikaynen" -c [email protected] commit -m "Images for <change>"
+git -C /tmp/nota-assets -c credential.helper= -c credential.helper='!gh auth git-credential' \
+ push https://github.com/nota-daw/nota.git HEAD:pr-assets
+git worktree remove /tmp/nota-assets
+```
+
+For benchmarks commit the CSV and `summary.md` next to the charts, so the numbers stay checkable.
+Embed with `https://raw.githubusercontent.com/nota-daw/nota/pr-assets/<folder>/<file>.png`.
+
+## 6. Push and open the PR
+
+- Push over HTTPS (SSH push to nota-daw/nota is denied):
+ `git -c credential.helper= -c credential.helper='!gh auth git-credential' push -u https://github.com/nota-daw/nota.git <branch>`,
+ then `git fetch origin <branch> && git branch -u origin/<branch>`.
+- `gh pr create --repo nota-daw/nota --base develop --head <branch> --title "<commit-style title>" --body-file <file>`.
+- Body: follow `.github/PULL_REQUEST_TEMPLATE.md` (Summary, Spec, Checklist — tick only what was
+ actually done; leave platforms you didn't build unticked). Add sections as needed:
+ - **Screenshots** — a table, before | after:
+ `| Before | After |` / `|---|---|` / `| ![before](raw-url) | ![after](raw-url) |`
+ - **Benchmark** — the charts, the `summary.md` tables, the commits measured, the machine, and
+ a sentence on how to reproduce (`scripts/bench-engine.sh …`).
+ - **Testing** — what was run and what was not.
+ - Link the issue (`Fixes #N` / `Refs #N`) and, for review follow-ups, the PR being followed up.
+- Base is `develop`. Don't enable auto-merge; don't merge.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index a9693860..5a780edc 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -29,10 +29,16 @@ jobs:
macos:
name: macOS
runs-on: macos-26
+ env:
+ CPM_SOURCE_CACHE: ${{ github.workspace }}/.cpm-cache # fetched deps, cached across runs
steps:
- uses: actions/checkout@v5
+ - name: Cache CPM dependency sources # JUCE, flac, … (cmake/dependencies.cmake)
+ uses: actions/cache@v6
with:
- submodules: recursive # JUCE, flac
+ path: .cpm-cache
+ key: cpm-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('src/native/nota.engine/cmake/dependencies.cmake', 'src/native/nota.engine/CMakeLists.txt') }}
+ restore-keys: cpm-${{ runner.os }}-${{ runner.arch }}-
- uses: actions/setup-dotnet@v5
with:
dotnet-version: '10.0.x'
@@ -47,10 +53,16 @@ jobs:
windows:
name: Windows
runs-on: windows-2022
+ env:
+ CPM_SOURCE_CACHE: ${{ github.workspace }}/.cpm-cache # fetched deps, cached across runs
steps:
- uses: actions/checkout@v5
+ - name: Cache CPM dependency sources # JUCE, flac, … (cmake/dependencies.cmake)
+ uses: actions/cache@v6
with:
- submodules: recursive
+ path: .cpm-cache
+ key: cpm-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('src/native/nota.engine/cmake/dependencies.cmake', 'src/native/nota.engine/CMakeLists.txt') }}
+ restore-keys: cpm-${{ runner.os }}-${{ runner.arch }}-
- uses: actions/setup-dotnet@v5
with:
dotnet-version: '10.0.x'
@@ -68,10 +80,16 @@ jobs:
linux:
name: Linux
runs-on: ubuntu-latest
+ env:
+ CPM_SOURCE_CACHE: ${{ github.workspace }}/.cpm-cache # fetched deps, cached across runs
steps:
- uses: actions/checkout@v5
+ - name: Cache CPM dependency sources # JUCE, flac, … (cmake/dependencies.cmake)
+ uses: actions/cache@v6
with:
- submodules: recursive
+ path: .cpm-cache
+ key: cpm-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('src/native/nota.engine/cmake/dependencies.cmake', 'src/native/nota.engine/CMakeLists.txt') }}
+ restore-keys: cpm-${{ runner.os }}-${{ runner.arch }}-
- uses: actions/setup-dotnet@v5
with:
dotnet-version: '10.0.x'
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index e00c464e..bc3db271 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -105,10 +105,16 @@ jobs:
fail-fast: false
matrix:
arch: [arm64, x86_64]
+ env:
+ CPM_SOURCE_CACHE: ${{ github.workspace }}/.cpm-cache # fetched deps, cached across runs
steps:
- uses: actions/checkout@v5
+ - name: Cache CPM dependency sources # JUCE, flac, … (cmake/dependencies.cmake)
+ uses: actions/cache@v6
with:
- submodules: recursive # JUCE
+ path: .cpm-cache
+ key: cpm-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('src/native/nota.engine/cmake/dependencies.cmake', 'src/native/nota.engine/CMakeLists.txt') }}
+ restore-keys: cpm-${{ runner.os }}-${{ runner.arch }}-
- uses: actions/setup-dotnet@v5
with:
dotnet-version: '10.0.x'
@@ -138,10 +144,16 @@ jobs:
needs: guard
if: github.event_name == 'push' || contains(fromJSON('["windows","all"]'), inputs.platforms)
runs-on: windows-2022
+ env:
+ CPM_SOURCE_CACHE: ${{ github.workspace }}/.cpm-cache # fetched deps, cached across runs
steps:
- uses: actions/checkout@v5
+ - name: Cache CPM dependency sources # JUCE, flac, … (cmake/dependencies.cmake)
+ uses: actions/cache@v6
with:
- submodules: recursive # JUCE
+ path: .cpm-cache
+ key: cpm-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('src/native/nota.engine/cmake/dependencies.cmake', 'src/native/nota.engine/CMakeLists.txt') }}
+ restore-keys: cpm-${{ runner.os }}-${{ runner.arch }}-
- uses: actions/setup-dotnet@v5
with:
dotnet-version: '10.0.x'
@@ -186,8 +198,14 @@ jobs:
container: ${{ matrix.image }}
steps:
- uses: actions/checkout@v5
+ - name: Point CPM at the cache # $GITHUB_WORKSPACE is the container path (github.workspace isn't)
+ run: echo "CPM_SOURCE_CACHE=$GITHUB_WORKSPACE/.cpm-cache" >> "$GITHUB_ENV"
+ - name: Cache CPM dependency sources # JUCE, flac, … (cmake/dependencies.cmake)
+ uses: actions/cache@v6
with:
- submodules: recursive # JUCE
+ path: .cpm-cache
+ key: cpm-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('src/native/nota.engine/cmake/dependencies.cmake', 'src/native/nota.engine/CMakeLists.txt') }}
+ restore-keys: cpm-${{ runner.os }}-${{ runner.arch }}-
- uses: actions/setup-dotnet@v5
with:
dotnet-version: '10.0.x'
diff --git a/.gitignore b/.gitignore
index 3e6e04fe..3a7e17fe 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,33 +1,34 @@
-# Build output
-[Bb]in/
-[Oo]bj/
-build/
-build-*/
-out/
-*.user
-
-# .NET
-project.lock.json
-*.nupkg
-
-# CMake
-CMakeCache.txt
-CMakeFiles/
-cmake_install.cmake
-
-# macOS
-.DS_Store
-
-# IDEs
-.idea/
-.vs/
-.vscode/
-*.swp
-*.DotSettings.user
-
-# Nota project bundles created during testing
-*.nota/
-dist/
+# Build output
+[Bb]in/
+[Oo]bj/
+build/
+build-*/
+.cpm-cache/
+out/
+*.user
+
+# .NET
+project.lock.json
+*.nupkg
+
+# CMake
+CMakeCache.txt
+CMakeFiles/
+cmake_install.cmake
+
+# macOS
+.DS_Store
+
+# IDEs
+.idea/
+.vs/
+.vscode/
+*.swp
+*.DotSettings.user
+
+# Nota project bundles created during testing
+*.nota/
+dist/
# Nota Remote phone page: Vite output of src/web/remote, rebuilt by the Nota.Remote build
src/managed/Nota.Remote/wwwroot/
diff --git a/.specify/bugs/idle-pool-spin/assessment.md b/.specify/bugs/idle-pool-spin/assessment.md
new file mode 100644
index 00000000..b4c70f95
--- /dev/null
+++ b/.specify/bugs/idle-pool-spin/assessment.md
@@ -0,0 +1,94 @@
+# Bug Assessment: Idle engine keeps hardware_concurrency − 1 cores busy (AudioThreadPool never parks)
+
+- **Slug**: idle-pool-spin
+- **Created**: 2026-10-20
+- **Source**: https://github.com/nota-daw/nota/issues/223 (host: github.com — allowlisted)
+- **Verdict**: valid
+- **Severity**: high
+
+## Report (summarized)
+
+Issue #223, "Engine uses almost every CPU core at 100% while idle (AudioThreadPool workers never
+sleep)". Since #212 (`64250a5`), an engine that was created and does nothing (transport stopped)
+burns `hardware_concurrency − 1` cores: 892 % on a 10-core M4 Mac mini, 294 % on a 4-core Linux VM;
+0 % before #212 (`82babfe`). Measured with `nota_engine_create()`, 1 s sleep, then `getrusage` over
+5 s. While rendering, total CPU work per second of audio also rises (1 track: 4 → 52 ms; 32 tracks:
+130 → 325 ms on M4), although wall-clock render time drops (32 tracks render 3.9× faster). Expected:
+idle ≈ 0 % CPU; workers spin briefly after a dispatch, then park on a blocking primitive until the
+next `dispatch()` wakes them; keep the parallel speed-up.
+
+## Symptom
+
+With the engine idle, every AudioThreadPool worker shows as a fully busy core (fans, heat, battery
+drain, competition with the audio callback thread). Expected: close to 0 % CPU when nothing renders.
+
+## Reproduction
+
+1. Build the issue's snippet against `libnota_engine` from `develop`.
+2. Run it: it calls `nota_engine_create()`, sleeps 1 s, measures process CPU over 5 s.
+3. Observe ≈ (hw − 1) × 100 % instead of ≈ 0 %. Alternatively open Nota and watch Activity Monitor.
+
+## Suspected Code Paths
+
+- `src/native/nota.engine/src/engine/AudioThreadPool.cpp:workerLoop()` — when `epoch_ == seen` the
+ worker does 256 × `NOTA_CPU_PAUSE()` then `std::this_thread::yield()`, forever; nothing blocks.
+ `yield()` only gives the core away when another thread is runnable.
+- `src/native/nota.engine/src/engine/AudioThreadPool.h:dispatch()` — publishes by storing `epoch_`
+ only; there is no wake-up path for a parked worker (the destructor comment "wake sleepers" refers
+ to sleepers that do not exist).
+- `src/native/nota.engine/src/engine/Engine_Render.cpp:2186` — the only `dispatch()` call, once per
+ audio block, so the gap between jobs is a whole block period (~10 ms at 512 @ 48 kHz) — all of it
+ spent spinning, which also explains the extra CPU work while rendering.
+
+## Root Cause Hypothesis
+
+Confidence: high. The pool introduced in #212 is spin-only by design (header comment: "Workers spin
+(pause hint, then yield — never block on a mutex)"). Spinning across the whole inter-block gap and
+across idle time costs one core per worker.
+
+## Proposed Remediation
+
+**Preferred**: two-phase wait in `workerLoop()`. After finishing (or seeing no) work, spin with
+`NOTA_CPU_PAUSE()` for a short, time-bounded window (~50 µs, checked against `steady_clock` every few
+dozen pauses), then park on a C++20 `std::atomic<uint32_t>::wait()` futex word. Parking protocol
+(Dekker-style, all `seq_cst`): the worker reads the wake word, increments `sleepers_`, re-checks
+`epoch_`/`stop_`, and only then `wait()`s on the wake word; `dispatch()` stores `epoch_` and, only if
+`sleepers_ > 0`, bumps the wake word and calls `notify_all()`. Either the worker sees the new epoch
+or the dispatcher sees the sleeper, so no wake-up is lost, and a hot render (workers still in their
+spin window) costs no syscall. The audio thread never blocks: `notify_all` is a non-blocking futex /
+`__ulock_wake` / `WakeByAddressAll`. A 32-bit wake word keeps the wait on the native futex size on
+every platform (libstdc++ proxies 64-bit waits). The destructor always bumps and notifies.
+
+**Alternatives**:
+- `std::counting_semaphore` released W times per dispatch — simpler, but `release()` on libstdc++/MSVC
+ can take internal paths that are heavier than a single wake, and releasing per worker every block
+ costs more than one `notify_all` gated on sleepers.
+- Keep spinning but `sleep_for` after N yields — cuts idle CPU but adds ms-scale wake latency that
+ breaks the render speed-up; rejected.
+
+**Files likely to change**:
+- `src/native/nota.engine/src/engine/AudioThreadPool.h`
+- `src/native/nota.engine/src/engine/AudioThreadPool.cpp`
+
+**Tests to add or update**:
+- Idle-CPU check: create the engine, measure process CPU over a few seconds, expect ≈ 0 % (the
+ issue's snippet as a throwaway harness).
+- Correctness: many dispatches with gaps longer than the spin window (forcing park/wake each time)
+ plus back-to-back dispatches — every index runs exactly once, no hang; destroy while parked.
+- `scripts/build.sh` smoke test must still pass (end-to-end render).
+
+## Risks & Considerations
+
+- Wake latency (~5–50 µs) is now paid once per block when the gap exceeds the spin window; the
+ caller starts claiming tickets immediately, so the block still completes, only with less help for
+ the first microseconds. Large sessions should keep most of the speed-up.
+- Lost-wakeup races would hang the audio thread's final `done_` wait only if a ticket were never
+ claimed — but the caller claims every unclaimed ticket itself, so a missed wake degrades to
+ serial rendering, never a hang.
+- AR-6: `notify_all` is a syscall on the audio thread, but non-blocking and lock-free; it is skipped
+ whenever no worker is parked.
+
+## Open Questions
+
+- None blocking. Spin window length (~50 µs) is a tunable; can be revisited with the issue's
+ render benchmark.
diff --git a/.specify/bugs/idle-pool-spin/fix.md b/.specify/bugs/idle-pool-spin/fix.md
new file mode 100644
index 00000000..955e654e
--- /dev/null
+++ b/.specify/bugs/idle-pool-spin/fix.md
@@ -0,0 +1,85 @@
+# Bug Fix: Idle engine keeps hardware_concurrency − 1 cores busy (AudioThreadPool never parks)
+
+- **Slug**: idle-pool-spin
+- **Fixed**: 2026-10-20
+- **Assessment**: ./assessment.md
+- **Status**: applied
+
+## Summary
+
+AudioThreadPool workers now spin for a short, fixed number of pause hints after each job and then
+park on a C++20 `std::atomic<uint32_t>::wait()` futex word; `dispatch()` wakes them with a
+non-blocking `notify_all()` only when a worker is parked and the job has more than one ticket. An
+idle engine drops from ~(hw − 1) × 100 % CPU to 0 %.
+
+## Changes
+
+| File | Change | Notes |
+|------|--------|-------|
+| `src/native/nota.engine/src/engine/AudioThreadPool.h` | modified | `sleepers_` + `wake_` members, `park()` decl; `dispatch()` publishes `epoch_` seq_cst and wakes parked workers when `n > 1`; header comment documents the park protocol |
+| `src/native/nota.engine/src/engine/AudioThreadPool.cpp` | modified | `park()`; `workerLoop()` spins 64 × `NOTA_CPU_PAUSE()` then parks (no more `yield()` loop); destructor always bumps + notifies `wake_` |
+
+## Diff Highlights
+
+```cpp
+// dispatch()
+epoch_.store(g, std::memory_order_seq_cst); // publish (seq_cst: pairs with park())
+if (n > 1 && sleepers_.load(std::memory_order_seq_cst) > 0) {
+ wake_.fetch_add(1, std::memory_order_release);
+ wake_.notify_all(); // non-blocking futex wake
+}
+
+// park()
+const uint32_t w = wake_.load(std::memory_order_acquire);
+sleepers_.fetch_add(1, std::memory_order_seq_cst);
+if (epoch_.load(std::memory_order_seq_cst) == seen && !stop_.load(std::memory_order_seq_cst))
+ wake_.wait(w, std::memory_order_acquire);
+sleepers_.fetch_sub(1, std::memory_order_relaxed);
+```
+
+## Tests Added or Updated
+
+No in-repo test target exists for the engine's internals (the engine is covered end-to-end by
+`tests/Nota.SmokeTest`). Throwaway harnesses in `/tmp/pool223/` (not committed):
+
+- `idle.cpp` — the issue's reproduction (create engine, measure process CPU over 5 s).
+- `stress.cpp` — 3 pools × 20 000 dispatches of 1–64 tickets mixing back-to-back dispatches, 100 µs
+ gaps (forces park/wake) and 5 ms gaps; checks every index runs exactly once; destroys while
+ parked. Also built with `-fsanitize=thread`.
+- `bench.cpp` — 1/8/32 audio tracks (WAV clip + Reverb), 10 s rendered in 512-frame blocks via
+ `nota_engine_render_offline`, back-to-back (offline) or paced like a 512 @ 48 kHz callback (rt).
+
+## Local Verification
+
+- `idle` → **0 %** of one core (before: ~1240 % on this 14-thread Mac, 13 workers).
+- `stress` → 1 949 904 tickets, 0 missed/duplicated, no hang. TSan reports 6 warnings on the
+ non-atomic job-slot reads in the claim loop — identical on the pre-fix code, so pre-existing and
+ not from the park path.
+- `bench` (CPU ms / wall ms per second of audio, M-series Mac, before → after):
+
+ | Case | Before | After |
+ |---|---|---|
+ | offline, 1 track | 71.5 / 5.9 | 4.4–5.9 / 4.4–5.9 |
+ | offline, 8 tracks | 182 / 14.0 | 63 / 9.5 |
+ | offline, 32 tracks | 270–280 / 20.9–22.4 | 206–209 / 21.9–22.2 |
+ | rt-paced, 1 track | 12 438 / 1000 | 32 / 1000 |
+ | rt-paced, 32 tracks | 11 894 / 1000 | 608 / 1000 |
+
+ Parallel render speed is unchanged (32-track wall time within run-to-run noise).
+- `scripts/build.sh` (incl. smoke test) → passed on the first version of the fix (3782 PASS,
+ 0 FAIL); re-run on the final version — see the test report.
+
+## Deviations from Assessment
+
+- The assessment proposed a ~50 µs time-bounded spin window. Measured 0 / 20 / 100 µs windows:
+ wall-clock render time was the same for all (within noise) while CPU grew with the window
+ (32 tracks rt: 639 / 695 / 749 ms), because the engine dispatches once per block. The fix uses a
+ fixed 64-pause spin with no clock reads instead.
+- Added the `n > 1` gate on waking: a single-ticket job is taken by the caller itself, so waking
+ workers for it only costs syscalls.
+
+## Follow-ups
+
+- TSan noise on the job-slot fields (pre-existing): consider relaxed atomics for `JobSlot` fields so
+ the pool can be checked under TSan.
+- Consider a small in-repo native test target for `AudioThreadPool` (the stress harness above).
diff --git a/.specify/bugs/idle-pool-spin/test.md b/.specify/bugs/idle-pool-spin/test.md
new file mode 100644
index 00000000..6c653b9f
--- /dev/null
+++ b/.specify/bugs/idle-pool-spin/test.md
@@ -0,0 +1,47 @@
+# Bug Verification: Idle engine keeps hardware_concurrency − 1 cores busy (AudioThreadPool never parks)
+
+- **Slug**: idle-pool-spin
+- **Tested**: 2026-10-20
+- **Assessment**: ./assessment.md
+- **Fix**: ./fix.md
+- **Result**: verified
+
+## Summary
+
+The issue's reproduction now reports 0 % CPU for an idle engine (was ~1240 % on this Mac). The pool
+stress test shows no lost or duplicated tickets and no hangs, the multi-core render speed is
+unchanged, and the full build with the smoke test passes. Checked on macOS (Apple Silicon) only.
+
+## Checks Performed
+
+| Check | Command / Action | Result | Notes |
+|-------|------------------|--------|-------|
+| Reproduction (post-fix) | `/tmp/pool223/idle` (issue snippet, linked to `build/libnota_engine.dylib`) | pass | 0 % of one core, twice; pre-fix build ~1240 % |
+| Pool correctness | `/tmp/pool223/stress` (3 pools × 20 000 dispatches, park/wake gaps, destroy while parked) | pass | 1 949 904 tickets, 0 bad, no hang |
+| Thread sanitizer | `stress` built with `-fsanitize=thread` | pass (no new findings) | 6 warnings on job-slot reads; identical on pre-fix code |
+| Render speed / CPU | `/tmp/pool223/bench_{old,new}` 1/8/32 tracks, offline + rt-paced | pass | 32-track wall time same within noise (~21–22 ms per s); CPU lower in every case (rt 32 tracks: 11 894 → 608 ms per s) |
+| Regression suite | `scripts/build.sh` (engine + app build + smoke test) | pass | `SMOKE TEST PASSED`, 3782 PASS, 0 FAIL, exit 0 |
+| Lint / type-check | — | skipped | no separate lint step for the engine; the build compiled clean |
+
+## Output Excerpts
+
+```
+idle engine: 0% of one core
+tickets=1949904 bad=0
+SMOKE TEST PASSED
+exit=0
+```
+
+## Residual Risks
+
+- Linux and Windows not run here. The fix uses standard C++20 `std::atomic<uint32_t>::wait/notify`
+ (futex on Linux, `WaitOnAddress` on Windows); CI's Linux/Windows builds and smoke tests should
+ confirm.
+- The app itself was not watched in Activity Monitor; the C ABI reproduction from the issue was used
+ instead.
+- Waking parked workers adds a futex wake per block on the audio thread (only when a worker is parked
+ and the job has more than one ticket) — non-blocking, but a syscall.
+
+## Recommendation
+
+Close the bug once the Linux/Windows CI builds pass — verified end-to-end on macOS.
diff --git a/.specify/bugs/pr212-review/assessment.md b/.specify/bugs/pr212-review/assessment.md
new file mode 100644
index 00000000..f7ec0267
--- /dev/null
+++ b/.specify/bugs/pr212-review/assessment.md
@@ -0,0 +1,121 @@
+# Bug Assessment: Review findings on the engine rebuild (#212)
+
+- **Slug**: pr212-review
+- **Created**: 2026-10-20
+- **Source**: review of https://github.com/nota-daw/nota/pull/212 (host: github.com — allowlisted), list pasted by the maintainer
+- **Verdict**: valid
+- **Severity**: high (use-after-free on the audio thread; ARM64 data race), the rest low
+
+## Report (summarized)
+
+Findings left on the merged PR #212 (`64250a5`):
+
+1. Use-after-free: `ensureTrackScratch` (Engine.cpp:601) reallocates `leafBuf_`/`leafWork_` on the
+ message thread inside `publishRaw` while the audio thread and pool workers write the current
+ block into them. Adding a track during playback can corrupt memory or crash.
+2. `AudioThreadPool` ordering: `done_.fetch_add` is `relaxed`, so the caller's acquire load has
+ nothing to synchronise with; on ARM64 the accumulate can read half-written worker buffers. Fix:
+ `release` in both places.
+3. Workers spin forever — already fixed in `idle-pool-spin` (#223).
+4. The parallel-render eligibility check doesn't look inside racks; v4 racks can hold hosted
+ plugins, which would then run on a pool thread.
+5. `stageSilent_` is computed every block but never read — wasted passes on the RT thread.
+6. Pool scratch is reserved but unused.
+7. Scanner dead code, including a second `indexOfId` with different logic.
+8. Two copies of `AudioPluginFormatManager` in the plugin host.
+9. `instantiateCatalog` copies the whole catalog for one entry and is TOCTOU-prone.
+10. CI not updated for CPM: no cache, `submodules: recursive` left over, JUCE/flac/miniaudio pinned
+ by tag instead of commit.
+
+## Symptom
+
+(1) memory corruption / crash when the track count grows while audio renders; (2) possible torn
+reads of worker output on ARM64; (4) a hosted plugin inside a rack processed off the audio thread;
+(5)–(9) wasted RT work and maintenance hazards; (10) slow, unpinned CI dependency fetches.
+
+## Reproduction
+
+1. Start playback with N tracks, add tracks until N exceeds the previous high-water mark — the
+ `std::vector` growth in `ensureTrackScratch`/`ensureMidiScratch` frees the buffers the audio
+ thread holds. (Not reproduced as a crash here; it is a code-evident race.)
+2. Put a VST3/AU inside an Audio Effect Rack on a track: `RackDevice::builtinKind()` is 5, so the
+ track is marked eligible and the rack (with its plugin) runs in `pool_.dispatch`.
+3. Others: read the code paths below.
+
+## Suspected Code Paths
+
+- `src/native/nota.engine/src/engine/Engine.cpp:584-604` `ensureMidiScratch`/`ensureTrackScratch` —
+ grow `blockMidi_`, `blockExpr_`, `blockMidiN_`, `blockExprN_`, `leafWork_`, `leafBuf_` in place
+ from `publishRaw` while `processBlock` may be mid-block on the audio thread. `blockMidi_`/`blockExpr_`
+ have the same flaw as the two named in the report (outer vector reallocation).
+- `src/native/nota.engine/src/engine/AudioThreadPool.h:dispatch()` and `.cpp:workerLoop()` —
+ `done_.fetch_add(1, relaxed)`.
+- `src/native/nota.engine/src/engine/Engine_Render.cpp:2163-2175` — eligibility uses
+ `instrument->kind() < 0` and `device->builtinKind() < 0`; racks (`RackDevice` 5, `RackInstrument`
+ 3, `DrumRack`) pass even when a chain holds a plugin.
+- `Engine_Render.cpp:1777,2310,2385,2476`, `Engine.h:1776-1777` — `stageSilence_`/`stageSilent_`
+ written only.
+- `AudioThreadPool.{h,cpp}` `reserveScratch`/`workerScratchBuffer`/`scratch_`; `Engine.cpp:25,602`.
+- `pluginhost/scanner/OutOfProcessScanner.{h,cpp}` `ScanResult`, `scanOne`;
+ `pluginhost/scanner/PluginCatalog.{h,cpp}` `snapshot`, `hasFileOrIdentifier`, free
+ `catalog::indexOfId` (suffix match instead of format+name+hex-uid); `bridge/PluginCatalogBridge.h`.
+- `pluginhost/scanner/abi_pluginscanner.cpp:formatManager()` vs
+ `pluginhost/hosting/PluginCommon.cpp:sharedFormatManager()`.
+- `pluginhost/hosting/PluginCommon.cpp:instantiateCatalog` (`catalog.types()` deep-copies every
+ description) and `PluginHost.cpp:createPluginInstrument` (`entryAt` then `instantiateCatalog` under
+ two separate locks: a scan in between shifts indexes).
+- `.github/workflows/ci.yml`, `.github/workflows/release.yml`,
+ `src/native/nota.engine/cmake/dependencies.cmake`.
+
+## Root Cause Hypothesis
+
+Confidence: high for all items — each is visible in the code as described.
+
+## Proposed Remediation
+
+**Preferred**:
+1. Move the per-block render scratch (leaf work + leaf buffers + MIDI/expression pre-pass buffers)
+ into one `RenderScratch` object published through the engine's existing `SnapshotHistory`
+ (message thread builds a bigger one with headroom, publishes it before the graph swap; the
+ audio thread reads it once per block after loading the graph and ends the block with a
+ `RenderScope`; retired scratch is freed two renders later). Nothing the audio thread holds is
+ ever reallocated.
+2. `done_.fetch_add(1, std::memory_order_release)` in the worker and caller claim loops.
+4. Add `virtual bool hostsPlugin() const` to `Device` (default `builtinKind() < 0`) and `Instrument`
+ (default `kind() < 0`); racks override it by walking their live snapshot recursively. The
+ eligibility check uses it.
+5. Remove `stageSilence_`/`stageSilent_` and the four detector passes.
+6. Remove the pool's scratch API.
+7. Remove the dead scanner code and the JUCE-free bridge it was the only user of.
+8. The scanner ABI uses `hosting::sharedFormatManager()`.
+9. `PluginCatalog::typeAt(index, out)` copies one description under one lock; instantiation checks
+ instrument-ness on that same copy.
+10. CI: drop `submodules: recursive`, set `CPM_SOURCE_CACHE` and cache it with `actions/cache`
+ keyed on `dependencies.cmake`; pin miniaudio, flac, JUCE by commit SHA (tag in a comment).
+
+**Files likely to change**: `Engine.{h,cpp}`, `Engine_Render.cpp`, `AudioThreadPool.{h,cpp}`,
+`devices/Device.h`, `devices/Instrument.h`, `devices/racks/RackCore.h`, `RackDevice.h`,
+`RackInstrument.h`, `pluginhost/scanner/*`, `pluginhost/bridge/PluginCatalogBridge.h`,
+`pluginhost/hosting/PluginCommon.{h,cpp}`, `PluginHost.cpp`, `cmake/dependencies.cmake`,
+`.github/workflows/{ci,release}.yml`.
+
+**Tests to add or update**:
+- Throwaway harness: grow the track count repeatedly while a second thread renders (ASan) — no
+ errors.
+- Pool stress harness from `idle-pool-spin` still passes.
+- `scripts/build.sh` smoke test (renders end-to-end, scans plugins, rack round-trips).
+
+## Risks & Considerations
+
+- Scratch headroom costs memory: 256 KB per track slot (kMaxBlock 16384 × 4 floats); growth
+ rounds up to multiples of 8 tracks.
+- Retired scratch is freed only on the next publish (SnapshotHistory semantics) — one extra copy
+ may linger.
+- The rack walk runs on the audio thread once per block per rack — reads only, no allocation.
+- Not addressed here: pool workers run at normal priority while the audio callback waits for them
+ (priority inversion). Needs per-platform priority work (macOS audio workgroups, Windows MMCSS,
+ Linux SCHED_FIFO) — follow-up.
+
+## Open Questions
+
+- None blocking.
diff --git a/.specify/bugs/pr212-review/fix.md b/.specify/bugs/pr212-review/fix.md
new file mode 100644
index 00000000..acd10a23
--- /dev/null
+++ b/.specify/bugs/pr212-review/fix.md
@@ -0,0 +1,131 @@
+# Bug Fix: Review findings on the engine rebuild (#212)
+
+- **Slug**: pr212-review
+- **Fixed**: 2026-10-20
+- **Assessment**: ./assessment.md
+- **Status**: applied (item 3 in `../idle-pool-spin/`)
+
+## Summary
+
+Per-block render scratch is now published as one immutable-size object through `SnapshotHistory`
+instead of being grown in place under the audio thread; pool completions publish with `release`;
+racks report nested hosted plugins so such tracks stay off the pool; unused stage-silence passes and
+pool scratch are gone; the plugin scanner lost its dead code, shares one format manager with hosting
+and instantiates from a single locked copy of one entry; CI caches CPM sources, no longer checks out
+submodules, and every git dependency is pinned by commit.
+
+## Changes
+
+| File | Change | Notes |
+|------|--------|-------|
+| `src/engine/Engine.h` | modified | `RenderScratch` (leaf work + buffers, MIDI/expr pre-pass) + `scratchHist_`/`rs_`; removed `leafWork_`, `leafBuf_`, `blockMidi*_`, `blockExpr*_`, `stageSilence_`/`stageSilent_` |
+| `src/engine/Engine.cpp` | modified | `ensureRenderScratch()` builds + publishes a new scratch (steps of 8 tracks) before the graph swap; replaces `ensureMidiScratch`/`ensureTrackScratch`; drops pool scratch reserve and detector rate setup |
+| `src/engine/Engine_Render.cpp` | modified | `processBlock` takes this block's scratch after the graph load under a `RenderScope`; all users read `rs_->…`; eligibility uses `hostsPlugin()`; four detector passes removed |
+| `src/engine/AudioThreadPool.{h,cpp}` | modified | `done_.fetch_add(1, release)` in caller + worker; scratch API removed |
+| `src/devices/Device.h`, `Instrument.h` | modified | `virtual bool hostsPlugin()` (default: not a built-in) |
+| `src/devices/racks/RackCore.{h,cpp}`, `RackDevice.h`, `RackInstrument.h` | modified | `chainsHostPlugin()` walks the live snapshot recursively; racks (and Drum Rack) override `hostsPlugin()` |
+| `pluginhost/scanner/PluginCatalog.{h,cpp}` | modified | indexed `types` copy synced on every mutation (reads no longer copy the whole list); `typeAt()`; `sharedFormatManager()` lives here; removed `snapshot`, `entryAt`, `hasFileOrIdentifier`, `types()`, free `catalog::indexOfId` |
+| `pluginhost/scanner/OutOfProcessScanner.{h,cpp}` | modified | removed `ScanResult`, `scanOne` |
+| `pluginhost/scanner/abi_pluginscanner.cpp` | modified | uses `scanner::sharedFormatManager()` |
+| `pluginhost/bridge/PluginCatalogBridge.h` | removed | only served the dead code |
+| `pluginhost/hosting/PluginCommon.{h,cpp}`, `PluginHost.cpp` | modified | `instantiateCatalog(index, sr, block, instrumentOnly)` copies one entry and checks it; second format manager removed |
+| `src/native/nota.engine/CMakeLists.txt`, `ARCHITECTURE.md` | modified | comments/docs for the removed bridge header |
+| `src/native/nota.engine/cmake/dependencies.cmake` | modified | miniaudio `9634bed`, flac `1507800`, JUCE `2cdfca8` (tag in comment) |
+| `.github/workflows/ci.yml`, `release.yml` | modified | no `submodules: recursive`; `actions/cache@v6` on `.cpm-cache` + `CPM_SOURCE_CACHE` (container job sets it from `$GITHUB_WORKSPACE`) |
+| `.gitignore`, `README.md`, `LICENSES/third-party.md` | modified | `.cpm-cache/`; plain `git clone`; pins described as commits |
+
+## Tests Added or Updated
+
+Throwaway harnesses in `/tmp/pool223/` (not committed; the engine has no in-repo native test target):
+
+- `grow.cpp` — a render thread runs 256-frame blocks non-stop while the main thread adds 40 tracks
+ (instrument + clip / audio + Reverb) and removes them, 4 rounds.
+- `stress.cpp`, `idle.cpp`, `bench.cpp` — from `idle-pool-spin`.
+
+## Local Verification
+
+- `grow` on pre-fix `develop`: **SIGSEGV (exit 139) 3/3**. After the fix: exit 0 5/5 (Release) and
+ 2/2 under AddressSanitizer with no reports.
+- Fresh configure with an empty `CPM_SOURCE_CACHE` fetched all deps; JUCE/flac/miniaudio checkouts
+ are at the pinned SHAs; JUCE shallow fetch by SHA works.
+- `stress` 0 bad tickets; `idle` 0 %; bench: 32 tracks offline 22.3 ms wall/s (unchanged), rt 32
+ tracks 556 ms CPU/s (was 608 before removing the detector passes).
+- `scripts/build.sh` — see test.md.
+
+## Deviations from Assessment
+
+- `blockMidi_`/`blockExpr_` had the same in-place growth race as `leafBuf_`/`leafWork_` and were
+ moved into the same scratch object.
+- Beyond `instantiateCatalog`, every catalog read (`count`, `idAt`, `descLine`, `indexOfId`, scan
+ helpers) copied the whole list via `KnownPluginList::getTypes()`; the indexed copy fixes them all.
+- The shared format manager moved to `scanner/` (not `hosting/`), keeping the rule that the scanner
+ never includes hosting code.
+
+## Later change: adaptive linger in the pool
+
+Benchmarking against pre-#212 and post-#212 builds showed the park-at-once workers made
+**offline** renders (export, freeze) slower than post-#212 on light loads (32 synth tracks:
+8.8 vs 6.3 ms per second of audio): back-to-back blocks are only tens of µs apart, so every block
+paid a wake-up. A fixed longer spin fixed that but cost 8–40 % more CPU in real time. `dispatch()`
+now measures the gap since the previous job: under 200 µs, idle workers linger up to twice the gap
+(≤ 100 µs) before parking; a device callback's gap is a whole buffer, so they park at once.
+Result: offline matches post-#212 (3.7 / 6.5 / 21.2 ms), real time stays low, idle 0 %.
+
+## Later change: real-time policy — one thread unless it can't keep up
+
+The three-way benchmark still showed the pool spending 2–2.7x the CPU of the single-threaded
+engine while playing (32 audio tracks: ~70 % vs ~31 % of a core). Measured, step by step:
+
+- Waking only as many workers as the job needs (`dispatch(n, fn, helpers)`, `notify_one` x k)
+ changed nothing: on a light block the woken threads cost the same either way.
+- On Apple Silicon the default worker count spilled onto efficiency cores (13 workers, 10
+ performance cores); capping at performance cores − 1 cut offline CPU by ~22 % at the same speed.
+ QoS classes made no difference.
+- The real cost: a block that fits the buffer, spread over parked threads, wakes idle cores at
+ low clocks. With small buffers parallel rendering also missed **more** deadlines than one
+ thread (128 tracks at 64 frames: 352 late blocks vs 2), because waking takes a good part of a
+ 1.3 ms period.
+
+So with a device the audio thread renders alone; the pool joins only under sustained overload —
+when the single-thread cost of the parallel leaves (measured on blocks rendered alone, smoothed
+by 1/16) passes the buffer period — and leaves after 2 s to re-measure (while it runs, a block
+rendered alone reads 1.5–2x its real cost, so it can't tell when the overload ends). Offline
+renders (back-to-back `renderOffline` blocks) still use every thread. Two traps found on the way
+and closed: a slow device block looked "back-to-back" and switched to offline mode (now only
+`renderOffline` can be offline), and lingering workers stole the tickets of a job that woke no one
+(no linger without helpers). New ABI `nota_engine_render_device_block` renders one block through
+the callback's path without a device, so tests and the benchmark measure what a device does.
+
+Device path, same machine: 32 audio tracks at 512 — 30 % (= one thread, = before #212);
+128 tracks at 64 frames — 75 %, same late blocks as one thread; 192 tracks at 64 frames
+(overload) — 547 late blocks of 7500 vs 2970 on one thread.
+
+## Regression guards (in the smoke test)
+
+`tests/Nota.SmokeTest/RenderPoolTests.cs` (full run and `-- --perf`), on top of two new ABI
+calls — `nota_engine_set_render_threads` / `nota_engine_render_threads` (0 = render on the audio
+thread alone, device stopped only) and `nota_engine_render_threads_cpu_seconds` (the render
+threads' own CPU clocks):
+
+1. idle engine: render threads < 20 ms CPU over 1 s;
+2. after playback stops: the same;
+3. real-time playback of 16 tracks (device path) that one thread keeps up with: render threads
+ < 2 % of a core, total CPU <= 1.5x single-thread + 3 %;
+3b. overload (256 tracks, 64-frame buffer, most blocks late on one thread): render threads join,
+ late blocks not more than on one thread (skipped when this machine keeps up alone);
+4. bounce of 16 tracks: parallel CPU work <= 3x single-thread; wall time <= 1.3x (timing budget,
+ lenient under CI);
+5. 8 synth tracks render bit-identically on N threads and on one;
+6. 48 tracks added/removed while blocks render: no crash.
+
+Proven against the old behaviour: with the #212 spin put back, checks 1–3 fail (11.6 s of worker
+CPU per idle second); with the scratch grown in place again, check 6 crashes the run.
+
+## Follow-ups
+
+- Priority inversion: pool workers run at normal priority while the audio callback waits on them.
+ Needs per-platform work (macOS audio workgroup / QoS, Windows MMCSS, Linux SCHED_FIFO).
+- `specs/030-dsp-architecture-overhaul/` still describes `PluginCatalogBridge.h` (historical spec
+ artifacts, left as is).
+- The rack-plugin eligibility path was not exercised at runtime (no plugin installed in the test
+ environment); covered by build + code reading.
diff --git a/.specify/bugs/pr212-review/test.md b/.specify/bugs/pr212-review/test.md
new file mode 100644
index 00000000..7b8c1593
--- /dev/null
+++ b/.specify/bugs/pr212-review/test.md
@@ -0,0 +1,51 @@
+# Bug Verification: Review findings on the engine rebuild (#212)
+
+- **Slug**: pr212-review
+- **Tested**: 2026-10-20
+- **Assessment**: ./assessment.md
+- **Fix**: ./fix.md
+- **Result**: partial
+
+## Summary
+
+The use-after-free reproduces on pre-fix `develop` (crash every run) and is gone after the fix,
+including under ASan. Pool, idle CPU, render speed and the full build + smoke test all pass on macOS.
+The result is partial because three items could not be exercised here: the ARM64 ordering fix (no
+reliable repro), the rack-with-plugin path (no plugin installed) and the CI workflow changes (run on
+GitHub only).
+
+## Checks Performed
+
+| Check | Command / Action | Result | Notes |
+|-------|------------------|--------|-------|
+| UAF reproduction (pre-fix) | `/tmp/pool223/grow_old` vs original `develop` dylib | fail as expected | SIGSEGV, exit 139, 3/3 |
+| UAF reproduction (post-fix) | `/tmp/pool223/grow_rel` | pass | exit 0, 5/5 |
+| UAF under ASan | `grow_asan` against `build-asan` (RelWithDebInfo + `-fsanitize=address`) | pass | 2/2, no ASan reports |
+| Pool ordering / correctness | `/tmp/pool223/stress` | pass | 1 949 904 tickets, 0 bad — exercises the pool but can't prove the ARM64 race is gone |
+| Idle CPU | `/tmp/pool223/idle` | pass | 0 % |
+| Render speed | `bench_new 32`, `32 rt`, `8` | pass | 22.3 ms wall/s (unchanged), CPU lower |
+| Rack with hosted plugin stays serial | — | not-run | no VST3/AU in the test environment; code-reviewed |
+| Pinned deps from scratch | fresh configure with empty `CPM_SOURCE_CACHE` | pass | JUCE `2cdfca8`, flac `1507800`, miniaudio `9634bed` checked out |
+| Workflow syntax | YAML parse of `ci.yml`, `release.yml` | pass | the cache/env behaviour on runners can only be confirmed by a CI run |
+| Render-pool guards | `dotnet run --project tests/Nota.SmokeTest -c Release -- --perf` | pass | 10 checks; fail against the reintroduced #212 spin (idle/stop/real-time), against waking every thread each block (render threads at 19 % of a core while one thread keeps up), and against in-place scratch growth (crash) |
+| Regression suite | `scripts/build.sh` (engine + app + smoke test) | pass | `SMOKE TEST PASSED`, 3789 PASS, 0 FAIL |
+
+## Output Excerpts
+
+```
+grow_old: exit 139 (x3)
+grow_rel: rendered 18899 blocks, tracks now 0 / exit=0
+grow_asan: rendered 11726 blocks, tracks now 0 (no AddressSanitizer report)
+SMOKE TEST PASSED
+```
+
+## Residual Risks
+
+- Linux/Windows untested locally; the CI run on the PR will cover the build and the new cache steps
+ (including the container job that sets `CPM_SOURCE_CACHE` from `$GITHUB_WORKSPACE`).
+- Priority inversion between the audio callback and normal-priority pool workers is not addressed
+ (follow-up).
+
+## Recommendation
+
+Merge once the PR's CI passes on all three platforms. Follow up separately on the pool-worker priority.
diff --git a/AGENTS.md b/AGENTS.md
index 98a0f974..03052283 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -18,7 +18,7 @@ restrictions).
edits — skips the spec and goes straight to the change.
- Bug reports go through the speckit `bug-assess` → `bug-fix` → `bug-test` commands.
- The `nota-*` skills in `.claude/skills/` and `.agents/skills/` (design, docs,
- features, instrument, shortcuts, release) encode project-specific workflows — prefer
+ features, instrument, shortcuts, release, pr) encode project-specific workflows — prefer
them over improvising.
- Before any pull request: `scripts/build.sh` (or the Linux/Windows siblings) must pass;
it runs the smoke test that drives the engine end-to-end.
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index e1a48fa6..df9b40f4 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -47,7 +47,7 @@ engine embeddable and the UI replaceable.
| `src/native/nota.engine/src/engine/` | Engine model classes (`Graph`, `Track`, `Transport`, `SessionPlayer`, `Automation`, `Modulation`, `MidiClip`, `MidiController`, `NoteExpression`, `CommandQueue`, `SnapshotHistory`, `Audition`) plus the multi-core `AudioThreadPool` — each as a `.h`/`.cpp` pair. |
| `src/native/nota.engine/src/dsp/` | Shared C++20 DSP building blocks: `core/` (spans, params, silence detection, RT attributes), `math/` (`FastMath`, SIMD, PRNG), `primitives/` (filters, delay, oscillators, envelopes, oversampler, convolution), `poly/` (voices, voice manager). |
| `src/native/nota.engine/src/abi/` | C ABI translation units (`nota_engine_*.cpp`) and `media/` (samples, warp, analysis) and `audio_io/` (platform backends). |
-| `src/native/nota.engine/pluginhost` | JUCE-based VST3/AU hosting: `hosting/` (play-head, editors, plugin devices), `scanner/` (thread-safe `PluginCatalog`, out-of-process scan, `nota_pluginscanner` INTERFACE target), `scanner/worker/` (`nota-scanworker`), `bridge/` (the two bridge headers). |
+| `src/native/nota.engine/pluginhost` | JUCE-based VST3/AU hosting: `hosting/` (play-head, editors, plugin devices), `scanner/` (thread-safe `PluginCatalog`, out-of-process scan, `nota_pluginscanner` INTERFACE target), `scanner/worker/` (`nota-scanworker`), `bridge/` (`PluginHostBridge.h`, the engine's only door into hosting). |
| `src/native/nota.engine/vendor` | Vendored third-party sources (see `LICENSES/third-party.md`). |
| `tests/Nota.SmokeTest` | End-to-end smoke test driven through the C ABI. |
| `scripts` | Per-platform build and packaging scripts. |
diff --git a/CLAUDE.md b/CLAUDE.md
index 731a4980..17292be8 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -19,6 +19,6 @@ restrictions).
the change.
- Bug reports go through `/speckit-bug-assess` → `/speckit-bug-fix` → `/speckit-bug-test`.
- The `nota-*` skills in `.claude/skills/` (design, docs, features, instrument,
- shortcuts, release) encode project-specific workflows — prefer them over improvising.
+ shortcuts, release, pr) encode project-specific workflows — prefer them over improvising.
- Before any pull request: `scripts/build.sh` (or the Linux/Windows siblings) must pass;
it runs the smoke test that drives the engine end-to-end.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 5b7b4ccb..2d136dba 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -156,6 +156,12 @@ git -C ../nota-assets add my-change && git -C ../nota-assets commit -m "Images f
git -C ../nota-assets push origin HEAD:pr-assets
```
+A user-visible UI change carries before/after screenshots there; a performance change
+carries a before/after benchmark — `scripts/bench-engine.sh` measures engine builds through
+the C ABI and `scripts/bench-chart.py` turns the results into charts and a table. The
+smoke test's render-pool guards (`RenderPoolTests`, `-- --perf` alone) catch the
+regressions automatically; a performance fix adds a guard there.
+
You can also drag images straight into the GitHub description box when you write it by
hand. The branch is for images added by scripts or tools, and for anything you want to
keep alongside the repository.
diff --git a/LICENSES/third-party.md b/LICENSES/third-party.md
index b64014fb..0f8be4e2 100644
--- a/LICENSES/third-party.md
+++ b/LICENSES/third-party.md
@@ -12,12 +12,12 @@ public domain, or AGPL-compatible copyleft.
|---|---|---|---|---|
| .NET runtime | 10 | Managed runtime | MIT | ✅ in use |
| Avalonia | 12 | UI framework | MIT | ✅ in use |
-| JUCE | 8.0.14 | Plugin hosting (VST3 / AU) | **AGPL-3.0** | ✅ in use — CPM tag, shallow fetch — see note 1 |
+| JUCE | 8.0.14 | Plugin hosting (VST3 / AU) | **AGPL-3.0** | ✅ in use — CPM pinned commit `2cdfca8`, shallow fetch — see note 1 |
| Steinberg VST3 SDK | bundled with JUCE 8 | VST3 hosting | MIT | ✅ in use — see note 2 |
-| miniaudio | 0.11.25 | Audio device I/O (WASAPI / PulseAudio / ALSA) | Unlicense **or** MIT-0 | ✅ in use — CPM tag, fetched to build dir |
+| miniaudio | 0.11.25 | Audio device I/O (WASAPI / PulseAudio / ALSA) | Unlicense **or** MIT-0 | ✅ in use — CPM pinned commit `9634bed`, fetched to build dir |
| RtMidi | 6.0.0 (pinned commit, byte-identical to former snapshot) | MIDI I/O (WinMM / ALSA) | MIT-like (RtMidi) | ✅ in use — CPM pinned commit, fetched to build dir |
| dr_libs (dr_wav / dr_flac / dr_mp3) | pinned commit `cd99e2c` (headers: wav 0.14.6 / flac 0.13.4 / mp3 0.7.4, byte-identical to former snapshot) | WAV / FLAC / MP3 decoding | Unlicense **or** MIT-0 | ✅ in use — CPM pinned commit, fetched to build dir — see note 3 |
-| libFLAC (xiph) | 1.5.0 | FLAC encoding (export) | BSD-3-Clause | ✅ in use — CPM tag, fetched to build dir |
+| libFLAC (xiph) | 1.5.0 | FLAC encoding (export) | BSD-3-Clause | ✅ in use — CPM pinned commit `1507800`, fetched to build dir |
| LAME | 3.100 (sources byte-identical to former snapshot; wrapper moved to `cmake/lame/`) | MP3 encoding (export) | **LGPL-2.0-or-later** | ⚠️ cleared with a condition — see note 7 |
| signalsmith-stretch | pinned commit `57b93f4` (header v1.3.2, byte-identical to former snapshot) | Time-stretch / pitch-shift (clip warping) | MIT | ✅ in use — CPM pinned commit, fetched to build dir |
| signalsmith-linear | pinned commit `7f53cdd` (fft.h byte-identical to former snapshot) | FFT / linear DSP primitives | MIT | ✅ in use — CPM pinned commit, fetched to build dir |
@@ -88,6 +88,6 @@ lists hide it, same as JUCE in note 1).
## Not shipped
-The JUCE submodule (`src/native/nota.engine/vendor/JUCE`) is fetched at build time and
+JUCE is fetched at build time by CPM (into the build dir) and
is **not** redistributed in this repository's own source tree. Binary releases that
statically link it do redistribute it, under AGPLv3.
diff --git a/README.md b/README.md
index 68241336..61ba702e 100644
--- a/README.md
+++ b/README.md
@@ -192,7 +192,7 @@ plugin hosting runs through JUCE, isolated in its own module so the engine core
JUCE-free.
```bash
-git clone --recurse-submodules https://github.com/nota-daw/nota.git
+git clone https://github.com/nota-daw/nota.git
cd nota
scripts/build.sh # Build on macOS.
scripts/build-linux.sh # Build on Linux.
diff --git a/scripts/bench-chart.py b/scripts/bench-chart.py
new file mode 100755
index 00000000..670d73a0
--- /dev/null
+++ b/scripts/bench-chart.py
@@ -0,0 +1,204 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: AGPL-3.0-only
+"""Turn scripts/bench-engine.sh output into charts and a Markdown summary.
+
+Usage: scripts/bench-chart.py <out-dir> [label=Display name ...]
+
+Reads <out-dir>/results.csv and machine.txt; takes the median of the runs per
+build and scenario; writes into <out-dir>:
+ cpu-playing.svg - CPU while idle and while playing in real time (% of one core)
+ bounce-time.svg - offline render time per second of audio (lower is faster)
+ bounce-cpu.svg - CPU work per second of audio during an offline render
+ small-buffer-late.svg / small-buffer-cpu.svg - late blocks and CPU for the rt runs
+ at buffers other than 512 (heavy sessions), when there are any
+ summary.md - the same numbers as Markdown tables, plus the machine
+Each SVG is also rendered to a 2x PNG (rsvg-convert or headless Chrome) for PR descriptions.
+Builds keep the order given on the command line (else CSV order). Stdlib only.
+"""
+
+import csv
+import math
+import os
+import shutil
+import statistics
+import subprocess
+import sys
+from collections import OrderedDict
+
+# Categorical slots 1-3 (validated all-pairs, light surface), chart chrome.
+SERIES = ["#2a78d6", "#eb6834", "#1baf7a"]
+SURFACE, INK, INK2, MUTED, GRID, AXIS = "#fcfcfb", "#0b0b0b", "#52514e", "#898781", "#e1e0d9", "#c3c2b7"
+FONT = "-apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif"
+
+SCEN_NAME = {"audio": "audio", "inst": "synth"}
+
+
+def group_name(scenario, tracks, block="512"):
+ if scenario == "idle":
+ return "Idle"
+ n = int(tracks)
+ name = f"{n} {SCEN_NAME[scenario]} track{'s' if n != 1 else ''}"
+ return name if block in ("", "512") else f"{name} · {block}-sample buffer"
+
+
+def load(out):
+ rows = list(csv.DictReader(open(os.path.join(out, "results.csv"))))
+ data = OrderedDict() # (scenario, tracks, mode) -> label -> [rows]
+ labels = []
+ for r in rows:
+ if r["label"] not in labels:
+ labels.append(r["label"])
+ block = r.get("block") or ("" if r["scenario"] == "idle" else "512")
+ r["block"] = block
+ if r.get("misses") not in (None, "") and block: # late blocks, % of the run's blocks
+ r["late_pct"] = str(100.0 * float(r["misses"]) / (10 * 48000 / int(block)))
+ data.setdefault((r["scenario"], r["tracks"], r["mode"], block), {}).setdefault(r["label"], []).append(r)
+ return data, labels
+
+
+def med(rs, field):
+ vals = [float(r[field]) for r in rs if r.get(field)]
+ return statistics.median(vals) if vals else None
+
+
+def nice_step(raw):
+ # 1, 2, 2.5 or 5 times a power of ten: ticks read as round numbers.
+ if raw <= 0:
+ return 1.0
+ mag = 10 ** math.floor(math.log10(raw))
+ return next(m * mag for m in (1, 2, 2.5, 5, 10) if m * mag >= raw)
+
+
+def fmt(v):
+ return f"{v:,.0f}" if v >= 100 else (f"{v:.1f}" if v >= 1 else f"{v:.2f}".rstrip("0").rstrip(".") or "0")
+
+
+def bar_chart(path, title, subtitle, unit, groups, labels, names):
+ """groups: [(group label, {label: value})]."""
+ W, H = 960, 440
+ left, right, top, bottom = 64, 24, 96, 56
+ pw, ph = W - left - right, H - top - bottom
+ peak = max((v for _, vals in groups for v in vals.values() if v is not None), default=1) * 1.08
+ step = nice_step(peak / 4)
+ ticks = max(1, math.ceil(peak / step))
+ vmax = step * ticks
+ gw = pw / len(groups)
+ bw = min(40, (gw - 24) / len(labels) - 2)
+ y = lambda v: top + ph - ph * v / vmax
+ s = [f'<svg xmlns="http://www.w3.org/2000/svg" width="{W}" height="{H}" viewBox="0 0 {W} {H}" font-family="{FONT}">',
+ f'<rect width="{W}" height="{H}" fill="{SURFACE}"/>',
+ f'<text x="{left}" y="34" font-size="18" font-weight="600" fill="{INK}">{title}</text>',
+ f'<text x="{left}" y="56" font-size="13" fill="{INK2}">{subtitle}</text>']
+ # legend (identity never colour-alone: labels sit next to the swatches)
+ lx = left
+ for i, lab in enumerate(labels):
+ s.append(f'<rect x="{lx}" y="70" width="12" height="12" rx="3" fill="{SERIES[i]}"/>')
+ s.append(f'<text x="{lx + 18}" y="80" font-size="13" fill="{INK2}">{names.get(lab, lab)}</text>')
+ lx += 30 + 7.5 * len(names.get(lab, lab))
+ # grid + y axis
+ for k in range(ticks + 1):
+ v = step * k
+ yy = y(v)
+ s.append(f'<line x1="{left}" x2="{W - right}" y1="{yy:.1f}" y2="{yy:.1f}" stroke="{GRID if k else AXIS}" stroke-width="1"/>')
+ tick = f"{v:,.0f}" if step >= 1 else f"{v:g}"
+ s.append(f'<text x="{left - 8}" y="{yy + 4:.1f}" font-size="12" fill="{MUTED}" text-anchor="end">{tick}</text>')
+ s.append(f'<text x="14" y="{top + ph / 2:.0f}" font-size="12" fill="{MUTED}" transform="rotate(-90 14 {top + ph / 2:.0f})" text-anchor="middle">{unit}</text>')
+ for gi, (gname, vals) in enumerate(groups):
+ gx = left + gi * gw + (gw - len(labels) * (bw + 2) + 2) / 2
+ for i, lab in enumerate(labels):
+ v = vals.get(lab)
+ if v is None:
+ continue
+ x = gx + i * (bw + 2)
+ h = max(ph * v / vmax, 1.5)
+ r = min(4, h / 2, bw / 2)
+ yt = top + ph - h
+ # rounded data end, square at the baseline
+ s.append(f'<path d="M{x:.1f},{top + ph:.1f} V{yt + r:.1f} Q{x:.1f},{yt:.1f} {x + r:.1f},{yt:.1f} '
+ f'H{x + bw - r:.1f} Q{x + bw:.1f},{yt:.1f} {x + bw:.1f},{yt + r:.1f} V{top + ph:.1f} Z" fill="{SERIES[i]}"/>')
+ s.append(f'<text x="{x + bw / 2:.1f}" y="{yt - 5:.1f}" font-size="11" fill="{INK2}" text-anchor="middle">{fmt(v)}</text>')
+ s.append(f'<text x="{left + gi * gw + gw / 2:.1f}" y="{top + ph + 22}" font-size="13" fill="{INK2}" text-anchor="middle">{gname}</text>')
+ s.append("</svg>")
+ open(path, "w").write("\n".join(s))
+
+
+def to_png(svg, w=960, h=440, scale=2):
+ """Rasterize at 2x with rsvg-convert, else headless Chrome; skip if neither exists."""
+ png = svg[:-4] + ".png"
+ if shutil.which("rsvg-convert"):
+ subprocess.run(["rsvg-convert", "-z", str(scale), "-o", png, svg], check=True)
+ return
+ chrome = next((c for c in ("/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+ shutil.which("google-chrome") or "", shutil.which("chromium") or "")
+ if c and os.path.exists(c)), None)
+ if chrome:
+ subprocess.run([chrome, "--headless", "--disable-gpu", f"--window-size={w},{h}",
+ f"--force-device-scale-factor={scale}", f"--screenshot={png}", "file://" + os.path.abspath(svg)],
+ capture_output=True)
+
+
+def main():
+ if len(sys.argv) < 2:
+ print(__doc__, file=sys.stderr)
+ sys.exit(2)
+ out = sys.argv[1]
+ names = dict(a.split("=", 1) for a in sys.argv[2:])
+ data, labels = load(out)
+ if names:
+ labels = [l for l in names if l in labels] + [l for l in labels if l not in names]
+
+ def series(mode, field, small=False):
+ groups = []
+ for (scen, tracks, m, block), by in data.items():
+ if m != mode or (block not in ("", "512")) != small:
+ continue
+ groups.append((group_name(scen, tracks, block), {l: med(by.get(l, []), field) for l in labels}))
+ return groups
+
+ playing = series("idle", "cpu_pct") + series("rt", "cpu_pct")
+ bounce_t = series("offline", "wall_ms_per_s")
+ bounce_c = series("offline", "cpu_ms_per_s")
+ small_late = series("rt", "late_pct", small=True)
+ small_cpu = series("rt", "cpu_pct", small=True)
+ charts = [
+ ("cpu-playing.svg", "CPU while idle and while playing",
+ "Process CPU, median of runs. Playing = blocks paced like a 512-sample buffer at 48 kHz. Lower is better.",
+ "% of one core", playing),
+ ("bounce-time.svg", "Offline render (bounce) time",
+ "Wall-clock time per second of audio, 512-frame blocks back-to-back. Lower is faster.",
+ "ms per second of audio", bounce_t),
+ ("bounce-cpu.svg", "CPU work during an offline render",
+ "CPU time summed over all threads, per second of audio. Lower uses less energy.",
+ "CPU ms per second of audio", bounce_c),
+ ]
+ if small_late:
+ charts += [
+ ("small-buffer-late.svg", "Late blocks at small buffers (heavy sessions)",
+ "Blocks that took longer than their buffer period (a dropout with a device). Lower is better.",
+ "% of blocks late", small_late),
+ ("small-buffer-cpu.svg", "CPU at small buffers (heavy sessions)",
+ "Process CPU while playing in real time. Lower is better.",
+ "% of one core", small_cpu),
+ ]
+ for fname, title, sub, unit, groups in charts:
+ p = os.path.join(out, fname)
+ bar_chart(p, title, sub, unit, groups, labels, names)
+ to_png(p)
+
+ md = []
+ machine = open(os.path.join(out, "machine.txt")).read().strip() if os.path.exists(os.path.join(out, "machine.txt")) else ""
+ for _, title, sub, unit, groups in charts:
+ md.append(f"**{title}** — {unit}, median. {sub.split('. ', 1)[-1]}\n")
+ md.append("| | " + " | ".join(names.get(l, l) for l in labels) + " |")
+ md.append("|---|" + "---:|" * len(labels))
+ for g, vals in groups:
+ md.append(f"| {g} | " + " | ".join(fmt(vals[l]) if vals[l] is not None else "—" for l in labels) + " |")
+ md.append("")
+ if machine:
+ md.append("<details><summary>Machine and builds</summary>\n\n```\n" + machine + "\n```\n</details>")
+ open(os.path.join(out, "summary.md"), "w").write("\n".join(md) + "\n")
+ print(os.path.join(out, "summary.md"))
+
+
+if __name__ == "__main__":
+ main()
diff --git a/scripts/bench-engine.sh b/scripts/bench-engine.sh
new file mode 100755
index 00000000..17806092
--- /dev/null
+++ b/scripts/bench-engine.sh
@@ -0,0 +1,89 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: AGPL-3.0-only
+#
+# Engine benchmark: compares engine builds on the same machine through the public C ABI
+# (scripts/bench/engine-bench.cpp). Each label points at a directory that holds a Release
+# libnota_engine (.dylib / .so) — build each revision you compare first. Runs are
+# interleaved across builds (run 1 of every build, then run 2 …) so heat and background
+# load hit them alike.
+#
+# Usage: scripts/bench-engine.sh [-r runs] <out-dir> <label>=<engine-lib-dir> ...
+# e.g. scripts/bench-engine.sh -r 3 /tmp/bench before=/tmp/old/build after=src/native/nota.engine/build
+#
+# Writes <out-dir>/results.csv (one row per run) and <out-dir>/machine.txt. Turn the CSV
+# into charts + a Markdown table with scripts/bench-chart.py.
+
+set -euo pipefail
+
+runs=3
+if [ "${1:-}" = "-r" ]; then runs="$2"; shift 2; fi
+[ $# -ge 2 ] || { sed -n '4,15p' "$0" >&2; exit 2; }
+
+root="$(cd "$(dirname "$0")/.." && pwd)"
+out="$1"; shift
+mkdir -p "$out"
+out="$(cd "$out" && pwd)"
+
+# Deterministic 12 s stereo noise clip at 48 kHz (same input for every build).
+clip="$out/clip.wav"
+python3 -I - "$clip" <<'EOF'
+import random, struct, sys, wave
+random.seed(1)
+w = wave.open(sys.argv[1], "wb")
+w.setnchannels(2); w.setsampwidth(2); w.setframerate(48000)
+w.writeframes(b"".join(struct.pack("<hh", random.randint(-8000, 8000), random.randint(-8000, 8000))
+ for _ in range(48000 * 12)))
+w.close()
+EOF
+
+cxx="${CXX:-c++}"
+flags=(-std=c++20 -O2 -I"$root/src/native/nota.engine/include")
+[ "$(uname)" = "Darwin" ] && flags+=(-mmacosx-version-min=13.0)
+
+labels=()
+for spec in "$@"; do
+ label="${spec%%=*}"; dir="${spec#*=}"
+ dir="$(cd "$dir" && pwd)"
+ ls "$dir"/libnota_engine.* >/dev/null 2>&1 || { echo "no libnota_engine in $dir" >&2; exit 1; }
+ "$cxx" "${flags[@]}" "$root/scripts/bench/engine-bench.cpp" -L"$dir" -lnota_engine -Wl,-rpath,"$dir" \
+ -o "$out/engine-bench-$label"
+ labels+=("$label")
+done
+
+scenarios=(
+ "idle"
+ "audio 1 offline" "audio 8 offline" "audio 32 offline"
+ "inst 8 offline" "inst 32 offline"
+ "audio 1 rt" "audio 8 rt" "audio 32 rt"
+ "inst 8 rt" "inst 32 rt"
+ "audio 64 rt 128" "audio 128 rt 64" "audio 192 rt 64"
+)
+
+{
+ echo "date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"
+ echo "os: $(uname -srm)"
+ if [ "$(uname)" = "Darwin" ]; then
+ echo "cpu: $(sysctl -n machdep.cpu.brand_string), $(sysctl -n hw.ncpu) threads"
+ echo "macos: $(sw_vers -productVersion)"
+ else
+ echo "cpu: $(grep -m1 'model name' /proc/cpuinfo | cut -d: -f2- | xargs), $(nproc) threads"
+ fi
+ echo "runs: $runs"
+ for spec in "$@"; do echo "build: $spec"; done
+} > "$out/machine.txt"
+
+csv="$out/results.csv"
+echo "label,run,scenario,tracks,mode,block,cpu_ms_per_s,wall_ms_per_s,cpu_pct,misses" > "$csv"
+for r in $(seq 1 "$runs"); do
+ for s in "${scenarios[@]}"; do
+ for label in "${labels[@]}"; do
+ # shellcheck disable=SC2086 # the scenario is a word list on purpose
+ set -- $s
+ [ "$1" = idle ] || set -- "$1" "$2" "$3" "$clip" "${@:4}" # clip before the optional block
+ row="$("$out/engine-bench-$label" "$@" 2>/dev/null | tail -1)"
+ echo "$label,$r,$row" >> "$csv"
+ echo "run $r $label $row"
+ done
+ done
+done
+echo "==> $csv"
diff --git a/scripts/bench/engine-bench.cpp b/scripts/bench/engine-bench.cpp
new file mode 100644
index 00000000..1b9b0c06
--- /dev/null
+++ b/scripts/bench/engine-bench.cpp
@@ -0,0 +1,132 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Egor Khindikaynen (Nota). See LICENSES/ for license terms.
+//
+// engine-bench — measures one engine scenario through the public C ABI and prints
+// one CSV row. Built and driven by scripts/bench-engine.sh, which links it against
+// each engine build being compared (so it only uses functions every compared build
+// exports — keep it to long-standing ABI).
+//
+// engine-bench idle
+// engine-bench <audio|inst> <tracks> <offline|rt> <clip.wav> [block]
+//
+// idle — engine created, nothing playing: process CPU over 5 s (% of one core).
+// audio — <tracks> audio tracks, each a WAV clip + Reverb.
+// inst — <tracks> instrument tracks (Nota Synth), each a MIDI clip of chords.
+// offline — 10 s rendered back-to-back in <block>-frame blocks (default 512; a bounce).
+// rt — the same blocks paced like a <block> @ 48 kHz device callback, through
+// nota_engine_render_device_block when the build exports it (the callback's
+// own path), else nota_engine_render_offline (builds before it existed).
+//
+// Row: scenario,tracks,mode,block,cpu_ms_per_s,wall_ms_per_s,cpu_pct,misses
+// (per second of audio; misses = rt blocks that took longer than their buffer period;
+// idle reports cpu_pct only).
+
+#include "nota/nota_engine.h"
+
+#include <chrono>
+#include <cstdio>
+#include <cstdlib>
+#include <cstring>
+#include <string>
+#include <thread>
+#include <vector>
+
+#include <dlfcn.h>
+#include <sys/resource.h>
+
+namespace {
+
+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;
+}
+
+int usage() {
+ std::fprintf(stderr, "usage: engine-bench idle | engine-bench <audio|inst> <tracks> <offline|rt> <clip.wav> [block]\n");
+ return 2;
+}
+
+} // namespace
+
+int main(int argc, char** argv) {
+ if (argc < 2) return usage();
+ const std::string scenario = argv[1];
+ using Clock = std::chrono::steady_clock;
+
+ NotaEngine* e = nota_engine_create();
+ if (!e) return 1;
+
+ if (scenario == "idle") {
+ std::this_thread::sleep_for(std::chrono::seconds(1)); // let threads settle
+ const double c0 = processCpuSeconds();
+ const auto t0 = Clock::now();
+ std::this_thread::sleep_for(std::chrono::seconds(5));
+ const double wall = std::chrono::duration<double>(Clock::now() - t0).count();
+ std::printf("idle,0,idle,,,,%.1f,\n", 100.0 * (processCpuSeconds() - c0) / wall);
+ nota_engine_destroy(e);
+ return 0;
+ }
+
+ if (argc < 5) return usage();
+ const int tracks = std::atoi(argv[2]);
+ const std::string mode = argv[3];
+ const char* clip = argv[4];
+ if ((scenario != "audio" && scenario != "inst") || (mode != "offline" && mode != "rt") || tracks <= 0)
+ return usage();
+
+ for (int i = 0; i < tracks; ++i) {
+ if (scenario == "audio") {
+ const int32_t t = nota_engine_add_audio_track(e);
+ nota_track_add_audio_clip(e, t, clip, 0.0);
+ nota_track_add_builtin_device(e, t, 2); // Reverb
+ } else {
+ const int32_t t = nota_engine_add_instrument_track(e);
+ const int32_t c = nota_track_add_midi_clip(e, t, 0.0, 32.0);
+ std::vector<NotaNoteData> notes;
+ for (int beat = 0; beat < 32; ++beat)
+ for (int k : {0, 4, 7}) { // a triad on every beat, root moving with the track
+ NotaNoteData n;
+ std::memset(&n, 0, sizeof n);
+ n.pitch = 48 + (i % 12) + k;
+ n.start_beat = beat;
+ n.length_beats = 0.9;
+ n.velocity = 0.8f;
+ notes.push_back(n);
+ }
+ nota_clip_set_notes(e, t, c, notes.data(), (int32_t)notes.size());
+ }
+ }
+
+ const int block = argc > 5 ? std::atoi(argv[5]) : 512, rate = 48000, seconds = 10;
+ if (block <= 0) return usage();
+ std::vector<float> buf((size_t)block * 2);
+ nota_engine_render_offline_at(e, buf.data(), block, rate); // prepares every node at the rate
+ nota_transport_play(e);
+
+ const bool paced = mode == "rt";
+ using RenderFn = NotaResult (*)(NotaEngine*, float*, int32_t);
+ RenderFn render = nota_engine_render_offline;
+ if (paced)
+ if (void* f = dlsym(RTLD_DEFAULT, "nota_engine_render_device_block")) render = (RenderFn)f;
+ const double periodS = (double)block / rate;
+ int misses = 0;
+ const double c0 = processCpuSeconds();
+ const auto t0 = Clock::now();
+ auto next = t0;
+ for (int f = 0; f < seconds * rate; f += block) {
+ const auto b0 = Clock::now();
+ render(e, buf.data(), block);
+ if (std::chrono::duration<double>(Clock::now() - b0).count() > periodS) ++misses;
+ if (paced) {
+ next += std::chrono::microseconds((int64_t)block * 1000000 / rate);
+ std::this_thread::sleep_until(next);
+ }
+ }
+ const double wall = std::chrono::duration<double>(Clock::now() - t0).count();
+ const double cpu = processCpuSeconds() - c0;
+ std::printf("%s,%d,%s,%d,%.1f,%.1f,%.1f,%d\n", scenario.c_str(), tracks, mode.c_str(), block,
+ 1000.0 * cpu / seconds, 1000.0 * wall / seconds, 100.0 * cpu / wall, paced ? misses : 0);
+ nota_engine_destroy(e);
+ return 0;
+}
diff --git a/src/managed/Nota.Infrastructure/Interop/NativeMethods.cs b/src/managed/Nota.Infrastructure/Interop/NativeMethods.cs
index ca8afae0..c97c13e5 100644
--- a/src/managed/Nota.Infrastructure/Interop/NativeMethods.cs
+++ b/src/managed/Nota.Infrastructure/Interop/NativeMethods.cs
@@ -253,6 +253,9 @@ internal static partial class NativeMethods
[LibraryImport(Lib, EntryPoint = "nota_engine_render_offline")]
internal static partial NotaResult RenderOffline(IntPtr engine, [Out] float[] outBuffer, int frames);
+ [LibraryImport(Lib, EntryPoint = "nota_engine_render_device_block")]
+ internal static partial NotaResult RenderDeviceBlock(IntPtr engine, [Out] float[] outBuffer, int frames);
+
[LibraryImport(Lib, EntryPoint = "nota_engine_render_offline_at")]
internal static partial NotaResult RenderOfflineAt(IntPtr engine, [Out] float[] outBuffer, int frames, double sampleRate);
@@ -288,4 +291,13 @@ internal static partial class NativeMethods
[LibraryImport(Lib, EntryPoint = "nota_engine_cpu_load")]
internal static partial float CpuLoad(IntPtr engine);
+
+ [LibraryImport(Lib, EntryPoint = "nota_engine_set_render_threads")]
+ internal static partial NotaResult SetRenderThreads(IntPtr engine, int count);
+
+ [LibraryImport(Lib, EntryPoint = "nota_engine_render_threads")]
+ internal static partial int RenderThreads(IntPtr engine);
+
+ [LibraryImport(Lib, EntryPoint = "nota_engine_render_threads_cpu_seconds")]
+ internal static partial double RenderThreadsCpuSeconds(IntPtr engine);
}
diff --git a/src/managed/Nota.Infrastructure/Interop/NotaEngine.cs b/src/managed/Nota.Infrastructure/Interop/NotaEngine.cs
index aefc6983..0296d9af 100644
--- a/src/managed/Nota.Infrastructure/Interop/NotaEngine.cs
+++ b/src/managed/Nota.Infrastructure/Interop/NotaEngine.cs
@@ -237,6 +237,16 @@ public sealed partial class NotaEngine : IAudioEngine
Check(NativeMethods.RenderOffline(_handle, outBuffer, frames));
}
+ /// <summary>
+ /// Renders one block the way the audio device callback does (real-time deadline), without
+ /// a device — for tests that pace blocks like a callback. Device must be stopped.
+ /// </summary>
+ public void RenderDeviceBlock(float[] outBuffer, int frames)
+ {
+ ThrowIfDisposed();
+ Check(NativeMethods.RenderDeviceBlock(_handle, outBuffer, frames));
+ }
+
/// <summary>
/// Renders `frames` of interleaved stereo at <paramref name="sampleRate"/> (WAV export, M6-4).
/// Stop the audio backend first — this mutates transport state the audio thread reads.
@@ -298,6 +308,20 @@ public sealed partial class NotaEngine : IAudioEngine
public float CpuLoad
{ get { ThrowIfDisposed(); return NativeMethods.CpuLoad(_handle); } }
+ /// <summary>
+ /// Dedicated parallel render threads (the audio thread helps too). Set while the device
+ /// is stopped: a negative count restores the default, 0 renders on the audio thread alone.
+ /// </summary>
+ public int RenderThreads
+ {
+ get { ThrowIfDisposed(); return NativeMethods.RenderThreads(_handle); }
+ set { ThrowIfDisposed(); Check(NativeMethods.SetRenderThreads(_handle, value)); }
+ }
+
+ /// <summary>CPU time the render threads have used, summed, in seconds (≈ constant while idle).</summary>
+ public double RenderThreadsCpuSeconds
+ { get { ThrowIfDisposed(); return NativeMethods.RenderThreadsCpuSeconds(_handle); } }
+
public void Dispose()
{
if (_handle != IntPtr.Zero)
diff --git a/src/native/nota.engine/CMakeLists.txt b/src/native/nota.engine/CMakeLists.txt
index 9b502f55..beff90d9 100644
--- a/src/native/nota.engine/CMakeLists.txt
+++ b/src/native/nota.engine/CMakeLists.txt
@@ -348,9 +348,9 @@ target_link_libraries(nota_pluginhost
# linking juce_audio_processors would compile a second copy of JUCE (~11k
# duplicate symbols at the nota_engine link). The scanner therefore builds its
# two translation units as part of nota_pluginhost — the single JUCE owner —
-# while keeping its own INTERFACE target, bridge headers, and directory.
+# while keeping its own INTERFACE target and directory.
# Enforcement is by construction, verified by grep (see below):
-# pluginhost/scanner/* includes only bridge/, NotaConfigFile.h and JUCE —
+# pluginhost/scanner/* includes only NotaConfigFile.h and JUCE —
# never Engine.h, Track.h, Graph.h, Device.h or Instrument.h.
# Full CMake STATIC split either keeps this
# model or makes the scanner JUCE-free (stdlib XML + fork/exec).
diff --git a/src/native/nota.engine/cmake/dependencies.cmake b/src/native/nota.engine/cmake/dependencies.cmake
index 784a6ba0..d3393749 100644
--- a/src/native/nota.engine/cmake/dependencies.cmake
+++ b/src/native/nota.engine/cmake/dependencies.cmake
@@ -3,8 +3,10 @@
#
# CMake dependencies via CPM (general infra, not per-library vendoring).
# Nothing here lands in the repo: CPM fetches each package into the build dir
-# (_deps) from a pinned URL + URL_HASH below. To add a dependency, append one
-# CPMAddPackage block and its row in LICENSES/third-party.md.
+# (_deps) — or CPM_SOURCE_CACHE when set (CI caches it) — from a pinned
+# URL + URL_HASH or a commit SHA below (never a movable tag; the release it
+# matches is in the comment). To add a dependency, append one CPMAddPackage
+# block and its row in LICENSES/third-party.md.
CPMAddPackage(
NAME nlohmann_json
@@ -26,7 +28,7 @@ CPMAddPackage(
)
CPMAddPackage(
NAME miniaudio
- GIT_TAG 0.11.25
+ GIT_TAG 9634bedb5b5a2ca38c1ee7108a9358a4e233f14d # 0.11.25
GITHUB_REPOSITORY mackron/miniaudio
DOWNLOAD_ONLY YES
)
@@ -50,7 +52,7 @@ CPMAddPackage(
)
CPMAddPackage(
NAME flac
- GIT_TAG 1.5.0
+ GIT_TAG 1507800de4b70e21be71f38caa0d9079d0bc6e45 # 1.5.0
GITHUB_REPOSITORY xiph/flac
OPTIONS
"WITH_OGG OFF"
@@ -75,7 +77,7 @@ CPMAddPackage(
)
CPMAddPackage(
NAME JUCE
- GIT_TAG 8.0.14
+ GIT_TAG 2cdfca8feb300fb424002ba2c2751569e5bacb64 # 8.0.14
GITHUB_REPOSITORY juce-framework/JUCE
GIT_SHALLOW TRUE
)
diff --git a/src/native/nota.engine/include/nota/nota_engine.h b/src/native/nota.engine/include/nota/nota_engine.h
index ac33451b..ffccec02 100644
--- a/src/native/nota.engine/include/nota/nota_engine.h
+++ b/src/native/nota.engine/include/nota/nota_engine.h
@@ -461,6 +461,16 @@ NOTA_API int32_t nota_engine_automation_overridden(const NotaEngine* engine);
* 0 when no live device is running. */
NOTA_API float nota_engine_cpu_load(const NotaEngine* engine);
+/* ---- Render threads -------------------------------------------------------
+ * Dedicated threads that render tracks in parallel (the audio thread helps too).
+ * set: count < 0 = the default (hardware threads - 1, capped), 0 = render on the audio
+ * thread alone. Only while the audio device is stopped: NOTA_ERR_ALREADY_RUNNING
+ * otherwise. cpu_seconds: CPU time those threads have used, summed (per-thread OS
+ * clocks) - near zero while nothing renders. Diagnostics and performance tests. */
+NOTA_API NotaResult nota_engine_set_render_threads(NotaEngine* engine, int32_t count);
+NOTA_API int32_t nota_engine_render_threads(const NotaEngine* engine);
+NOTA_API double nota_engine_render_threads_cpu_seconds(const NotaEngine* engine);
+
/* ---- Transport (M1) ------------------------------------------------------ */
NOTA_API NotaResult nota_transport_play(NotaEngine* engine);
NOTA_API NotaResult nota_transport_stop(NotaEngine* engine);
@@ -1745,6 +1755,13 @@ NOTA_API NotaResult nota_engine_render_offline(NotaEngine* engine, float* out, i
NOTA_API NotaResult nota_engine_render_offline_at(NotaEngine* engine, float* out,
int32_t frames, double sampleRate);
+/* Renders one block exactly as the audio device callback does (a real-time deadline, not
+ * a bounce: the render threads join only when one thread can't keep up), without a
+ * device. For tests and benchmarks that pace blocks like a callback; call
+ * nota_engine_render_offline_at once first to prepare the nodes at a rate. The device
+ * must be stopped (NOTA_ERR_ALREADY_RUNNING otherwise). */
+NOTA_API NotaResult nota_engine_render_device_block(NotaEngine* engine, float* out, int32_t frames);
+
/* ---- Audio file encoders (export) -----------------------------------------
* Streaming FLAC / MP3 writers behind the same ABI as the offline render above:
* the managed exporter pulls render chunks and streams them through one of
diff --git a/src/native/nota.engine/pluginhost/bridge/PluginCatalogBridge.h b/src/native/nota.engine/pluginhost/bridge/PluginCatalogBridge.h
deleted file mode 100644
index 79445fa9..00000000
--- a/src/native/nota.engine/pluginhost/bridge/PluginCatalogBridge.h
+++ /dev/null
@@ -1,32 +0,0 @@
-// SPDX-License-Identifier: AGPL-3.0-only
-// Copyright (c) 2026 Egor Khindikaynen (Nota). See LICENSES/ for license terms.
-//
-// PluginCatalogBridge — pure C++ (JUCE-free) snapshot view over the plugin
-// catalog . The engine and hosting layer read catalog
-// entries through this struct; only pluginhost/scanner/ touches JUCE types.
-// Lets nota_pluginhost instantiate plugins without depending on Engine/Track.
-
-#pragma once
-
-#include <cstdint>
-#include <string>
-
-namespace nota {
-namespace catalog {
-
-struct PluginEntry {
- std::string identifier; // JUCE "<format>-<name>-<hash>-<uid>" id string
- std::string name;
- std::string format; // "VST3" | "AudioUnit"
- std::string manufacturer;
- std::string category;
- std::string fileOrIdentifier;
- bool isInstrument = false;
-};
-
-// ID fallback: exact match first, then format+name+uid (same plugin at another
-// path — see PluginHost.cpp nota_pluginhost_index_of_id).
-int32_t indexOfId(const PluginEntry* entries, int32_t count, const char* identifier) noexcept;
-
-} // namespace catalog
-} // namespace nota
diff --git a/src/native/nota.engine/pluginhost/hosting/PluginCommon.cpp b/src/native/nota.engine/pluginhost/hosting/PluginCommon.cpp
index b2cc8347..7ee17447 100644
--- a/src/native/nota.engine/pluginhost/hosting/PluginCommon.cpp
+++ b/src/native/nota.engine/pluginhost/hosting/PluginCommon.cpp
@@ -112,28 +112,20 @@ int32_t paramIndexOfIdImpl(juce::AudioPluginInstance* p, const std::string& id)
return -1;
}
-juce::AudioPluginFormatManager& sharedFormatManager() {
- static juce::AudioPluginFormatManager fm;
- static const bool once = [] {
- juce::addDefaultFormatsToManager(fm);
- return true;
- }();
- juce::ignoreUnused(once);
- return fm;
-}
-
std::unique_ptr<juce::AudioPluginInstance> createInstance(
const juce::PluginDescription& desc, double sr, int maxBlock) {
juce::String err;
- return sharedFormatManager().createPluginInstance(desc, sr, maxBlock, err);
+ return scanner::sharedFormatManager().createPluginInstance(desc, sr, maxBlock, err);
}
-std::unique_ptr<juce::AudioPluginInstance> instantiateCatalog(int catalogIndex, double sr, int maxBlock) {
+std::unique_ptr<juce::AudioPluginInstance> instantiateCatalog(
+ int catalogIndex, double sr, int maxBlock, bool instrumentOnly) {
auto& catalog = scanner::PluginCatalog::instance();
catalog.loadOnce();
- auto types = catalog.types();
- if (catalogIndex < 0 || catalogIndex >= static_cast<int>(types.size())) return nullptr;
- return createInstance(*types[static_cast<size_t>(catalogIndex)], sr, maxBlock);
+ juce::PluginDescription desc; // one entry, copied under one lock
+ if (!catalog.typeAt(catalogIndex, desc)) return nullptr;
+ if (instrumentOnly && !desc.isInstrument) return nullptr;
+ return createInstance(desc, sr, maxBlock);
}
} // namespace hosting
diff --git a/src/native/nota.engine/pluginhost/hosting/PluginCommon.h b/src/native/nota.engine/pluginhost/hosting/PluginCommon.h
index 4a733fda..e2b2aa30 100644
--- a/src/native/nota.engine/pluginhost/hosting/PluginCommon.h
+++ b/src/native/nota.engine/pluginhost/hosting/PluginCommon.h
@@ -61,14 +61,14 @@ float paramGetImpl(juce::AudioPluginInstance* p, int32_t i);
void paramSetImpl(juce::AudioPluginInstance* p, int32_t i, float v);
int32_t paramIndexOfIdImpl(juce::AudioPluginInstance* p, const std::string& id);
-// Shared plugin format manager (VST3 everywhere, AU on macOS). Message thread.
-juce::AudioPluginFormatManager& sharedFormatManager();
-
// Instantiate a full description in-process (message thread). Null on failure.
std::unique_ptr<juce::AudioPluginInstance> createInstance(const juce::PluginDescription& desc, double sr, int maxBlock);
-// Instantiate catalog entry `catalogIndex` in-process (message thread).
-std::unique_ptr<juce::AudioPluginInstance> instantiateCatalog(int catalogIndex, double sr, int maxBlock);
+// Instantiate catalog entry `catalogIndex` in-process (message thread). With
+// `instrumentOnly`, an entry that isn't an instrument yields null — checked on the
+// same entry that is instantiated, so a scan landing in between can't swap it.
+std::unique_ptr<juce::AudioPluginInstance> instantiateCatalog(
+ int catalogIndex, double sr, int maxBlock, bool instrumentOnly);
} // namespace hosting
} // namespace nota
diff --git a/src/native/nota.engine/pluginhost/hosting/PluginHost.cpp b/src/native/nota.engine/pluginhost/hosting/PluginHost.cpp
index 209c1f8e..227d1493 100644
--- a/src/native/nota.engine/pluginhost/hosting/PluginHost.cpp
+++ b/src/native/nota.engine/pluginhost/hosting/PluginHost.cpp
@@ -12,7 +12,6 @@
#include "PluginCommon.h"
#include "PluginEffect.h"
#include "PluginInstrument.h"
-#include "scanner/PluginCatalog.h"
#include <juce_audio_processors/juce_audio_processors.h>
#include <juce_gui_basics/juce_gui_basics.h>
@@ -95,18 +94,14 @@ namespace nota {
std::shared_ptr<Instrument> createPluginInstrument(int32_t catalogIndex, double sr, int32_t maxBlock) {
ensureJuceGui();
- auto& catalog = scanner::PluginCatalog::instance();
- catalog.loadOnce();
- catalog::PluginEntry entry;
- if (catalog.entryAt(catalogIndex, entry) && !entry.isInstrument) return nullptr; // not an instrument
- auto inst = hosting::instantiateCatalog(catalogIndex, sr, maxBlock);
+ auto inst = hosting::instantiateCatalog(catalogIndex, sr, maxBlock, /*instrumentOnly*/ true);
if (!inst) return nullptr;
return std::make_shared<hosting::PluginInstrument>(std::move(inst), sr, maxBlock);
}
std::shared_ptr<Device> createPluginEffect(int32_t catalogIndex, double sr, int32_t maxBlock) {
ensureJuceGui();
- auto inst = hosting::instantiateCatalog(catalogIndex, sr, maxBlock);
+ auto inst = hosting::instantiateCatalog(catalogIndex, sr, maxBlock, /*instrumentOnly*/ false);
if (!inst) return nullptr;
return std::make_shared<hosting::PluginEffect>(std::move(inst), sr, maxBlock);
}
diff --git a/src/native/nota.engine/pluginhost/scanner/OutOfProcessScanner.cpp b/src/native/nota.engine/pluginhost/scanner/OutOfProcessScanner.cpp
index b6bac184..5556a974 100644
--- a/src/native/nota.engine/pluginhost/scanner/OutOfProcessScanner.cpp
+++ b/src/native/nota.engine/pluginhost/scanner/OutOfProcessScanner.cpp
@@ -1,9 +1,8 @@
// SPDX-License-Identifier: AGPL-3.0-only
// Copyright (c) 2026 Egor Khindikaynen (Nota). See LICENSES/ for license terms.
//
-// OutOfProcessScanner implementation. Mirrors scanOne() in PluginHost.cpp so
-// the ABI move is behavior-preserving; adds workerAvailable() and a
-// value-semantics ScanResult for the future batched-session mode.
+// OutOfProcessScanner implementation. Mirrors scanOne() in the former
+// PluginHost.cpp so the ABI move is behavior-preserving; adds workerAvailable().
#include "OutOfProcessScanner.h"
@@ -72,22 +71,5 @@ std::vector<std::unique_ptr<juce::PluginDescription>> OutOfProcessScanner::scanD
return out;
}
-void OutOfProcessScanner::scanOne(
- const std::string& formatName, const std::string& fileOrId, std::vector<catalog::PluginEntry>& out) const noexcept {
- try {
- for (auto& desc : scanDescriptions(formatName, fileOrId)) {
- catalog::PluginEntry entry;
- entry.identifier = desc->createIdentifierString().toStdString();
- entry.name = desc->name.toStdString();
- entry.format = desc->pluginFormatName.toStdString();
- entry.manufacturer = desc->manufacturerName.toStdString();
- entry.category = desc->category.toStdString();
- entry.fileOrIdentifier = desc->fileOrIdentifier.toStdString();
- entry.isInstrument = desc->isInstrument;
- out.push_back(std::move(entry));
- }
- } catch (...) { out.clear(); }
-}
-
} // namespace scanner
} // namespace nota
diff --git a/src/native/nota.engine/pluginhost/scanner/OutOfProcessScanner.h b/src/native/nota.engine/pluginhost/scanner/OutOfProcessScanner.h
index 1c602183..5e78b373 100644
--- a/src/native/nota.engine/pluginhost/scanner/OutOfProcessScanner.h
+++ b/src/native/nota.engine/pluginhost/scanner/OutOfProcessScanner.h
@@ -15,8 +15,6 @@
#include <string>
#include <vector>
-#include "bridge/PluginCatalogBridge.h"
-
namespace juce {
class PluginDescription;
} // namespace juce
@@ -24,25 +22,15 @@ class PluginDescription;
namespace nota {
namespace scanner {
-struct ScanResult {
- std::vector<catalog::PluginEntry> found;
- int32_t scanned = 0;
- int32_t failed = 0;
-};
-
class OutOfProcessScanner {
public:
static constexpr int kDefaultTimeoutMs = 30000;
explicit OutOfProcessScanner(std::string workerPath, int timeoutMs = kDefaultTimeoutMs) noexcept;
- // Scan one plugin id (format + fileOrIdentifier) via the worker.
- // Never throws; failures increment result.failed.
- void scanOne(const std::string& formatName, const std::string& fileOrId,
- std::vector<catalog::PluginEntry>& out) const noexcept;
-
- // Lossless variant: full JUCE descriptions (uid, path hash) for catalog
- // storage. Never throws; returns empty on any failure.
+ // Scan one plugin id (format + fileOrIdentifier) via the worker: full JUCE
+ // descriptions (uid, path hash) for catalog storage. Never throws; returns
+ // empty on any failure.
std::vector<std::unique_ptr<juce::PluginDescription>> scanDescriptions(
const std::string& formatName, const std::string& fileOrId) const noexcept;
diff --git a/src/native/nota.engine/pluginhost/scanner/PluginCatalog.cpp b/src/native/nota.engine/pluginhost/scanner/PluginCatalog.cpp
index 06edba94..b80c644c 100644
--- a/src/native/nota.engine/pluginhost/scanner/PluginCatalog.cpp
+++ b/src/native/nota.engine/pluginhost/scanner/PluginCatalog.cpp
@@ -2,8 +2,8 @@
// Copyright (c) 2026 Egor Khindikaynen (Nota). See LICENSES/ for license terms.
//
// PluginCatalog implementation — lossless JUCE KnownPluginList behind a
-// shared_mutex, with a JUCE-free bridge snapshot for readers. Behavior matches
-// pluginhost/PluginHost.cpp (M3-1) exactly; only the locking is new.
+// shared_mutex. Behavior matches pluginhost/PluginHost.cpp (M3-1) exactly;
+// only the locking is new.
#include "PluginCatalog.h"
@@ -18,7 +18,14 @@ namespace scanner {
struct PluginCatalog::Impl {
juce::KnownPluginList list;
+ // list's entries in list order. KnownPluginList only hands out whole-list copies
+ // (getTypes()), so reads index this instead; sync() after every mutation.
+ std::vector<juce::PluginDescription> types;
std::vector<std::string> scanPaths;
+ void sync() {
+ const auto all = list.getTypes();
+ types.assign(all.begin(), all.end());
+ }
};
namespace {
@@ -52,20 +59,18 @@ juce::File scanPathsFile() {
return supportDir().getChildFile("scanpaths.txt");
}
-catalog::PluginEntry toEntry(const juce::PluginDescription& d) {
- catalog::PluginEntry e;
- e.identifier = d.createIdentifierString().toStdString();
- e.name = d.name.toStdString();
- e.format = d.pluginFormatName.toStdString();
- e.manufacturer = d.manufacturerName.toStdString();
- e.category = d.category.toStdString();
- e.fileOrIdentifier = d.fileOrIdentifier.toStdString();
- e.isInstrument = d.isInstrument;
- return e;
-}
-
} // namespace
+juce::AudioPluginFormatManager& sharedFormatManager() {
+ static juce::AudioPluginFormatManager fm;
+ static const bool once = [] {
+ juce::addDefaultFormatsToManager(fm);
+ return true;
+ }();
+ juce::ignoreUnused(once);
+ return fm;
+}
+
PluginCatalog::PluginCatalog() : impl_(std::make_unique<Impl>()) {}
PluginCatalog::~PluginCatalog() = default;
@@ -74,40 +79,26 @@ PluginCatalog& PluginCatalog::instance() {
return inst;
}
-std::vector<catalog::PluginEntry> PluginCatalog::snapshot() const {
- std::shared_lock lock(mutex_);
- std::vector<catalog::PluginEntry> out;
- for (const auto& t : impl_->list.getTypes()) out.push_back(toEntry(t));
- return out;
-}
-
int32_t PluginCatalog::count() const {
std::shared_lock lock(mutex_);
- return impl_->list.getNumTypes();
-}
-
-bool PluginCatalog::entryAt(int32_t index, catalog::PluginEntry& out) const {
- std::shared_lock lock(mutex_);
- const auto types = impl_->list.getTypes();
- if (index < 0 || index >= types.size()) return false;
- out = toEntry(types.getReference(index));
- return true;
+ return static_cast<int32_t>(impl_->types.size());
}
std::string PluginCatalog::idAt(int32_t index) const {
std::shared_lock lock(mutex_);
- const auto types = impl_->list.getTypes();
- if (index < 0 || index >= types.size()) return {};
- return types.getReference(index).createIdentifierString().toStdString();
+ const auto& types = impl_->types;
+ if (index < 0 || index >= static_cast<int32_t>(types.size())) return {};
+ return types[static_cast<size_t>(index)].createIdentifierString().toStdString();
}
int32_t PluginCatalog::indexOfId(const char* identifier) const {
if (identifier == nullptr) return -1;
const juce::String want{juce::CharPointer_UTF8(identifier)};
std::shared_lock lock(mutex_);
- const auto types = impl_->list.getTypes();
- for (int i = 0; i < types.size(); ++i)
- if (types.getReference(i).createIdentifierString() == want) return i;
+ const auto& types = impl_->types;
+ const int n = static_cast<int>(types.size());
+ for (int i = 0; i < n; ++i)
+ if (types[static_cast<size_t>(i)].createIdentifierString() == want) return i;
// Fallback: JUCE ids are "<format>-<name>-<hex path hash>-<hex uid>", so the
// same plugin at another path never matches exactly. Match format + name + uid.
@@ -116,8 +107,8 @@ int32_t PluginCatalog::indexOfId(const char* identifier) const {
if (hashDash <= 0) return -1;
const auto prefix = want.substring(0, hashDash);
const auto uid = want.substring(uidDash + 1);
- for (int i = 0; i < types.size(); ++i) {
- const auto& t = types.getReference(i);
+ for (int i = 0; i < n; ++i) {
+ const auto& t = types[static_cast<size_t>(i)];
if (t.pluginFormatName + "-" + t.name == prefix &&
(juce::String::toHexString(t.uniqueId) == uid || juce::String::toHexString(t.deprecatedUid) == uid))
return i;
@@ -127,9 +118,9 @@ int32_t PluginCatalog::indexOfId(const char* identifier) const {
std::string PluginCatalog::descLine(int32_t index) const {
std::shared_lock lock(mutex_);
- const auto types = impl_->list.getTypes();
- if (index < 0 || index >= types.size()) return {};
- const auto& d = types.getReference(index);
+ const auto& types = impl_->types;
+ if (index < 0 || index >= static_cast<int32_t>(types.size())) return {};
+ const auto& d = types[static_cast<size_t>(index)];
return (d.name + " | " + d.pluginFormatName + " | " + (d.isInstrument ? "inst" : "fx") + " | " +
(d.manufacturerName.isEmpty() ? juce::String("?") : d.manufacturerName) + " | " +
d.category.replaceCharacter('|', '/'))
@@ -145,7 +136,6 @@ void PluginCatalog::addScanPath(const std::string& dir) {
if (dir.empty()) return;
{
std::unique_lock lock(mutex_);
- const juce::String d{juce::CharPointer_UTF8(dir.c_str())};
for (const auto& p : impl_->scanPaths)
if (p == dir) return;
impl_->scanPaths.push_back(dir);
@@ -177,22 +167,16 @@ std::string PluginCatalog::scanPathAt(int32_t index) const {
void PluginCatalog::addType(const juce::PluginDescription& desc) {
std::unique_lock lock(mutex_);
impl_->list.addType(desc);
-}
-
-bool PluginCatalog::hasFileOrIdentifier(const std::string& fileOrId) const {
- const juce::String want{juce::CharPointer_UTF8(fileOrId.c_str())};
- std::shared_lock lock(mutex_);
- for (const auto& t : impl_->list.getTypes())
- if (t.fileOrIdentifier == want) return true;
- return false;
+ impl_->sync();
}
void PluginCatalog::removeMissingVst3OnDisk() {
std::unique_lock lock(mutex_);
juce::Array<juce::PluginDescription> gone;
- for (const auto& t : impl_->list.getTypes())
+ for (const auto& t : impl_->types)
if (t.pluginFormatName == "VST3" && !juce::File(t.fileOrIdentifier).exists()) gone.add(t);
for (const auto& t : gone) impl_->list.removeType(t);
+ if (!gone.isEmpty()) impl_->sync();
}
std::vector<std::string> PluginCatalog::unknownIds(const std::vector<std::string>& discovered) const {
@@ -201,7 +185,7 @@ std::vector<std::string> PluginCatalog::unknownIds(const std::vector<std::string
for (const auto& id : discovered) {
const juce::String want{juce::CharPointer_UTF8(id.c_str())};
bool known = false;
- for (const auto& t : impl_->list.getTypes())
+ for (const auto& t : impl_->types)
if (t.fileOrIdentifier == want) {
known = true;
break;
@@ -211,11 +195,12 @@ std::vector<std::string> PluginCatalog::unknownIds(const std::vector<std::string
return out;
}
-std::vector<std::unique_ptr<juce::PluginDescription>> PluginCatalog::types() const {
+bool PluginCatalog::typeAt(int32_t index, juce::PluginDescription& out) const {
std::shared_lock lock(mutex_);
- std::vector<std::unique_ptr<juce::PluginDescription>> out;
- for (const auto& t : impl_->list.getTypes()) out.push_back(std::make_unique<juce::PluginDescription>(t));
- return out;
+ const auto& types = impl_->types;
+ if (index < 0 || index >= static_cast<int32_t>(types.size())) return false;
+ out = types[static_cast<size_t>(index)];
+ return true;
}
void PluginCatalog::loadOnce() {
@@ -223,6 +208,7 @@ void PluginCatalog::loadOnce() {
if (catalogLoaded_) return;
catalogLoaded_ = true;
if (auto xml = juce::parseXML(catalogFile())) impl_->list.recreateFromXml(*xml);
+ impl_->sync();
}
void PluginCatalog::save() const {
@@ -254,29 +240,4 @@ void PluginCatalog::saveScanPaths() const {
}
} // namespace scanner
-
-namespace catalog {
-
-int32_t indexOfId(const PluginEntry* entries, int32_t count, const char* identifier) noexcept {
- if (entries == nullptr || identifier == nullptr || count <= 0) return -1;
- const std::string want(identifier);
- for (int32_t i = 0; i < count; ++i)
- if (entries[i].identifier == want) return i;
- const auto uidDash = want.rfind('-');
- if (uidDash == std::string::npos || uidDash == 0) return -1;
- const auto hashDash = want.rfind('-', uidDash - 1);
- if (hashDash == std::string::npos || hashDash == 0) return -1;
- const std::string prefix = want.substr(0, hashDash);
- const std::string uid = want.substr(uidDash + 1);
- for (int32_t i = 0; i < count; ++i) {
- if (entries[i].format + "-" + entries[i].name == prefix) {
- if (entries[i].identifier.size() >= uid.size() &&
- entries[i].identifier.compare(entries[i].identifier.size() - uid.size(), uid.size(), uid) == 0)
- return i;
- }
- }
- return -1;
-}
-
-} // namespace catalog
} // namespace nota
diff --git a/src/native/nota.engine/pluginhost/scanner/PluginCatalog.h b/src/native/nota.engine/pluginhost/scanner/PluginCatalog.h
index 40f30d5b..99cb8159 100644
--- a/src/native/nota.engine/pluginhost/scanner/PluginCatalog.h
+++ b/src/native/nota.engine/pluginhost/scanner/PluginCatalog.h
@@ -6,8 +6,8 @@
// (C# Task.Run -> nota_pluginhost_scan) take the unique lock; UI reads
// (count/desc/index_of_id) take the shared lock — no data races, no iterator
// invalidation. Internally keeps full JUCE PluginDescriptions (uid, path hash,
-// category) so persistence is lossless; the JUCE-free bridge snapshot
-// (PluginCatalogBridge.h) is derived on read. Zero dependencies on
+// category) so persistence is lossless, plus an indexed copy rebuilt on every
+// mutation so a read never copies the whole list. Zero dependencies on
// Engine/Track/Graph/Device (AR-5/AR-6 safe: all file I/O runs on
// message/background threads, never the audio thread).
@@ -20,16 +20,18 @@
#include <string>
#include <vector>
-#include "bridge/PluginCatalogBridge.h"
-
namespace juce {
+class AudioPluginFormatManager;
class PluginDescription;
-class KnownPluginList;
} // namespace juce
namespace nota {
namespace scanner {
+// The process's one plugin format manager (VST3 everywhere, AU on macOS), shared by
+// scanning and in-process hosting. Created on first use; thread-safe to obtain.
+juce::AudioPluginFormatManager& sharedFormatManager();
+
class PluginCatalog {
public:
static PluginCatalog& instance();
@@ -37,11 +39,9 @@ class PluginCatalog {
PluginCatalog(const PluginCatalog&) = delete;
PluginCatalog& operator=(const PluginCatalog&) = delete;
- // Read API (shared lock). Snapshots are copied out — safe to hold across
+ // Read API (shared lock). Results are copied out — safe to hold across
// a background scan.
- std::vector<catalog::PluginEntry> snapshot() const;
int32_t count() const;
- bool entryAt(int32_t index, catalog::PluginEntry& out) const;
int32_t indexOfId(const char* identifier) const;
std::string descLine(int32_t index) const;
std::string idAt(int32_t index) const;
@@ -55,13 +55,13 @@ class PluginCatalog {
// Mutation from the scan coordinator (unique lock).
void addType(const juce::PluginDescription& desc);
- bool hasFileOrIdentifier(const std::string& fileOrId) const;
void removeMissingVst3OnDisk();
std::vector<std::string> unknownIds(const std::vector<std::string>& discovered) const;
- // Full JUCE types for in-process instantiation (message thread). Returned
- // by value so the caller never touches the locked list.
- std::vector<std::unique_ptr<juce::PluginDescription>> types() const;
+ // Full JUCE description of entry `index` for in-process instantiation, copied
+ // under one lock so the index and the entry can't drift apart mid-scan. False
+ // when `index` is out of range.
+ bool typeAt(int32_t index, juce::PluginDescription& out) const;
// Persistence (message/background threads only — file I/O, never RT).
void loadOnce();
diff --git a/src/native/nota.engine/pluginhost/scanner/abi_pluginscanner.cpp b/src/native/nota.engine/pluginhost/scanner/abi_pluginscanner.cpp
index d1cdf825..ab6f17d7 100644
--- a/src/native/nota.engine/pluginhost/scanner/abi_pluginscanner.cpp
+++ b/src/native/nota.engine/pluginhost/scanner/abi_pluginscanner.cpp
@@ -24,18 +24,8 @@ namespace {
// AU first (macOS priority), then VST3 — see ARCHITECTURE.md § Plugin hosting.
const char* const kFormatOrder[] = {"AudioUnit", "VST3"};
-juce::AudioPluginFormatManager& formatManager() {
- static juce::AudioPluginFormatManager fm;
- static const bool once = [] {
- juce::addDefaultFormatsToManager(fm);
- return true;
- }();
- juce::ignoreUnused(once);
- return fm;
-}
-
juce::AudioPluginFormat* findFormat(const juce::String& name) {
- for (auto* f : formatManager().getFormats())
+ for (auto* f : nota::scanner::sharedFormatManager().getFormats())
if (f->getName() == name) return f;
return nullptr;
}
diff --git a/src/native/nota.engine/src/abi/nota_engine_core.cpp b/src/native/nota.engine/src/abi/nota_engine_core.cpp
index 04d4f415..2927797e 100644
--- a/src/native/nota.engine/src/abi/nota_engine_core.cpp
+++ b/src/native/nota.engine/src/abi/nota_engine_core.cpp
@@ -131,6 +131,16 @@ int32_t nota_engine_xrun_selftest(NotaEngine* e) {
float nota_engine_cpu_load(const NotaEngine* e) {
return e ? CENG(e)->cpuLoad() : 0.0f;
}
+NotaResult nota_engine_set_render_threads(NotaEngine* e, int32_t count) {
+ if (!e) return NOTA_ERR_INVALID_ARG;
+ return ENG(e)->setRenderThreads(count) ? NOTA_OK : NOTA_ERR_ALREADY_RUNNING;
+}
+int32_t nota_engine_render_threads(const NotaEngine* e) {
+ return e ? CENG(e)->renderThreads() : 0;
+}
+double nota_engine_render_threads_cpu_seconds(const NotaEngine* e) {
+ return e ? CENG(e)->renderThreadsCpuSeconds() : 0.0;
+}
// ---- Transport ------------------------------------------------------------
@@ -430,6 +440,13 @@ NotaResult nota_engine_render_offline(NotaEngine* e, float* out, int32_t frames)
return NOTA_OK;
}
+NotaResult nota_engine_render_device_block(NotaEngine* e, float* out, int32_t frames) {
+ if (!e || !out || frames <= 0) return NOTA_ERR_INVALID_ARG;
+ if (ENG(e)->isRunning()) return NOTA_ERR_ALREADY_RUNNING; // the device renders itself
+ ENG(e)->renderDeviceBlock(out, frames);
+ return NOTA_OK;
+}
+
NotaResult nota_engine_render_offline_at(NotaEngine* e, float* out, int32_t frames, double sr) {
if (!e || !out || frames <= 0 || sr <= 0.0) return NOTA_ERR_INVALID_ARG;
ENG(e)->renderOffline(out, frames, sr);
diff --git a/src/native/nota.engine/src/devices/Device.h b/src/native/nota.engine/src/devices/Device.h
index e0172565..cd5fa566 100644
--- a/src/native/nota.engine/src/devices/Device.h
+++ b/src/native/nota.engine/src/devices/Device.h
@@ -56,6 +56,11 @@ class Device {
// 4=Utility, 6=Amp), or -1 for a hosted plugin. Message thread only.
virtual int32_t builtinKind() const { return -1; }
+ // True when processing this device runs a hosted plugin instance — the device itself,
+ // or one nested in it (a rack's chains). Such a device stays on the audio thread:
+ // plugin instances aren't safe to process from a pool worker. Audio thread safe.
+ virtual bool hostsPlugin() const { return builtinKind() < 0; }
+
// Stable plugin identifier for project save (M7-6c); empty for built-ins.
// Message thread only.
virtual std::string pluginIdentifier() const { return {}; }
diff --git a/src/native/nota.engine/src/devices/Instrument.h b/src/native/nota.engine/src/devices/Instrument.h
index 20e41137..b3c022f9 100644
--- a/src/native/nota.engine/src/devices/Instrument.h
+++ b/src/native/nota.engine/src/devices/Instrument.h
@@ -129,6 +129,11 @@ class Instrument {
// -1 = hosted plugin / unknown. Message thread only.
virtual int32_t kind() const { return -1; }
+ // True when rendering this instrument runs a hosted plugin instance — the instrument
+ // itself, or one nested in it (a rack's chains). Keeps the track off the render pool
+ // (see Device::hostsPlugin). Audio thread safe.
+ virtual bool hostsPlugin() const { return kind() < 0; }
+
// Human-readable name (built-in "Synth"/"Sampler", or the hosted plugin's name).
// Used to label the track. Message thread only.
virtual const char* displayName() const { return "Instrument"; }
diff --git a/src/native/nota.engine/src/devices/racks/RackCore.cpp b/src/native/nota.engine/src/devices/racks/RackCore.cpp
index 42037aba..1ee83412 100644
--- a/src/native/nota.engine/src/devices/racks/RackCore.cpp
+++ b/src/native/nota.engine/src/devices/racks/RackCore.cpp
@@ -37,6 +37,17 @@ void RackCore::forwardTransport(const TransportInfo& ti) {
}
}
+bool RackCore::chainsHostPlugin() const {
+ const RackState* st = live();
+ if (!st) return false;
+ for (const auto& c : st->chains) {
+ if (c.instrument && c.instrument->hostsPlugin()) return true;
+ for (const auto& d : c.devices)
+ if (d && d->hostsPlugin()) return true;
+ }
+ return false;
+}
+
void RackCore::forwardTempo(double beatStart, double spb, bool playing) {
RackState* st = live();
if (!st) return;
diff --git a/src/native/nota.engine/src/devices/racks/RackCore.h b/src/native/nota.engine/src/devices/racks/RackCore.h
index 4af906ee..4b1b40e1 100644
--- a/src/native/nota.engine/src/devices/racks/RackCore.h
+++ b/src/native/nota.engine/src/devices/racks/RackCore.h
@@ -130,6 +130,10 @@ class RackCore {
// without it they ran on their free times inside a rack. Audio thread, once per block.
void forwardTempo(double beatStart, double spb, bool playing);
+ // Whether any chain child (instrument or insert, at any nesting depth) is a hosted
+ // plugin. Walks the live snapshot: reads only. Audio thread safe.
+ bool chainsHostPlugin() const;
+
// Sample rate + max block; forwarded to every child. Message thread.
void setRates(double sr, int32_t maxBlock);
diff --git a/src/native/nota.engine/src/devices/racks/RackDevice.h b/src/native/nota.engine/src/devices/racks/RackDevice.h
index 685a8af1..2c7916f6 100644
--- a/src/native/nota.engine/src/devices/racks/RackDevice.h
+++ b/src/native/nota.engine/src/devices/racks/RackDevice.h
@@ -25,6 +25,7 @@ class RackDevice final : public Device, public RackCore {
public:
int32_t builtinKind() const override { return 5; } // Audio Effect Rack (project compat)
const char* displayName() const override { return "Nota Audio Effect Rack"; }
+ bool hostsPlugin() const override { return chainsHostPlugin(); }
void setSampleRate(double sr, int32_t maxBlock) override { setRates(sr, maxBlock); }
diff --git a/src/native/nota.engine/src/devices/racks/RackInstrument.h b/src/native/nota.engine/src/devices/racks/RackInstrument.h
index 8b9e0ba7..346e89ff 100644
--- a/src/native/nota.engine/src/devices/racks/RackInstrument.h
+++ b/src/native/nota.engine/src/devices/racks/RackInstrument.h
@@ -25,6 +25,7 @@ class RackInstrument : public Instrument, public RackCore {
public:
int32_t kind() const override { return 3; } // built-in Instrument Rack (project compat)
const char* displayName() const override { return "Nota Instrument Rack"; }
+ bool hostsPlugin() const override { return chainsHostPlugin(); } // Drum Rack too
void setSampleRate(double sr) override { setRates(sr, kMaxBlock); }
diff --git a/src/native/nota.engine/src/engine/AudioThreadPool.cpp b/src/native/nota.engine/src/engine/AudioThreadPool.cpp
index 4a3cd26d..f1605321 100644
--- a/src/native/nota.engine/src/engine/AudioThreadPool.cpp
+++ b/src/native/nota.engine/src/engine/AudioThreadPool.cpp
@@ -1,8 +1,8 @@
// SPDX-License-Identifier: AGPL-3.0-only
// Copyright (c) 2026 Egor Khindikaynen (Nota). See LICENSES/ for license terms.
//
-// AudioThreadPool implementation . Thread management,
-// worker spin loop, and scratch sizing live here; dispatch() is a header
+// AudioThreadPool implementation. Thread management and the worker
+// spin-then-park loop live here; dispatch() is a header
// template (type-erased via a non-owning trampoline — no std::function,
// no allocation on the audio path).
@@ -11,11 +11,37 @@
#include "dsp/core/ScopedNoDenormals.h"
#include <algorithm>
+#include <chrono>
+
+#if defined(_WIN32)
+#ifndef WIN32_LEAN_AND_MEAN
+#define WIN32_LEAN_AND_MEAN
+#endif
+#ifndef NOMINMAX
+#define NOMINMAX
+#endif
+#include <windows.h>
+#elif defined(__APPLE__)
+#include <mach/mach.h>
+#include <pthread.h>
+#include <sys/sysctl.h>
+#else
+#include <pthread.h>
+#include <time.h>
+#endif
namespace nota {
int AudioThreadPool::defaultWorkers() {
- const int hw = (int)std::thread::hardware_concurrency();
+ int hw = (int)std::thread::hardware_concurrency();
+#if defined(__APPLE__)
+ // Performance cores only: a job split onto efficiency cores waits for its
+ // slowest part, and the same work costs those cores more CPU time.
+ int perf = 0;
+ size_t size = sizeof perf;
+ if (sysctlbyname("hw.perflevel0.physicalcpu", &perf, &size, nullptr, 0) == 0 && perf > 0)
+ hw = std::min(hw, perf);
+#endif
if (hw <= 2) return 0; // tiny machines: render inline
return std::min(hw - 1, 16); // cap: past this the fork-join overhead wins
}
@@ -23,41 +49,83 @@ int AudioThreadPool::defaultWorkers() {
AudioThreadPool::AudioThreadPool(int workers) {
int w = workers < 0 ? defaultWorkers() : workers;
w = std::clamp(w, 0, 64);
- scratch_.resize((size_t)w + 1); // +1 caller slot
for (int i = 0; i < w; ++i) workers_.emplace_back([this, i] { workerLoop(i); });
}
AudioThreadPool::~AudioThreadPool() {
- stop_.store(true, std::memory_order_relaxed);
- epoch_.fetch_add(1, std::memory_order_release); // wake sleepers so they observe stop_
+ stop_.store(true, std::memory_order_seq_cst);
+ epoch_.fetch_add(1, std::memory_order_seq_cst);
+ wake_.fetch_add(1, std::memory_order_release); // wake parked workers so they observe stop_
+ wake_.notify_all();
for (auto& t : workers_)
if (t.joinable()) t.join();
}
-void AudioThreadPool::reserveScratch(size_t floats) {
- if (floats <= scratchFloats_) return;
- scratchFloats_ = floats;
- for (auto& s : scratch_) s.resize(floats); // message thread only: may allocate
+double AudioThreadPool::workersCpuSeconds() const {
+ double total = 0.0;
+ for (auto& t : const_cast<std::vector<std::thread>&>(workers_)) {
+#if defined(_WIN32)
+ FILETIME created, exited, kernel, user;
+ if (GetThreadTimes((HANDLE)t.native_handle(), &created, &exited, &kernel, &user)) {
+ auto ticks = [](const FILETIME& f) { return ((uint64_t)f.dwHighDateTime << 32) | f.dwLowDateTime; };
+ total += (double)(ticks(kernel) + ticks(user)) * 1e-7; // 100 ns units
+ }
+#elif defined(__APPLE__)
+ const mach_port_t port = pthread_mach_thread_np(t.native_handle());
+ thread_basic_info_data_t info;
+ mach_msg_type_number_t count = THREAD_BASIC_INFO_COUNT;
+ if (thread_info(port, THREAD_BASIC_INFO, (thread_info_t)&info, &count) == KERN_SUCCESS)
+ total += info.user_time.seconds + info.user_time.microseconds * 1e-6 + info.system_time.seconds +
+ info.system_time.microseconds * 1e-6;
+#else
+ clockid_t clock;
+ timespec ts{};
+ if (pthread_getcpuclockid(t.native_handle(), &clock) == 0 && clock_gettime(clock, &ts) == 0)
+ total += ts.tv_sec + ts.tv_nsec * 1e-9;
+#endif
+ }
+ return total;
+}
+
+// Block until wake_ moves, unless a job (or stop) arrived since `seen`.
+void AudioThreadPool::park(uint64_t seen) {
+ const uint32_t w = wake_.load(std::memory_order_acquire);
+ sleepers_.fetch_add(1, std::memory_order_seq_cst);
+ if (epoch_.load(std::memory_order_seq_cst) == seen && !stop_.load(std::memory_order_seq_cst))
+ wake_.wait(w, std::memory_order_acquire);
+ sleepers_.fetch_sub(1, std::memory_order_relaxed);
}
void AudioThreadPool::workerLoop(int id) {
+ // Pause-spins before parking, plus the linger dispatch() picked from the
+ // gap between jobs. With a live device the next job is a buffer period
+ // away, and a fixed longer spin (measured: 20, 50, 100 us) only burned CPU
+ // there; offline renders get the linger instead.
+ using Clock = std::chrono::steady_clock;
+ constexpr int kSpinPauses = 64;
dsp::ScopedNoDenormals ftz; // whole thread lifetime: FTZ + DAZ
uint64_t seen = 0;
int spins = 0;
+ Clock::time_point idleSince{};
for (;;) {
const uint64_t e = epoch_.load(std::memory_order_acquire);
- if (e == seen) { // parked: brief pause-spin, then yield (no mutex, no block)
- if (++spins < 256) {
+ if (e == seen) { // idle: brief pause-spin, then park on the futex word
+ if (stop_.load(std::memory_order_relaxed)) return;
+ if (spins < kSpinPauses) {
+ if (++spins == kSpinPauses) idleSince = Clock::now();
NOTA_CPU_PAUSE();
- } else {
- std::this_thread::yield();
- spins = 0;
+ continue;
}
- if (stop_.load(std::memory_order_relaxed)) return;
+ if (const int64_t ns = lingerNs_.load(std::memory_order_relaxed);
+ ns > 0 && Clock::now() - idleSince < std::chrono::nanoseconds(ns)) {
+ NOTA_CPU_PAUSE();
+ continue;
+ }
+ park(seen);
+ spins = 0;
continue;
}
seen = e;
- spins = 0;
if (stop_.load(std::memory_order_relaxed)) return;
// Same check-then-CAS claim loop as the caller (see header
// comment): overshoot probes never consume, so a lagging probe
@@ -74,9 +142,10 @@ void AudioThreadPool::workerLoop(int id) {
uint64_t expect = t;
if (claimed_.compare_exchange_weak(expect, t + 1, std::memory_order_relaxed)) {
s.call(s.ctx, id, (int)(t - s.base));
- done_.fetch_add(1, std::memory_order_relaxed);
+ done_.fetch_add(1, std::memory_order_release); // publishes this task's writes
}
}
+ spins = 0;
}
}
diff --git a/src/native/nota.engine/src/engine/AudioThreadPool.h b/src/native/nota.engine/src/engine/AudioThreadPool.h
index 1adddf4e..bd5c1426 100644
--- a/src/native/nota.engine/src/engine/AudioThreadPool.h
+++ b/src/native/nota.engine/src/engine/AudioThreadPool.h
@@ -5,10 +5,11 @@
// render passes . The audio thread publishes a job (count +
// type-erased callable, no allocation) by bumping a generation counter;
// dedicated workers plus the calling thread itself claim tickets from a
-// shared monotonic counter. Workers spin (pause hint, then yield — never
-// block on a mutex), hold FTZ/DAZ for their whole lifetime, and own
-// pre-allocated scratch buffers sized once on the message thread (AR-6: the
-// audio path never allocates, locks, or blocks).
+// shared monotonic counter. Workers spin briefly after each job (pause
+// hint), then park on a futex word (std::atomic::wait) so an idle engine
+// costs no CPU; they hold FTZ/DAZ for their whole lifetime (AR-6: the
+// audio path never allocates, locks, or blocks — waking parked workers is a
+// non-blocking futex notify, skipped while none are parked).
//
// Race discipline (three measured crash/hang bugs killed two earlier
// designs — fetch_add claim + counter resets, then fetch_add + monotonic
@@ -31,12 +32,20 @@
// - job descriptors live in generation-indexed slots; a publish writes its
// slot before the epoch bump (release) and is gated on the previous
// job's completion, so a live ticket's slot is stable while held.
+// - parking is Dekker-style (all seq_cst): a worker bumps sleepers_, then
+// re-checks epoch_ before waiting on wake_; dispatch() stores epoch_,
+// then reads sleepers_. Either the worker sees the new epoch or the
+// dispatcher sees the sleeper and bumps wake_, so no wake-up is lost.
+// Even a missed wake could never hang: the caller claims every ticket
+// nobody else took.
#pragma once
#include "dsp/core/RtAttributes.h"
+#include <algorithm>
#include <atomic>
+#include <chrono>
#include <cstddef>
#include <cstdint>
#include <thread>
@@ -47,7 +56,8 @@ namespace nota {
class AudioThreadPool {
public:
// Dedicated worker threads (the caller always helps as an extra worker).
- // <= 0 selects a default (hardware threads minus one for the caller).
+ // < 0 selects a default (hardware threads minus one for the caller); 0 runs
+ // every job on the caller alone.
explicit AudioThreadPool(int workers = -1);
~AudioThreadPool();
@@ -59,26 +69,44 @@ class AudioThreadPool {
// Dedicated threads (excludes the caller-helper slot).
int workerCount() const noexcept { return (int)workers_.size(); }
- // Scratch management. Message thread only: grows each worker's buffer
- // (plus one caller slot) to at least `floats` floats.
- void reserveScratch(size_t floats);
- size_t scratchCapacity() const noexcept { return scratchFloats_; }
+ // Caller thread: whether the next job follows the previous one back-to-back
+ // (an offline render: no deadline, finish fast) rather than a buffer period
+ // later (a device callback: finish in time, spend little CPU).
+ bool backToBack() const noexcept {
+ return std::chrono::steady_clock::now() - lastEnd_ < std::chrono::nanoseconds(kLingerGapNs);
+ }
- // Worker-private scratch. Audio thread safe (no allocation, no locks).
- // id in [0, workerCount()], where workerCount() is the CALLER slot.
- // Caller must have reserved enough via reserveScratch().
- float* workerScratchBuffer(int worker) NOTA_RT_SAFE { return scratch_[(size_t)worker].data(); }
- const float* workerScratchBuffer(int worker) const NOTA_RT_SAFE { return scratch_[(size_t)worker].data(); }
+ // CPU time the dedicated workers have used since they started, summed, in
+ // seconds (per-thread OS clocks: unaffected by other threads in the process).
+ // Any thread. Lets tests tell parked workers (~0) from spinning ones.
+ double workersCpuSeconds() const;
// Run fn(workerId, index) for index in [0, n). The caller participates
// with worker id == workerCount(). Returns when all n are done.
// fn must not throw, allocate, lock, or block (audio thread).
- template <typename F> void dispatch(int n, F&& fn) {
+ // helpers: how many parked workers to wake (< 0 = as many as useful, 0 =
+ // none: the caller runs the job alone, joined only by workers that are
+ // still spinning from the previous job). Each wake costs the woken thread
+ // a context switch, so wake only as many as the job's work pays for.
+ template <typename F> void dispatch(int n, F&& fn, int helpers = -1) {
if (n <= 0) return;
if (workers_.empty()) {
for (int i = 0; i < n; ++i) fn(workerCount(), i);
return;
}
+ // Linger: how long idle workers keep spinning before they park, from the gap
+ // since the previous job ended. A device callback dispatches a buffer period
+ // apart (ms): park at once, spinning would only burn CPU. An offline render
+ // (export, freeze) dispatches back-to-back (us): a parked worker's wake-up
+ // would cost more than the spin, so linger about twice the gap.
+ // A job that wakes no one (helpers == 0) lets no one linger either: workers
+ // that keep spinning would take its tickets anyway.
+ {
+ const auto now = std::chrono::steady_clock::now();
+ const int64_t gapNs = std::chrono::duration_cast<std::chrono::nanoseconds>(now - lastEnd_).count();
+ lingerNs_.store(helpers != 0 && gapNs < kLingerGapNs ? std::min<int64_t>(2 * gapNs, kMaxLingerNs) : 0,
+ std::memory_order_relaxed);
+ }
// Publish into this generation's slot BEFORE the bump (release):
// workers observe the slot through the epoch's acquire chain.
const uint64_t g = epoch_.load(std::memory_order_relaxed) + 1;
@@ -88,7 +116,21 @@ class AudioThreadPool {
s.n = n;
s.base = claimed_.load(std::memory_order_relaxed);
doneBase_ = done_.load(std::memory_order_relaxed);
- epoch_.store(g, std::memory_order_release); // publish: workers wake
+ epoch_.store(g, std::memory_order_seq_cst); // publish (seq_cst: pairs with park())
+ // Wake parked workers — at most `helpers`, and never more than there are
+ // tickets beyond the one the caller takes itself. Workers left parked stay
+ // asleep (their wait sees the bumped word only when a later notify reaches
+ // them, and then the epoch tells them what is live).
+ if (n > 1 && helpers != 0) {
+ if (const int asleep = sleepers_.load(std::memory_order_seq_cst); asleep > 0) {
+ const int want = std::min(helpers < 0 ? workerCount() : helpers, n - 1);
+ wake_.fetch_add(1, std::memory_order_release);
+ if (want >= asleep)
+ wake_.notify_all(); // one non-blocking futex wake for everyone
+ else
+ for (int i = 0; i < want; ++i) wake_.notify_one();
+ }
+ }
// Claim loop: validate against the live slot, claim by CAS, run.
// The caller needs no stop checks (single audio thread: no
// concurrent publish can invalidate its own job mid-flight).
@@ -103,15 +145,20 @@ class AudioThreadPool {
}
if (claimed_.compare_exchange_weak(t, t + 1, std::memory_order_relaxed)) {
fn(self, (int)(t - ls.base));
- done_.fetch_add(1, std::memory_order_relaxed);
+ done_.fetch_add(1, std::memory_order_release); // publishes this task's writes
}
}
+ // Acquire pairs with every task's release increment (a release sequence through
+ // the RMWs), so all workers' buffer writes are visible once the count is reached.
const uint64_t need = doneBase_ + (uint64_t)n;
while (done_.load(std::memory_order_acquire) < need) NOTA_CPU_PAUSE();
+ lastEnd_ = std::chrono::steady_clock::now();
}
private:
static constexpr uint64_t kSlots = 8;
+ static constexpr int64_t kLingerGapNs = 200'000; // gaps below this count as back-to-back
+ static constexpr int64_t kMaxLingerNs = 100'000;
template <typename F> static void callTrampoline(void* ctx, int worker, int index) {
(*static_cast<F*>(ctx))(worker, index);
@@ -126,18 +173,21 @@ class AudioThreadPool {
};
void workerLoop(int id);
+ void park(uint64_t seen);
std::vector<std::thread> workers_;
- std::vector<std::vector<float>> scratch_; // [workerCount()+1], message-thread sized
- size_t scratchFloats_ = 0;
NOTA_CACHE_ALIGNED std::atomic<uint64_t> epoch_{0};
NOTA_CACHE_ALIGNED std::atomic<uint64_t> claimed_{0};
NOTA_CACHE_ALIGNED std::atomic<uint64_t> done_{0};
std::atomic<bool> stop_{false};
+ NOTA_CACHE_ALIGNED std::atomic<int> sleepers_{0}; // workers inside park()
+ std::atomic<uint32_t> wake_{0}; // futex word (native 32-bit wait everywhere)
+ std::atomic<int64_t> lingerNs_{0}; // set per dispatch (see dispatch())
JobSlot slots_[kSlots]; // gen-indexed descriptors (see header comment)
uint64_t doneBase_ = 0; // caller-thread only (single audio thread)
+ std::chrono::steady_clock::time_point lastEnd_{}; // caller-thread only: previous job's end
};
} // namespace nota
diff --git a/src/native/nota.engine/src/engine/Engine.cpp b/src/native/nota.engine/src/engine/Engine.cpp
index a52edd0c..b1d243bb 100644
--- a/src/native/nota.engine/src/engine/Engine.cpp
+++ b/src/native/nota.engine/src/engine/Engine.cpp
@@ -22,7 +22,6 @@ Engine::Engine()
authoring_->masterTrack = std::make_shared<Track>(kMasterTrackId, TrackType::Audio);
scratch_.assign(kMaxBlock * 2, 0.0f);
mixTmp_.assign(kMaxBlock * 2, 0.0f);
- pool_.reserveScratch((size_t)kMaxBlock * 4); // two halves per worker (dry + post)
monitorHwBuf_.assign(kMaxBlock * 2, 0.0f);
clipEnvScratch_.assign(kMaxBlock * 2, 0.0f);
for (auto& b : returnBus_) b.assign(kMaxBlock * 2, 0.0f); // M6-1 send buses
@@ -32,6 +31,7 @@ Engine::Engine()
for (auto& b : routeBusPre_) b.assign(kMaxBlock * 2, 0.0f); // Phase D pre-FX tap
for (auto& b : routeBusPreNext_) b.assign(kMaxBlock * 2, 0.0f);
for (auto& s : routeSlotTrackId_) s.store(-1, std::memory_order_relaxed);
+ ensureRenderScratch(authoring_->tracks.size());
liveGraph_.store(authoring_.get(), std::memory_order_release);
retired_.push_back(authoring_);
installRackPluginFactory(); // lets rack blobs rebuild hosted-plugin children on load
@@ -86,9 +86,7 @@ void Engine::propagateSampleRate(double sr) {
for (auto& t : authoring_->tracks)
if (t) rate(*t);
if (authoring_->masterTrack) rate(*authoring_->masterTrack);
- if (authoring_) ensureMidiScratch(authoring_->tracks.size());
- if (authoring_) ensureTrackScratch(authoring_->tracks.size());
- for (auto& det : stageSilence_) det.setSampleRate(sr);
+ if (authoring_) ensureRenderScratch(authoring_->tracks.size());
preparedSR_ = sr; // the offline render re-prepares only when this changes
}
@@ -578,29 +576,29 @@ std::shared_ptr<Track> Engine::cloneTrack(const Track& t) const {
return nt;
}
-// Message thread: pre-size the per-track MIDI pre-pass scratch so the audio
-// thread never resizes (AR-6). Runs inside publishRaw (before the live-graph
-// swap, sized for the incoming graph) and propagateSampleRate.
-void Engine::ensureMidiScratch(size_t tracks) {
- if (blockMidi_.size() < tracks) blockMidi_.resize(tracks);
- if (blockMidiN_.size() < tracks) blockMidiN_.resize(tracks, 0);
- if (blockExpr_.size() < tracks) blockExpr_.resize(tracks);
- if (blockExprN_.size() < tracks) blockExprN_.resize(tracks, 0);
- for (size_t i = 0; i < tracks; ++i) {
- if (blockMidi_[i].size() < 1024) blockMidi_[i].resize(1024);
- if (blockExpr_[i].size() < static_cast<size_t>(kMaxBlockExpr)) blockExpr_[i].resize(kMaxBlockExpr);
- }
-}
-
-// Message thread: size per-track Pass 1 scratch + pool scratch (AR-6: the
-// audio thread never grows these).
-void Engine::ensureTrackScratch(size_t tracks) {
- if (leafWork_.size() < tracks) leafWork_.resize(tracks);
- // Two halves (dry + post) of kMaxBlock stereo frames per track.
- const size_t need = tracks * (size_t)kMaxBlock * 4;
- if (leafBuf_.size() < need) leafBuf_.assign(need, 0.0f);
- pool_.reserveScratch((size_t)kMaxBlock * 4); // retained for future parallel passes
- if (mixTmp_.size() < (size_t)kMaxBlock * 2) mixTmp_.assign((size_t)kMaxBlock * 2, 0.0f);
+// Message thread: make sure the published render scratch holds `tracks` tracks. Never
+// grows the live one (the audio thread may be inside a block using it): builds a new one
+// with headroom and publishes it. Runs inside publishRaw (before the live-graph swap, so a
+// block that sees the new graph sees its scratch too) and propagateSampleRate.
+void Engine::ensureRenderScratch(size_t tracks) {
+ if (const RenderScratch* cur = scratchHist_.live(); cur && cur->tracks >= tracks) return;
+ const size_t cap = std::max<size_t>(8, (tracks + 7) / 8 * 8); // grow in steps of 8 tracks
+ auto s = std::make_shared<RenderScratch>();
+ s->tracks = cap;
+ s->leafWork.resize(cap);
+ s->leafBuf.assign(cap * (size_t)kMaxBlock * 4, 0.0f); // two halves (dry + post) per track
+ s->blockMidi.assign(cap, std::vector<MidiEv>(1024));
+ s->blockMidiN.assign(cap, 0);
+ s->blockExpr.assign(cap, std::vector<ExprEv>(kMaxBlockExpr));
+ s->blockExprN.assign(cap, 0);
+ s->parIdx.assign(cap, 0);
+ scratchHist_.publish(std::move(s));
+}
+
+bool Engine::setRenderThreads(int n) {
+ if (isRunning()) return false; // the audio thread may be inside dispatch()
+ pool_ = std::make_unique<AudioThreadPool>(n < 0 ? -1 : n);
+ return true;
}
void Engine::publishRaw(std::shared_ptr<Graph> g) {
@@ -610,8 +608,7 @@ void Engine::publishRaw(std::shared_ptr<Graph> g) {
if (static_cast<int32_t>(t->sessionSlots.size()) < g->sceneCount) t->sessionSlots.resize(g->sceneCount);
authoring_ = g;
retired_.push_back(g);
- if (g) ensureMidiScratch(g->tracks.size());
- if (g) ensureTrackScratch(g->tracks.size());
+ if (g) ensureRenderScratch(g->tracks.size());
liveGraph_.store(g.get(), std::memory_order_release);
recomputeRouting(); // Phase B: refresh sidechain source-track → route-slot table
updateMonitorInput(); // a monitoring track may have come or gone (undo, delete, load)
diff --git a/src/native/nota.engine/src/engine/Engine.h b/src/native/nota.engine/src/engine/Engine.h
index 2bbb5915..fa84cccf 100644
--- a/src/native/nota.engine/src/engine/Engine.h
+++ b/src/native/nota.engine/src/engine/Engine.h
@@ -15,8 +15,8 @@
#include "audio_io/AudioConfig.h"
#include "audio_io/AudioInput.h"
#include "CommandQueue.h"
-#include "dsp/core/SilenceDetector.h"
#include "engine/AudioThreadPool.h"
+#include "engine/SnapshotHistory.h"
#include "EngineTypes.h" // queue payloads, undo model, control events (from this header)
#include "Graph.h"
#include "audio_io/MidiConfig.h"
@@ -55,6 +55,8 @@ class Engine {
void stop();
double sampleRate() const { return backend_ ? backend_->sampleRate() : 0.0; }
bool isRunning() const { return backend_ && backend_->isRunning(); }
+ // One block through the device callback's path, without a device (tests/benchmarks).
+ void renderDeviceBlock(float* out, int32_t frames) { render(out, frames); }
// --- audio device settings (M7-1) ---
// The chosen device/rate/buffer live in config_ (persisted to audio.json)
@@ -131,6 +133,11 @@ class Engine {
// --- DSP load (Phase 11): RT render time / block budget, smoothed 0..1 ---
float cpuLoad() const { return cpuLoad_.load(std::memory_order_relaxed); }
+ // Parallel render threads (the audio thread helps too): n < 0 = default, 0 = none.
+ // Device stopped only (message thread); false while it runs.
+ bool setRenderThreads(int n);
+ int renderThreads() const { return pool_->workerCount(); }
+ double renderThreadsCpuSeconds() const { return pool_->workersCpuSeconds(); }
// --- parameter automation (M9) ---
// Device-free: interpolation + block-rate apply write the target atomic.
@@ -1107,10 +1114,10 @@ class Engine {
// A track's own post-MIDI-FX events (gather + drum swing + its MIDI FX chain), run once.
int computeInstrumentMidi(Track& t, MidiEv* evs, int32_t frames, double blockStart, double spb, bool playing,
bool arrangementActive, ExprEv* xev = nullptr, int* xn = nullptr);
- // Pre-pass: fill blockMidi_/blockMidiN_ for every non-session instrument track.
+ // Pre-pass: fill rs_->blockMidi/blockMidiN for every non-session instrument track.
void computeBlockMidi(
Graph* g, int32_t frames, double blockStart, double spb, bool playing, bool arrangementActive);
- // Hand a MIDI-keyed device its source track's notes for this block (from blockMidi_).
+ // Hand a MIDI-keyed device its source track's notes for this block (from rs_->blockMidi).
void feedMidiKey(Graph* g, Device& d, int32_t srcTrackId);
void renderSessionSlotRaw(Track& t, float* dst, int32_t frames, double spb);
// Session P0 (audio thread): queue a follow action / Repeat retrigger before the launch
@@ -1173,7 +1180,6 @@ class Engine {
std::shared_ptr<SampleBuffer> findSampleById(int64_t sampleId) const; // M7-6b
void publish(std::shared_ptr<Graph> g); // checkpoints (undo), then publishRaw
void publishRaw(std::shared_ptr<Graph> g); // swap live/authoring only, no undo entry
- void ensureMidiScratch(size_t tracks); // message thread: pre-size blockMidi_/blockExpr_ (AR-6)
void configureClipWarp(AudioClip& c, double spb, double devSR); // build the clip's warp cache (unless deferred)
const AudioClip* warpBuildTargetClip() const; // in-progress build target, revalidated (null = abandon)
void reconfigureAllWarpStreams(); // rebuild warp caches for the current tempo + device SR
@@ -1621,8 +1627,7 @@ class Engine {
double captureNow_ = 0.0; // capture clock at this block's start (drainLiveMidi)
void publishHeldSnapshot(double nowBeat);
- // Clip-note expression replayed per block (computeBlockMidi fills, the render pass merges),
- // per track position like blockMidi_.
+ // Clip-note expression replayed per block: capacity of each RenderScratch::blockExpr row.
static constexpr int kMaxBlockExpr = 1024;
// A clip's controller curves on the playback wire for one block (specs/020): the value at the
// clip's start or at a jump into it (chase), every point inside the block, and a value every
@@ -1633,8 +1638,6 @@ class Engine {
// held by a clip that is over.
static void clipCtlEndResets(const MidiClip& clip, double clipStartS, double clipEndS, double blockStart,
int32_t frames, ExprEv* out, int& n, int cap);
- std::vector<std::vector<ExprEv>> blockExpr_;
- std::vector<int> blockExprN_;
// Appends a clip note's recorded expression for the block: the note sounds over
// [onS, offS) in samples relative to the block start; one value per dim at the note's
// start (or the block's) and then every kExprStep samples while its curve moves.
@@ -1738,21 +1741,62 @@ class Engine {
bool eligible = false; // parallel DSP (built-ins only, no shared writers)
LeafPath path = LeafPath::Skip;
int wid = -1; // pool worker that rendered this track (diagnostic)
+ int64_t workNs = 0; // time its parallel DSP took (sizes the next block's helpers)
float* dest = nullptr; // group bus or master out (stable during block)
float* route = nullptr; // post-fader route tap or nullptr
float sends[kMaxReturns] = {};
bool anySend = false;
bool tapRec = false;
};
- std::vector<LeafWork> leafWork_;
- // Per-track Pass 1 render storage (two halves per track: dry pre-device
- // + post; message-thread sized). NOTE: pool worker slots can NOT back
- // per-track renders — tracks outnumber workers, so a shared slot would
- // hold only the last writer's signal (measured cross-talk). Each task
- // owns leafBuf_ + li*stride exclusively for the block.
- std::vector<float> leafBuf_;
- float* leafBase(size_t li, size_t stride) { return leafBuf_.data() + li * stride * 2; }
- void ensureTrackScratch(size_t tracks); // message thread: leafWork_ + pool scratch (AR-6)
+ // Per-block render scratch, by position in the live graph's track list: Pass 1 leaf
+ // work + render storage and the MIDI/expression pre-pass buffers. The audio thread
+ // fills and reads it during a block, so it is never resized in place (growing the
+ // vectors under a block in flight freed the memory the audio thread and pool workers
+ // were writing): the message thread builds a bigger one and publishes it through
+ // scratchHist_ before the graph that needs it, and the old one is freed once no
+ // render can still hold it (AR-6).
+ struct RenderScratch {
+ size_t tracks = 0; // capacity in tracks (every vector below is sized for it)
+ std::vector<LeafWork> leafWork;
+ // Pass 1 render storage (two halves per track: dry pre-device + post).
+ // NOTE: pool worker slots can NOT back per-track renders — tracks outnumber
+ // workers, so a shared slot would hold only the last writer's signal (measured
+ // cross-talk). Each task owns leafBase(li) exclusively for the block.
+ std::vector<float> leafBuf;
+ // Per-block MIDI output of each instrument track (post its own MIDI FX). Filled
+ // once per block by computeBlockMidi; the render pass feeds each instrument its
+ // own buffer plus the buffers of any tracks routing MIDI to it, so a source's
+ // MIDI FX (arp) drive the destination too.
+ std::vector<std::vector<MidiEv>> blockMidi;
+ std::vector<int> blockMidiN;
+ // Clip-note expression replayed per block (computeBlockMidi fills, the render pass
+ // merges).
+ std::vector<std::vector<ExprEv>> blockExpr;
+ std::vector<int> blockExprN;
+ // Pass 1: indices of the leaves rendered on the pool this block (dispatched alone,
+ // so the job's ticket count is its real work).
+ std::vector<int> parIdx;
+ };
+ // Pass 1 with a device (audio thread state). Measured: spreading a block that fits the
+ // buffer over parked render threads costs 2-3x the CPU (cores wake from idle at low
+ // clocks) and misses MORE deadlines (waking takes a good part of a short buffer). So
+ // the pool joins only under sustained overload: when leafWorkNs_ — the single-thread
+ // cost of the parallel leaves, measured on blocks this thread renders alone, smoothed
+ // by 1/16 so a few slow blocks don't count — passes the buffer period. It leaves after
+ // kRtHoldSeconds and this thread re-measures alone: while the pool runs, a block this
+ // thread renders alone reads 1.5-2x its real cost (its core runs cold, the DSP state
+ // sits in other cores' caches), so it can't tell when the overload is over. A real
+ // overload brings it back within a few blocks.
+ int64_t leafWorkNs_ = 0;
+ bool deviceBlock_ = false; // render() (a device callback) vs renderOffline()
+ bool rtParallel_ = false;
+ double rtParallelLeftNs_ = 0;
+ static constexpr double kRtSizeLoad = 0.85; // helpers: finish within this much of the buffer
+ static constexpr double kRtHoldSeconds = 2.0;
+ SnapshotHistory<RenderScratch> scratchHist_;
+ RenderScratch* rs_ = nullptr; // audio thread: this block's scratch (set in processBlock)
+ float* leafBase(size_t li, size_t stride) { return rs_->leafBuf.data() + li * stride * 2; }
+ void ensureRenderScratch(size_t tracks); // message thread: publish scratch for `tracks` (AR-6)
// Per-leaf DSP (Pass 1 steps 1/2/2b): render dry + device chain + PDC.
// Split in two so the serial accumulate can tap the pre-device signal
// (Phase D) while the fader reads the post-device one: parallel tasks
@@ -1766,15 +1810,9 @@ class Engine {
double spb, bool playing, const TransportInfo& ti);
// Fork-join pool for parallel Pass 1 leaf renders (constructed on the
// message thread; workers park when idle).
- AudioThreadPool pool_;
- // Stage silence propagation : hysteresis detectors over each
- // stage's output bus + sticky flags. Consumers: PDC structural skips
- // and instrument playEvents skips read device-level idle state; device
- // process() calls are never engine-skipped (free-running LFO/mod
- // phases would jump — each device's own skip advances them instead).
- enum StageIdx : uint8_t { ST_LEAF = 0, ST_GROUP, ST_RETURN, ST_MASTER };
- dsp::SilenceDetector stageSilence_[4];
- bool stageSilent_[4] = {true, true, true, true};
+ // Replaced only while the device is stopped (setRenderThreads), so the audio
+ // thread never sees it change.
+ std::unique_ptr<AudioThreadPool> pool_ = std::make_unique<AudioThreadPool>();
// Freeze capture (M7): while armed, mixGraph stashes the target track's post-device
// pre-fader signal into freezeCaptureBuf_. Filled sequentially from a seek(0) render;
// only touched on the render thread, which is the message thread while capturing (the
@@ -1784,12 +1822,6 @@ class Engine {
int64_t freezeCapFrames_ = 0; // capacity in frames
int64_t freezeCursor_ = 0; // frames written so far
double freezeCaptureSpb_ = 0.0; // samples-per-beat at capture
- // Per-block MIDI output of each instrument track (post its own MIDI FX), keyed by
- // position in the live graph's track list. Filled once per block by computeBlockMidi;
- // the render pass feeds each instrument its own buffer plus the buffers of any tracks
- // routing MIDI to it, so a source's MIDI FX (arp) drive the destination too.
- std::vector<std::vector<MidiEv>> blockMidi_;
- std::vector<int> blockMidiN_;
// Sample rate every node was last prepared at (propagateSampleRate). The offline render
// re-prepares only when it changes, so a chunked export doesn't reset DSP state per block.
double preparedSR_ = 0.0;
diff --git a/src/native/nota.engine/src/engine/Engine_Render.cpp b/src/native/nota.engine/src/engine/Engine_Render.cpp
index 53559c13..0cc6f10c 100644
--- a/src/native/nota.engine/src/engine/Engine_Render.cpp
+++ b/src/native/nota.engine/src/engine/Engine_Render.cpp
@@ -751,6 +751,7 @@ void Engine::render(float* out, int32_t numFrames) {
}
dsp::ScopedNoDenormals noDenormals;
const auto t0 = std::chrono::steady_clock::now();
+ deviceBlock_ = true; // a deadline, whatever the gap since the last block
processBlock(out, numFrames);
// DSP load = render time / block budget, smoothed (Phase 11). Live-device
// path only; renderOffline stays untimed.
@@ -789,6 +790,7 @@ void Engine::renderOffline(float* out, int32_t frames) {
recomputePdc();
preparedSR_ = sr;
}
+ deviceBlock_ = false; // export/freeze: back-to-back blocks are offline
processBlock(out, frames);
}
@@ -1221,7 +1223,7 @@ int Engine::computeInstrumentMidi(Track& t, MidiEv* evs, int32_t frames, double
}
// MIDI pre-pass: compute each non-session instrument track's post-FX MIDI output into its
-// per-position buffer (blockMidi_). Runs once per block so each track's MIDI FX advance once;
+// per-position buffer (rs_->blockMidi). Runs once per block so each track's MIDI FX advance once;
// the render pass then feeds instruments from these buffers (own + routed sources').
void Engine::computeBlockMidi(
Graph* g, int32_t frames, double blockStart, double spb, bool playing, bool arrangementActive) {
@@ -1230,46 +1232,46 @@ void Engine::computeBlockMidi(
// every inner buffer) for each graph swap before it goes live. The guard
// below is unreachable in practice; it neutralizes counts so no stale
// MIDI can replay instead of growing.
- const size_t have = std::min({blockMidi_.size(), blockMidiN_.size(), blockExpr_.size(), blockExprN_.size()});
+ const size_t have = std::min({rs_->blockMidi.size(), rs_->blockMidiN.size(), rs_->blockExpr.size(), rs_->blockExprN.size()});
if (have < nt) {
for (size_t i = 0; i < have; ++i) {
- blockMidiN_[i] = 0;
- blockExprN_[i] = 0;
+ rs_->blockMidiN[i] = 0;
+ rs_->blockExprN[i] = 0;
}
return;
}
for (size_t i = 0; i < nt; ++i) {
- blockMidiN_[i] = 0;
- blockExprN_[i] = 0;
+ rs_->blockMidiN[i] = 0;
+ rs_->blockExprN[i] = 0;
Track& t = *g->tracks[i];
// Session-active tracks feed via renderSessionSlotRaw (their own clock), so skip here.
const bool sessionActive = t.sessionPlayer && t.sessionPlayer->playing.load(std::memory_order_relaxed) >= 0;
if (t.type() != TrackType::Instrument || !t.instrument || sessionActive) continue;
- auto& buf = blockMidi_[i];
+ auto& buf = rs_->blockMidi[i];
if (buf.size() < 1024) {
- blockMidiN_[i] = 0;
- blockExprN_[i] = 0;
+ rs_->blockMidiN[i] = 0;
+ rs_->blockExprN[i] = 0;
continue;
} // unreachable: pre-sized
- auto& xbuf = blockExpr_[i];
+ auto& xbuf = rs_->blockExpr[i];
if (xbuf.size() < static_cast<size_t>(kMaxBlockExpr)) {
- blockMidiN_[i] = 0;
- blockExprN_[i] = 0;
+ rs_->blockMidiN[i] = 0;
+ rs_->blockExprN[i] = 0;
continue;
}
- blockMidiN_[i] = computeInstrumentMidi(
- t, buf.data(), frames, blockStart, spb, playing, arrangementActive, xbuf.data(), &blockExprN_[i]);
+ rs_->blockMidiN[i] = computeInstrumentMidi(
+ t, buf.data(), frames, blockStart, spb, playing, arrangementActive, xbuf.data(), &rs_->blockExprN[i]);
}
}
// A device that takes a MIDI key (Nota Auto Shift's MIDI target) gets its source track's
-// post-FX notes for this block, from the pre-pass (blockMidi_). Audio thread.
+// post-FX notes for this block, from the pre-pass (rs_->blockMidi). Audio thread.
void Engine::feedMidiKey(Graph* g, Device& d, int32_t srcTrackId) {
if (!g) return;
- const size_t nt = std::min(g->tracks.size(), blockMidiN_.size());
+ const size_t nt = std::min(g->tracks.size(), rs_->blockMidiN.size());
for (size_t j = 0; j < nt; ++j)
if (g->tracks[j] && g->tracks[j]->id() == srcTrackId) {
- d.setMidiKey(blockMidi_[j].data(), blockMidiN_[j]);
+ d.setMidiKey(rs_->blockMidi[j].data(), rs_->blockMidiN[j]);
return;
}
}
@@ -1294,7 +1296,7 @@ void Engine::renderInstrumentRaw(
// Recording the destination prints the routed MIDI into its take (arm the destination).
const bool captureRouted = srcId >= 0 && t.id() == recordTrackId_ && (playing || countInActive_) &&
recording_.load(std::memory_order_relaxed) && spb > 0.0;
- const size_t nt = std::min(g->tracks.size(), blockMidiN_.size());
+ const size_t nt = std::min(g->tracks.size(), rs_->blockMidiN.size());
for (size_t j = 0; j < nt; ++j) {
Track* p = g->tracks[j].get();
if (!p) continue;
@@ -1303,18 +1305,18 @@ void Engine::renderInstrumentRaw(
// its own render is skipped, but its buffer was computed in the pre-pass.
const bool routed = !self && srcId >= 0 && p->type() == TrackType::Instrument && p->id() == srcId;
if (!self && !routed) continue;
- const int m = blockMidiN_[j];
- const MidiEv* srcEvs = blockMidi_[j].data();
+ const int m = rs_->blockMidiN[j];
+ const MidiEv* srcEvs = rs_->blockMidi[j].data();
for (int k = 0; k < m && n < 1024; ++k) evs[n++] = srcEvs[k];
- if (j < blockExprN_.size())
- for (int k = 0; k < blockExprN_[j] && xn < kMaxBlockExpr; ++k) xev[xn++] = blockExpr_[j][k];
+ if (j < rs_->blockExprN.size())
+ for (int k = 0; k < rs_->blockExprN[j] && xn < kMaxBlockExpr; ++k) xev[xn++] = rs_->blockExpr[j][k];
if (routed && t.armed()) trackRoutedDown(t.id(), srcEvs, m, blockStart, spb, playing || countInActive_);
if (routed && captureRouted) {
captureRoutedNotes(srcEvs, m, blockStart, spb, countInClockOffset());
// The source's controllers (its clips' curves) print into the take too.
- if (j < blockExprN_.size())
- for (int k = 0; k < blockExprN_[j]; ++k) {
- const ExprEv& x = blockExpr_[j][k];
+ if (j < rs_->blockExprN.size())
+ for (int k = 0; k < rs_->blockExprN[j]; ++k) {
+ const ExprEv& x = rs_->blockExpr[j][k];
if (x.dim < kCtlDimBase) continue;
recordedCtl_.push(RecordedCtl{x.dim - kCtlDimBase,
(blockStart + x.off) / spb + countInClockOffset(), x.value, recordPass_});
@@ -1675,6 +1677,10 @@ void Engine::processBlock(float* out, int32_t numFrames) {
drainLiveMidi(transport_.playheadSamples() / spb, playing);
Graph* g = liveGraph_.load(std::memory_order_acquire);
+ // This block's scratch, read after the graph: publishRaw publishes the scratch first, so
+ // it always fits the graph seen here. Held until the scope ends the render epoch.
+ const SnapshotHistory<RenderScratch>::RenderScope scratchScope(scratchHist_);
+ rs_ = scratchHist_.live();
auto flushArrangementVoices = [&] {
if (g)
@@ -1773,9 +1779,6 @@ void Engine::processBlock(float* out, int32_t numFrames) {
renderTone(out, numFrames);
renderPreview(out, numFrames); // audition voice (M7-4a), pre-master
- // master-stage silence (pre-master-chain mix).
- stageSilent_[ST_MASTER] = stageSilence_[ST_MASTER].process(out, numFrames) == dsp::SignalState::Silent;
-
// Master effect chain (post-mix, pre-fader): run the whole mix through the master
// track's devices, in kMaxBlock chunks so each device sees at most a full block.
if (g && g->masterTrack) {
@@ -2062,13 +2065,13 @@ void Engine::mixGraph(Graph* g, float* out, int32_t frames, double blockStart, b
// Per-track render storage (two halves: dry + post). Falls back to
// all-serial when undersized (unreachable: sized per graph swap).
const size_t stride = (size_t)frames * 2;
- const bool parallelOk = leafBuf_.size() >= ntracks * stride * 2 && (uint64_t)frames * 2 <= mixTmp_.size() &&
- leafWork_.size() >= ntracks;
+ const bool parallelOk = rs_->leafBuf.size() >= ntracks * stride * 2 && (uint64_t)frames * 2 <= mixTmp_.size() &&
+ rs_->leafWork.size() >= ntracks;
const int32_t capTrackId = freezeCaptureTrackId_.load(std::memory_order_relaxed);
const bool recArmed = recording_.load(std::memory_order_relaxed);
for (size_t li = 0; li < ntracks; ++li) {
Track& t = *g->tracks[li];
- LeafWork& w = leafWork_[li];
+ LeafWork& w = rs_->leafWork[li];
w = LeafWork{};
if (t.type() == TrackType::Return) continue; // return buses run in pass 2
if (t.type() == TrackType::Group) continue; // group submixes run in pass 1.5
@@ -2161,17 +2164,18 @@ void Engine::mixGraph(Graph* g, float* out, int32_t frames, double blockStart, b
w.tapRec = (recSrc > 0 && t.id() == recSrc); // internal resampling source
// Parallel eligibility: built-in DSP only (hosted plugin instances
- // are not thread-safe across threads), no shared-queue writers
- // (record queues are SPSC), no hardware monitoring.
+ // are not thread-safe across threads — also when nested in a rack),
+ // no shared-queue writers (record queues are SPSC), no hardware
+ // monitoring.
bool eligible = parallelOk;
const int32_t srcId = t.midiFromTrackId();
if (srcId >= 0 && t.id() == recordTrackId_ && (playing || countInActive_) && recArmed && spb > 0.0)
eligible = false; // captureRouted destination prints into shared takes
if (srcId >= 0 && t.armed()) eligible = false; // routed source prints while armed
- if (eligible && t.instrument && t.instrument->kind() < 0) eligible = false;
+ if (eligible && t.instrument && t.instrument->hostsPlugin()) eligible = false;
if (eligible)
for (auto& d : t.devices)
- if (d && !d->bypassed() && d->builtinKind() < 0) {
+ if (d && !d->bypassed() && d->hostsPlugin()) {
eligible = false;
break;
}
@@ -2179,29 +2183,78 @@ void Engine::mixGraph(Graph* g, float* out, int32_t frames, double blockStart, b
}
// Parallel DSP phase: eligible leaves render dry into their own
- // leafBuf_ region, copy to the post half, run devices in place
+ // rs_->leafBuf region, copy to the post half, run devices in place
// there. Regions are per-track (never shared), so completion order
// cannot mix signals; the serial accumulate below fixes mix order.
- if (parallelOk)
- pool_.dispatch((int)ntracks, [&](int wid, int i) {
- LeafWork& w = leafWork_[(size_t)i];
- if (!w.t || w.path == LeafPath::Skip || !w.eligible) return;
- w.wid = wid;
- float* base = leafBase((size_t)i, stride);
- renderLeafDry(*w.t, base, w, g, frames, blockStart, spb, playing, ti, arrangementActive);
- std::copy_n(base, stride, base + stride);
- processLeafDevices(*w.t, base + stride, w, g, frames, blockStart, spb, playing, ti);
- });
+ if (parallelOk) {
+ int m = 0;
+ for (size_t li = 0; li < ntracks; ++li) {
+ const LeafWork& w = rs_->leafWork[li];
+ if (w.t && w.path != LeafPath::Skip && w.eligible) rs_->parIdx[(size_t)m++] = (int)li;
+ }
+ // Offline (blocks back-to-back, no deadline): every thread, finish fast. With a
+ // device: this thread alone unless it can't keep up (see rtParallel_); then
+ // enough threads to finish within kRtSizeLoad of the buffer.
+ // Only renderOffline can be offline: a device block that follows the last one
+ // closely is an overloaded callback, not a bounce.
+ const bool offline = !deviceBlock_ && pool_->backToBack();
+ const double periodNs = 1e9 * frames / std::max(1.0, transport_.sampleRate());
+ int helpers = -1;
+ if (!offline) {
+ helpers = 0;
+ if (rtParallel_ && (rtParallelLeftNs_ -= periodNs) <= 0) {
+ rtParallel_ = false; // re-measure alone
+ leafWorkNs_ = (int64_t)(kRtSizeLoad * periodNs); // back within a few blocks if still over
+ }
+ if (rtParallel_) {
+ const int threads = (int)std::ceil((double)leafWorkNs_ / (kRtSizeLoad * periodNs));
+ helpers = std::clamp(threads - 1, 1, std::max(1, m - 1));
+ }
+ }
+ pool_->dispatch(
+ m,
+ [&](int wid, int j) {
+ const size_t i = (size_t)rs_->parIdx[(size_t)j];
+ LeafWork& w = rs_->leafWork[i];
+ const auto t0 = std::chrono::steady_clock::now();
+ w.wid = wid;
+ float* base = leafBase(i, stride);
+ renderLeafDry(*w.t, base, w, g, frames, blockStart, spb, playing, ti, arrangementActive);
+ std::copy_n(base, stride, base + stride);
+ processLeafDevices(*w.t, base + stride, w, g, frames, blockStart, spb, playing, ti);
+ w.workNs = std::chrono::duration_cast<std::chrono::nanoseconds>(
+ std::chrono::steady_clock::now() - t0).count();
+ },
+ helpers);
+ // The single-thread cost, from blocks this thread rendered alone (see
+ // leafWorkNs_).
+ if (!offline && m > 0) {
+ int64_t work = 0;
+ bool alone = true;
+ for (int j = 0; j < m; ++j) {
+ const LeafWork& w = rs_->leafWork[(size_t)rs_->parIdx[(size_t)j]];
+ work += w.workNs;
+ alone = alone && w.wid == pool_->workerCount();
+ }
+ if (alone && !rtParallel_) {
+ leafWorkNs_ += (work - leafWorkNs_) / 16;
+ if (leafWorkNs_ > periodNs) {
+ rtParallel_ = true;
+ rtParallelLeftNs_ = kRtHoldSeconds * 1e9;
+ }
+ }
+ }
+ }
// Serial accumulate in track order (bit-identical: same elementwise
// ops in the same order; SIMD adds/scales are exact per element).
for (size_t li = 0; li < ntracks; ++li) {
- LeafWork& w = leafWork_[li];
+ LeafWork& w = rs_->leafWork[li];
if (!w.t || w.path == LeafPath::Skip) continue;
Track& t = *w.t;
// pre = dry pre-device (pre-FX tap source), post = post-device
// (fader/capture source). Parallel tracks read both halves of
- // their own leafBuf_ region; serial tracks render dry, tap, then
+ // their own rs_->leafBuf region; serial tracks render dry, tap, then
// run devices in place — the original per-track order.
float* pre = nullptr;
float* post = nullptr;
@@ -2306,9 +2359,6 @@ void Engine::mixGraph(Graph* g, float* out, int32_t frames, double blockStart, b
pkL, pkR, static_cast<float>(std::sqrt(sqL / frames)), static_cast<float>(std::sqrt(sqR / frames)));
}
- // leaf-stage silence (post-leaf `out`, zeroed on entry).
- stageSilent_[ST_LEAF] = stageSilence_[ST_LEAF].process(out, frames) == dsp::SignalState::Silent;
-
// Pass 1.5: group submixes. Process deepest-first so a nested group folds into its
// parent's bus before the parent reads it; top-level groups fold into the master.
for (int depth = maxDepth; depth >= 1; --depth)
@@ -2381,9 +2431,6 @@ void Engine::mixGraph(Graph* g, float* out, int32_t frames, double blockStart, b
pkL, pkR, static_cast<float>(std::sqrt(sqL / frames)), static_cast<float>(std::sqrt(sqR / frames)));
}
- // group-stage silence (leaf + group folds).
- stageSilent_[ST_GROUP] = stageSilence_[ST_GROUP].process(out, frames) == dsp::SignalState::Silent;
-
// Pass 2: return buses -> device chain -> master (M6-1). Exempt from the
// solo gate (a soloed track's reverb/delay still sounds); a return only
// honours its own mute. Runs even when stopped so effect tails ring out.
@@ -2472,9 +2519,6 @@ void Engine::mixGraph(Graph* g, float* out, int32_t frames, double blockStart, b
pkL, pkR, static_cast<float>(std::sqrt(sqL / frames)), static_cast<float>(std::sqrt(sqR / frames)));
}
- // return-stage silence (full pre-master mix).
- stageSilent_[ST_RETURN] = stageSilence_[ST_RETURN].process(out, frames) == dsp::SignalState::Silent;
-
// Internal resampling from the master bus: capture the fully-mixed output.
if (recSrc == -1) {
int64_t recDropped = 0;
diff --git a/tests/Nota.SmokeTest/Program.cs b/tests/Nota.SmokeTest/Program.cs
index 4777e699..8ceb9f67 100644
--- a/tests/Nota.SmokeTest/Program.cs
+++ b/tests/Nota.SmokeTest/Program.cs
@@ -248,6 +248,14 @@ if (args.Length >= 1 && args[0] == "--bundle")
return failures == 0 ? 0 : 1;
}
+// Render pool performance guards alone: `--perf`. Also part of the full run.
+if (args.Length >= 1 && args[0] == "--perf")
+{
+ Console.WriteLine("-- render pool --");
+ foreach (var (ok, label) in RenderPoolTests.Run()) Check(ok, label);
+ Console.WriteLine(failures == 0 ? "PERF PASSED" : $"PERF FAILED ({failures})");
+ return failures == 0 ? 0 : 1;
+}
// Process CPU readout alone: `--cpu`. Also part of the full run.
if (args.Length >= 1 && args[0] == "--cpu")
{
@@ -14948,6 +14956,8 @@ Console.WriteLine("-- dsp optimization --");
foreach (var (ok, label) in DspOptimizationTests.Run()) Check(ok, label);
Console.WriteLine("-- dsp silence bypass --");
foreach (var (ok, label) in DspSilenceBypassTests.Run()) Check(ok, label);
+Console.WriteLine("-- render pool --");
+foreach (var (ok, label) in RenderPoolTests.Run()) Check(ok, label);
Console.WriteLine("-- tap tempo --");
foreach (var (ok, label) in TapTempoTests.Run()) Check(ok, label);
diff --git a/tests/Nota.SmokeTest/RenderPoolTests.cs b/tests/Nota.SmokeTest/RenderPoolTests.cs
new file mode 100644
index 00000000..04471bb1
--- /dev/null
+++ b/tests/Nota.SmokeTest/RenderPoolTests.cs
@@ -0,0 +1,223 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Egor Khindikaynen (Nota). See LICENSES/ for license terms.
+//
+// Parallel render pool: performance regression guards (issue #223, the #212 review). The
+// render threads must cost nothing while nothing renders, must stay parked while playing
+// when the audio thread keeps up alone, must join when it can't (an overloaded small
+// buffer), must not make a bounce slower than rendering on one thread, must render
+// bit-identically to one thread, and must survive tracks being added and removed while
+// blocks render. Real-time checks render through the device callback's own path
+// (RenderDeviceBlock), not the offline one.
+//
+// Hardware-independent by construction: every check compares the parallel engine with the
+// same session rendered on the audio thread alone (render threads = 0) in this process,
+// or measures the render threads' own CPU clocks (nota_engine_render_threads_cpu_seconds)
+// rather than the whole process, so the .NET runtime and earlier tests add no noise.
+// Render CPU = time spent inside the render call (the calling thread renders or waits there)
+// + the render threads' CPU. Only the wall-clock and late-block comparisons are timing
+// budgets.
+// Also runnable alone: `dotnet run --project tests/Nota.SmokeTest -- --perf`.
+
+using System.Diagnostics;
+using Nota.Application;
+using Nota.Infrastructure;
+
+namespace Nota.SmokeTest;
+
+internal static class RenderPoolTests
+{
+ private const int Block = 512, Rate = 48000;
+ private static readonly double BlockSeconds = (double)Block / Rate;
+
+ private static string NoiseClip()
+ {
+ string path = Path.Combine(Path.GetTempPath(), "nota-perf-noise.wav");
+ if (!File.Exists(path))
+ {
+ var rng = new Random(1);
+ WavWriter.WriteStereo(path, 8, Rate, _ => (rng.NextDouble() * 0.5 - 0.25, rng.NextDouble() * 0.5 - 0.25));
+ }
+ return path;
+ }
+
+ // `tracks` audio tracks, each a noise clip through a Reverb — real DSP on every track.
+ private static NotaEngine AudioSession(int tracks, int renderThreads)
+ {
+ var e = new NotaEngine();
+ if (renderThreads >= 0) e.RenderThreads = renderThreads;
+ string clip = NoiseClip();
+ for (int i = 0; i < tracks; i++)
+ {
+ int t = e.AddAudioTrack();
+ e.AddAudioClip(t, clip, 0.0);
+ e.AddBuiltinDevice(t, 2); // Reverb
+ }
+ var b = new float[Block * 2];
+ e.RenderOffline(b, Block, Rate); // prepare every node at the rate
+ e.Seek(0); e.Play();
+ return e;
+ }
+
+ // Parallel engines get at least two render threads, so the comparison means something
+ // on a two-core runner too (where the default is none).
+ private static int ParallelThreads()
+ {
+ using var probe = new NotaEngine();
+ return Math.Max(probe.RenderThreads, 2);
+ }
+
+ // Renders `seconds` of audio in `block`-frame blocks; paced = one block per buffer period
+ // through the device callback's path (RenderDeviceBlock), else back-to-back like a bounce.
+ // Returns render CPU s, wall s, the render threads' share of the CPU, and blocks that took
+ // longer than their buffer period.
+ private static (double Cpu, double Wall, double Threads, int Late) Measure(
+ NotaEngine e, double seconds, bool paced, int block = Block)
+ {
+ var b = new float[block * 2];
+ double period = (double)block / Rate;
+ int blocks = (int)(seconds / period), late = 0;
+ double inside = 0, workers0 = e.RenderThreadsCpuSeconds;
+ var wall = Stopwatch.StartNew();
+ var call = new Stopwatch();
+ for (int i = 0; i < blocks; i++)
+ {
+ call.Restart();
+ if (paced) e.RenderDeviceBlock(b, block); else e.RenderOffline(b, block);
+ double took = call.Elapsed.TotalSeconds;
+ inside += took;
+ if (took > period) late++;
+ if (paced)
+ {
+ double ahead = (i + 1) * period - wall.Elapsed.TotalSeconds;
+ if (ahead > 0.0005) Thread.Sleep(TimeSpan.FromSeconds(ahead));
+ }
+ }
+ double threads = e.RenderThreadsCpuSeconds - workers0;
+ return (inside + threads, wall.Elapsed.TotalSeconds, threads, late);
+ }
+
+ private static float[] RenderSynths(int renderThreads)
+ {
+ using var e = new NotaEngine();
+ e.RenderThreads = renderThreads;
+ e.SetBpm(120);
+ for (int i = 0; i < 8; i++)
+ {
+ int t = e.AddInstrumentTrack();
+ int clip = e.AddMidiClip(t, 0.0, 4.0);
+ e.SetClipNotes(t, clip, new[] { new NotaNote(48 + i * 3, 0.0, 2.0, 0.8f), new NotaNote(60 + i, 1.0, 3.0, 0.7f) });
+ e.AddBuiltinDevice(t, 3); // Delay: state carried across blocks
+ }
+ e.Seek(0); e.Play();
+ var all = new float[24 * Block * 2];
+ var b = new float[Block * 2];
+ for (int i = 0; i < 24; i++) { e.RenderOffline(b, Block); Array.Copy(b, 0, all, i * Block * 2, Block * 2); }
+ return all;
+ }
+
+ public static IEnumerable<(bool Ok, string Label)> Run()
+ {
+ int par = ParallelThreads();
+
+ // 1. Idle: render threads park. A spinning pool costs ~1 s of CPU per thread per second.
+ using (var e = new NotaEngine())
+ {
+ e.RenderThreads = par;
+ double c0 = e.RenderThreadsCpuSeconds;
+ Thread.Sleep(1000);
+ double used = e.RenderThreadsCpuSeconds - c0;
+ yield return (used < 0.02,
+ $"idle engine: {par} render threads use {used * 1000:0.0} ms CPU over 1 s (parked, < 20 ms)");
+ }
+
+ // 2. After playback: once blocks stop coming, the threads park again.
+ using (var e = AudioSession(8, par))
+ {
+ Measure(e, 0.5, paced: true);
+ e.StopTransport();
+ Thread.Sleep(100); // let the last job's linger run out
+ double c0 = e.RenderThreadsCpuSeconds;
+ Thread.Sleep(1000);
+ double used = e.RenderThreadsCpuSeconds - c0;
+ yield return (used < 0.02,
+ $"after playback stops, render threads use {used * 1000:0.0} ms CPU over 1 s (parked, < 20 ms)");
+ }
+
+ // 3. Playing in real time when one thread keeps up: the render threads stay out of it
+ // (spreading a block that fits the buffer over parked threads costs 2-3x the CPU and
+ // misses more deadlines; the #212 pool spun between blocks: ~40x).
+ (double Cpu, double Wall, double Threads, int Late) ser, prl;
+ using (var e = AudioSession(16, 0)) ser = Measure(e, 2.0, paced: true);
+ using (var e = AudioSession(16, par)) prl = Measure(e, 2.0, paced: true);
+ {
+ double s = ser.Cpu / ser.Wall * 100, p = prl.Cpu / prl.Wall * 100, t = prl.Threads / prl.Wall * 100;
+ yield return (t < 2,
+ $"playing 16 tracks in real time, one thread keeps up: render threads stay parked ({t:0.0} % of a core, < 2)");
+ yield return (p <= 1.5 * s + 3,
+ $"playing 16 tracks in real time: render CPU {p:0.0} % of a core vs {s:0.0} % on one thread (<= 1.5x + 3)");
+ }
+
+ // 3b. Overloaded (one thread can't make a 64-frame deadline): the render threads join.
+ // Skipped when this machine renders the load alone in time.
+ using (var e = AudioSession(256, 0)) ser = Measure(e, 1.5, paced: true, block: 64);
+ int smallBlocks = (int)(1.5 * Rate / 64);
+ if (ser.Late * 2 < smallBlocks)
+ yield return (true, $"overload check skipped: one thread renders 256 tracks at a 64-frame buffer in time ({ser.Late} of {smallBlocks} blocks late)");
+ else
+ {
+ using (var e = AudioSession(256, par)) prl = Measure(e, 1.5, paced: true, block: 64);
+ yield return (prl.Threads > 0.05,
+ $"overloaded (256 tracks, 64-frame buffer, {ser.Late} of {smallBlocks} blocks late on one thread): render threads join ({prl.Threads * 1000:0} ms CPU)");
+ yield return TimingBudget.Check(true, prl.Late <= ser.Late,
+ $"overloaded: late blocks {prl.Late} with render threads vs {ser.Late} on one thread (not more)");
+ }
+
+ // 4. Bounce (blocks back-to-back): CPU work bounded, and never slower than one thread.
+ using (var e = AudioSession(16, 0)) ser = Measure(e, 3.0, paced: false);
+ using (var e = AudioSession(16, par)) prl = Measure(e, 3.0, paced: false);
+ yield return (prl.Cpu <= 3 * ser.Cpu + 0.05,
+ $"bouncing 16 tracks: parallel CPU work {prl.Cpu * 1000:0} ms vs {ser.Cpu * 1000:0} ms on one thread (<= 3x)");
+ yield return TimingBudget.Check(true, prl.Wall <= 1.3 * ser.Wall + 0.01,
+ $"bouncing 16 tracks: parallel {prl.Wall * 1000:0} ms vs {ser.Wall * 1000:0} ms on one thread (not slower, <= 1.3x)");
+
+ // 5. Parallel rendering is transparent: same samples as one thread.
+ var one = RenderSynths(0);
+ var many = RenderSynths(par);
+ double diff = 0, rms = 0;
+ for (int i = 0; i < one.Length; i++) { diff = Math.Max(diff, Math.Abs(one[i] - many[i])); rms += one[i] * (double)one[i]; }
+ rms = Math.Sqrt(rms / one.Length);
+ yield return (rms > 1e-3 && diff == 0.0,
+ $"8 synth tracks render bit-identically on {par} render threads and on one (rms {rms:0.0000}, maxdiff {diff:E1})");
+
+ // 6. Tracks added and removed while blocks render (the render scratch used to be
+ // reallocated under a block in flight: use-after-free, crashes).
+ using (var e = AudioSession(1, par))
+ {
+ long rendered = 0;
+ var stop = false;
+ var render = new Thread(() =>
+ {
+ var b = new float[256 * 2];
+ while (!Volatile.Read(ref stop)) { e.RenderOffline(b, 256); Interlocked.Increment(ref rendered); }
+ });
+ render.Start();
+ string clip = NoiseClip();
+ for (int round = 0; round < 2; round++)
+ {
+ var ids = new List<int>();
+ for (int i = 0; i < 24; i++)
+ {
+ int t = i % 2 == 0 ? e.AddAudioTrack() : e.AddInstrumentTrack();
+ if (i % 2 == 0) { e.AddAudioClip(t, clip, 0.0); e.AddBuiltinDevice(t, 2); }
+ ids.Add(t);
+ Thread.Sleep(1);
+ }
+ foreach (int t in ids) e.RemoveTrack(t);
+ }
+ Volatile.Write(ref stop, true);
+ render.Join();
+ yield return (Interlocked.Read(ref rendered) > 100,
+ $"adding and removing 48 tracks while blocks render: no crash ({rendered} blocks rendered)");
+ }
+ }
+}