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
72 changes: 69 additions & 3 deletions .github/workflows/harmony-fast-dsp.yml
Original file line number Diff line number Diff line change
@@ -1,21 +1,73 @@
name: Harmony native DSP fast verification
name: Vocal Harmony plugin DSP (scoped)
# Only code/tests of the built-in Vocal Harmony FX may start this workflow.
# In particular, shared CMakeLists.txt, Player, mixer, generic GUI and CI
# maintenance must never trigger an unrelated Vocal Harmony failure.
on:
pull_request:
types: [opened, reopened, synchronize]
paths:
- 'engine/builtin_fx/Harmony*.h'
- 'engine/builtin_fx/ChannelHarmonyProcessor.h'
- 'tests/harmony*.cpp'
- 'tools/harmony_offline_ab.cpp'
- 'CMakeLists.txt'
- '.github/workflows/harmony-fast-dsp.yml'
- 'site/preview-v2/assets/mixer-native-harmony.js'
- 'tests/native_harmony_assembly_test.py'
- 'tests/approved_native_harmony_smoke.py'
permissions:
contents: read
concurrency:
group: harmony-fast-${{ github.event.pull_request.number }}
cancel-in-progress: true
jobs:
scope:
name: Check Vocal Harmony files changed in this PR update
runs-on: ubuntu-latest
timeout-minutes: 3
outputs:
dsp: ${{ steps.scope.outputs.dsp }}
ui: ${{ steps.scope.outputs.ui }}
steps:
- uses: actions/checkout@v4
with:
ref: ${{ github.event.pull_request.head.sha }}
fetch-depth: 2
- name: Classify only actual Vocal Harmony source changes
id: scope
shell: bash
env:
PR_ACTION: ${{ github.event.action }}
PR_BEFORE: ${{ github.event.before }}
PR_BASE: ${{ github.event.pull_request.base.sha }}
run: |
# GitHub 'paths' looks at the entire PR diff. If a mixed PR
# changes unrelated files later, do not re-run the plugin DSP.
# Prefer the exact synchronize-before SHA to handle multi-commit
# pushes; on missing/unfetchable evidence, fail OPEN for safety.
BASE="$PR_BASE"
if [[ "$PR_ACTION" == "synchronize" && "$PR_BEFORE" =~ ^[a-fA-F0-9]{40}$ && ! "$PR_BEFORE" =~ ^0+$ ]]; then
BASE="$PR_BEFORE"
fi
if [[ ! "$BASE" =~ ^[a-fA-F0-9]{40}$ ]]; then
printf 'dsp=true\nui=true\n' >> "$GITHUB_OUTPUT"
exit 0
fi
if ! git cat-file -e "$BASE^{commit}" 2>/dev/null; then
if ! git fetch --no-tags --depth=1 origin "$BASE"; then
printf 'dsp=true\nui=true\n' >> "$GITHUB_OUTPUT"
exit 0
fi
fi
if ! git diff --name-only --no-renames "$BASE" HEAD > "$RUNNER_TEMP/vocal-harmony-diff.txt"; then
printf 'dsp=true\nui=true\n' >> "$GITHUB_OUTPUT"
exit 0
fi
node scripts/vocal_harmony_ci_scope.mjs < "$RUNNER_TEMP/vocal-harmony-diff.txt" >> "$GITHUB_OUTPUT"
echo "VOCAL_HARMONY_CHANGED_FILES:"
cat "$RUNNER_TEMP/vocal-harmony-diff.txt"
harmony-cpp:
name: Native DSP compile and PCM regression (Linux, no JUCE)
needs: scope
if: ${{ needs.scope.outputs.dsp == 'true' }}
runs-on: ubuntu-latest
timeout-minutes: 7
steps:
Expand All @@ -38,3 +90,17 @@ jobs:
run: |
g++ -std=c++20 -O2 -Wall -Wextra tools/harmony_offline_ab.cpp -o /tmp/arson-harmony-ab
/tmp/arson-harmony-ab --self-test
harmony-ui:
name: Vocal Harmony editor syntax and approved UI contract (no Chromium)
needs: scope
if: ${{ needs.scope.outputs.ui == 'true' }}
runs-on: ubuntu-latest
timeout-minutes: 5
steps:
- uses: actions/checkout@v4
with:
ref: ${{ github.event.pull_request.head.sha }}
- name: Plugin editor JS and native bridge/ACK contract
run: |
node --check site/preview-v2/assets/mixer-native-harmony.js
python tests/native_harmony_assembly_test.py
127 changes: 127 additions & 0 deletions .github/workflows/sonku-native-windows.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,127 @@
name: SonKu native JUCE Windows (focused experimental quality)
# Verify the REAL JUCE adapter in a single targeted opt-in build.
# No full mixer executable, installer, Chromium, hardware ASIO or Vocal Harmony.
on:
pull_request:
types: [opened, reopened, synchronize, ready_for_review]
paths:
- 'engine/builtin_fx/sonku/**'
- 'engine/builtin_fx/SonKuSpatialProcessor.h'
- 'tests/sonku_native_state_test.cpp'
- 'tests/sonku_p6_realtime_quality_test.cpp'
- '.github/workflows/sonku-native-windows.yml'
permissions:
contents: read
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
steps:
- uses: actions/checkout@v4
with:
ref: ${{ github.event.pull_request.head.sha }}
- name: Verify immutable PR head
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_SHA_MISMATCH expected=$env:EXPECTED actual=$sha"
}
Write-Host "SONKU_QUALIFICATION_SOURCE_SHA=$sha"
- uses: actions/checkout@v4
with:
repository: juce-framework/JUCE
ref: 8.0.15
path: third_party/JUCE
persist-credentials: false
- name: Provide pinned WebView2 CMake 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 only CTest catalog with experimental P6 ON
shell: pwsh
run: |
cmake -S . -B build-sonku-p6 -G "Visual Studio 17 2022" -A x64 `
-DJUCE_ROOT="${{ github.workspace }}/third_party/JUCE" `
-DJUCE_WEBVIEW2_PACKAGE_LOCATION="${{ github.workspace }}/.deps" `
-DARMIX_SONKU_EXPERIMENTAL_DIRECTIONAL_RT=ON -DBUILD_TESTING=ON
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
$result = (& ctest --test-dir build-sonku-p6 -C Release --show-only=json-v1 | Out-String | ConvertFrom-Json)
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
$found = @($result.tests | ForEach-Object { $_.name })
foreach($name in @('NativeSonKuSessionV1V2AndAudioAppliedAck',
'NativeSonKuP6PreparedRoomDirectionalAndChunkParity')) {
if($name -notin $found) { throw "SONKU_CTEST_TARGET_NOT_REGISTERED:$name" }
}
- name: Build ONLY two SonKu source targets (no installer/full app)
shell: pwsh
run: |
cmake --build build-sonku-p6 --config Release --parallel 2 --target ARMixSonKuNativeStateTests ARMixSonKuP6PreparedTests
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
- name: Execute native JUCE acceptance, PCM and state CTests
shell: pwsh
run: |
ctest --test-dir build-sonku-p6 -C Release --output-on-failure `
-R '^NativeSonKu(SessionV1V2AndAudioAppliedAck|P6PreparedRoomDirectionalAndChunkParity)$'
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
Write-Host 'SONKU_P6_WINDOWS_JUCE_NATIVE_ON=PASS (no physical ASIO)'
8 changes: 8 additions & 0 deletions .github/workflows/ui-smoke.yml
Original file line number Diff line number Diff line change
Expand Up @@ -320,6 +320,14 @@ jobs:
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: P6 native JUCE-path quality prepare, active room PCM and chunk parity
run: |
g++ -std=c++20 -O2 -Wall -Wextra -pedantic tests/sonku_p6_realtime_quality_test.cpp -o /tmp/sonku-p6-native
/tmp/sonku-p6-native
- name: P6 actual realtime ROOM FRONT/REAR listening WAV and objective audit
run: |
/tmp/sonku-integrity-audio sonku-integrity-evidence --p6-realtime-only
python tests/sonku_p6_realtime_audio_audit.py sonku-integrity-evidence
- name: P2 original voice-like headphone A/B and numeric PCM comparison
run: |
/tmp/sonku-integrity-audio sonku-integrity-evidence --directional-er-only
Expand Down
18 changes: 17 additions & 1 deletion CMakeLists.txt
Original file line number Diff line number Diff line change
@@ -1,5 +1,9 @@
cmake_minimum_required(VERSION 3.22)
project(ARMixConsole VERSION 0.5.0 LANGUAGES C CXX)
# Experimental P6 native profile: OFF by default in production/installer.
option(ARMIX_SONKU_EXPERIMENTAL_DIRECTIONAL_RT
"Enable unqualified SonKu full KEMAR directional reflections on the native JUCE callback"
OFF)
set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

