Repository navigation
P0: sample-accurate FX bypass de-click, zero added latency and cross-thread reconciliation #107
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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; | ||
| }; | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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; | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
When recalling a preset containing a latency-bearing VST3, every staged
Slotstill has its defaultlatency = 0when passed toprepare(). 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 👍 / 👎.