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
4 changes: 4 additions & 0 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -219,6 +219,10 @@ if(BUILD_TESTING)
target_link_libraries(ARMixApprovedRoutingPcmTests PRIVATE juce::juce_core juce::juce_recommended_config_flags)
target_compile_features(ARMixApprovedRoutingPcmTests PRIVATE cxx_std_20)
add_test(NAME P0ApprovedDecoderChannelToChannelAndSourceOnlyPCM COMMAND ARMixApprovedRoutingPcmTests)
# M3a: actual ChannelId vs M4 production blocks before compatibility retirement.
add_executable(ARMixProductionRenderAuditTests tests/production_render_audit_test.cpp)
target_compile_features(ARMixProductionRenderAuditTests PRIVATE cxx_std_20)
add_test(NAME M3ActualProductionRenderPathAndFailSilentCounters COMMAND ARMixProductionRenderAuditTests)
add_dependencies(ARMixMixerRoutingTests ARMixApprovedRoutingPcmTests)
add_executable(ARMixLatencyCompensationTests tests/dynamic_latency_compensation_test.cpp)
target_compile_features(ARMixLatencyCompensationTests PRIVATE cxx_std_20)
Expand Down
48 changes: 48 additions & 0 deletions docs/architecture/M3_RENDER_PATH_EVIDENCE_20261111.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
# M3a — production render-path evidence

## Verified callback structure

The one JUCE device callback is LiveAudioEngine::audioDeviceIOCallbackWithContext.
It checks the hardware direct fence, then NativeRenderAuthority decides
fail-silent unpatched, accepted routed session or isolated diagnostics.
A routed session calls LiveDryRoutingLab::process ONCE. Its nonblocking
RealtimeRenderPermit prevents overlapping callbacks from invoking the same FX.

Inside this existing sole routed pass, native ChannelId PCM uses
DynamicNativeSessionPublisher::render when the matching device-epoch admission
is installed. The compatibility branch uses PreparedMixerBlock::process only
when no native ChannelId PCM epoch is admitted. These are alternatives, never
summed, but M4 compatibility is still reachable in source. Do NOT delete it.

The explicit diagnostic tail runs no vendor VST3. SOURCE ONLY may still
process and meter channel PCM without a MAIN signal, and hardware mute can
silence device pins while a logical graph continues to run. The secondary
WASAPI output copies MAIN PCM after this single render pass.

## Instrumentation and meaning

The native status object now contains dryRoutingLab.renderAudit. It reports
nativeStarted, nativeCompleted, nativeFailed, m4Started, m4Completed, m4Failed,
overlapDenied, unpatchedSilent and mutedNoRender. All counters are monotonic
within the application process, not per device. They are independent relaxed
atomics: a concurrent CONTROL snapshot can briefly observe an unfinished
callback attempt. A block is counted once regardless of DSP chunk count.

This is an observation, not output authorization or proof of audible sound.
Compare deltas of these counters across a field-test window alongside
deviceEpoch, routing admission and output mute. Do not add browser polling
or a new dashboard solely for these metrics.

## Tests and next-step admission

The new zero-JUCE M3ActualProductionRenderPathAndFailSilentCounters CTest checks
that native and M4 attempts, completions, failures, overlapping callbacks and
silent exits remain distinct. Existing real block-by-block PCM tests for
WIRE, SOURCE ONLY, parallel sends, bus and channel FX remain mandatory.
A Windows MSVC/full CTest validates integration. Physical ASIO listening is
PENDING and cannot be inferred from green CI.

