Skip to content
Merged
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
768 changes: 767 additions & 1 deletion CMakeLists.txt

Large diffs are not rendered by default.

43 changes: 43 additions & 0 deletions docs/SONKU_P94_FRONT_REAR_EXTERNALIZATION_FAT_20261116.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
# SonKu P9.4 — Front/Rear Externalization A/B (2026-11-16)

**STATUS: PRIVATE HEADPHONE FAT CANDIDATE / DRAFT, NOT ACOUSTICALLY VERIFIED.**

## Baselines / preservation
- Production main: `37985f02caecd93b22f853183888d81e18dc6736`.
- Operator-confirmed P9.1/P9.2: `763706a15a2617a10d23b5e2e43eb5689e454ccb`, frozen at `checkpoint/sonku-p91-p92-operator-confirmed-20261116`, issue #720.
- P9.3 GUI: draft PR #721; original perspective **ellipse** (148×83 SVG) is the APPROVED 3D oblique view of a circular 360° audio orbit. It is not the fault. Its movable modeless window, accepted FX Power, preset scenes and SPACE layout are inherited without changes.
- P9.4 starts from PR #721 head and adds *only* an explicitly opt-in spatial-depth experiment to the actual P9 native renderer. No upstream PR/main/checkpoint source is changed.

## What the listener actually reported
At equal physical source radius and continuous 360° orbit, front (0°) and rear (180°) are perceived too close to the listener while ±90° lateral positions feel farther away. A person perceives a *flattened acoustic orbit*, **not a faulty UI ellipse**.

The P9.1 renderer already uses a world-anchored two-speaker KEMAR 2×2 measured-HRIR field and LF foundation. It centres correlated stereo content at the actual median-plane HRIR. With a non-individualized HRTF, front/back spectral cues and distance externalization can be weak despite geometrically correct source angles. Older P9 direct/ER/tail levels have no head-relative angular externalization compensation. This is a perceptual limitation to investigate, not proof the DSP position calculation is elliptical.

## P9.4 A/B hypothesis and code contract
Research in binaural externalization relates localization to HRTF pinna fine structure, listener/head rotation, individualized headphone calibration, binaural reflections and direct-to-reverberant ratio (DRR); increasing diffuse reverb alone is not proven to fix it. A published 2026 frontal-source study also discusses direct and reflection level adjustment in generic BRIRs. Such research motivates a **bounded test**, not any claim of dearVR parity.

`SonKuP94FrontBackDepthCue.h` is a fixed-size, 45ms-slewed median-plane angular weighting computed on the existing 16-sample HRTF retarget cadence. It uses a 361-entry table prepared once, no allocation, locks, timers, FFT, or trigonometry in the per-sample audio callback.

- Head-relative centre azimuth: `p83::toHead(worldCenter, yaw)`. Never use SVG pixel coordinates or pretend the speaker moved closer.
- Weight: `cos^4(theta)`: 1 at 0° and 180°, 0 at ±90°; smooth and periodic at the wrap.
- For P9 only and if room + early reflection wet are ON: multiply the **already measured HRTF direct pressure** by `1-0.045*w` (max −0.40 dB), and its **directional early reflections** by `1+0.28*w` (max +2.14 dB). Late reverb, bass room modes, KEMAR spectral coefficients, ITD, ILD, source distance, orbit phase, output gain and stereo MID/SIDE graph are unchanged. The front/rear direct/early pressure-ratio proxy changes by at most about −2.54 dB. The ROOM OFF / ER=0 return is exactly neutral. This is **not** a measured personalized BRIR, not a cabinet resonance model and not a substitute for head tracking.
- The feature is compiled only with `-DARMIX_SONKU_EXPERIMENTAL_P94_FRONT_BACK_DEPTH=ON` and P9 already enabled. Default builds OFF, compile-time guard rejects P9.4 without P9.
- No state schema/ABI change: `renderMode=9` remains authoritative, but native readback `p94FrontBackDepthCue=true` specifically identifies this experimental build. UI label `P9.4 · FRONT/REAR DEPTH (A/B)` appears only for that genuine capability. P9.1-only builds still say P9.1+P9.2.

