Skip to content
Closed
73 changes: 73 additions & 0 deletions docs/SONKU_V4_DISTANCE_SPACE_DECISION_20261113.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
# 8D-SonKu V4 — independent source-distance and large-room candidate
2026-11-13 | offline headphone experiment | stacked on approved Square + V3 FDN PR #629

## Baseline lock / non-goals
The owner approved a 7.2 × 7.2 m Square Orbit at 1.6 m emitter radius.
Checkpoint `3a74b0273c7a7e13d5d2614183d19995eb12ad57` must not move.
Do NOT modify any HRIR coefficients, direction signs, native SonKu controls,
V3 reverb presets, production JUCE state, mixer WIRE routing, or public Pages.

## Why ROOM SIZE and SOURCE DISTANCE are NOT the same parameter
- **Room dimensions:** move virtual image walls, which changes first reflection
arrival times and amplitude by source-to-listener path distance.
- **Source distance:** changes relative direct energy (reference pressure 1.6/r),
while each reflected path is independently scaled with 1.6/path. The 1.6 m
reference is unchanged, including EXACT original floating-point operation order.
- **Diffuse late reverb:** not physically equivalent to either quantity. The
existing Studio Glue (0.78 s) and Airy Chamber (1.28 s) are deliberately OFF
in new distance/room A/B tracks. A large "hall" RT60 must be separately
modeled, calibrated and listened to; do not fake hall size with one longer tail.

## Engine changes and realtime constraints
- `SonKuEarlyReflections::setGeometry({width,depth,distance})` controls an
unpublished, inactive processor only. Geometry is bounded to 5–40 m per
dimension, source distance 1.6–10 m, >0.5 m wall clearance and worst image
path within the existing 8192-frame circular delay ring at 48 kHz.
- First-order image-source paths still use 2 emitters × 4 walls, 64-frame
geometry cadence, fractional-delay taps, smoothed delays and gains. No ray
tracing, FFT, new thread, host callback, heap or IO in `process()`.
- `SonKuSpatialCore` applies reference-distance gain ONLY to direct measured
HRTF when an experimental non-reference geometry is configured; reflections
use absolute reflected path pressure and the existing FDN stage is unchanged.
- This is NOT a full physical BRIR: no floor/ceiling, higher-order reflections,
occlusion, calibrated high-frequency air absorption, direct time-of-flight,
personalized pinna model, dynamic head tracking or release-qualified tail.
- No GUI/bridge/lease/session edits; ALL production instances remain legacy
geometry with direct gain=1 and the approved PCM arithmetic unchanged.

## Matched-source audition matrix (two 10-second 360° revolutions)
The existing `sonku-v2-square-orbit-cw-2x.wav` remains the reference.

| WAV stem | Width × depth | Emission radius | Late reverb | Intended comparison |
| --- | --- | --- | --- | --- |
| v2-square | 7.2 × 7.2 m | 1.6 m | OFF | Owner-approved |
| v4-spacious-near | 14.4 × 14.4 m | 1.6 m | OFF | Room dimension only |
| v4-spacious-far | 14.4 × 14.4 m | 5.0 m | OFF | Distance only vs spacious-near |
| v4-large-near | 28.8 × 28.8 m | 1.6 m | OFF | Larger room without moving source |
| v4-large-far | 28.8 × 28.8 m | 8.0 m | OFF | Distance only vs large-near |

All render the same deterministic noise, source stereo, azimuth path,
KEMAR HRIR, wet setting and trim. Files are NOT normalized: distant samples
are truly quieter. For localization evaluation match perceived monitoring
loudness safely and separately evaluate the physical level change.
Headphones only; disable OS spatial enhancement.

## Gates
1. Legacy default Square vs explicit identical geometry: byte-exact early
reflection and full native-core PCM under both 44.1/48k.
2. Larger room first-echo onset must move later, beyond the reference.
3. Distant direct field must approximate 1.6/r with ER OFF; reject invalid,
nonfinite, too-small, out-of-wall geometry and active edits.
4. Complete WAV formats, continuous 2-turn seam, non-silent tails,
direction signs, parity, amplitude safety and same-runner CPU telemetry.
5. Listener A/B judgment and Windows ASIO hardware tests are separate,
necessary release gates. No native GUI control or installer promotion yet.

## Research
- Allen and Berkley, JASA 65(4), 943–950 (1979), DOI 10.1121/1.382599:
first-order image-source paths for rectangular rooms.
- Valve Steam Audio core guide, direct distance attenuation and reflection
model as separate signal-processing stages:
https://github.com/ValveSoftware/steam-audio/blob/master/core/doc/guide.rst

