Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 53 additions & 0 deletions .github/workflows/sonku-native-windows.yml
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,60 @@ concurrency:
group: sonku-native-windows-${{ github.event.pull_request.number }}
cancel-in-progress: true
jobs:
scope:
name: Classify exact new source changes, avoid unrelated Windows repeats
runs-on: ubuntu-latest
timeout-minutes: 3
outputs:
compile: ${{ steps.delta.outputs.compile }}
steps:
- uses: actions/checkout@v4
with:
ref: ${{ github.event.pull_request.head.sha }}
fetch-depth: 2
- name: Compare exact PR synchronization range, fail open if unknown
id: delta
shell: bash
env:
ACTION: ${{ github.event.action }}
BEFORE: ${{ github.event.before }}
run: |
set -euo pipefail
# On initial or uncertain pushes always compile; never guess.
if [[ "$ACTION" != synchronize || ! "$BEFORE" =~ ^[0-9a-f]{40}$ || "$BEFORE" =~ ^0+$ ]]; then
echo "compile=true" >> "$GITHUB_OUTPUT"
echo "SONKU_WINDOWS_COMPILE_REASON=initial_or_unverifiable_delta"
exit 0
fi
if ! git cat-file -e "$BEFORE^{commit}" 2>/dev/null; then
if ! git fetch --no-tags --depth=1 origin "$BEFORE"; then
echo "compile=true" >> "$GITHUB_OUTPUT"
echo "SONKU_WINDOWS_COMPILE_REASON=missing_predecessor"
exit 0
fi
fi
if ! git diff --name-only --no-renames "$BEFORE" HEAD > "$RUNNER_TEMP/sonku-delta.txt"; then
echo "compile=true" >> "$GITHUB_OUTPUT"
exit 0
fi
cat "$RUNNER_TEMP/sonku-delta.txt"
# P7-only MIT measured data and six-plane lab files are compiled
# OUT of the real JUCE P6 build. They have their own Linux CI.
if grep -Eq '^((CMakeLists.txt)|(engine/builtin_fx/SonKuSpatialProcessor.h)|(engine/builtin_fx/sonku/(SonKuEarlyReflections|SonKuSpatialCore|SonKuStereoIntegrity|SonKuMeasuredHrir|SonKuMusicalReverb).h)|(tests/sonku_(native_state|p6_realtime_quality)_test.cpp)|(\.github/workflows/sonku-native-windows.yml))$' "$RUNNER_TEMP/sonku-delta.txt"; then
echo "compile=true" >> "$GITHUB_OUTPUT"
echo "SONKU_WINDOWS_COMPILE_REASON=real_native_adapter_change"
elif grep -Eq '^engine/builtin_fx/sonku/' "$RUNNER_TEMP/sonku-delta.txt" &&
grep '^engine/builtin_fx/sonku/' "$RUNNER_TEMP/sonku-delta.txt" |
grep -Ev '^engine/builtin_fx/sonku/(SonKuMeasuredHrir3D|SonKuVerticalImageSource).h$' >/dev/null; then
echo "compile=true" >> "$GITHUB_OUTPUT"
echo "SONKU_WINDOWS_COMPILE_REASON=unknown_sonku_native_header"
else
echo "compile=false" >> "$GITHUB_OUTPUT"
echo "SONKU_WINDOWS_COMPILE_REASON=research_or_docs_only"
fi
native-juce:
needs: scope
if: ${{ needs.scope.outputs.compile == 'true' }}
name: Windows MSVC SonKu native adapter + core (opt-in ON)
runs-on: windows-2022
timeout-minutes: 20
Expand Down
67 changes: 67 additions & 0 deletions .github/workflows/sonku-p7-research.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
name: SonKu P7 measured-elevation research (scoped native)
# Compile licensed multi-elevation KEMAR ONLY in the research tests.
# Production DSP, GUI, Harmony CI, installer and full JUCE are not touched.
on:
pull_request:
types: [opened, reopened, synchronize]
paths:
- 'engine/builtin_fx/sonku/**'
- 'tests/sonku_p7_*'
- 'tools/sonku_offline_listening.cpp'
- 'tools/sonku_p7_cpu.cpp'
- '.github/workflows/sonku-p7-research.yml'
permissions:
contents: read
concurrency:
group: sonku-p7-${{ github.event.pull_request.number }}
cancel-in-progress: true
jobs:
six-surface:
name: P7 full measured KEMAR, 6 planes, native stereo WAV and CPU
runs-on: ubuntu-latest
timeout-minutes: 9
steps:
- uses: actions/checkout@v4
with:
ref: ${{ github.event.pull_request.head.sha }}
- name: Proven P6 LIGHT/default contract and P5 stale-history regression
run: |
g++ -std=c++20 -O2 -Wall -Wextra -pedantic tests/sonku_p6_realtime_quality_test.cpp -o /tmp/p6
/tmp/p6
g++ -std=c++20 -O2 -Wall -Wextra -pedantic tests/sonku_p5_room_reactivation_test.cpp -o /tmp/p5
/tmp/p5
- name: Confirm deterministic MIT bank extractor syntax without network
run: python -m py_compile scripts/generate_sonku_measured_hrir3d.py
- name: Preserve all prior P0-P4 source audio invariants on unmodified production profile
run: |
set -euo pipefail
for source in sonku_spatial_core_test sonku_multiband_phase_test sonku_directional_reflections_test sonku_p3_spread_zero_fusion_test sonku_p4_contiguous_reflections_test; do
g++ -std=c++20 -O2 -Wall -Wextra -pedantic tests/${source}.cpp -o "/tmp/${source}"
"/tmp/${source}"
done
g++ -std=c++20 -O2 -Wall -Wextra -pedantic tests/sonku_hrir_spectral_audit.cpp -o /tmp/sonku-p7-spectral
mkdir -p sonku-p7-evidence
/tmp/sonku-p7-spectral > sonku-p7-evidence/P7-LEGACY-KEMAR-380-POINTS.csv
test "$(($(wc -l < sonku-p7-evidence/P7-LEGACY-KEMAR-380-POINTS.csv)-1))" -eq 380
- name: P7 measured 14-elevation KEMAR + native source six-plane PCM
run: |
g++ -std=c++20 -O2 -Wall -Wextra -pedantic -DSONKU_P7_MEASURED_ELEVATION_RESEARCH=1 tests/sonku_p7_six_surface_test.cpp -o /tmp/p7
/tmp/p7
- name: Four matched P6 four-wall versus P7 six-plane realtime ROOM WAV pairs
run: |
g++ -std=c++20 -O2 -Wall -Wextra -pedantic -DSONKU_P7_MEASURED_ELEVATION_RESEARCH=1 tools/sonku_offline_listening.cpp -o /tmp/p7-render
mkdir -p sonku-p7-evidence
/tmp/p7-render sonku-p7-evidence --p7-six-surface-only
python tests/sonku_p7_six_surface_audio_audit.py sonku-p7-evidence
- name: Informational CPU 1/2/4 inserts P6 versus P7 48k/128
run: |
g++ -std=c++20 -O2 -Wall -Wextra -pedantic -DSONKU_P7_MEASURED_ELEVATION_RESEARCH=1 tools/sonku_p7_cpu.cpp -o /tmp/p7-bench
/tmp/p7-bench | tee sonku-p7-evidence/SONKU-P7-CPU-REPORT.txt
- name: Upload 8 matched lossless WAV and JSON/CPU evidence
if: ${{ always() }}
uses: actions/upload-artifact@v4
with:
name: SonKu-P7-Measured-Six-Surface-${{ github.run_id }}
path: sonku-p7-evidence/*
if-no-files-found: ignore
retention-days: 14
106 changes: 106 additions & 0 deletions docs/SONKU_P7_SIX_SURFACE_MEASURED_ELEVATION_20261114.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,106 @@
# SonKu P7.0 — six-surface measured-elevation KEMAR reflection pilot

14 November 2026 · research branch stacked on #678 → #674 · **NOT public/realtime-approved**.

## Scope and source

The existing P6 native direct HRTF, four-wall image sources, P0/P1 stereo
integrity, P5 fresh-history guard, .smix v1/v2 and UI are NOT changed in
the shipping default. The new internal `SixSurfaceKemarResearch` profile
can only be prepared in a build compiled explicitly with
`SONKU_P7_MEASURED_ELEVATION_RESEARCH=1`. Public JUCE release binaries
do not define this flag; not a GUI/session parameter.

A fully measured MIT KEMAR compact normal-pinna bank is pinned in
`SonKuMeasuredHrir3D.h` for 44.1k (128 zero-padded to 140 taps) and
48k (140 taps): 14 elevations **−40° through +90°**, with original
azimuths for EACH elevation (not fake uniform 5°). 368 original
measurement pairs per sample rate, excluding duplication of the existing
0° bank. Negative azimuths swap ears. 0° retains the original bank
bit-for-bit; upper and lower elevation interpolate actual HRIR taps.
Source provenance: MIT HRTF C Library, original KEMAR Gardner/Martin
measurements compiled by Aristotel Digenis under MIT, source blobs
`5e5bcac17b0d59f1b8e7fee04b380170f7d521d2` (44.1k),
`39931add922dad4687e572059bc157b124926944` (48k),
https://github.com/jhonmark/mit-hrtf-lib/tree/master/source/normal .
Retain existing `docs/THIRD_PARTY_8D_SONKU_HRTF.md` attribution.
No Dear Reality proprietary IR, HRTF or DSP is used.

The 3D source-image geometry adds precisely TWO first-order reflection
paths: floor z = −sourceHeight − listenerHeight and
ceiling z = 2×height − sourceHeight − listenerHeight. It calculates
physical propagation distance, delay relative to direct path, azimuth,
elevation, measured-ear 140-tap reflection FIR and 1/path pressure.
Four original walls, native smoothing, P3 zero-spread fusion, P4 contiguous
ring reads and P5 epoch guards are reused, not duplicated.

Source height is **at listener height** until a proper measured
direct-source elevation HRTF and UI contract exist. This pilot tests
elevation of reflected arrivals; it is NOT true full XYZ direct placement.
Measured −40° is the lower dataset limit: more-negative arrivals are
clamped to −40° rather than unvalidated HRTF extrapolation. Front/rear
externalization, diffuse field and 3D position perception require
loudness-matched headphone listening with multiple people.

## Real-time discipline

- When the P7 macro is absent, 3D data and 2 extra wall processors are
compiled OUT, preserving the public P6 legacy 4-wall renderer.
- Prepared profile is immutable across audio callbacks; illegal/unsupported
selection fails closed. The first-image six-plane calculation runs on
the existing 64-frame geometry cadence, not per audio sample.
- No dynamic allocation, FFT, lazy file reads, lock, new DSP worker,
second PCM authority or listener UI placeholder.
- Same native accepted ROOM controls and audio graph; not another VST3.
Extra two 140-tap reflection FIRs cost CPU. Measure p99, concurrent
instances and ASIO/XRUN before considering realtime deployment.

## Gates

1. Native 44.1/48k measured-ear mirror, 0° exact original bank,
positive and negative spectral elevation differences, physically
causal FLOOR/CEILING delays and height validation.
2. P6 vs P7 same-source active native ROOM with 0/60 stereo spread,
64/257 partition parity, no early ghost, finite peak and nonzero
reflection-only difference.
3. Source-matched lossless FRONT/REAR WAV comparisons + objective metrics;
do not call a measurable difference an audible improvement.
4. Scoped Linux CI for P0–P7 and focused Windows opt-in JUCE tests
remain separate. Do not turn P7 on in public installer or main.

Further qualification needed: true XYZ direct interpolation,
headphone individualization, actual Windows ASIO multi-instance p99,
externalization/tonal listening and owner approval.

## P7 fast-lane observed CPU (Linux only)

Exact first P7 [Action #43555803671](https://github.com/masarray/arsonmix/actions/runs/43555803671) SUCCESS and WAV [artifact #14098845051](https://github.com/masarray/arsonmix/actions/runs/43555803671/artifacts/14098845051).
For 48k/128, 1 second synthetic PCM, Linux hosted runner: six-surface
4-insert/60° callback **p99 2581.884µs**, or **96.8% of the 2666.7µs
buffer period**, compared with roughly 1.4× P6 directional CPU in
same-runner paired modes. These are explicitly **NOT Windows ASIO
measurements** and are far too close to the deadline to justify enabling
P7 across several inserts. Do not add a naive per-buffer auto quality switch
or arbitrary CI wallclock threshold. The native host needs an explicit
preflight measured/admitted budget before P7 could be shipped.

This experiment now additionally tests P5 stale vertical FIR history on
ROOM ON → OFF while old PCM is present → ON in silence, then a new
causal impulse, at 44.1 and 48k. Whole engine must remain allocation-free.

Legacy P0–P4 exact native source tests and the original 380-point KEMAR
spectral audit now also run in P7's *dedicated* Linux gate, with P7
macro deliberately disabled. That is the negative-control guarantee:
shipping SonKu HRTF/ROOM/phase invariants cannot be silently changed
by the experimental elevation implementation.

## Spectral / interaural quality evidence

The P7 same-source WAV analyzer now performs native offline Goertzel
measurements over one steady 1-second interval for the original 220,
660, 940, 3200 and 4700 Hz instruments. Each FRONT/REAR and 0/60°
pair reports P7-versus-P6 **per-ear magnitude changes**, interaural
level difference and interaural phase difference. Changes of ≥1.5 dB
are recorded as *engineering listening-review flags*, not CI failures
or universal audibility thresholds. These are necessary sanity checks
against tonal damage; **not a human naturalness/externalization rating**.
4 changes: 3 additions & 1 deletion docs/THIRD_PARTY_8D_SONKU_HRTF.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,9 @@ Date 2026-11-12. Source: 8D-SonKu `SonKuMeasuredHrir.h`.
- Original HRIR measurements: Bill Gardner and Keith Martin, MIT Media Laboratory, 1994. MIT KEMAR (0° elevation).
- MIT Media Laboratory terms are reported in the OpenAL Soft MIT_KEMAR.def: free of charge without usage restrictions provided original authors are cited. https://github.com/kcat/openal-soft/blob/master/utils/MIT_KEMAR.def
- C table format and 44.1/48 kHz processed 128/140-tap values derived from **Aristotel Digenis, MIT HRTF C Library**, https://github.com/jhonmark/mit-hrtf-lib (MIT license; copyright 2007 Aristotel Digenis; repository LICENSE copyright 2014 greekgoddj).
- Source path: `source/normal/mit_hrtf_normal_44100.h` and `source/normal/mit_hrtf_normal_48000.h`; only the 0° elevation 0–180° at 5° spacing; 44.1 kHz rows zero-padded to 140; negative 180..360 by ear symmetry.
- Existing public source path: `source/normal/mit_hrtf_normal_44100.h` and `source/normal/mit_hrtf_normal_48000.h`; only the 0° elevation 0–180° at 5° spacing; 44.1 kHz rows zero-padded to 140; negative 180..360 by ear symmetry.
- **P7 research-only** `engine/builtin_fx/sonku/SonKuMeasuredHrir3D.h` additionally copies the original MIT-licensed measurements at **14 elevations (−40..+90°)** with the exact upstream nonuniform azimuth grids (368 measured angle pairs/sample-rate, including 0° reused from the native public bank). Upstream Git blobs `5e5bcac17b0d59f1b8e7fee04b380170f7d521d2` (44.1k) and `39931add922dad4687e572059bc157b124926944` (48k). The extractor `scripts/generate_sonku_measured_hrir3d.py` regenerates this checked-in bank from locally supplied verified source headers; no runtime/network dataset fetching or proprietary vendor coefficients.
- The extra P7 measured bank compiles only with `SONKU_P7_MEASURED_ELEVATION_RESEARCH=1`. No P7 installer redistribution is authorized yet; retain this MIT attribution and all third-party notices in any future test package.
- **These are general-purpose nonindividualized HRIRs**. Front/rear externalization is NOT guaranteed. No dearVR code or IR is used.

MIT License (MIT)
Expand Down
Loading
Loading