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) Audio Unit plug-ins get exactly their own channels per block (#216)

Egor Khindikaynende96d1de41bc
diff --git a/.specify/bugs/au-process-assert/assessment.md b/.specify/bugs/au-process-assert/assessment.md
new file mode 100644
index 00000000..cca0d0fd
--- /dev/null
+++ b/.specify/bugs/au-process-assert/assessment.md
@@ -0,0 +1,116 @@
+# Bug Assessment: Audio Unit plug-ins get 31 channels per block — JUCE assertion and dropouts
+
+- **Slug**: au-process-assert
+- **Created**: 2026-10-20
+- **Source**: pasted text (console output from the user's debug run on macOS)
+- **Verdict**: valid
+- **Severity**: high
+
+## Report (verbatim or summarized)
+
+Debug build on macOS. Opening a project that hosts an Audio Unit plug-in prints:
+
+```
+JUCE v8.0.14
+3985
+JUCE Assertion failure in juce_AudioUnitPluginFormatImpl.h:1346
+```
+
+Pressing play then floods the console, once per audio block (~33 ms apart):
+
+```
+JUCE Assertion failure in juce_AudioUnitPluginFormatImpl.h:1346
+[xrun] audio dropout #127 at 2026-10-20T10:01:26.2563380+03:00
+2
+JUCE Assertion failure in juce_AudioUnitPluginFormatImpl.h:1346
+[xrun] audio dropout #128 at 2026-10-20T10:01:26.2902800+03:00
+...
+[xrun] audio dropout #219 at 2026-10-20T10:01:31.3891860+03:00
+```
+
+The bare numbers between lines (`3985`, `2`, `4`, `42`, `1806`) are an event count, according to the user. They are not printed by
+Nota's code. On quit, JUCE's `LeakedObjectDetector` reports `VST3PluginFormatHeadless`, `AudioUnitPluginFormatHeadless`,
+2 × `AudioPluginFormat`, `MessageManager`, and 84 × `PluginDescription`.
+
+## Symptom
+
+Every `processBlock` of a hosted AU fails JUCE's `buffer.getNumChannels() <= preparedChannels` check. In the debug build, each
+failure goes with an audio dropout, so playback stutters on every block. Expected: AU plug-ins get a buffer that fits the layout
+they were prepared for, with no assertion and no dropouts.
+
+## Reproduction
+
+1. macOS, debug build of the engine (assertions enabled).
+2. Open a project with any Audio Unit instrument or effect on a track. The assertion is printed already on load.
+3. Press play. The assertion is printed once per block, each time followed by `[xrun] audio dropout #N`.
+
+[NEEDS CLARIFICATION: which AU the project uses, and whether the app was started under a debugger. With a debugger attached,
+`jassertfalse` runs `JUCE_BREAK_IN_DEBUGGER` (`kill(0, SIGTRAP)`) on every block, which would explain a dropout per block on its own.]
+
+## Suspected Code Paths
+
+- `src/native/nota.engine/pluginhost/PluginHost.cpp:400` — `kNoAllocChans = 31`.
+- `src/native/nota.engine/pluginhost/PluginHost.cpp:409` `pluginChannelPtrs()` — returns
+ `max(kNoAllocChans, storage, plugin in, plugin out)`. Every plug-in, of any format, gets ≥ 31 channels.
+- `src/native/nota.engine/pluginhost/PluginHost.cpp:742` `PluginInstrument::render` and `:~911` `PluginEffect::process` — wrap
+ those pointers in a `juce::AudioBuffer` and call `plugin_->processBlock`.
+- `vendor/JUCE/modules/juce_audio_processors_headless/format_types/juce_AudioUnitPluginFormatImpl.h:1302` —
+ `preparedChannels = jmax(totalIn, totalOut)` in `prepareToPlay` (2 for a stereo plug-in).
+- Same file, `:1346` — `jassert(buffer.getNumChannels() <= preparedChannels)`, followed by
+ `inputBuffer.makeCopyOf(buffer, true)`. This resizes `inputBuffer` to 31 channels (an allocation on the audio thread on the
+ first block) and copies 31 channels on every block after that.
+
+## Root Cause Hypothesis
+
+Commit 06057f89 (bug `plugin-add-crash-windows`, in releases since v0.52.1) made `pluginChannelPtrs()` always hand a plug-in at
+least 31 channels. The headroom is there for VST3: JUCE's VST3 wrapper maps buses straight from `buffer.getWritePointer(ch)`, and
+a VST3 plug-in that widens its layout at runtime would otherwise get null channels. The AU wrapper works differently. It copies
+the incoming buffer into its own `inputBuffer`, which was sized at `prepareToPlay`, and asserts when the host buffer is wider.
+The 31-channel buffer therefore fails the assertion on every block. The same path also does one audio-thread allocation and an
+extra 31-channel copy per block in release builds, where the assertion itself is compiled out. A dropout on every block in the
+debug run is consistent with the per-block assertion: logging plus `JUCE_BREAK_IN_DEBUGGER` when a debugger is attached.
+Confidence: **high** for the assertion. **Medium** that the assertion alone causes the dropouts; the per-block copy and the
+debug build also cost CPU.
+
+## Proposed Remediation
+
+**Preferred**: apply the channel headroom only to formats that need it. At prepare time (`PluginInstrument::prepare`,
+`PluginEffect::setSampleRate`, both on the message thread), cache the minimum width for the instance: `kNoAllocChans` when
+`getPluginDescription().pluginFormatName == "VST3"`, 0 otherwise. `pluginChannelPtrs()` takes that minimum and returns
+`max(minChans, plugin in, plugin out)`, at least 1, capped at `kMaxChans`. For non-VST3 plug-ins it no longer adds
+`storage.getNumChannels()`. `storage_` is padded to ≥ 2 channels, so a mono AU (prepared for 1) would still get 2 and fail the
+assertion. The callers already read channel 1 only when `stereoOut_` / `stereoIn_`, so a 1-channel buffer is safe for them. An AU
+that changes its layout is re-prepared by JUCE on its own path, and reading `getTotalNum*Channels()` each block keeps the width
+in step with that.
+
+**Alternatives**:
+- Keep the 31-channel buffer for all formats and only cut the AU's width back to `preparedChannels`. This is not reachable from
+ outside the wrapper, so in practice it is the same per-format branch.
+- Remove the headroom entirely and resize on `audioProcessorChanged`. That needs a lock-free buffer swap; out of scope (already
+ listed as a follow-up of `plugin-add-crash-windows`).
+
+**Files likely to change**:
+- `src/native/nota.engine/pluginhost/PluginHost.cpp`
+- `tests/Nota.SmokeTest/Program.cs` (if the assertion check below is added)
+
+**Tests to add or update**:
+- The smoke test already hosts an AU instrument and an AU effect (`Program.cs:475`). In a debug build, check that they render
+ without assertions. One way: run the smoke test and fail if stderr contains `juce_AudioUnitPluginFormatImpl.h`. Otherwise,
+ verify by hand with Apple's built-in AUs (`DLSMusicDevice`, `AUDelay`), which are on every Mac.
+- Regression guard for 06057f89: the Reaktor 6 VST3 layout-widening harness (`/tmp/widenharness`, see
+ `plugin-add-crash-windows/fix.md`) should still render without SIGSEGV.
+
+## Risks & Considerations
+
+- VST3 behaviour must stay exactly as it is (the headroom fixes a real crash). Gate it by format name and keep the code path
+ unchanged for VST3.
+- An AU whose layout grows between `getTotalNum*Channels()` and `processBlock` gets a buffer narrower than its new layout. The AU
+ wrapper copies by channel count (`makeCopyOf`) and maps buses through `inMapping`/`outMapping`, which were set up at prepare.
+ It does not dereference null channels the way the VST3 wrapper did. Worth confirming during the fix.
+- The leak reports on quit are a separate, debug-only issue: `formatManager()`, `MessageManager` and the plug-in list are not torn
+ down before JUCE's static leak detectors run. They are not caused by this bug; track them separately if they matter.
+
+## Open Questions
+
+- [NEEDS CLARIFICATION: which AU plug-in(s) the project hosts, and whether the dropouts also happen in a release build.]
+- [NEEDS CLARIFICATION: was the app running under a debugger (e.g. netcoredbg)?]
diff --git a/.specify/bugs/au-process-assert/fix.md b/.specify/bugs/au-process-assert/fix.md
new file mode 100644
index 00000000..afc0392b
--- /dev/null
+++ b/.specify/bugs/au-process-assert/fix.md
@@ -0,0 +1,78 @@
+# Bug Fix: Audio Unit plug-ins get 31 channels per block — JUCE assertion and dropouts
+
+- **Slug**: au-process-assert
+- **Fixed**: 2026-10-20
+- **Assessment**: ./assessment.md
+- **Status**: applied
+
+## Summary
+
+The 31-channel headroom from `plugin-add-crash-windows` (06057f89) now applies to VST3 plug-ins only. Any other format (Audio
+Unit) gets a process buffer exactly as wide as its current layout, `max(1, in, out)`. That is no wider than the layout JUCE's AU
+wrapper was prepared for, so `jassert(buffer.getNumChannels() <= preparedChannels)` no longer fires and the wrapper no longer
+grows its `inputBuffer` on the audio thread or copies 31 channels per block.
+
+## Changes
+
+| File | Change | Notes |
+|------|--------|-------|
+| `src/native/nota.engine/pluginhost/PluginHost.cpp` | modified | `pluginChannelPtrs()` takes a `minChans` floor. New `minProcessChannels()` (VST3 → `kNoAllocChans`, else 0). `PluginInstrument` / `PluginEffect` cache it as `chanFloor_` in `prepare()` / `setSampleRate()` on the message thread, next to the other prepare-time state the audio thread reads |
+
+## Diff Highlights
+
+```cpp
+int pluginChannelPtrs(const juce::AudioProcessor& p, juce::AudioBuffer<float>& storage,
+ float* spare, int frames, int minChans, float* (&ptrs)[kMaxChans]) {
+ const int have = juce::jmin(storage.getNumChannels(), kMaxChans);
+ const int want = juce::jmin(kMaxChans, juce::jmax(minChans > 0 ? juce::jmax(minChans, have) : 1,
+ p.getTotalNumInputChannels(), p.getTotalNumOutputChannels()));
+ ...
+}
+
+int minProcessChannels(const juce::AudioPluginInstance& p) {
+ return p.getPluginDescription().pluginFormatName == "VST3" ? kNoAllocChans : 0;
+}
+```
+
+For VST3, `max(max(31, have), in, out)` is the old `max(31, have, in, out)`: the behaviour is unchanged. For AU, `storage_`
+(padded to ≥ 2) no longer counts, so a mono AU gets 1 channel. The callers read channel 1 only when `stereoOut_`, which implies
+≥ 2 output channels.
+
+## Tests Added or Updated
+
+None in the repo. The opt-in `--hostcheck` mode of the smoke test already hosts an AU instrument and an AU effect. It can't see
+the assertion, though: JUCE prints it to the native stderr and keeps going, and the smoke test has no hook into that.
+
+## Local Verification
+
+Engine built in the existing Debug configuration (`cmake --build src/native/nota.engine/build`, assertions on). Run with
+`Nota.SmokeTest --hostcheck build/nota-scanworker`, `NOTA_DATA_DIR` isolated. It picks Apple's AUSampler (instrument) and
+AUVectorPanner (effect):
+
+- **Before** (HEAD's `PluginHost.cpp`): `HOSTCHECK PASSED`, but **38 ×** `JUCE Assertion failure in
+ juce_AudioUnitPluginFormatImpl.h:1346` on stderr. This reproduces the report.
+- **After**: `HOSTCHECK PASSED` (instrument rms 0.2157, through the effect 0.0096, restored project audible), **0 ×** `:1346`.
+ The remaining assertions are pre-existing and unrelated: 2 × `juce_MessageListener.cpp:50` at start, 5 ×
+ `LeakedObjectDetector` at exit. Both appear in the "before" run too.
+- Not run: `scripts/build.sh`. It reconfigures the engine build as Release and would replace the user's Debug build dir, and the
+ full smoke run on this branch already fails 4 timing/stress checks (Pentad/Consort stress, reverb preview, render speed) on the
+ Debug engine regardless of this change.
+- Not run: the Reaktor 6 VST3 layout-widening harness from `plugin-add-crash-windows` (`/tmp/widenharness` no longer exists). The
+ VST3 width is algebraically the same as before (see above).
+- Not done by hand in the GUI app: open the user's project and press play.
+
+## Deviations from Assessment
+
+- No automated assertion check was added to the smoke test (assessment suggested failing on stderr). The managed test can't
+ capture the engine's native stderr without redirecting fd 2 for the whole process. The `--hostcheck` before/after above is the
+ reproducible check.
+
+## Follow-ups
+
+- `/speckit-bug-test slug=au-process-assert`: open the reporter's project in the app (Debug), press play, and confirm no `:1346`
+ and no `[xrun]` lines.
+- Re-check Reaktor 6 VST3 Play/Patch/Build switching (guard for 06057f89).
+- `scripts/build.sh` before the PR.
+- CHANGELOG `[Unreleased]` → Fixed entry. Not added here because this working tree is `feat/ui-scale`, which already has unrelated
+ CHANGELOG edits. The fix belongs on its own `fix/…` branch from `develop`.
+- Separate, debug-only: JUCE leak reports at exit and `MessageListener.cpp:50` at start.
diff --git a/.specify/bugs/au-process-assert/test.md b/.specify/bugs/au-process-assert/test.md
new file mode 100644
index 00000000..e124eb11
--- /dev/null
+++ b/.specify/bugs/au-process-assert/test.md
@@ -0,0 +1,57 @@
+# Bug Verification: Audio Unit plug-ins get 31 channels per block — JUCE assertion and dropouts
+
+- **Slug**: au-process-assert
+- **Tested**: 2026-10-20
+- **Assessment**: ./assessment.md
+- **Fix**: ./fix.md
+- **Result**: partial
+
+## Summary
+
+The engine-level reproduction no longer triggers the assertion. On a Debug engine (assertions on), the AU instrument plus AU
+effect render from `--hostcheck` produces 0 × `juce_AudioUnitPluginFormatImpl.h:1346`, against 38 before the fix. Audio still
+flows. The full build and smoke test pass on the Release engine. The reporter's own scenario has not been re-run: the
+reporter's project in the GUI app, under a debugger. Neither has the VST3 layout-widening guard (Reaktor 6). Hence `partial`.
+
+## Checks Performed
+
+| Check | Command / Action | Result | Notes |
+|-------|------------------|--------|-------|
+| Reproduction (post-fix), Debug engine | `cmake … -B build-debug -DCMAKE_BUILD_TYPE=Debug` + `Nota.SmokeTest --hostcheck build-debug/nota-scanworker` (bin copy with the Debug dylib, `NOTA_DATA_DIR` isolated) | pass | 0 × `:1346` (38 before the fix, see fix.md). AUSampler + AUVectorPanner audible. The 13 `repo root located` FAILs come from running the binary copy outside the repo (design checks look for `Nota.sln`) and are unrelated |
+| Hosted AU check, Release engine | `tests/Nota.SmokeTest/bin/Release/net10.0/Nota.SmokeTest --hostcheck build/nota-scanworker` | pass | `HOSTCHECK PASSED`, instrument rms 0.2157, through effect 0.0096, restored project audible, 0 JUCE assertions |
+| Regression suite | `scripts/build.sh` (Release engine + managed build + full smoke test) | pass | `SMOKE TEST PASSED`, 3688 PASS / 0 FAIL, exit 0 |
+| In-app reproduction (reporter's project, press play) | GUI app on the Debug engine | not-run | Needs the GUI and the reporter's AU project; to be done by the user |
+| VST3 regression guard (Reaktor 6 Play/Patch/Build) | `plugin-add-crash-windows` harness | not-run | Harness `/tmp/widenharness` no longer exists. The VST3 width is algebraically unchanged: `max(max(31, have), in, out)` |
+| Lint / type-check | — | skipped | No separate C++ lint step in the project. Both engine configs compile cleanly |
+
+## Output Excerpts
+
+```
+# Debug engine (build-debug), post-fix
+ [PASS] hosted instrument produces audio (rms=0,2157)
+ [PASS] audio flows through the effect (rms=0,0096)
+ [PASS] restored plugin project is audible (rms=0,0038)
+ 5 JUCE Assertion failure in juce_LeakedObjectDetector.h:116
+ 2 JUCE Assertion failure in juce_MessageListener.cpp:50
+ (no juce_AudioUnitPluginFormatImpl.h:1346)
+
+# scripts/build.sh
+SMOKE TEST PASSED
+exit=0
+```
+
+## Residual Risks
+
+- The `--hostcheck` AUs are Apple's (AUSampler, AUVectorPanner), both stereo. A mono-output AU (now handed 1 channel) and the
+ reporter's Massive AU were not exercised.
+- The reporter's dropouts had a second cause that this fix does not cover: the engine in `build/` had been reconfigured as Debug
+ (-O0) and the app ran under netcoredbg. The VSCodium setup now keeps `build/` Release (CMake Tools → `build-debug/`). On a
+ -O0 engine, heavy projects can still drop out regardless of this fix.
+- The VST3 path is unchanged by construction but was not exercised with a layout-changing plug-in.
+
+## Recommendation
+
+Hold for one manual check, then close. Open the AU project in the app with **Run Nota** (Release engine): no dropouts. Then open
+it once with **Nota + Debug engine (LLDB)**: no `:1346`. If Reaktor 6 is handy, switch its Play/Patch/Build modes once to confirm
+the VST3 guard. Before merging, move the change to its own `fix/…` branch from `develop`, with a CHANGELOG `[Unreleased]` → Fixed
+entry (fix.md § Follow-ups).
diff --git a/CHANGELOG.md b/CHANGELOG.md
index d7a3e7d9..e2cb5084 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -26,6 +26,12 @@ Entry categories: `Added`, `Changed`, `Fixed`, `Removed`.
- **macOS: About Nota and Settings… sit directly in the Nota app menu** (nota-daw/nota#160):
they used to hide inside an extra **Nota ›** submenu. The bold **Nota** menu now opens
with About Nota, then Settings… (⌘,), then Services, Hide and Quit, as in other Mac apps.
+- **macOS: Audio Unit plug-ins no longer waste work on every audio block**: since 0.52.1 Nota
+ handed each AU 31 audio channels instead of the two it was set up for, so the plug-in
+ copied the extra channels every block and grabbed memory on the audio thread on the first
+ one. In debug builds this printed a JUCE assertion per block and caused dropouts. AUs now get
+ exactly their own channels; VST3 plug-ins keep the extra headroom that stops them crashing
+ when they change their inputs or outputs.
## [0.56.1] — 2026-10-19
diff --git a/src/native/nota.engine/pluginhost/PluginHost.cpp b/src/native/nota.engine/pluginhost/PluginHost.cpp
index 7c378105..2a8c6956 100644
--- a/src/native/nota.engine/pluginhost/PluginHost.cpp
+++ b/src/native/nota.engine/pluginhost/PluginHost.cpp
@@ -405,17 +405,25 @@ constexpr int kNoAllocChans = 31;
// VST3 plugin can widen its layout at any moment (restartComponent kIoChanged → JUCE
// re-prepares it on the message thread, e.g. Reaktor switching Play/Patch/Build) — so the
// buffer is never narrower than the plugin's current layout, with headroom for a change that
-// lands between this read and processBlock. Returns the channel count. Audio thread.
+// lands between this read and processBlock. That headroom is VST3-only (`minChans` from
+// minProcessChannels): the AU wrapper copies the buffer into one sized for the layout it was
+// prepared with, so a wider buffer asserts and reallocates there — an AU gets exactly its
+// layout. Returns the channel count. Audio thread.
int pluginChannelPtrs(const juce::AudioProcessor& p, juce::AudioBuffer<float>& storage,
- float* spare, int frames, float* (&ptrs)[kMaxChans]) {
+ float* spare, int frames, int minChans, float* (&ptrs)[kMaxChans]) {
const int have = juce::jmin(storage.getNumChannels(), kMaxChans);
- const int want = juce::jmin(kMaxChans, juce::jmax(kNoAllocChans, have,
+ const int want = juce::jmin(kMaxChans, juce::jmax(minChans > 0 ? juce::jmax(minChans, have) : 1,
p.getTotalNumInputChannels(), p.getTotalNumOutputChannels()));
if (want > have) juce::FloatVectorOperations::clear(spare, frames);
for (int c = 0; c < want; ++c) ptrs[c] = c < have ? storage.getWritePointer(c) : spare;
return want;
}
+// The floor pluginChannelPtrs gets for this plugin. Message thread, at prepare.
+int minProcessChannels(const juce::AudioPluginInstance& p) {
+ return p.getPluginDescription().pluginFormatName == "VST3" ? kNoAllocChans : 0;
+}
+
// Turn on every bus the plugin has, keeping the main buses as the caller set them. JUCE hands
// an inactive VST3 bus to process() with null channel pointers (HostBufferMapper), and some
// multi-output instruments (Vienna Synchron Pianos) write to every output bus regardless —
@@ -739,7 +747,7 @@ public:
: juce::MidiMessage::noteOff(1, g.pitch), 0);
storage_.clear();
float* ptrs[kMaxChans];
- juce::AudioBuffer<float> block(ptrs, pluginChannelPtrs(*plugin_, storage_, spare_.data(), frames, ptrs), frames);
+ juce::AudioBuffer<float> block(ptrs, pluginChannelPtrs(*plugin_, storage_, spare_.data(), frames, chanFloor_, ptrs), frames);
plugin_->processBlock(block, pending_);
pending_.clear();
const float* l = block.getReadPointer(0);
@@ -813,12 +821,14 @@ private:
storage_.setSize(juce::jmax(2, plugin_->getTotalNumInputChannels(), plugin_->getTotalNumOutputChannels()), maxBlock_);
stereoOut_ = plugin_->getBusCount(false) > 0 && plugin_->getChannelCountOfBus(false, 0) > 1;
spare_.assign((size_t)maxBlock_, 0.0f);
+ chanFloor_ = minProcessChannels(*plugin_);
}
NotaPlayHead playHead_; // declared first: outlives plugin_ (which points at it)
std::unique_ptr<juce::AudioPluginInstance> plugin_;
juce::AudioBuffer<float> storage_;
std::vector<float> spare_; // the channels past storage_ (see pluginChannelPtrs)
+ int chanFloor_ = 0; // pluginChannelPtrs floor (see minProcessChannels)
juce::MidiBuffer pending_;
int maxBlock_;
bool stereoOut_ = true; // main output bus has a channel 1 (see prepare)
@@ -872,6 +882,7 @@ public:
stereoIn_ = plugin_->getBusCount(true) > 0 && plugin_->getChannelCountOfBus(true, 0) > 1;
stereoOut_ = plugin_->getBusCount(false) > 0 && plugin_->getChannelCountOfBus(false, 0) > 1;
spare_.assign((size_t)maxBlock_, 0.0f);
+ chanFloor_ = minProcessChannels(*plugin_);
if (hasSidechain_ && plugin_->getBus(true, 1) != nullptr) {
scChanOffset_ = plugin_->getChannelIndexInProcessBlockBuffer(true, 1, 0);
scNumChans_ = plugin_->getBus(true, 1)->getNumberOfChannels();
@@ -905,7 +916,7 @@ public:
scBuf_ = nullptr; // consume once; the engine re-hands it each block if a source is set
float* ptrs[kMaxChans];
- juce::AudioBuffer<float> block(ptrs, pluginChannelPtrs(*plugin_, storage_, spare_.data(), frames, ptrs), frames);
+ juce::AudioBuffer<float> block(ptrs, pluginChannelPtrs(*plugin_, storage_, spare_.data(), frames, chanFloor_, ptrs), frames);
empty_.clear();
plugin_->processBlock(block, empty_);
@@ -990,6 +1001,7 @@ private:
int scChanOffset_ = -1, scNumChans_ = 0; // where its channels sit in the process buffer
juce::AudioBuffer<float> storage_;
std::vector<float> spare_; // the channels past storage_ (see pluginChannelPtrs)
+ int chanFloor_ = 0; // pluginChannelPtrs floor (see minProcessChannels)
juce::MidiBuffer empty_;
int maxBlock_ = 0;
bool stereoIn_ = true, stereoOut_ = true; // main buses have a channel 1 (see setSampleRate)