Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
5e856e5
feat(sonku): realtime-safe prepared FDN room decay and wet transitions
masarray Nov 13, 2026
2f03e07
feat(sonku): bounded nonclearing live room geometry and reflection co…
masarray Nov 13, 2026
aed2fce
feat(sonku): typed room/distance/ambience scene in authoritative PCM …
masarray Nov 13, 2026
0bd148e
fix(sonku): keep original offline FDN preset path unmodified on defau…
masarray Nov 13, 2026
e52b311
feat(sonku): versioned v1/v2 session restore, tail and native scene r…
masarray Nov 13, 2026
ef8d6ec
feat(sonku): typed native room/distance/ambience set and authoritativ…
masarray Nov 13, 2026
132678e
feat(sonku): compact SPACE size/distance/ambience GUI wired to native…
masarray Nov 13, 2026
be2e4fb
style(sonku): compact responsive SPACE instrument controls in existin…
masarray Nov 13, 2026
98f6ec1
test(sonku): native scene PCM partition parity and live transition re…
masarray Nov 13, 2026
3199b39
test(sonku): prepared FDN live preset switching and stale-tail suppre…
masarray Nov 13, 2026
2f8a170
test(sonku): real Chromium SPACE size/distance ACK/readback and fail-…
masarray Nov 13, 2026
28bf141
test(sonku): source-level native v2 DSP ACK and session persistence c…
masarray Nov 13, 2026
f337ae0
docs(sonku): native SPACE vertical slice architecture and release gates
masarray Nov 13, 2026
a597ae9
fix(sonku): make first native ROOM selection audible while preserving…
masarray Nov 13, 2026
2900ffb
feat(sonku): render five M4 musical scene WAVs through exact ACKed DS…
masarray Nov 13, 2026
29e671b
test(sonku): real M4 musical scene PCM differences and distance falloff
masarray Nov 13, 2026
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
71 changes: 71 additions & 0 deletions docs/SONKU_M4_NATIVE_SPACE_RELEASE_CANDIDATE_20261113.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
# SonKu M4 — Native SPACE / musical ambience release candidate
2026-11-13 | Draft stacked on #643 → #629 → #606 | NOT public release

## Why this is a vertical product slice
Operator opens **8D-SonKu** from the real FX rack and selects OFF / SQUARE /
CHAMBER / LARGE. Two small sliders control source distance and musical
AMBIENCE. A single `nativeSonKuSet` message flows through the existing
device-epoch, graph-revision, exact ChannelId, instance lease, native queue,
JUCE processing callback and completion. The GUI only displays APPLIED after
matching callback ACK and accepted DSP readback. No WebAudio, browser PCM,
fake owner or duplicated audio callback.

Room map:
- OFF: original direct KEMAR HRIR; no ER or late FDN work, v1-compatible.
- SQUARE: 7.2 × 7.2 m, max radius 3.1 m, short Studio Glue decay ~0.78 s.
- CHAMBER: 14.4 × 14.4 m, max radius 6.7 m, Airy decay ~1.28 s.
- LARGE: 28.8 × 28.8 m, max radius 10 m, restrained decay ~2.05 s.
RoomAmount is fixed to the previously tested 0.55 when user first enables
a scene. For each scene, the direct path uses 1.6 / sourceDistance pressure,
the eight first-order wall paths use 1.6 / reflectedPath pressure, and the
diffuse tail is wet-only. The exact approved HRIR azimuth and orbit geometry
are unchanged.

## Realtime invariants
- All 8× per-line FDN feedback gains and damping coefficients for these
presets are computed on `prepare()` and selected without exp(), new/delete,
locks, device restart, or blocking calls in the callback.
- Coefficients and wet levels slew on the sample clock; existing ER fractional
delays and gains slew too, with geometry recalculated only every 64 samples.
- Reenable after disabled room uses a validity horizon on the existing fixed
8192-sample ER rings; reenable on FDN uses a horizon on the existing 4096-
frame rings. No ~64/128 KiB buffer clears in a live edit.
- FX graph owns bypass/retire/reorder/routing; SonKu never installs its own
audio device or hidden monitoring gate.
- Multiple instances have independent fixed memory; no static mutable DSP.

## Persistence and backward compatibility
`SonKuSpatialProcessor` serializes SONK version 2, exactly 46 bytes with
old 30-byte v1 restore supported. New state carries `spacePreset`,
`sourceDistanceMeters`, `roomAmount`, `ambience`. Legacy v1 restores as
room OFF; malformed v2 is rejected atomically; the last accepted edit is
only persisted after audio-applied completion. Accepted snapshot schema=2
returns exactly the stored state. Existing GUI transport v1 fields may omit
new controls and default OFF.

