Skip to content
Closed
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
9 changes: 9 additions & 0 deletions docs/P0_WASAPI_CAPTURE_DECLICK_EXPERIMENT_20261031.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
# P0 WASAPI capture click experiment — explicit muted A/B only

This milestone is an intentionally **OFF-by-default** candidate for real hardware FAT. It never automatically modifies capture PCM on startup, device reopen, Show recall or ASIO. After choosing a verified Windows Audio DIRECT capture/render pair, the operator must **MUTE OUTPUT** and enable **CAPTURE DE-CLICK: ON (BETA)** in SIGNAL CHECK. Then manually START AUDIO at low headphone volume. It disables itself at every audio device generation and does not apply to independent dual-clock mode or isolated tone/capture routes.

When ON, only candidate exact-zero-head discontinuities in stereo capture cause a bounded 64-frame prepared copy/repair (or invalid-sample sanitization); ordinary healthy blocks remain zero-copy. Candidate zero-head is NOT driver-proven xrun. An artificial zero prefix could be legitimate digital silence; compare against OFF under identical conditions and listen for coloration/artifacts. There is no proof of repaired or missing audio samples. No automatic output arm, buffer change, SRC, clock restart or additional DSP graph.

**FAT:** 0 FX, 48k/480 where supported, VB-Cable CABLE Output → MAONO wired out; A: OFF capture 5 user MARK CRACKLE windows, COPY FULL REPORT; B: MUTE → enable BETA → manual START AUDIO, capture 5 windows. Record raw capture candidate blocks/frames, repair blocks/frames, WASAPI capture discontinuity flags, sample rate/clock/endpoint/actual callback, post MAIN peak, audible change and any unintended tones. Repeat real MAONO ASIO/direct (BETA must be unavailable). Compare output-only isolated tone (BETA must be unavailable). A hardware clean run >=30 minutes is required before considering making the feature a recommendation; **do not automatically enable it in production**. P0 issue #15 remains open.

