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
2 changes: 1 addition & 1 deletion .github/workflows/p1-windows.yml
Original file line number Diff line number Diff line change
Expand Up @@ -89,7 +89,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 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 ARMixPreparedMixerBlockTests 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
14 changes: 13 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/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/PreparedMixerBlock.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 @@ -47,6 +47,18 @@ 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(ARMixChannelRoutingContractTests tests/channel_routing_contract_test.cpp)
target_compile_features(ARMixChannelRoutingContractTests PRIVATE cxx_std_20)
add_test(NAME MonoStereoSparsePhysicalPortRouting COMMAND ARMixChannelRoutingContractTests)
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(ARMixPreparedMixerBlockTests tests/prepared_mixer_block_test.cpp)
target_compile_features(ARMixPreparedMixerBlockTests PRIVATE cxx_std_20)
add_test(NAME TenChannelEndToEndPreparedAudioRender COMMAND ARMixPreparedMixerBlockTests)
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/P1A_REAL_MIXER_ROUTING_CORE_20261028.md
Original file line number Diff line number Diff line change
@@ -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.
56 changes: 56 additions & 0 deletions docs/P1B_MONO_STEREO_PORT_CONTRACT_20261028.md
Original file line number Diff line number Diff line change
@@ -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 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

- 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.
Loading
Loading