diff --git a/.github/workflows/p1-windows.yml b/.github/workflows/p1-windows.yml index 104d14d8f..7a1199917 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 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 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 diff --git a/CMakeLists.txt b/CMakeLists.txt index 3af1c2451..41a59f7f7 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/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/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 @@ -47,6 +47,9 @@ target_link_libraries(ARMixConsole PRIVATE include(CTest) 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(ARMixOrbitPhaseTests tests/orbit_phase_test.cpp) target_compile_features(ARMixOrbitPhaseTests PRIVATE cxx_std_20) add_test(NAME VstAzimuthOrbitRamp COMMAND ARMixOrbitPhaseTests) diff --git a/docs/P1A_REAL_MIXER_ROUTING_CORE_20261028.md b/docs/P1A_REAL_MIXER_ROUTING_CORE_20261028.md new file mode 100644 index 000000000..7d5baf688 --- /dev/null +++ b/docs/P1A_REAL_MIXER_ROUTING_CORE_20261028.md @@ -0,0 +1,32 @@ +# ArSonMix P1A — verified foundation for real 10-channel routing + MASTER (2026-10-28) + +Baseline: `main@de683b001a5a1e5e050bc20ddb52d32b22fa58d1`. Scope: **pure DSP core plus deterministic C++ tests, no live activation**. Superseded/stale UI-DSP PRs must not be bulk merged. Owner's global priority remains stable ultra-low-latency Windows audio and the approved v0.8 GUI; this is not a release or a hardware certification. + +## Why this milestone exists + +The current JUCE native callback (`src/LiveAudioEngine.h`) processes one stereo input source through one VST3 chain to the master; `src/Main.cpp` currently consumes channel fader/pan/mute only for Channel 1. Its ten other GUI channel/MASTER insert surfaces cannot be called native live FX until a real input/bus topology exists. Issue #15 **0-FX hardware crackle** remains a release gate, and the Smart Audio Engine ARD explicitly prohibits activating P2.6 live multi-channel DSP until that hardware gate passes. + +## Implemented: device-independent, offline-prepared routing contract + +`engine/core/MixerRoutingPlan.h`: + +- Exactly 10 source strips + one MASTER. Every source starts **disconnected** (never invented or assigned to an arbitrary device pin). Physical input indexes are explicit; mono/stereo slots do not infer a nonexistent stereo device. +- The control thread validates *all* channel mappings, valid numeric parameters, stereo channel separation, source mode and physically negotiated input count. It compiles a temporary plan and atomically **as a unit at the API boundary** replaces the output Plan only on complete success. The caller must still publish the Plan across threads safely; **this implementation does not yet provide a graph swap or cross-thread publication**. +- Precomputed equal-power mono pan and stereo-balance coefficients; logical SOLO/MUTE arbitration; fader level, MASTER gain/PAN/mute/mono. No per-sample trig, heap, logging, scans or device operations. +- `extract(strip,...)` reads true physical channel input into preallocated stereo scratch, preserving stereo. `accumulate(strip,...)` sums post-FX stereo scratch into the MASTER mix. `finishMaster(...)` applies MASTER controls after the future master FX chain. +- Unassigned or unavailable physical input returns silence and `false` from `extract`; it never masquerades as a live VST3 or fabricates VU levels. + +## Engineering invariants / tests + +`tests/mixer_routing_plan_test.cpp` covers 10 independent mono sources, separate left/right physical inputs, stereo identity, mono centered -3 dB law, panic/mute/solo correctness, M/S output summing, invalid physical input and duplicate L/R index, non-finite pan, gain bounds, unknown source modes, recompile rollback and null/insufficient input availability. Existing Windows CTest builds `ARMixMixerRoutingTests` as part of the established workflow (no extra workflow or redundant matrix). + +## Next integration gates (deliberately not marked complete) + +1. Issue #15 must be physically gated for **0 FX** (OUTPUT_ONLY_TONE, CAPTURE_ONLY, DRY_THROUGH; negotiated driver rate/period and capture/renderer evidence). A CTest pass is not a substitute. +2. Create `SourceRegistry` populated from *actual* ASIO/WASAPI/virtual input endpoints, mapping by explicit per-channel source ID, not hard-coded GUI label or default fake input. Preserve robust DirectFence/independent clocks. +3. Allocate fixed scratch/master buffers ahead of callback; each source: `extract → channel VST chain → fader/pan/mute/solo accumulate`, then `MASTER FX → finishMaster → actual output`. Avoid feedback paths for FX Return. Handle mono/stereo VST bus layout and channel-local plugin/editor/Orbit identity. +4. Publish immutable source/routing snapshots at audio block boundary using the existing `LiveGraphHandoff` epoch/quiescent retirement pattern. No graph destruction, initialization, allocations, locks or device restarts on callback. Support transaction rollback, ACK and source availability status. +5. Verify per-source meters against true post-FX levels; add callback budget profiling, cross-channel isolation, device hotplug, recall, latency/PDC and minimum-buffer soak tests. No guaranteed click-free VST order change until measured on the real device. +6. Only then enable `ADD FX` for CH2–10 and MASTER in native GUI. An unrouted channel must show a truthful disabled/unassigned status until activation. + +No installer/runtime changes are included in this milestone. Public/private binary feature parity and the portable VST Vault rules remain unchanged. diff --git a/engine/core/MixerRoutingPlan.h b/engine/core/MixerRoutingPlan.h new file mode 100644 index 000000000..c55d1aaaa --- /dev/null +++ b/engine/core/MixerRoutingPlan.h @@ -0,0 +1,168 @@ +// SPDX-License-Identifier: AGPL-3.0-only +#pragma once +#include +#include +#include +#include + +// Phase P1: prepared, device-independent 10-strip + MASTER routing primitive. +// NO connection to the live audio callback yet. All topology changes must be +// compiled on the control thread and published using a quiescent/epoch handoff. +// Only read/accumulate/master belong in the realtime callback. +namespace armix::mixer { + +constexpr int stripCount = 10; + +enum class SourceMode { disconnected, mono, stereo }; + +struct StripConfig final { + SourceMode source = SourceMode::disconnected; + int inputA = -1, inputB = -1; // physical input indices, never GUI labels + float faderLinear = 1.0f; // UI dB conversion happens on control thread + float pan = 0.0f; // -1 = left, 0 = center, +1 = right + bool mute = false, solo = false; +}; +struct MasterConfig final { + float gainLinear = 1.0f; + float pan = 0.0f; + bool mute = false, mono = false; +}; +struct Configuration final { + std::array strips {}; + MasterConfig master {}; +}; +enum class Fault { none, invalidInputCount, inputOutOfRange, duplicateStereoInput, + invalidSourceMode, invalidGain, invalidPan }; +struct Error final { + Fault code = Fault::none; + int strip = -1; // -1 denotes master/device rather than a source strip +}; + +struct CompiledStrip final { + int inputA = -1, inputB = -1; + SourceMode mode = SourceMode::disconnected; + bool active = false; // muted, disconnected and solo-excluded are never routed + float leftGain = 0.f, rightGain = 0.f; +}; + +struct Plan final { + std::array strips {}; + int physicalInputs = 0; + float masterGain = 1.f, masterLeftBalance = 1.f, masterRightBalance = 1.f; + bool masterMono = false; + int activeStrips = 0; + + // Control thread ONLY. Rejection leaves previous plan untouched. + // Unassigned strips are legal and always silent, never fake VST buses. + static bool compile(const Configuration& cfg, int inputCount, Plan& destination, + Error& error) noexcept { + error = {}; + if (inputCount < 0 || inputCount > 256) { + error = {Fault::invalidInputCount,-1}; + return false; + } + if (!validGain(cfg.master.gainLinear)) { + error = {Fault::invalidGain,-1}; return false; + } + if (!validPan(cfg.master.pan)) { + error = {Fault::invalidPan,-1}; return false; + } + bool anySolo = false; + for (int i=0;i=inputCount || + (c.source==SourceMode::stereo && (c.inputB<0 || c.inputB>=inputCount))) { + error={Fault::inputOutOfRange,i};return false; + } + if (c.source==SourceMode::stereo && c.inputA==c.inputB) { + error={Fault::duplicateStereoInput,i};return false; + } + if (c.solo && !c.mute) anySolo = true; + } + Plan candidate; + candidate.physicalInputs = inputCount; + candidate.masterGain = cfg.master.mute?0.f:cfg.master.gainLinear; + candidate.masterMono = cfg.master.mono; + candidate.masterLeftBalance = cfg.master.pan>0.f?1.f-cfg.master.pan:1.f; + candidate.masterRightBalance = cfg.master.pan<0.f?1.f+cfg.master.pan:1.f; + for (int i=0;i0.f; + if (!p.active) continue; + ++candidate.activeStrips; + if (c.source==SourceMode::mono) { + // Equal-power mono panning, computed exactly once per topology edit. + p.leftGain=c.faderLinear*std::sqrt(0.5f*(1.f-c.pan)); + p.rightGain=c.faderLinear*std::sqrt(0.5f*(1.f+c.pan)); + } else { + // Stereo BALANCE, not an accidental crossfeed or stereo collapse. + p.leftGain=c.faderLinear*(c.pan>0.f?1.f-c.pan:1.f); + p.rightGain=c.faderLinear*(c.pan<0.f?1.f+c.pan:1.f); + } + } + destination=candidate; + return true; + } + + // RT: read one physical input source into preallocated stereo FX scratch. + // Stereo processors can consume both channels before accumulate(). + bool extract(int strip,const float* const* inputs,int availableInputs, + float* left,float* right,int frames) const noexcept { + if (!left || !right || frames<=0 || strip<0 || strip>=stripCount) return false; + const auto& route=strips[strip]; + const bool valid=route.active && inputs && + route.inputA>=0 && route.inputA=0 && route.inputB=stripCount || frames<=0 || + !left || !right || !masterL || !masterR) return; + const auto& p=strips[strip]; + if (!p.active) return; + for(int i=0;i=0.f&&v<=4.f; } + static bool validPan(float v) noexcept { return std::isfinite(v)&&v>=-1.f&&v<=1.f; } +}; +} // namespace armix::mixer diff --git a/tests/mixer_routing_plan_test.cpp b/tests/mixer_routing_plan_test.cpp new file mode 100644 index 000000000..4da65d4a5 --- /dev/null +++ b/tests/mixer_routing_plan_test.cpp @@ -0,0 +1,97 @@ +// SPDX-License-Identifier: AGPL-3.0-only +#include "../engine/core/MixerRoutingPlan.h" +#include +#include +#include +#include + +using namespace armix::mixer; +static bool close(float a,float b,float tol=1.e-5f){return std::abs(a-b) a={1.f,2.f,3.f,4.f}; + const std::array b={.25f,.5f,.75f,1.f}; + const std::array c={-1.f,-2.f,-3.f,-4.f}; + const float* input[]={a.data(),b.data(),c.data()}; + std::array l{},r{},ml{},mr{}; + assert(!plan.extract(0,input,3,l.data(),r.data(),4)); + for(int i=0;i<4;++i)assert(l[i]==0.f&&r[i]==0.f); + cfg.strips[0]={SourceMode::stereo,0,1,1.f,0.f,false,false}; + cfg.strips[1]={SourceMode::mono,2,-1,1.f,0.f,false,false}; + assert(Plan::compile(cfg,3,plan,err)&&plan.activeStrips==2); + assert(plan.extract(0,input,3,l.data(),r.data(),4)); + Plan::clearMaster(ml.data(),mr.data(),4); + plan.accumulate(0,l.data(),r.data(),ml.data(),mr.data(),4); + assert(close(ml[0],1.f)&&close(mr[0],.25f)); // stereo transparency + assert(plan.extract(1,input,3,l.data(),r.data(),4)); + plan.accumulate(1,l.data(),r.data(),ml.data(),mr.data(),4); + constexpr float center=.7071067811865475f; + assert(close(ml[0],1.f-center)&&close(mr[0],.25f-center)); + plan.finishMaster(ml.data(),mr.data(),4); + // Muting other bus must be independent, never change strip 0. + cfg.strips[1].mute=true; + assert(Plan::compile(cfg,3,plan,err)&&plan.activeStrips==1); + Plan::clearMaster(ml.data(),mr.data(),4); + assert(!plan.extract(1,input,3,l.data(),r.data(),4)); + assert(plan.extract(0,input,3,l.data(),r.data(),4)); + plan.accumulate(0,l.data(),r.data(),ml.data(),mr.data(),4); + assert(close(ml[3],4.f)&&close(mr[3],1.f)); + // Solo arbitration is determined off RT, and mute wins over solo. + cfg.strips[1].mute=false;cfg.strips[1].solo=true; + assert(Plan::compile(cfg,3,plan,err)&&plan.activeStrips==1); + assert(!plan.extract(0,input,3,l.data(),r.data(),4)); + assert(plan.extract(1,input,3,l.data(),r.data(),4)); + cfg.strips[1].mute=true; + assert(Plan::compile(cfg,3,plan,err)&&plan.activeStrips==1); + assert(plan.extract(0,input,3,l.data(),r.data(),4)); + // Stereo balance and true mono master happen after summing. + cfg.strips[1]={}; + cfg.master={2.f,1.f,false,true}; + assert(Plan::compile(cfg,3,plan,err)); + Plan::clearMaster(ml.data(),mr.data(),4); + assert(plan.extract(0,input,3,l.data(),r.data(),4)); + plan.accumulate(0,l.data(),r.data(),ml.data(),mr.data(),4); + plan.finishMaster(ml.data(),mr.data(),4); + assert(close(ml[0],.25f)&&close(mr[0],.25f)); // right-only, doubled, mono + // Reject illegal hardware routes, NaNs and stereo self-alias; NO partial commit. + const auto old=plan; + cfg.strips[2]={SourceMode::stereo,1,9,1.f,0.f,false,false}; + assert(!Plan::compile(cfg,3,plan,err)&&err.code==Fault::inputOutOfRange&&err.strip==2); + assert(plan.activeStrips==old.activeStrips&&plan.masterMono==old.masterMono); + cfg.strips[2].inputB=1; + assert(!Plan::compile(cfg,3,plan,err)&&err.code==Fault::duplicateStereoInput); + cfg.strips[2]={}; + cfg.strips[0].pan=std::numeric_limits::quiet_NaN(); + assert(!Plan::compile(cfg,3,plan,err)&&err.code==Fault::invalidPan&&err.strip==0); + cfg.strips[0].pan=0.f; + cfg.strips[3].source=static_cast(255); + assert(!Plan::compile(cfg,3,plan,err)&&err.code==Fault::invalidSourceMode&&err.strip==3); + cfg.strips[3]={}; + cfg.master.gainLinear=10.f; + assert(!Plan::compile(cfg,3,plan,err)&&err.code==Fault::invalidGain&&err.strip==-1); + cfg.master.gainLinear=1.f; + assert(!Plan::compile(cfg,-1,plan,err)&&err.code==Fault::invalidInputCount); + // 10 independent mono strips, no fixed 2-channel or 1-channel shortcut. + cfg=Configuration{}; + std::array,stripCount> sources{}; + std::array pointers{}; + for(int i=0;i(i+1); + pointers[i]=sources[i].data(); + cfg.strips[i]={SourceMode::mono,i,-1,1.f,-1.f,false,false}; + } + assert(Plan::compile(cfg,stripCount,plan,err)&&plan.activeStrips==stripCount); + float sumL=0.f,sumR=0.f,cl=0.f,cr=0.f; + for(int i=0;i