Expand Down Expand Up @@ -192,7 +196,8 @@ target_compile_definitions(ARMixConsole PRIVATE
JUCE_APPLICATION_NAME_STRING="AR MIX Studio"
JUCE_APPLICATION_VERSION_STRING="${ARMIX_APP_VERSION}"
ARMIX_BUILD_SOURCE_SHA="${ARMIX_BUILD_SOURCE_SHA}"
ARMIX_GFX_EMBED_PNG_SKINS=1)
ARMIX_GFX_EMBED_PNG_SKINS=1
$<$<BOOL:${ARMIX_SONKU_EXPERIMENTAL_DIRECTIONAL_RT}>:ARMIX_SONKU_EXPERIMENTAL_DIRECTIONAL_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 @@ -261,12 +266,23 @@ if(BUILD_TESTING)
add_executable(ARMixSonKuCoreTests tests/sonku_spatial_core_test.cpp)
target_compile_features(ARMixSonKuCoreTests PRIVATE cxx_std_20)
add_test(NAME NativeSonKuMeasuredBinauralDirectionalAndChunkParity COMMAND ARMixSonKuCoreTests)
# P6 same core/PCM profile: no JUCE or SDK required for source regression.
add_executable(ARMixSonKuP6PreparedTests tests/sonku_p6_realtime_quality_test.cpp)
target_compile_features(ARMixSonKuP6PreparedTests PRIVATE cxx_std_20)
add_test(NAME NativeSonKuP6PreparedRoomDirectionalAndChunkParity
COMMAND ARMixSonKuP6PreparedTests)
# Real JUCE processor: audio-applied ACK, v1/v2 state, corruption fences.
juce_add_console_app(ARMixSonKuNativeStateTests PRODUCT_NAME "ArSonMix SonKu Native State Tests")
target_sources(ARMixSonKuNativeStateTests PRIVATE tests/sonku_native_state_test.cpp)
target_link_libraries(ARMixSonKuNativeStateTests PRIVATE
juce::juce_audio_processors juce::juce_recommended_config_flags)
target_compile_features(ARMixSonKuNativeStateTests PRIVATE cxx_std_20)
# Compile and test the same opt-in native profile in the actual JUCE
# adapter when a deliberately qualified experimental build requests it.
if(ARMIX_SONKU_EXPERIMENTAL_DIRECTIONAL_RT)
target_compile_definitions(ARMixSonKuNativeStateTests PRIVATE
ARMIX_SONKU_EXPERIMENTAL_DIRECTIONAL_RT=1)
endif()
add_test(NAME NativeSonKuSessionV1V2AndAudioAppliedAck
COMMAND ARMixSonKuNativeStateTests)
# Pure control-plane first-run routing selection: no JUCE, drivers,
Expand Down
86 changes: 86 additions & 0 deletions docs/SONKU_P6_PREPARED_REALTIME_DIRECTIONAL_20261114.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,86 @@
# SonKu P6 — prepared realtime directional KEMAR (experimental integration)

