diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 5bd3b0a..4355372 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -32,6 +32,7 @@ jobs: run: | New-Item -ItemType Directory -Force artifacts & ./build/Release/engine_bench.exe | Tee-Object artifacts/benchmark.txt + & ./build/Release/rt_stress.exe | Tee-Object artifacts/realtime-stress.txt - name: Package install-ready Windows test artifact shell: pwsh run: | @@ -42,6 +43,7 @@ jobs: Copy-Item 'build/ArSonComp_artefacts/Release/Standalone/ArSonComp.exe' "$dest/Standalone/" Copy-Item 'docs/WINDOWS-QUICKSTART.md' "$dest/START-HERE.md" Copy-Item 'artifacts/benchmark.txt' "$dest/benchmark.txt" + Copy-Item 'artifacts/realtime-stress.txt' "$dest/realtime-stress.txt" Copy-Item 'build/ArSonComp-preview*.png' "$dest/Screenshots/" $files = Get-ChildItem "$dest/Plugin", "$dest/Standalone" -File -Recurse $files | ForEach-Object { "$((Get-FileHash $_.FullName -Algorithm SHA256).Hash) $($_.FullName.Substring((Resolve-Path $dest).Path.Length + 1))" } | diff --git a/CMakeLists.txt b/CMakeLists.txt index 1122f9b..5b34cf0 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -24,6 +24,8 @@ if(BUILD_TESTING) add_test(NAME engine_contract COMMAND engine_tests) add_executable(engine_bench tests/Benchmark.cpp) target_link_libraries(engine_bench PRIVATE arson_engine) + add_executable(rt_stress tests/RealtimeStress.cpp) + target_link_libraries(rt_stress PRIVATE arson_engine) endif() if(ARSON_BUILD_PLUGIN) if(DEFINED JUCE_SOURCE_DIR) diff --git a/docs/RT-RELIABILITY-PLAN.md b/docs/RT-RELIABILITY-PLAN.md new file mode 100644 index 0000000..9ce834d --- /dev/null +++ b/docs/RT-RELIABILITY-PLAN.md @@ -0,0 +1,39 @@ +# ArSonComp — RT Reliability and Pro-C Quality Strategy (2026-10-31) + +Status: investigation milestone, not proof that physical audio dropouts are fixed. + +## Audit findings from the current source +- The hot loop updates 19 parameter ramps every sample and performs log10(detector) and exp(gain-reduction) per channel and sample. These are CPU-cost candidates, not confirmed causes of stutter. +- APVTS parameters are snapped once per block; changed control coefficients are coalesced; the SPSC GUI telemetry queue is bounded and lossy; GUI repaint is message-thread only. Do not discard these existing good practices. +- Engine-level tests already guard process-time allocations. They do not prove no leaks in VST3, editor lifecycle, multiple hosts or long running sessions. +- Earlier GitHub CI averaged around half of one core percent for a stereo instance. Mean throughput alone says nothing about missed host deadlines, worst-case spikes or Windows audio drivers. +- Audio compressor envelope state is causal and serial. Do NOT move live compression to a worker that the realtime callback must wait on: it can introduce queues, unpredictable scheduling, additional latency and new failure modes. + +## Reproducible performance measurement +1. Use tests/RealtimeStress.cpp to report mean, P99, P99.9 and max of a simulated block-processing chain (32/64/128 frames; 1/8/24 instances; Peak, RMS+SC and automation). CI results are comparative engine-only wall-clock timing and include OS jitter, not an actual xrun test. +2. On user's Windows hardware, capture standalone and at least two VST3 hosts, including ArSonMiX if available. Document audio device, ASIO/WASAPI driver, sample rate 48/96kHz, buffer 32/64/128, instances 1/8/16, GUI open/closed, OS/DPC latency and actual host xrun counters. +3. Use ETW/WPR/WPA or another sampler to attribute CPU and stalls. Never insert filesystem writes, locks or printf into the process callback. +4. For memory, repeat editor open/close and state reload, then run a 60-minute session with stable instance count. Monitor private bytes, retained allocations and heap diagnostics. Do not label a memory leak without reproducible retained growth. +5. Test candidate optimizations one at a time against a reference waveform: gain and detector conversions, inactive-parameter ramps, peak-only detector path, GUI painting. Preserve state, transient and denormal behavior, automation smoothing and sample partition invariance. Avoid fast-math and unproven LUT shortcuts. + +## DSP musical-quality track, separate from realtime optimization +- FabFilter Pro-C 3 documents 14 program-dependent compression styles, character modes, complex sidechain EQ, and optional lookahead/oversampling. Its DSP implementation is proprietary; copying behavior cannot be inferred from the GUI. +- Compare independently designed models using loudness-matched WAVs: vocal, drums, bass and mix bus. Measure compression envelope, overshoot, release recovery, THD/harmonic sidebands, aliasing, pumping, transient crest and dry/wet phase. +- Program-dependent envelopes and true feedback topology need reliable tests before marketing claims. A separate optional lookahead/oversampling quality mode may add latency; preserve the zero-added-sample live path as default. +- No style label counts as an independent algorithm without distinct transient/envelope output and listening validation. + +## Engineering acceptance (targets, not achieved results) +- No allocations, deallocations, mutex waits, worker waits, filesystem access or GUI calls from the realtime processing path. +- On the target machine, document P99.9 and maximum audio callback processing times relative to block deadline; target single-instance <=20% of deadline and retain margin for all other mixer plugins. Do not confuse CI benchmark with hardware proof. +- Zero observed xrun during documented 60-minute real-device test at the declared stable buffer, not an unqualified zero-latency promise. +- pluginval, two host projects, state/preset reload, mono/stereo external SC, 32/64/128 frames, DPI and sustained multi-instance lifecycle. +- Match reference recordings by measured loudness and verify audible improvement, not just benchmark improvements. + +References: https://steinbergmedia.github.io/vst3_dev_portal/pages/FAQ/Processing.html +https://www.fabfilter.com/help/pro-c/using/styleandcharacter +https://www.fabfilter.com/help/pro-c/using/oversampling +https://www.fabfilter.com/help/pro-c/using/overview + +## M2 implemented CPU-work avoidance (no sonic approximation) + +The current M2 engine patch adds a bounded active-ramp index list recomputed once per host block. When controls are stationary, the sample loop performs **no parameter ramp iterations**; active automation continues sample-by-sample using the original ramp math. The static lower-knee threshold is preconverted to linear once per block; samples definitely below the soft knee skip the log10 gain-computer conversion. Exact zero gain reduction skips exp(0). All three changes preserve the original compression law, sample-clock semantics, zero additional samples and existing state schema. When Threshold/Knee are moving, the linear-domain shortcut is disabled to preserve automation. Stereo + RMS/Peak + all three models, 44.1-192kHz, block partition invariance, multi-instance finite output and no heap allocations are validated in engine tests. Win/Linux CI is the gate; hardware audio stability still requires measurements. diff --git a/engine/Compressor.cpp b/engine/Compressor.cpp index 6b3670c..e557db6 100644 --- a/engine/Compressor.cpp +++ b/engine/Compressor.cpp @@ -19,7 +19,13 @@ void Compressor::prepare(double rate,const Parameters& initial) noexcept { hpState={}; lpState={}; rms={}; envelope={}; smoothEnvelope={}; previousGain={1.0f,1.0f}; holdRemaining={}; meter={}; meterCount=0; rmsCoeff=static_cast(std::exp(-1.0/(0.01*fs))); p=initial; p.sanitize(); - for(std::size_t i=0;i20.01f ? 1.0f : 0.0f); filterWet[1].reset(p[Lowpass]<19999.0f ? 1.0f : 0.0f); attackCoeff=static_cast(std::exp(-1000.0/(p[Attack]*fs))); @@ -45,12 +51,24 @@ void Compressor::setParameters(Parameters next) noexcept { if(next[Lowpass]!=p[Lowpass]) filterWet[1].set(next[Lowpass]<19999.0f ? 1.0f : 0.0f,rampLength); p=next; + // Build a tiny stack-owned active index list once per host block, never + // iterate 19 inactive one-pole ramps per AUDIO SAMPLE. + activeRampCount=0; + for(std::size_t i=0;i0) + activeRampIndices[activeRampCount++]=static_cast(i); + staticKneeGate=smooth[Threshold].remaining==0 && smooth[Knee].remaining==0; + if(staticKneeGate) + lowerKneeLinear=dbToGain(p[Threshold]-0.5f*p[Knee]); } void Compressor::process(float* const* audio,int channels,int samples,const float* const* sc,int scChannels,MeterQueue* meters) noexcept { if(!audio || channels<1 || channels>2 || samples<=0) return; for(int n=0;n v{}; - for(std::size_t i=0;ienv) { env=target+attackCoeff*(env-target); holdRemaining[c]=holdSamples; } else if(holdRemaining[c]>0) --holdRemaining[c]; @@ -97,7 +122,10 @@ void Compressor::process(float* const* audio,int channels,int samples,const floa smoothEnvelope[c]=flush(env+coeff*(smoothEnvelope[c]-env)); } else smoothEnvelope[c]=env; const float effectiveEnv=env+(smoothEnvelope[c]-env)*smoothWeight; - const float attenuation=dbToGain(-effectiveEnv); + // exp(0) == 1 exactly. Sparse idle/no-GR sections therefore + // bypass exponential gain conversion without sonic approximation. + const float attenuation=effectiveEnv==0.0f ? 1.0f : + dbToGain(-effectiveEnv); previousGain[c]=attenuation; const float wet=dry[c]*attenuation*makeupGain; float out=dry[c]+(wet-dry[c])*(v[Mix]*0.01f); diff --git a/engine/Compressor.h b/engine/Compressor.h index 004b2cd..6ae9bdb 100644 --- a/engine/Compressor.h +++ b/engine/Compressor.h @@ -1,6 +1,7 @@ #pragma once #include "Parameters.h" #include "MeterQueue.h" +#include namespace arson { // Framework-free, audio-thread-owned state. Planar mono/stereo, arbitrary block size. class Compressor { @@ -23,6 +24,15 @@ class Compressor { }; Parameters p; std::array smooth{}; + // Canonical smoothed values and sparse ramp indexes. Audio calls never + // allocate; stable controls cause zero per-sample ramp work. + std::array currentValues{}; + std::array activeRampIndices{}; + std::size_t activeRampCount=0; + // Preconverted lower knee edge for the steady-parameter no-compression path. + // Disabled while threshold/knee are ramping to retain exact automation. + float lowerKneeLinear=0.0f; + bool staticKneeGate=false; // Filter on/off is blended separately from cutoff coefficients to avoid endpoint steps. std::array filterWet{}; std::array hpState{}, lpState{}, rms{}, envelope{}, smoothEnvelope{}, previousGain{1.0f,1.0f}; diff --git a/tests/EngineTests.cpp b/tests/EngineTests.cpp index 693586d..a17fb5f 100644 --- a/tests/EngineTests.cpp +++ b/tests/EngineTests.cpp @@ -197,6 +197,75 @@ int main() { require(allocations.load()==before,"no allocation in process or parameter updates"); MeterFrame f;int count=0;while(q.pop(f))++count;require(count==511,"bounded telemetry drops on saturation"); } + { + // Quiet input must be bit-exact passthrough when the entire + // detector remains below the knee. Regression for the optional + // static linear-domain gate across model/detector/sample rates. + for(double rate: {44100.0,48000.0,96000.0,192000.0}) + for(int model=0;model<3;++model) + for(int detector=0;detector<2;++detector) { + Parameters p; + p.value[Style]=static_cast(model); + p.value[Detector]=static_cast(detector); + p.value[Threshold]=-30.0f; + p.value[Knee]=18.0f; + p.value[Highpass]=100.0f; + Compressor c;c.prepare(rate,p); + std::array left{},right{}; + for(int i=0;i<512;++i) { + left[i]=0.004f*std::sin(i*0.13f); + right[i]=0.003f*std::cos(i*0.19f); + } + const auto referenceLeft=left,referenceRight=right; + float* ptr[]{left.data(),right.data()}; + c.process(ptr,2,512); + require(left==referenceLeft && right==referenceRight, + "steady below-knee audio remains bit exact"); + } + // A threshold/knee automation ramp must not erroneously gate + // gain reduction before its sample-smoothed target is reached. + Parameters p;p.value[Threshold]=-8;p.value[Knee]=0; + Compressor smooth,reference; + smooth.prepare(48000,p);reference.prepare(48000,p); + p.value[Threshold]=-40;p.value[Knee]=18; + smooth.setParameters(p);reference.setParameters(p); + std::array a{},b{}; + for(int i=0;i<4096;++i) a[i]=b[i]=0.045f; + float* pa[]{a.data()},*pb[]{b.data()}; + smooth.process(pa,1,4096); + for(int off=0;off<4096;) { + const int len=std::min(29,4096-off); + float* sub[]{b.data()+off}; + reference.setParameters(p);reference.process(sub,1,len); + off+=len; + } + require(a==b,"sparse ramps and gate remain block-partition invariant"); + require(a.back()<0.045f,"threshold automation eventually reduces gain"); + // Multi-instance memory and signal safety: no heap allocations + // during repeated short-block processing and automation snapshots. + std::array engines{}; + std::array ps{}; + for(auto& e:engines)e.prepare(48000); + float l[128]{},r[128]{};float* audio[]{l,r}; + const auto before=allocations.load(); + for(int frames: {32,64,128})for(int block=0;block<240;++block) { + for(int i=0;i((block+x)%12); + spec.value[Detector]=static_cast(block%2); + spec.value[Style]=static_cast(x%3); + engines[x].setParameters(spec); + engines[x].process(audio,2,frames); + require(std::isfinite(l[frames-1]) && std::isfinite(r[frames-1]), + "multi-instance finite output"); + } + } + require(allocations.load()==before, + "multi-instance 32/64/128 processing allocates no heap"); + } { // Two LED meter columns must carry genuinely independent channel // peak values, rather than duplicating one shared maximum. diff --git a/tests/RealtimeStress.cpp b/tests/RealtimeStress.cpp new file mode 100644 index 0000000..91a1b28 --- /dev/null +++ b/tests/RealtimeStress.cpp @@ -0,0 +1,85 @@ +#include +#include +#include +#include +#include +#include +#include +#include +#include "Compressor.h" +namespace { +constexpr int maxFrames=128; +struct Case { const char* name; bool rms; bool sc; bool automate; }; +struct Instance { + arson::Compressor engine; + arson::Parameters p; + arson::MeterQueue q; + std::array l{},r{},side{}; + std::array audio{{l.data(),r.data()}}; + std::array sc{{side.data()}}; + explicit Instance(Case c) { + p.value[arson::Threshold]=-24; + p.value[arson::Ratio]=4; + p.value[arson::Detector]=c.rms?1.f:0.f; + p.value[arson::AutoRelease]=1; + p.value[arson::Highpass]=c.sc?100.f:20.f; + p.value[arson::External]=c.sc?1.f:0.f; + p.value[arson::Style]=c.sc?2.f:0.f; + engine.prepare(48000,p); + } + void fill(int frames,int block) { + for(int i=0;i((block*frames+i)%2048); + l[i]=0.48f*std::sin(phase*0.031f); + r[i]=0.31f*std::sin(phase*0.057f); + side[i]=0.8f*std::sin(phase*0.073f); + } + } + void process(int frames,bool external) noexcept { + engine.setParameters(p); + engine.process(audio.data(),2,frames,external?sc.data():nullptr, + external?1:0,&q); + } +}; +void run(Case scenario,int frames,int count) { + std::vector> xs;xs.reserve(count); + for(int i=0;i(scenario)); + for(int k=0;k<200;++k) for(auto& a:xs){a->fill(frames,k);a->process(frames,scenario.sc);} + constexpr int blocks=1600; + std::vector durations;durations.reserve(blocks); + double total=0; + for(int k=0;kfill(frames,k+200); + if(scenario.automate&&k%8==0) + a->p.value[arson::Threshold]=(k%16==0)?-32.f:-18.f; + } + const auto begin=std::chrono::steady_clock::now(); + for(auto& a:xs)a->process(frames,scenario.sc); + const auto end=std::chrono::steady_clock::now(); + const double us=std::chrono::duration(end-begin).count(); + durations.push_back(us);total+=us; + } + for(auto& a:xs) if(!std::isfinite(a->l[frames-1])||!std::isfinite(a->r[frames-1])) + throw 1; + std::sort(durations.begin(),durations.end()); + auto percentile=[&](double p){return durations[static_cast(std::ceil(p*blocks)-1)];}; + const double budget=frames*1.e6/48000.; + std::cout<