From 46774ca52db0a00a2071d8e3d1992dc709df7d0f Mon Sep 17 00:00:00 2001 From: Ari Sulistiono Date: Wed, 28 Oct 2026 05:48:39 +0700 Subject: [PATCH 1/8] feat(mixer): compile independent mono/stereo channel and sparse physical input contracts --- engine/core/ChannelRoutingContract.h | 182 +++++++++++++++++++++++++++ 1 file changed, 182 insertions(+) create mode 100644 engine/core/ChannelRoutingContract.h diff --git a/engine/core/ChannelRoutingContract.h b/engine/core/ChannelRoutingContract.h new file mode 100644 index 000000000..f6af59265 --- /dev/null +++ b/engine/core/ChannelRoutingContract.h @@ -0,0 +1,182 @@ +// SPDX-License-Identifier: AGPL-3.0-only +#pragma once +#include "MixerRoutingPlan.h" +#include +#include +#include +#include +#include + +// P1B: device-independent, offline-compiled MONO/STEREO channel contract. +// An enabled physical port is NOT a callback pointer ordinal: sparse ASIO +// masks must be translated by the backend at device setup, never on audio RT. +// This unit deliberately does not activate any JUCE device, FX or mixer GUI. +namespace armix::mixer { + +constexpr int maxPhysicalPorts = 256; + +enum class ChannelFormat : std::uint8_t { followSource, mono, stereo }; +enum class LayoutFault : std::uint8_t { + none, invalidPhysicalPort, duplicateEnabledPort, unavailableSourcePort, + invalidChannelFormat, basePlanRejected +}; +struct LayoutError final { + LayoutFault fault = LayoutFault::none; + int strip = -1; + int physicalPort = -1; + Error baseError {}; +}; + +// Backend-owned control code MUST supply ports in the exact callback pointer +// order negotiated with the driver. Enumerated labels alone are insufficient. +// The physical-port index is device-scoped; portability requires endpoint-ID +// and port-ID validation when restoring a saved Performance on a new PC. +struct InputPortMap final { + std::array callbackIndex {}; + int enabledCount = 0; + + static bool prepare(std::span callbackOrderedPhysicalPorts, + InputPortMap& out, LayoutError& error) noexcept { + error = {}; + if (callbackOrderedPhysicalPorts.size() > maxPhysicalPorts) { + error.fault = LayoutFault::invalidPhysicalPort; + return false; + } + InputPortMap candidate; + candidate.callbackIndex.fill(-1); + for (std::size_t i = 0; i < callbackOrderedPhysicalPorts.size(); ++i) { + const int port = callbackOrderedPhysicalPorts[i]; + if (port < 0 || port >= maxPhysicalPorts) { + error.fault = LayoutFault::invalidPhysicalPort; + error.physicalPort = port; + return false; + } + if (candidate.callbackIndex[port] != -1) { + error.fault = LayoutFault::duplicateEnabledPort; + error.physicalPort = port; + return false; + } + candidate.callbackIndex[port] = static_cast(i); + } + candidate.enabledCount = static_cast(callbackOrderedPhysicalPorts.size()); + out = candidate; + return true; + } + int callbackFor(int physicalPort) const noexcept { + return physicalPort >= 0 && physicalPort < maxPhysicalPorts + ? callbackIndex[physicalPort] : -1; + } +}; + +struct ChannelRoutingConfig final { + Configuration stripsAndMaster {}; + std::array formats {}; // all followSource by default +}; + +struct ChannelRoutingPlan final { + // Existing P1A Plan remains authoritative for mixing/solo/master controls. + Plan base {}; + std::array effectiveFormats {}; + std::array foldStereoToMono {}; + InputPortMap inputPorts {}; + + // Compile/reject on the control thread. Destination is only updated after + // every source, physical pin, mode, gain, pan and master rule passes. + static bool compile(const ChannelRoutingConfig& requested, + std::span callbackOrderedPhysicalPorts, + ChannelRoutingPlan& destination, + LayoutError& error) noexcept { + error = {}; + InputPortMap ports; + if (!InputPortMap::prepare(callbackOrderedPhysicalPorts, ports, error)) + return false; + + Configuration mapped = requested.stripsAndMaster; + std::array effective {}; + std::array folded {}; + for (int i=0; i 0.f ? 1.f-original.pan : 1.f); + out.rightGain = center * original.faderLinear * (original.pan < 0.f ? 1.f+original.pan : 1.f); + } + } + ChannelRoutingPlan ready; + ready.base = candidate; + ready.inputPorts = ports; + ready.effectiveFormats = effective; + ready.foldStereoToMono = folded; + destination = ready; + return true; + } + + // Audio thread: consume *preallocated* stereo scratch supplied by caller. + // No format/device queries, allocation, mutex, trigonometry, or I/O here. + bool extract(int strip, const float* const* input, int availableCallbackInputs, + float* left, float* right, int frames) const noexcept { + if (!base.extract(strip, input, availableCallbackInputs, left, right, frames)) + return false; + if (foldStereoToMono[strip]) { + for (int i = 0; i < frames; ++i) { + const float mono = 0.5f * (left[i] + right[i]); + left[i] = mono; + right[i] = mono; + } + } + return true; + } + void accumulate(int strip, const float* left, const float* right, + float* masterL, float* masterR, int frames) const noexcept { + base.accumulate(strip, left, right, masterL, masterR, frames); + } +}; +} // namespace armix::mixer From f3e7c45817cf74de104b6595fb5be925b71f1eae Mon Sep 17 00:00:00 2001 From: Ari Sulistiono Date: Wed, 28 Oct 2026 05:49:10 +0700 Subject: [PATCH 2/8] test(mixer): validate sparse pins, independent formats, isolation and rollback --- tests/channel_routing_contract_test.cpp | 100 ++++++++++++++++++++++++ 1 file changed, 100 insertions(+) create mode 100644 tests/channel_routing_contract_test.cpp diff --git a/tests/channel_routing_contract_test.cpp b/tests/channel_routing_contract_test.cpp new file mode 100644 index 000000000..c03d9f038 --- /dev/null +++ b/tests/channel_routing_contract_test.cpp @@ -0,0 +1,100 @@ +// SPDX-License-Identifier: AGPL-3.0-only +#include "../engine/core/ChannelRoutingContract.h" +#include +#include +#include +#include +#include +using namespace armix::mixer; +static bool approx(float a, float b) { return std::abs(a-b) <= 0.00001f; } +int main() { + // Sparse physical ports ordered as the callback really delivers them. + // callback[0] = physical 5, callback[1] = physical 2, + // callback[2] = physical 7. Do not assume ordinal == hardware port. + constexpr std::array enabled={5,2,7}; + ChannelRoutingConfig cfg; + cfg.stripsAndMaster.strips[0]={SourceMode::mono,2,-1,1.f,0.f,false,false}; + cfg.stripsAndMaster.strips[1]={SourceMode::stereo,5,7,1.f,0.f,false,false}; + ChannelRoutingPlan plan; LayoutError error; + assert(ChannelRoutingPlan::compile(cfg,enabled,plan,error)); + assert(plan.inputPorts.callbackFor(2)==1); + assert(plan.inputPorts.callbackFor(5)==0); + assert(plan.inputPorts.callbackFor(7)==2); + assert(plan.inputPorts.callbackFor(0)==-1); + std::array p5={0.8f,-0.8f,0.2f}; + std::array p2={0.2f,0.4f,0.6f}; + std::array p7={0.4f,-0.4f,0.6f}; + const float* callback[]={p5.data(),p2.data(),p7.data()}; + std::array l{},r{},ml{},mr{}; + assert(plan.extract(0,callback,3,l.data(),r.data(),3)); + assert(approx(l[0],0.2f)&&approx(r[0],0.2f)); + plan.accumulate(0,l.data(),r.data(),ml.data(),mr.data(),3); + assert(approx(ml[0],.2f*.70710678f)&&approx(mr[0],.2f*.70710678f)); + assert(plan.extract(1,callback,3,l.data(),r.data(),3)); + assert(approx(l[0],.8f)&&approx(r[0],.4f)); + plan.accumulate(1,l.data(),r.data(),ml.data(),mr.data(),3); + assert(approx(ml[0],.8f+.2f*.70710678f)&&approx(mr[0],.4f+.2f*.70710678f)); + + // Source stereo -> channel MONO: pre-FX calibrated 0.5(L+R), + // then equal-power center pan. Side cancellation is deterministic. + cfg.formats[1]=ChannelFormat::mono; + assert(ChannelRoutingPlan::compile(cfg,enabled,plan,error)); + assert(plan.effectiveFormats[1]==ChannelFormat::mono); + assert(plan.foldStereoToMono[1]); + assert(plan.extract(1,callback,3,l.data(),r.data(),3)); + assert(approx(l[0],.6f)&&approx(r[0],.6f)); + assert(approx(l[1],-.6f)&&approx(r[1],-.6f)); + Plan::clearMaster(ml.data(),mr.data(),3); + plan.accumulate(1,l.data(),r.data(),ml.data(),mr.data(),3); + assert(approx(ml[0],.6f*.70710678f)&&approx(mr[0],ml[0])); + + // Source MONO -> channel STEREO: dual mono, no invented width and + // no +3dB jump compared with original equal-power mono center. + cfg.formats[0]=ChannelFormat::stereo; + assert(ChannelRoutingPlan::compile(cfg,enabled,plan,error)); + assert(plan.extract(0,callback,3,l.data(),r.data(),3)); + Plan::clearMaster(ml.data(),mr.data(),3); + plan.accumulate(0,l.data(),r.data(),ml.data(),mr.data(),3); + assert(approx(ml[0],.2f*.70710678f)&&approx(mr[0],.2f*.70710678f)); + + // Physical mapping rejected transactionally: plan stays bit-exact. + const auto old=plan; + cfg.stripsAndMaster.strips[0].inputA=6; + assert(!ChannelRoutingPlan::compile(cfg,enabled,plan,error)); + assert(error.fault==LayoutFault::unavailableSourcePort && error.strip==0 && error.physicalPort==6); + assert(plan.base.strips[0].inputA==old.base.strips[0].inputA); + cfg.stripsAndMaster.strips[0].inputA=2; + cfg.formats[0]=static_cast(99); + assert(!ChannelRoutingPlan::compile(cfg,enabled,plan,error)); + assert(error.fault==LayoutFault::invalidChannelFormat && error.strip==0); + cfg.formats[0]=ChannelFormat::stereo; + constexpr std::array duplicates={5,2,5}; + assert(!ChannelRoutingPlan::compile(cfg,duplicates,plan,error)); + assert(error.fault==LayoutFault::duplicateEnabledPort && error.physicalPort==5); + constexpr std::array outside={5,256,7}; + assert(!ChannelRoutingPlan::compile(cfg,outside,plan,error)); + assert(error.fault==LayoutFault::invalidPhysicalPort && error.physicalPort==256); + assert(plan.base.strips[0].inputA==old.base.strips[0].inputA); + + // Stereo L and R may be nonadjacent in *physical* space, but + // L/R self alias is invalid (fail-closed, not dual-mono by accident). + cfg.stripsAndMaster.strips[1].inputB=5; + assert(!ChannelRoutingPlan::compile(cfg,enabled,plan,error)); + assert(error.fault==LayoutFault::basePlanRejected); + assert(error.baseError.code==Fault::duplicateStereoInput); + cfg.stripsAndMaster.strips[1].inputB=7; + + // 10 channels share 1 input safely: fanout but no extra device pin. + cfg={}; + for(auto& s:cfg.stripsAndMaster.strips) s={SourceMode::mono,2,-1,1.f,0.f,false,false}; + assert(ChannelRoutingPlan::compile(cfg,enabled,plan,error)); + assert(plan.base.activeStrips==10); + for(int i=0;i::quiet_NaN(); + assert(!ChannelRoutingPlan::compile(cfg,enabled,plan,error)); + assert(error.fault==LayoutFault::basePlanRejected && error.baseError.strip==9); +} From 6e4a545ea6acba1581f5da70ecd048189a3a2f86 Mon Sep 17 00:00:00 2001 From: Ari Sulistiono Date: Wed, 28 Oct 2026 05:49:31 +0700 Subject: [PATCH 3/8] build: register mono/stereo port contract in existing CTest gate --- CMakeLists.txt | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 41a59f7f7..8f282d79a 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -19,7 +19,7 @@ juce_add_gui_app(ARMixConsole juce_add_binary_data(ARMixAssets SOURCES web/index.html web/styles.css web/app.js web/bridge.js web/monitor.js) -target_sources(ARMixConsole PRIVATE src/Main.cpp src/LiveAudioEngine.h src/VstOrbitController.h engine/core/MixerRoutingPlan.h engine/core/OrbitPhase.h engine/core/OrbitControlPolicy.h engine/core/OrbitMotion.h engine/core/OrbitDistanceMapping.h engine/core/DearVrPolarPolicy.h src/PluginCatalog.h src/PluginVault.h src/PortableWorkspace.h src/DiagnosticsRecorder.h src/StereoPan.h src/NativePresetArchive.h src/VstBusLayout.h src/LiveGraphHandoff.h src/DiagnosticTone.h engine/core/RealtimeHealthHistogram.h engine/core/CallbackCadenceEvidence.h engine/diagnostics/CrackleEvidenceWindow.h engine/device/AdaptiveClockBridge.h engine/device/AudioProfilePolicy.h engine/device/PeriodCapabilityEvidence.h engine/device/SessionLifecycle.h engine/device/WasapiCapabilityProbe.h engine/device/JuceIndependentClockDevice.h engine/device/ClockBridgeSizing.h engine/device/IndependentStreamFormatFence.h engine/device/DirectRestoreBackoff.h engine/device/IndependentStreamWatchdog.h engine/device/BridgeContinuityGate.h engine/device/EndpointIdentityPolicy.h engine/device/WasapiEndpointIdentityGuard.h engine/device/AsioStartupPolicy.h engine/device/AsioPriorityDeviceManager.h engine/device/AsioRegistrationPolicy.h engine/device/AsioRegistryIdentityProbe.h engine/device/DirectRouteFence.h) +target_sources(ARMixConsole PRIVATE src/Main.cpp src/LiveAudioEngine.h src/VstOrbitController.h engine/core/MixerRoutingPlan.h engine/core/ChannelRoutingContract.h engine/core/OrbitPhase.h engine/core/OrbitControlPolicy.h engine/core/OrbitMotion.h engine/core/OrbitDistanceMapping.h engine/core/DearVrPolarPolicy.h src/PluginCatalog.h src/PluginVault.h src/PortableWorkspace.h src/DiagnosticsRecorder.h src/StereoPan.h src/NativePresetArchive.h src/VstBusLayout.h src/LiveGraphHandoff.h src/DiagnosticTone.h engine/core/RealtimeHealthHistogram.h engine/core/CallbackCadenceEvidence.h engine/diagnostics/CrackleEvidenceWindow.h engine/device/AdaptiveClockBridge.h engine/device/AudioProfilePolicy.h engine/device/PeriodCapabilityEvidence.h engine/device/SessionLifecycle.h engine/device/WasapiCapabilityProbe.h engine/device/JuceIndependentClockDevice.h engine/device/ClockBridgeSizing.h engine/device/IndependentStreamFormatFence.h engine/device/DirectRestoreBackoff.h engine/device/IndependentStreamWatchdog.h engine/device/BridgeContinuityGate.h engine/device/EndpointIdentityPolicy.h engine/device/WasapiEndpointIdentityGuard.h engine/device/AsioStartupPolicy.h engine/device/AsioPriorityDeviceManager.h engine/device/AsioRegistrationPolicy.h engine/device/AsioRegistryIdentityProbe.h engine/device/DirectRouteFence.h) target_compile_definitions(ARMixConsole PRIVATE JUCE_WEB_BROWSER=1 JUCE_USE_WIN_WEBVIEW2=1 @@ -50,6 +50,9 @@ if(BUILD_TESTING) add_executable(ARMixMixerRoutingTests tests/mixer_routing_plan_test.cpp) target_compile_features(ARMixMixerRoutingTests PRIVATE cxx_std_20) add_test(NAME TenStripStaticRoutingAndMaster COMMAND ARMixMixerRoutingTests) + add_executable(ARMixChannelRoutingContractTests tests/channel_routing_contract_test.cpp) + target_compile_features(ARMixChannelRoutingContractTests PRIVATE cxx_std_20) + add_test(NAME MonoStereoSparsePhysicalPortRouting COMMAND ARMixChannelRoutingContractTests) add_executable(ARMixOrbitPhaseTests tests/orbit_phase_test.cpp) target_compile_features(ARMixOrbitPhaseTests PRIVATE cxx_std_20) add_test(NAME VstAzimuthOrbitRamp COMMAND ARMixOrbitPhaseTests) From 5d975b47ebdc4e5852d4e26bd14702cfd608952d Mon Sep 17 00:00:00 2001 From: Ari Sulistiono Date: Wed, 28 Oct 2026 05:50:26 +0700 Subject: [PATCH 4/8] test: keep routing assertions live in Release builds --- tests/channel_routing_contract_test.cpp | 3 +++ 1 file changed, 3 insertions(+) diff --git a/tests/channel_routing_contract_test.cpp b/tests/channel_routing_contract_test.cpp index c03d9f038..d76f94495 100644 --- a/tests/channel_routing_contract_test.cpp +++ b/tests/channel_routing_contract_test.cpp @@ -1,6 +1,9 @@ // SPDX-License-Identifier: AGPL-3.0-only #include "../engine/core/ChannelRoutingContract.h" #include +#if defined(NDEBUG) +#undef NDEBUG // Assertions are test execution, even in Windows Release. +#endif #include #include #include From ed6d36826f5d8e5e73f593e119580789d78c36a3 Mon Sep 17 00:00:00 2001 From: Ari Sulistiono Date: Wed, 28 Oct 2026 05:50:41 +0700 Subject: [PATCH 5/8] test: prevent P1A routing regressions from being skipped in Release --- tests/mixer_routing_plan_test.cpp | 3 +++ 1 file changed, 3 insertions(+) diff --git a/tests/mixer_routing_plan_test.cpp b/tests/mixer_routing_plan_test.cpp index 4da65d4a5..3b3565b5f 100644 --- a/tests/mixer_routing_plan_test.cpp +++ b/tests/mixer_routing_plan_test.cpp @@ -1,6 +1,9 @@ // SPDX-License-Identifier: AGPL-3.0-only #include "../engine/core/MixerRoutingPlan.h" #include +#if defined(NDEBUG) +#undef NDEBUG // Never skip P1A assertions in Release native CTest. +#endif #include #include #include From c85843de69a1f1f398a4dd31722aab74a6e57f2f Mon Sep 17 00:00:00 2001 From: Ari Sulistiono Date: Wed, 28 Oct 2026 05:51:40 +0700 Subject: [PATCH 6/8] docs: lock P1B format/port contract, GUI UX and measured gates --- .../P1B_MONO_STEREO_PORT_CONTRACT_20261028.md | 56 +++++++++++++++++++ 1 file changed, 56 insertions(+) create mode 100644 docs/P1B_MONO_STEREO_PORT_CONTRACT_20261028.md diff --git a/docs/P1B_MONO_STEREO_PORT_CONTRACT_20261028.md b/docs/P1B_MONO_STEREO_PORT_CONTRACT_20261028.md new file mode 100644 index 000000000..92a779dd5 --- /dev/null +++ b/docs/P1B_MONO_STEREO_PORT_CONTRACT_20261028.md @@ -0,0 +1,56 @@ +# P1B — Independent mono/stereo strips and sparse physical-port contract + +**Date:** 2026-10-28 +**Parent:** [P1A real 10-strip routing PR #108](https://github.com/masarray/arsonmix/pull/108) +**Product authority:** [Routing and mono/stereo ARD #109](https://github.com/masarray/arsonmix/issues/109) +**Safety boundaries:** [P0 0-VST crackle #15](https://github.com/masarray/arsonmix/issues/15), [FX reorder #102](https://github.com/masarray/arsonmix/pull/102), [portable performance #85](https://github.com/masarray/arsonmix/issues/85) + +## Scope, not promotional claims + +P1B extends the **control-thread-compiled, device-independent P1A DSP primitive**. It does **not** open ASIO/WASAPI, replace `LiveAudioEngine.h`, enable audio inputs for CH2–10, change the native WebView2 GUI, make sends live, or perform runtime VST3 mono/stereo layout negotiation. No Windows hardware FAT or live crackle guarantee is claimed. + +The new `engine/core/ChannelRoutingContract.h` adds: + +1. **Three independent channel-format choices:** `followSource` (default compatibility), `mono`, and `stereo`. A source can independently be `disconnected/mono/stereo`. These typed selections avoid the common error of treating source width and channel processing width as the same property. +2. **Device callback port mapping:** an explicitly provided list of actual enabled *physical ports in callback-pointer order*. `InputPortMap` verifies every port index is within the implementation boundary 0–255, has no duplicates, and maps physical port ID to dense callback pointer index. **This list must come from the opened device, not inferred from channel labels.** JUCE callback pointer ordering and each device's active bitsets need implementation/proof in the forthcoming adapter. +3. **Sparse/nonadjacent input choices:** physically numbered port 2 may be callback[1], and stereo L=5, R=7 may be callback[0] and callback[2]. Any unavailable physical port fails closed; existing routing plan is retained. The same hardware input may feed several independent mixer strips. +4. **Format conversion:** stereo → mono input folds down `0.5*(L+R)` before channel FX scratch; mono → stereo is explicitly dual mono, with calibrated -3 dB center send gain matching the original P1A mono center. The stereo→mono path uses a mono equal-power panner and the ordinary stereo→stereo path retains L/R balance. +5. **Prepared-only parameters:** format-dependent pan coefficients and physical mapping are compiled before audio RT. `extract` and `accumulate` are fixed-size, allocation-free operations on caller-owned preallocated buffers. No cache lookup, lock, device query, resize, VST construction, event emit, or thread spawning in callback. + +## Important DSP rules for integration + +- This P1B implementation models **channel format before FX**, not the plugin bus layout. Stereo reverb on a mono track may legitimately turn a mono-input DSP channel into a stereo-output FX path. Do not downmix the post-FX wet signal without explicit routing/policy. The actual negotiated plugin input/output bus layout (mono, stereo, mono-in/stereo-out) belongs to the next FX adapter gate. +- A mono source duplicated to stereo is *dual mono*, not claimed stereophonic width. A regular stereo source is not accidentally collapsed. The chosen -3 dB center mapping is a deliberate compatibility law, **not** a universal acoustical loudness guarantee when stereo plugins introduce decorrelated components. +- The simple `0.5*(L+R)` downmix can cancel anti-phase material. Show a phase/correlation warning in the eventual UI when appropriate; do not add a hidden signal-level maximizer. +- Legacy P1A `Plan` is composed, not rewritten or forked. Existing P1A default settings retain their behavior. There is no duplicate audio engine. +- The existing caller must publish validated routing plans via an explicit RT-safe ownership/epoch protocol. **P1B's all-or-nothing compile does not itself implement a cross-thread graph swap.** Device generation, graph generation, UI request/ACK and no stale update are next-stage requirements. +- Raw device-scoped physical indices are not portable stable identities. Workspace restore must check endpoint identity + per-port identity/label against the current driver, present missing/unmapped status and require user confirmation before live activation. Never silently reassign CH1 mic or monitor speaker. +- If the requested input port is outside the driver's current **active mask**, enabling it may need explicit Audio Setup and a device restart. Switching between already enabled ports can be compiled without reopening, once safe graph publication exists. Do not claim universally click-free switching. + +## Tests in existing Windows CTest + +`tests/channel_routing_contract_test.cpp` checks: sparse callback pointer order, nonadjacent stereo L/R, independent mono/stereo output coefficients, stereo-to-mono fold, center pan level continuity, invalid/missing ports, duplicate enabled port, invalid format, rejection without partial mutation, cross-strip input fanout, and corrupt NaN parameters. + +Both `channel_routing_contract_test.cpp` and the inherited `mixer_routing_plan_test.cpp` explicitly restore assertions if `NDEBUG` is defined. This is important: native Windows Release CI otherwise compiles `assert()` away, accidentally reporting a test PASS without executing assertions. + +New CTest target: `MonoStereoSparsePhysicalPortRouting`. No separate CI workflow. Local GCC 20 optimization with AddressSanitizer/UndefinedBehaviorSanitizer passed on the new contract; Microsoft MSVC/Windows CI and real hardware must be checked separately. + +## Approved GUI plan (not yet enabled) + +**Preserve the existing user-approved 10-strip + MASTER console**, faders, meters, FX inserts and current compact visual language. + +- Main strip displays compact `SOURCE` (e.g. `IN 3`, `IN 5/7`, `CH 1`) and clearly distinct `MONO/ST` format indicator, not a misleading `M` icon confused with MUTE. +- Click SOURCE to open a lightweight anchored chooser of current valid hardware mono/stereo L/R pairs and internal sends. An inspector provides L and R independent selectors, source width/processing format, output bus, send pre/post fader, and input status. Only route kinds actually supported by native engine are enabled. +- Advanced Patchbay matrix visualizes all channels and ports without ten giant popovers. No blur/glow filters, no heavyweight hover shaders, no per-channel animation timers or fake meters. Use existing shared visual scheduler and byte-identical CSS/build assets. +- UI changes are **request → pending → native ACK/reject**, never optimistic localStorage authority for audio. Failure keeps the prior DSP route. Missing hardware is named, not silently reassigned. +- Preview mode uses a clearly labelled simulated topology and cannot be mistaken for real native audio. + +## Next gates, strictly ordered + +1. Review this P1B stacked PR against #108; Windows CTest + native build must PASS before integrating. Never merge the stacked PR directly into main without its parent P1A. +2. Native `DevicePortRegistry`: enumerate actual negotiated device channel masks and map physical ports to callback pointers, then verify on ASIO 4+/8+ channel hardware and WASAPI variants. No hidden channel re-open. +3. Implement per-strip prepared DSP state and mono/stereo plugin bus negotiation, then controlled graph publication with device epoch, ACK, smooth mute/ramp, and deferred destruction. Reuse existing LiveGraphHandoff patterns; do not co-own one VST processor in two concurrent execution graphs. +4. Add true SOURCE/MONO/ST controls and advanced Patchbay only when live native engine can execute them. Complete native sends, output mapping and latency compensation, plus portable state persistence. +5. Prove no-VST baseline #15 and perform multi-channel physical FAT, hotplug recovery, callback deadlines, audio isolation, clicks and real VST3 vendor states. Hardware test is the release gate. + +**Definition of P1B completion:** checked-in pure routing code + passing deterministic release-mode assertions, not a new user-ready EXE. From 943461376aecd56b41925cd216c1bf39e3ff9398 Mon Sep 17 00:00:00 2001 From: Ari Sulistiono Date: Wed, 28 Oct 2026 05:52:27 +0700 Subject: [PATCH 7/8] ci: actually build new routing contract target before CTest on Windows --- .github/workflows/p1-windows.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/p1-windows.yml b/.github/workflows/p1-windows.yml index 7a1199917..dd5c96876 100644 --- a/.github/workflows/p1-windows.yml +++ b/.github/workflows/p1-windows.yml @@ -63,7 +63,7 @@ jobs: -DBUILD_TESTING=ON -DJUCE_WEBVIEW2_PACKAGE_LOCATION="${{ github.workspace }}/.deps" - name: Build executable and native RT tests - run: cmake --build build --config Release --target ARMixConsole ARMixMixerRoutingTests ARMixWorkspaceTests ARMixVaultTests ARMixOrbitPhaseTests ARMixOrbitControlTests ARMixOrbitMotionTests ARMixOrbitDistanceTests ARMixDearVrPolarPolicyTests ARMixRTTests ARMixPresetTests ARMixDiagnosticTests ARMixClockBridgeTests ARMixVirtualClockSoakTests ARMixCadenceTests ARMixCrackleWindowTests ARMixHealthTests ARMixPolicyTests ARMixPeriodEvidenceTests ARMixLifecycleTests ARMixWasapiProbeTests ARMixDualJuceTests ARMixClockSizingTests ARMixIndependentFormatTests ARMixRecoveryTests ARMixStreamWatchdogTests ARMixBridgeContinuityTests ARMixEndpointPolicyTests ARMixEndpointGuardTests ARMixAsioPolicyTests ARMixAsioBackendTests ARMixAsioRegistryIdentityTests ARMixDirectFenceTests --parallel 2 + run: cmake --build build --config Release --target ARMixConsole ARMixMixerRoutingTests ARMixChannelRoutingContractTests ARMixWorkspaceTests ARMixVaultTests ARMixOrbitPhaseTests ARMixOrbitControlTests ARMixOrbitMotionTests ARMixOrbitDistanceTests ARMixDearVrPolarPolicyTests ARMixRTTests ARMixPresetTests ARMixDiagnosticTests ARMixClockBridgeTests ARMixVirtualClockSoakTests ARMixCadenceTests ARMixCrackleWindowTests ARMixHealthTests ARMixPolicyTests ARMixPeriodEvidenceTests ARMixLifecycleTests ARMixWasapiProbeTests ARMixDualJuceTests ARMixClockSizingTests ARMixIndependentFormatTests ARMixRecoveryTests ARMixStreamWatchdogTests ARMixBridgeContinuityTests ARMixEndpointPolicyTests ARMixEndpointGuardTests ARMixAsioPolicyTests ARMixAsioBackendTests ARMixAsioRegistryIdentityTests ARMixDirectFenceTests --parallel 2 - name: Test realtime control primitives run: ctest --test-dir build -C Release --output-on-failure - name: Package verified JUCE GUI for hardware FAT From 33da06a9ae6b0c3ad6558f34fa4352a2eaa2db0b Mon Sep 17 00:00:00 2001 From: Ari Sulistiono Date: Wed, 28 Oct 2026 05:54:26 +0700 Subject: [PATCH 8/8] fix(routing): retain equal-power mono source panning at stereo format endpoints --- docs/P1B_MONO_STEREO_PORT_CONTRACT_20261028.md | 2 +- engine/core/ChannelRoutingContract.h | 7 +------ tests/channel_routing_contract_test.cpp | 11 +++++++++++ 3 files changed, 13 insertions(+), 7 deletions(-) diff --git a/docs/P1B_MONO_STEREO_PORT_CONTRACT_20261028.md b/docs/P1B_MONO_STEREO_PORT_CONTRACT_20261028.md index 92a779dd5..983986b95 100644 --- a/docs/P1B_MONO_STEREO_PORT_CONTRACT_20261028.md +++ b/docs/P1B_MONO_STEREO_PORT_CONTRACT_20261028.md @@ -14,7 +14,7 @@ The new `engine/core/ChannelRoutingContract.h` adds: 1. **Three independent channel-format choices:** `followSource` (default compatibility), `mono`, and `stereo`. A source can independently be `disconnected/mono/stereo`. These typed selections avoid the common error of treating source width and channel processing width as the same property. 2. **Device callback port mapping:** an explicitly provided list of actual enabled *physical ports in callback-pointer order*. `InputPortMap` verifies every port index is within the implementation boundary 0–255, has no duplicates, and maps physical port ID to dense callback pointer index. **This list must come from the opened device, not inferred from channel labels.** JUCE callback pointer ordering and each device's active bitsets need implementation/proof in the forthcoming adapter. 3. **Sparse/nonadjacent input choices:** physically numbered port 2 may be callback[1], and stereo L=5, R=7 may be callback[0] and callback[2]. Any unavailable physical port fails closed; existing routing plan is retained. The same hardware input may feed several independent mixer strips. -4. **Format conversion:** stereo → mono input folds down `0.5*(L+R)` before channel FX scratch; mono → stereo is explicitly dual mono, with calibrated -3 dB center send gain matching the original P1A mono center. The stereo→mono path uses a mono equal-power panner and the ordinary stereo→stereo path retains L/R balance. +4. **Format conversion:** stereo → mono input folds down `0.5*(L+R)` before channel FX scratch; mono → stereo is explicitly dual mono, with the existing equal-power mono pan law (-3 dB center, unity at hard left/right). The stereo→mono path uses a mono equal-power panner and the ordinary stereo→stereo path retains L/R balance. 5. **Prepared-only parameters:** format-dependent pan coefficients and physical mapping are compiled before audio RT. `extract` and `accumulate` are fixed-size, allocation-free operations on caller-owned preallocated buffers. No cache lookup, lock, device query, resize, VST construction, event emit, or thread spawning in callback. ## Important DSP rules for integration diff --git a/engine/core/ChannelRoutingContract.h b/engine/core/ChannelRoutingContract.h index f6af59265..1eb5e8d33 100644 --- a/engine/core/ChannelRoutingContract.h +++ b/engine/core/ChannelRoutingContract.h @@ -142,12 +142,7 @@ struct ChannelRoutingPlan final { // applies AFTER FX, with no raw L+R +6 dB double sum. out.leftGain = original.faderLinear * std::sqrt(0.5f*(1.f-original.pan)); out.rightGain = original.faderLinear * std::sqrt(0.5f*(1.f+original.pan)); - } else if (effective[i] == ChannelFormat::stereo && original.source == SourceMode::mono) { - // A mono source expanded to a stereo channel is DUAL MONO, - // not fabricated stereo width. Preserve -3dB center pan law. - constexpr float center = 0.7071067811865475244f; - out.leftGain = center * original.faderLinear * (original.pan > 0.f ? 1.f-original.pan : 1.f); - out.rightGain = center * original.faderLinear * (original.pan < 0.f ? 1.f+original.pan : 1.f); + } } ChannelRoutingPlan ready; diff --git a/tests/channel_routing_contract_test.cpp b/tests/channel_routing_contract_test.cpp index d76f94495..5098ad068 100644 --- a/tests/channel_routing_contract_test.cpp +++ b/tests/channel_routing_contract_test.cpp @@ -60,6 +60,17 @@ int main() { plan.accumulate(0,l.data(),r.data(),ml.data(),mr.data(),3); assert(approx(ml[0],.2f*.70710678f)&&approx(mr[0],.2f*.70710678f)); + // Mono source keeps equal-power pan even with STEREO channel format. + // At hard right, level is unity and never unintentionally -3dB. + cfg.stripsAndMaster.strips[0].pan=1.f; + assert(ChannelRoutingPlan::compile(cfg,enabled,plan,error)); + Plan::clearMaster(ml.data(),mr.data(),3); + assert(plan.extract(0,callback,3,l.data(),r.data(),3)); + plan.accumulate(0,l.data(),r.data(),ml.data(),mr.data(),3); + assert(approx(ml[0],0.f)&&approx(mr[0],.2f)); + cfg.stripsAndMaster.strips[0].pan=0.f; + assert(ChannelRoutingPlan::compile(cfg,enabled,plan,error)); + // Physical mapping rejected transactionally: plan stays bit-exact. const auto old=plan; cfg.stripsAndMaster.strips[0].inputA=6;