Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/p1-windows.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
3 changes: 3 additions & 0 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
27 changes: 27 additions & 0 deletions docs/ARSONMIX_CROSS_THREAD_HANDOFF_20261028.md
Original file line number Diff line number Diff line change
@@ -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.
84 changes: 84 additions & 0 deletions engine/core/FxBypassEnvelope.h
Original file line number Diff line number Diff line change
@@ -0,0 +1,84 @@
// SPDX-License-Identifier: AGPL-3.0-only
#pragma once
#include <algorithm>
#include <cmath>

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<float>(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::min(target,wet_+step_);
else 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;
};
}
47 changes: 45 additions & 2 deletions src/LiveAudioEngine.h
Original file line number Diff line number Diff line change
Expand Up @@ -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 <array>
#include <atomic>
#include <cmath>
Expand Down Expand Up @@ -45,6 +46,9 @@ class LiveAudioEngine final : private juce::AudioIODeviceCallback
{
std::array<Slot, maxFx> slots {};
std::array<std::atomic<bool>, maxFx> bypassFlags {};
// Owned and advanced exclusively by the realtime render callback.
// Physical-slot identity survives an atomic logical reorder (PR #102).
std::array<armix::dsp::FxBypassEnvelope, maxFx> bypassEnvelope {};
int count = 0;
int latency = 0;
bool hasRecallState = false;
Expand All @@ -57,6 +61,8 @@ class LiveAudioEngine final : private juce::AudioIODeviceCallback
{
formats_.addFormat (std::make_unique<juce::VST3PluginFormat>());
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());
}

Expand Down Expand Up @@ -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();
Comment on lines +686 to 688

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Read restored plugin latency before preparing its bypass envelope

When recalling a preset containing a latency-bearing VST3, every staged Slot still has its default latency = 0 when passed to prepare(). The actual latency is read immediately afterward, but the envelope retains zero internally. Subsequent bypass toggles therefore use the zero-latency wet/dry crossfade instead of switching at silence, mixing time-misaligned signals and introducing comb filtering or cancellation during the transition. Since live recall does not restart the device, this persists until a later device restart. Populate the slot latency before preparing its envelope.

Useful? React with 👍 / 👎.

if (!staged->slots[i].bypass) staged->latency += staged->slots[i].latency;
}
Expand All @@ -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;i<graphOwned_->count;++i)
if(!graphOwned_->bypassFlags[i].load(std::memory_order_acquire))
activeLatency+=graphOwned_->slots[i].latency;
totalLatency_.store(activeLatency,std::memory_order_release);
return true;
}

Expand Down Expand Up @@ -996,6 +1011,7 @@ class LiveAudioEngine final : private juce::AudioIODeviceCallback
armix::rt::LiveGraphHandoff<Graph> handoff_;
bool attached_ = false;
juce::AudioBuffer<float> scratch_;
juce::AudioBuffer<float> dryScratch_;
armix::diagnostics::DiagnosticTone diagnosticTone_;
std::atomic<armix::diagnostics::Route> diagnosticRoute_ {armix::diagnostics::Route::normal};
std::atomic<bool> routeReconfiguring_ {false};
Expand Down Expand Up @@ -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);
Expand Down Expand Up @@ -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);
Expand All @@ -1252,6 +1282,19 @@ class LiveAudioEngine final : private juce::AudioIODeviceCallback
if (static_cast<double> (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<frames;++i)
{
const auto g=bypass.next();
wetL[i]=g.wet*wetL[i]+g.dry*dryL[i];
wetR[i]=g.wet*wetR[i]+g.dry*dryR[i];
}
}
midi.clear();
}
}
Expand Down
49 changes: 49 additions & 0 deletions tests/fx_bypass_envelope_test.cpp
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
// SPDX-License-Identifier: AGPL-3.0-only
#include "../engine/core/FxBypassEnvelope.h"
#include <cmath>
#include <iostream>
static int failures=0;
static void check(bool ok,const char* name){if(!ok){++failures;std::cerr<<"FAIL "<<name<<"\n";}}
int main() {
using armix::dsp::FxBypassEnvelope;
// Hard bypass must not change gain abruptly. 48 kHz * 8 ms = 384 samples.
FxBypassEnvelope e;e.prepare(false,48000,0);
check(!e.transitioning() && e.shouldProcessWet(),"steady wet fast path");
e.request(true);
check(e.transitioning() && e.shouldProcessWet(),"first bypass block processes FX");
auto last=e.next();check(last.wet>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;
}
10 changes: 10 additions & 0 deletions tests/live_graph_contract_test.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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/);
});
Loading