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: 2 additions & 0 deletions .github/workflows/build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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: |
Expand All @@ -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))" } |
Expand Down
2 changes: 2 additions & 0 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
39 changes: 39 additions & 0 deletions docs/RT-RELIABILITY-PLAN.md
Original file line number Diff line number Diff line change
@@ -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.
38 changes: 33 additions & 5 deletions engine/Compressor.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -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<float>(std::exp(-1.0/(0.01*fs)));
p=initial; p.sanitize();
for(std::size_t i=0;i<Count;++i) smooth[i].reset(rampTarget(i,p[i],fs));
for(std::size_t i=0;i<Count;++i) {
smooth[i].reset(rampTarget(i,p[i],fs));
currentValues[i]=smooth[i].current;
}
activeRampCount=0;
lowerKneeLinear=dbToGain(p[Threshold]-0.5f*p[Knee]);
staticKneeGate=true;
filterWet[0].reset(p[Highpass]>20.01f ? 1.0f : 0.0f);
filterWet[1].reset(p[Lowpass]<19999.0f ? 1.0f : 0.0f);
attackCoeff=static_cast<float>(std::exp(-1000.0/(p[Attack]*fs)));
Expand All @@ -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;i<Count;++i)
if(smooth[i].remaining>0)
activeRampIndices[activeRampCount++]=static_cast<std::uint8_t>(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<samples;++n) {
std::array<float,Count> v{};
for(std::size_t i=0;i<Count;++i) v[i]=smooth[i].next();
for(std::size_t k=0;k<activeRampCount;++k) {
const auto i=activeRampIndices[k];
currentValues[i]=smooth[i].next();
}
const auto& v=currentValues;
const float inputGain=v[Input],makeupGain=v[Makeup];
const float hpCoeff=v[Highpass],lpCoeff=v[Lowpass];
// Clean feedforward; Feedback senses prior actual attenuation;
Expand Down Expand Up @@ -81,7 +99,14 @@ void Compressor::process(float* const* audio,int channels,int samples,const floa
const float linked=std::max(detected[0],detected[channels-1]);
for(int c=0;c<channels;++c) {
const float detector=detected[c]+(linked-detected[c])*(v[Link]*0.01f);
const float target=reduction(gainToDb(detector),v[Threshold],v[Ratio],v[Knee],v[Range]);
// All compressor styles share a mathematically zero static curve
// below threshold - knee/2. For steady threshold/knee, avoid the
// expensive log10 entirely. A tiny guard accommodates float
// rounding near the knee boundary; dynamic automation uses the
// unmodified exact path.
const float target=(staticKneeGate &&
detector<lowerKneeLinear*0.99999f) ? 0.0f :
reduction(gainToDb(detector),v[Threshold],v[Ratio],v[Knee],v[Range]);
auto& env=envelope[c];
if(target>env) { env=target+attackCoeff*(env-target); holdRemaining[c]=holdSamples; }
else if(holdRemaining[c]>0) --holdRemaining[c];
Expand All @@ -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);
Expand Down
10 changes: 10 additions & 0 deletions engine/Compressor.h
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
#pragma once
#include "Parameters.h"
#include "MeterQueue.h"
#include <cstdint>
namespace arson {
// Framework-free, audio-thread-owned state. Planar mono/stereo, arbitrary block size.
class Compressor {
Expand All @@ -23,6 +24,15 @@ class Compressor {
};
Parameters p;
std::array<Ramp,Count> smooth{};
// Canonical smoothed values and sparse ramp indexes. Audio calls never
// allocate; stable controls cause zero per-sample ramp work.
std::array<float,Count> currentValues{};
std::array<std::uint8_t,Count> 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<Ramp,2> filterWet{};
std::array<float,2> hpState{}, lpState{}, rms{}, envelope{}, smoothEnvelope{}, previousGain{1.0f,1.0f};
Expand Down
69 changes: 69 additions & 0 deletions tests/EngineTests.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -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<float>(model);
p.value[Detector]=static_cast<float>(detector);
p.value[Threshold]=-30.0f;
p.value[Knee]=18.0f;
p.value[Highpass]=100.0f;
Compressor c;c.prepare(rate,p);
std::array<float,512> 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<float,4096> 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<Compressor,8> engines{};
std::array<Parameters,8> 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<frames;++i) {
l[i]=0.2f*std::sin(i*0.07f);r[i]=0.17f*std::cos(i*0.13f);
}
for(std::size_t x=0;x<engines.size();++x) {
auto& spec=ps[x];
spec.value[Threshold]=-30.0f+static_cast<float>((block+x)%12);
spec.value[Detector]=static_cast<float>(block%2);
spec.value[Style]=static_cast<float>(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.
Expand Down
85 changes: 85 additions & 0 deletions tests/RealtimeStress.cpp
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
#include <array>
#include <chrono>
#include <cmath>
#include <iostream>
#include <memory>
#include <vector>
#include <algorithm>
#include <iomanip>
#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<float,maxFrames> l{},r{},side{};
std::array<float*,2> audio{{l.data(),r.data()}};
std::array<const float*,1> 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<frames;++i) {
const auto phase=static_cast<float>((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<std::unique_ptr<Instance>> xs;xs.reserve(count);
for(int i=0;i<count;++i)xs.emplace_back(std::make_unique<Instance>(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<double> durations;durations.reserve(blocks);
double total=0;
for(int k=0;k<blocks;++k) {
for(auto& a:xs) {
a->fill(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<double,std::micro>(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<size_t>(std::ceil(p*blocks)-1)];};
const double budget=frames*1.e6/48000.;
std::cout<<scenario.name<<" frames="<<frames<<" instances="<<count
<<std::fixed<<std::setprecision(2)<<" mean="<<total/blocks
<<"us p99="<<percentile(.99)<<"us p99.9="<<percentile(.999)
<<"us max="<<durations.back()<<"us p99/deadline="
<<100.*percentile(.99)/budget<<"%\n";
}
}
int main(){
std::cout<<"48kHz engine-only wall-clock probe. Includes OS jitter. Not a hardware dropout test.\n";
try {
for(const auto scenario: {Case{"Clean Peak",false,false,false},
Case{"Smooth RMS+SC",true,true,false},
Case{"RMS automate",true,true,true}})
for(int frames: {32,64,128})
for(int n: {1,8,24})run(scenario,frames,n);
}catch(...){std::cerr<<"Nonfinite output\n";return 1;}
std::cout<<"PASS: finite output; actual audio device and host remain untested.\n";
}
Loading