## Automated acceptance & safety boundaries
- Test real source PCM at 44.1/48 kHz, static 0/90/180/270 with ROOM ON/OFF, mono-like stereo and strict anti-phase, 64 vs 256-frame bit-parity, finite output + existing 0.98 linked peak guard.
- Isolate the curve itself: equal front/rear gains, lateral exactly neutral once smoothed, bounded ratio correction, head-yaw turns world FRONT into head SIDE, wrap continuity. Re-run existing P9.1/P9.2 PCM, P9.0 coherence, P8.9, GUI dropdown and Chromium tests.
- Exact source build of Windows native mixer + CTest and portable artifact must PASS before operator FAT. Keep draft, do not merge to main.

## Mandatory headphone FAT / rejection conditions
- Compare ***original checkpoint P9.1+P9.2***, PR #721 GUI-only and P9.4 at matching integrated loudness (±0.5 LU) on the SAME device/headphones. Play actual music: kick, bass guitar, low-level room content, vocals, percussive transients, and 30–180Hz anti-phase material.
- Orbit static stepped 0, ±45, ±90, ±135, 180; then continuous slow 6–12s with head yaw 0/90/180 and fixed 1.6/3.1m source distance. Record perceived distance (front/right/back/left), front-back reversals, tonal degradation, and whether room returns become echoes/boom.
- Inspect measured signal energy and short-time binaural interaural coherence per direction, direct/ER cross-correlation, potential transient smearing, limiter gain reduction, and true loudness against raw music.
- **Reject P9.4** if user perceives no appreciable improvement, music becomes more reverberant/distant but not externalized, integrated level moves >0.5 LU without intentional user gain, or bass/treble/phase and ASIO stability regress. Retain accepted checkpoint. Real HRTF personalization/head tracking/BRIR options remain future work.

## References / cautions
- Sound Externalization: A Review of Recent Research. https://pmc.ncbi.nlm.nih.gov/articles/PMC7488874/
- Auditory localization: a comprehensive practical review. https://pmc.ncbi.nlm.nih.gov/articles/PMC11267622/
- Enhancing Externalization of Frontal Virtual Sound Sources in Binaural Synthesis via Level and Reflection Adjustment of Non-individualized BRIRs (2026). https://doi.org/10.1177/23312165261468752

No claims that these articles establish the optimal numeric .045/.28 values: those are **research calibration candidates** requiring controlled audio comparison.
28 changes: 28 additions & 0 deletions docs/SONKU_P95_IMMERSIVE_MUSIC_VENUE_FAT_20261116.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
# SonKu P9.5 Immersive Music & Venue — acceptance and architecture (2026-11-16)

**PRIVATE DRAFT: no public release, no claim of dearVR acoustic parity.**

## Operator sound reference
The operator likes P9.1/P9.2 **music fidelity, real separation and living external sound** but wants deeper front/back and a much larger sound-system presentation, with powerful yet controlled bass. Reference screenshot settings: P9.4 mode, 6.5 s orbit, 82° spread, MIX 100%, GAIN +7dB, LARGE room 28.8×28.8m, distance 3.1m, reflections 100%, reverb 62%, plus rear/front distance concern. This is the starting reference, **not** a verified universal optimum.

## Protected checkpoints
- Operator-accepted P9.1/P9.2: `763706a15a2617a10d23b5e2e43eb5689e454ccb` checkpoint issue #720
- GUI-only PR #721 retains 148×83 *visual perspective ellipse* as the correct 3D view.
- P9.4 PR #723 provides real measured KEMAR source with bounded median-plane DRR adjustment; no claim of measured individual BRIR.
- P9.5 is an isolated child branch. No merge into main without headphone FAT.

