diff --git a/.github/workflows/ui-smoke.yml b/.github/workflows/ui-smoke.yml index 6c81d2313..2d3bffee8 100644 --- a/.github/workflows/ui-smoke.yml +++ b/.github/workflows/ui-smoke.yml @@ -113,6 +113,8 @@ jobs: node --check site/preview-v2/assets/mixer-native-sonku.js g++ -std=c++20 -O2 -Wall -Wextra -pedantic tests/sonku_spatial_core_test.cpp -o /tmp/armix-sonku-core-smoke /tmp/armix-sonku-core-smoke + g++ -std=c++20 -O2 -Wall -Wextra -pedantic tests/sonku_multiband_phase_test.cpp -o /tmp/armix-sonku-band-smoke + /tmp/armix-sonku-band-smoke python tests/native_peq_assembly_test.py python tests/native_v60_fader_assembly_contract.py python tests/approved_operator_ux_smoke.py @@ -198,7 +200,7 @@ jobs: needs: quick # Both 8D-SonKu and SOF native-owner PRs share ONE actual Chromium runner. # Preserve fast-only checks for unrelated GUI and engine branches. - if: ${{ (github.event_name == 'pull_request' && (startsWith(github.head_ref, 'feat/8d-sonku-') || startsWith(github.head_ref, 'feat/sonku-') || startsWith(github.head_ref, 'test/sof-native-') || startsWith(github.head_ref, 'integration/sof-sonku-main-') || startsWith(github.head_ref, 'fix/native-wire-inspector-') || (startsWith(github.head_ref, 'integration/sonku-m4-wire-') || startsWith(github.head_ref, 'integration/sonku-m4-guitar-picker-') || startsWith(github.head_ref, 'fix/sonku-')))) || (github.event_name == 'workflow_dispatch' && startsWith(github.ref, 'refs/heads/feat/8d-sonku-') && inputs.expected_sha != '') }} + if: ${{ (github.event_name == 'pull_request' && (startsWith(github.head_ref, 'feat/8d-sonku-') || (startsWith(github.head_ref, 'feat/sonku-') && !startsWith(github.head_ref, 'feat/sonku-music-integrity-')) || startsWith(github.head_ref, 'test/sof-native-') || startsWith(github.head_ref, 'integration/sof-sonku-main-') || startsWith(github.head_ref, 'fix/native-wire-inspector-') || (startsWith(github.head_ref, 'integration/sonku-m4-wire-') || startsWith(github.head_ref, 'integration/sonku-m4-guitar-picker-') || startsWith(github.head_ref, 'fix/sonku-')))) || (github.event_name == 'workflow_dispatch' && startsWith(github.ref, 'refs/heads/feat/8d-sonku-') && inputs.expected_sha != '') }} runs-on: ubuntu-latest timeout-minutes: 12 steps: @@ -276,6 +278,80 @@ jobs: if-no-files-found: ignore retention-days: 7 + sonku-music-integrity-audio: + name: SonKu music integrity native WAV/CPU (no Chromium, no Windows packaging) + needs: quick + if: ${{ github.event_name == 'pull_request' && startsWith(github.head_ref, 'feat/sonku-music-integrity-') }} + runs-on: ubuntu-latest + timeout-minutes: 9 + steps: + - uses: actions/checkout@v4 + # Public alpha.23 is immutable baseline; fetch ONLY SonKu engine + # headers for matched native C++ reference rendering (no JUCE/SDK). + - name: Checkout immutable public alpha.23 SonKu baseline headers + uses: actions/checkout@v4 + with: + ref: 4a6e47e2905a4aa995f879045a907abee8b1aae5 + path: .baseline-sonku + persist-credentials: false + sparse-checkout: | + engine/builtin_fx/sonku + sparse-checkout-cone-mode: true + - name: Render and numerically compare six native PCM music A/B tracks + run: | + g++ -std=c++20 -O2 -Wall -Wextra -pedantic tools/sonku_offline_listening.cpp -o /tmp/sonku-integrity-audio + /tmp/sonku-integrity-audio sonku-integrity-evidence --music-integrity-only + g++ -std=c++20 -O2 -Wall -Wextra -pedantic -DSONKU_AB_BASELINE tools/sonku_offline_listening.cpp -o /tmp/sonku-integrity-baseline + /tmp/sonku-integrity-baseline sonku-integrity-baseline --music-integrity-only + python tests/sonku_music_integrity_comparison.py sonku-integrity-baseline sonku-integrity-evidence + - name: P2 measured-KEMAR early reflection source regression + run: | + g++ -std=c++20 -O2 -Wall -Wextra -pedantic tests/sonku_directional_reflections_test.cpp -o /tmp/sonku-p2-er + /tmp/sonku-p2-er + - name: P3 directional zero-spread fusion PCM and spread-transition regression + run: | + g++ -std=c++20 -O2 -Wall -Wextra -pedantic tests/sonku_p3_spread_zero_fusion_test.cpp -o /tmp/sonku-p3-fusion-test + /tmp/sonku-p3-fusion-test + - name: P4 ring-wrap/source-motion full-HRIR equivalence regression + run: | + g++ -std=c++20 -O2 -Wall -Wextra -pedantic tests/sonku_p4_contiguous_reflections_test.cpp -o /tmp/sonku-p4-regression + /tmp/sonku-p4-regression + - name: P5 ROOM OFF ON fresh-history directional FIR protection + run: | + g++ -std=c++20 -O2 -Wall -Wextra -pedantic tests/sonku_p5_room_reactivation_test.cpp -o /tmp/sonku-p5-room + /tmp/sonku-p5-room + - name: P2 original voice-like headphone A/B and numeric PCM comparison + run: | + /tmp/sonku-integrity-audio sonku-integrity-evidence --directional-er-only + python tests/sonku_directional_reflections_audio_audit.py sonku-integrity-evidence + - name: P3 exact-source FRONT/REAR native P2/P3 PCM A/B + run: | + /tmp/sonku-integrity-audio sonku-integrity-evidence --p3-fusion-only + python tests/sonku_p3_fusion_audio_audit.py sonku-integrity-evidence + - name: P4 original independent stereo 60/120 FRONT/REAR PCM identity + run: | + /tmp/sonku-integrity-audio sonku-integrity-evidence --p4-contiguous-only + python tests/sonku_p4_contiguous_audio_audit.py sonku-integrity-evidence + - name: Broad KEMAR frequency-response integrity audit (44.1k/48k) + run: | + g++ -std=c++20 -O2 -Wall -Wextra -pedantic tests/sonku_hrir_spectral_audit.cpp -o /tmp/sonku-hrir-audit + /tmp/sonku-hrir-audit > sonku-integrity-evidence/KEMAR-SPECTRAL-AUDIT.csv + test "$(($(wc -l < sonku-integrity-evidence/KEMAR-SPECTRAL-AUDIT.csv)-1))" -eq 380 + - name: Same-runner informational SonKu native realtime CPU check + run: | + g++ -std=c++20 -O2 -Wall -Wextra -pedantic tools/sonku_rt_benchmark.cpp -o /tmp/sonku-integrity-cpu + /tmp/sonku-integrity-cpu + - name: Upload original lossless music-integrity proof + if: ${{ always() }} + uses: actions/upload-artifact@v4 + with: + name: ArSonMix-SonKu-Phase-Integrity-${{ github.run_id }} + path: | + sonku-integrity-evidence/* + sonku-integrity-baseline/* + if-no-files-found: ignore + retention-days: 14 + vocal-throw-preview: name: Vocal Delay native editor desktop/mobile Chromium FAT needs: quick diff --git a/docs/SONKU_ADR_P1_1_MULTIBAND_PHASE_INTEGRITY_20261114.md b/docs/SONKU_ADR_P1_1_MULTIBAND_PHASE_INTEGRITY_20261114.md new file mode 100644 index 000000000..9a8cec703 --- /dev/null +++ b/docs/SONKU_ADR_P1_1_MULTIBAND_PHASE_INTEGRITY_20261114.md @@ -0,0 +1,78 @@ +# SonKu ADR P1.1 — mixed-polarity frequency-local integrity + +2026-11-14 · experimental draft PR #674 · no public release. + +## Source-proven failure and decision +The single JUCE native PCM `SonKuSpatialCore` maps L/R into two +measured KEMAR HRIR sources, summed at each ear. At zero source +spread, L=-R in *any frequency band* cancels in both ears. The +existing P0 full-band correlation guard recovers only globally +anti-correlated input. A stronger centered 170/220Hz bass can +hide an inverted 3200Hz instrument, leaving global correlation +positive and the high-frequency signal destructively lost. + +Inside the **existing** callback-owned `SonKuStereoIntegrity`, +split each input with prepared 260Hz and 2600Hz one-pole filters: +`low=LP260(x)`, `mid=LP2600(x)-LP260(x)`, +`high=x-LP2600(x)`. These three bands sum to the original +input sample for sample (no linear-phase FIR, lookahead or new +graph). Each has its own 20ms correlation evidence, -0.78/-0.55 +hysteresis and 15ms de-click blend. Preserve only locally +inverted stereo difference; the existing broadband gate remains +authoritative when full-band L=-R, to avoid double rescue. +The P0 positive coherent MID HRIR correction remains unchanged. + +## ABI/performance/risk +Only small fixed POD state and per-sample add/multiply operations. +No allocations, locks, file I/O, network, runtime coefficient +design, FFT, extra convolution or GUIs. The original source +side-bed bound of 0.65×mix×trim, `.smix` v1/v2, +native ACK/readback, routing, FX identity and JUCE graph remain. + +A post-HRTF stereo side bed is partly **head-locked**, not +physically externalized. Band crossover changes can affect +timbre/image stability. A passed unit test is only proof of +synthetic signal preservation, NOT externalization or dearVR +equivalence. Reject the experiment if subjective A/B shows +unacceptable artifacts. Subsequent milestones require directional +BRIR, personalizable licensed HRTF, distance DRR and real ASIO +CPU/headphone evidence. + +## References +- Official dearVR PRO 2 manual (documented room/distance/Clarity + product behaviors, not proprietary code/coefficients): + https://files.plugin-alliance.com/products/dearvr-pro-2/dearvr-pro-2_manual.pdf +- Sennheiser official timbre-vs-localization discussion: + https://help.sennheiser.com/hc/en-us/articles/27424692616594-How-to-produce-natural-immersive-music-with-the-CLARITY-modul-of-dearVR-PRO2 +- SOFA/AES69 (future data format): https://www.sofacoustics.org/ +- 2026 BRIR/early reflection externalization evidence: + https://pmc.ncbi.nlm.nih.gov/articles/PMC13451706/ +- ITU-R BS.1116-3 listening method: + https://www.itu.int/rec/R-REC-BS.1116-3-201502-I/en + +SonKu's frequency-band decision is original experimental +filter/correlation algebra, not a claim about dearVR internals. + +## Verified first-pass GitHub Actions evidence + +Following exact digital-silence repair, [Actions #43524526143](https://github.com/masarray/arsonmix/actions/runs/43524526143) +passes native 44.1/48k source regression, six identical-input baseline/candidate +WAV pairs, 380 KEMAR spectral checks and runner-local CPU benchmark. +The sixth 3200Hz note recovered above an objective amplitude gate of +0.006 while the coherent 220Hz bass changed by less than 0.25dB. +This is a machine test threshold, not a perceptual listening rating. +The run's artifact is [#14083314097](https://github.com/masarray/arsonmix/actions/runs/43524526143/artifacts/14083314097). + +## Informational block callback distribution (same native core) + +The scoped `tools/sonku_rt_benchmark.cpp` collects external +`steady_clock` timing around each exact DSP `process` call, sorts +per-callback timings and reports p50/p95/p99 in microseconds on +64/128/256/512-frame blocks at 44.1/48kHz, for HRTF-only, early-room +and late-room modes. Also reports p99 divided by the theoretical +buffer duration. All benchmark allocations are **outside** the DSP +callback; no new runtime telemetry or DSP branch is added. +Hosted CI percentiles are informational and may include scheduler +jitter; there is deliberately no unstable hard CPU pass threshold. +Real Windows ASIO field p99, XRUN count and source+FX+WIRE integration +remain release blockers. diff --git a/docs/SONKU_ADR_P2_DIRECTIONAL_REFLECTIONS_20261114.md b/docs/SONKU_ADR_P2_DIRECTIONAL_REFLECTIONS_20261114.md new file mode 100644 index 000000000..00bfe4999 --- /dev/null +++ b/docs/SONKU_ADR_P2_DIRECTIONAL_REFLECTIONS_20261114.md @@ -0,0 +1,102 @@ +# SonKu ADR P2 — Directional measured-HRIR image-source reflections +2026-11-14 · experimental on draft PR #674 · NOT public/released + +## Verified source-level gap +Existing SonKuEarlyReflections uses measured wall image-source paths +but ear output is a delayed filtered mono sample with synthetic +0.31ms maximum ITD and 13% ILD proxy. It omits the pinna/FRONT-REAR +spectral signatures of each reflected arrival. The existing KEMAR +bank provides actual 0° elevation measured horizontal HRTF. + +## Independent design +Retain exact current realtime default. Add OFFLINE-only +setDirectionalEarlyReflectionsHrir(true) forwarded to the original +room instance (not a parallel audio graph). Active changes are rejected. +For each of 2 stereo source emitters x 4 first-order image paths, +compute image-source arrival azimuth atan2(x,y) every 64 samples. +Use horizontal KEMAR 5° HRIR interpolation with ear mirroring and +existing wall/distance pressure law; apply one COMMON path delay +and measured left/right KEMAR 140-tap FIRs. The measured HRIR +already includes ITD/ILD: no additional fake ear delay/gain. +Smooth moving filter targets over 8ms, existing delay/gain slew +remains; fixed state and history, no allocation, I/O or locks in +callback. Baseline renderer path stays structurally unchanged. +No new GUI, .smix, VST3 catalog, routing or JUCE ACK protocol. + +## Scientific and commercial provenance +dearVR PRO 2 *official user manual*, §§2.1 and 3.2: +https://files.plugin-alliance.com/products/dearvr-pro-2/dearvr-pro-2_manual.pdf +describes first reflections and 6 surfaces; this is NOT a claim +about unpublished dearVR DSP. Steam Audio documentation: +https://partner.steamgames.com/doc/features/steam_audio +describes directional HRTF and reflected geometry, and associated +CPU costs. Meta spatial audio guide: +https://developers.meta.com/vr/design/spatial_audio/ +explains spectral pinna cues in FRONT/REAR. SOFA/AES69: +https://www.sofacoustics.org/ for future multi-elevation BRIR +profile interchange. Existing SonKu KEMAR license remains under +docs/THIRD_PARTY_8D_SONKU_HRTF.md. No proprietary assets copied. + +## Limitations and gates +This is a physically grounded HORIZONTAL early reflection pilot, +not full externalization, not 3D BRIR, not elevation or head tracking. +Four reflected 140-tap filters x two source emitters are expensive. +Do not publish the mode until CPU p99 on ASIO hardware, headphone +blinded same-gain A/B, front/rear clarity, timbre and DRR tests. +CI covers 44.1/48k causal delay, measured ear mirror, finite output, +legacy-default, rejection of active switching, off-silence, and +existing full source PCM/music integrity tests. Do not claim dearVR +quality merely from a synthetic regression or static source IR. + +## P2 objective and CPU evidence additions +The same native offline renderer emits four 2s 48k/16bit WAVs: +FRONT/REAR x legacy light vs measured image-HRIR early reflections, +all on the identical original harmonic test input and exact direct +KEMAR. The Python evidence writer verifies direct PCM is byte-equal +before reflections, output finite/in-range, reflection difference +nonzero, and records directional-vs-light ear RMS and sample peaks. +These are **objective DSP differences**, not proof of perceived distance, +color or externalization. The informational runner benchmark compares +48k/128 3-second native wall-clock and callback p99 using the same +source and block size for light vs full measured reflections. + +## P2 CPU qualification and rejected optimization (2026-11-14) + +The measured HRIR P2 mode PASSED actual native C++/WAV gates on +[Action #43528783968](https://github.com/masarray/arsonmix/actions/runs/43528783968). +At 48kHz / 128 frames, the same runner 3s CPU test was: +light ER 49.992ms, directional HRIR ER 231.677ms, +ratio 4.634; directional callback p99 228.678us. +These values are for isolated Linux runner, not live ASIO. + +A mirrored 2× delay-ring optimization was tested separately on +[Action #43529139184](https://github.com/masarray/arsonmix/actions/runs/43529139184): +light 49.992ms, directional 230.648ms, ratio 4.614, +p99 223.867us. The observed ~0.4% whole-window change is much +smaller than typical hosted-runner variability and costs an additional +64KiB per processor; **reject and revert** this optimization. +It does not pass an honest data-backed speed-quality tradeoff gate. + +The independent test now additionally exercises moving orbit PCM +partition parity with coherent bass and reversed treble, and real +near/far wall geometry arrival-time ordering. Only testable quality +improvements are acceptable; no artificial CPU numbers or claim of +dearVR equivalence. + +P2 measured per-ear reflection FIR remains intentionally offline. +A practical production renderer requires **substantially cheaper** +directional processing (such as carefully profiled SIMD/block +convolution) or a measured quality/performance policy, followed by +headphone and Windows ASIO evidence. This cannot be decided from CI +alone. + +## P2 music timbre audit (candidate evidence, no perception claim) +For each of the four 48k original A/B WAVs, offline analysis +now demodulates exact 165/660/2200/4700Hz synthetic test harmonics +over a one-second steady interval, comparing light and directional +magnitude response by ear in dB. It reports RMS delta, sample peak +and a 1.5dB *engineering review flag* (NOT a scientifically validated +audibility threshold). Reflective HRTF spectral coloration is expected, +but must be assessed for musical preference and no destructive notches +with controlled blind headphones. This synthetic four-tone sample cannot +prove transparency for real multitrack music. diff --git a/docs/SONKU_ADR_P3_ZERO_SPREAD_FUSION_20261114.md b/docs/SONKU_ADR_P3_ZERO_SPREAD_FUSION_20261114.md new file mode 100644 index 000000000..644cc55be --- /dev/null +++ b/docs/SONKU_ADR_P3_ZERO_SPREAD_FUSION_20261114.md @@ -0,0 +1,73 @@ +# ADR SonKu P3 — zero-source-spread linear binaural reflection fusion + +2026-11-14 · draft PR #674 · OFFLINE research only. + +## Research and root cause +Official dearVR PRO 2 manual §2.1 documents geometric +early reflections as critical to externalization, and §3.2 ties +reflection patterns to moving source and six wall planes. +https://files.plugin-alliance.com/products/dearvr-pro-2/dearvr-pro-2_manual.pdf +Steam Audio's implementation explicitly trades CPU against +HRTF-filtered reflection quality: +https://valvesoftware.github.io/steam-audio/doc/capi/reflections-effect.html +Neither source gives permission to copy proprietary DSP or +claims our output already matches dearVR. +The P2 renderer has 2 stereo emitter x 4 walls x 2 ears x 140 tap +FIR plus live slew per sample. 2026-11-14 CI P2 measured +~4–6x light reflection CPU on hosted Linux. + +## P3 mathematically derived optimization +For exact `stereoSpreadDegrees == 0` both input emitters +travel along the identical image-source directions and acquire +identical wall path delays, gains, and 0°-elevation measured KEMAR +HRIR. Linearity gives: +`H * x_L + H * x_R = H * (x_L + x_R)`. +This holds for *arbitrary stereo*, including anti-phase material, +and does not presume L=R, add gain, or remove spectral cues. +The original stereo music-integrity side guard is upstream, +not bypassed by this optional wet-only optimization. + +On each P3 room sample update both lowpass histories as before; +convolve their delayed sum only once for each of the four +image-source reflections. Advance the skipped path's HRIR filter +and delay/gain state so a live spread edit can fall back without +stale coefficients. Any nonzero spread permanently disarms +the fusion until reset. This reduces the work for zero spread, +while full 140 taps remain intact. 60° stereo spread runs +the exact P2 convolution, with no HRTF approximation. +P3 is OPT-IN through the unpublished native core accessor; +P2/alpha.23 defaults do not change; no new GUI or .smix field. + +## Qualification gates +- Native 44.1/48k four input cases: true mono, independent stereo, + inverted stereo, coherent bass + inverted treble. Compare precise + floating wet outputs to unfused P2 on a rotating moving source, + assert RMS <3e-6, worst-case absolute <2e-5. Verify 60° spread + and return to 0 remain unfused after initial nonzero spread + until reset, with no stale-filter spikes. +- Same-runner 48k/128/3s P2-vs-P3 benchmark with *spread 0*, + plus a separate 60° control. No performance claims until CI. +- P0/P1 music baseline 6 WAV, P2 4 WAV and KEMAR 380 + spectral checks all remain required. No release/merge pending + headphone A/B and Windows ASIO live CPU gates. + +## Known limits +Optimization works only for EXACT zero source spread; it +does NOT reduce CPU on moving 60°/180° source-separated stereo. +No six-surface geometry, multi-elevation measured HRTF, headphone +individualization, head-tracking or true BRIR is claimed. + +## Native same-runner performance observation +GitHub Actions #43533510068, 48kHz/128 samples/3s: +P2 spread 0 CPU **263.289ms**; P3 spread 0 **178.636ms** +(1.474x faster), p99 **250.590us -> 176.808us**. +P3 with spread 60 explicitly does not fuse (248.051ms). +These numbers are NOT full Windows ASIO/graph deadlines. + +## Additional audio gate +Render four original-source 2s PCM WAVs: P2 reference and P3 +fused, FRONT and REAR. Same exact 140-tap horizontal KEMAR, +room geometry, direct HRTF, 48kHz and 16-bit conversion. +Require <=2 peak PCM LSB, <2e-5 RMS, <0.05dB on +165/660/2200/4700Hz in both ears. This evaluates +sound quality invariance, not externalization superiority. diff --git a/docs/SONKU_ADR_P4_CONTIGUOUS_HRIR_REFLECTIONS_20261114.md b/docs/SONKU_ADR_P4_CONTIGUOUS_HRIR_REFLECTIONS_20261114.md new file mode 100644 index 000000000..a203599ed --- /dev/null +++ b/docs/SONKU_ADR_P4_CONTIGUOUS_HRIR_REFLECTIONS_20261114.md @@ -0,0 +1,79 @@ +# SonKu P4 experiment — contiguous 140-tap reflection HRIR without extra ring +2026-11-14 · draft PR #674 · offline only; native 44.1/48k source PCM PASS; hosted CPU measurement provisional + +## Context and research +The [dearVR PRO 2 official manual](https://files.plugin-alliance.com/products/dearvr-pro-2/dearvr-pro-2_manual.pdf) +§§2.1 and 3.2 describes geometric early reflections as +important to perceptual externalization, responsive to source +motion, distance and six surfaces. It does not disclose +proprietary rendering code or guarantee equivalence. +[Steam Audio reflection effect](https://valvesoftware.github.io/steam-audio/doc/capi/reflections-effect.html) +documented CPU-versus-quality alternatives include HRTF filtering, +multi-channel convolution and hybrids. + +## Exact algorithm +Current P2 full 140-tap horizontal KEMAR reflected FIR computes +two ring-wrap masks per input tap and per reflection per sample. +The index `idx=(write-integerDelay)&8191` refers to the newest +valid delayed sample, and FIR reads indices `idx-k` and +`idx-k-1` for k=0..139. When idx>=140, ALL reads are within +the same 8192-float history span (8052 positions, ~98.3% +of ring phase). Optional P4 path uses the identical interpolated +input expression but plain `float*[-k]` addresses, reducing per-tap +mask/index arithmetic. When idx<140, use the previous masked +reference. No doubled ring memory or vector backend, no FIR +truncation, downsampling, delayed coefficient update, or tap loss. +P3 zero-spread fusion and both ear HRIR coefficient smoothing remain +exactly the same, including spread transitions. + +Access is set only on an OFFLINE inactive core: +`setDirectionalEarlyReflectionsHrir(true)` then +`setDirectionalContiguousHrir(true)`. Default stays false; +no GUI, .smix schema, JUCE graph, WIRE, FX ACK or public release +changes. No extra audio thread, malloc, I/O or locking. + +## Acceptance / rejection +Must pass 44.1/48k C++ compare to full source P2 for 0/60/120° +stereo spread, coherent, frequency-conflicted independent stereo and +independent impulse streams, rotating azimuth and 3 wrap periods. +Exact per sample absolute error <2e-6, and room OFF strict +release. P0/P1 baseline six WAV, P2 front/rear A/B and KEMAR +380-point spectral remain as release gates. +Bench on same GitHub runner and 48k/128 60° spread native +full-core CPU p99. **Reject** and revert opt-in P4 if no convincing +improvement relative to runner variance, as with previously +rejected doubled-ring technique (~0.4%). +No claims of improved front/rear externalization from a CPU edit. + +## Native result: 2026-11-14, exact commit 77d1fc9 + +GitHub Actions [#43536803506](https://github.com/masarray/arsonmix/actions/runs/43536803506): +P4 44.1/48k, 0/60/120° 140-tap PCM, three ring wraps, +moving azimuth, independent/correlated/transient audio PASS. +P0/P1 six 4s baseline A/B PASS, P2 and P3 native regressions +PASS, and KEMAR 380-point spectral audit PASS. +For **48k/128/3s, spread 60°**, same-runner isolated core: +P2 723.042ms vs P4 437.188ms = **1.654×** speedup, +p99 666.749us vs 470.390us. Spread 0/120° and 44.1k +showed ratios 1.615–1.657×. Absolute values vary +substantially across shared Linux CI hosts. Not ASIO proof. +Unlike the rejected doubled-ring earlier, this method +needs no additional delay history. + +## Additional independent stereo WAV qualification +Four 2s 48k/16bit original synthetic independent-stereo +FRONT/REAR x 60°/120° P2 full and P4 contiguous pairs. +A Python gate checks <=1 signed PCM 16bit LSB maximum +sample difference, <2% differing samples, <1e-5 normalized +RMS difference, <0.01 dB each 165/940/2200/4700/5100Hz +harmonic on both ears. It also reports exact byte identity +and sample-difference fraction. One-bit quantization +boundaries are NOT evidence of changed perceptual quality. +The initially strict byte-equality gate failed: a one-LSB +quantization difference must be measured, not mislabeled +as a proven invariant. The C++ wet-only full-float +source test still uses <2e-6 per-sample absolute error. +All existing PCM, spectral, motion, ring and CPU checks remain. +There is no claim of perceptual improvement from a bit-exact +optimization; its benefit is rendering identical directional +early reflections with lower callback CPU cost. diff --git a/docs/SONKU_ADR_P5_REFLECTION_REACTIVATION_20261114.md b/docs/SONKU_ADR_P5_REFLECTION_REACTIVATION_20261114.md new file mode 100644 index 000000000..8ce19de87 --- /dev/null +++ b/docs/SONKU_ADR_P5_REFLECTION_REACTIVATION_20261114.md @@ -0,0 +1,45 @@ +# SonKu P5 — directional ROOM reactivation uses only fresh history +2026-11-14 · draft PR #674 · experimental native room only + +## Verified source-level risk +SonKuEarlyReflections::setRealtimeRoom resets `validFrames_` +when a previously inactive ROOM is turned ON. The previous +lightweight `delayed()` code respects `validFrames_`, +but the new P2/P4 measured-HRIR 140-tap convolution read +directly from `history_`, whose ring entries contain samples +from the previous listening epoch. In a quick OFF/ON cycle, +old audio could become false *new* directional reflections. +Blindly clearing two 8192-float delay rings during control +updates on the audio thread would create a potentially blocking +64KiB memory-write burst and harm realtime performance. + +## RT-safe solution +When `realtimeMode_` is enabled, compute the count of valid +reflected FIR taps from this activation: +`freshTaps = clamp(validFrames - integerDelay, 0, 140)`. +Each reflection FIR tap requires the two adjacent fractional +delay samples; therefore if k>=freshTaps its input is zero, +and cannot read stale ring values. Continue to slew both +KEMAR ear kernels for all taps during warmup so source +movement and smoother state are maintained. Once history +has filled the delayed 140-tap window, the full exact 140 +tap processing remains unchanged. No heap, extra state +arrays, locks, I/O, secondary device or ring clear. + +The previous approved light renderer, and offline P2/P3/P4 +exact-native fixtures with `realtimeMode_ == false`, remain +unchanged; no native GUI, FX identity, .smix schema, ACK, +source routing or hardware release change. + +## CI acceptance +44.1/48k, four 7.2m first-wall configurations: +feed independent 440/720Hz stereo while room on, then keep +feeding 520/1250Hz while ROOM fades to OFF so the old ring +definitely contains audio. Re-enable ROOM on silence: every +sample must be exactly zero. New source impulse afterwards +must produce nonzero causal reflections; the warmup may +not permanently mute the processor. Repeat for source +spread 0/60/120 and P2 full vs P4 contiguous. +Existing full P0/P1, P2/P3/P4 native/spectral/CPU checks +must continue to pass. P5 does not establish subjective +externalization, nor is it an ASIO hardware test. diff --git a/docs/SONKU_DEARVR_QUALITY_GAP_AND_MUSIC_INTEGRITY_20261113.md b/docs/SONKU_DEARVR_QUALITY_GAP_AND_MUSIC_INTEGRITY_20261113.md new file mode 100644 index 000000000..aa61ab72e --- /dev/null +++ b/docs/SONKU_DEARVR_QUALITY_GAP_AND_MUSIC_INTEGRITY_20261113.md @@ -0,0 +1,82 @@ +# 8D-SonKu → externalized, music-faithful binaural audio +2026-11-13 · Engineering audit + P0 music integrity implementation · EXPERIMENTAL (not a public release) + +## Objective and provenance + +Owner reports **dearVR externalizes music convincingly, with depth and tonality preserved**, while SonKu sounds near/in-head and loses parts of the stereo music. This is subjective field evidence; the two renders have not yet been loudness matched or evaluated with the same stems, headphones and HRTF personalization. + +**DO NOT copy proprietary dearVR CORE/AMBEO Clarity code, coefficients, internal IR/BRIR, or product UI.** Refer to published techniques and build SonKu's own real-time algorithm. Sennheiser describes patented AMBEO Clarity as a tradeoff between HRTF timbre coloration and localization/externalization. This repository contains original C++ and licensed MIT KEMAR measurements, not dearVR files. + +Primary published references: +- Official dearVR PRO 2 manual (January 2024), Position, Reflections, Reverb and Master/Clarity sections: https://files.plugin-alliance.com/products/dearvr-pro-2/dearvr-pro-2_manual.pdf +- Sennheiser engineering article (2025), Clarity and musical timbre preservation: https://help.sennheiser.com/hc/en-us/articles/27424692616594-How-to-produce-natural-immersive-music-with-the-CLARITY-modul-of-dearVR-PRO2 +- Sennheiser PRO 2 release, stereo width, controllable distance and separate early/late acoustic filters: https://newsroom.sennheiser.com/dear-reality-releases-dearvr-pro-2-spatializer-plugin-xhdtie +- 2024 review, reverberation, listener movement and individualized HRTFs for externalization: https://www.frontiersin.org/journals/psychology/articles/10.3389/fpsyg.2024.1408073/full +- AES Convention 157 (2024), timbral vs spatial fidelity in different headphone renderers: https://aes.org/publications/elibrary/elibrary-page/?id=22754 +- MIT KEMAR HRIR provenance: docs/THIRD_PARTY_8D_SONKU_HRTF.md + +## Actual code-level gap in v0.5.0-alpha.23 + +The **single authoritative JUCE PCM graph** calls `SonKuSpatialProcessor::processBlock` → `SonKuSpatialCore::process`. The renderer uses **two** directional measured KEMAR HRIR FIR sources and, for each ear, sums +`y = 0.5 * gain * (H0 * inputL + H1 * inputR)`. +With `stereoSpreadDegrees=0`, `H0 == H1`; for `inputR = -inputL`, the direct field cancels **exactly**. Room's diffuse return, if enabled, cannot restore an already missing dry stereo side. At nonzero spread, low-frequency HRIR similarity can still produce partial cancellation. This is an actual deterministic DSP failure, independent of PNG, WebView2 and virtual orbit cosmetics. + +Additional limitations: horizontal-only non-individualized 0° elevation KEMAR; 2D first-order four-wall ER with light ITD/ILD proxy instead of true directional BRIR; synthetic eight-line late room; basic monitor gain/bass compensation. There is no headphone-specific equalization, individual ear selection, head tracker or frequency-dependent HRTF clarity control. Avoid marketing these as implemented or claiming parity. + +## P0 implemented in PR (candidate only): coherence-aware Mid/Side binaural rendering + +### Two independent, objective cancellation mechanisms + +**Anti-phase source null:** with `stereoSpread=0`, H0=H1 and `L=-R` removes direct HRTF pressure at both ears entirely. A protective phase-aware side bed is introduced after the FIR output, with bounded energy and callback-owned history. + +**Coherent stereo comb:** music `L=R` spread across two virtual emitter directions also causes comb filtering of a shared melodic object. Exact KEMAR 48 kHz HRIR frequency-response audit with `stereoSpread=60°` demonstrates that the legacy two-source coherent sum is **7.2 dB lower at 2 kHz FRONT** and **11.6 dB lower at 2 kHz REAR** than ONE center-direction HRTF (left ear), in the measured HRTF bank. This is an offline **transfer-function comparison**, not a listening or loudness measurement. Below ~250Hz other opposite-phase sources remain similarly vulnerable. + +For strongly positively correlated stereo, the source-mid spectral transfer is steered to the KEMAR center azimuth using **coefficient-level algebra**, not a third FIR: +``` +H_L' = H_L + mu * (H_center - 0.5*(H_L + H_R)) +H_R' = H_R + mu * (H_center - 0.5*(H_L + H_R)) +``` +Consequently `H_L' - H_R' == H_L - H_R` at every tap: the encoded stereo-side difference transfer is unchanged by this step, while coherent mid tends to one measured central head-related transfer. `mu` is positive-correlation evidence with .80/.55 hysteresis and 15ms envelope. HRIR updates use the original 16-frame cadence and 6ms coefficient slews; the native PCM callback still executes **the original four 140-tap FIRs**, not six. + +The negative-correlation rescue is separate, not an HRTF surrogate for a physically located object. It must be auditioned for a potentially head-locked secondary stereo image. This is our own original algorithm, not the vendor Clarity implementation. + +- `SonKuStereoIntegrity` owns fixed per-processor correlation state; 20ms cross/energy detector, -0.78 engage / -0.55 disengage hysteresis, 15ms gain smoothing, silence release and bounded finite evidence. No allocation, extra render thread, FFT, new device callback, WIRE or routing authority; no added reported sample latency. +- Preserve the source side difference `0.5 * (L-R)` **after** the binaural FIR summation, independently and symmetrically in the two output ears; never fold that side signal to mono. Bounded .65 × native mix × gain and only strong negative phase correlation. This is a protective **side-bed**; it is not itself an externalized HRTF image, and will not necessarily survive a mono L+R fold-down (nor does a native anti-phase stereo recording). +- Ordinary coherent L=R center at **0° SPREAD** remains numerically and byte-for-byte equivalent to the prior KEMAR impulse; coherent L=R with **nonzero SPREAD** intentionally changes the wavefront to eliminate comb filtering; `spatialMix=0` is unchanged. Native ROOM OFF, early-reflection/distance A/B and native ROOM ON share the same guard. No plugin/preset identity, SONK v1/v2 state, session ABI, transport, FX bypass or UI changes. +- Exact-source C++ test at 44.1/48 kHz covers L=R impulse equality to published KEMAR taps; anti-phase stereo FRONT/RIGHT/REAR/LEFT minimum ear RMS, bounded peak, sample partition parity; normal positive stereo no-op, silent release, reset and dry mix identity. +- Fast A/B renderer writes **five** 4s matched level/time original generated tone stems: coherent FRONT/0° spread, anti-phase FRONT/0°, anti-phase REAR/0°, and coherent FRONT/60° and REAR/60°. A pinned baseline from public alpha.23 is compiled beside the candidate (same tools, same source signal), and the test compares exact coherent CENTER PCM, anti-phase RMS and calibrated 2 kHz sine amplitude. One JSON metric report and 10 WAV files (five each) are uploaded. **Headphones only.** No normalization, copyright problem or unlicensed dearVR recordings. +- The audio developer must not merge to main solely on these mathematical tests. Human listening can reveal audible color, internalized side bed or changes to stereo image; listen to real music. + +## Exact baseline-vs-candidate evidence (same-source, same-runner) + +**Source base:** approved `main` release ancestor `4a6e47e2905a4aa995f879045a907abee8b1aae5` (public Windows alpha.23 DSP). **Candidate:** this draft PR. The lightweight GitHub Action checks out baseline header sources at the immutable SHA, compiles the *same* offline renderer twice (baseline and candidate), writes 5×4 s unnormalized 48kHz/16-bit stereo WAV per engine and validates both PCM sets with `tests/sonku_music_integrity_comparison.py`. No cross-device/OS capture differences are involved. + +The measured native output in [Action #43446354590](https://github.com/masarray/arsonmix/actions/runs/43446354590) (before documentation-only change): + +| Test | Candidate versus baseline | Interpretation | +| --- | --- | --- | +| Coherent stereo FRONT, 60° spread, 2kHz per ear | **+7.19 dB** | Comb notch reduced at this measured frequency | +| Coherent stereo REAR, 60° spread, 2kHz per ear | **+11.64 dB** | More severe original rear comb notch reduced | +| Inverted stereo FRONT, 0° spread | RMS L/R = **0.04922 / 0.04922** | Both ears recovered from effectively zero baseline | +| Inverted stereo REAR, 0° spread | RMS L/R = **0.04922 / 0.04922** | Both ears recovered from effectively zero baseline | +| Coherent FRONT, 0° spread | **Byte-exact PCM match** | Previously approved centralized direct HRIR retained | + +- C++ non-JUCE native regression at 44.1 and 48kHz passes, with cardinal direction, stereo RMS, exact original central impulse, 2kHz reference response, block partition parity, silence/positive correlation, reset and wet/dry transitions. +- Same-runner informational CPU at 48k/128 frames: measured 3s simulated DSP time **39.725 ms** HRTF-only, **43.777 ms** ER and **47.276 ms** late room. This is not Windows ASIO CPU/p99/XRUN data. Do not present it as hardware latency. +- [10 native WAV files and JSON transfer metrics](https://github.com/masarray/arsonmix/actions/runs/43446354590/artifacts/14047729710). All exact baseline and candidate samples share generated input material; do not infer naturalness, equal perceived loudness, individualized HRTF or dearVR parity from the report. + +## Next quality milestones (requires objective + listening evidence) + +1. **P1 spectral/music fidelity.** Beyond the new two coherent/antiphase protections, capture ear transfer functions FRONT/45/90/135/REAR and L/R & mid/side energy in 1/3-octave bands, compare dry stereo vs wet binaural at matched level, isolate bass loss, comb notches and late-reverb masking. Develop a *new SonKu* prepared minimum-phase spectral compensation or complementary dry/timbre-control stage, with strict frequency-band and headroom limits and a user-facing quality mode. Verify it improves music without defeating HRIR ITD/ILD. Never extrapolate from one KEMAR listener. +2. **P2 externalization and geometry.** Introduce licensed multi-elevation individualized/selectable SOFA HRIR datasets (per-data license check), reconstruct 3D directional image-source reflections including floor/ceiling; optionally measured BRIR with separate direct/ER/late paths. Control direct-to-reverberant ratio, air absorption and listener distance independently. Prepare all FFT/filter coefficients out of the audio callback. Avoid naive reverb amount as a proxy for distance. +3. **P3 motion/stability.** Evaluate optional head tracking and frequency-dependent directional interpolation; measure adaptation latency, glitch-free seek, 44.1/48k and 64/128/256 frame callback CPU p95/p99, memory, zero allocation and XRUNs in Windows ASIO (real hardware). +4. **Perceptual acceptance.** Compare the *same* licensed mono voice, recorded stereo music and anti-phase/wide stems through dearVR PRO 2 and SonKu using the same actual headphones, disabled OS spatial enhancements and loudness matched within 0.2 LUFS. Blind A/B rate front/back/externalization, distance ordering, musical tone integrity, stereo width, artifacts and listener preference. Capture reference plugin preset, sample rate, distance, stereo width, gain and room settings. A single engineer cannot prove all-listener equivalence. + +## Release gate +This PR changes the **native audio** of a user-installed FX, not just the picture. Do not mark production/dearVR-equivalent, edit README as shipped, or trigger a public Windows installer until source tests, offline A/B, performance telemetry, real Windows WebView2/ASIO/headphone listening and user approval are complete. + +## P1.0 frequency-response guard (independent analytical verification) + +The current experimental PR additionally includes `tests/sonku_hrir_spectral_audit.cpp`. Its exact licensed MIT KEMAR source-bank coefficients are transformed at 19 roughly one-third-octave centers (125–8000 Hz), five directional anchors (FRONT, 45°, RIGHT, 135°, REAR), both ears and 44.1/48 kHz: **380 deterministic frequency points**. The CSV artifact `KEMAR-SPECTRAL-AUDIT.csv` publishes the magnitude of the original two-offset-HRIR coherent MID versus the central-direction reference. It checks the implemented algebra at full correction: central-frequency response restored without altering the two-source stereo SIDE transfer. This deliberately adds no real-time FFT, convolution, gain boost, GUI slider, CPU callback allocation, or patented Dear Reality coefficients. + +This is *frequency-response source analysis*, not proof of perceptual neutrality: temporal coherence is inferred from the existing exact-core WAV/PCM comparison, and moving/partially correlated/room-on real music remains an open listening gate. If any frequency audit fails CI, the PR stays draft rather than bypassing the guard. The output CSV is available within the same scoped SonKu audio Action artifact, so future spectral compensation can be evaluated against actual baseline frequency bins instead of guessed EQ curves. diff --git a/engine/builtin_fx/sonku/SonKuEarlyReflections.h b/engine/builtin_fx/sonku/SonKuEarlyReflections.h index 92aeebf05..477af9b54 100644 --- a/engine/builtin_fx/sonku/SonKuEarlyReflections.h +++ b/engine/builtin_fx/sonku/SonKuEarlyReflections.h @@ -5,6 +5,7 @@ #include #include #include +#include "SonKuMeasuredHrir.h" // Bounded, first-order image-source room for headphone externalization trials. // Reflection image geometry follows Allen & Berkley (JASA, 1979), not @@ -34,6 +35,8 @@ class SonKuEarlyReflections final { delaySlew_=static_cast(1.-std::exp(-1./(rate*0.024))); gainSlew_=static_cast(1.-std::exp(-1./(rate*0.012))); amountSlew_=static_cast(1.-std::exp(-1./(rate*0.010))); + kernelSlew_=static_cast(1.-std::exp(-1./(rate*0.008))); + hrirBank_=(rate==44100.)?hrir::normal44100:hrir::normal48000; reset(); ready_=true; return true; @@ -44,7 +47,38 @@ class SonKuEarlyReflections final { for(auto& paths:tap_)for(auto& p:paths)p=Tap{}; write_=0;untilGeometry_=0;primed_=false;validFrames_=0; amount_=0.f; + fuseEligible_=true; } + // OFFLINE A/B ONLY: existing approved room mode remains bit-exact by + // default. Reject mode changes while active; no public state/GUI switch. + bool setDirectionalHrir(bool enabled) noexcept { + if(active())return false; + directionalHrir_=enabled; + if(!enabled){fastZeroSpread_=false;fastContiguousHrir_=false;} + fuseEligible_=true; + untilGeometry_=0;primed_=false; + return true; + } + bool directionalHrirEnabled() const noexcept{return directionalHrir_;} + // Offline-only P3 exact-linear four-wall source fusion. Valid ONLY + // while both emitters share the same direction (spread == 0). + // This changes no public settings or live graph authority. + bool setDirectionalZeroSpreadFusion(bool enabled) noexcept { + if(active() || (enabled && !directionalHrir_))return false; + fastZeroSpread_=enabled; + fuseEligible_=true; + return true; + } + bool zeroSpreadFusionEnabled() const noexcept{return fastZeroSpread_;} + // P4 experimental, inactive-only: eliminate per-tap circular masking + // when the delayed 140-tap HRIR FIR window is wholly in one ring span. + // No duplicated ring storage and no HRIR coefficient truncation. + bool setDirectionalContiguousHrir(bool enabled) noexcept { + if(active() || (enabled && !directionalHrir_))return false; + fastContiguousHrir_=enabled; + return true; + } + bool contiguousHrirEnabled() const noexcept{return fastContiguousHrir_;} // Deliberately experimental and OFF by default. Legacy 8/8 direction // baseline stays bit-identical. A/B is set on an unpublished/offline core // until headphone, CPU and device gates approve native publication. @@ -134,16 +168,92 @@ class SonKuEarlyReflections final { // Bound shutdown to a finite 10-12 time-constant fade, then // restore strict bit-exact OFF/zero CPU on the next callback. if(std::abs(amount_-amountTarget_)<1.e-5f)amount_=amountTarget_; + // Linearity: for identical source/image direction, FIR(H, xL) + + // FIR(H, xR) = FIR(H, xL+xR). Stereo content need not be mono. + // Any nonzero spread permanently disarms fusion until reset, so + // live spread edits cannot reuse stale second-path filter state. + if(fastZeroSpread_ && spread!=0.f)fuseEligible_=false; + const bool fused=directionalHrir_ && fastZeroSpread_ && + fuseEligible_ && spread==0.f; Ears output{}; - for(int s=0;s(ringFrames-hrir::taps-3)); + const int d=static_cast(delay); + const float frac=delay-d; + const int idx=(write_-d)&(ringFrames-1); + const auto& signal=history_[s]; + float l=0.f,r=0.f; + // ROOM may have been OFF for a long time without writing + // new audio into history_. After reactivation never read + // old, pre-OFF samples as new directional reflections. + // The fractional-delay source requires both adjacent + // samples to be from the current activation epoch. + // Zero-filling a 64KiB ring inside the callback is banned. + const int freshTaps=realtimeMode_? + std::clamp(validFrames_-d,0,hrir::taps):hrir::taps; + const bool warming=freshTaps=freshTaps) + ?0.f:sample(k); + 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; + } + l+=v*hL;r+=v*hR; + } + }; + if(fastContiguousHrir_ && idx>=hrir::taps){ + // For 8052/8192 ring positions the entire 140-tap + // window is continuous; no wrap mask inside FIR. + const float* first=signal.data()+idx; + const float* second=history_[1].data()+idx; + render([&](int k) noexcept { + return fused + ?((1.f-frac)*(first[-k]+second[-k])+ + frac*(first[-k-1]+second[-k-1])) + :((1.f-frac)*first[-k]+frac*first[-k-1]); + }); + }else{ + // Exact, original masked circular reference path, + // used for all non-opt-in and near-wrap samples. + render([&](int k) noexcept { + const int at=(idx-k)&(ringFrames-1); + const int prev=(at-1)&(ringFrames-1); + return fused + ?((1.f-frac)*(signal[at]+history_[1][at])+ + frac*(signal[prev]+history_[1][prev])) + :((1.f-frac)*signal[at]+frac*signal[prev]); + }); + } + if(fused){ + auto& second=tap_[1][wall]; + second.delayL=p.delayL;second.delayR=p.delayR; + second.gainL=p.gainL;second.gainR=p.gainR; + } + output.left+=p.gainL*l; + output.right+=p.gainR*r; + }else{ + output.left+=p.gainL*delayed(s,p.delayL); + output.right+=p.gainR*delayed(s,p.delayR); + } } } write_=(write_+1)&(ringFrames-1); @@ -160,6 +270,8 @@ class SonKuEarlyReflections final { float delayL=1.f,delayR=1.f,gainL=0.f,gainR=0.f; float targetDelayL=1.f,targetDelayR=1.f; float targetGainL=0.f,targetGainR=0.f; + using EarBank=std::array,2>; + EarBank kernel{},targetKernel{}; }; float delayed(int source,float delay) const noexcept { // Fractional delay interpolated in a fixed-size power-of-two ring. @@ -204,7 +316,7 @@ class SonKuEarlyReflections final { const float extra=(path-sourceDistance)*rate_/speedOfSound; // Constant 0.31ms ear baseline makes differential ITD // symmetric while keeping every reflection causal. - const float common=extra+earHalfTime*rate_; + const float common=extra+(directionalHrir_?0.f:earHalfTime*rate_); const float earDelta=directionX*earHalfTime*rate_; // New distance studies use fixed 1.6m acoustic reference: // pressure at a reflected path falls with 1/path. Legacy @@ -212,12 +324,32 @@ class SonKuEarlyReflections final { const float level=.28f*walls[wall]* ((custom_?1.6f:sourceDistance)/path); auto& tap=tap_[source][wall]; - tap.targetDelayL=std::clamp(common+earDelta,1.f, + tap.targetDelayL=std::clamp(common+(directionalHrir_?0.f:earDelta),1.f, static_cast(ringFrames-3)); - tap.targetDelayR=std::clamp(common-earDelta,1.f, + tap.targetDelayR=std::clamp(common-(directionalHrir_?0.f:earDelta),1.f, static_cast(ringFrames-3)); - tap.targetGainL=level*(1.f-.13f*directionX); - tap.targetGainR=level*(1.f+.13f*directionX); + tap.targetGainL=level*(directionalHrir_?1.f:(1.f-.13f*directionX)); + tap.targetGainR=level*(directionalHrir_?1.f:(1.f+.13f*directionX)); + if(directionalHrir_){ + // The IMAGE-source arrival angle, NOT source azimuth. + const float dir=std::atan2(x,y)*180.f/pi; + const float pos=std::abs(dir)/hrir::spacingDegrees; + const int lo=std::clamp(static_cast(pos),0, + hrir::directions-1); + const int hi=std::min(lo+1,hrir::directions-1); + const float t=pos-lo; + constexpr float scale=1.f/32768.f; + for(int ear=0;ear<2;++ear){ + const int measured=dir<0.f?1-ear:ear; + for(int k=0;k,sourceCount> history_{}; std::array,sourceCount> tap_{}; std::array lowpass_{}; - float rate_=0.f,delaySlew_=0.f,gainSlew_=0.f,amountSlew_=0.f; + using Bank=const std::int16_t (*)[2][hrir::taps]; + Bank hrirBank_=nullptr; + float rate_=0.f,delaySlew_=0.f,gainSlew_=0.f,amountSlew_=0.f,kernelSlew_=0.f; float amount_=0.f,amountTarget_=0.f; int write_=0,untilGeometry_=0,validFrames_=0; bool realtimeMode_=false; SonKuRoomShape shape_=SonKuRoomShape::Rectangular; SonKuRoomGeometry geometry_{}; bool custom_=false,ready_=false,primed_=false; + bool directionalHrir_=false; + bool fastZeroSpread_=false,fuseEligible_=true; + bool fastContiguousHrir_=false; }; } // namespace armix::sonku diff --git a/engine/builtin_fx/sonku/SonKuSpatialCore.h b/engine/builtin_fx/sonku/SonKuSpatialCore.h index 924fbb639..2f9cb8df0 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; @@ -131,6 +134,18 @@ class SonKuSpatialCore final { bool setEarlyReflectionsShape(SonKuRoomShape shape) noexcept { return room_.setShape(shape); } + // Experimental offline only. No persisted or native/UI renderer switch. + bool setDirectionalEarlyReflectionsHrir(bool on) noexcept { + return room_.setDirectionalHrir(on); + } + // P3 offline-only matched-source-direction optimization; no .smix ABI. + bool setDirectionalZeroSpreadFusion(bool on) noexcept { + return room_.setDirectionalZeroSpreadFusion(on); + } + // P4 research opt-in, no on-disk state nor native GUI control. + bool setDirectionalContiguousHrir(bool on) noexcept { + return room_.setDirectionalContiguousHrir(on); + } // Offline M3 distance/large-room acoustic trial. Not a GUI/native ABI. bool setAcousticRoomGeometry(const SonKuRoomGeometry& geometry) noexcept { return room_.setGeometry(geometry); @@ -181,6 +196,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 +235,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 +285,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. @@ -300,7 +322,8 @@ class SonKuSpatialCore final { } // Positive azimuth is right. MIT KEMAR supplied azimuth 0..180 with // symmetric opposite-ear swapping for left hemisphere, not yaw-panning. - void interpolate(std::size_t source,double azimuth) noexcept { + using EarKernel=std::array,2>; + void interpolate(EarKernel& destination,double azimuth) noexcept { const double norm=wrapDegrees(azimuth); const bool swapped=norm>180.; const double positive=swapped?360.-norm:norm; @@ -315,15 +338,40 @@ class SonKuSpatialCore final { const float next=scale*(static_cast(bank_[lo][measuredEar][k])*(1.f-u) + static_cast(bank_[hi][measuredEar][k])*u); // Recompute target every 16 samples, interpolate per sample. - targets_[source][ear][k]=next; + destination[ear][k]=next; } } } void updateKernels() noexcept { - interpolate(0,degrees_-static_cast(settings_.stereoSpreadDegrees)*0.5); - interpolate(1,degrees_+static_cast(settings_.stereoSpreadDegrees)*0.5); - // First prepared sample is a valid full-level measured HRIR; only - // subsequent direction edits slew, avoiding initial audio dropout. + interpolate(targets_[0], + degrees_-static_cast(settings_.stereoSpreadDegrees)*0.5); + interpolate(targets_[1], + degrees_+static_cast(settings_.stereoSpreadDegrees)*0.5); + // A stereo L=R object should become ONE virtual source at the central + // azimuth. Averaging two displaced HRIRs generates comb filtering + // (for example ~11dB attenuation near 2 kHz at rear/60° in KEMAR). + // Algebraic M/S projection, without a third convolution: + // H_L' = H_L + mu*(H_center - (H_L+H_R)/2) + // H_R' = H_R + mu*(H_center - (H_L+H_R)/2) + // The mid gets the true center HRIR as mu→1, while the SIDE + // transfer H_L'-H_R' is unchanged for ANY mu. Mono channel + // inputs/correlated scene intensity remain native PCM-only. + const float coherent=integrity_.coherentAmount(); + if(coherent>1.e-5f && settings_.stereoSpreadDegrees>0.f) { + interpolate(centerTarget_,degrees_); + for(int ear=0;ear<2;++ear) { + for(int k=0;k,2> history_{}; std::array,2>,2> kernels_{}; std::array,2>,2> targets_{}; + EarKernel centerTarget_{}; // fixed target coefficients, no extra PCM FIR 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; diff --git a/engine/builtin_fx/sonku/SonKuStereoIntegrity.h b/engine/builtin_fx/sonku/SonKuStereoIntegrity.h new file mode 100644 index 000000000..aa708ffc8 --- /dev/null +++ b/engine/builtin_fx/sonku/SonKuStereoIntegrity.h @@ -0,0 +1,91 @@ +// SPDX-License-Identifier: AGPL-3.0-only +#pragma once +#include +#include +#include + +// P1.1 experimental native phase guard. A coherent bass can mask a +// phase-inverted treble instrument in a full-band stereo correlation score. +// Independent SonKu DSP: NOT proprietary Clarity/BRIR or externalization. +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))); + constexpr double twoPi=6.28318530717958647692; + lowAlpha_=static_cast(1.-std::exp(-twoPi*260./rate)); + highAlpha_=static_cast(1.-std::exp(-twoPi*2600./rate)); + reset(); + return true; + } + void reset() noexcept { + energyL_=energyR_=cross_=amount_=coherentAmount_=0.f; + antiCorrelated_=positivelyCorrelated_=false; + low_.fill(0.f);high_.fill(0.f); + for(auto& b:bands_)b=Band{}; + } + float preservedSide(float x0,float x1) noexcept { + const float l=std::clamp(std::isfinite(x0)?x0:0.f,-4.f,4.f); + const float r=std::clamp(std::isfinite(x1)?x1:0.f,-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; + if(power<1.e-8f)positivelyCorrelated_=false; + else if(positivelyCorrelated_) { + if(cross_<.55f*power)positivelyCorrelated_=false; + }else if(cross_>.80f*power)positivelyCorrelated_=true; + amount_+=blendAlpha_*((antiCorrelated_?1.f:0.f)-amount_); + coherentAmount_+=blendAlpha_*((positivelyCorrelated_?1.f:0.f)-coherentAmount_); + if(std::abs(amount_)<1.e-6f)amount_=0.f; + if(std::abs(coherentAmount_)<1.e-6f)coherentAmount_=0.f; + // Exact complementary three-band decomposition; one-pole + // coefficients are prepared, not calculated on the audio thread. + low_[0]+=lowAlpha_*(l-low_[0]); + low_[1]+=lowAlpha_*(r-low_[1]); + high_[0]+=highAlpha_*(l-high_[0]); + high_[1]+=highAlpha_*(r-high_[1]); + const std::array bL{low_[0],high_[0]-low_[0],l-high_[0]}; + const std::array bR{low_[1],high_[1]-low_[1],r-high_[1]}; + float selected=0.f; + for(int i=0;i<3;++i) { + auto& b=bands_[i]; + const float a=bL[i],c=bR[i]; + b.el+=evidenceAlpha_*(a*a-b.el); + b.er+=evidenceAlpha_*(c*c-b.er); + b.cross+=evidenceAlpha_*(a*c-b.cross); + const float p=.5f*(b.el+b.er); + if(p<1.e-8f)b.active=false; + else if(b.active) { + if(b.cross>-.55f*p)b.active=false; + }else if(b.cross<-.78f*p)b.active=true; + b.amount+=blendAlpha_*((b.active?1.f:0.f)-b.amount); + if(std::abs(b.amount)<1.e-6f)b.amount=0.f; + selected+=.5f*(a-c)*b.amount; + } + // Global phase guard has priority; never duplicate global rescue. + // The core keeps the existing bounded 0.65 * mix * trim return. + // The analysis filters retain history for smooth re-entry, but a + // digital-silence input must never emit a synthetic filter tail. + // Preserve P0's exact-zero digital silence contract. + if(l==0.f && r==0.f)return 0.f; + return .5f*(l-r)*amount_+(1.f-amount_)*selected; + } + float recoveryAmount()const noexcept{return amount_;} + float coherentAmount()const noexcept{return coherentAmount_;} +private: + struct Band {float el=0.f,er=0.f,cross=0.f,amount=0.f;bool active=false;}; + float evidenceAlpha_=0.f,blendAlpha_=0.f,lowAlpha_=0.f,highAlpha_=0.f; + float energyL_=0.f,energyR_=0.f,cross_=0.f,amount_=0.f; + float coherentAmount_=0.f; + std::array low_{},high_{}; + std::array bands_{}; + bool antiCorrelated_=false,positivelyCorrelated_=false; +}; +} // namespace armix::sonku diff --git a/tests/sonku_directional_reflections_audio_audit.py b/tests/sonku_directional_reflections_audio_audit.py new file mode 100644 index 000000000..502a24638 --- /dev/null +++ b/tests/sonku_directional_reflections_audio_audit.py @@ -0,0 +1,92 @@ +#!/usr/bin/env python3 +"""Measured directional image-source A/B. Objective PCM, NOT perception.""" +import array +import json +import math +import sys +import wave +from pathlib import Path + +RATE = 48000 +FRAMES = RATE * 2 + +def read(path): + with wave.open(str(path), "rb") as w: + assert (w.getnchannels(), w.getsampwidth(), w.getframerate(), + w.getnframes()) == (2, 2, RATE, FRAMES), path + raw = w.readframes(FRAMES) + samples = array.array("h") + samples.frombytes(raw) + if sys.byteorder != "little": + samples.byteswap() + return samples + +def rms(samples, ch, first, last): + return math.sqrt(sum((samples[2*i+ch]/32768.)**2 + for i in range(first,last))/(last-first)) + +def tone_amplitude(samples, channel, hz): + # Integer cycles in a fixed, 1-second steady window. These are + # synthetic component amplitudes, NOT LUFS or a perceptual metric. + first, count = RATE // 2, RATE + real = imag = 0.0 + for i in range(first, first + count): + value = samples[2*i+channel] / 32768. + phase = 2. * math.pi * hz * i / RATE + real += value * math.cos(phase) + imag -= value * math.sin(phase) + return 2. * math.hypot(real, imag) / count + +def run(folder): + report = {"note": "Measured PCM change, not proven improved externalization", + "rate": RATE, "frames": FRAMES, "scenes": {}} + for pos in ("front", "rear"): + base = read(folder/f"sonku-p2-light-{pos}.wav") + next_ = read(folder/f"sonku-p2-directional-{pos}.wav") + assert base[:300] == next_[:300], "direct pre-reflection PCM changed" + assert max(map(abs, next_)) < 30000, "clipped P2" + delta = math.sqrt(sum(((a-b)/32768.)**2 + for a,b in zip(base[48000:144000], next_[48000:144000])) + / 96000) + assert delta > .000005, (pos, "directional room did not alter reflection", delta) + values = [rms(next_, ch, RATE//2, RATE*3//2) for ch in (0,1)] + original = [rms(base, ch, RATE//2, RATE*3//2) for ch in (0,1)] + assert min(values) > .001 and max(values) < .5 + report["scenes"][pos] = { + "pcmRmsDifference": delta, + "lightEarRms": original, + "directionalEarRms": values, + "directionalSamplePeakDbFS": + 20*math.log10(max(map(abs,next_))/32768.), + } + # Report actual synthetic harmonic spectral changes rather than + # claiming externalization or music neutrality from RMS alone. + # 165/660/2200/4700Hz map to the exact original source motif. + band_delta = {} + for hz in (165, 660, 2200, 4700): + before = [tone_amplitude(base,ch,hz) for ch in (0,1)] + after = [tone_amplitude(next_,ch,hz) for ch in (0,1)] + assert min(before) > 1e-6 and min(after) > 1e-6, ( + "invalid harmonic measurement",pos,hz,before,after) + differences = [20*math.log10(a/b) for a,b in zip(after,before)] + assert all(math.isfinite(db) for db in differences) + band_delta[str(hz)] = differences + report["scenes"][pos]["harmonicChangeDb"] = band_delta + report["scenes"][pos]["rmsChangeDb"] = [ + 20*math.log10(v/b) for v,b in zip(values,original)] + # 1.5dB is an engineering review flag, not a subjective PASS gate. + report["scenes"][pos]["tonalityReviewFlag"] = any( + abs(db)>1.5 for pair in band_delta.values() for db in pair) + (folder/"SONKU-P2-DIRECTIONAL-OBJECTIVE.json").write_text( + json.dumps(report, indent=2, sort_keys=True)+"\n",encoding="utf-8") + return report + +if __name__ == "__main__": + result=run(Path(sys.argv[1])) + for name, metric in result["scenes"].items(): + print("SONKU_P2",name,"differenceRms",metric["pcmRmsDifference"], + "light",metric["lightEarRms"], + "directional",metric["directionalEarRms"], + "harmonicDeltaDb",metric["harmonicChangeDb"], + "tonalityReviewFlag",metric["tonalityReviewFlag"]) + print("PASS SonKu P2 directional native PCM A/B measurements") diff --git a/tests/sonku_directional_reflections_test.cpp b/tests/sonku_directional_reflections_test.cpp new file mode 100644 index 000000000..6472b35c1 --- /dev/null +++ b/tests/sonku_directional_reflections_test.cpp @@ -0,0 +1,128 @@ +// SPDX-License-Identifier: AGPL-3.0-only +#if defined(NDEBUG) +#undef NDEBUG +#endif +#include "../engine/builtin_fx/sonku/SonKuEarlyReflections.h" +#include "../engine/builtin_fx/sonku/SonKuSpatialCore.h" +#include +#include +#include +#include + +int main(){ + using namespace armix::sonku; + for(double rate:{44100.,48000.}){ + auto light=std::make_unique(); + auto hrirRoom=std::make_unique(); + auto mirror=std::make_unique(); + assert(light->prepare(rate)&&hrirRoom->prepare(rate)&&mirror->prepare(rate)); + assert(!light->directionalHrirEnabled()); + assert(hrirRoom->setDirectionalHrir(true)&&mirror->setDirectionalHrir(true)); + assert(light->setShape(SonKuRoomShape::Square)); + assert(hrirRoom->setShape(SonKuRoomShape::Square)); + assert(mirror->setShape(SonKuRoomShape::Square)); + assert(light->setAmount(.55f)&&hrirRoom->setAmount(.55f)); + assert(mirror->setAmount(.55f)); + assert(!hrirRoom->setDirectionalHrir(false)); // active mode change rejected + int first=-1; + double energy=0.,delta=0.,sym=0.; + for(int i=0;i<6500;++i){ + const float v=i==0?.40f:0.f; + const auto ref=light->process(v,0.f,90.,0.f); + const auto a=hrirRoom->process(v,0.f,90.,0.f); + const auto b=mirror->process(v,0.f,-90.,0.f); + assert(std::isfinite(a.left)&&std::isfinite(a.right)); + assert(std::abs(a.left)<.98f&&std::abs(a.right)<.98f); + if(i<150)assert(a.left==0.f&&a.right==0.f); + if(first<0&&(a.left!=0.f||a.right!=0.f))first=i; + energy+=std::abs(a.left)+std::abs(a.right); + delta+=std::abs(a.left-ref.left)+std::abs(a.right-ref.right); + sym+=std::abs(a.left-b.right)+std::abs(a.right-b.left); + } + assert(first>150&&energy>.0001&&delta>.0005); + assert(sym<.02); // measured right/left KEMAR symmetry + assert(hrirRoom->setAmount(0.f)); + for(int i=0;i<10000;++i){ + auto out=hrirRoom->process(0.f,0.f,0.,0.f); + if(i>9000)assert(out.left==0.f&&out.right==0.f); + } + assert(!hrirRoom->active()); + assert(hrirRoom->setDirectionalHrir(false)); + auto core=std::make_unique(); + assert(core->prepare(rate)); + assert(core->setDirectionalEarlyReflectionsHrir(true)); + assert(core->setEarlyReflectionsShape(SonKuRoomShape::Square)); + assert(core->setEarlyReflectionsAmount(.55f)); + Settings s{};s.moving=false;s.stereoSpreadDegrees=0.f; + assert(core->setSettings(s)); + float l[256]{},r[256]{};l[0]=r[0]=.14f; + core->process(l,r,256); + for(int i=0;i<256;++i)assert(std::isfinite(l[i])&&std::isfinite(r[i])); + // P2: moving 360-degree source, frequency-conflicted stereo + // input, two different native host block partitionings. + // No GUI/WebAudio proxy: exact native core process sample history. + { + constexpr int samples=12288; + auto one=std::make_unique(); + auto chunks=std::make_unique(); + assert(one->prepare(rate)&&chunks->prepare(rate)); + assert(one->setDirectionalEarlyReflectionsHrir(true)); + assert(chunks->setDirectionalEarlyReflectionsHrir(true)); + assert(one->setEarlyReflectionsShape(SonKuRoomShape::Square)); + assert(chunks->setEarlyReflectionsShape(SonKuRoomShape::Square)); + assert(one->setEarlyReflectionsAmount(.55f)); + assert(chunks->setEarlyReflectionsAmount(.55f)); + Settings orbit{}; + orbit.moving=true;orbit.revolutionSeconds=4.f; + orbit.stereoSpreadDegrees=60.f;orbit.outputTrim=.6f; + assert(one->setSettings(orbit)&&chunks->setSettings(orbit)); + std::array a{},b{},ca{},cb{}; + constexpr double pi=3.14159265358979323846; + for(int i=0;i( + 2.*pi*220.*i/rate)); + const float treble=.07f*std::sin(static_cast( + 2.*pi*3200.*i/rate)); + a[i]=ca[i]=bass+treble; + b[i]=cb[i]=bass-treble; + } + one->process(a.data(),b.data(),samples); + for(int at=0;atprocess(ca.data()+at,cb.data()+at,n); + at+=n; + } + double energy=0.; + for(int i=0;i1.); + assert(std::abs(one->azimuthDegrees()-chunks->azimuthDegrees())<1.e-8); + } + // Larger actual wall geometry delays directional image-source + // first arrival, not merely a longer arbitrary reverb preset. + { + auto small=std::make_unique(); + auto large=std::make_unique(); + assert(small->prepare(rate)&&large->prepare(rate)); + assert(small->setDirectionalHrir(true)&&large->setDirectionalHrir(true)); + assert(small->setShape(SonKuRoomShape::Square)); + assert(large->setGeometry({28.8f,28.8f,1.6f})); + assert(small->setAmount(.55f)&&large->setAmount(.55f)); + int firstSmall=-1,firstLarge=-1; + for(int i=0;i<7500;++i){ + const float input=i==0?.5f:0.f; + const auto a=small->process(input,input,0.,0.f); + const auto b=large->process(input,input,0.,0.f); + if(firstSmall<0&&(a.left!=0.f||a.right!=0.f))firstSmall=i; + if(firstLarge<0&&(b.left!=0.f||b.right!=0.f))firstLarge=i; + } + assert(firstSmall>100&&firstLarge>firstSmall+800); + } + } + std::puts("PASS P2 directional reflected-KEMAR 44.1/48k, mirror, orbit chunk parity, near/far, OFF"); +} diff --git a/tests/sonku_hrir_spectral_audit.cpp b/tests/sonku_hrir_spectral_audit.cpp new file mode 100644 index 000000000..407cde326 --- /dev/null +++ b/tests/sonku_hrir_spectral_audit.cpp @@ -0,0 +1,96 @@ +// SPDX-License-Identifier: AGPL-3.0-only +// Offline diagnostic only: published KEMAR FIR spectral evidence at fixed azimuths. +// No DSP implementation, third-party binaries, runtime FFT or audio callback work. +#include "../engine/builtin_fx/sonku/SonKuMeasuredHrir.h" +#include +#include +#include +#include +#include +#include + +namespace { +using namespace armix::sonku; +constexpr double pi=3.14159265358979323846; +using Response=std::complex; +double wrap(double deg) { + while(deg>180.)deg-=360.; + while(deg<-180.)deg+=360.; + return deg; +} +Response hrtf(double angle,int ear,double hz,double rate) { + angle=wrap(angle); + const bool opposite=angle<0.; + const double coordinate=std::abs(angle)/hrir::spacingDegrees; + const int lo=std::clamp(static_cast(std::floor(coordinate)),0,hrir::directions-1); + const int hi=std::min(lo+1,hrir::directions-1); + const double t=coordinate-lo; + const int selectedEar=opposite?1-ear:ear; + const auto& bank=rate==44100.?hrir::normal44100:hrir::normal48000; + Response sum{}; + for(int k=0;k frequencies{ + 125,160,200,250,315,400,500,630,800,1000,1250,1600,2000, + 2500,3150,4000,5000,6300,8000}; + constexpr std::array directions{0,45,90,135,180}; + std::printf("rate,azimuth,ear,hz,baselineMidVsCenterDb,correctedMidVsCenterDb,sideError\n"); + int rows=0; + for(const double rate: {44100.,48000.}) { + for(const int azimuth:directions) { + for(int ear=0;ear<2;++ear) { + for(const int hz:frequencies) { + const Response h0=hrtf(azimuth-30,ear,hz,rate); + const Response h1=hrtf(azimuth+30,ear,hz,rate); + const Response center=hrtf(azimuth,ear,hz,rate); + const Response average=.5*(h0+h1); + // Mirrors the exact two-kernel correction from + // SonKuSpatialCore::updateKernels() with mu=1. + const Response correction=center-average; + const Response n0=h0+correction,n1=h1+correction; + const Response corrected=.5*(n0+n1); + const double baselineDb=db(std::abs(average)/std::max(1.e-9,std::abs(center))); + const double correctedDb=db(std::abs(corrected)/std::max(1.e-9,std::abs(center))); + const double sideError=std::abs((n0-n1)-(h0-h1)); + expect(std::isfinite(baselineDb)&&std::isfinite(correctedDb), + "nonfinite frequency response"); + expect(std::abs(correctedDb)<1.e-8, + "correction must restore central HRIR frequency response"); + expect(sideError<1.e-7, + "coherent-mid correction changed stereo side transfer"); + // Both axes were independently observed to have deep + // KEMAR 2kHz coherent-source notches at 60-degree spread. + if(rate==48000. && hz==2000 && ear==0 && + (azimuth==0 || azimuth==180)) + expect(baselineDb< -5., "missing legacy 2kHz comb notch"); + std::printf("%.0f,%d,%d,%d,%.5f,%.9f,%.9g\n", + rate,azimuth,ear,hz,baselineDb,correctedDb,sideError); + ++rows; + } + } + } + } + expect(rows==380,"unexpected spectral audit coverage"); + std::fprintf(stderr,"PASS SonKu KEMAR 380 spectral checks: 44.1/48k, 5 angles, " + "two ears, 19 bands; corrected MID and stereo SIDE invariant\n"); + return 0; + } catch(const std::exception& e) { + std::fprintf(stderr,"SonKu spectral audit FAILED: %s\n",e.what()); + return 1; + } +} diff --git a/tests/sonku_multiband_phase_test.cpp b/tests/sonku_multiband_phase_test.cpp new file mode 100644 index 000000000..b080bbc5d --- /dev/null +++ b/tests/sonku_multiband_phase_test.cpp @@ -0,0 +1,62 @@ +// SPDX-License-Identifier: AGPL-3.0-only +#if defined(NDEBUG) +#undef NDEBUG +#endif +#include "../engine/builtin_fx/sonku/SonKuStereoIntegrity.h" +#include +#include +#include +#include +#include + +int main() { + constexpr float pi=3.14159265358979323846f; + for(double rate:{44100.,48000.}) { + using armix::sonku::SonKuStereoIntegrity; + SonKuStereoIntegrity probe; + assert(probe.prepare(rate)); + // The P0 full-band detector misses both mixtures: total L/R + // correlation is positive while a local stereo-side band is lost. + for(bool invertBass:{false,true}){ + probe.reset(); + double power=0.; + for(int i=0;i<30000;++i) { + const float lo=(invertBass?.10f:.29f)* + std::sin(2.f*pi*170.f*i/static_cast(rate)); + const float hi=(invertBass?.34f:.10f)* + std::sin(2.f*pi*3200.f*i/static_cast(rate)); + const float l=lo+hi; + const float r=invertBass?(-lo+hi):(lo-hi); + const float rescue=probe.preservedSide(l,r); + assert(std::isfinite(rescue)); + if(i>=22000)power+=rescue*rescue; + } + assert(probe.recoveryAmount()<.02f); + assert(std::sqrt(power/8000.)>.035); + } + // Positive coherent mono must remain bit-exact zero from the side + // reconstruction (no new transient phantom or center coloration). + probe.reset(); + for(int i=0;i<22000;++i) { + const float v=.20f*std::sin(2.f*pi*440.f*i/static_cast(rate)); + assert(probe.preservedSide(v,v)==0.f); + } + assert(probe.recoveryAmount()==0.f); + assert(probe.coherentAmount()>.95f); + probe.reset(); + for(int i=0;i<22000;++i) { + const float v=.20f*std::sin(2.f*pi*440.f*i/static_cast(rate)); + (void)probe.preservedSide(v,-v); + } + assert(probe.recoveryAmount()>.95f); + for(int i=0;i<25000;++i)assert(probe.preservedSide(0.f,0.f)==0.f); + assert(probe.recoveryAmount()<.05f); + assert(probe.prepare(rate)); + assert(probe.recoveryAmount()==0.f); + assert(probe.coherentAmount()==0.f); + assert(std::isfinite(probe.preservedSide( + std::numeric_limits::infinity(), + std::numeric_limits::quiet_NaN()))); + } + std::puts("PASS SonKu P1.1 mixed-polarity 3-band guard 44.1/48k"); +} diff --git a/tests/sonku_music_integrity_comparison.py b/tests/sonku_music_integrity_comparison.py new file mode 100644 index 000000000..163ec4c9e --- /dev/null +++ b/tests/sonku_music_integrity_comparison.py @@ -0,0 +1,173 @@ +#!/usr/bin/env python3 +"""Exact-source SonKu headphone A/B comparison against pinned public alpha.23. + +No perceptual/dearVR claim: measures native PCM rescue of deterministic +anti-phase stereo and coherent 2kHz rear comb-filter coloration. +All inputs match in length, phase, SPL/gain settings and native audio path. +""" +from __future__ import annotations + +import array +import json +import math +from pathlib import Path +import sys +import wave + +RATE = 48_000 +FRAMES = RATE * 4 +FILES = ( + "sonku-music-positive-front.wav", + "sonku-music-anti-phase-front.wav", + "sonku-music-anti-phase-rear.wav", + "sonku-music-coherent-front-spread60.wav", + "sonku-music-coherent-rear-spread60.wav", + "sonku-music-splitband-bass-coherent-treble-inverted.wav", +) + + +def read_audio(folder: Path, name: str) -> tuple[bytes, array.array]: + path = folder / name + assert path.is_file() and path.stat().st_size == FRAMES * 4 + 44, path + with wave.open(str(path), "rb") as f: + assert (f.getnchannels(), f.getsampwidth(), f.getframerate(), + f.getnframes(), f.getcomptype()) == (2, 2, RATE, FRAMES, "NONE"), name + raw = f.readframes(FRAMES) + assert len(raw) == FRAMES * 4 + audio = array.array("h") + audio.frombytes(raw) + if sys.byteorder != "little": + audio.byteswap() + assert max(map(abs, audio)) < 30_000, (name, "clipping", max(map(abs, audio))) + return raw, audio + + +def rms(audio: array.array, ear: int) -> float: + # 1.5-3.5s: exclude onset/correlation attack and 20ms last fade. + start = int(RATE * 1.5) + end = int(RATE * 3.5) + values = (audio[2 * i + ear] / 32768. for i in range(start, end)) + energy = sum(sample * sample for sample in values) + return math.sqrt(energy / (end - start)) + + +def tone_amplitude(audio: array.array, ear: int, frequency: int = 2000) -> float: + # Exactly 48k steady frames = integer cycles at all fixture frequencies. + # Coherent sine/cosine demod measures *2kHz tonal content*, not overall + # level which could hide comb filtering through other musical harmonics. + start, count = RATE * 2, RATE + re = im = 0. + for i in range(count): + sample = audio[(start + i) * 2 + ear] / 32768. + phase = 2. * math.pi * frequency * i / RATE + re += sample * math.cos(phase) + im += sample * math.sin(phase) + return (2. / count) * math.hypot(re, im) + + +def run(baseline_dir: Path, candidate_dir: Path) -> dict: + base, improved = {}, {} + for name in FILES: + base[name] = read_audio(baseline_dir, name) + improved[name] = read_audio(candidate_dir, name) + # Legacy 0° SPREAD mono/coherent signal must be bit-exact. + center = FILES[0] + assert base[center][0] == improved[center][0], ( + "regression: previously approved center KEMAR PCM has changed") + report = {"baseline": "v0.5.0-alpha.23 native SonKu core", + "note": "Measured numerical transfer only; headphone externalization unproven", + "sampleRate": RATE, "frames": FRAMES, + "exactCenteredPcm": True, "antiPhase": {}, "coherentMid2kHz": {}, + "mixedPolarityTreble": {}} + # Old filters are identical for L=-R / 0 spread and cancel completely. + # New guard must preserve actual music energy in *both ears*, not just + # front/rear labels, despite the native 0.5 wet mix. + for name in FILES[1:3]: + old = [rms(base[name][1], ear) for ear in (0, 1)] + new = [rms(improved[name][1], ear) for ear in (0, 1)] + assert max(old) < 0.001, (name, "old should null", old) + assert min(new) > 0.025, (name, "anti-phase PCM not rescued", old, new) + assert max(new) < 0.5, (name, "excess output", new) + report["antiPhase"][name] = {"baselineRms": old, + "candidateRms": new} + # Coherent 60° two-source FIR is a direct comb-filter mechanism. Verify + # native kernel-center compensation, not an overall boost or new reverb. + for name, threshold in ((FILES[3], 1.30), (FILES[4], 2.0)): + old = [tone_amplitude(base[name][1], ear) for ear in (0, 1)] + new = [tone_amplitude(improved[name][1], ear) for ear in (0, 1)] + factors = [a / max(1.e-10, b) for a, b in zip(new, old)] + assert min(factors) > threshold, ( + name, "2kHz cancellation not repaired", factors) + assert max(new) < 0.25, (name, "excessive compensated gain", new) + report["coherentMid2kHz"][name] = { + "baselineAmplitude": old, "candidateAmplitude": new, + "candidateOverBaseline": factors, + "increaseDb": [20. * math.log10(x) for x in factors], + } + # Original coherent bass dominates full-band L/R correlation and + # should be numerically unchanged by high-frequency protection. + name = FILES[5] + old_high = [tone_amplitude(base[name][1], ear, 3200) for ear in (0, 1)] + new_high = [tone_amplitude(improved[name][1], ear, 3200) for ear in (0, 1)] + assert max(old_high) < 0.0002, ("baseline treble should cancel", old_high) + assert min(new_high) > 0.006, ("split-band treble not rescued", new_high) + assert max(new_high) < 0.1, ("split-band rescue unexpectedly loud", new_high) + old_low = [tone_amplitude(base[name][1], ear, 220) for ear in (0, 1)] + new_low = [tone_amplitude(improved[name][1], ear, 220) for ear in (0, 1)] + low_delta = [20. * math.log10(max(n, 1e-12) / max(b, 1e-12)) + for b, n in zip(old_low, new_low)] + assert max(map(abs, low_delta)) < .25, ("coherent bass changed", low_delta) + report["mixedPolarityTreble"][name] = { + "baselineTrebleAmplitude": old_high, + "candidateTrebleAmplitude": new_high, + "bassDifferenceDb": low_delta, + } + # A relative binaural phase measurement is necessary for a signal + # that must remain artistically inverted, not silently become mono. + def phasor(ear: int) -> complex: + start, count, hz = RATE * 2, RATE, 3200 + re = im = 0. + for j in range(count): + sample = improved[name][1][2 * (start + j) + ear] / 32768. + phase = 2. * math.pi * hz * j / RATE + re += sample * math.cos(phase) + im -= sample * math.sin(phase) + return complex(re, im) * (2. / count) + + cross_phase = phasor(0) * phasor(1).conjugate() + interaural_deg = math.degrees(math.atan2(cross_phase.imag, cross_phase.real)) + assert abs(abs(interaural_deg) - 180.) < 5., ( + "recovered artistic treble polarity was not retained", interaural_deg) + report["mixedPolarityTreble"][name]["interauralPhaseDifferenceDeg"] = interaural_deg + # RMS dBFS is measured PCM level, NOT K-weighted LUFS or true-peak. + report["mixedPolarityTreble"][name]["candidateRmsDbFS"] = [ + 20. * math.log10(max(rms(improved[name][1], ear), 1e-12)) + for ear in (0, 1) + ] + peak = max(abs(v) for v in improved[name][1]) / 32768. + report["mixedPolarityTreble"][name]["samplePeakDbFS"] = ( + 20. * math.log10(max(peak, 1e-12)) + ) + (candidate_dir / "MUSIC-INTEGRITY-OBJECTIVE.json").write_text( + json.dumps(report, indent=2, sort_keys=True) + "\n", encoding="utf-8") + return report + + +if __name__ == "__main__": + if len(sys.argv) != 3: + sys.exit("Usage: sonku_music_integrity_comparison.py BASELINE_DIR CANDIDATE_DIR") + result = run(Path(sys.argv[1]), Path(sys.argv[2])) + for name, case in result["coherentMid2kHz"].items(): + print("SONKU_COHERENT_HRIR_2KHZ", name, "perEarGainDb", + [round(v, 2) for v in case["increaseDb"]]) + for name, case in result["antiPhase"].items(): + print("SONKU_ANTI_PHASE_RECOVERY", name, "perEarRms", + [round(v, 5) for v in case["candidateRms"]]) + for name, case in result["mixedPolarityTreble"].items(): + print("SONKU_SPLITBAND_TREBLE_3200", name, + "baseline", [round(v, 6) for v in case["baselineTrebleAmplitude"]], + "candidate", [round(v, 6) for v in case["candidateTrebleAmplitude"]], + "bassDeltaDb", [round(v, 4) for v in case["bassDifferenceDb"]], + "phaseDeg", round(case["interauralPhaseDifferenceDeg"], 2), + "samplePeakDbFS", round(case["samplePeakDbFS"], 2)) + print("PASS SONKU MUSIC INTEGRITY exact baseline-vs-new PCM, 6 WAV, 48k") diff --git a/tests/sonku_p3_fusion_audio_audit.py b/tests/sonku_p3_fusion_audio_audit.py new file mode 100644 index 000000000..c14238548 --- /dev/null +++ b/tests/sonku_p3_fusion_audio_audit.py @@ -0,0 +1,63 @@ +#!/usr/bin/env python3 +"""Exact-engine P3 140-tap directional reflection equivalence test.""" +import array +import json +import math +import sys +import wave +from pathlib import Path + +RATE=48000 +FRAMES=RATE*2 +HARMONICS=(165,660,2200,4700) + +def read(path): + with wave.open(str(path),"rb") as f: + assert (f.getnchannels(),f.getsampwidth(),f.getframerate(), + f.getnframes())==(2,2,RATE,FRAMES),path + payload=f.readframes(FRAMES) + a=array.array("h") + a.frombytes(payload) + if sys.byteorder!="little":a.byteswap() + return a + +def amplitude(a,ear,hz): + first,count=RATE//2,RATE + re=im=0.0 + for i in range(first,first+count): + phase=2*math.pi*hz*i/RATE + x=a[2*i+ear]/32768. + re+=x*math.cos(phase) + im-=x*math.sin(phase) + return 2*math.hypot(re,im)/count + +def run(folder): + report={"method":"same source native P2 versus P3 zero spread", + "caveat":"not a listening or Windows ASIO proof", + "scenes":{}} + for direction in ("front","rear"): + original=read(folder/f"sonku-p3-reference-{direction}.wav") + fused=read(folder/f"sonku-p3-fused-{direction}.wav") + differences=[a-b for a,b in zip(original,fused)] + peak=max(map(abs,differences)) + rms=math.sqrt(sum(d*d for d in differences)/len(differences))/32768. + assert peak<=2,(direction,"peak more than 2 PCM LSB",peak) + assert rms<2e-5,(direction,"RMS drift",rms) + harmonics={} + for hz in HARMONICS: + a=[amplitude(original,ear,hz) for ear in (0,1)] + b=[amplitude(fused,ear,hz) for ear in (0,1)] + assert min(a)>1e-7 and min(b)>1e-7 + delta=[20*math.log10(y/x) for x,y in zip(a,b)] + assert max(map(abs,delta))<.05,(direction,hz,delta) + harmonics[str(hz)]=delta + report["scenes"][direction]={ + "maxSampleDifferenceLSB":peak, + "differenceRms":rms, + "harmonicChangeDb":harmonics} + (folder/"SONKU-P3-PCM-EQUIVALENCE.json").write_text( + json.dumps(report,indent=2,sort_keys=True)+"\n",encoding="utf-8") + print("PASS P3 exact native PCM and harmonic equivalence",json.dumps(report)) + +if __name__=="__main__": + run(Path(sys.argv[1])) diff --git a/tests/sonku_p3_spread_zero_fusion_test.cpp b/tests/sonku_p3_spread_zero_fusion_test.cpp new file mode 100644 index 000000000..72bd04266 --- /dev/null +++ b/tests/sonku_p3_spread_zero_fusion_test.cpp @@ -0,0 +1,76 @@ +// SPDX-License-Identifier: AGPL-3.0-only +// P3 optional optimization, equality of full first-order image HRIR +// at exactly equal L/R emitter directions. No mono assumption. +#if defined(NDEBUG) +#undef NDEBUG +#endif +#include "../engine/builtin_fx/sonku/SonKuEarlyReflections.h" +#include "../engine/builtin_fx/sonku/SonKuSpatialCore.h" +#include +#include +#include +#include +#include +#include +#include + +int main(){ + using namespace armix::sonku; + constexpr double pi=3.14159265358979323846; + for(double rate:{44100.,48000.})for(int mode=0;mode<4;++mode){ + // 0 coherent; 1 stereo independent; 2 phase-inverted; + // 3 correlated bass + inverted treble: music-integrity stress. + auto slow=std::make_unique(); + auto fast=std::make_unique(); + assert(slow->prepare(rate)&&fast->prepare(rate)); + assert(!fast->setDirectionalZeroSpreadFusion(true)); // requires P2 mode + assert(slow->setDirectionalHrir(true)&&fast->setDirectionalHrir(true)); + assert(fast->setDirectionalZeroSpreadFusion(true)); + assert(!slow->zeroSpreadFusionEnabled()); + assert(fast->zeroSpreadFusionEnabled()); + assert(slow->setShape(SonKuRoomShape::Square)); + assert(fast->setShape(SonKuRoomShape::Square)); + assert(slow->setAmount(.55f)&&fast->setAmount(.55f)); + assert(!fast->setDirectionalZeroSpreadFusion(false)); // active rejection + double squared=0.,error=0.,maxDiff=0.; + for(int i=0;i(rate/2);++i){ + const double t=i/rate; + const float a=.10f*std::sin(2.*pi*220.*t)+ + .045f*std::sin(2.*pi*3200.*t); + const float b=mode==0?a:mode==1 + ?.10f*std::sin(2.*pi*470.*t)+ + .035f*std::sin(2.*pi*7400.*t) + :mode==2?-a + :.10f*std::sin(2.*pi*220.*t)- + .045f*std::sin(2.*pi*3200.*t); + const double angle=static_cast(i)*720./rate; + const auto x=slow->process(a,b,angle,0.f); + const auto y=fast->process(a,b,angle,0.f); + assert(std::isfinite(y.left)&&std::isfinite(y.right)); + for(const float d:{x.left-y.left,x.right-y.right}){ + const double v=std::abs(d); + maxDiff=std::max(maxDiff,v);error+=v*v; + } + squared+=x.left*x.left+x.right*x.right; + } + // Exact L=-R sums to zero for spread==0: a PHYSICALLY CORRECT + // null, not a DSP failure. Music-side preservation belongs to + // the spatial core (P0/P1 regression), not this wet-only path. + if(mode==2)assert(squared<1.e-6); + else assert(squared>1.e-4); + const double errorRms=std::sqrt(error/rate); + assert(errorRms<3.e-6&&maxDiff<2.e-5); + // In-flight spread change automatically DISARMS fusion forever + // until reset, while preserving both ear histories and coefficients. + for(int i=0;i<1000;++i){ + const float a=.04f*std::sin(static_cast(2*pi*700*i/rate)); + const float b=.05f*std::cos(static_cast(2*pi*960*i/rate)); + const float spread=i<500?60.f:0.f; + const auto x=slow->process(a,b,40.,spread); + const auto y=fast->process(a,b,40.,spread); + assert(std::abs(x.left-y.left)<3.e-5f); + assert(std::abs(x.right-y.right)<3.e-5f); + } + } + std::puts("PASS P3 source-azimuth fusion, 44.1/48k, 4 music profiles, rotation and spread edit"); +} diff --git a/tests/sonku_p4_contiguous_audio_audit.py b/tests/sonku_p4_contiguous_audio_audit.py new file mode 100644 index 000000000..580f6264f --- /dev/null +++ b/tests/sonku_p4_contiguous_audio_audit.py @@ -0,0 +1,88 @@ +#!/usr/bin/env python3 +"""Bit-exact 140-tap source PCM P4 vs P2, 60/120 spread, independent stereo. + +This validates data invariance, not claimed improved subjective externalization. +""" +import array +import json +import math +import sys +import wave +from pathlib import Path + +RATE = 48000 +FRAMES = RATE * 2 +SCENES = ("front-spread60", "rear-spread60", + "front-spread120", "rear-spread120") +HARMONICS = (165, 940, 2200, 4700, 5100) + +def read(path): + with wave.open(str(path), "rb") as f: + assert (f.getnchannels(), f.getsampwidth(), f.getframerate(), + f.getnframes()) == (2, 2, RATE, FRAMES), path + data = f.readframes(FRAMES) + result = array.array("h") + result.frombytes(data) + if sys.byteorder != "little": + result.byteswap() + return data, result + +def amplitude(signal, ear, hz): + start, count = RATE//2, RATE + re = im = 0. + for i in range(start, start+count): + phase = 2.*math.pi*hz*i/RATE + value = signal[2*i+ear]/32768. + re += value*math.cos(phase) + im -= value*math.sin(phase) + return 2.*math.hypot(re, im)/count + +def run(folder): + report = {"method": "identical original independent-stereo source P2 vs P4", + "note": "no human hearing / ASIO / dearVR comparison", "scenes": {}} + for scene in SCENES: + full, a = read(folder/f"sonku-p4-full-{scene}.wav") + contig, b = read(folder/f"sonku-p4-contiguous-{scene}.wav") + differences = [int(x)-int(y) for x,y in zip(a,b)] + peakError = max(map(abs,differences)) + changed = sum(d!=0 for d in differences) + fraction = changed/len(a) + rmsError = math.sqrt(sum(d*d for d in differences)/len(a))/32768. + assert peakError<=1,(scene,"excessive sample delta in LSB",peakError) + assert fraction<.02,(scene,"widespread numeric drift",fraction) + assert rmsError<1e-5,(scene,"excessive RMS delta",rmsError) + bands={} + for ear in (0, 1): + baseline = {str(hz): amplitude(a, ear, hz) for hz in HARMONICS} + optimized = {str(hz): amplitude(b, ear, hz) for hz in HARMONICS} + assert any(v > .001 for v in baseline.values()),(scene,ear) + changes = {} + for hz in HARMONICS: + before, after = baseline[str(hz)], optimized[str(hz)] + assert min(before,after)>1e-7 + db = 20.*math.log10(after/before) + assert abs(db)<.01,(scene,ear,hz,db) + changes[str(hz)] = db + bands[str(ear)] = changes + report["scenes"][scene] = { + "byteExact": full == contig, + "peakSampleDifferenceLSB": peakError, + "changedSampleCount": changed, + "changedSampleFraction": fraction, + "differenceRms": rmsError, + "harmonicDeltaDb": bands, + "frames": FRAMES, + "interleavedSamples": len(a)} + (folder/"SONKU-P4-EXACT-PCM.json").write_text( + json.dumps(report, indent=2, sort_keys=True)+"\n", + encoding="utf-8") + for scene, data in report["scenes"].items(): + print("SONKU_P4_PCM",scene, + "peakLSB",data["peakSampleDifferenceLSB"], + "changedFraction",data["changedSampleFraction"], + "rms",data["differenceRms"], + "harmonicDeltaDb",data["harmonicDeltaDb"]) + print("PASS P4 native independent stereo 1-LSB / 0.01dB tolerance 60/120 FRONT/REAR") + +if __name__ == "__main__": + run(Path(sys.argv[1])) diff --git a/tests/sonku_p4_contiguous_reflections_test.cpp b/tests/sonku_p4_contiguous_reflections_test.cpp new file mode 100644 index 000000000..ad95857d0 --- /dev/null +++ b/tests/sonku_p4_contiguous_reflections_test.cpp @@ -0,0 +1,86 @@ +// SPDX-License-Identifier: AGPL-3.0-only +// Exact 140-tap native-room FIR invariance across ring wrap, moving HRIR, +// two independent stereo emitters and dynamic spread changes. +#if defined(NDEBUG) +#undef NDEBUG +#endif +#include "../engine/builtin_fx/sonku/SonKuEarlyReflections.h" +#include "../engine/builtin_fx/sonku/SonKuSpatialCore.h" +#include +#include +#include +#include +#include +#include +int main(){ + using namespace armix::sonku; + constexpr double pi=3.14159265358979323846; + for(double rate:{44100.,48000.}){ + for(float spread:{0.f,60.f,120.f}){ + for(int mode=0;mode<3;++mode){ + auto ref=std::make_unique(); + auto fast=std::make_unique(); + assert(ref->prepare(rate)&&fast->prepare(rate)); + assert(!fast->setDirectionalContiguousHrir(true)); + assert(ref->setDirectionalHrir(true)); + assert(fast->setDirectionalHrir(true)); + assert(fast->setDirectionalContiguousHrir(true)); + assert(fast->contiguousHrirEnabled()); + assert(ref->setShape(SonKuRoomShape::Square)); + assert(fast->setShape(SonKuRoomShape::Square)); + assert(ref->setAmount(.55f)&&fast->setAmount(.55f)); + assert(!fast->setDirectionalContiguousHrir(false)); + double energy=0.; + // 24576 crosses ring wrap x3; at least one frame enters + // each of the fast/fallback windows at both sample rates. + for(int i=0;i<24576;++i){ + const double t=i/rate; + const float a=mode==2?(i%1973==0?.30f:0.f): + .14f*std::sin(2*pi*220*t)+ + .047f*std::sin(2*pi*3200*t); + const float b=mode==2?(i%1613==0?.22f:0.f): + (mode==0? a : .12f*std::sin(2*pi*470*t)- + .057f*std::sin(2*pi*3200*t)); + const float az=static_cast(360.*i/12288.); + const float activeSpread=(i>12000&&i<16000) + ?90.f:spread; + const auto original=ref->process(a,b,az,activeSpread); + const auto optimized=fast->process(a,b,az,activeSpread); + assert(std::isfinite(optimized.left)); + assert(std::isfinite(optimized.right)); + assert(std::abs(original.left-optimized.left)<2.e-6f); + assert(std::abs(original.right-optimized.right)<2.e-6f); + energy+=original.left*original.left+ + original.right*original.right; + } + if(mode!=0 || spread!=0.f)assert(energy>.0001); + assert(fast->contiguousHrirEnabled()); + assert(fast->setAmount(0.f)); + assert(ref->setAmount(0.f)); + for(int i=0;i<9000;++i){ + auto x=ref->process(0.f,0.f,0.,spread); + auto y=fast->process(0.f,0.f,0.,spread); + assert(std::abs(x.left-y.left)<1.e-6f); + assert(std::abs(x.right-y.right)<1.e-6f); + } + assert(!fast->active()); + assert(fast->setDirectionalContiguousHrir(false)); + } + } + // The same opt-in mode must also work through the native core. + auto core=std::make_unique(); + assert(core->prepare(rate)); + assert(core->setDirectionalEarlyReflectionsHrir(true)); + assert(core->setDirectionalContiguousHrir(true)); + assert(core->setEarlyReflectionsShape(SonKuRoomShape::Square)); + assert(core->setEarlyReflectionsAmount(.55f)); + Settings s{};s.moving=true;s.stereoSpreadDegrees=60.f; + assert(core->setSettings(s)); + float l[128]{},r[128]{}; + l[0]=r[0]=.13f; + core->process(l,r,128); + for(int i=0;i<128;++i) + assert(std::isfinite(l[i])&&std::isfinite(r[i])); + } + std::puts("PASS P4 full-140 KEMAR FIR PCM, 44.1/48k, 0/60/120 spread, 3 ring wraps"); +} diff --git a/tests/sonku_p5_room_reactivation_test.cpp b/tests/sonku_p5_room_reactivation_test.cpp new file mode 100644 index 000000000..906a2a954 --- /dev/null +++ b/tests/sonku_p5_room_reactivation_test.cpp @@ -0,0 +1,67 @@ +// SPDX-License-Identifier: AGPL-3.0-only +// P5 stale-tail prevention when a native directional room is turned OFF +// and re-enabled with silence, without clearing the ring in audio callback. +#if defined(NDEBUG) +#undef NDEBUG +#endif +#include "../engine/builtin_fx/sonku/SonKuEarlyReflections.h" +#include +#include +#include +#include +int main(){ + using namespace armix::sonku; + constexpr double pi=3.14159265358979323846; + for(double rate:{44100.,48000.}){ + for(bool contiguous:{false,true}){ + for(float spread:{0.f,60.f,120.f}){ + auto room=std::make_unique(); + assert(room->prepare(rate)); + assert(room->setDirectionalHrir(true)); + if(contiguous)assert(room->setDirectionalContiguousHrir(true)); + const SonKuRoomGeometry geometry{7.2f,7.2f,1.6f}; + assert(room->setRealtimeRoom(geometry,.55f,true)); + for(int i=0;i<4500;++i){ + float l=.22f*std::sin(static_cast(2*pi*440*i/rate)); + float r=.13f*std::sin(static_cast(2*pi*720*i/rate)); + room->process(l,r,45.,spread); + } + // Drive the old ring with audio while the ROOM fades out, + // so stale samples are definitely present at the restart. + assert(room->setRealtimeRoom(geometry,0.f,false)); + int fadeFrames=0; + while(room->active()&&fadeFrames<10000){ + const float l=.14f*std::sin(static_cast( + 2*pi*520*fadeFrames/rate)); + const float r=.11f*std::cos(static_cast( + 2*pi*1250*fadeFrames/rate)); + room->process(l,r,70.,spread); + ++fadeFrames; + } + assert(!room->active()); + assert(fadeFrames>100); + // OFF => no history writes. Re-enabling on a changed + // source scene with zero input must NOT resurrect old PCM. + assert(room->setRealtimeRoom(geometry,.55f,true)); + for(int i=0;i<1500;++i){ + auto out=room->process(0.f,0.f,135.,spread); + assert(std::isfinite(out.left)&&std::isfinite(out.right)); + assert(out.left==0.f && out.right==0.f); + } + // But newly captured signal MUST still emerge with + // physically causal image-path delay, not be dead-muted. + int first=-1; + double energy=0.; + for(int i=0;i<7000;++i){ + const float v=i==0?.35f:0.f; + const auto out=room->process(v,v,135.,spread); + if(first<0&&(out.left!=0.f||out.right!=0.f))first=i; + energy+=out.left*out.left+out.right*out.right; + } + assert(first>100&&first<6000); + assert(energy>1.e-7); + } + } + } + std::puts("PASS SonKu P5 no old room ghost on reactivation; real new impulse remains audible"); +} diff --git a/tests/sonku_spatial_core_test.cpp b/tests/sonku_spatial_core_test.cpp index 0258e2201..9b5980e02 100644 --- a/tests/sonku_spatial_core_test.cpp +++ b/tests/sonku_spatial_core_test.cpp @@ -10,8 +10,218 @@ #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); + assert(guard.coherentAmount()>.95f); + guard.reset(); + assert(guard.coherentAmount()==0.f); + 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); + assert(guard.coherentAmount()<.01f); + for(int i=0;i<25000;++i) + assert(guard.preservedSide(0.f,0.f)==0.f); + assert(guard.recoveryAmount()<.05f); + assert(guard.coherentAmount()<.05f); + assert(guard.prepare(rate)); // device restart must not remember polarity + assert(guard.recoveryAmount()==0.f); + assert(guard.coherentAmount()==0.f); + } + // A fully coherent music MID should take one center KEMAR HRIR instead + // of the comb-filtered mean of two spatially separated virtual speakers. + // This exercises the REAL native FIR in steady state (not a UI pan). + { + Settings coherent=s; + coherent.startAzimuthDegrees=180.f; + coherent.stereoSpreadDegrees=60.f; + coherent.spatialMix=1.f; + coherent.outputTrim=.6f; + auto mid=std::make_unique(); + assert(mid->prepare(rate)&&mid->setSettings(coherent)); + constexpr int frames=32768; + constexpr double frequency=2000.; + std::vector left(frames),right(frames); + for(int i=0;i( + std::sin(2.*3.14159265358979323846*frequency*i/rate)); + mid->process(left.data(),right.data(),frames); + double sum=0.; + for(int i=frames-8192;i(left[i])*left[i]; + const double observed=std::sqrt(sum/8192.)*std::sqrt(2.); + const auto& h=(std::abs(rate-44100.)<.1)? + hrir::normal44100:hrir::normal48000; + auto response=[&](int azimuth,int ear) { + double real=0.,imag=0.; + for(int i=0;i{real,imag}; + }; + const auto center=response(180,0); + const double expected=.04*coherent.outputTrim* + std::hypot(center[0],center[1]); + assert(expected>.005 && observed/expected>.86 + && observed/expected<1.14); + if(std::abs(rate-48000.)<.1){ + const auto a=response(150,0),b=response(150,1); + const double oldMean=.5*std::hypot(a[0]+b[0],a[1]+b[1]); + const double newCenter=std::hypot(center[0],center[1]); + // Independent frequency-domain HRTF audit: REAR 2kHz old + // 60deg coherent stereo comb ~11.6dB, center is much clearer. + assert(newCenter>oldMean*2.5); + } + } + // The exact native ROOM ON path uses the SAME phase guard. Live room + // reflections and the FDN cannot silently drop the side content, exceed + // peak bounds or depend on host block partition. This is actual PCM. + { + auto live=std::make_unique(); + auto chunks=std::make_unique(); + Settings scene=s; + scene.startAzimuthDegrees=180.f; + scene.stereoSpreadDegrees=0.f; + scene.spatialMix=1.f; + scene.outputTrim=.65f; + scene.spacePreset=2; // 14.4m chamber, 5m source + scene.sourceDistanceMeters=5.f; + scene.roomAmount=.55f; + scene.ambience=.32f; + assert(valid(scene)); + assert(live->prepare(rate)&&chunks->prepare(rate)); + assert(live->setSettings(scene)&&chunks->setSettings(scene)); + constexpr int sceneFrames=16384; + std::vector l(sceneFrames),r(sceneFrames), + cl(sceneFrames),cr(sceneFrames); + for(int i=0;i( + std::sin(2.*3.14159265358979323846*440.*i/rate)); + l[i]=cl[i]=v;r[i]=cr[i]=-v; + } + live->process(l.data(),r.data(),sceneFrames); + for(int at=0;atprocess(cl.data()+at,cr.data()+at, + std::min(256,sceneFrames-at)); + double leftPower=0.,rightPower=0.; + for(int i=0;i=sceneFrames/2) { + leftPower+=static_cast(l[i])*l[i]; + rightPower+=static_cast(r[i])*r[i]; + } + } + assert(std::sqrt(leftPower/(sceneFrames/2))>.025); + assert(std::sqrt(rightPower/(sceneFrames/2))>.025); + } + // 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)); + // The original engine intentionally slews MIX edits for de-click; + // exact dry identity applies after the accepted transition settles. + std::array warmL{},warmR{}; + for(int k=0;k<48;++k) + dry->process(warmL.data(),warmR.data(),256); + 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())); diff --git a/tools/sonku_offline_listening.cpp b/tools/sonku_offline_listening.cpp index ae2697103..83ffe4bef 100644 --- a/tools/sonku_offline_listening.cpp +++ b/tools/sonku_offline_listening.cpp @@ -3,7 +3,11 @@ // 8D-SonKu measured HRTF core. No external music, WebAudio or second engine. // Generates lossless stereo WAVs for listening and blind front/rear evaluation. // Audio is NONPERSONALIZED MIT KEMAR, so perceptual externalization is UNPROVEN. +#if defined(SONKU_AB_BASELINE) +#include "../.baseline-sonku/engine/builtin_fx/sonku/SonKuSpatialCore.h" +#else #include "../engine/builtin_fx/sonku/SonKuSpatialCore.h" +#endif #include #include #include @@ -141,6 +145,43 @@ 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, + float stereoSpread=0.f) { + SonKuSpatialCore dsp; + Settings settings=fixed(azimuth); + settings.stereoSpreadDegrees=stereoSpread; + if(!dsp.prepare(rate)|| + !dsp.setSettings(settings)) + 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*(.12f*std::sin(2.f*pi*220.f*t)+ + .07f*std::sin(2.f*pi*330.f*t)+ + .04f*std::sin(2.f*pi*660.f*t)+ + .035f*std::sin(2.f*pi*2000.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