Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
6e599ac
feat(sonku): opt-in constant-radius front/rear DRR calibration with r…
masarray Nov 16, 2026
d48541c
feat(sonku): isolate P9.4 front/back depth cue to measured P9 direct/…
masarray Nov 16, 2026
b41be8a
build(sonku): opt-in P9.4 front/back calibration default OFF and isol…
masarray Nov 16, 2026
816cd95
test(sonku): 44.1/48k real P9 front/rear DRR proxy, room OFF neutrali…
masarray Nov 16, 2026
bd403a3
feat(sonku): native v11 readback advertises optional P9.4 front/rear …
masarray Nov 16, 2026
e6b47c6
ui(sonku): capability-gated P9.4 experimental label with P9.1/P9.2 fa…
masarray Nov 16, 2026
33c3045
test(sonku): P9.4 native flag truth, stable 40-readback dropdown, P9.…
masarray Nov 16, 2026
47fc43d
test(sonku): let 45ms smoothing reach exact neutral target before bit…
masarray Nov 16, 2026
b6cafa6
docs(sonku): preserve approved 3D ellipse and define measurable front…
masarray Nov 16, 2026
5f43cda
ci(sonku): opt-in P9.4 native source and Windows JUCE/6-CTest FAT wit…
masarray Nov 16, 2026
936c5cd
test(sonku): align P9.4 menu fixture with actual render selection bef…
masarray Nov 16, 2026
e47dc95
test(sonku): compile identical P9 native stimulus as baseline and exp…
masarray Nov 16, 2026
10f5480
test(sonku): compare actual P9.1 vs P9.4 PCM RMS at 0/90/180/270, enf…
masarray Nov 16, 2026
f55e435
test(sonku): two native P9 binaries + automated same-source level-mat…
masarray Nov 16, 2026
766b8d7
ci(sonku): compare P9.4 opt-in against golden P9.1 same-source PCM on…
masarray Nov 16, 2026
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
21 changes: 15 additions & 6 deletions .github/workflows/p1-windows.yml
Original file line number Diff line number Diff line change
Expand Up @@ -660,7 +660,7 @@ jobs:
sonku-p90-source:
# Runs only on the P9 research PR, even while its production jobs skip.
name: SonKu P9 exact-source C++ PCM preflight
if: ${{ github.event_name == 'pull_request' && (startsWith(github.event.pull_request.head.ref, 'research/sonku-p90-') || (startsWith(github.event.pull_request.head.ref, 'research/sonku-p91-p92-') || startsWith(github.event.pull_request.head.ref, 'feat/sonku-p93-'))) }}
if: ${{ github.event_name == 'pull_request' && (startsWith(github.event.pull_request.head.ref, 'research/sonku-p90-') || (startsWith(github.event.pull_request.head.ref, 'research/sonku-p91-p92-') || (startsWith(github.event.pull_request.head.ref, 'feat/sonku-p93-') || startsWith(github.event.pull_request.head.ref, 'research/sonku-p94-')))) }}
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
Expand All @@ -680,14 +680,18 @@ jobs:
/tmp/sonku-p90
g++ $FLAGS tests/sonku_p91_p92_music_bass_foundation_test.cpp -o /tmp/sonku-p91p92
/tmp/sonku-p91p92
g++ $FLAGS tests/sonku_p94_front_back_depth_source_test.cpp -o /tmp/sonku-p94-reference
g++ $FLAGS -DSONKU_P94_FRONT_BACK_DEPTH_RESEARCH=1 tests/sonku_p94_front_back_depth_source_test.cpp -o /tmp/sonku-p94
/tmp/sonku-p94
python3 scripts/verify_sonku_p94_acoustic_levels.py /tmp/sonku-p94-reference /tmp/sonku-p94
g++ $FLAGS tests/sonku_p89_stereo_room_depth_source_test.cpp -o /tmp/sonku-p89
/tmp/sonku-p89
echo "SONKU_P90_NATIVE_SOURCE_CTEST_PASSED"

