Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
ce7c658
feat(sonku-v2): fixed-memory directional image-source early reflectio…
masarray Nov 13, 2026
b6df9a0
test(sonku-v2): A/B identical-source WAVs, PCM parity and exact-causa…
masarray Nov 13, 2026
2dfc5d4
docs(sonku-v2): externalization image-source model and gated A/B design
masarray Nov 13, 2026
2fe3df6
fix(sonku-v2): finite room shutdown and exact zero bypass after slew
masarray Nov 13, 2026
272b198
perf(sonku-v2): same-runner V1 vs early-reflection CPU comparison at …
masarray Nov 13, 2026
59f18b1
feat(sonku-v2): render uninterrupted two-turn 20s orbit with seam and…
masarray Nov 13, 2026
2b6d2b2
feat(sonku-v2): 20s square-room diagnostic orbit and mirrored reflect…
masarray Nov 13, 2026
409ed5d
feat(sonku-v2): two-turn clockwise and counterclockwise binaural A/B set
masarray Nov 13, 2026
e1ac004
merge(sonku): reconcile latest approved GUI/native bridge base withou…
masarray Nov 13, 2026
3a74b02
test(sonku-v2): import room-shape enum in mirror symmetry fixture
masarray Nov 13, 2026
a5a1b5a
merge(sonku-v2): reconcile latest native GUI Windows UTF-8 and PCM fi…
masarray Nov 13, 2026
3aca183
feat(sonku): bounded eight-line stereo FDN late ambience with prepare…
masarray Nov 13, 2026
30a75ef
test(sonku): musical FDN impulse/PCM/CPU gates and 2x orbit A-B liste…
masarray Nov 13, 2026
880e158
feat(sonku): original plucked-tone musical A/B on approved square orbit
masarray Nov 13, 2026
63a85fb
test(sonku): compare late FDN against exact approved square PCM baseline
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
8 changes: 8 additions & 0 deletions .github/workflows/ui-smoke.yml
Original file line number Diff line number Diff line change
Expand Up @@ -213,6 +213,14 @@ jobs:
run: |
g++ -std=c++20 -O2 -Wall -Wextra -pedantic tools/sonku_offline_listening.cpp -o /tmp/sonku-listening
/tmp/sonku-listening sonku-listening
g++ -std=c++20 -O2 -Wall -Wextra -pedantic tests/sonku_early_reflections_test.cpp -o /tmp/sonku-room-test
/tmp/sonku-room-test
g++ -std=c++20 -O2 -Wall -Wextra -pedantic tests/sonku_musical_reverb_test.cpp -o /tmp/sonku-fdn-test
/tmp/sonku-fdn-test
- name: SonKu same-runner realtime CPU comparison (informational, not a release pass)
run: |
g++ -std=c++20 -O2 -Wall -Wextra -pedantic tools/sonku_rt_benchmark.cpp -o /tmp/sonku-rt-bench
/tmp/sonku-rt-bench
python tests/sonku_offline_demo_contract.py sonku-listening
- name: Publish 8D-SonKu reproducible listening WAVs and blind answer key
if: ${{ always() }}
Expand Down
4 changes: 4 additions & 0 deletions docs/ARD_8D_SONKU_BINAURAL_ENGINE_20261112.md
Original file line number Diff line number Diff line change
Expand Up @@ -151,3 +151,7 @@ This record supersedes the earlier **round/circular stage UI** and radial 2D mar
- **No extra renderer or CSS owner**: add to existing one /preview/ editor and existing `mixer-fx-rack.css`, maintaining exactly 18 CSS owner links. No WebAudio, DSP JS clone, extra callback or CPU-intensive continuous 3D scene.
- **Verification evidence**: Chromium assembled native GUI two viewport screenshots, actual FX picker insertion and ACK/readback, four acoustic directions, front/rear painter order, both monitors visible at 0° spread, real mouse drag to FRONT, rotary drag with one typed native request. Exact SHA `4652a744ab4ae01b1ceca58bb6c3d7e372eb420a`, [UI run](https://github.com/masarray/arsonmix/actions/runs/43342451656), [two screenshots](https://github.com/masarray/arsonmix/actions/runs/43342451656/artifacts/13999089726).
- **Release gate**: browser FAT uses simulated JUCE events. It is not physical binaural localization or installed Windows/ASIO FAT, and the PR must be reconciled with advancing `main` before any public release.


## 2026-11-13 — V2 spatial externalization architecture
See docs/SONKU_V2_EXTERNALIZATION_DECISION_20261113.md. Experimental room processing is opt-in and OFF in native JUCE until qualified with headphone A/B. Fixed bounded image-source early reflections retain the same single PCM authority; future ITD-aligned HRIR implementation is a separate stage.
4 changes: 4 additions & 0 deletions docs/PRD_8D_SONKU_SPATIAL_AUDIO_20261112.md
Original file line number Diff line number Diff line change
Expand Up @@ -100,3 +100,7 @@ Both L and R studio monitor speakers must remain separately visible and individu
The editor must feel like a compact hardware-grade audio plugin, with tactile rotary controls and clear numeric readouts, not large web-style cards or anonymous browser sliders. Rotary pointer gestures must be bounded and single-commit; keyboard focus, range semantics and double-click default restoration remain accessible. Do not imitate or redistribute commercial plugin skins.

Acceptance evidence on the real compiled native HTML bundle must cover correct Z-order, actual PNG load, two separately visible monitors at 0° spread, correct four-direction mapping, mouse drag to FRONT, knob edit single native queue/ACK and desktop/narrow screenshots. Do not translate GUI PASS into a claim of verified binaural headphone localization.


## 2026-11-13 — perceptual acceptance and UX guardrails
User reports correct 8/8 blind positions and 4/4 known, but insufficient FRONT/REAR distance and uneven perceived motion. Preserve the correct azimuth signs and build same-input, level-checked original-vs-V2 headphone WAVs first. No extra controls or labels before sound is validated. A future SPACE knob must be compact, discoverable and backed by native typed ACK/readback and compatible session migration; default must remain user-test-proven rather than arbitrary reverb.
53 changes: 53 additions & 0 deletions docs/SONKU_V2_EXTERNALIZATION_DECISION_20261113.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
# 8D-SonKu V2 — Externalization & Natural Orbit Architecture
2026-11-13 | Experimental stage M1 | Based on PR #606 baseline

## Confirmed user observations
- Headphone listener reports correct directions, 4/4 known and 8/8 blind.
- FRONT/REAR are too thin/near-head and motion through both median-plane axes lacks realistic depth.
- This is a perceptual report, NOT a measured distance, CPU benchmark or proof of identical HRTF fit for all listeners.

## Technical research and prior art (no code or skin copying)
- Allen & Berkley (1979), Image Method for Efficiently Simulating Small-Room Acoustics, JASA 65(4), DOI 10.1121/1.382599 — geometrical mirror-image first-order acoustic paths and time-of-flight.
- Steam Audio core guide: https://github.com/ValveSoftware/steam-audio/blob/master/core/doc/guide.rst — direct binaural HRTF, room reflections and distance effects are separate, testable stages.
- 3D Tune-In Audio Toolkit: https://github.com/3DTune-In/3dti_AudioToolkit — ITD-independent HRIR interpolation and acoustic parallax are mature solutions, *research for later M2*, not implemented here.
- Frontal externalization BRIR study: https://pmc.ncbi.nlm.nih.gov/articles/PMC13451706/ — altered early reflections and direct/reflected ratio can improve front externalization for some listeners, not a guaranteed result on all headphones.

## Current implementation decision: split M1 from the other acoustic stages
Keep SonKuSpatialCore and native JUCE/PCM graph as one authoritative processor; no new DSP engine, new device callback, JS audio path, thread, blocking call, file access or dynamic callback allocation. Add SonKuEarlyReflections as a fixed-memory, first-order image-source *experimental* room stage. Amount=0 by default and guarantees identical previously qualified native PCM. Amount=.55 generates *offline-only* A/B comparison WAVs using the exact original source samples and direct KEMAR HRIR. Do not publish this as a new default until blind headphone tests support it.

### Bounded acoustic model (M1)
- Room width 6.4m, depth 8.0m, listener centered, 2 sources at 1.6m rotating on the horizontal ring.
- Four first-order wall images per source (left, right, front, rear), hence eight reflected paths.
- Delay in samples = (distance from image - direct source distance) / 343m/s × sample rate, plus a small symmetric ear baseline to create directional ITD; gains = wall reflectivity × directDistance/pathDistance × fixed safety factor.
- Mild source low-pass, ear-directional ITD/ILD approximation; NOT HRTF-convolved reflected signals or FDN reverb.
- Fixed 8192-frame power-of-two ring for each source (~64KiB total) and fractional-delay interpolation; geometry updates every 64 frames while delay and gains smoothly follow per-sample.
- Works at 44.1/48k; conservative fixed delay bounds; original direct HRTF FIR, stereo dry, spatialMix, outputTrim, ASIO and native ACK/readback remain untouched.
- One C++ unit gate, one exact-core integration parity test, two A/B WAV comparisons and a bounded CPU comparison before Windows FAT.

## Staged next steps (NOT yet delivered)
M2: ITD/time-aligned measured HRIR preprocessing + fractional ear delay, grid-point identity and phase/ILD regression; no generic "phase aligned" switch without proving source accuracy.
M3: if needed, prepared HRTF-filtered reflections with bounded convolution and room distance parameter.
M4: only after successful listening trials, a compact SPACE control with native typed lease, accepted ACK/readback, versioned session schema and a calibrated default. No extra user-facing page.
M5: optional low-cost FDN late reverb, several HRTF profiles / calibration and head tracking after measured CPU and perceptual evidence.

## Listening gate
Compare the legacy source-accurate 4-direction WAV and 10s orbit with two V2 files rendered from EXACT same input samples. Match perceived level, listen on headphones with OS virtualization off. Measure 8-direction mapping, front/rear distance, orbit continuity, colorations, metallic echoes and time-varying flutter. If room worsens direction or sound quality, keep amount=0. CI PCM PASS alone does not prove spatial externalization.

## 2026-11-13 listener feedback and two-turn orbit gate
Listener recognizes direction but describes a noncircular perceived orbit: RIGHT → FRONT is pleasing, yet FRONT/RIGHT/REAR continuity feels incomplete and FRONT subjectively nearer. The room is **rectangular 6.4 × 8 m**, so reflected image distances and directional/temporal profiles vary across axes. This is one plausible contributor, not a proven cause; non-individual HRTF and ITD-inconsistent HRIR interpolation remain other hypotheses.

The offline evaluation now renders a **single uninterrupted 20-second, 2 × 360° clockwise trajectory** (10 seconds/turn) for both legacy direct HRTF and rectangular-room A/B. Only fade in at time 0 and fade out at 20 seconds; no fade/reset/offset at the 10-second boundary. Landmarks: FRONT 0/10/20s; RIGHT 2.5/12.5; REAR 5/15; LEFT 7.5/17.5. PCM tests verify 960,000 frames, non-silent seam, fixed rate and output sign, and C++ end-of-two-turn phase closure. Do not market a verified circular perceptual effect until headphone evaluation.

## 2026-11-13 — rectangular vs symmetric-room controlled comparison
The report of an elliptical/unequal-distance orbit does NOT prove a room-model bug. Alongside V1 direct HRTF and the existing rectangular 6.4×8m image-source room, a third A/B WAV uses a square 7.2×7.2m room with all wall reflectivities identical. The emitted direct HRTF, sample clock, source waveform and 2×360° motion remain identical. The square wall layout has fourfold rotational geometry and tests whether wall distance contributes to perceived asymmetry; it is NOT a circular room or a promised perceptual cure. C++ tests check left/right mirror of the reflected impulse. A/B only, original native default remains OFF.

## 2026-11-13 — independent reversed-motion listening probes
In response to asymmetrical perceived naturalness of RIGHT→FRONT vs FRONT→RIGHT, add three CCW two-turn WAVs alongside the three clockwise versions. All six are 20 seconds, use the exact same deterministic original noise, same native HRTF and DSP sample clock, and have no loop seam. Clockwise: FRONT → RIGHT → REAR → LEFT → FRONT. Counterclockwise: FRONT → LEFT → REAR → RIGHT → FRONT. This allows listening comparison of RIGHT→FRONT (CCW at 7.5–10 and 17.5–20 seconds) with FRONT→RIGHT (CW at 0–2.5 and 10–12.5 seconds), and tests whether perceptual asymmetry reverses with source rotation direction. No additional live motion modes, no UI changes, no assertion of physically circular perception.

## 2026-11-13 — listener-approved Square Orbit checkpoint and musical late reverb M2
The owner has listened to and approved the **square-room orbit as perceptually circular**. Its exact base code is pinned at `checkpoint/8d-sonku-square-orbit-approved-20261113` (`3a74b0273c7a7e13d5d2614183d19995eb12ad57`); this immutable evaluation milestone must not be overwritten by reverb experiments. There already are eight bounded 1st-order wall-reflection paths (four per source), but **there was no late reverb**.

New *opt-in offline candidate*, original `SonKuMusicalReverb.h`: 8 noncommensurate delays with a normalized Hadamard orthogonal feedback matrix, per-line RT60 feedback gains prepared for 44.1/48k, damping low-pass in the loop, stereo decorrelated output, 12ms wet ramp, and at least 43ms to first late energy. Max delay ring 8×4096 floats (~128KiB) with no dynamic PCM buffer, FFT, allpass resonator cascade, or per-sample trigonometry/exp. Two listening-only presets: Studio Glue (RT60 ~0.78s; 5.9kHz damping) and Airy Chamber (RT60 ~1.28s; 7kHz). Wet amount .42 for controlled A/B is intentionally modest and **OFF in the native plugin**. Square early reflections remain exactly as approved, with no room-size or HRTF clock modification. Compare baseline square with Studio Glue and Airy Chamber 20s 2-turn WAVs, using same source, latency, level trim, azimuth and direct HRIR. C++ tests validate stable impulse energy, late onset, stereo width, RT60 decay, byte-exact disabled state and PCM partition parity. No GUI knob, session upgrade or public release until listener feedback and physical Windows audio qualification. FDN theory: Stautner/Puckette (1982), Jot/Chaigne (1991), and practical low-metallic density guidance from Valhalla DSP; original GPL-compatible implementation, no copied commercial source.

## 2026-11-13 — original musical-content A/B
Because broadband noise cannot reveal whether a late reverb is pleasing on music, the exact core offline renderer now also creates a deterministic 20-second synthetic plucked-tone motif, repeated identically once per 360° orbit, under the same Square ER. Three WAVs: baseline late OFF; Studio Glue RT60≈0.78s; Airy Chamber RT60≈1.28s. The melody is originally generated test material, with no copyrighted recordings. Envelope fades within each note to avoid spurious onset clicks. C++ and Python gates verify correct WAV format, PCM non-identity between presets and no clipping. This remains a **perceptual candidate**, not an assertion of musical quality.
Loading
Loading