Retire an M4 branch only after actual native field sessions show no M4
render deltas with equivalent VST3/FX, channel meters, bus and physical MAIN
performance across restart, devices and output mute. Never permit legacy
fallback merely because native publication failed.
1 change: 1 addition & 0 deletions docs/architecture/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,7 @@ Assembled /preview/ DOM (presentation only)
| Modal setup transaction (M2b) | src/Main.cpp::showDeviceSetup; NativeDeviceApplyCoordinator.h | Persistent one-owner lease across visible JUCE selector, explicit Apply and automatic ASIO restart; repeated Setup clicks never re-mute; selector close completes readback/rebind before releasing lease |
| Live hardware readback (M2c) | src/NativeDeviceApplyCoordinator.h; src/Main.cpp | Consolidated actual device-object readback on CONTROL, strict ASIO driver instance identity and live mask/rate/buffer verification before Apply/rollback; no new device owner or callback |
| Production audio compatibility | src/LiveDryRoutingLab.h; engine/core/UnifiedLegacyProductionAdmission.h | Retain only proven required M4/FAT migration semantics; never create another render authority |
| M3a actual render evidence | engine/core/ProductionRenderAudit.h; LiveDryRoutingLab::process/status; docs/architecture/M3_RENDER_PATH_EVIDENCE_20261111.md | One native or M4 render attempt per JUCE callback; success/fault/overlap and muted/unpatched readback; no audio authority change |
| Built-in DSP and VST lifecycle | engine/builtin_fx/**; src/NativeBuiltInFx.h; src/FactoryFxRegistry.h; src/PluginCatalog.h; engine/core/DynamicChannelFxLeaseBank.h; src/LiveAudioEngine.h | Per-processor DSP; one built-in registration for live insert, offline prepare, restore and native picker. Specialized editors and vendor lease remain with their existing owners. |
| Player | engine/player/**; src/Main.cpp dispatch | Worker decode / buffered PCM, one native graph virtual input, no independent hardware output callback |
| Native status projection | integration/ApprovedNativeRuntimeSnapshot.h; integration/ApprovedNativeV8Projection.h; src/NativeLogicalMixerControl.h | Canonical installed and retained projection, with a forwarding include for old clients. Logical-only readback is separate and cannot admit PCM. |
Expand Down
48 changes: 48 additions & 0 deletions engine/core/ProductionRenderAudit.h
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
// SPDX-License-Identifier: AGPL-3.0-only
#pragma once
#include <atomic>
#include <cstdint>

// Read-only evidence for the single JUCE production renderer. Neither this
// type nor its counters authorize PCM/output. No heap, lock, wait or log on RT.
namespace armix::rt {
class ProductionRenderAudit final {
public:
enum class Path : std::uint8_t { channelId, compatibilityM4 };
struct Snapshot {
std::uint64_t nativeStarted=0,nativeCompleted=0,nativeFailed=0;
std::uint64_t m4Started=0,m4Completed=0,m4Failed=0;
std::uint64_t overlapDenied=0,unpatchedSilent=0,mutedNoRender=0;
};
ProductionRenderAudit()=default;
ProductionRenderAudit(const ProductionRenderAudit&)=delete;
ProductionRenderAudit& operator=(const ProductionRenderAudit&)=delete;
void started(Path path) noexcept {select(path,nativeStarted_,m4Started_).fetch_add(1,std::memory_order_relaxed);}
void completed(Path path) noexcept {select(path,nativeCompleted_,m4Completed_).fetch_add(1,std::memory_order_relaxed);}
void failed(Path path) noexcept {select(path,nativeFailed_,m4Failed_).fetch_add(1,std::memory_order_relaxed);}
void deniedOverlap() noexcept {overlapDenied_.fetch_add(1,std::memory_order_relaxed);}
void unpatched() noexcept {unpatchedSilent_.fetch_add(1,std::memory_order_relaxed);}
void muted() noexcept {mutedNoRender_.fetch_add(1,std::memory_order_relaxed);}
// CONTROL only: independent relaxed loads can briefly show an in-flight
// attempt. Counters are monotonic since process start, not per device.
[[nodiscard]] Snapshot snapshot() const noexcept {
return {nativeStarted_.load(std::memory_order_relaxed),
nativeCompleted_.load(std::memory_order_relaxed),
nativeFailed_.load(std::memory_order_relaxed),
m4Started_.load(std::memory_order_relaxed),
m4Completed_.load(std::memory_order_relaxed),
m4Failed_.load(std::memory_order_relaxed),
overlapDenied_.load(std::memory_order_relaxed),
unpatchedSilent_.load(std::memory_order_relaxed),
mutedNoRender_.load(std::memory_order_relaxed)};
}
private:
using Counter=std::atomic<std::uint64_t>;
static Counter& select(Path path,Counter& native,Counter& m4) noexcept {
return path==Path::channelId?native:m4;
}
Counter nativeStarted_{0},nativeCompleted_{0},nativeFailed_{0};
Counter m4Started_{0},m4Completed_{0},m4Failed_{0};
Counter overlapDenied_{0},unpatchedSilent_{0},mutedNoRender_{0};
};
} // namespace armix::rt
31 changes: 30 additions & 1 deletion src/LiveDryRoutingLab.h
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@
#include "../engine/device/JuceActivePortSnapshot.h"
#include "../engine/core/RealtimeRoutePublisher.h"
#include "../engine/core/RealtimeRenderPermit.h"
#include "../engine/core/ProductionRenderAudit.h"
#include "../engine/device/LiveInputPortRegistry.h"
#include <juce_audio_devices/juce_audio_devices.h>
#include <algorithm>
Expand Down Expand Up @@ -2777,6 +2778,7 @@ class LiveDryRoutingLab final {
// do not spin or take a lock on the host-owned realtime callback.
armix::rt::RealtimeRenderPermit exclusive{rendering_};
if(!exclusive) {
renderAudit_.deniedOverlap();
if(outputs && frames>0 && frames<=Block::hardFrameLimit)
for(int c=0;c<outputCount;++c)
if(outputs[c])juce::FloatVectorOperations::clear(outputs[c],frames);
Expand Down Expand Up @@ -2823,6 +2825,7 @@ class LiveDryRoutingLab final {
// channel, AUX and MASTER vendor processing until explicit native ACK.
// One atomic read; outputs are cleared by the fail-silent gate above.
if(!userPatched_.load(std::memory_order_acquire)) {
renderAudit_.unpatched();
fadeRemaining_=0;
lastOutputL_=lastOutputR_=0.f;
silence();return true;
Expand Down Expand Up @@ -2889,7 +2892,10 @@ class LiveDryRoutingLab final {
fadeRemaining_=rampFrames;
fadeFromL_=fadeFromR_=0.f;
lastOutputL_=lastOutputR_=0.f;
if(!meterOnly){silence();return true;}
if(!meterOnly){
renderAudit_.muted();
silence();return true;
}
}
// Large/variable JUCE quantum is chunked using stack pointer views;
// no heap allocation or new processing object inside callback.
Expand All @@ -2902,6 +2908,12 @@ class LiveDryRoutingLab final {
topologyFault_.store(true,std::memory_order_release);
silence();return true;
}
// One attempt per outer JUCE callback; a 64/256/1024-frame chunk
// loop still owns exactly ONE native or compatibility DSP pass.
const auto auditPath=channelIdRender?
armix::rt::ProductionRenderAudit::Path::channelId:
armix::rt::ProductionRenderAudit::Path::compatibilityM4;
renderAudit_.started(auditPath);
float peakL=0.f,peakR=0.f,monitorPeakL=0.f,monitorPeakR=0.f;
std::array<float,count> perChannelPeaks{};
std::array<float,count> perChannelPeaksL{},perChannelPeaksR{};
Expand Down Expand Up @@ -2967,6 +2979,7 @@ class LiveDryRoutingLab final {
// A native publication can briefly contend with a reader.
// The epoch/pin checks above own sticky topology faults.
if(!channelIdRender)topologyFault_.store(true,std::memory_order_release);
renderAudit_.failed(auditPath);
silence();return true;
}
for(int ch=0;ch<count;++ch) {
Expand Down Expand Up @@ -3035,6 +3048,7 @@ class LiveDryRoutingLab final {
}
nativeMeterEpoch_.store(generation,std::memory_order_release);
} else nativeMeterEpoch_.store(0,std::memory_order_release);
renderAudit_.completed(auditPath);
return true;
}

Expand All @@ -3046,6 +3060,20 @@ class LiveDryRoutingLab final {
out->setProperty("hasAcceptedRoute",hasExplicitRoute());
const bool nativePcm=channelIdPhysicalPcmActive();
out->setProperty("nativeChannelIdPcmActive",nativePcm);
// Exact attempted PCM producers, not an optimistic GUI/admission
// indicator. Allocations are CONTROL-only in status(), never render().
const auto evidence=renderAudit_.snapshot();
auto audit=std::make_unique<juce::DynamicObject>();
audit->setProperty("nativeStarted",static_cast<juce::int64>(evidence.nativeStarted));
audit->setProperty("nativeCompleted",static_cast<juce::int64>(evidence.nativeCompleted));
audit->setProperty("nativeFailed",static_cast<juce::int64>(evidence.nativeFailed));
audit->setProperty("m4Started",static_cast<juce::int64>(evidence.m4Started));
audit->setProperty("m4Completed",static_cast<juce::int64>(evidence.m4Completed));
audit->setProperty("m4Failed",static_cast<juce::int64>(evidence.m4Failed));
audit->setProperty("overlapDenied",static_cast<juce::int64>(evidence.overlapDenied));
audit->setProperty("unpatchedSilent",static_cast<juce::int64>(evidence.unpatchedSilent));
audit->setProperty("mutedNoRender",static_cast<juce::int64>(evidence.mutedNoRender));
out->setProperty("renderAudit",juce::var(audit.release()));
// ShowV2 and the legacy M4 route cannot serialize extra ChannelId
// GROUP/FX RETURN buses. This stays visible even after DSP faults
// silent so SAVE/RECALL cannot silently discard audible topology.
Expand Down Expand Up @@ -3209,6 +3237,7 @@ class LiveDryRoutingLab final {
static constexpr int mutedMeterFrames=512;
std::array<std::array<float,mutedMeterFrames>,2> mutedMain_{},mutedMonitor_{};
std::atomic_flag rendering_=ATOMIC_FLAG_INIT; // one AUDIO producer
armix::rt::ProductionRenderAudit renderAudit_; // per-process, RT-only writers
Publisher publisher_;
armix::mixer::DynamicNativeSessionPublisher nativePublisher_;
armix::mixer::UnifiedLegacyAccepted nativeAccepted_;
Expand Down
2 changes: 1 addition & 1 deletion tests/live_routing_ui_contract_test.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,7 @@ test("MUTE gate precedes processing and suppresses previous audible crossfade",(
assert.match(gate,/fadeRemaining_=rampFrames/);
assert.match(gate,/fadeFromL_=fadeFromR_=0\.f/);
assert.match(gate,/lastOutputL_=lastOutputR_=0\.f/);
assert.match(gate,/if\(!meterOnly\)\{silence\(\);return true;\}/);
assert.match(gate,/if\(!meterOnly\)\s*\{\s*renderAudit_\.muted\(\);\s*silence\(\);return true;\s*\}/);
assert.match(gate,/meterOnly\?mutedMain_\[0\]\.data\(\):mainL\+offset/);
assert.match(lab,/if\(outputs\[c\] && \(meterOnly \|\|/);
assert.ok(!lab.includes("masterMuted?0.f:std::clamp(masterGain"), "don't mute before fade and then reintroduce old samples");
Expand Down
30 changes: 30 additions & 0 deletions tests/production_render_audit_test.cpp
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
// SPDX-License-Identifier: AGPL-3.0-only
#if defined(NDEBUG)
#undef NDEBUG
#endif
#include "../engine/core/ProductionRenderAudit.h"
#include <cassert>
#include <type_traits>
#include <utility>
using Audit=armix::rt::ProductionRenderAudit;
static_assert(!std::is_copy_constructible_v<Audit>);
static_assert(noexcept(std::declval<Audit&>().started(Audit::Path::channelId)));
static_assert(noexcept(std::declval<Audit&>().snapshot()));
int main() {
Audit a;
auto s=a.snapshot();
assert(s.nativeStarted==0 && s.m4Started==0 && s.overlapDenied==0);
// Count once per outer hardware callback, not per DSP chunk or channel.
a.started(Audit::Path::channelId);a.completed(Audit::Path::channelId);
a.started(Audit::Path::channelId);a.completed(Audit::Path::channelId);
a.started(Audit::Path::channelId);a.failed(Audit::Path::channelId);
a.started(Audit::Path::compatibilityM4);a.completed(Audit::Path::compatibilityM4);
a.started(Audit::Path::compatibilityM4);a.failed(Audit::Path::compatibilityM4);
a.deniedOverlap();a.unpatched();a.unpatched();a.muted();
s=a.snapshot();
assert(s.nativeStarted==3&&s.nativeCompleted==2&&s.nativeFailed==1);
assert(s.m4Started==2&&s.m4Completed==1&&s.m4Failed==1);
assert(s.overlapDenied==1&&s.unpatchedSilent==2&&s.mutedNoRender==1);
assert(s.nativeStarted==s.nativeCompleted+s.nativeFailed);
assert(s.m4Started==s.m4Completed+s.m4Failed);
}
Loading