diff --git a/.github/workflows/p1-windows.yml b/.github/workflows/p1-windows.yml index db8ab4d4a..57b946585 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 ARMixChannelRoutingContractTests ARMixChannelSendTests ARMixWorkspaceTests ARMixVaultTests ARMixOrbitPhaseTests ARMixOrbitControlTests ARMixOrbitMotionTests ARMixOrbitDistanceTests ARMixFxBypassEnvelopeTests 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 ARMixChannelSendTests ARMixPreparedMixerFlowTests ARMixWorkspaceTests ARMixVaultTests ARMixOrbitPhaseTests ARMixOrbitControlTests ARMixOrbitMotionTests ARMixOrbitDistanceTests ARMixFxBypassEnvelopeTests 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 a37722ee6..0d2bd289b 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/ChannelRoutingContract.h engine/core/ChannelSendPlan.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/ChannelSendPlan.h engine/core/PreparedMixerFlow.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 @@ -58,6 +58,9 @@ if(BUILD_TESTING) add_executable(ARMixChannelSendTests tests/channel_send_plan_test.cpp) target_compile_features(ARMixChannelSendTests PRIVATE cxx_std_20) add_test(NAME TenChannelAcyclicPrePostSends COMMAND ARMixChannelSendTests) + add_executable(ARMixPreparedMixerFlowTests tests/prepared_mixer_flow_test.cpp) + target_compile_features(ARMixPreparedMixerFlowTests PRIVATE cxx_std_20) + add_test(NAME PreparedTenStripDryGraphEndToEnd COMMAND ARMixPreparedMixerFlowTests) 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/P1D_PREPARED_MIXER_FLOW_20261028.md b/docs/P1D_PREPARED_MIXER_FLOW_20261028.md new file mode 100644 index 000000000..6d272eeff --- /dev/null +++ b/docs/P1D_PREPARED_MIXER_FLOW_20261028.md @@ -0,0 +1,32 @@ +# ArSonMix P1D — PreparedMixerFlow execution contract (2026-10-28) + +**Milestone:** compose P1A/P1B/P1C's static validated routing, sparse physical input mapping and bounded acyclic sends into an offline-executable dry mixer, while leaving the current JUCE native audio callback and user GUI COMPLETELY unchanged. Stacked on integration PR #112 `6d470cc07c05c87ce40ae954cdca35820a0ffdfd`. + +## Existing baseline reconciled, no duplicate systems +- `ChannelRoutingPlan`: physical mono/stereo port identity, sparse callback indices, raw source extraction, format conversion. +- `ChannelSendPlan`: max 32 validated DAG edges, pre/post send taps, deterministic topological order, per-strip master inclusion. +- `Plan`: 10 source strips, gain/PAN/mute/solo and MASTER settings. +- Issue #15 remains the zero-plugin live hardware qualification gate; current native CH2–10 FX are not yet functional. PR #102 is still stale/conflicted and must not replace approved GUI code. + +## New code +- `engine/core/PreparedMixerFlow.h` controls three verified subplans, compiles and validates all subplans before replacing the prepared result. Derives per-format gain coefficients on control thread (mono equal-power, stereo balance), including inputless bus returns. Prevents a physical-MONO-to-processing-STEREO channel from inheriting unwanted mono attenuation. +- `Workspace` is caller-owned **and preallocated**. Each incoming bus receives fixed L/R arrays; one scratch pair processes the current strip in topological order. No per-block malloc/locks/vector/sort/trigonometry. There is no device restart or audio callback mutation. +- `render` supports raw physical extraction; adds accumulated internal sends once; calls a **caller-provided per-strip FX hook** exactly between extraction/bus sum and fader; exposes pre-fader/post-FX sends and post-mute/solo/post-fader sends; routes selected strips to MASTER, then applies compiled MASTER mono/balance/gain. +- MUTE/SOLO policy: both suppress pre and post sends; zero-fader does **not** suppress pre-fader sends. This is one explicit engineering policy; alternate pre-mute taps require a future explicit selector, not implicit changes. +- Physically missing inputs fail closed **before** the VST processing hook when no internal source exists, avoiding fake output from a missing driver pin. A genuine internal FX return remains runnable with zero new source frames so reverberation tails can continue. +- If a requested block exceeds the preallocated capacity or invalid device input count, `render` returns false without memory writes. The eventual native host MUST clear its hardware output and emit a bounded offline error event on such failure. +- Dry FX hook accepts a stereo pair plus the explicitly selected processing format. The eventual VST3 host must keep per-strip plugin instances separate and validate mono/stereo bus layouts. No native VST instances are created here. + +## Tests and acceptance +`tests/prepared_mixer_flow_test.cpp` verifies end-to-end: unassigned silence, inputless FX returns, pre-fader sends at -infinity dB, effects before pre-fader taps, post-fader gating, mute/solo including bus returns, 2-hop topology, sparse callback port identity, mono-source-to-stereo unity center, post-fader mono equal power, fanout/master summing, no stale block contents, transactional rollback on bad topology or physical ports, bounded frames, and missing input fail-closed behavior. `#undef NDEBUG` enables assertions in Release CTest. + +Existing Windows workflow compiles `ARMixPreparedMixerFlowTests` with all prior Orbit/FxBypass/P1A/B/C tests, then runs CTest and packages native host. **No new GitHub workflow** is created. + +## Remaining before any real live usage +1. Verify PR #112's exact-source CI green and reconcile current main. Merge main integration before retargeting this stacked PR; never merge child alone. +2. Control-thread `SourceRegistry` must map stable endpoint/port IDs to actual *enabled* callback pointer order. Present explicit source assignment in GUI only when endpoint is really available. +3. Create approved immutable graph revision publication with quiescent retirement, ACK and cancellation. Own preallocated channel scratch/master scratch outside the callback; never instantiate plugins inside callback or process one plugin object concurrently on two graphs. +4. Resolve #15 real 0-VST3 crackle first. Test output-only tone/capture-only/dry 48/44.1 kHz and concrete ASIO/WASAPI device+buffer matrix before enabling multichannel. +5. Per-channel DSP plugin ownership, routing snapshots, audio latencies/PDC, bus FX return and source identity, click-free mutation, meters and solo/mute cross-talk hardware acceptance. Do not claim all 10 channels live before those stages. + +**Status:** pre-production engineering milestone, not a repaired crackle or 10-channel hardware-ready app. diff --git a/engine/core/PreparedMixerFlow.h b/engine/core/PreparedMixerFlow.h new file mode 100644 index 000000000..5731b9380 --- /dev/null +++ b/engine/core/PreparedMixerFlow.h @@ -0,0 +1,167 @@ +// SPDX-License-Identifier: AGPL-3.0-only +#pragma once +#include "ChannelSendPlan.h" +#include +#include +#include +#include +#include +#include + +// P1D offline integration: combines P1A physical input, P1B channel format, +// and P1C DAG sends into one deterministic dry-processing contract. +// NOT INSTALLED IN JUCE. Caller owns a preallocated workspace and an immutable +// validated plan for the entire block. Graph publication/device lifetime is +// deliberately outside this component. +namespace armix::mixer { + +enum class FlowFault { none, inputLayout, sendTopology }; +struct FlowError final { + FlowFault fault = FlowFault::none; + LayoutError layout {}; + SendError send {}; +}; + +struct PreparedMixerFlow final { + struct StripMix { + bool audible = false; // post-mute/solo with positive fader + bool canSendPre = false; // pre-fader is still subject to mute/solo + bool mayReceivePhysical = false; + float gainL = 0.f, gainR = 0.f; + }; + ChannelRoutingPlan routing {}; + ChannelSendPlan sends {}; + std::array mix {}; + + static bool compile(const ChannelRoutingConfig& config, + std::span callbackOrderedPhysicalPorts, + const SendRequest& sendsRequest, + PreparedMixerFlow& destination, + FlowError& error) noexcept { + error = {}; + PreparedMixerFlow next; + if (!ChannelRoutingPlan::compile(config,callbackOrderedPhysicalPorts, + next.routing,error.layout)) { + error.fault=FlowFault::inputLayout; return false; + } + if (!ChannelSendPlan::compile(sendsRequest,next.sends,error.send)) { + error.fault=FlowFault::sendTopology; return false; + } + bool anySolo=false; + for (int i=0;i0.f; + if(!m.audible)continue; + // Channel FORMAT, not physical pin width, chooses the pan law. + // MONO-to-STEREO dual-mono uses stereo balance (unity center). + // Forced stereo-to-MONO uses equal-power pan after the raw fold. + // This also applies to internal returns with no hardware input. + if(next.routing.effectiveFormats[i]==ChannelFormat::mono) { + m.gainL=c.faderLinear*std::sqrt(.5f*(1.f-c.pan)); + m.gainR=c.faderLinear*std::sqrt(.5f*(1.f+c.pan)); + } else { + m.gainL=c.faderLinear*(c.pan>0.f?1.f-c.pan:1.f); + m.gainR=c.faderLinear*(c.pan<0.f?1.f+c.pan:1.f); + } + } + destination=next; + return true; + } + + template + struct Workspace final { + static_assert(Capacity>0,"Fixed DSP workspace requires at least 1 frame"); + std::array,stripCount> incomingL {},incomingR {}; + std::array sourceL {},sourceR {}; + std::array physicalL {},physicalR {}; + std::array masterL {},masterR {}; + std::array sendL {},sendR {}; + + Workspace() noexcept { + for(int i=0;i + bool render(const float* const* inputs,int callbackInputs,int frames, + Workspace& work,FxProcessor&& processFx) const noexcept { + if(frames<=0||static_cast(frames)>Capacity|| + callbackInputs<0||callbackInputs>maxPhysicalPorts)return false; + for(int strip=0;strip +#include +#include +#include + +using namespace armix::mixer; +static bool eq(float a,float b,float eps=1.e-5f){return std::abs(a-b) port0={0}; +using Flow=PreparedMixerFlow; +using Work=Flow::Workspace; +static constexpr auto dry=[](int,ChannelFormat,float*,float*,int) noexcept {}; + +int main() { + Flow flow; FlowError error;Work work; + ChannelRoutingConfig cfg; SendRequest request; + std::array in0={1.f,-.5f,.25f,.75f}; + const float* capture[]={in0.data()}; + assert(Flow::compile(cfg,port0,request,flow,error)); + assert(flow.render(capture,1,frames,work,dry)); + for(int i=0;i CH2 -> CH3 -> MASTER (no duplicate dry). + cfg.stripsAndMaster.strips[0]={SourceMode::mono,0,-1,1.f,-1.f,false,false}; + cfg.formats[0]=ChannelFormat::mono; + cfg.formats[1]=ChannelFormat::stereo; + request.count=2;request.toMaster[1]=false; + request.sends[0]={0,1,SendTap::postFader,1.f,0.f,true}; + request.sends[1]={1,2,SendTap::postFader,1.f,0.f,true}; + assert(Flow::compile(cfg,port0,request,flow,error)); + assert(flow.render(capture,1,frames,work,dry)); + assert(eq(work.masterL[0],1.f)&&eq(work.masterR[0],0.f)); + + // Solo BUS RETURN: non-solo physical CH is silent, but raw input can be + // captured for analysis/FX while post-fader and pre-fader sends are gated. + cfg.stripsAndMaster.strips[2].solo=true; + assert(Flow::compile(cfg,port0,request,flow,error)); + assert(!flow.mix[0].canSendPre && !flow.mix[0].audible); + assert(flow.render(capture,1,frames,work,dry)); + assert(eq(work.masterL[0],0.f)); + + // Sparse physical input identity: hardware ports 3,9 appear in callback + // order [3,9], while stereo mapping requests [9,3]. + cfg=ChannelRoutingConfig{};request=SendRequest{}; + cfg.stripsAndMaster.strips[0]={SourceMode::stereo,9,3,1.f,0.f,false,false}; + cfg.formats[0]=ChannelFormat::stereo; + constexpr std::array sparsePorts={3,9}; + std::array left={.2f,.4f,.6f,.8f}; + std::array right={.9f,.7f,.5f,.3f}; + const float* sparseCapture[]={left.data(),right.data()}; + assert(Flow::compile(cfg,sparsePorts,request,flow,error)); + assert(flow.render(sparseCapture,2,frames,work,dry)); + assert(eq(work.masterL[0],right[0]) && eq(work.masterR[0],left[0])); + + // Mono physical source explicitly promoted to stereo MUST have unity + // center balance, not mono -3dB applied to both replicated channels. + cfg=ChannelRoutingConfig{};cfg.stripsAndMaster.strips[0]= + {SourceMode::mono,0,-1,1.f,0.f,false,false}; + cfg.formats[0]=ChannelFormat::stereo; + assert(Flow::compile(cfg,port0,request,flow,error)); + assert(flow.render(capture,1,frames,work,dry)); + assert(eq(work.masterL[0],1.f) && eq(work.masterR[0],1.f)); + cfg.formats[0]=ChannelFormat::mono; + assert(Flow::compile(cfg,port0,request,flow,error)); + assert(flow.render(capture,1,frames,work,dry)); + constexpr float center=.7071067811865475f; + assert(eq(work.masterL[0],center)&&eq(work.masterR[0],center)); + + // Upstream fanout, then fan-in into empty return bus, all destinations + // initialized exactly once per block (no leaked previous audio block). + request=SendRequest{}; + cfg.formats[1]=ChannelFormat::stereo; + cfg.formats[2]=ChannelFormat::stereo; + request.count=2;request.toMaster[0]=false; + request.sends[0]={0,1,SendTap::preFader,.25f,0.f,true}; + request.sends[1]={0,2,SendTap::preFader,.5f,0.f,true}; + assert(Flow::compile(cfg,port0,request,flow,error)); + assert(flow.render(capture,1,frames,work,dry)); + assert(eq(work.masterL[0],.75f)&&eq(work.masterR[0],.75f)); + assert(flow.render(capture,1,frames,work,dry)); + assert(eq(work.masterL[0],.75f)&&eq(work.masterR[0],.75f)); + + // Invalid DAG/source compile leaves last good entire P1D plan intact. + const Flow previous=flow; + request.sends[1].destination=0; + assert(!Flow::compile(cfg,port0,request,flow,error)); + assert(error.fault==FlowFault::sendTopology); + assert(flow.sends.edgeCount==previous.sends.edgeCount); + request.sends[1].destination=2; + cfg.stripsAndMaster.strips[0].inputA=77; + assert(!Flow::compile(cfg,port0,request,flow,error)); + assert(error.fault==FlowFault::inputLayout); + assert(flow.sends.edgeCount==previous.sends.edgeCount); + cfg.stripsAndMaster.strips[0].inputA=0; + + // A transiently unavailable input must NOT let a VST synthesize a + // phantom signal from a disconnected capture-only source. + const auto phantom=[](int,ChannelFormat,float* l,float* r,int n) noexcept { + for(int i=0;i physicalIds {}; + std::array,stripCount> tenInputs {}; + std::array tenPtrs {}; + for(int i=0;i(i+1)); + tenPtrs[i]=tenInputs[i].data(); + } + request.toMaster[0]=false; + request.count=1; + request.sends[0]={0,9,SendTap::preFader,.5f,0.f,true}; + assert(Flow::compile(cfg,physicalIds,request,flow,error)); + assert(flow.render(tenPtrs.data(),stripCount,frames,work,dry)); + assert(eq(work.masterL[0],54.5f)&&eq(work.masterR[0],54.5f)); + cfg.stripsAndMaster.strips[5].mute=true; + assert(Flow::compile(cfg,physicalIds,request,flow,error)); + assert(flow.render(tenPtrs.data(),stripCount,frames,work,dry)); + assert(eq(work.masterL[0],48.5f)&&eq(work.masterR[0],48.5f)); + + // Stereo-to-mono must fold before FX; a hard-left mono pan uses the + // folded midpoint rather than dropping the opposite stereo input. + cfg=ChannelRoutingConfig{};request=SendRequest{}; + cfg.stripsAndMaster.strips[0]={SourceMode::stereo,0,1,1.f,-1.f,false,false}; + cfg.formats[0]=ChannelFormat::mono; + constexpr std::array adjacent={0,1}; + std::array stereoL{},stereoR{}; + stereoL.fill(1.f);stereoR.fill(.2f); + const float* stereoInputs[]={stereoL.data(),stereoR.data()}; + assert(Flow::compile(cfg,adjacent,request,flow,error)); + assert(flow.render(stereoInputs,2,frames,work,dry)); + assert(eq(work.masterL[0],.6f)&&eq(work.masterR[0],0.f)); +}