2026-11-14 · stacked on PR #674 / P0–P5 · **not production-qualified**

## What was integrated

The P2 directional image-source measured-KEMAR HRIR renderer, P3 exact
zero-spread source fusion and P4 contiguous 140-tap read are now selectable
as **one immutable prepared native render profile**. `SonKuSpatialCore::prepare`
accepts `SonKuReflectionProfile::DirectionalKemar`. The selected profile
reaches the original `SonKuEarlyReflections` that already handles actual
native `spacePreset` ROOM scenes and is called from one JUCE PCM processor.

`SonKuSpatialProcessor::prepareToPlay` uses this profile only when the
**explicit experimental** CMake option is enabled:

```
-DARMIX_SONKU_EXPERIMENTAL_DIRECTIONAL_RT=ON
```

Default = **OFF**. Do not add this to published installers or release workflows
until qualification. No WebAudio worker, duplicate DSP graph, new FX ID,
.session/`.smix` schema, GUI, bridge, control ACK or WIRE modifications.

The profile is admitted *before* the native room is activated. All experimental
offline setters are rejected on that profile so the renderer cannot be silently
downgraded/mutated after prepare. Device restart re-prepares the profile
and restores the accepted native acoustic scene. ROOM ON/OFF and scene distance
edits continue to use the existing smoothed 64-sample image geometry and
10–24ms level/delay transitions; P5 epoch guard prevents old ring audio.
The realtime callback does not allocate, lock, query clock, clear large rings,
load datasets, spawn threads or select a new renderer.