## P9.5 implemented engineering
1. **Bypass animation** — the JS visual PLL stops integrating when accepted native FX state is OFF / RACK OFF / UNKNOWN. Discard stale observed azimuth on disable. Do not reset to 0 on every 250ms readback. Resume only from current native telemetry; freeze visual pose while audio callback bypassed. Native FX rack remains sole audio authority.
2. **One latest-engine selector** — no confusing P8.4/P8.9/P9.0/P9.4 research catalog for a P9.5-capable build; legacy saved mode can be displayed honestly as legacy session and switched to latest by explicit operator action, never silently rewritten.
3. **Factory scenes** — five deliberate starting points, full native setting transaction + ACK/readback, editable afterwards: Signature 3.1m/100% ER/62% late/+5.6dB (1.9x linear), Large Studio 4.8m/94% ER/72% late/+4.3dB, Cinema 7.5m/100% ER/84% late/+4.6dB, Venue 10m/100% ER/100% late/+5.1dB, Live Orbit 6.5m/100% ER/83% late/+4.9dB. All use the physical LARGE 28.8m room model, **not claimed as distinct new BRIR measurements or individually different architectural room designs**. Old SMALL/CHAMBER values remain in the schema for session compatibility.
4. **Default only for NEW P9.5 inserts** — initialize `accepted_` with Signature rather than 1.6m/ROOM OFF/outputTrim .75. `.smix` restore applies saved exact settings. Other experimental/production builds unchanged.
5. **Slow electrical music-presence compensation (opt-in)** — 280ms stereo energy detector, 450ms smoothing of the makeup, update desired max once per 256 PCM samples, upward-only target 1.0..1.65. A near-1dB electrical minimum is a **target, not guaranteed loudness** with strong transients. Never reduce explicitly requested positive GAIN. Existing linked 0.98 sample peak limiter remains, peak safety comes before any claiming of dynamic improvement. P9.5 only, no WebAudio, heap, second graph, or front/rear geometry changes. Force bypass at 0% mix.
6. **Large venue low-frequency foundation** — existing three finite-Q room modes increase by at most 18% on the ROOM=Large wet modal return, *not* on direct bass; no fake subwoofer box or hidden low shelf. Bass/treble integrity and attack must survive field tests.
7. **No new .smix schema**: mode9 and typed native settings remain the same, new feature advertised only by `p95MusicalPresence` readback. Existing saved state is authoritative.

## FAT / reject
- Linux source P9, P9.1/P9.2, P9.4 baseline PCM checks, P9.5 44.1/48k and stereo anti-phase, 64/256 buffer parity; UI Chromium with bypass motion freeze and 5 scene transaction/readback.
- Windows actual JUCE + V11 state ACK, GUI portable, checks / source provenance. No release until operator listens.
- Critical loudness: equal-gain A/B and user-preferred +gain A/B are **separate**. Compare integrated loudness, short-term crest factor and limiter activity; do NOT select louder just because it wins unblinded A/B.
- Headphones, same device / gain path / speaker fader / source, actual 0/90/180/270 and 6–12 second orbit, 3.1m/7.5m/10m; compare bass drum punch, 50–120Hz notes, cymbal air and stereo music separation. Retain P9.1/P9.2 baseline for quick revert. Reject if boost causes pumping, peak flatlining, harshness, mono collapse, spurious echoes, or ASIO interruptions.
- Important known ceiling: these five named scenes still share existing native large-room geometry and algorithm. True physically distinct cinema/venue BRIRs need new early-reflection geometry, materials, speaker directivity, and listening measurements. Label this as a FOUNDATION, not completed dearVR equivalent.
25 changes: 25 additions & 0 deletions docs/SONKU_P96_DISTANCE_REINFORCEMENT_FAT_20261116.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
# SonKu P9.6 — Distance Without Losing Bass & Air (PRIVATE FAT, 2026-11-16)

**Research branch, not approved sound, no public release.** Child of P9.5 PR #725 exact head b895d92c1706ab0e098bfe49447fa7b83058f865. Do not merge competing P9.5 #724 changes or alter frozen operator-approved P9.1/P9.2 checkpoint 763706a1. Preserve approved visual ellipse and P9.5 bypass/GUI fixes.

## Proven source root cause

In native P9 mode 9, with ROOM enabled, the complete direct KEMAR ear pressure is multiplied by 1/(1+0.27*(distanceMeters-1.6)), reaching **0.306x at 10m**. World-speaker LF shares the attenuation, while independent room returns can still dominate midrange. P9.5 RMS makeup / output trim do not selectively restore LF / HF. This identifies an engineering mechanism, not a listening-quality proof.