Benchmark for Console UI/navigation remains the official [Fender Studio Pro Console](https://fenderstudiopromanual.fender.com/en/Content/Mixing_Topics/The_Console.htm). This feature is a hidden opt-in engineering diagnostic, not an everyday Studio I/O step.
85 changes: 85 additions & 0 deletions engine/core/CaptureClickRepair.h
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
// SPDX-License-Identifier: AGPL-3.0-only
#pragma once
#include <algorithm>
#include <array>
#include <atomic>
#include <cmath>
#include <cstdint>

namespace armix::rt {
// P0: no extra FIFO, resampler, or callback latency. Only a verified stereo
// WASAPI DIRECT exceptional block is copied into caller-prepared scratch.
// The upstream evidence is a heuristic, NOT a driver-proven discontinuity.
// Healthy PCM never crosses this memory copy or changes a single sample.
class CaptureClickRepair final {
public:
static constexpr int minZeroHead=32;
static constexpr int maxRamp=64;
void reset() noexcept {
previous_.fill(0.f);
repairedBlocks_.store(0,std::memory_order_relaxed);
repairedFrames_.store(0,std::memory_order_relaxed);
sanitizedSamples_.store(0,std::memory_order_relaxed);
}
void clearCarry() noexcept { previous_.fill(0.f); }
bool process(const float* const* input,int channels,int frames,
int candidateHead,bool hasNonFinite,
float* outL,float* outR) noexcept {
if(!input || channels!=2 || frames<=0 || !input[0] || !input[1]) {
clearCarry();return false;
}
const auto previous=previous_;
previous_[0]=std::isfinite(input[0][frames-1])?input[0][frames-1]:0.f;
previous_[1]=std::isfinite(input[1][frames-1])?input[1][frames-1]:0.f;
const bool fade=candidateHead>=minZeroHead && candidateHead<frames &&
!hasNonFinite &&
(std::abs(previous[0])>=0.002f || std::abs(previous[1])>=0.002f);
if(!fade&&!hasNonFinite)return false; // common RT fast path
if(!outL||!outR)return false;
std::uint64_t invalid=0;
for(int i=0;i<frames;++i) {
const float l=input[0][i],r=input[1][i];
const bool okL=std::isfinite(l),okR=std::isfinite(r);
invalid+=static_cast<unsigned>(!okL)+static_cast<unsigned>(!okR);
outL[i]=okL?l:0.f;
outR[i]=okR?r:0.f;
}
if(invalid)sanitizedSamples_.fetch_add(invalid,std::memory_order_relaxed);
if(fade) {
const int tail=std::min(maxRamp,candidateHead);
const int resume=std::min(maxRamp,frames-candidateHead);
// Fade the last valid sample into an exact zero head rather than
// abruptly cutting at a callback boundary; ease resumption too.
// Bounded 1.33ms envelope at 48k; zero new samples of latency.
for(int i=0;i<tail;++i) {
const float g=1.f-static_cast<float>(i+1)/static_cast<float>(tail);
outL[i]=previous[0]*g;outR[i]=previous[1]*g;
}
for(int i=0;i<resume;++i) {
const int p=candidateHead+i;
const float g=static_cast<float>(i+1)/static_cast<float>(resume);
outL[p]*=g;outR[p]*=g;
}
repairedBlocks_.fetch_add(1,std::memory_order_relaxed);
repairedFrames_.fetch_add(static_cast<std::uint64_t>(tail+resume),
std::memory_order_relaxed);
}
return true;
}
std::uint64_t repairedBlocks() const noexcept {
return repairedBlocks_.load(std::memory_order_relaxed);
}
std::uint64_t repairedFrames() const noexcept {
return repairedFrames_.load(std::memory_order_relaxed);
}
std::uint64_t sanitizedSamples() const noexcept {
return sanitizedSamples_.load(std::memory_order_relaxed);
}
static constexpr const char* provenance() noexcept {
return "STEREO_WASAPI_ZERO_HEAD_BOUNDED_DECLICK_NOT_CLOCK_DRIFT_OR_RENDER_XRUN_FIX";
}
private:
std::array<float,2> previous_{}; // only native callback owns it
std::atomic<std::uint64_t> repairedBlocks_{0},repairedFrames_{0},sanitizedSamples_{0};
};
}
65 changes: 64 additions & 1 deletion src/LiveAudioEngine.h
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@
#include "../engine/core/RealtimeHealthHistogram.h"
#include "../engine/core/CallbackCadenceEvidence.h"
#include "../engine/core/CaptureBoundaryEvidence.h"
#include "../engine/core/CaptureClickRepair.h"
#include "../engine/core/FxBypassEnvelope.h"
#include "../engine/core/NativeOutputPairTap.h"
#include <array>
Expand Down Expand Up @@ -99,6 +100,7 @@ class LiveAudioEngine final : private juce::AudioIODeviceCallback
{
formats_.addFormat (std::make_unique<juce::VST3PluginFormat>());
scratch_.setSize (2, maxFrames, false, true, false);
captureRepairScratch_.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 @@ -343,6 +345,25 @@ class LiveAudioEngine final : private juce::AudioIODeviceCallback
// Normal ASIO / verified single-clock devices remain on the zero-SRC
// JUCE direct callback. Independent capture/render is opt-in in P0.
bool independentClockActive() const noexcept { return independent_.active(); }
// P0 hardware experiment: OFF by default and never persisted. The user
// must explicitly mute MAIN before enabling/disabling this heuristic.
// Native callback still owns all repair history; no control-thread reset.
juce::String setCaptureDeClickEnabled (bool wanted)
{
if (monitor_.load (std::memory_order_acquire))
return "MUTE OUTPUT before toggling experimental capture de-click";
if (independent_.active() || hasPendingDirectRestore())
return "Return to verified DIRECT audio before capture de-click A/B";
if (diagnosticRoute() != armix::diagnostics::Route::normal)
return "Return SIGNAL CHECK to NORMAL before capture de-click A/B";
if (wanted && (deviceManager_.getCurrentAudioDevice() == nullptr ||
deviceManager_.getCurrentAudioDeviceType() != "Windows Audio" ||
!wasapiDirectCapture_.load (std::memory_order_acquire)))
return "Experimental capture de-click is only available on a verified DIRECT Windows Audio device";
captureDeClickRequested_.store (wanted, std::memory_order_release);
return {};
}

// Control-thread-only: true after an unsuccessful DIRECT rollback.
// The original endpoint selection is retained for bounded recovery.
bool hasPendingDirectRestore() const noexcept { return savedDirectSetup_.has_value(); }
Expand Down Expand Up @@ -1280,6 +1301,14 @@ class LiveAudioEngine final : private juce::AudioIODeviceCallback
o->setProperty ("captureZeroHeadCandidateFrames",static_cast<double>(captureBoundary_.candidateFrames()));
o->setProperty ("captureNonFiniteSamples",static_cast<double>(captureBoundary_.nonFiniteSamples()));
o->setProperty ("captureZeroHeadProvenance",armix::rt::CaptureBoundaryEvidence::provenance());
o->setProperty ("captureDeClickEnabled",captureDeClickRequested_.load(std::memory_order_acquire));
o->setProperty ("captureDeClickEligible",wasapiDirectCapture_.load(std::memory_order_acquire)
&& !independent_.active() && diagnosticRoute()==armix::diagnostics::Route::normal);
o->setProperty ("captureDeClickDefault","OFF_EXPLICIT_HARDWARE_AB_ONLY");
o->setProperty ("captureDeClickBlocks",static_cast<double>(captureClickRepair_.repairedBlocks()));
o->setProperty ("captureDeClickFrames",static_cast<double>(captureClickRepair_.repairedFrames()));
o->setProperty ("captureSanitizedSamples",static_cast<double>(captureClickRepair_.sanitizedSamples()));
o->setProperty ("captureDeClickProvenance",armix::rt::CaptureClickRepair::provenance());
o->setProperty ("postFxPeak", postFxPeak_.load());
o->setProperty ("peak", outputPeak_.load());
o->setProperty ("peakLeft", outputPeakL_.load());
Expand Down Expand Up @@ -1428,6 +1457,7 @@ class LiveAudioEngine final : private juce::AudioIODeviceCallback
std::atomic<std::uint64_t> fxMovePendingOrder_ {Graph::canonicalOrder};
bool attached_ = false;
juce::AudioBuffer<float> scratch_;
juce::AudioBuffer<float> captureRepairScratch_; // prepared stereo exceptional path
juce::AudioBuffer<float> dryScratch_;
armix::dsp::NativeMasterLoudness masterLoudness_;
armix::diagnostics::DiagnosticTone diagnosticTone_;
Expand All @@ -1441,6 +1471,9 @@ class LiveAudioEngine final : private juce::AudioIODeviceCallback
std::atomic<float> inputPeak_ { 0.f }, postFxPeak_ { 0.f }, outputPeak_ { 0.f };
std::atomic<std::uint64_t> captureSignalBlocks_ {0}; // per native device epoch
armix::rt::CaptureBoundaryEvidence captureBoundary_; // callback-only PCM continuity
armix::rt::CaptureClickRepair captureClickRepair_;
std::atomic<bool> captureDeClickRequested_{false}; // no auto restart/Show arm
std::atomic<bool> wasapiDirectCapture_{false};
std::atomic<float> outputPeakL_ { 0.f }, outputPeakR_ { 0.f };
std::atomic<int> callbackInputs_ { 0 }, callbackOutputs_ { 0 };
std::atomic<unsigned long long> callbackCount_ { 0 };
Expand Down Expand Up @@ -1531,6 +1564,10 @@ class LiveAudioEngine final : private juce::AudioIODeviceCallback
inputPeak_.store(0.f,std::memory_order_relaxed);
captureSignalBlocks_.store(0,std::memory_order_relaxed);
captureBoundary_.reset(); // only between device generations
captureClickRepair_.reset();
captureDeClickRequested_.store(false,std::memory_order_release); // device generations fail closed
wasapiDirectCapture_.store(d->getTypeName()=="Windows Audio",
std::memory_order_release);
deviceStartCount_.fetch_add (1, std::memory_order_relaxed);
sampleRateHz_ = juce::jmax (1.0, d->getCurrentSampleRate());
diagnosticTone_.prepare (sampleRateHz_); // device stopped; no RT allocation
Expand Down Expand Up @@ -1721,17 +1758,43 @@ class LiveAudioEngine final : private juce::AudioIODeviceCallback
const bool outputPermitted=outputGate.renderMain;
// Native input PCM must remain observable even with safe output MUTE.
// Scan bounded verified callback channels, no allocation or lock.
const auto priorCandidateBlocks=captureBoundary_.candidateBlocks();
const auto priorCandidateFrames=captureBoundary_.candidateFrames();
const auto priorInvalidSamples=captureBoundary_.nonFiniteSamples();
const float rawCapturePeak=captureBoundary_.observe(
inputs,juce::jmin(inputChannels,armix::device::LiveInputPortRegistry::limit),samples);
if(rawCapturePeak>0.0005f)
captureSignalBlocks_.fetch_add(1,std::memory_order_relaxed);
// Use PR #247's ONE existing raw capture scan to trigger a
// conditional de-click copy. The common case stays zero-copy and
// bit-identical through the single native mixer. Never change
// JUCE's const input pointers or retry/reopen on the RT thread.
const float* const* renderInputs=inputs;
std::array<const float*,2> guardedInputs{};
if(captureDeClickRequested_.load(std::memory_order_relaxed) &&
wasapiDirectCapture_.load(std::memory_order_relaxed) &&
inputChannels==2 && inputs && inputs[0] && inputs[1] &&
samples<=maxFrames) {
const bool zeroCandidate=captureBoundary_.candidateBlocks()!=priorCandidateBlocks;
const auto addedFrames=captureBoundary_.candidateFrames()-priorCandidateFrames;
const int head=zeroCandidate && addedFrames<=static_cast<std::uint64_t>(samples)
?static_cast<int>(addedFrames):0;
const bool nonFinite=captureBoundary_.nonFiniteSamples()!=priorInvalidSamples;
float* const destL=captureRepairScratch_.getWritePointer(0);
float* const destR=captureRepairScratch_.getWritePointer(1);
if(captureClickRepair_.process(inputs,inputChannels,samples,
head,nonFinite,destL,destR)) {
guardedInputs={{destL,destR}};
renderInputs=guardedInputs.data();
}
} else captureClickRepair_.clearCarry();
// Both native 10CH routing and the existing CH1 vendor FX chain
// execute in ONE stereo output render pass. Never mix a parallel
// CH1 output on top or copy vendor processors into another graph.
LegacyChannelOneLease ch1Lease{this,cycle.graph};
std::array<int,2> nativeMainPair{{-1,-1}};
std::array<int,2> nativeMonitorPair{{-1,-1}};
const bool routed=dryRoutingLab_.process(inputs,inputChannels,outputs,
const bool routed=dryRoutingLab_.process(renderInputs,inputChannels,outputs,
outputChannels,samples,
masterGain_.load(std::memory_order_relaxed),
!outputPermitted,&ch1Lease,&processLegacyChannelOne,
Expand Down
14 changes: 14 additions & 0 deletions src/Main.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -2010,6 +2010,20 @@ class ConsoleWindow final : public juce::DocumentWindow, private juce::Timer, pr
emitNotice ("Audio diagnostic: " + selected +
". Use low headphone volume and MARK CRACKLE on audible faults.");
}
else if (action == "captureDeClick")
{
const bool wanted=bool(value);
const auto error=engine_.setCaptureDeClickEnabled(wanted);
if(error.isNotEmpty()) {
diagnostics_.record("CAPTURE_DECLICK_REJECT",error);
return emitNotice(error,true);
}
diagnostics_.record("CAPTURE_DECLICK_EXPERIMENT",
wanted?"ENABLED_MANUALLY_MUTED_DIRECT_ONLY":"DISABLED_MANUALLY");
emitNotice(wanted
? "Experimental WASAPI capture de-click ON (not an xrun fix). START AUDIO manually; MARK CRACKLE for A/B evidence."
: "Experimental capture de-click OFF; direct PCM untouched.");
}
else if (action == "diagnosticMark")
{
const auto status = engine_.status();
Expand Down
47 changes: 47 additions & 0 deletions tests/capture_boundary_evidence_test.cpp
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
// SPDX-License-Identifier: AGPL-3.0-only
#include "../engine/core/CaptureBoundaryEvidence.h"
#include "../engine/core/CaptureClickRepair.h"
#include <array>
#include <cstdlib>
#include <cmath>
Expand Down Expand Up @@ -52,4 +53,50 @@ int main() {
l.fill(0);r.fill(0);p.observe(in,2,480);
check(p.candidateBlocks()==0);
check(std::strstr(P::provenance(),"NOT_DRIVER_XRUN")!=nullptr);
// One 480-frame buffer's candidate at most; no new FIFO/latency.
P evidence;
armix::rt::CaptureClickRepair repair;
std::array<float,480> outL{},outR{};
repair.reset();evidence.reset();
l.fill(.125f);r.fill(-.125f);
auto beforeBlock=evidence.candidateBlocks(),beforeFrames=evidence.candidateFrames();
evidence.observe(in,2,480);
check(!repair.process(in,2,480,0,false,outL.data(),outR.data()));
check(repair.repairedBlocks()==0);
for(int i=0;i<64;++i)l[i]=r[i]=0.f;
beforeBlock=evidence.candidateBlocks();beforeFrames=evidence.candidateFrames();
evidence.observe(in,2,480);
check(evidence.candidateBlocks()==beforeBlock+1);
const int head=static_cast<int>(evidence.candidateFrames()-beforeFrames);
check(head==64);
check(repair.process(in,2,480,head,false,outL.data(),outR.data()));
check(outL[0]>.12f&&outL[63]==0.f&&outL[64]>0.f&&outL[64]<.01f);
check(outR[0]<-.12f&&outR[63]==0.f&&r[0]==0.f); // immutable source
check(repair.repairedBlocks()==1&&repair.repairedFrames()==128);
// Full-block silence after a signal is NOT concealed as fake music.
l.fill(.125f);r.fill(-.125f);
evidence.observe(in,2,480);
repair.process(in,2,480,0,false,outL.data(),outR.data());
l.fill(0.f);r.fill(0.f);
evidence.observe(in,2,480);
check(!repair.process(in,2,480,480,false,outL.data(),outR.data()));
// Single-channel zero and honest music produce no repair.
l.fill(.125f);r.fill(-.125f);
repair.process(in,2,480,0,false,outL.data(),outR.data());
for(int i=0;i<64;++i)l[i]=0.f;
check(!repair.process(in,2,480,0,false,outL.data(),outR.data()));
// Non-finite PCM only enters prepared scratch on exceptional blocks.
l.fill(.25f);r.fill(-.25f);
l[21]=std::numeric_limits<float>::quiet_NaN();
check(repair.process(in,2,480,0,true,outL.data(),outR.data()));
check(outL[21]==0.f&&std::isfinite(outL[21])&&repair.sanitizedSamples()==1);
repair.reset();evidence.reset();
check(repair.repairedBlocks()==0&&repair.sanitizedSamples()==0);
l.fill(.125f);r.fill(-.125f);
for(int i=0;i<100000;++i){
evidence.observe(in,2,480);
check(!repair.process(in,2,480,0,false,outL.data(),outR.data()));
}
check(repair.repairedBlocks()==0&&repair.sanitizedSamples()==0);
check(std::strstr(armix::rt::CaptureClickRepair::provenance(),"NOT_CLOCK_DRIFT")!=nullptr);
}
3 changes: 2 additions & 1 deletion tests/live_routing_ui_contract_test.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,8 @@ test("R0B unified native mixer keeps VST3/clock/diagnostic paths protected",()=>
assert.match(engine,/setOutputMuted\(true\); \/\/ never expose CH1 unexpectedly/);
assert.match(engine,/dryRoutingLab_\.prepareDevice\(d\)/);
assert.match(engine,/dryRoutingLab_\.deviceStopped\(\)/);
assert.match(engine,/dryRoutingLab_\.process\(inputs,inputChannels,outputs/);
assert.match(engine,/dryRoutingLab_\.process\(renderInputs,inputChannels,outputs/);
assert.match(engine,/const float\* const\* renderInputs=inputs/);
assert.match(engine,/std::shared_ptr<juce::AudioPluginInstance> processor/);
assert.match(engine,/if \(dryRoutingLab_\.hasExplicitRoute\(\)\) return "CLEAR PATCH before recalling CH1 native preset"/);
assert.match(lab,/publisher_\.publish/);
Expand Down
Loading
Loading