## Evidence

- Native C++ P6 test covers invalid profile fail closed, default unchanged,
explicit JUCE-path profile selection, active ROOM + moving orbit,
44.1/48k mixed-polarity music, fixed versus arbitrary PCM chunks,
strict no-reflection early prefix, measurable distinction from lightweight
room, restart with an accepted active scene, and immutable profile rejection.
- All previous P0–P5 fixture/PCM/380-frequency and A/B guards remain.
- The SAME native core, native ROOM scene and exact input are benchmarked as
`SONKU_P6_RT` at 48k/128, spread 0° and 60°, reporting p99 against the
theoretical block budget; shared Linux runner numbers are informational only.

## Release veto (open)

This is **engine integration**, not proof of a better audible space.
Directional reflections still use horizontal-only MIT KEMAR, four walls, and
may be expensive for many concurrent inserts. Do not auto-promote this
CMake switch, PR, public binary, or claim dearVR parity before:
1. On the actual Windows JUCE/ASIO mixer, measure p95/p99, XRUN and channel count
at 44.1/48k with 64/128/256 frames, 1 and several SonKu instances, WIRE + VST3.
2. Same-gain, blind headphone A/B on real stereo material, solo voice, anti-phase,
FRONT/REAR, movement, ROOM on/off and 0°/60° spread.
3. Confirm tonal coloration, perceived outside-head position, distance ordering,
no click on edit/restart, no audible late-reverb artifact.
4. Reconcile any main-branch changes and run native JUCE Windows compilation
before a tester build. Keep original P0–P5 PR draft.

Do not use an unstable per-callback CPU clock to dynamically switch HRTF modes;
a global mixer graph budget belongs to the host admission policy, not a guessed
one-size threshold in the audio thread.

## P6 native ROOM headphone artifact

The scoped SonKu fast CI also renders **eight lossless original 48k/16-bit
stereo WAVs**: LIGHT versus DIRECTIONAL prepared mode on FRONT/REAR and
stereo spreads 0°/60°. Both use the exact same real native SQUARE
ROOM controls, output trim, direct HRIR, synthesized phase-conflicted
L/R instruments and 3-second frame clock (no external licensed music).
`tests/sonku_p6_realtime_audio_audit.py` enforces consistent metadata,
the exact no-reflection early prefix, finite / unclipped and non-silent
PCM, and a genuine measured wet-output difference after reflections.
Metrics are uploaded with the WAVs and listening guide. A difference
from lightweight reflections is expected; it is **not** evidence the
candidate sounds better, externalizes more or matches dearVR.

## Native build reproducibility

`ARMixSonKuP6PreparedTests` is now a focused portable CTest target.
The existing real JUCE `ARMixSonKuNativeStateTests` asserts the prepared
profile in **both** option-OFF (Lightweight) and explicit option-ON
(DirectionalKemar) Windows builds, alongside native ACK/state restoration.
Use the exact PR SHA to compile the test once on Windows; Linux native
GitHub Actions proves portable-core behavior but not a Windows JUCE binary.
12 changes: 11 additions & 1 deletion engine/builtin_fx/SonKuSpatialProcessor.h
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,14 @@ class SonKuSpatialProcessor final : public juce::AudioProcessor,
&& layout.getMainOutputChannelSet()==juce::AudioChannelSet::stereo();
}
void prepareToPlay(double rate,int) override {
ready_=core_.prepare(rate);
// 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
constexpr auto profile=armix::sonku::SonKuReflectionProfile::DirectionalKemar;
#else
constexpr auto profile=armix::sonku::SonKuReflectionProfile::Lightweight;
#endif
ready_=core_.prepare(rate,profile);
observedAzimuthDegrees_.store(accepted_.startAzimuthDegrees,std::memory_order_relaxed);
if(ready_)ready_=core_.setSettings(accepted_);
}
Expand Down Expand Up @@ -71,6 +78,9 @@ class SonKuSpatialProcessor final : public juce::AudioProcessor,
}
armix::sonku::Settings acceptedSettings() const noexcept {return accepted_;}
bool isReady() const noexcept {return ready_;}
armix::sonku::SonKuReflectionProfile preparedReflectionProfile() const noexcept {
return core_.preparedReflectionProfile();
}
float observedAzimuthDegrees() const noexcept {
return observedAzimuthDegrees_.load(std::memory_order_relaxed);
}
Expand Down
Loading
Loading