From 4be963484eed2d9cca653fcfedef16fa6d789c8f Mon Sep 17 00:00:00 2001 From: Ari Sulistiono Date: Fri, 13 Nov 2026 21:25:40 +0700 Subject: [PATCH 01/44] feat(sonku): add bounded phase-aware stereo music-integrity stage --- .../builtin_fx/sonku/SonKuStereoIntegrity.h | 58 +++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 engine/builtin_fx/sonku/SonKuStereoIntegrity.h diff --git a/engine/builtin_fx/sonku/SonKuStereoIntegrity.h b/engine/builtin_fx/sonku/SonKuStereoIntegrity.h new file mode 100644 index 000000000..99ac8d39f --- /dev/null +++ b/engine/builtin_fx/sonku/SonKuStereoIntegrity.h @@ -0,0 +1,58 @@ +// SPDX-License-Identifier: AGPL-3.0-only +#pragma once +#include +#include + +// SonKu native music-integrity guard. Two coherent, equal-angle virtual +// sources carrying L and inverted R cancel mathematically in BOTH ear FIRs. +// Do not sum their side channel into a mono object; preserve that content +// as a bounded stereo difference bed only while strong negative correlation +// is MEASURED. This is not a dearVR/AMBEO implementation or virtual BRIR. +// +// Per-instance, audio-callback-owned fixed POD state. No heap, locks, +// timers, lookahead, UI/audio routing authority or added host latency. +// A hysteretic 20 ms correlation detector avoids reacting to ordinary +// uncorrelated stereo; 15 ms gain slewing avoids a hard switch. +namespace armix::sonku { +class SonKuStereoIntegrity final { +public: + bool prepare(double rate) noexcept { + if (!std::isfinite(rate) || rate<40000. || rate>48000.) return false; + evidenceAlpha_=static_cast(1.-std::exp(-1./(rate*.020))); + blendAlpha_=static_cast(1.-std::exp(-1./(rate*.015))); + reset(); + return true; + } + void reset() noexcept { + energyL_=0.f;energyR_=0.f;cross_=0.f;amount_=0.f; + antiCorrelated_=false; + } + // Returns a *single* difference signal. Caller adds it to LEFT and + // subtracts it from RIGHT after HRTF/room sums, not before the FIR. + // Sanitized finite x0/x1 are still bounded for correlation evidence: + // corrupt/overscale host audio must not produce NaN in the detector. + float preservedSide(float x0,float x1) noexcept { + const float l=std::clamp(x0,-4.f,4.f); + const float r=std::clamp(x1,-4.f,4.f); + energyL_+=evidenceAlpha_*(l*l-energyL_); + energyR_+=evidenceAlpha_*(r*r-energyR_); + cross_+=evidenceAlpha_*(l*r-cross_); + const float power=.5f*(energyL_+energyR_); + if(power<1.e-8f)antiCorrelated_=false; + else if(antiCorrelated_){ + if(cross_>-.55f*power)antiCorrelated_=false; + }else if(cross_<-.78f*power)antiCorrelated_=true; + amount_+=blendAlpha_*((antiCorrelated_?1.f:0.f)-amount_); + if(std::abs(amount_)<1.e-6f)amount_=0.f; + // At exact L=R the side is mathematically zero. Under opposite + // polarity L=-R, this returns the original side; it never converts + // the source to mono or modifies the measured HRTF kernel. + return .5f*(l-r)*amount_; + } + float recoveryAmount()const noexcept{return amount_;} +private: + float evidenceAlpha_=0.f,blendAlpha_=0.f; + float energyL_=0.f,energyR_=0.f,cross_=0.f,amount_=0.f; + bool antiCorrelated_=false; +}; +} // namespace armix::sonku From d40ce26d7c79a3c262e6c74f19ee9d7fbb7d41f6 Mon Sep 17 00:00:00 2001 From: Ari Sulistiono Date: Fri, 13 Nov 2026 21:26:10 +0700 Subject: [PATCH 02/44] fix(sonku-dsp): retain anti-phase stereo music while preserving measured HRTF + room authority Add callback-owned hysteretic energy/cross-correlation recovery of input M/S difference after binaural convolution, never mono-summing that content. Active only for strongly negative correlation, gain-slewed, finite/RT-safe; zero for correlated source and spatialMix=0. Apply to ROOM-OFF, experimental distance and native SPACE branches with consistent output trim, reuse scene limiter, preserve JUCE state/ACK ABI. --- engine/builtin_fx/sonku/SonKuSpatialCore.h | 25 ++++++++++++++++------ 1 file changed, 18 insertions(+), 7 deletions(-) diff --git a/engine/builtin_fx/sonku/SonKuSpatialCore.h b/engine/builtin_fx/sonku/SonKuSpatialCore.h index 924fbb639..0bc21e695 100644 --- a/engine/builtin_fx/sonku/SonKuSpatialCore.h +++ b/engine/builtin_fx/sonku/SonKuSpatialCore.h @@ -3,6 +3,7 @@ #include "SonKuMeasuredHrir.h" #include "SonKuEarlyReflections.h" #include "SonKuMusicalReverb.h" +#include "SonKuStereoIntegrity.h" #include #include #include @@ -73,7 +74,8 @@ class SonKuSpatialCore final { distanceSlew_=static_cast(1.-std::exp(-1./(rate*0.030))); bassSlew_=static_cast(1.-std::exp(-2.*3.14159265358979323846*180./rate)); limiterRelease_=static_cast(1./(rate*0.080)); - if(!room_.prepare(rate)||!reverb_.prepare(rate))return false; + if(!room_.prepare(rate)||!reverb_.prepare(rate)|| + !integrity_.prepare(rate))return false; reset(); ready_=true; // Re-publish a saved active scene after device restart, but do NOT @@ -100,6 +102,7 @@ class SonKuSpatialCore final { haveKernel_=false; room_.reset(); reverb_.reset(); + integrity_.reset(); } bool setSettings(const Settings& s) noexcept { if(!valid(s))return false; @@ -181,6 +184,13 @@ class SonKuSpatialCore final { } const float x0=std::isfinite(left[i])?left[i]:0.f; const float x1=std::isfinite(right[i])?right[i]:0.f; + // Preserve strong anti-correlated music side energy without + // collapsing it into the two virtual mono HRTF sources. The + // independent guard has no hidden UI state or new audio bus. + const float preservedSide=integrity_.preservedSide(x0,x1); + // At native spatialMix=0 the dry input stays bit-exact. + // At ordinary positively-correlated stereo the guard is zero. + const float sideRescue=.65f*smoothedMix_*smoothedTrim_*preservedSide; history_[0][write_]=x0; history_[1][write_]=x1; float ears[2]{0.f,0.f}; @@ -213,13 +223,13 @@ class SonKuSpatialCore final { // ROOM OFF and gain <= unity. Newly boosted GAIN > unity // uses the protected branch below even with ROOM OFF. if(distanceGain==1.f) { - left[i]=dryLevel*x0+legacyBinauralLevel*(ears[0]+reflection.left+late.left); - right[i]=dryLevel*x1+legacyBinauralLevel*(ears[1]+reflection.right+late.right); + left[i]=dryLevel*x0+legacyBinauralLevel*(ears[0]+reflection.left+late.left)+sideRescue; + right[i]=dryLevel*x1+legacyBinauralLevel*(ears[1]+reflection.right+late.right)-sideRescue; } else { left[i]=dryLevel*x0+legacyBinauralLevel* - (distanceGain*ears[0]+reflection.left+late.left); + (distanceGain*ears[0]+reflection.left+late.left)+sideRescue; right[i]=dryLevel*x1+legacyBinauralLevel* - (distanceGain*ears[1]+reflection.right+late.right); + (distanceGain*ears[1]+reflection.right+late.right)-sideRescue; } } else { // Slew gain changes per sample; a typed 1.6→8 m edit must @@ -263,9 +273,9 @@ class SonKuSpatialCore final { // When ROOM OFF is reselected after a native scene, the // additional wet presence smoothly decays with its own engine. float outL=smoothedTrim_* - (dryLevel*x0+sceneBinauralLevel*smoothedRoomLevel_*spatialL); + (dryLevel*x0+sceneBinauralLevel*smoothedRoomLevel_*spatialL)+sideRescue; float outR=smoothedTrim_* - (dryLevel*x1+sceneBinauralLevel*smoothedRoomLevel_*spatialR); + (dryLevel*x1+sceneBinauralLevel*smoothedRoomLevel_*spatialR)-sideRescue; // Zero-lookahead *linked* sample-peak safety guard. Quiet // signals are linear; peaks are gently returned below unity // without routing through a second engine or allocating. @@ -335,6 +345,7 @@ class SonKuSpatialCore final { Settings settings_{}; SonKuEarlyReflections room_{}; SonKuMusicalReverb reverb_{}; + SonKuStereoIntegrity integrity_{}; float smoothedMix_=1.f,smoothedTrim_=0.75f; float smoothedDistanceGain_=1.f,smoothedRoomLevel_=1.f; float smoothedBassShelf_=0.f,limiterGain_=1.f; From f19940ea169bf0dd8755da7952efeb752d178548 Mon Sep 17 00:00:00 2001 From: Ari Sulistiono Date: Fri, 13 Nov 2026 21:27:37 +0700 Subject: [PATCH 03/44] test(sonku): prove exact centered HRTF, anti-phase stereo energy and PCM chunk parity at 44.1/48k Numerical tests exercise native impulse, FRONT/RIGHT/REAR/LEFT collapse rescue, independent L/R, 128-frame chunk parity, finite peak guard, positive-correlation no-op, silence reset, device prepare and spatialMix=0 dry identity. --- tests/sonku_spatial_core_test.cpp | 108 ++++++++++++++++++++++++++++++ 1 file changed, 108 insertions(+) diff --git a/tests/sonku_spatial_core_test.cpp b/tests/sonku_spatial_core_test.cpp index 0258e2201..7123e2d32 100644 --- a/tests/sonku_spatial_core_test.cpp +++ b/tests/sonku_spatial_core_test.cpp @@ -10,8 +10,116 @@ #include #include +// Measurable failure case from the listening report: two equal-angle virtual +// emitters fed opposite-polarity stereo cancel in each ear HRTF summation. +// Test the actual native PCM path, not a JS animation or guessed acoustics. +static void verifySonKuMusicIntegrity(double rate) { + using namespace armix::sonku; + Settings s{}; + s.moving=false;s.stereoSpreadDegrees=0.f;s.spatialMix=1.f; + s.outputTrim=.75f;s.spacePreset=0; + // A perfectly coherent stereo center must remain the exact old measured + // impulse, including coefficient, amplitude, phase and callback timing. + { + auto center=std::make_unique(); + assert(center->prepare(rate)&¢er->setSettings(s)); + std::array l{},r{}; + l[0]=r[0]=.24f; + center->process(l.data(),r.data(),static_cast(l.size())); + const auto& h=(std::abs(rate-44100.)<.1)? + hrir::normal44100:hrir::normal48000; + for(int i=0;i(h[0][0][i])/32768.f; + const float expectedR=.24f*s.outputTrim* + static_cast(h[0][1][i])/32768.f; + assert(std::abs(l[i]-expectedL)<3.e-6f); + assert(std::abs(r[i]-expectedR)<3.e-6f); + } + } + constexpr int n=16384; + constexpr float pi=3.14159265358979323846f; + for (float angle : {0.f,90.f,180.f,270.f}) { + auto whole=std::make_unique(); + auto partition=std::make_unique(); + s.startAzimuthDegrees=angle; + assert(whole->prepare(rate)&&partition->prepare(rate)); + assert(whole->setSettings(s)&&partition->setSettings(s)); + std::vector l(n),r(n),cl(n),cr(n); + for(int i=0;i(i)/static_cast(rate)); + l[i]=cl[i]=v; + r[i]=cr[i]=-v; + } + whole->process(l.data(),r.data(),n); + for(int at=0;atprocess(cl.data()+at,cr.data()+at, + std::min(128,n-at)); + double leftEnergy=0.,rightEnergy=0.,crossEnergy=0.; + for(int i=0;in/2){ + leftEnergy+=static_cast(l[i])*l[i]; + rightEnergy+=static_cast(r[i])*r[i]; + crossEnergy+=static_cast(l[i])*r[i]; + } + } + const double rmsL=std::sqrt(leftEnergy/(n/2-1)); + const double rmsR=std::sqrt(rightEnergy/(n/2-1)); + // Original SonKu collapses to zero at FRONT/REAR and zero SPREAD. + // The phase-aware branch must preserve a musical stereo side signal + // without converting it into a mono HRTF object. + assert(rmsL>.065&&rmsR>.065); + if(angle==0.f||angle==180.f)assert(crossEnergy<0.); + } + // Mixed stereo without strong anti-correlation never activates recovery: + // a mono-correlated signal is not given a phantom second bed. + { + SonKuStereoIntegrity guard; + assert(guard.prepare(rate)); + for(int i=0;i<8000;++i){ + float v=.4f*std::sin(2.f*pi*160.f* + static_cast(i)/static_cast(rate)); + assert(guard.preservedSide(v,.7f*v)==0.f); + } + assert(guard.recoveryAmount()==0.f); + guard.reset(); + for(int i=0;i<8000;++i){ + float v=.4f*std::sin(2.f*pi*160.f* + static_cast(i)/static_cast(rate)); + (void)guard.preservedSide(v,-v); + } + assert(guard.recoveryAmount()>.95f); + for(int i=0;i<25000;++i) + assert(guard.preservedSide(0.f,0.f)==0.f); + assert(guard.recoveryAmount()<.05f); + assert(guard.prepare(rate)); // device restart must not remember polarity + assert(guard.recoveryAmount()==0.f); + } + // Mix=0 preserves the source channels as dry, including negative phase. + { + auto dry=std::make_unique(); + s.spatialMix=0.f;s.startAzimuthDegrees=0.f; + assert(dry->prepare(rate)&&dry->setSettings(s)); + std::array l{},r{}; + for(int i=0;i(l.size());++i){ + l[i]=.15f*std::sin(i*.017f);r[i]=-l[i]; + } + const auto before=l; + dry->process(l.data(),r.data(),static_cast(l.size())); + for(int i=0;i(l.size());++i){ + assert(l[i]==before[i]&&r[i]==-before[i]); + } + } +} + int main() { using namespace armix::sonku; + for(double r:{44100.,48000.})verifySonKuMusicIntegrity(r); SonKuSpatialCore rejected; assert(!rejected.prepare(96000.)); assert(!rejected.prepare(std::numeric_limits::infinity())); From 5e14e38eae120a9ea0b22052a70c0dc8af0d57ab Mon Sep 17 00:00:00 2001 From: Ari Sulistiono Date: Fri, 13 Nov 2026 21:29:19 +0700 Subject: [PATCH 04/44] test(sonku): publish reproducible lossless music-integrity headphone evidence Render original harmonic material at matched time/level as coherent front, anti-phase front and anti-phase rear with exact native core. Do not normalize WAVs or claim dearVR externalization. --- tools/sonku_offline_listening.cpp | 47 ++++++++++++++++++++++++++++++- 1 file changed, 46 insertions(+), 1 deletion(-) diff --git a/tools/sonku_offline_listening.cpp b/tools/sonku_offline_listening.cpp index ae2697103..3fd56e159 100644 --- a/tools/sonku_offline_listening.cpp +++ b/tools/sonku_offline_listening.cpp @@ -141,6 +141,39 @@ std::vector orbit(float roomAmount=0.f, throw std::runtime_error("Two turns do not close acoustic orbit"); return result; } +// Native anti-phase stereo proof using three original harmonics, not +// copyrighted music or an imitation of a proprietary dearVR recording. +// Equal LEVEL, timing, HRTF and 0-degree stereo spread across all variants; +// only one input channel's polarity differs. +std::vector musicIntegrityProof(float azimuth,bool inverted) { + SonKuSpatialCore dsp; + if(!dsp.prepare(rate)|| + !dsp.setSettings(fixed(azimuth))) + throw std::runtime_error("Music integrity fixture not prepared"); + constexpr int total=rate*4; + constexpr float pi=3.14159265358979323846f; + std::vector audio; + audio.reserve(static_cast(total)*4); + for(int at=0;at l{},r{}; + for(int i=0;i(n)/rate; + const float env=std::clamp( + std::min(n,total-1-n)/static_cast(rate/30),0.f,1.f); + const float x=env*(.13f*std::sin(2.f*pi*220.f*t)+ + .08f*std::sin(2.f*pi*330.f*t)+ + .045f*std::sin(2.f*pi*660.f*t)); + l[static_cast(i)]=x; + r[static_cast(i)]=inverted?-x:x; + } + dsp.process(l.data(),r.data(),count); + for(int i=0;i