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
10 changes: 10 additions & 0 deletions .github/workflows/sonku-p72-native-xyz.yml
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,10 @@ on:
- 'engine/builtin_fx/SonKuSpatialProcessor.h'
- 'engine/builtin_fx/sonku/**'
- 'tests/sonku_p72_*'
- 'src/SonKuNativeBridgeContract.h'
- 'site/preview-v2/assets/mixer-native-sonku.js'
- 'tests/sonku_p73_*'
- 'tests/native_peq_assembly_test.py'
- 'CMakeLists.txt'
- '.github/workflows/sonku-p72-native-xyz.yml'
permissions:
Expand All @@ -31,6 +35,12 @@ jobs:
run: |
test "$(git rev-parse HEAD)" = "$EXPECTED"
echo "SONKU_P72_EXACT_SHA=$EXPECTED"
- name: P7.3 JS grammar, actual geometry/capability and bridge regression
run: |
set -euo pipefail
node --check site/preview-v2/assets/mixer-native-sonku.js
node tests/sonku_p73_gui_contract_test.js
python -m unittest discover -s tests -p native_peq_assembly_test.py
- name: Compile and execute original default native PCM contracts
run: |
set -euo pipefail
Expand Down
59 changes: 59 additions & 0 deletions docs/SONKU_P73_NATIVE_GUI_BRIDGE_CONTRACT_20261114.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
# SonKu P7.3 — native GUI/bridge contract research milestone
Date: 14 November 2026 | stacked P7.3 → #685 (P7.2) → #681 (P7.1)

## Scope / actual implementation

The existing `src/Main.cpp` SonKu native action dispatcher now delegates both
typed incoming `nativeSonKuSet.settings` and outbound accepted
`nativeSonKuSnapshot.settings` to **one**
`src/SonKuNativeBridgeContract.h`, rather than maintaining a divergent
manual v2 parse and snapshot. This is a CONTROL-thread-only codec and
contains no second audio renderer or graph. It checks finite typed numbers,
native `Settings::valid()`, bool types, geometric admissibility and all
mandatory v1 fields. Optional legacy v2 ROOM fields remain backwards
compatible. The native SPSC callback and native applied ACK remain the
sole authoritative audio state.

- **Production default:** `ARMIX_SONKU_EXPERIMENTAL_NATIVE_XYZ_RT=OFF`
means `schemaVersion=2`, the bridge snapshot has no elevation, v2-only
settings **reject** unexpected `directElevationDegrees`; the normal
46-byte SONK v2 FX state persists unchanged.
- **Experimental:** option ON means `schemaVersion=3`, the same typed
settings codec admits measured `directElevationDegrees` jointly with
radial distance/ROOM. Missing elevation from old browser clients defaults
exactly 0°. P7.2 native FX persists v3 50 bytes and can restore v1/v2.
No second `.smix` document schema or unverified host path introduced.

The existing SonKu editor (same `/preview-v2/` asset, no cloned UI) shows
a single compact **SOURCE ELEVATION** slider *only after* an exact
ChannelId/instance/deviceEpoch/graphRevision matched native snapshot
advertises v3 with valid elevation. Range is derived from actual source
radial distance and room height, respecting ear clearance and measured
bank angle; room/distance changes transparently fit existing elevation
within the new room. The main 2D top-down SVG is still the azimuth
control; elevation is one independent, keyboard-accessible source height
control. The stage caption changes from 0° to measured 3D only when
native capability is established.

All gestures continue to use pre-existing 25Hz bounded SPSC intent,
latest-wins coalescing, and **ACK + snapshot appliedRequestId**
verification before claiming DSP APPLIED. The new slider is not a
WebAudio panner or a speculative optimistic DSP state. A stale graph
revision/device epoch snapshot cannot arm v3 capability. `hidden`
overrides the existing grid display rule so **public v2 GUI size and
layout are unchanged**.

## Evidence / non-claims

