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
104 changes: 104 additions & 0 deletions .github/workflows/sonku-p72-native-xyz.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,104 @@
name: SonKu P7.2 native XYZ ACK and v3 state — isolated
# No installer / full mixer compile. JUCE source adapter and pure C++ PCM.
# Production remains LIGHT and SONK v2; P7.2 opt-in flag OFF by default.
on:
pull_request:
types: [opened, reopened, synchronize, ready_for_review]
paths:
- 'engine/builtin_fx/SonKuSpatialProcessor.h'
- 'engine/builtin_fx/sonku/**'
- 'tests/sonku_p72_*'
- 'CMakeLists.txt'
- '.github/workflows/sonku-p72-native-xyz.yml'
permissions:
contents: read
concurrency:
group: sonku-p72-native-${{ github.event.pull_request.number }}
cancel-in-progress: true
jobs:
source:
name: Pure native 44.1/48k PCM, SPSC-safe XYZ edit and P6/P7.1 parity
runs-on: ubuntu-latest
timeout-minutes: 7
steps:
- uses: actions/checkout@v4
with:
ref: ${{ github.event.pull_request.head.sha }}
- name: Exact PR commit fingerprint
shell: bash
env:
EXPECTED: ${{ github.event.pull_request.head.sha }}
run: |
test "$(git rev-parse HEAD)" = "$EXPECTED"
echo "SONKU_P72_EXACT_SHA=$EXPECTED"
- name: Compile and execute original default native PCM contracts
run: |
set -euo pipefail
g++ -std=c++20 -O2 -Wall -Wextra -Werror -pedantic tests/sonku_p6_realtime_quality_test.cpp -o /tmp/sonku-p6
/tmp/sonku-p6
g++ -std=c++20 -O2 -Wall -Wextra -Werror -pedantic -DSONKU_P7_MEASURED_ELEVATION_RESEARCH=1 -DSONKU_P71_DIRECT_XYZ_RESEARCH=1 tests/sonku_p71_xyz_direct_test.cpp -o /tmp/sonku-p71
/tmp/sonku-p71
- name: P7.2 live native ROOM edit + complete measured direct PCM
run: |
set -euo pipefail
g++ -std=c++20 -O2 -Wall -Wextra -Werror -pedantic \
-DSONKU_P7_MEASURED_ELEVATION_RESEARCH=1 \
-DSONKU_P71_DIRECT_XYZ_RESEARCH=1 \
-DSONKU_P72_NATIVE_XYZ_RT=1 \
tests/sonku_p72_realtime_xyz_test.cpp -o /tmp/sonku-p72
/tmp/sonku-p72
windows-juce:
name: Windows MSVC JUCE real native PCM→ACK→v3/legacy state
runs-on: windows-2022
timeout-minutes: 21
steps:
- uses: actions/checkout@v4
with:
ref: ${{ github.event.pull_request.head.sha }}
- name: Exact immutable source SHA before compilation
shell: pwsh
env:
EXPECTED: ${{ github.event.pull_request.head.sha }}
run: |
$sha = (& git rev-parse HEAD).Trim()
if($LASTEXITCODE -ne 0 -or $sha -ne $env:EXPECTED) { throw "SONKU_P72_SHA_MISMATCH:$sha" }
Write-Host "SONKU_P72_WINDOWS_SOURCE_SHA=$sha"
- uses: actions/checkout@v4
with:
repository: juce-framework/JUCE
ref: 8.0.15
path: third_party/JUCE
persist-credentials: false
- name: Pinned WebView2 CMake configure SDK (no installer)
shell: pwsh
run: |
nuget install Microsoft.Web.WebView2 -Version 1.0.3485.44 -OutputDirectory .deps -NonInteractive
if($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
- name: Configure research option explicitly ON; verify only required targets
shell: pwsh
run: |
cmake -S . -B build-sonku-p72 -G "Visual Studio 17 2022" -A x64 `
-DJUCE_ROOT="${{ github.workspace }}/third_party/JUCE" `
-DJUCE_WEBVIEW2_PACKAGE_LOCATION="${{ github.workspace }}/.deps" `
-DARMIX_SONKU_EXPERIMENTAL_NATIVE_XYZ_RT=ON -DBUILD_TESTING=ON
if($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
$tests = (& ctest --test-dir build-sonku-p72 -C Release --show-only=json-v1 | Out-String | ConvertFrom-Json)
if($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
$found = @($tests.tests | ForEach-Object { $_.name })
foreach($name in @('NativeSonKuP72AtomicXyzLiveEditSource',
'NativeSonKuP72JuceV3XyzLiveAckV1V2Restore',
'NativeSonKuSessionV1V2AndAudioAppliedAck')) {
if($name -notin $found) { throw "SONKU_P72_MISSING_CTEST:$name" }
}
- name: Build only two P72 source/JUCE targets + original light regression
shell: pwsh
run: |
cmake --build build-sonku-p72 --config Release --parallel 2 --target ARMixSonKuP72SourceTests ARMixSonKuP72NativeTests ARMixSonKuNativeStateTests
if($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
- name: Run native v3 ACK and v1/v2 corruption/restore CTests
shell: pwsh
run: |
ctest --test-dir build-sonku-p72 -C Release --output-on-failure `
-R '^NativeSonKu(P72AtomicXyzLiveEditSource|P72JuceV3XyzLiveAckV1V2Restore|SessionV1V2AndAudioAppliedAck)$'
if($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
Write-Host 'SONKU_P72_JUCE_WINDOWS_3_CTESTS_PASS_NO_PHYSICAL_ASIO'
42 changes: 41 additions & 1 deletion CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,12 @@ project(ARMixConsole VERSION 0.5.0 LANGUAGES C CXX)
option(ARMIX_SONKU_EXPERIMENTAL_DIRECTIONAL_RT
"Enable unqualified SonKu full KEMAR directional reflections on the native JUCE callback"
OFF)
# Native XYZ/ACK v3: isolated research switch, OFF in every public installer.
# This implies the measured KEMAR full-elevation research tables explicitly
# and never changes the ordinary 46-byte SonKu v2 native FX ABI.
option(ARMIX_SONKU_EXPERIMENTAL_NATIVE_XYZ_RT
"Enable P7.2 unqualified native real-time XYZ/v3 research adapter"
OFF)
set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

Expand Down Expand Up @@ -197,7 +203,11 @@ target_compile_definitions(ARMixConsole PRIVATE
JUCE_APPLICATION_VERSION_STRING="${ARMIX_APP_VERSION}"
ARMIX_BUILD_SOURCE_SHA="${ARMIX_BUILD_SOURCE_SHA}"
ARMIX_GFX_EMBED_PNG_SKINS=1
$<$<BOOL:${ARMIX_SONKU_EXPERIMENTAL_DIRECTIONAL_RT}>:ARMIX_SONKU_EXPERIMENTAL_DIRECTIONAL_RT=1>)
$<$<BOOL:${ARMIX_SONKU_EXPERIMENTAL_DIRECTIONAL_RT}>:ARMIX_SONKU_EXPERIMENTAL_DIRECTIONAL_RT=1>
$<$<BOOL:${ARMIX_SONKU_EXPERIMENTAL_NATIVE_XYZ_RT}>:ARMIX_SONKU_EXPERIMENTAL_NATIVE_XYZ_RT=1>
$<$<BOOL:${ARMIX_SONKU_EXPERIMENTAL_NATIVE_XYZ_RT}>:SONKU_P7_MEASURED_ELEVATION_RESEARCH=1>
$<$<BOOL:${ARMIX_SONKU_EXPERIMENTAL_NATIVE_XYZ_RT}>:SONKU_P71_DIRECT_XYZ_RESEARCH=1>
$<$<BOOL:${ARMIX_SONKU_EXPERIMENTAL_NATIVE_XYZ_RT}>:SONKU_P72_NATIVE_XYZ_RT=1>)
if(WIN32)
# Windows retains its proven ASIO-first / WASAPI / static WebView2 distribution.
# Never link Windows loader or sound APIs into macOS/Linux builds.
Expand Down Expand Up @@ -285,6 +295,36 @@ if(BUILD_TESTING)
endif()
add_test(NAME NativeSonKuSessionV1V2AndAudioAppliedAck
COMMAND ARMixSonKuNativeStateTests)

# P7.2 native real-time 3D is never required in production: its test
# binaries, large measured elevation bank and v3 schema are built ONLY
# when explicitly opted in. Reuse the exact existing JUCE processor.
if(ARMIX_SONKU_EXPERIMENTAL_NATIVE_XYZ_RT)
add_executable(ARMixSonKuP72SourceTests
tests/sonku_p72_realtime_xyz_test.cpp)
target_compile_features(ARMixSonKuP72SourceTests PRIVATE cxx_std_20)
target_compile_definitions(ARMixSonKuP72SourceTests PRIVATE
SONKU_P7_MEASURED_ELEVATION_RESEARCH=1
SONKU_P71_DIRECT_XYZ_RESEARCH=1
SONKU_P72_NATIVE_XYZ_RT=1)
add_test(NAME NativeSonKuP72AtomicXyzLiveEditSource
COMMAND ARMixSonKuP72SourceTests)

juce_add_console_app(ARMixSonKuP72NativeTests
PRODUCT_NAME "ArSonMix SonKu P72 Native XYZ Tests")
target_sources(ARMixSonKuP72NativeTests PRIVATE
tests/sonku_p72_native_juce_xyz_test.cpp)
target_link_libraries(ARMixSonKuP72NativeTests PRIVATE
juce::juce_audio_processors juce::juce_recommended_config_flags)
target_compile_features(ARMixSonKuP72NativeTests PRIVATE cxx_std_20)
target_compile_definitions(ARMixSonKuP72NativeTests PRIVATE
ARMIX_SONKU_EXPERIMENTAL_NATIVE_XYZ_RT=1
SONKU_P7_MEASURED_ELEVATION_RESEARCH=1
SONKU_P71_DIRECT_XYZ_RESEARCH=1
SONKU_P72_NATIVE_XYZ_RT=1)
add_test(NAME NativeSonKuP72JuceV3XyzLiveAckV1V2Restore
COMMAND ARMixSonKuP72NativeTests)
endif()
# Pure control-plane first-run routing selection: no JUCE, drivers,
# WASAPI activation or callback dependencies. Full Windows CTest gate.
add_executable(ARMixFirstRunEndpointPolicyTests
Expand Down
58 changes: 58 additions & 0 deletions docs/SONKU_P72_NATIVE_XYZ_ACK_V3_RESEARCH_20261114.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
# SonKu P7.2 — research-only realtime JUCE XYZ native ACK and v3 state

14 November 2026 · stacked on P7.1 #681 → P7 #679 → P6 #678.
**Research native host feature, not public 3D UX / ASIO / dearVR parity.**

## Audited architecture

The existing SonKu `Settings` POD, per-instance native SPSC queue, JUCE
`consumeRealtimeEdits`, completion ACK, and `SonKuSpatialCore` are the
**single** audio/control source of truth; no second processor, WebAudio DSP,
worker thread, new audio callback, or hidden FX identity.

When **both** the project option
`ARMIX_SONKU_EXPERIMENTAL_NATIVE_XYZ_RT=ON` (default OFF) and CMake's
specific source targets are built, the JUCE native processor prepares
`SixSurfaceKemarResearch`, compiles the independent MIT KEMAR 3D
measured bank, and extends the existing SonKu POD control with the
research-only `directElevationDegrees` field. This parameter is
**validated in combination with the same ROOM/distance settings**, accepted
by the native callback as one transaction, and included in completion ACK
only after audio applies it. The direct HRIR and six physical reflected
paths slew on existing geometry clocks; no callback allocation or
`prepare()`/history reset during a live edit. 3D edits are rejected if
they violate room clearance or cannot fit the delay ring, preventing
silent clamping of impossible geometry or partial UX state.

The experimental native FX state adds a single float to the existing
SONK v2 payload, making **SONK v3 / 50 bytes**. The exact older binary
v2 / 46-byte and v1 / 30-byte states are still accepted in the
experimental JUCE adapter, defaulting direct elevation to 0°. A
normal/public SonKu binary **still writes v2 46 bytes**, and does not
silently attempt to interpret experimental v3. V3 is not automatically
published in the `.smix` GUI or FX rack; an approved user-facing state/
UI/host protocol migration requires separate evidence and release.

This pilot is also protected against an old-engine bug where a
`setSettings` failure could change the orbit phase before declining
a ROOM edit. A rejected P7.2 edit must preserve accepted state and
azimuth. Device `prepareToPlay(44100/48000, frames)` reuses the
approved elevation. Compiling with the switch OFF emits **none** of the
extra KEMAR 3D tables and retains original v1/v2 persistence.

## Test and release gates

- Linux no-JUCE source CTests: 44.1/48k, 0→+25→−25° live edit on the same
core; 64/257 chunk parity, moving azimuth continuity and anti-phase
musical PCM, finite/headroom, no invalid state or rejected-phase movement.
- Real MSVC JUCE adapter: queue returns QUEUED, processBlock applies,
completion readback is authoritative, rejected geometry never ACKs,
experimental 50-byte v3 and 46/30-byte v2/v1 restorable, corrupt/truncated
state fails without accepting partial data, driver-rate reprepare works.
- All tests target only specific native source binaries with pinned
JUCE 8.0.15 and WebView2 configure headers; no full mixer/installer,
no Vocal Harmony CI, no heavy UI snapshot jobs.
- These are host/native tests, **not a physical ASIO 64/128/256 XRUN test**
or approved GUI click/end-to-end WIRE route. Actual board/real music
listening, multiple inserts, licensing and production UI remain blocked
on Issue #683.
40 changes: 33 additions & 7 deletions engine/builtin_fx/SonKuSpatialProcessor.h
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,10 @@ class SonKuSpatialProcessor final : public juce::AudioProcessor,
void prepareToPlay(double rate,int) override {
// P6 is opt-in at build time on an unreleased test binary only.
// The render profile is immutable across native audio callbacks.
#if defined(ARMIX_SONKU_EXPERIMENTAL_DIRECTIONAL_RT) && ARMIX_SONKU_EXPERIMENTAL_DIRECTIONAL_RT
#if defined(ARMIX_SONKU_EXPERIMENTAL_NATIVE_XYZ_RT) && ARMIX_SONKU_EXPERIMENTAL_NATIVE_XYZ_RT
// Only an explicit native experimental build prepares six surfaces.
constexpr auto profile=armix::sonku::SonKuReflectionProfile::SixSurfaceKemarResearch;
#elif defined(ARMIX_SONKU_EXPERIMENTAL_DIRECTIONAL_RT) && ARMIX_SONKU_EXPERIMENTAL_DIRECTIONAL_RT
constexpr auto profile=armix::sonku::SonKuReflectionProfile::DirectionalKemar;
#else
constexpr auto profile=armix::sonku::SonKuReflectionProfile::Lightweight;
Expand Down Expand Up @@ -92,7 +95,11 @@ class SonKuSpatialProcessor final : public juce::AudioProcessor,
void getStateInformation(juce::MemoryBlock& dest) override {
juce::MemoryOutputStream out(dest,false);
out.writeInt(0x534F4E4B); // SONK
#if defined(ARMIX_SONKU_EXPERIMENTAL_NATIVE_XYZ_RT) && ARMIX_SONKU_EXPERIMENTAL_NATIVE_XYZ_RT
out.writeInt(3);
#else
out.writeInt(2);
#endif
out.writeFloat(accepted_.startAzimuthDegrees);
out.writeFloat(accepted_.revolutionSeconds);
out.writeFloat(accepted_.stereoSpreadDegrees);
Expand All @@ -104,15 +111,30 @@ class SonKuSpatialProcessor final : public juce::AudioProcessor,
out.writeFloat(accepted_.sourceDistanceMeters);
out.writeFloat(accepted_.roomAmount);
out.writeFloat(accepted_.ambience);
#if defined(ARMIX_SONKU_EXPERIMENTAL_NATIVE_XYZ_RT) && ARMIX_SONKU_EXPERIMENTAL_NATIVE_XYZ_RT
out.writeFloat(accepted_.directElevationDegrees);
#endif
}
bool restoreUnpublishedState(const void* data,int size) {
if(published_||!data||(size!=30&&size!=46)||
if(published_||!data||
#if defined(ARMIX_SONKU_EXPERIMENTAL_NATIVE_XYZ_RT) && ARMIX_SONKU_EXPERIMENTAL_NATIVE_XYZ_RT
(size!=30&&size!=46&&size!=50)||
#else
(size!=30&&size!=46)||
#endif
!queue_.empty()||!complete_.empty())return false;
juce::MemoryInputStream in(data,static_cast<std::size_t>(size),false);
if(in.readInt()!=0x534F4E4B)return false;
const int version=in.readInt();
if((version!=1&&version!=2)||
(version==1&&size!=30)||(version==2&&size!=46))return false;
if((version!=1&&version!=2
#if defined(ARMIX_SONKU_EXPERIMENTAL_NATIVE_XYZ_RT) && ARMIX_SONKU_EXPERIMENTAL_NATIVE_XYZ_RT
&&version!=3
#endif
) || (version==1&&size!=30)||(version==2&&size!=46)
#if defined(ARMIX_SONKU_EXPERIMENTAL_NATIVE_XYZ_RT) && ARMIX_SONKU_EXPERIMENTAL_NATIVE_XYZ_RT
||(version==3&&size!=50)
#endif
)return false;
armix::sonku::Settings next{};
next.startAzimuthDegrees=in.readFloat();
next.revolutionSeconds=in.readFloat();
Expand All @@ -123,14 +145,18 @@ class SonKuSpatialProcessor final : public juce::AudioProcessor,
if(moving>1||clockwise>1)return false;
next.moving=moving!=0;
next.clockwise=clockwise!=0;
if(version==2) {
if(version>=2) {
next.spacePreset=in.readInt();
next.sourceDistanceMeters=in.readFloat();
next.roomAmount=in.readFloat();
next.ambience=in.readFloat();
}
// Old v1 .smix restores to HRTF-only. New v2 carries the acoustic
// scene, but never allows malformed/partial state into live PCM.
#if defined(ARMIX_SONKU_EXPERIMENTAL_NATIVE_XYZ_RT) && ARMIX_SONKU_EXPERIMENTAL_NATIVE_XYZ_RT
if(version==3)next.directElevationDegrees=in.readFloat();
#endif
// v1 OFF, v2 original scene; experimental v3 includes direct
// elevation, and is rejected by ordinary public v2 builds.
// Never accept a partial or malformed native FX state.
if(!in.isExhausted())return false;
if(!armix::sonku::valid(next))return false;
if(ready_&&!core_.setSettings(next))return false;
Expand Down
Loading
Loading