Research basis: https://pmc.ncbi.nlm.nih.gov/articles/PMC5479918/ finds atmospheric HF loss in the 1–15m range relatively small; https://pmc.ncbi.nlm.nih.gov/articles/PMC4744263/ discusses distance/DRR. The target is a **sound-reinforced concert speaker** rather than literal free-field attenuation.

## Narrow change

- OFF-by-default native flag ARMIX_SONKU_EXPERIMENTAL_P96_DISTANCE_REINFORCEMENT, requires P9.5 and P9 world source. P9.5 with flag OFF is preserved.
- P9 mode 9 only, with room ON and distance above 2m: split SAME HRTF-positioned direct ear pressure with causal 170Hz and 4.2kHz complementary first-order filters; retain more bass and air while preserving early/late wet and original source position.
- Slowly ramp distance retention over 35ms, no headlocked dry bass, no second graph, no extra FIR/delay/FFT/heap. P9.4 front/rear calibration remains multiplicative outside this band split.
- At 10m, target LF/mid/HF direct pressure gains ~0.83/0.50/0.77 before crossover rolloffs; locally tested sinus probes are approximately 0.79 at 70Hz, 0.50 at 800Hz and 0.65 at 7.5kHz. NOT verified final-output/headphone loudness.
- ROOM OFF / <=2m preserves original direct samples after transition settles; schema v11 unchanged. Native capability p96DistanceReinforcement is emitted only from the opted-in native build.
- Existing limiter (linked 0.98 sample peak), P9.5 music presence and saved sessions are unchanged.

## Acceptance before merge or release

1. 44.1/48k isolated native tests: ROOM OFF, <=2m exact direct samples, LF/MID/HF spectral energy, anti-phase, finite output; full P9.5 core P96-on source compile/render at 0/90/180/270 and 64/256 buffers.
2. Exact-head Windows JUCE/native ACK/CTest and source-provenance bundle. Do not claim CI or audio-device FAT until inspected.
3. A/B reference P9.5 versus P9.6 on headphones at 2m / 5m / 7.5m / 10m, identical input, source angle and gain; compare measured band RMS, LUFS/crest/peak protection, then loudness-match for subjective depth.
4. REJECT if distance collapses, highs become harsh, kick masks vocal, reverb becomes dry or limiter pumps. Do not claim dearVR parity without headphone evidence.
31 changes: 31 additions & 0 deletions docs/SONKU_P97_STAGE_IMPACT_FAT_20261116.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
# SonKu P9.7 Stage Impact and External Presence — PRIVATE FAT, 2026-11-16

**Selected listening checkpoint:** P9.6 PR #727 head `720cec619b41aa601414d4b5ae664cb418f04ca1`. User confirmed P9.6 is already reasonably good; preserve it immutably for A/B. P9.7 is a child branch and does not rebase P9.6, alter `main`, merge the competing P9.5 PR #724, or change old .smix bytes.

## Research, limits, and actual algorithm

