diff --git a/.github/workflows/p1-windows.yml b/.github/workflows/p1-windows.yml index 104d14d8f..8a6a85a3b 100644 --- a/.github/workflows/p1-windows.yml +++ b/.github/workflows/p1-windows.yml @@ -63,7 +63,7 @@ jobs: -DBUILD_TESTING=ON -DJUCE_WEBVIEW2_PACKAGE_LOCATION="${{ github.workspace }}/.deps" - name: Build executable and native RT tests - run: cmake --build build --config Release --target ARMixConsole ARMixWorkspaceTests ARMixVaultTests ARMixOrbitPhaseTests ARMixOrbitControlTests ARMixOrbitMotionTests ARMixOrbitDistanceTests ARMixDearVrPolarPolicyTests ARMixRTTests ARMixPresetTests ARMixDiagnosticTests ARMixClockBridgeTests ARMixVirtualClockSoakTests ARMixCadenceTests ARMixCrackleWindowTests ARMixHealthTests ARMixPolicyTests ARMixPeriodEvidenceTests ARMixLifecycleTests ARMixWasapiProbeTests ARMixDualJuceTests ARMixClockSizingTests ARMixIndependentFormatTests ARMixRecoveryTests ARMixStreamWatchdogTests ARMixBridgeContinuityTests ARMixEndpointPolicyTests ARMixEndpointGuardTests ARMixAsioPolicyTests ARMixAsioBackendTests ARMixAsioRegistryIdentityTests ARMixDirectFenceTests --parallel 2 + run: cmake --build build --config Release --target ARMixConsole ARMixWorkspaceTests ARMixVaultTests ARMixOrbitPhaseTests ARMixOrbitControlTests ARMixOrbitMotionTests ARMixOrbitDistanceTests ARMixFxBypassEnvelopeTests ARMixDearVrPolarPolicyTests ARMixRTTests ARMixPresetTests ARMixDiagnosticTests ARMixClockBridgeTests ARMixVirtualClockSoakTests ARMixCadenceTests ARMixCrackleWindowTests ARMixHealthTests ARMixPolicyTests ARMixPeriodEvidenceTests ARMixLifecycleTests ARMixWasapiProbeTests ARMixDualJuceTests ARMixClockSizingTests ARMixIndependentFormatTests ARMixRecoveryTests ARMixStreamWatchdogTests ARMixBridgeContinuityTests ARMixEndpointPolicyTests ARMixEndpointGuardTests ARMixAsioPolicyTests ARMixAsioBackendTests ARMixAsioRegistryIdentityTests ARMixDirectFenceTests --parallel 2 - name: Test realtime control primitives run: ctest --test-dir build -C Release --output-on-failure - name: Package verified JUCE GUI for hardware FAT diff --git a/CMakeLists.txt b/CMakeLists.txt index 3af1c2451..5982b680c 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -131,6 +131,9 @@ if(BUILD_TESTING) target_compile_features(ARMixVirtualClockSoakTests PRIVATE cxx_std_20) add_test(NAME IndependentClockASRCDriftJitterSoak COMMAND ARMixVirtualClockSoakTests) set_tests_properties(IndependentClockASRCDriftJitterSoak PROPERTIES TIMEOUT 30) + add_executable(ARMixFxBypassEnvelopeTests tests/fx_bypass_envelope_test.cpp) + target_compile_features(ARMixFxBypassEnvelopeTests PRIVATE cxx_std_20) + add_test(NAME P0FXBypassSampleAccurateDeClick COMMAND ARMixFxBypassEnvelopeTests) add_executable(ARMixCrackleWindowTests tests/crackle_evidence_window_test.cpp) target_compile_features(ARMixCrackleWindowTests PRIVATE cxx_std_20) add_test(NAME P0PreMarkerFiveSecondEvidenceWindow COMMAND ARMixCrackleWindowTests) diff --git a/docs/ARSONMIX_CROSS_THREAD_HANDOFF_20261028.md b/docs/ARSONMIX_CROSS_THREAD_HANDOFF_20261028.md new file mode 100644 index 000000000..550b4ecbb --- /dev/null +++ b/docs/ARSONMIX_CROSS_THREAD_HANDOFF_20261028.md @@ -0,0 +1,27 @@ +# ArSonMix cross-thread engineering reconciliation — 2026-10-28 + +## Latest authoritative baseline +- Base main when the fix was authored: `de683b001a5a1e5e050bc20ddb52d32b22fa58d1` (merged PR #105). Read the latest GitHub `main` again before every integration. +- Preserved: accepted dearVR PRO 2 Orbit/POLAR UX (PR #105), contextual Near/Far 2 m display (PR #103), native MASTER LED visibility (PR #104), latest approved meter/GUI. **Do not** replace source with older handoff branches. +- Hardware reality: only native Channel 1 VST3/DSP is qualified, other strips remain UI previews. No deceptive CH2-10 feature claims. +- Issue #15: zero-plugin crackles still NOT proven resolved. Hardware report: 48k/480 WASAPI DIRECT, VB Cable capture to Space Travel 2 render, 117 capture discontinuities, 15 before MARK CRACKLE; DSP callback worst 92us, no budget overruns. Backend count is CAPTURE, not measured render underruns. Existing Smart Clock Independent is a manual A/B test, not an automatic cure. + +## Present changes — bypass de-click +- Root cause: `setBypass` published a bare atomic flag consumed by the RT callback, instantly changing from processed to dry samples at a buffer edge. +- New per-physical-slot `FxBypassEnvelope`: zero-latency plugin wet/dry gain crossfades over ~8 ms, equal-sum linear; high-latency plugin switches only at silence (8 ms down then 8 ms up) to avoid mixing non-aligned dry/wet and combing. +- All state owned by RT callback; control publishes only desired bypass. No locks, heap, audio-thread WebView calls, graph rebuild, restart, or additional device buffer. Dry stereo scratch preallocated on the control thread. Steady active/bypassed paths have no blend copy, bypassed plugin processBlock is skipped. Latency counter updated only on control thread. +- Graph handoff initialises bypass state for preset recall; device restarts reset envelope from actual flags. Under plugin order reconfiguration, keep transition state indexed by physical processor, not logical GUI index. +- CI: a single existing Windows pipeline builds `ARMixFxBypassEnvelopeTests` and runs CTest; existing Node contract covers callback wiring. Never create a second Windows distributor. PR screenshots/browser flow remain unaffected. + +## Parallel PR integration order and conflict guard +- PR #102 (DAW drag/drop, lock-free atomic MOVE, flattened fader): OPEN. It touches `src/LiveAudioEngine.h` and `web/bridge.js`; currently GitHub says MERGE CONFLICT. Do **not** merge #102 blindly; rebase it on the accepted main and preserve the bypass-envelope code and physical-slot association; run both reorder and bypass tests after reconciliation. Its structural ADD/REMOVE implementation remains distinct from ON/OFF bypass; do not claim audio click-free on structural operations by fixing bypass only. +- PR #106 (meter ballistics): OPEN, Chromium PASS; do not overwrite current GUI CSS/JS and do not merge until Windows/native tests succeed and current main is reconciled. +- PR #101 (lean CI): OPEN, needs independent review and status/required-check compatibility. Do not cherry-pick old source or trigger multiple Windows builds. +- Other legacy PRs (#97/#60/#59/#29/#26/#25 and old P1/P2 PRs): historical/experimental; check staleness and conflicts before any rebase/merge. +- This handoff is a snapshot, not a guaranteed global lock. Any thread must read current main SHA and open PR status at time of change. + +## FAT acceptance +1. Add a low-latency VST3, start steady music/voice, toggle ON/OFF multiple times, listen for click at the transition. Try rapid toggle and multiple FX. +2. Repeat with high-latency plugin; a brief ~16ms level dip is expected; hard crackles are not. +3. Verify no CPU spikes, overruns, latency regressions or Orbit interruption. Test actual ASIO/WASAPI devices; browser smoke cannot establish acoustic absence of clicks. +4. Separately test zero-plugin WASAPI crackles per Issue #15, with DIRECT vs opt-in Independent mode and output-only tone diagnostic. diff --git a/engine/core/FxBypassEnvelope.h b/engine/core/FxBypassEnvelope.h new file mode 100644 index 000000000..3c3174976 --- /dev/null +++ b/engine/core/FxBypassEnvelope.h @@ -0,0 +1,84 @@ +// SPDX-License-Identifier: AGPL-3.0-only +#pragma once +#include +#include + +namespace armix::dsp { +// RT-only instance per physical FX slot. The control thread publishes ONLY +// the requested bypass flag; no locks/heap/plugin GUI access in audio callback. +// +// Zero-latency processors: 8ms linear wet/dry crossfade (no gain jump). +// Latency-bearing processors: fade-out / source switch at exact silence / +// fade-in. Do not sum time-misaligned dry and wet and introduce comb filtering. +// A delayed plugin may still need a latency-aligned bypass for seamless tails; +// this intentionally prioritizes click avoidance and zero extra latency. +class FxBypassEnvelope final +{ +public: + struct Gains {float wet=0.f, dry=1.f;}; + void prepare(bool bypass, double sampleRate, int pluginLatency) noexcept + { + const double rate=std::isfinite(sampleRate)?std::clamp(sampleRate,8000.,384000.):48000.; + const double length=std::clamp(rate*0.008,64.,4096.); + step_=static_cast(1.0/length); + latency_=std::max(0,pluginLatency); + wet_=bypass?0.f:1.f; + currentWet_=!bypass; + targetWet_=!bypass; + amplitude_=1.f; + stage_=Stage::steady; + } + void request(bool bypass) noexcept + { + const bool wantWet=!bypass; + if(wantWet==targetWet_)return; + targetWet_=wantWet; + if(latency_==0)return; + if(stage_==Stage::steady)stage_=Stage::down; + else if(stage_==Stage::down && targetWet_==currentWet_)stage_=Stage::up; + else if(stage_==Stage::up && targetWet_!=currentWet_)stage_=Stage::down; + } + bool transitioning() const noexcept + { + return latency_==0 ? wet_!=(targetWet_?1.f:0.f) : stage_!=Stage::steady; + } + bool shouldProcessWet() const noexcept + { + return latency_==0 ? wet_>0.f||targetWet_ : + currentWet_||targetWet_||stage_!=Stage::steady; + } + Gains next() noexcept + { + if(latency_==0) + { + const float target=targetWet_?1.f:0.f; + if(wet_target)wet_=std::max(target,wet_-step_); + return {wet_,1.f-wet_}; + } + if(stage_==Stage::down) + { + amplitude_=std::max(0.f,amplitude_-step_); + if(amplitude_<=0.f) + { + amplitude_=0.f; + currentWet_=targetWet_; + stage_=Stage::up; + } + } + else if(stage_==Stage::up) + { + amplitude_=std::min(1.f,amplitude_+step_); + if(amplitude_>=1.f)stage_=Stage::steady; + } + return currentWet_?Gains{amplitude_,0.f}:Gains{0.f,amplitude_}; + } + bool fullyBypassed() const noexcept {return !transitioning() && !shouldProcessWet();} +private: + enum class Stage : unsigned char {steady,down,up}; + Stage stage_=Stage::steady; + float wet_=1.f, amplitude_=1.f, step_=1.f/384.f; + int latency_=0; + bool currentWet_=true,targetWet_=true; +}; +} diff --git a/src/LiveAudioEngine.h b/src/LiveAudioEngine.h index bead8706f..b25357a2e 100644 --- a/src/LiveAudioEngine.h +++ b/src/LiveAudioEngine.h @@ -14,6 +14,7 @@ #include "../engine/device/WasapiEndpointIdentityGuard.h" #include "../engine/core/RealtimeHealthHistogram.h" #include "../engine/core/CallbackCadenceEvidence.h" +#include "../engine/core/FxBypassEnvelope.h" #include #include #include @@ -45,6 +46,9 @@ class LiveAudioEngine final : private juce::AudioIODeviceCallback { std::array slots {}; std::array, maxFx> bypassFlags {}; + // Owned and advanced exclusively by the realtime render callback. + // Physical-slot identity survives an atomic logical reorder (PR #102). + std::array bypassEnvelope {}; int count = 0; int latency = 0; bool hasRecallState = false; @@ -57,6 +61,8 @@ class LiveAudioEngine final : private juce::AudioIODeviceCallback { formats_.addFormat (std::make_unique()); scratch_.setSize (2, maxFrames, false, true, false); + // One reusable preallocated stereo dry snapshot for transient FX bypass. + dryScratch_.setSize (2, maxFrames, false, true, false); handoff_.initialize (graphOwned_.get()); } @@ -677,6 +683,8 @@ class LiveAudioEngine final : private juce::AudioIODeviceCallback for (int i = 0; i < staged->count; ++i) { staged->bypassFlags[i].store (staged->slots[i].bypass, std::memory_order_relaxed); + staged->bypassEnvelope[i].prepare (staged->slots[i].bypass, rate, + staged->slots[i].latency); staged->slots[i].latency = staged->slots[i].processor->getLatencySamples(); if (!staged->slots[i].bypass) staged->latency += staged->slots[i].latency; } @@ -696,6 +704,13 @@ class LiveAudioEngine final : private juce::AudioIODeviceCallback // Message-thread metadata and an atomic value consumed by the audio thread. graphOwned_->slots[index].bypass = value; graphOwned_->bypassFlags[index].store (value, std::memory_order_release); + // Recompute the advertised steady-state graph latency on the control + // thread. The audible transition is managed sample-by-sample by RT. + int activeLatency=0; + for(int i=0;icount;++i) + if(!graphOwned_->bypassFlags[i].load(std::memory_order_acquire)) + activeLatency+=graphOwned_->slots[i].latency; + totalLatency_.store(activeLatency,std::memory_order_release); return true; } @@ -996,6 +1011,7 @@ class LiveAudioEngine final : private juce::AudioIODeviceCallback armix::rt::LiveGraphHandoff handoff_; bool attached_ = false; juce::AudioBuffer scratch_; + juce::AudioBuffer dryScratch_; armix::diagnostics::DiagnosticTone diagnosticTone_; std::atomic diagnosticRoute_ {armix::diagnostics::Route::normal}; std::atomic routeReconfiguring_ {false}; @@ -1109,7 +1125,9 @@ class LiveAudioEngine final : private juce::AudioIODeviceCallback slot.processor->prepareToPlay (d->getCurrentSampleRate(), juce::jmax (32, d->getCurrentBufferSizeSamples())); slot.latency = slot.processor->getLatencySamples(); - if (!graphOwned_->bypassFlags[i].load (std::memory_order_relaxed)) latency += slot.latency; + const bool bypass=graphOwned_->bypassFlags[i].load (std::memory_order_relaxed); + graphOwned_->bypassEnvelope[i].prepare(bypass,sampleRateHz_,slot.latency); + if (!bypass) latency += slot.latency; } } totalLatency_.store (latency); @@ -1241,7 +1259,19 @@ class LiveAudioEngine final : private juce::AudioIODeviceCallback for (int fx = 0; fx < cycle.graph->count; ++fx) { auto& slot = cycle.graph->slots[fx]; - if (slot.processor && ! cycle.graph->bypassFlags[fx].load (std::memory_order_relaxed)) + if (!slot.processor) {midi.clear();continue;} + auto& bypass=cycle.graph->bypassEnvelope[fx]; + bypass.request(cycle.graph->bypassFlags[fx].load(std::memory_order_acquire)); + // Steady wet/dry requires no copy or extra arithmetic. + // A transition temporarily snapshots the exact input to + // this insert; a second full FX graph is never created. + const bool blend=bypass.transitioning(); + if (blend) + for(int ch=0;ch<2;++ch) + juce::FloatVectorOperations::copy( + dryScratch_.getWritePointer(ch), + scratch_.getReadPointer(ch),frames); + if (bypass.shouldProcessWet()) { const auto pluginBeginUs = clockMicros(); slot.processor->processBlock (scratchView, midi); @@ -1252,6 +1282,19 @@ class LiveAudioEngine final : private juce::AudioIODeviceCallback if (static_cast (pluginUs) > periodUs * 0.75) slowPlugins_.fetch_add (1, std::memory_order_relaxed); } + if (blend) + { + float* wetL=scratch_.getWritePointer(0); + float* wetR=scratch_.getWritePointer(1); + const float* dryL=dryScratch_.getReadPointer(0); + const float* dryR=dryScratch_.getReadPointer(1); + for(int i=0;i +#include +static int failures=0; +static void check(bool ok,const char* name){if(!ok){++failures;std::cerr<<"FAIL "<0.f && last.wet<1.f,"no immediate dry jump"); + check(std::abs(last.wet+last.dry-1.f)<0.00001f,"unity sum"); + for(int i=1;i<500;++i){ + auto now=e.next(); + check(std::abs(now.wet-last.wet)<0.004f,"bounded sample ramp"); + check(std::abs(now.wet+now.dry-1.f)<0.00001f,"crossfade unity sum"); + last=now; + } + check(e.fullyBypassed(),"DSP skipped when stable bypass"); + e.request(false); + check(e.transitioning() && e.shouldProcessWet(),"reactivate processes wet during ramp"); + last=e.next();check(last.wet>0.f && last.wet<1.f,"reactivate not jump to wet"); + for(int i=0;i<500;++i)last=e.next(); + check(!e.transitioning() && e.shouldProcessWet(),"fully active after fade"); + // Discontinuous rapid user commands must be bounded; do not reset to + // silence or to an endpoint abruptly. + e.request(true);for(int i=0;i<50;++i)last=e.next(); + const auto atToggle=last; + e.request(false);last=e.next(); + check(std::abs(last.wet-atToggle.wet)<0.004f,"rapid reverse continuous"); + // With plugin latency, never mix time-misaligned wet and dry; switch at zero. + FxBypassEnvelope delayed;delayed.prepare(false,48000,512); + delayed.request(true); + bool sawDry=false,sawZero=false; + for(int i=0;i<1000;++i){ + const auto x=delayed.next(); + check(x.wet==0.f||x.dry==0.f,"latency path never sums misaligned signals"); + if(x.wet==0.f&&x.dry==0.f)sawZero=true; + if(x.dry>0.f)sawDry=true; + } + check(sawZero && sawDry && delayed.fullyBypassed(),"latency switch at silence"); + delayed.request(false); + for(int i=0;i<1000;++i)last=delayed.next(); + check(!delayed.transitioning() && delayed.shouldProcessWet(),"delayed reactivation"); + return failures?1:0; +} diff --git a/tests/live_graph_contract_test.mjs b/tests/live_graph_contract_test.mjs index 86ce65738..ddd6b3984 100644 --- a/tests/live_graph_contract_test.mjs +++ b/tests/live_graph_contract_test.mjs @@ -32,3 +32,13 @@ test('old structural operations remain guarded and declared as unfinished',()=>{ assert.match(e,/if \(handoff_\.busy\(\)\) return false/); assert.match(e,/Legacy Add\/Remove\/Move still detach/); }); + +test('bypass is sample-smoothed on audio callback without control-thread CPU work',()=>{ + assert.match(e,/bypassEnvelope/); + assert.match(e,/bypass\.request\(cycle\.graph->bypassFlags/); + assert.match(e,/bypass\.transitioning\(\)/); + assert.match(e,/dryScratch_\.setSize \(2, maxFrames/); + assert.match(e,/bypass\.next\(\)/); + assert.match(e,/bypass\.shouldProcessWet\(\)/); + assert.doesNotMatch(e.slice(e.indexOf('bool setBypass'),e.indexOf('bool removeAt')),/detach\(|prepareToPlay|releaseResources/); +});