No external code or proprietary impulse responses copied.
56 changes: 49 additions & 7 deletions engine/builtin_fx/sonku/SonKuEarlyReflections.h
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,12 @@
// No allocation, locks, worker, I/O, FFT or second device callback.
namespace armix::sonku {
enum class SonKuRoomShape : std::uint8_t { Rectangular=0, Square=1 };
// Offline-only center-listener geometry. Width/depth are full room spans;
// the source moves on a horizontal ring at distanceMeters from the listener.
// No realtime mutation or native state schema is published by this experiment.
struct SonKuRoomGeometry {
float widthMeters=7.2f,depthMeters=7.2f,distanceMeters=1.6f;
};
class SonKuEarlyReflections final {
public:
struct Ears {float left=0.f,right=0.f;};
Expand Down Expand Up @@ -54,10 +60,39 @@ class SonKuEarlyReflections final {
return false;
if(active())return false;
shape_=shape;
custom_=false; // restores the exact legacy square/rectangle semantics
untilGeometry_=0;
primed_=false;
return true;
}
// Evaluated on an unpublished, inactive DSP instance only. Width up to
// 40m is safely contained in the existing 8192-frame delay rings at 48k.
static bool validGeometry(const SonKuRoomGeometry& g) noexcept {
if(!std::isfinite(g.widthMeters)||!std::isfinite(g.depthMeters)||
!std::isfinite(g.distanceMeters))return false;
if(g.widthMeters<5.f||g.depthMeters<5.f||
g.widthMeters>40.f||g.depthMeters>40.f||
g.distanceMeters<1.6f||g.distanceMeters>10.f||
2.f*(g.distanceMeters+.5f)>std::min(g.widthMeters,g.depthMeters))
return false;
const float longest=std::max(g.widthMeters,g.depthMeters)+g.distanceMeters;
const float largestPath=std::sqrt(longest*longest+
g.distanceMeters*g.distanceMeters);
return (largestPath-g.distanceMeters)*48000.f/343.f+32.f <
static_cast<float>(ringFrames-3);
}
bool setGeometry(const SonKuRoomGeometry& g) noexcept {
if(active()||!validGeometry(g))return false;
geometry_=g;
custom_=true;
shape_=SonKuRoomShape::Square; // consistent 0.70 walls, not rectangle
untilGeometry_=0;
primed_=false;
return true;
}
float relativeDistanceGain() const noexcept {
return custom_?1.6f/geometry_.distanceMeters:1.f;
}
SonKuRoomShape shape() const noexcept {return shape_;}
bool active() const noexcept {return ready_&&(amount_>0.f||amountTarget_>0.f);}
float targetAmount() const noexcept {return amountTarget_;}
Expand Down Expand Up @@ -116,11 +151,13 @@ class SonKuEarlyReflections final {
}
void updateGeometry(double azimuth,float spread) noexcept {
constexpr float pi=3.14159265358979323846f;
constexpr float sourceDistance=1.60f; // meters
// The square profile tests rotationally symmetric wall geometry;
// it is not a simulated circular room or guaranteed psychoacoustics.
const float halfWidth=(shape_==SonKuRoomShape::Square)?3.60f:3.20f;
const float halfDepth=(shape_==SonKuRoomShape::Square)?3.60f:4.00f;
const float sourceDistance=custom_?geometry_.distanceMeters:1.60f;
// Preserve the approved 7.2m/1.6m path exactly when custom_ is false.
// A wider room changes physical image paths, not KEMAR azimuth signs.
const float halfWidth=custom_?geometry_.widthMeters*.5f:
((shape_==SonKuRoomShape::Square)?3.60f:3.20f);
const float halfDepth=custom_?geometry_.depthMeters*.5f:
((shape_==SonKuRoomShape::Square)?3.60f:4.00f);
constexpr float speedOfSound=343.f;
constexpr float earHalfTime=.00031f; // max +/-0.31ms
constexpr std::array<float,wallCount> rectangular{.74f,.74f,.67f,.67f};
Expand All @@ -145,7 +182,11 @@ class SonKuEarlyReflections final {
// symmetric while keeping every reflection causal.
const float common=extra+earHalfTime*rate_;
const float earDelta=directionX*earHalfTime*rate_;
const float level=.28f*walls[wall]*(sourceDistance/path);
// New distance studies use fixed 1.6m acoustic reference:
// pressure at a reflected path falls with 1/path. Legacy
// calculations are untouched at the accepted radius.
const float level=.28f*walls[wall]*
((custom_?1.6f:sourceDistance)/path);
auto& tap=tap_[source][wall];
tap.targetDelayL=std::clamp(common+earDelta,1.f,
static_cast<float>(ringFrames-3));
Expand All @@ -171,6 +212,7 @@ class SonKuEarlyReflections final {
float amount_=0.f,amountTarget_=0.f;
int write_=0,untilGeometry_=0;
SonKuRoomShape shape_=SonKuRoomShape::Rectangular;
bool ready_=false,primed_=false;
SonKuRoomGeometry geometry_{};
bool custom_=false,ready_=false,primed_=false;
};
} // namespace armix::sonku
21 changes: 19 additions & 2 deletions engine/builtin_fx/sonku/SonKuSpatialCore.h
Original file line number Diff line number Diff line change
Expand Up @@ -89,6 +89,10 @@ class SonKuSpatialCore final {
bool setEarlyReflectionsShape(SonKuRoomShape shape) noexcept {
return room_.setShape(shape);
}
// Offline M3 distance/large-room acoustic trial. Not a GUI/native ABI.
bool setAcousticRoomGeometry(const SonKuRoomGeometry& geometry) noexcept {
return room_.setGeometry(geometry);
}
// Experimental wet-only late room, OFF unless explicitly enabled by
// controlled offline A/B. The native parameter contract is unchanged.
bool setMusicalReverbAmount(float amount) noexcept {
Expand All @@ -105,6 +109,7 @@ class SonKuSpatialCore final {
if(!ready_ || !left || !right || samples<=0)return;
const double step=(settings_.moving ?
(settings_.clockwise?1.:-1.)*360./(sampleRate_*settings_.revolutionSeconds) : 0.);
const float distanceGain=room_.relativeDistanceGain();
for(int i=0;i<samples;++i) {
smoothedMix_+=levelSlew_*(settings_.spatialMix-smoothedMix_);
smoothedTrim_+=levelSlew_*(settings_.outputTrim-smoothedTrim_);
Expand Down Expand Up @@ -149,8 +154,20 @@ class SonKuSpatialCore final {
const auto late=reverb_.active()
?reverb_.process(x0,x1)
:SonKuMusicalReverb::Ears{};
left[i]=dryLevel*x0+binauralLevel*(ears[0]+reflection.left+late.left);
right[i]=dryLevel*x1+binauralLevel*(ears[1]+reflection.right+late.right);
// Exact legacy PCM arithmetic on the 1.6m reference (including
// all native instances). More distant experimental sources get
// inverse-distance pressure falloff on the DIRECT binaural field.
// ER uses matching absolute path pressure; diffuse late field
// remains an independent environmental stage.
if(distanceGain==1.f) {
left[i]=dryLevel*x0+binauralLevel*(ears[0]+reflection.left+late.left);
right[i]=dryLevel*x1+binauralLevel*(ears[1]+reflection.right+late.right);
} else {
left[i]=dryLevel*x0+binauralLevel*
(distanceGain*ears[0]+reflection.left+late.left);
right[i]=dryLevel*x1+binauralLevel*
(distanceGain*ears[1]+reflection.right+late.right);
}
if(++write_==taps)write_=0;
if(step!=0.) {
degrees_+=step;
Expand Down
41 changes: 41 additions & 0 deletions tests/sonku_early_reflections_test.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@
int main(){
using armix::sonku::SonKuEarlyReflections;
using armix::sonku::SonKuRoomShape;
using armix::sonku::SonKuRoomGeometry;
SonKuEarlyReflections invalid;
assert(!invalid.prepare(96000.));
assert(!invalid.prepare(std::numeric_limits<double>::quiet_NaN()));
Expand All @@ -30,6 +31,46 @@ int main(){
}
assert(soundEnergy>.004);
assert(mirrorError<1.e-4);
// The published user's approved square impulse must remain byte-exact
// when the same geometry is expressed explicitly.
{
SonKuEarlyReflections approved,explicitSquare;
assert(approved.prepare(rate)&&explicitSquare.prepare(rate));
assert(approved.setShape(SonKuRoomShape::Square));
assert(explicitSquare.setGeometry({7.2f,7.2f,1.6f}));
assert(approved.setAmount(.55f)&&explicitSquare.setAmount(.55f));
assert(!explicitSquare.setGeometry({14.4f,14.4f,5.f}));
for(int i=0;i<8192;++i) {
const float v=i==0?.75f:0.f;
const auto a0=approved.process(v,v,37.,45.f);
const auto b0=explicitSquare.process(v,v,37.,45.f);
assert(a0.left==b0.left&&a0.right==b0.right);
}
}
assert(!SonKuEarlyReflections::validGeometry({7.2f,7.2f,5.f}));
assert(!SonKuEarlyReflections::validGeometry({40.1f,40.f,1.6f}));
assert(!SonKuEarlyReflections::validGeometry({
std::numeric_limits<float>::quiet_NaN(),14.f,2.f}));
assert(SonKuEarlyReflections::validGeometry({14.4f,14.4f,5.f}));
assert(SonKuEarlyReflections::validGeometry({28.8f,28.8f,8.f}));
// Larger boundaries delay the FIRST reflected arrival. No longer
// room is faked by increasing a single reverb decay number.
{
SonKuEarlyReflections nearRoom,largeRoom;
assert(nearRoom.prepare(rate)&&largeRoom.prepare(rate));
assert(nearRoom.setShape(SonKuRoomShape::Square));
assert(largeRoom.setGeometry({28.8f,28.8f,1.6f}));
assert(nearRoom.setAmount(.55f)&&largeRoom.setAmount(.55f));
int nearFirst=-1,largeFirst=-1;
for(int i=0;i<8000;++i) {
const float v=i==0?1.f:0.f;
const auto a0=nearRoom.process(v,v,0.,0.f);
const auto b0=largeRoom.process(v,v,0.,0.f);
if(nearFirst<0 && (a0.left!=0.f||a0.right!=0.f))nearFirst=i;
if(largeFirst<0 && (b0.left!=0.f||b0.right!=0.f))largeFirst=i;
}
assert(nearFirst>100 && largeFirst>nearFirst+800);
}
SonKuEarlyReflections a,b;
assert(a.prepare(rate)&&b.prepare(rate));
assert(!a.active());
Expand Down
27 changes: 22 additions & 5 deletions tests/sonku_offline_demo_contract.py
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
import wave

root = Path(sys.argv[1] if len(sys.argv)>1 else "sonku-listening")
def read(name, frames):
def read(name, frames, minimum_peak=250, minimum_energy=100000):
path=root/name
assert path.exists() and path.stat().st_size>10000,path
with wave.open(str(path),"rb") as w:
Expand All @@ -18,8 +18,8 @@ def read(name, frames):
if sys.byteorder!="little":pcm.byteswap()
assert len(pcm)==2*frames
peak=max(map(abs,pcm))
assert 250<peak<30000,(name,peak)
assert sum(abs(x) for x in pcm[:48000])>100000,(name,"unexpected silence")
assert minimum_peak<peak<30000,(name,peak)
assert sum(abs(x) for x in pcm[:48000])>minimum_energy,(name,"unexpected silence")
return pcm
single=read("sonku-reference-four.wav",4*120000)
blind=read("sonku-blind-eight.wav",8*120000)
Expand All @@ -35,6 +35,22 @@ def read(name, frames):
musicBase=read("sonku-musical-square-base-2x.wav",960000)
musicGlue=read("sonku-musical-square-glue-2x.wav",960000)
musicAiry=read("sonku-musical-square-airy-2x.wav",960000)
spaciousNear=read("sonku-v4-spacious-near-orbit-cw-2x.wav",960000)
spaciousFar=read("sonku-v4-spacious-far-orbit-cw-2x.wav",960000,60,10000)
largeNear=read("sonku-v4-large-near-orbit-cw-2x.wav",960000)
largeFar=read("sonku-v4-large-far-orbit-cw-2x.wav",960000,40,8000)
# Same source and identical 20s orbital clock: room width only changes
# path delay/level; source distance only changes geometric pressure.
def pcm_delta(a,b):
return sum(abs(int(x)-int(y)) for x,y in zip(a[300000:440000],b[300000:440000]))
assert pcm_delta(spaciousNear,squareOrbit)>1500,"Spacious room is identical to approved square"
assert pcm_delta(largeNear,spaciousNear)>1500,"Large and spacious room are identical"
assert pcm_delta(spaciousFar,spaciousNear)>1500,"5m source ignored"
assert pcm_delta(largeFar,largeNear)>1500,"8m source ignored"
def energy(a):
return sum(abs(int(x)) for x in a[300000:440000])
assert .08<energy(spaciousFar)/energy(spaciousNear)<.75,"Unexpected 5m distance pressure"
assert .05<energy(largeFar)/energy(largeNear)<.70,"Unexpected 8m distance pressure"
# Baseline V1 and candidate V2 are deliberately non-identical on same noise.
# Room must affect later samples, not fake position on the direct sound.
difference=sum(abs(int(a)-int(b)) for a,b in
Expand Down Expand Up @@ -72,10 +88,11 @@ def read(name, frames):
assert sum(abs(x) for x in orbit[220000:230000])>1000
# Verify there is no mute, edit or source reset at the 10s handoff.
# Stereo interleaved: 48000 samples = 1 second, 2 PCM ints per frame.
for audio in (orbit,v2orbit,squareOrbit,reverse,reverseRoom,reverseSquare,glue,airy):
for audio in (orbit,v2orbit,squareOrbit,reverse,reverseRoom,reverseSquare,
glue,airy,spaciousNear,spaciousFar,largeNear,largeFar):
for second in (9,10,11,19):
begin=(second*48000+4000)*2
assert sum(abs(x) for x in audio[begin:begin+9600])>2000,(
assert sum(abs(x) for x in audio[begin:begin+9600])>400,(
"silent loop seam",second)
assert "20s" in (root/"LISTENING-GUIDE.txt").read_text()
assert not (root/"sonku-orbit-cw.wav").exists(),(
Expand Down
Loading
Loading