- [Sound Externalization: A Review of Recent Research](https://pmc.ncbi.nlm.nih.gov/articles/PMC7488874/) describes the significance of direct pinna cues, realistic interaural differences in reverberation, and room/source congruence. Real externalization requires headphone listening and cannot be proven by spectral gain or generalized KEMAR only.
- [Jiang et al., effect of pinna filtering](https://doi.org/10.1016/j.apacoust.2020.107257) finds direct pinna filtering helps externalization whereas applying it to diffuse reverberation can reduce externalization. We retain the measured direct HRIR and existing non-pinna image-source ER path.
- [AES virtual bass review](https://aes.org/publications/elibrary/elibrary-page/?id=18050) documents perceived bass versus distortion risks. We DO NOT generate missing-fundamental harmonics, synthesize extra LFE, or attach a headlocked mono bass.

One opt-in **native P9.7** component (`SonKuP97StageImpact.h`) adds three bounded paths to the existing P9 mode-9 scene only when ROOM is ON and distance is above 2m. All parameters are research constants, not hardcoded .smix fields or hidden GUI pseudo-controls:

1. **Concert punch / room body:** prepared, low-Q ~85Hz bandpass at +0.23 relative peak to the already HRTF/P9.6-processed direct ear pressure; one-pole 62Hz sub body at +0.085. The existing P9.2 position-aware damped 3-mode low-frequency *room return* is modestly increased by at most 12%, without modifying resonator decay or creating uncontrolled feedback.
2. **Center-panned presence (not vocal separation):** low-Q ~1.9kHz bandpass of INPUT L+R MID with at most +0.19 on both virtual speaker source feeds, before existing full KEMAR HRIR convolution. The center-band is filtered twice to suppress high-frequency phase leakage, and a further modest +0.085 centered presence band is added to the *already HRIR-positioned direct ears*, never a dry mono voice. The original stereo feeds remain authoritative for decoder observation, P9.2 world bass and room reflections. No dry/headlocked vocal injection or extra FIR. This can enhance centered vocal *and centered instruments*; it is NOT an AI stem separator.
3. **Early-reflection air:** +0.24 of the high-pass complement above 4.5kHz, applied only to the existing two-ear directional early-reflection result. No inter-channel mixing, Haas timing, repeated reverb worker or extra spectral EQ on the diffuse tail. This aims to improve high-frequency spatial cues without simply making room reverb hissier.

A small +0.038 high-frequency direct-air complement preserves the already-external KEMAR cymbal/treble energy when the center-band is boosted, avoiding the earlier P9.7 first-pass regression where 7.5kHz electrical energy fell by ~13% at 10m. An explicit no-high-loss test now rejects that outcome. P9.5's adaptive upward makeup was found to reduce its overall gain as P9.7 made bass and center louder; in the first integrated candidate 7.5kHz remained ~16% below P9.6 even after the center-band filter was narrowed. A bounded 135Hz low complement (+0.080 max) and 4.5kHz high complement (+0.35 max) are therefore applied to the **already externalized, post-P9.5 stereo ear signal** immediately before the unchanged linked 0.98 peak guard. This last-stage gain is not an extra dry/stem/reverb path, and identical bilateral coefficients preserve channel-based localization cues. A test checks spectral output *after* P9.5 normalization. Reject the design if the limiter's dynamic pumping increases on music FAT.

All P9.7 source, direct/early/modal and post-makeup stages are explicitly disabled at 0% spatial MIX so the existing native dry/bypass is preserved bit for bit; the full-PCM hash verifier covers that case with ROOM still enabled at 10m.

The three gains ramp together over 45ms as distance moves through 2–6m. All bands use control-side prepared coefficients, bounded stable filters, fixed memory and no callback allocations. No new EQ slots, public schema, selectable render modes, fake stereo widening or additional HRTF graph. P9.5 output makeup and 0.98 linked peak guard remain unchanged.

## Gates before approving listening audio

1. Independently compile 44.1/48k source tests for exact ROOM OFF, 0% spatial MIX with active ROOM, and <=2m, voice/air/bass response, finite PCM, antiphase symmetry, bounded room-modal amplification and no device-restart stale memory.
2. Compare complete P9.6 and P9.7 native PCM *hashes* at 2m and ROOM OFF, and target bands at 3.1m and 10m (front and back) for 44.1/48k, using the very same source fixture. The checkpoint must remain bit-for-bit identical in disabled scenes. This guards known-good sound rather than relying on nominal gains.
3. Compile exact Windows JUCE application, V11 state/ACK, sample-peak safety CTests, UI Chromium and source-provenance portable in a branch-qualified build. No public release/merge based on a green Linux source test alone.
4. Operator headphone A/B at matching LUFS and also matching *GAIN setting*: kick/tom attack, bass audibility and decay, center vocal location and intelligibility, edge/cymbal air, interaural position, stage distance, reverb body, 0/90/180/270° and 44.1/48k. Reject nasal vocals, metallic cymbals, mono collapse, bass masking, over-limiter pumping, apparent image moving inside the head. User preference controls promotion.
5. No marketing claim of source-separated vocals, customized individual BRIR, measured live concert loudspeaker impulse response, true-peak certification or dearVR acoustic parity.

**Checkpoint:** P9.6 remains branch/PR #727 and this draft P9.7 is entirely removable by deleting its child branch. Feature OFF recovers P9.6 binary behavior and no new user parameter exists.
Loading
Loading