- C++ native Windows CTests compile and run v2/v3 actual typed JSON codec,
including invalid elevation, NaN, incompatible room distance, wrong types,
and fail-atomic decode. P7.2 real JUCE PCM callback/ACK and v1/v2/v3 state
tests are reused; no entire installer/full-application rebuild.
- Linux Node checks actual SonKu GUI script syntax and physical room
geometry (old v2, source height, fit), plus native GUI bridge source
regression. P0–P7.2 PCM negative controls remain in scoped CI.
- Still **NOT proven:** full `ARMixConsole` Windows integration build,
physical ASIO + WIRE/VST3, human HRTF/dearVR listening, published
`.smix` end-to-end click/open/save/restore in a native tester, release
licensing, or P7.3 interaction design certification. Keep all stacked PRs
DRAFT and the production XYZ feature OFF until these gates are proven.
1 change: 1 addition & 0 deletions site/preview-v2/assets/mixer-fx-rack.css
Original file line number Diff line number Diff line change
Expand Up @@ -1355,6 +1355,7 @@
.mx-sonku .sk-space-options button[aria-pressed="true"]{color:#e8fbff;
border-color:#6fc6d7;background:#24556a;box-shadow:inset 0 1px #ffffff19}
.mx-sonku .sk-space-options button:focus-visible{outline:2px solid #9bdae8;outline-offset:1px}
.mx-sonku .sk-controls .sk-space-slider[hidden]{display:none!important}
.mx-sonku .sk-controls .sk-space-slider{display:grid!important;
grid-template-columns:1fr auto;gap:3px!important;align-items:center;
font-size:9px;letter-spacing:.4px;color:#a6c5d1;margin:0}
Expand Down
74 changes: 66 additions & 8 deletions site/preview-v2/assets/mixer-native-sonku.js
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,24 @@ const defaults=()=>({startAzimuthDegrees:0,revolutionSeconds:12,
stereoSpreadDegrees:60,spatialMix:1,outputTrim:.75,moving:true,clockwise:true,
spacePreset:0,sourceDistanceMeters:1.6,roomAmount:.55,ambience:.30});
const normalizeSettings=s=>({...defaults(),...s});
// Native schema v3 is the ONLY authority that enables elevation controls.
// Public v2 never receives, edits or serializes a speculative XYZ field.
const roomHeights=[3.2,3.2,4.8,7.2];
const elevationLimits=s=>{
const distance=s.sourceDistanceMeters;
const height=roomHeights[s.spacePreset];
if(!Number.isFinite(distance)||!height)return {min:0,max:0};
const bottom=Math.max(-40,Math.asin(Math.max(-1,Math.min(1,(.5-1.45)/distance)))*180/Math.PI);
const top=Math.min(60,Math.asin(Math.max(-1,Math.min(1,(height-.5-1.45)/distance)))*180/Math.PI);
// Keep a 0.1 degree safety margin for C++ float boundary rounding.
return {min:Math.ceil((bottom+0.001)*10)/10,
max:Math.floor((top-0.001)*10)/10};
};
const fitElevation=s=>{
if(!Object.prototype.hasOwnProperty.call(s,"directElevationDegrees"))return s;
const {min,max}=elevationLimits(s);
return {...s,directElevationDegrees:Math.min(max,Math.max(min,s.directElevationDegrees))};
};
// Legacy v1/v2 states already persist a LINEAR outputTrim number (0..1).
// Keep the native JSON key and its meaning intact; the visible GAIN dial
// now expresses the SAME linear multiplier in dB and can exceed unity.
Expand All @@ -26,7 +44,14 @@ const valid=s=>s && Number.isFinite(s.startAzimuthDegrees) &&
Number.isFinite(s.sourceDistanceMeters) && s.sourceDistanceMeters>=1.6 &&
s.sourceDistanceMeters<=roomMaxDistance[s.spacePreset]+.0001 &&
Number.isFinite(s.roomAmount) && s.roomAmount>=0 && s.roomAmount<=1 &&
Number.isFinite(s.ambience) && s.ambience>=0 && s.ambience<=1;
Number.isFinite(s.ambience) && s.ambience>=0 && s.ambience<=1 &&
(s.directElevationDegrees===undefined || (
Number.isFinite(s.directElevationDegrees) &&
s.directElevationDegrees>= -40 && s.directElevationDegrees<=60 &&
s.sourceDistanceMeters*Math.cos(s.directElevationDegrees*Math.PI/180)>=.7 &&
1.45+s.sourceDistanceMeters*Math.sin(s.directElevationDegrees*Math.PI/180)>=.5 &&
1.45+s.sourceDistanceMeters*Math.sin(s.directElevationDegrees*Math.PI/180)<=
roomHeights[s.spacePreset]-.5));
const backend=()=>window.__JUCE__?.backend;
const native=()=>typeof backend()?.emitEvent==="function";
const snapshot=()=>window.__ARMIX_NATIVE_M2__?.fxEditorState?.()||
Expand Down Expand Up @@ -129,6 +154,8 @@ root.innerHTML=[
'<button type="button" data-sk-room="3">LARGE</button></div>',
'<label class="sk-space-slider" for="skDistance">SOURCE DISTANCE <output id="skDistanceValue">1.6 m</output>',
'<input id="skDistance" type="range" min="1.6" max="10" step="0.1" value="1.6"/></label>',
'<label class="sk-space-slider" id="skElevationRow" for="skElevation" hidden>SOURCE ELEVATION <output id="skElevationValue">0.0°</output>',
'<input id="skElevation" type="range" min="-30" max="45" step="0.1" value="0" aria-label="Direct source elevation in degrees" title="Measured binaural source height · native experimental schema v3 only"/></label>',
'<label class="sk-space-slider" for="skReflections">REFLECTIONS <output id="skReflectionsValue">55%</output>',
'<input id="skReflections" type="range" min="0" max="100" step="1" value="55" title="First-wall reflections level, 0 is dry"/></label>',
'<label class="sk-space-slider" for="skAmbience">REVERB <output id="skAmbienceValue">30%</output>',
Expand All @@ -146,6 +173,7 @@ const depthLayers={far:$("skFarSources"),near:$("skNearSources")};
const mount=()=>{if(!root.isConnected)document.body.append(root)};
if(document.readyState==="loading")document.addEventListener("DOMContentLoaded",mount,{once:true});else mount();
let current=null,accepted=defaults(),draft=defaults(),pending=null,latest=null,
xyzCapable=false,
readId="",readSentAt=0,seq=1,clock=null,frame=null,observed=0,observedAt=0,
drag=null,dialDrag=null,rangeEdits=new Set(),gestureStart=new Map(),
visualPhase=0,visualAt=0,liveTimer=null,lastLiveAt=0;
Expand Down Expand Up @@ -193,6 +221,19 @@ function render(){
if(!rangeEdits.has("skDistance"))
distance.value=String(Math.min(max,s.sourceDistanceMeters));
$("skDistanceValue").textContent=s.sourceDistanceMeters.toFixed(1)+" m";
// Never expose a nonfunctional XYZ control in the publicly compiled
// v2-only application; the actual native snapshot controls capability.
const elevationRow=$("skElevationRow"),elevation=$("skElevation");
elevationRow.hidden=!xyzCapable;
if(xyzCapable){
const limits=elevationLimits(s);
elevation.min=String(limits.min);elevation.max=String(limits.max);
if(!rangeEdits.has("skElevation"))elevation.value=String(s.directElevationDegrees);
$("skElevationValue").textContent=s.directElevationDegrees.toFixed(1)+"°";
}
root.querySelector(".sk-stage-caption").textContent=xyzCapable
?"HEADPHONES · MEASURED 3D HRIR · 44.1 / 48 kHz"
:"HEADPHONES · HRIR 0° ELEVATION · 44.1 / 48 kHz";
if(!rangeEdits.has("skAmbience"))
$("skAmbience").value=String(Math.round(s.ambience*100));
const reflections=$("skReflections");
Expand Down Expand Up @@ -277,7 +318,8 @@ function requestSnapshot(force=false){
// latest-wins coalescing; ACK + accepted snapshot remain mandatory before
// issuing the next. Never fill the DSP SPSC queue with raw pointer events.
const LIVE_INTERVAL_MS=40;
const sameSettings=(a,b)=>a&&b&&Object.keys(defaults()).every(k=>a[k]===b[k]);
const sameSettings=(a,b)=>a&&b&&Object.keys(defaults()).every(k=>a[k]===b[k]) &&
(!xyzCapable || a.directElevationDegrees===b.directElevationDegrees);
function send(next,continuous=false){
if(!valid(next))return false;
draft={...next};render();
Expand Down Expand Up @@ -338,9 +380,17 @@ backend()?.addEventListener?.("arMixBuiltinSonKuAck",r=>{
backend()?.addEventListener?.("arMixBuiltinSonKuSnapshot",r=>{
if(r?.requestId!==readId||!current)return;
const c=context();if(!c||r.status!=="ACCEPTED"||
r.channelId!==c.channelId||r.instanceId!==c.instanceId)return;
r.channelId!==c.channelId||r.instanceId!==c.instanceId||
String(r.deviceEpoch)!==String(c.deviceEpoch)||
String(r.graphRevision)!==String(c.graphRevision))return;
const measured=r.schemaVersion===3 &&
Number.isFinite(r.settings?.directElevationDegrees);
if(r.schemaVersion!==2&&!measured)return;
const incoming=normalizeSettings(r.settings);
if(!measured)delete incoming.directElevationDegrees;
if(!valid(incoming))return;
// Activation happens only after a fully identity-bound native readback.
xyzCapable=measured;
readId="";readSentAt=0;
if(pending) {
if(!pending.ack || r.appliedRequestId!==pending.requestId){
Expand All @@ -363,7 +413,7 @@ backend()?.addEventListener?.("arMixBuiltinSonKuSnapshot",r=>{
}
render();
});
$("skClose").addEventListener("click",()=>{root.hidden=true;current=null;
$("skClose").addEventListener("click",()=>{root.hidden=true;current=null;xyzCapable=false;
cancelLiveTimer();pending=null;latest=null;readId="";readSentAt=0;dialDrag=null;
drag=null;rangeEdits.clear();gestureStart.clear();lastLiveAt=0;
if(clock!==null){clearInterval(clock);clock=null;}
Expand All @@ -372,12 +422,17 @@ $("skMotion").addEventListener("click",()=>send({...draft,moving:!draft.moving})
$("skDirection").addEventListener("click",()=>send({...draft,clockwise:!draft.clockwise}));
root.querySelectorAll("[data-sk-room]").forEach(btn=>btn.addEventListener("click",()=>{
const preset=Number(btn.dataset.skRoom),max=roomMaxDistance[preset];
send({...draft,spacePreset:preset,
const proposed={...draft,spacePreset:preset,
sourceDistanceMeters:preset===0?draft.sourceDistanceMeters:
Math.min(draft.sourceDistanceMeters,max)});
Math.min(draft.sourceDistanceMeters,max)};
const fitted=xyzCapable?fitElevation(proposed):proposed;
if(send(fitted)&&xyzCapable &&
fitted.directElevationDegrees!==proposed.directElevationDegrees)
hint("ELEVATION FITTED TO ROOM · AWAITING DSP ACK");
}));
for(const [id,key,convert] of [
["skDistance","sourceDistanceMeters",v=>v],
["skElevation","directElevationDegrees",v=>v],
["skReflections","roomAmount",v=>v/100],
["skAmbience","ambience",v=>v/100]]) {
const slider=$(id);
Expand All @@ -391,7 +446,10 @@ for(const [id,key,convert] of [
const value=Number(slider.value);
if(!Number.isFinite(value))return;
rangeEdits.add(id);
liveInput({...draft,[key]:convert(value)});
const proposed={...draft,[key]:convert(value)};
const fitted=key==="sourceDistanceMeters"&&xyzCapable
?fitElevation(proposed):proposed;
liveInput(fitted);
});
slider.addEventListener("change",()=>{
gestureStart.delete(id);rangeEdits.delete(id);
Expand Down Expand Up @@ -508,7 +566,7 @@ const api={
cancelLiveTimer();pending=null;latest=null;readId="";readSentAt=0;dialDrag=null;
observedAt=0;visualAt=0;visualPhase=0;lastLiveAt=0;
drag=null;rangeEdits.clear();gestureStart.clear();
accepted=defaults();draft=defaults();
accepted=defaults();draft=defaults();xyzCapable=false;
current={track,slot,instanceId:null};
const s=snapshot(),id=window.__ARMIX_NATIVE_M2__?.nativeIdFor?.(track);
const fx=s?.graph?.channels?.find(x=>x.id===id)?.inserts?.[slot];
Expand Down
61 changes: 9 additions & 52 deletions src/Main.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,7 @@
#include "NativeHotkeyRegistry.h"
#include "NativeFxParameterHotkey.h"
#include "NativeFxControlRequest.h"
#include "SonKuNativeBridgeContract.h"
#include "NativeDeviceApplyCoordinator.h"
#if defined(_WIN32)
#include "../engine/device/WindowsFirstRunEndpointDiscovery.h"
Expand Down Expand Up @@ -3003,23 +3004,13 @@ class ConsoleWindow final : public juce::DocumentWindow, private juce::Timer, pr
reply->setProperty("deviceEpoch",epoch);
reply->setProperty("graphRevision",revision);
reply->setProperty("instanceId",instanceId);
reply->setProperty("schemaVersion",2);
reply->setProperty("schemaVersion",
armix::builtin_fx::sonku_bridge::schemaVersion());
reply->setProperty("status",processor?"ACCEPTED":"REJECTED");
if(processor) {
const auto s=processor->acceptedSettings();
auto values=std::make_unique<juce::DynamicObject>();
values->setProperty("startAzimuthDegrees",s.startAzimuthDegrees);
values->setProperty("revolutionSeconds",s.revolutionSeconds);
values->setProperty("stereoSpreadDegrees",s.stereoSpreadDegrees);
values->setProperty("spatialMix",s.spatialMix);
values->setProperty("outputTrim",s.outputTrim);
values->setProperty("moving",s.moving);
values->setProperty("clockwise",s.clockwise);
values->setProperty("spacePreset",s.spacePreset);
values->setProperty("sourceDistanceMeters",s.sourceDistanceMeters);
values->setProperty("roomAmount",s.roomAmount);
values->setProperty("ambience",s.ambience);
reply->setProperty("settings",juce::var(values.release()));
reply->setProperty("settings",
armix::builtin_fx::sonku_bridge::acceptedSettings(
processor->acceptedSettings()));
reply->setProperty("observedAzimuthDegrees",
processor->observedAzimuthDegrees());
if(epoch=="0" && instanceId==lastLogicalFxInstance_ &&
Expand Down Expand Up @@ -4626,46 +4617,12 @@ class ConsoleWindow final : public juce::DocumentWindow, private juce::Timer, pr
rawEpoch.toString(),rawRevision.toString(),rawInstance.toString(),p);
return;
}
const auto values=args.getProperty("settings",{});
armix::sonku::Settings settings{};
auto number=[&values](const char* key,float& dest) {
const auto v=values.getProperty(key,{});
if(!v.isDouble()&&!v.isInt())return false;
const double n=static_cast<double>(v);
if(!std::isfinite(n) || n>1.0e6 || n< -1.0e6)return false;
dest=static_cast<float>(n);
return std::isfinite(dest);
};
const auto moving=values.getProperty("moving",{});
const auto clockwise=values.getProperty("clockwise",{});
const bool parameters=values.isObject() &&
number("startAzimuthDegrees",settings.startAzimuthDegrees) &&
number("revolutionSeconds",settings.revolutionSeconds) &&
number("stereoSpreadDegrees",settings.stereoSpreadDegrees) &&
number("spatialMix",settings.spatialMix) &&
number("outputTrim",settings.outputTrim) &&
moving.isBool()&&clockwise.isBool();
if(parameters){settings.moving=static_cast<bool>(moving);
settings.clockwise=static_cast<bool>(clockwise);}
// Optional v2 fields preserve legacy v1 clients and old sessions.
// Typed native intent remains bounded and validated before SPSC.
const auto preset=values.getProperty("spacePreset",{});
bool acousticParameters=true;
if(!preset.isVoid()){
if(!preset.isInt())acousticParameters=false;
else settings.spacePreset=static_cast<int>(preset);
}
const auto optionalNumber=[&](const char* key,float& target) {
if(values.getProperty(key,{}).isVoid())return true;
return number(key,target);
};
acousticParameters=acousticParameters &&
optionalNumber("sourceDistanceMeters",settings.sourceDistanceMeters) &&
optionalNumber("roomAmount",settings.roomAmount) &&
optionalNumber("ambience",settings.ambience);
const bool parameters=armix::builtin_fx::sonku_bridge::decodeSettings(
args.getProperty("settings",{}),settings);
const auto numeric=fxRequest.sequence("sonku-");
bool queued=false;
if(p&&numeric&&parameters&&acousticParameters&&armix::sonku::valid(settings) &&
if(p&&numeric&&parameters &&
!pendingNativeSonKu_.owner&&!nativeShowBusy_&&!studioBackupBusy_&&
!engine_.independentClockActive()) {
queued=p->queueSettings(settings,numeric);
Expand Down
Loading
Loading