## What still blocks public release
1. CI: source contract, native no-JUCE PCM, Chromium actual WebView2-assembled
controls, exact-SHA Windows MSVC/CTest, multi-instance restore and restart.
2. Confirm no clicks/glitches on OFF→LARGE→SQUARE, rapid slider changes, rack
bypass, graph remove, save/open .smix, device swap, and stereo-only policy.
3. Human headphone A/B: compare approved Square reference, Studio Glue, Airy
and M4 scene presets with music + voice (front/rear distance, flutter,
metallic coloration, decay masking); adjust only after evidence.
4. Reconcile parent #606 (latest main) → #629 → #643 → this M4 without
dropping independent WIRE, GUI, updater and FX progress. Do not promote
public release based on Linux offline/Chromium mocks alone.

## Explicit physical limits
2D first-order 4-wall image model; no height/floor/ceiling, personalized
HRTF, frequency-calibrated air absorption, true measured BRIR, later
higher-order bounces or physically fitted RT60. LARGE is a musical scene
preset, not a certified geometry-based hall reverb. Accurate propagation
delay of the direct path is not modeled, for low latency.

## References (concepts only)
- Allen–Berkley image-source method: JASA 65(4), 1979, DOI 10.1121/1.382599
- Valve Steam Audio core guide: direct distance and room reflections are
separate stages; no vendor code copied.
https://github.com/ValveSoftware/steam-audio/blob/master/core/doc/guide.rst
- JUCE AudioProcessor: processBlock realtime cautions and bypass semantics.
https://docs.juce.com/master/classjuce_1_1AudioProcessor.html
29 changes: 24 additions & 5 deletions engine/builtin_fx/SonKuSpatialProcessor.h
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,9 @@ class SonKuSpatialProcessor final : public juce::AudioProcessor,
bool acceptsMidi() const override {return false;}
bool producesMidi() const override {return false;}
bool isMidiEffect() const override {return false;}
double getTailLengthSeconds() const override {return 0.;}
// Conservative bounded tail for the longest enabled room program. OFF
// still performs no FDN work; this reports potential host tail ownership.
double getTailLengthSeconds() const override {return 2.6;}
int getNumPrograms() override {return 1;}
int getCurrentProgram() override {return 0;}
void setCurrentProgram(int) override {}
Expand Down Expand Up @@ -80,29 +82,46 @@ class SonKuSpatialProcessor final : public juce::AudioProcessor,
void getStateInformation(juce::MemoryBlock& dest) override {
juce::MemoryOutputStream out(dest,false);
out.writeInt(0x534F4E4B); // SONK
out.writeInt(1);
out.writeInt(2);
out.writeFloat(accepted_.startAzimuthDegrees);
out.writeFloat(accepted_.revolutionSeconds);
out.writeFloat(accepted_.stereoSpreadDegrees);
out.writeFloat(accepted_.spatialMix);
out.writeFloat(accepted_.outputTrim);
out.writeByte(accepted_.moving?1:0);
out.writeByte(accepted_.clockwise?1:0);
out.writeInt(accepted_.spacePreset);
out.writeFloat(accepted_.sourceDistanceMeters);
out.writeFloat(accepted_.roomAmount);
out.writeFloat(accepted_.ambience);
}
bool restoreUnpublishedState(const void* data,int size) {
if(published_||!data||size!=30||!queue_.empty()||!complete_.empty())return false;
if(published_||!data||(size!=30&&size!=46)||
!queue_.empty()||!complete_.empty())return false;
juce::MemoryInputStream in(data,static_cast<std::size_t>(size),false);
if(in.readInt()!=0x534F4E4B||in.readInt()!=1)return 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;
armix::sonku::Settings next{};
next.startAzimuthDegrees=in.readFloat();
next.revolutionSeconds=in.readFloat();
next.stereoSpreadDegrees=in.readFloat();
next.spatialMix=in.readFloat();
next.outputTrim=in.readFloat();
const int moving=in.readByte(),clockwise=in.readByte();
if(moving>1||clockwise>1||!in.isExhausted())return false;
if(moving>1||clockwise>1)return false;
next.moving=moving!=0;
next.clockwise=clockwise!=0;
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(!in.isExhausted())return false;
if(!armix::sonku::valid(next))return false;
if(ready_&&!core_.setSettings(next))return false;
accepted_=next;
Expand Down
29 changes: 27 additions & 2 deletions engine/builtin_fx/sonku/SonKuEarlyReflections.h
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ class SonKuEarlyReflections final {
for(auto& h:history_)h.fill(0.f);
lowpass_.fill(0.f);
for(auto& paths:tap_)for(auto& p:paths)p=Tap{};
write_=0;untilGeometry_=0;primed_=false;
write_=0;untilGeometry_=0;primed_=false;validFrames_=0;
amount_=0.f;
}
// Deliberately experimental and OFF by default. Legacy 8/8 direction
Expand Down Expand Up @@ -90,6 +90,26 @@ class SonKuEarlyReflections final {
primed_=false;
return true;
}
// Caller validates geometry on CONTROL side before queuing the POD edit.
// Audio-side update only changes targets for existing 64-frame image
// geometry updates; old path taps smoothly move, never clear big rings.
bool setRealtimeRoom(const SonKuRoomGeometry& g,float amount,
bool enabled) noexcept {
if(!std::isfinite(amount)||amount<0.f||amount>1.f)return false;
if(enabled && !validGeometry(g))return false;
if(!active() && enabled && amount>0.f){
validFrames_=0; lowpass_.fill(0.f);
}
if(enabled){
geometry_=g;custom_=true;shape_=SonKuRoomShape::Square;
}else{
custom_=false;shape_=SonKuRoomShape::Square;
}
realtimeMode_=true;
amountTarget_=enabled?amount:0.f;
untilGeometry_=0;
return true;
}
float relativeDistanceGain() const noexcept {
return custom_?1.6f/geometry_.distanceMeters:1.f;
}
Expand Down Expand Up @@ -127,6 +147,7 @@ class SonKuEarlyReflections final {
}
}
write_=(write_+1)&(ringFrames-1);
if(realtimeMode_&&validFrames_<ringFrames)++validFrames_;
--untilGeometry_;
// Preserve the headroom of the native direct path: no artificial
// direction-dependent boost at FRONT or REAR.
Expand All @@ -144,6 +165,9 @@ class SonKuEarlyReflections final {
// Fractional delay interpolated in a fixed-size power-of-two ring.
const float bounded=std::clamp(delay,1.f,static_cast<float>(ringFrames-3));
const int integer=static_cast<int>(bounded);
// Avoid re-reading a stale tail after the user disabled and later
// re-enabled the ROOM. Entire 64 KiB ring never needs RT clearing.
if(realtimeMode_&&validFrames_<=integer+1)return 0.f;
const float fract=bounded-static_cast<float>(integer);
const int i0=(write_-integer)&(ringFrames-1);
const int i1=(i0-1)&(ringFrames-1);
Expand Down Expand Up @@ -210,7 +234,8 @@ class SonKuEarlyReflections final {
std::array<float,sourceCount> lowpass_{};
float rate_=0.f,delaySlew_=0.f,gainSlew_=0.f,amountSlew_=0.f;
float amount_=0.f,amountTarget_=0.f;
int write_=0,untilGeometry_=0;
int write_=0,untilGeometry_=0,validFrames_=0;
bool realtimeMode_=false;
SonKuRoomShape shape_=SonKuRoomShape::Rectangular;
SonKuRoomGeometry geometry_{};
bool custom_=false,ready_=false,primed_=false;
Expand Down
55 changes: 49 additions & 6 deletions engine/builtin_fx/sonku/SonKuMusicalReverb.h
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
// reflections; no source-following stereo pan is imposed on the reverb tail.
// These listening-test presets are OFF in the shipping JUCE editor.
namespace armix::sonku {
enum class SonKuReverbPreset : std::uint8_t { StudioGlue=0, AiryChamber=1 };
enum class SonKuReverbPreset : std::uint8_t { StudioGlue=0, AiryChamber=1, LargeRoom=2 };

class SonKuMusicalReverb final {
public:
Expand All @@ -28,14 +28,20 @@ class SonKuMusicalReverb final {
amountTarget_=0.f;
preset_=SonKuReverbPreset::StudioGlue;
configure();
// All room-aware coefficients prepared once OFF the PCM callback.
prepared_[0]=makeCoefficients(.78f,5900.f);
prepared_[1]=makeCoefficients(1.28f,7000.f);
prepared_[2]=makeCoefficients(2.05f,6000.f);
targetGain_=gain_;targetDamp_=dampCoeff_;
realtimeMode_=false;
reset();
ready_=true;
return true;
}
void reset() noexcept {
for(auto& line:memory_)line.fill(0.f);
lowpass_.fill(0.f);
write_=0;amount_=0.f;
write_=0;amount_=0.f;validFrames_=0;
// The target amount is a CONTROL-side setting and survives resetting
// host transport/processor so the same program can restart cleanly.
}
Expand All @@ -55,6 +61,24 @@ class SonKuMusicalReverb final {
configure();
return true;
}
// Realtime-safe preset/wet update: only POD/table copies, no exponentials,
// heap, locks or clearing 128 KiB of delay memory in the audio callback.
// A validity horizon ensures no stale tail from a previous OFF period.
bool setRealtimeProgram(SonKuReverbPreset preset,float amount) noexcept {
if((preset!=SonKuReverbPreset::StudioGlue &&
preset!=SonKuReverbPreset::AiryChamber &&
preset!=SonKuReverbPreset::LargeRoom)||
!std::isfinite(amount)||amount<0.f||amount>1.f)return false;
if(!active() && amount>0.f){validFrames_=0;lowpass_.fill(0.f);}
const auto& coefficients=prepared_[static_cast<int>(preset)];
targetGain_=coefficients.gains;
targetDamp_=coefficients.damping;
if(!realtimeMode_){gain_=targetGain_;dampCoeff_=targetDamp_;}
realtimeMode_=true;
preset_=preset;
amountTarget_=amount;
return true;
}
SonKuReverbPreset preset() const noexcept {return preset_;}
bool active() const noexcept {return ready_&&(amount_>0.f||amountTarget_>0.f);}
float targetAmount() const noexcept {return amountTarget_;}
Expand All @@ -65,10 +89,13 @@ class SonKuMusicalReverb final {
const float mid=.5f*(a+b);
const float side=.5f*(a-b);
std::array<float,lineCount> y{},mix{};
if(realtimeMode_)dampCoeff_+=slew_*(targetDamp_-dampCoeff_);
for(int i=0;i<lineCount;++i){
const int index=(write_-delay_[i])&(ringFrames-1);
const float sample=memory_[i][index];
const float sample=(realtimeMode_&&validFrames_<delay_[i])
?0.f:memory_[i][index];
lowpass_[i]+=dampCoeff_*(sample-lowpass_[i]);
if(realtimeMode_)gain_[i]+=slew_*(targetGain_[i]-gain_[i]);
y[i]=sample;
mix[i]=lowpass_[i]*gain_[i];
}
Expand Down Expand Up @@ -96,6 +123,7 @@ class SonKuMusicalReverb final {
(mid*inMid[i]+side*inSide[i]);
}
write_=(write_+1)&(ringFrames-1);
if(realtimeMode_&&validFrames_<ringFrames)++validFrames_;
amount_+=slew_*(amountTarget_-amount_);
if(std::abs(amount_-amountTarget_)<1.e-5f)amount_=amountTarget_;
// Wet-only. The KEMAR direct field and physical reflections retain
Expand All @@ -104,6 +132,19 @@ class SonKuMusicalReverb final {
.right=wetRight*.23f*amount_};
}
private:
struct Coefficients {
std::array<float,lineCount> gains{};
float damping=0.f;
};
Coefficients makeCoefficients(float rt60,float cutoff) const noexcept {
Coefficients prepared{};
constexpr float pi=3.14159265358979323846f;
prepared.damping=1.f-std::exp(-2.f*pi*cutoff/sampleRate_);
for(int i=0;i<lineCount;++i)
prepared.gains[i]=std::exp(-6.9077553f*
static_cast<float>(delay_[i])/(sampleRate_*rt60));
return prepared;
}
void configure() noexcept {
// Incommensurate lengths at 48k, scaled once at prepare/control side.
// First late energy arrives ~44 ms: behind earliest image reflections.
Expand All @@ -123,11 +164,13 @@ class SonKuMusicalReverb final {
static_assert((ringFrames&(ringFrames-1))==0);
std::array<std::array<float,ringFrames>,lineCount> memory_{};
std::array<float,lineCount> lowpass_{};
std::array<float,lineCount> gain_{};
std::array<float,lineCount> gain_{},targetGain_{};
std::array<Coefficients,3> prepared_{};
std::array<int,lineCount> delay_{};
float sampleRate_=48000.f,dampCoeff_=0.f,slew_=0.f;
float sampleRate_=48000.f,dampCoeff_=0.f,targetDamp_=0.f,slew_=0.f;
float amount_=0.f,amountTarget_=0.f;
int write_=0;
int write_=0,validFrames_=0;
bool realtimeMode_=false;
SonKuReverbPreset preset_=SonKuReverbPreset::StudioGlue;
bool ready_=false;
};
Expand Down
42 changes: 40 additions & 2 deletions engine/builtin_fx/sonku/SonKuSpatialCore.h
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,15 @@ struct Settings {
float outputTrim = 0.75f; // avoid summing two uncorrelated emitters at unity
bool moving = true;
bool clockwise = true;
// Version-2 persisted, native-ACKed acoustic scene. Zero is legacy
// HRTF-only. All other scenes are optional and OFF unless selected.
int spacePreset = 0; // 0=OFF, 1=Square 7.2, 2=Chamber 14.4, 3=Large 28.8
float sourceDistanceMeters = 1.6f;
// Stored while OFF so the first selected scene is immediately audible
// and turning ROOM off/on remembers the previous wet preference.
// spacePreset=0 still guarantees identical legacy HRTF-only PCM.
float roomAmount = .55f;
float ambience = .30f;
};
inline bool valid(const Settings& s) noexcept {
return std::isfinite(s.startAzimuthDegrees) &&
Expand All @@ -30,7 +39,16 @@ inline bool valid(const Settings& s) noexcept {
std::isfinite(s.stereoSpreadDegrees) && s.stereoSpreadDegrees>=0.f &&
s.stereoSpreadDegrees<=180.f &&
std::isfinite(s.spatialMix) && s.spatialMix>=0.f && s.spatialMix<=1.f &&
std::isfinite(s.outputTrim) && s.outputTrim>=0.f && s.outputTrim<=1.f;
std::isfinite(s.outputTrim) && s.outputTrim>=0.f && s.outputTrim<=1.f &&
s.spacePreset>=0 && s.spacePreset<=3 &&
std::isfinite(s.sourceDistanceMeters) && s.sourceDistanceMeters>=1.6f &&
s.sourceDistanceMeters<=10.f &&
std::isfinite(s.roomAmount) && s.roomAmount>=0.f && s.roomAmount<=1.f &&
std::isfinite(s.ambience) && s.ambience>=0.f && s.ambience<=1.f &&
(s.spacePreset==0 || SonKuEarlyReflections::validGeometry({
s.spacePreset==1?7.2f:s.spacePreset==2?14.4f:28.8f,
s.spacePreset==1?7.2f:s.spacePreset==2?14.4f:28.8f,
s.sourceDistanceMeters}));
}
inline double wrapDegrees(double degrees) noexcept {
degrees=std::fmod(degrees,360.0);
Expand All @@ -53,7 +71,10 @@ class SonKuSpatialCore final {
if(!room_.prepare(rate)||!reverb_.prepare(rate))return false;
reset();
ready_=true;
return true;
// Re-publish a saved active scene after device restart, but do NOT
// select the new realtime FDN program for the legacy/offline default:
// original Studio Glue / Airy Chamber listening renders remain exact.
return settings_.spacePreset==0 || applyAcousticSettings(settings_);
}
void reset() noexcept {
for(auto& channel:history_)channel.fill(0.f);
Expand All @@ -75,6 +96,11 @@ class SonKuSpatialCore final {
if(!s.moving || !settings_.moving ||
s.startAzimuthDegrees!=settings_.startAzimuthDegrees)
degrees_=wrapDegrees(s.startAzimuthDegrees);
const bool changed=s.spacePreset!=settings_.spacePreset ||
s.sourceDistanceMeters!=settings_.sourceDistanceMeters ||
s.roomAmount!=settings_.roomAmount ||
s.ambience!=settings_.ambience;
if(changed && !applyAcousticSettings(s))return false;
settings_=s;
remaining_=0;
return true;
Expand Down Expand Up @@ -178,6 +204,18 @@ class SonKuSpatialCore final {
}
}
private:
bool applyAcousticSettings(const Settings& s) noexcept {
const float width=s.spacePreset==1?7.2f:
s.spacePreset==2?14.4f:28.8f;
const SonKuRoomGeometry geometry{
width,width,s.spacePreset? s.sourceDistanceMeters:1.6f};
const auto preset=s.spacePreset==3?SonKuReverbPreset::LargeRoom:
s.spacePreset==2?SonKuReverbPreset::AiryChamber:
SonKuReverbPreset::StudioGlue;
return room_.setRealtimeRoom(geometry,s.roomAmount,s.spacePreset!=0) &&
reverb_.setRealtimeProgram(preset,
s.spacePreset!=0?s.ambience:0.f);
}
// 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 {
Expand Down
Loading
Loading