sonku-p90-windows-fat:
name: SonKu P9 actual JUCE / GUI portable x64
needs: sonku-p90-source
if: ${{ github.event_name == 'pull_request' && (startsWith(github.event.pull_request.head.ref, 'research/sonku-p90-') || (startsWith(github.event.pull_request.head.ref, 'research/sonku-p91-p92-') || startsWith(github.event.pull_request.head.ref, 'feat/sonku-p93-'))) }}
if: ${{ github.event_name == 'pull_request' && (startsWith(github.event.pull_request.head.ref, 'research/sonku-p90-') || (startsWith(github.event.pull_request.head.ref, 'research/sonku-p91-p92-') || (startsWith(github.event.pull_request.head.ref, 'feat/sonku-p93-') || startsWith(github.event.pull_request.head.ref, 'research/sonku-p94-')))) }}
runs-on: windows-2022
timeout-minutes: 55
steps:
Expand Down Expand Up @@ -724,21 +728,25 @@ jobs:
-DARMIX_SONKU_EXPERIMENTAL_P88_NATIVE_RT=ON `
-DARMIX_SONKU_EXPERIMENTAL_P89_NATIVE_RT=ON `
-DARMIX_SONKU_EXPERIMENTAL_P90_NATIVE_RT=ON `
-DARMIX_SONKU_EXPERIMENTAL_P94_FRONT_BACK_DEPTH=ON `
-DBUILD_TESTING=ON
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
$cache = Get-Content build/CMakeCache.txt -Raw
if ($cache -notmatch 'ARMIX_SONKU_EXPERIMENTAL_P90_NATIVE_RT:BOOL=ON') {
throw 'SONKU_P90_WRONG_NATIVE_CONFIGURATION'
}
if ($cache -notmatch 'ARMIX_SONKU_EXPERIMENTAL_P94_FRONT_BACK_DEPTH:BOOL=ON') {
throw 'SONKU_P94_WRONG_NATIVE_CONFIGURATION'
}
- name: Build real native JUCE PCM, state ACK, and Windows GUI
shell: pwsh
run: |
cmake --build build --config Release --parallel 2 --target ARMixSonKuP91P92MusicBassTests ARMixSonKuP90NativeTests ARMixSonKuP90SourceTests ARMixSonKuP89NativeTests ARMixSonKuP89SourceTests ARMixConsole
cmake --build build --config Release --parallel 2 --target ARMixSonKuP94SourceTests ARMixSonKuP94ReferenceTests ARMixSonKuP91P92MusicBassTests ARMixSonKuP90NativeTests ARMixSonKuP90SourceTests ARMixSonKuP89NativeTests ARMixSonKuP89SourceTests ARMixConsole
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
if (-not (Test-Path -LiteralPath 'build/ARMixConsole_artefacts/Release/AR MIX Studio.exe' -PathType Leaf)) {
throw 'SONKU_P90_NATIVE_GUI_EXE_MISSING'
}
ctest --test-dir build -C Release --output-on-failure -R '^NativeSonKuP(89RoomAnchoredStereoAndP88GoldenParity|89JuceV10AppliedAckAndV9Restore|90StereoExternalizationSource|90JuceV11AppliedAckAndLegacyRestore|91P92MusicFidelityWorldBassAndRoom)$'
ctest --test-dir build -C Release --output-on-failure -R '^NativeSonKuP(89RoomAnchoredStereoAndP88GoldenParity|89JuceV10AppliedAckAndV9Restore|90StereoExternalizationSource|90JuceV11AppliedAckAndLegacyRestore|91P92MusicFidelityWorldBassAndRoom|94FrontBackDepthA_BSource|94LevelMatchedAB)$'
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
- name: Verified portable package, no installer or release
shell: pwsh
Expand All @@ -752,12 +760,13 @@ jobs:
Copy-Item docs/THIRD_PARTY_8D_SONKU_HRTF.md dist/THIRD_PARTY_8D_SONKU_HRTF.md
Copy-Item docs/SONKU_P90_TRUE_EXTERNAL_SPEAKER_FAT_20261115.md dist/SONKU_P90_FIELD_FAT.md
Copy-Item docs/SONKU_P91_P92_RECONCILED_MUSIC_FIDELITY_BASS_FAT_20261116.md dist/SONKU_P91_P92_FIELD_FAT.md
Copy-Item docs/SONKU_P94_FRONT_REAR_EXTERNALIZATION_FAT_20261116.md dist/SONKU_P94_FRONT_REAR_FAT.md
$provenance = Get-Content -LiteralPath dist/BUILD_PROVENANCE.json -Raw | ConvertFrom-Json
if ($provenance.sourceCommit -ne (git rev-parse HEAD).Trim()) {
throw 'SONKU_P90_SOURCE_COMMIT_MISMATCH'
}
$provenance | Add-Member -Force -NotePropertyName sonkuExperiment -NotePropertyValue @{
mode = 'P9.1_P9.2_MUSIC_FIDELITY_PHYSICAL_BASS'
mode = 'P9.4_FRONT_REAR_DEPTH_EXPERIMENT'
stateSchema = 11
headphoneFat = 'PENDING'
publicRelease = $false
Expand All @@ -767,7 +776,7 @@ jobs:
$provenance | ConvertTo-Json -Depth 20 | Set-Content dist/BUILD_PROVENANCE.json -Encoding utf8
- uses: actions/upload-artifact@v4
with:
name: ArSonMix-SonKu-P90-Windows-x64-${{ github.run_id }}
name: ArSonMix-SonKu-P94-FrontRear-Research-Windows-x64-${{ github.run_id }}
path: dist/
if-no-files-found: error
retention-days: 21
Expand Down
33 changes: 32 additions & 1 deletion CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -96,6 +96,13 @@ if(ARMIX_SONKU_EXPERIMENTAL_P90_NATIVE_RT AND
NOT ARMIX_SONKU_EXPERIMENTAL_P89_NATIVE_RT)
message(FATAL_ERROR "P9.0 requires P8.9 research branch baseline")
endif()
# Private P9.4 perceptual A/B: default OFF and never silently changes P9.1.
option(ARMIX_SONKU_EXPERIMENTAL_P94_FRONT_BACK_DEPTH
"Private front/back HRTF/early reflection depth calibration experiment" OFF)
if(ARMIX_SONKU_EXPERIMENTAL_P94_FRONT_BACK_DEPTH AND
NOT ARMIX_SONKU_EXPERIMENTAL_P90_NATIVE_RT)
message(FATAL_ERROR "P9.4 depth cue requires the P9 measured two-speaker engine")
endif()
set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

Expand Down Expand Up @@ -312,7 +319,9 @@ target_compile_definitions(ARMixConsole PRIVATE
$<$<BOOL:${ARMIX_SONKU_EXPERIMENTAL_P89_NATIVE_RT}>:ARMIX_SONKU_EXPERIMENTAL_P89_NATIVE_RT=1>
$<$<BOOL:${ARMIX_SONKU_EXPERIMENTAL_P89_NATIVE_RT}>:SONKU_P89_DEPTH_COHERENCE_RESEARCH=1>
$<$<BOOL:${ARMIX_SONKU_EXPERIMENTAL_P90_NATIVE_RT}>:ARMIX_SONKU_EXPERIMENTAL_P90_NATIVE_RT=1>
$<$<BOOL:${ARMIX_SONKU_EXPERIMENTAL_P90_NATIVE_RT}>:SONKU_P90_TRUE_EXTERNAL_RESEARCH=1>)
$<$<BOOL:${ARMIX_SONKU_EXPERIMENTAL_P90_NATIVE_RT}>:SONKU_P90_TRUE_EXTERNAL_RESEARCH=1>
$<$<BOOL:${ARMIX_SONKU_EXPERIMENTAL_P94_FRONT_BACK_DEPTH}>:SONKU_P94_FRONT_BACK_DEPTH_RESEARCH=1>
$<$<BOOL:${ARMIX_SONKU_EXPERIMENTAL_P94_FRONT_BACK_DEPTH}>:ARMIX_SONKU_EXPERIMENTAL_P94_FRONT_BACK_DEPTH=1>)
if(WIN32)
# Windows retains its proven ASIO-first / WASAPI / static WebView2 distribution.
# Never link Windows loader or sound APIs into macOS/Linux builds.
Expand Down Expand Up @@ -817,6 +826,28 @@ if(BUILD_TESTING)
SONKU_P90_TRUE_EXTERNAL_RESEARCH=1)
add_test(NAME NativeSonKuP91P92MusicFidelityWorldBassAndRoom
COMMAND ARMixSonKuP91P92MusicBassTests)
if(ARMIX_SONKU_EXPERIMENTAL_P94_FRONT_BACK_DEPTH)
add_executable(ARMixSonKuP94ReferenceTests
tests/sonku_p94_front_back_depth_source_test.cpp)
target_compile_features(ARMixSonKuP94ReferenceTests PRIVATE cxx_std_20)
target_compile_definitions(ARMixSonKuP94ReferenceTests PRIVATE
$<TARGET_PROPERTY:ARMixSonKuP91P92MusicBassTests,COMPILE_DEFINITIONS>)
add_executable(ARMixSonKuP94SourceTests
tests/sonku_p94_front_back_depth_source_test.cpp)
target_compile_features(ARMixSonKuP94SourceTests PRIVATE cxx_std_20)
# Reuse the proven exact P9.1/P9.2 native flag set.
# Do not duplicate a parallel DSP/test configuration.
target_compile_definitions(ARMixSonKuP94SourceTests PRIVATE
$<TARGET_PROPERTY:ARMixSonKuP91P92MusicBassTests,COMPILE_DEFINITIONS>
SONKU_P94_FRONT_BACK_DEPTH_RESEARCH=1)
add_test(NAME NativeSonKuP94FrontBackDepthA_BSource
COMMAND ARMixSonKuP94SourceTests)
add_test(NAME NativeSonKuP94LevelMatchedAB
COMMAND "${Python3_EXECUTABLE}"
"${CMAKE_SOURCE_DIR}/scripts/verify_sonku_p94_acoustic_levels.py"
"$<TARGET_FILE:ARMixSonKuP94ReferenceTests>"
"$<TARGET_FILE:ARMixSonKuP94SourceTests>")
endif()
juce_add_console_app(ARMixSonKuP90NativeTests
PRODUCT_NAME "ArSonMix SonKu P90 JUCE v11 State Tests")
target_sources(ARMixSonKuP90NativeTests PRIVATE
Expand Down
43 changes: 43 additions & 0 deletions docs/SONKU_P94_FRONT_REAR_EXTERNALIZATION_FAT_20261116.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
# SonKu P9.4 — Front/Rear Externalization A/B (2026-11-16)

**STATUS: PRIVATE HEADPHONE FAT CANDIDATE / DRAFT, NOT ACOUSTICALLY VERIFIED.**

## Baselines / preservation
- Production main: `37985f02caecd93b22f853183888d81e18dc6736`.
- Operator-confirmed P9.1/P9.2: `763706a15a2617a10d23b5e2e43eb5689e454ccb`, frozen at `checkpoint/sonku-p91-p92-operator-confirmed-20261116`, issue #720.
- P9.3 GUI: draft PR #721; original perspective **ellipse** (148×83 SVG) is the APPROVED 3D oblique view of a circular 360° audio orbit. It is not the fault. Its movable modeless window, accepted FX Power, preset scenes and SPACE layout are inherited without changes.
- P9.4 starts from PR #721 head and adds *only* an explicitly opt-in spatial-depth experiment to the actual P9 native renderer. No upstream PR/main/checkpoint source is changed.

## What the listener actually reported
At equal physical source radius and continuous 360° orbit, front (0°) and rear (180°) are perceived too close to the listener while ±90° lateral positions feel farther away. A person perceives a *flattened acoustic orbit*, **not a faulty UI ellipse**.

The P9.1 renderer already uses a world-anchored two-speaker KEMAR 2×2 measured-HRIR field and LF foundation. It centres correlated stereo content at the actual median-plane HRIR. With a non-individualized HRTF, front/back spectral cues and distance externalization can be weak despite geometrically correct source angles. Older P9 direct/ER/tail levels have no head-relative angular externalization compensation. This is a perceptual limitation to investigate, not proof the DSP position calculation is elliptical.

## P9.4 A/B hypothesis and code contract
Research in binaural externalization relates localization to HRTF pinna fine structure, listener/head rotation, individualized headphone calibration, binaural reflections and direct-to-reverberant ratio (DRR); increasing diffuse reverb alone is not proven to fix it. A published 2026 frontal-source study also discusses direct and reflection level adjustment in generic BRIRs. Such research motivates a **bounded test**, not any claim of dearVR parity.

`SonKuP94FrontBackDepthCue.h` is a fixed-size, 45ms-slewed median-plane angular weighting computed on the existing 16-sample HRTF retarget cadence. It uses a 361-entry table prepared once, no allocation, locks, timers, FFT, or trigonometry in the per-sample audio callback.

- Head-relative centre azimuth: `p83::toHead(worldCenter, yaw)`. Never use SVG pixel coordinates or pretend the speaker moved closer.
- Weight: `cos^4(theta)`: 1 at 0° and 180°, 0 at ±90°; smooth and periodic at the wrap.
- For P9 only and if room + early reflection wet are ON: multiply the **already measured HRTF direct pressure** by `1-0.045*w` (max −0.40 dB), and its **directional early reflections** by `1+0.28*w` (max +2.14 dB). Late reverb, bass room modes, KEMAR spectral coefficients, ITD, ILD, source distance, orbit phase, output gain and stereo MID/SIDE graph are unchanged. The front/rear direct/early pressure-ratio proxy changes by at most about −2.54 dB. The ROOM OFF / ER=0 return is exactly neutral. This is **not** a measured personalized BRIR, not a cabinet resonance model and not a substitute for head tracking.
- The feature is compiled only with `-DARMIX_SONKU_EXPERIMENTAL_P94_FRONT_BACK_DEPTH=ON` and P9 already enabled. Default builds OFF, compile-time guard rejects P9.4 without P9.
- No state schema/ABI change: `renderMode=9` remains authoritative, but native readback `p94FrontBackDepthCue=true` specifically identifies this experimental build. UI label `P9.4 · FRONT/REAR DEPTH (A/B)` appears only for that genuine capability. P9.1-only builds still say P9.1+P9.2.

## Automated acceptance & safety boundaries
- Test real source PCM at 44.1/48 kHz, static 0/90/180/270 with ROOM ON/OFF, mono-like stereo and strict anti-phase, 64 vs 256-frame bit-parity, finite output + existing 0.98 linked peak guard.
- Isolate the curve itself: equal front/rear gains, lateral exactly neutral once smoothed, bounded ratio correction, head-yaw turns world FRONT into head SIDE, wrap continuity. Re-run existing P9.1/P9.2 PCM, P9.0 coherence, P8.9, GUI dropdown and Chromium tests.
- Exact source build of Windows native mixer + CTest and portable artifact must PASS before operator FAT. Keep draft, do not merge to main.

## Mandatory headphone FAT / rejection conditions
- Compare ***original checkpoint P9.1+P9.2***, PR #721 GUI-only and P9.4 at matching integrated loudness (±0.5 LU) on the SAME device/headphones. Play actual music: kick, bass guitar, low-level room content, vocals, percussive transients, and 30–180Hz anti-phase material.
- Orbit static stepped 0, ±45, ±90, ±135, 180; then continuous slow 6–12s with head yaw 0/90/180 and fixed 1.6/3.1m source distance. Record perceived distance (front/right/back/left), front-back reversals, tonal degradation, and whether room returns become echoes/boom.
- Inspect measured signal energy and short-time binaural interaural coherence per direction, direct/ER cross-correlation, potential transient smearing, limiter gain reduction, and true loudness against raw music.
- **Reject P9.4** if user perceives no appreciable improvement, music becomes more reverberant/distant but not externalized, integrated level moves >0.5 LU without intentional user gain, or bass/treble/phase and ASIO stability regress. Retain accepted checkpoint. Real HRTF personalization/head tracking/BRIR options remain future work.

## References / cautions
- Sound Externalization: A Review of Recent Research. https://pmc.ncbi.nlm.nih.gov/articles/PMC7488874/
- Auditory localization: a comprehensive practical review. https://pmc.ncbi.nlm.nih.gov/articles/PMC11267622/
- Enhancing Externalization of Frontal Virtual Sound Sources in Binaural Synthesis via Level and Reflection Adjustment of Non-individualized BRIRs (2026). https://doi.org/10.1177/23312165261468752

No claims that these articles establish the optimal numeric .045/.28 values: those are **research calibration candidates** requiring controlled audio comparison.
63 changes: 63 additions & 0 deletions engine/builtin_fx/sonku/SonKuP94FrontBackDepthCue.h
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
// SPDX-License-Identifier: AGPL-3.0-only
#pragma once
#include <algorithm>
#include <array>
#include <cmath>
#include <cstddef>

// P9.4 private acoustic A/B (NOT a measured BRIR / dearVR clone).
// A front/rear source can collapse inside the head with non-individual KEMAR.
// At CONSTANT physical radius, adjust only the direct/first-reflection
// energy balance near the interaural median plane; measured HRIR spectra,
// ITD/ILD, speaker azimuth, low-frequency world transfer and tail stay intact.
// Must be validated by loudness-matched headphone FAT before release.
namespace armix::sonku::p94 {
class FrontBackDepthCue final {
public:
struct Gains {float direct=1.f,early=1.f;};
bool prepare(double sampleRate) noexcept {
if(!std::isfinite(sampleRate) ||
(std::abs(sampleRate-44100.)>.1 && std::abs(sampleRate-48000.)>.1))
return false;
constexpr double pi=3.1415926535897932384626433832795;
slew_=static_cast<float>(1.-std::exp(-1./(sampleRate*.045)));
for(std::size_t i=0;i<shape_.size();++i){
const double c=std::cos(double(i)*pi/180.);
shape_[i]=static_cast<float>((c*c)*(c*c));
}
reset();
return true;
}
void reset() noexcept {target_=0.f;weight_=0.f;enabled_=false;}
// Called at the existing every-16-sample HRTF retarget. Angle MUST be
// center WORLD azimuth - head yaw, never the ellipse's 2D SVG position.
void retarget(float headRelativeAzimuth,bool roomWithEarly) noexcept {
enabled_=roomWithEarly;
if(!enabled_ || !std::isfinite(headRelativeAzimuth)){
target_=0.f;return;
}
// p83::toHead returns [-180,180], bounded wrap avoids RT fmod/cos.
float d=std::clamp(headRelativeAzimuth,-360.f,360.f);
if(d<0.f)d+=360.f;
if(d>=360.f)d-=360.f;
const int lo=std::clamp(static_cast<int>(d),0,359);
const float frac=d-lo;
target_=shape_[lo]*(1.f-frac)+shape_[lo+1]*frac;
}
Gains next() noexcept {
weight_+=slew_*(target_-weight_);
if(std::abs(weight_-target_)<1.e-6f)weight_=target_;
// Room OFF / ER zero must never perturb the golden P9 PCM.
if(!enabled_)return {};
const float w=std::clamp(weight_,0.f,1.f);
// At 0/180: direct -0.40 dB, early +2.14 dB. Ratio shifts by
// ~2.54 dB; NOT a source distance or headphone gain multiplier.
// At ±90 the output is mathematically bit-identical to P9.1/P9.2.
return {1.f-.045f*w,1.f+.28f*w};
}
private:
std::array<float,361> shape_{};
float slew_=0.f,target_=0.f,weight_=0.f;
bool enabled_=false;
};
} // namespace armix::sonku::p94
Loading
Loading