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
26 changes: 26 additions & 0 deletions .github/workflows/sonku-p7-research.yml
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ on:
paths:
- 'engine/builtin_fx/sonku/**'
- 'tests/sonku_p7_*'
- 'tests/sonku_p71_*'
- 'tools/sonku_offline_listening.cpp'
- 'tools/sonku_p7_cpu.cpp'
- '.github/workflows/sonku-p7-research.yml'
Expand Down Expand Up @@ -47,16 +48,41 @@ jobs:
run: |
g++ -std=c++20 -O2 -Wall -Wextra -pedantic -DSONKU_P7_MEASURED_ELEVATION_RESEARCH=1 tests/sonku_p7_six_surface_test.cpp -o /tmp/p7
/tmp/p7
- name: P7.1 true XYZ source direct HRTF 44.1/48k and phase-safe spatial PCM
run: |
g++ -std=c++20 -O2 -Wall -Wextra -pedantic -DSONKU_P7_MEASURED_ELEVATION_RESEARCH=1 -DSONKU_P71_DIRECT_XYZ_RESEARCH=1 tests/sonku_p71_xyz_direct_test.cpp -o /tmp/p71
/tmp/p71
- name: Four matched P6 four-wall versus P7 six-plane realtime ROOM WAV pairs
run: |
g++ -std=c++20 -O2 -Wall -Wextra -pedantic -DSONKU_P7_MEASURED_ELEVATION_RESEARCH=1 tools/sonku_offline_listening.cpp -o /tmp/p7-render
mkdir -p sonku-p7-evidence
/tmp/p7-render sonku-p7-evidence --p7-six-surface-only
python tests/sonku_p7_six_surface_audio_audit.py sonku-p7-evidence
- name: P7.1 measured direct elevation original same-source 12 WAVs
run: |
g++ -std=c++20 -O2 -Wall -Wextra -pedantic -DSONKU_P7_MEASURED_ELEVATION_RESEARCH=1 -DSONKU_P71_DIRECT_XYZ_RESEARCH=1 tools/sonku_offline_listening.cpp -o /tmp/p71-render
/tmp/p71-render sonku-p7-evidence --p71-xyz-direct-only
- name: P7.1 fused FIR fast path against exact P7 original WAV reference
run: |
mkdir -p /tmp/sonku-p71-fir-fast
/tmp/p71-render /tmp/sonku-p71-fir-fast --p7-six-surface-only
python tests/sonku_p71_fir_parity_audit.py sonku-p7-evidence /tmp/sonku-p71-fir-fast
- name: P7.1 measure same-source XYZ direct stereo musical integrity / per-ear acoustics
run: |
python tests/sonku_p71_xyz_audio_audit.py sonku-p7-evidence
- name: Informational CPU 1/2/4 inserts P6 versus P7 48k/128
run: |
g++ -std=c++20 -O2 -Wall -Wextra -pedantic -DSONKU_P7_MEASURED_ELEVATION_RESEARCH=1 tools/sonku_p7_cpu.cpp -o /tmp/p7-bench
/tmp/p7-bench | tee sonku-p7-evidence/SONKU-P7-CPU-REPORT.txt
- name: Informational P7.1 direct XYZ CPU 1/2/4 inserts, 0/+25/-25 degrees
run: |
g++ -std=c++20 -O2 -Wall -Wextra -pedantic -DSONKU_P7_MEASURED_ELEVATION_RESEARCH=1 -DSONKU_P71_DIRECT_XYZ_RESEARCH=1 tools/sonku_p7_cpu.cpp -o /tmp/p71-bench
/tmp/p71-bench | grep SONKU_P71_CPU | tee sonku-p7-evidence/SONKU-P71-CPU-REPORT.txt
- name: P7.1 controlled interleaved old-vs-fast FIR benchmark (informational)
run: |
g++ -std=c++20 -O2 -Wall -Wextra -pedantic -DSONKU_P7_MEASURED_ELEVATION_RESEARCH=1 tools/sonku_p71_hotpath_benchmark.cpp -o /tmp/p71-original
g++ -std=c++20 -O2 -Wall -Wextra -pedantic -DSONKU_P7_MEASURED_ELEVATION_RESEARCH=1 -DSONKU_P71_DIRECT_XYZ_RESEARCH=1 tools/sonku_p71_hotpath_benchmark.cpp -o /tmp/p71-fast
python tests/sonku_p71_interleaved_cpu_audit.py /tmp/p71-original /tmp/p71-fast sonku-p7-evidence
- name: Upload 8 matched lossless WAV and JSON/CPU evidence
if: ${{ always() }}
uses: actions/upload-artifact@v4
Expand Down
54 changes: 54 additions & 0 deletions .github/workflows/sonku-p71-windows-core.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
name: SonKu P7.1 native Windows core — focused and no JUCE SDK
# P7.1 research only, independent of installer, ASIO, and Vocal Harmony.
on:
pull_request:
types: [opened, reopened, synchronize, ready_for_review]
paths:
- 'engine/builtin_fx/sonku/SonKuSpatialCore.h'
- 'engine/builtin_fx/sonku/SonKuEarlyReflections.h'
- 'engine/builtin_fx/sonku/SonKuVerticalImageSource.h'
- 'engine/builtin_fx/sonku/SonKuSourcePlacement3D.h'
- 'engine/builtin_fx/sonku/SonKuMeasuredHrir3D.h'
- 'tests/sonku_p71_xyz_direct_test.cpp'
- 'tests/sonku_p71_windows/CMakeLists.txt'
- '.github/workflows/sonku-p71-windows-core.yml'
permissions:
contents: read
concurrency:
group: sonku-p71-win-${{ github.event.pull_request.number }}
cancel-in-progress: true
jobs:
native:
name: Windows MSVC 20 — P7.1 XYZ and P6 default PCM (two tiny targets)
runs-on: windows-2022
timeout-minutes: 12
steps:
- uses: actions/checkout@v4
with:
ref: ${{ github.event.pull_request.head.sha }}
- name: Refuse stale/incorrect source SHA
shell: pwsh
env:
EXPECTED_SHA: ${{ github.event.pull_request.head.sha }}
run: |
$actual=(& git rev-parse HEAD).Trim()
if($LASTEXITCODE -ne 0 -or $actual -ne $env:EXPECTED_SHA) {
throw "SONKU_P71_SHA_MISMATCH expected=$env:EXPECTED_SHA actual=$actual"
}
Write-Host "SONKU_P71_WINDOWS_CORE_SHA=$actual"
- name: Configure isolated MSVC source tests (no JUCE or WebView2)
shell: pwsh
run: |
cmake -S tests/sonku_p71_windows -B build-p71-win -G "Visual Studio 17 2022" -A x64
if($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
- name: Compile two exact native C++20 source regression targets
shell: pwsh
run: |
cmake --build build-p71-win --config Release --parallel 2 --target SonKuP71XYZSource SonKuP6DefaultRegression
if($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
- name: 44.1k/48k measured HRTF XYZ PCM and P6 default assertions
shell: pwsh
run: |
ctest --test-dir build-p71-win -C Release --output-on-failure
if($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
Write-Host 'SONKU_P71_MSVC_SOURCE_PCM=PASS no_ASIO_hardware_claim'
83 changes: 83 additions & 0 deletions docs/SONKU_P71_DIRECT_XYZ_MEASURED_SOURCE_20261114.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,83 @@
# SonKu P7.1 — source XYZ / measured DIRECT HRTF, experiment

2026-11-14 | stacked PR #681 → P7 #679 → P6 #678 → P0–P5 #674.
**This milestone is research implementation, not Windows ASIO or dearVR
parity certification.** No main/installer change.

## Physics, source of truth and control-plane safety

The 44.1k/48k MIT KEMAR 14-band measurement bank already pinned in P7
is reused for the **direct** binaural FIR (L/R emitters *and* coherent
MID correction) with no extra convolution or per-tap magic EQ.
Source radial distance remains the original accepted 1.6–10m, projected
at a measured elevation to horizontal distance = r*cos(theta) and
source height = earHeight + r*sin(theta). First-order wall image sources
use (x,y,z) path length, arrival elevation/azimuth and measured KEMAR
coefficients, while floor/ceiling images use the true reflected source
height and subtract the **3D source radial path**, not an incorrect
horizontal-only direct distance. At elevation 0, original four walls,
P7 vertical reflections and direct measured horizontal bank are preserved.

A single `SonKuSpatialCore::setResearchDirectElevation()` accepts only
a pre-prepared `SixSurfaceKemarResearch` instance before *any* PCM
has been processed, validates source clearance within the current
3D room, rejects NaN and impossible positions, and does not add a
public FX parameter, .smix version, GUI gesture or audio callback mutation.
It is guarded by BOTH `SONKU_P7_MEASURED_ELEVATION_RESEARCH=1`
and `SONKU_P71_DIRECT_XYZ_RESEARCH=1`; neither appears in public JUCE.
Per-frame FIR tap count remains 140; moving source orientation is the
original azimuth clock and the new elevation is constant within a
quiescent research render. A real user-controllable XYZ scene requires
a **separate approved host UI/state/ACK design**, not an invisible knob.

## Evidence and disqualifiers

The native CI covers 44.1/48k, true distance projection, room-clearance
rejection, above/below path geometry and direct HRIR ear mirror,
mid/side phase and chunk-parity with 64/257 irregular partitions,
no post-publish changes, and prepared restart/downgrade to P6.
A/B/C 12 lossless original source 48k stereo WAVs compare horizontal
versus +25°/-25° direct placement in FRONT/REAR and 0/60° spread.
Goertzel offline instrument evidence measures 220/660/940/3200/4700Hz
per-ear level, interaural level and phase, flags significant spectral
changes for human review; these are not perceptual quality scores.

Performance measurement is only same-runner Linux C++ timing of 1/2/4
concurrent stereo instances; the new measured-elevation interpolation
updates every 16 direct/64 reflection PCM frames and introduces no new
FIR in the callback. This **does not** qualify p99/XRUN on physical ASIO.
No hidden adaptive DSP mode switch, plugin duplication, bit-depth
truncation, per-buffer heap/clock, synchronous logging or background work.

P7.1 source-level milestone can be marked complete after the exact
CI SHA passes, but public feature remains vetoed until actual
Windows ASIO, performance headroom, author-approved FX/UX workflow,
.lsmix/.smix persistence and headphone blind tests versus dearVR are
satisfactory. Do not merge stacked drafts prematurely.

## P7.1 FIR fast-path experiment

A second, macro-gated FIR implementation splits the convolution into
**valid epoch samples** and **warm-up kernel advancement**. Once the delay
ring is warm, the full 140-tap reflection convolution does not execute
the former per-tap stale-history conditional. The filter kernel still
slews for every tap, including silent warm-up samples, and the exact
P3 0° stereo fusion/0–60° states remain. This is not truncation,
interpolation approximation, a hidden adaptive DSP path, or a new mixer.

The scoped native CI compiles the original P7 C++ room WAV fixture twice,
with and without the P7.1 macro, for FRONT/REAR, 0°/60°, four-wall/six-surface,
then compares all 8 × 144000 × 2 samples at <= 1 signed-16-bit LSB.
CPU 1/2/4 insert timing is informational and must demonstrate real
benefit before shipping any optimization.

### Closure / immutability guarantee

The research edit gate now stays closed after any PCM has run even if
`reset()` is called. Only `prepare()` may explicitly re-enter an
unpublished research session, preventing a reset-based concurrent
control bypass. OFF scene placement uses conservative 3.2 m height
validation so future selection of SQUARE cannot silently accept an
impossible elevated source. Physical XYZ editing during playback and
host ACK remain **not supported** until an explicit realtime architecture
is approved; this avoids fake editor/control state.
73 changes: 67 additions & 6 deletions engine/builtin_fx/sonku/SonKuEarlyReflections.h
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,9 @@
#if defined(SONKU_P7_MEASURED_ELEVATION_RESEARCH) && SONKU_P7_MEASURED_ELEVATION_RESEARCH
#include "SonKuMeasuredHrir3D.h"
#include "SonKuVerticalImageSource.h"
#if defined(SONKU_P71_DIRECT_XYZ_RESEARCH) && SONKU_P71_DIRECT_XYZ_RESEARCH
#include "SonKuSourcePlacement3D.h"
#endif
#endif

// Bounded first-order image-source room (Allen & Berkley JASA, 1979).
Expand Down Expand Up @@ -172,7 +175,11 @@ class SonKuEarlyReflections final {
if(enabled && profile_==SonKuReflectionProfile::SixSurfaceKemarResearch &&
!sixsurface::fitsDelayRing(
{g.heightMeters,g.listenerHeightMeters,g.sourceHeightMeters},
g.distanceMeters,rate_,ringFrames,hrir::taps))return false;
(g.distanceMeters!=0.f?
std::sqrt(std::max(0.f,g.distanceMeters*g.distanceMeters-
(g.sourceHeightMeters-g.listenerHeightMeters)*
(g.sourceHeightMeters-g.listenerHeightMeters))):0.f),
rate_,ringFrames,hrir::taps))return false;
#endif
if(!active() && enabled && amount>0.f){
validFrames_=0; lowpass_.fill(0.f);
Expand Down Expand Up @@ -252,10 +259,39 @@ class SonKuEarlyReflections final {
// Zero-filling a 64KiB ring inside the callback is banned.
const int freshTaps=realtimeMode_?
std::clamp(validFrames_-d,0,hrir::taps):hrir::taps;
#if !defined(SONKU_P71_DIRECT_XYZ_RESEARCH) || !SONKU_P71_DIRECT_XYZ_RESEARCH
const bool warming=freshTaps<hrir::taps;
#endif
// One source of truth for the coefficient slew and ear
// FIR arithmetic; only history address selection varies.
// Advance kernels even while history is warming.
#if defined(SONKU_P71_DIRECT_XYZ_RESEARCH) && SONKU_P71_DIRECT_XYZ_RESEARCH
// P7.1 measured-only hot path. In the overwhelmingly
// common fully warm ring, the 140-tap FIR has NO
// per-tap fresh-history comparison. Warm-up still
// advances ALL filter kernels, but reads no pre-OFF
// samples: zero extra heap, tables, clocks or FIRs.
const auto advance=[&](int k) noexcept {
auto& hL=p.kernel[0][k];
auto& hR=p.kernel[1][k];
hL+=kernelSlew_*(p.targetKernel[0][k]-hL);
hR+=kernelSlew_*(p.targetKernel[1][k]-hR);
if(fused){
tap_[1][wall].kernel[0][k]=hL;
tap_[1][wall].kernel[1][k]=hR;
}
return std::array<float,2>{hL,hR};
};
const auto render=[&](auto&& sample) noexcept {
for(int k=0;k<freshTaps;++k){
const float v=sample(k);
const auto h=advance(k);
l+=v*h[0];r+=v*h[1];
}
for(int k=freshTaps;k<hrir::taps;++k)
(void)advance(k);
};
#else
const auto render=[&](auto&& sample) noexcept {
for(int k=0;k<hrir::taps;++k){
const float v=(warming && k>=freshTaps)
Expand All @@ -271,6 +307,7 @@ class SonKuEarlyReflections final {
l+=v*hL;r+=v*hR;
}
};
#endif
if(fastContiguousHrir_ && idx>=hrir::taps){
// For 8052/8192 ring positions the entire 140-tap
// window is continuous; no wrap mask inside FIR.
Expand Down Expand Up @@ -339,6 +376,17 @@ class SonKuEarlyReflections final {
void updateGeometry(double azimuth,float spread) noexcept {
constexpr float pi=3.14159265358979323846f;
const float sourceDistance=custom_?geometry_.distanceMeters:1.60f;
// The existing four-wall path stays bit-exact at equal source/ear
// height. Only explicitly enabled research geometry projects true XYZ.
float horizontalDistance=sourceDistance,dz=0.f;
#if defined(SONKU_P71_DIRECT_XYZ_RESEARCH) && SONKU_P71_DIRECT_XYZ_RESEARCH
if(profile_==SonKuReflectionProfile::SixSurfaceKemarResearch &&
geometry_.sourceHeightMeters!=geometry_.listenerHeightMeters) {
dz=geometry_.sourceHeightMeters-geometry_.listenerHeightMeters;
horizontalDistance=std::sqrt(std::max(0.f,
sourceDistance*sourceDistance-dz*dz));
}
#endif
// 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:
Expand All @@ -354,16 +402,18 @@ class SonKuEarlyReflections final {
const float degrees=static_cast<float>(azimuth)
+(source==0?-.5f:.5f)*spread;
const float rad=degrees*(pi/180.f);
const float sx=sourceDistance*std::sin(rad);
const float sy=sourceDistance*std::cos(rad);
const float sx=horizontalDistance*std::sin(rad);
const float sy=horizontalDistance*std::cos(rad);
const std::array<std::array<float,2>,wallCount> images{{
{{-2.f*halfWidth-sx,sy}},{{2.f*halfWidth-sx,sy}},
{{sx,2.f*halfDepth-sy}},{{sx,-2.f*halfDepth-sy}}
}};
for(int wall=0;wall<wallCount;++wall){
const float x=images[wall][0],y=images[wall][1];
const float path=std::sqrt(x*x+y*y);
const float directionX=x/path;
const float planarPath=std::sqrt(x*x+y*y);
const float path=dz!=0.f?
std::hypot(planarPath,dz):planarPath;
const float directionX=x/planarPath;
const float extra=(path-sourceDistance)*rate_/speedOfSound;
// Constant 0.31ms ear baseline makes differential ITD
// symmetric while keeping every reflection causal.
Expand All @@ -384,6 +434,16 @@ class SonKuEarlyReflections final {
if(directionalHrir_){
// The IMAGE-source arrival angle, NOT source azimuth.
const float dir=std::atan2(x,y)*180.f/pi;
#if defined(SONKU_P71_DIRECT_XYZ_RESEARCH) && SONKU_P71_DIRECT_XYZ_RESEARCH
if(profile_==SonKuReflectionProfile::SixSurfaceKemarResearch &&
dz!=0.f){
hrir3d::interpolate(dir,std::atan2(dz,planarPath)*180.f/pi,
std::abs(rate_-44100.f)<.1f,
tap.targetKernel);
if(!primed_)tap.kernel=tap.targetKernel;
}else
#endif
{
const float pos=std::abs(dir)/hrir::spacingDegrees;
const int lo=std::clamp(static_cast<int>(pos),0,
hrir::directions-1);
Expand All @@ -400,6 +460,7 @@ class SonKuEarlyReflections final {
if(!primed_)tap.kernel[ear][k]=value;
}
}
}
}
if(!primed_){
tap.delayL=tap.targetDelayL;
Expand All @@ -421,7 +482,7 @@ class SonKuEarlyReflections final {
const auto boundary=i==0?sixsurface::Boundary::Floor:
sixsurface::Boundary::Ceiling;
const auto arrival=sixsurface::image(
heights,sourceDistance,sourceAz,boundary,rate_);
heights,horizontalDistance,sourceAz,boundary,rate_);
auto& p=tap_[source][wallCount+i];
// Measured HRIR already contains directional ITD/ILD.
// No invented extra ear delay, EQ or pseudo elevation.
Expand Down
33 changes: 33 additions & 0 deletions engine/builtin_fx/sonku/SonKuSourcePlacement3D.h
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
// SPDX-License-Identifier: AGPL-3.0-only
#pragma once
// Exact source-to-listener spherical -> Cartesian geometry, research only.
// No new parameter/schema; this is a quiescent off-line native DSP control.
#include <algorithm>
#include <cmath>
namespace armix::sonku::xyz {
struct Placement {
float horizontalMeters=1.6f;
float sourceHeightMeters=1.45f;
float heightDeltaMeters=0.f;
float directDistanceMeters=1.6f;
};
inline bool project(float radialMeters,float elevationDegrees,
float listenerHeight,float roomHeight,
Placement& result) noexcept {
if(!std::isfinite(radialMeters)||!std::isfinite(elevationDegrees)||
!std::isfinite(listenerHeight)||!std::isfinite(roomHeight)||
radialMeters<1.6f||radialMeters>10.f||
elevationDegrees< -40.f||elevationDegrees>60.f||
roomHeight<2.4f||roomHeight>12.f||
listenerHeight<.5f||listenerHeight>roomHeight-.5f)return false;
constexpr float radians=.017453292519943295769f;
const float z=radialMeters*std::sin(elevationDegrees*radians);
const float horizontal=radialMeters*std::cos(elevationDegrees*radians);
const float height=listenerHeight+z;
if(height<.5f||height>roomHeight-.5f||horizontal<.7f)return false;
const float distance=std::hypot(horizontal,z);
if(!(distance>0.f)||!std::isfinite(distance))return false;
result={horizontal,height,z,radialMeters};
return true;
}
} // namespace armix::sonku::xyz
Loading
Loading