Skip to content
Closed
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
2 changes: 1 addition & 1 deletion .github/workflows/p1-windows.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
5 changes: 4 additions & 1 deletion CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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)
Expand Down
32 changes: 32 additions & 0 deletions docs/P1D_PREPARED_MIXER_FLOW_20261028.md
Original file line number Diff line number Diff line change
@@ -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<Capacity>` 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.
167 changes: 167 additions & 0 deletions engine/core/PreparedMixerFlow.h
Original file line number Diff line number Diff line change
@@ -0,0 +1,167 @@
// SPDX-License-Identifier: AGPL-3.0-only
#pragma once
#include "ChannelSendPlan.h"
#include <algorithm>
#include <array>
#include <cmath>
#include <cstddef>
#include <span>
#include <utility>

// 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<StripMix, stripCount> mix {};

static bool compile(const ChannelRoutingConfig& config,
std::span<const int> 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;i<stripCount;++i) {
const auto& c=config.stripsAndMaster.strips[i];
if(c.solo && !c.mute &&
(c.source!=SourceMode::disconnected ||
next.sends.receivesInternalAudio(i))) anySolo=true;
}
for (int i=0;i<stripCount;++i) {
const auto& c=config.stripsAndMaster.strips[i];
auto& m=next.mix[i];
m.mayReceivePhysical=c.source!=SourceMode::disconnected;
const bool sourceAvailable=m.mayReceivePhysical ||
next.sends.receivesInternalAudio(i);
m.canSendPre=sourceAvailable && !c.mute && (!anySolo || c.solo);
m.audible=m.canSendPre && c.faderLinear>0.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 <std::size_t Capacity>
struct Workspace final {
static_assert(Capacity>0,"Fixed DSP workspace requires at least 1 frame");
std::array<std::array<float,Capacity>,stripCount> incomingL {},incomingR {};
std::array<float,Capacity> sourceL {},sourceR {};
std::array<float,Capacity> physicalL {},physicalR {};
std::array<float,Capacity> masterL {},masterR {};
std::array<float*,stripCount> sendL {},sendR {};

Workspace() noexcept {
for(int i=0;i<stripCount;++i) {
sendL[i]=incomingL[i].data();sendR[i]=incomingR[i].data();
}
}
Workspace(const Workspace&)=delete;
Workspace& operator=(const Workspace&)=delete;
};

// FxProcessor signature: void(int strip, ChannelFormat format,
// float* left, float* right, int frames) noexcept.
// Dry unit tests pass an empty noexcept processor. The future host may call
// each channel's independent VST chain here, after raw physical+bus sum.
// The callback MUST supply a prepared workspace with no concurrent access.
// On invalid frame count no buffers are touched: host must output silence.
template <std::size_t Capacity, class FxProcessor>
bool render(const float* const* inputs,int callbackInputs,int frames,
Workspace<Capacity>& work,FxProcessor&& processFx) const noexcept {
if(frames<=0||static_cast<std::size_t>(frames)>Capacity||
callbackInputs<0||callbackInputs>maxPhysicalPorts)return false;
for(int strip=0;strip<stripCount;++strip) {
std::fill_n(work.incomingL[strip].data(),frames,0.f);
std::fill_n(work.incomingR[strip].data(),frames,0.f);
}
Plan::clearMaster(work.masterL.data(),work.masterR.data(),frames);
for(int order=0;order<stripCount;++order) {
const int strip=sends.topologicalOrder[order];
const auto& control=mix[strip];
if(!control.mayReceivePhysical && !sends.receivesInternalAudio(strip))
continue;
std::copy_n(work.incomingL[strip].data(),frames,work.sourceL.data());
std::copy_n(work.incomingR[strip].data(),frames,work.sourceR.data());
bool physicallyAvailable=false;
if(control.mayReceivePhysical) {
physicallyAvailable=routing.extractSource(
strip,inputs,callbackInputs,work.physicalL.data(),
work.physicalR.data(),frames);
if(physicallyAvailable) {
for(int i=0;i<frames;++i) {
work.sourceL[i]+=work.physicalL[i];
work.sourceR[i]+=work.physicalR[i];
}
}
}
// Missing/disconnected driver input must remain silent even when
// a VST generates output from zeros. However, an internal return
// is allowed to process a reverb tail with no fresh input.
if(!physicallyAvailable && !sends.receivesInternalAudio(strip))
continue;
// POST-FX, PRE-FADER tap: fader zero does not suppress the send.
processFx(strip,routing.effectiveFormats[strip],
work.sourceL.data(),work.sourceR.data(),frames);
if(control.canSendPre)
sends.dispatch(strip,SendTap::preFader,
work.sourceL.data(),work.sourceR.data(),
work.sendL.data(),work.sendR.data(),frames);
// POST-FADER tap, including MUTE/SOLO arbitration.
if(!control.audible)continue;
for(int i=0;i<frames;++i) {
work.sourceL[i]*=control.gainL;
work.sourceR[i]*=control.gainR;
}
sends.dispatch(strip,SendTap::postFader,
work.sourceL.data(),work.sourceR.data(),
work.sendL.data(),work.sendR.data(),frames);
if(sends.masterEnabled(strip)) {
for(int i=0;i<frames;++i) {
work.masterL[i]+=work.sourceL[i];
work.masterR[i]+=work.sourceR[i];
}
}
}
routing.base.finishMaster(work.masterL.data(),work.masterR.data(),frames);
return true;
}
};
} // namespace armix::mixer
Loading
Loading