From 075b0ab6aa71299d3978097e73cc215b70a1a9a0 Mon Sep 17 00:00:00 2001 From: Ari Sulistiono Date: Sat, 31 Oct 2026 19:59:08 +0700 Subject: [PATCH 01/12] feat(m3): atomic native-session Studio-style group/FX bus creation and primary OUT vs SEND model --- engine/core/DynamicChannelRoster.h | 99 +++++++++++++++++++++++++++++- 1 file changed, 96 insertions(+), 3 deletions(-) diff --git a/engine/core/DynamicChannelRoster.h b/engine/core/DynamicChannelRoster.h index 0b0e71c31..72b78533d 100644 --- a/engine/core/DynamicChannelRoster.h +++ b/engine/core/DynamicChannelRoster.h @@ -9,6 +9,7 @@ #include #include #include +#include // DYN0: control-thread session model, NOT a second renderer or a LIVE audio graph. // One state type serves every future input, return, group, monitor and master. @@ -26,6 +27,7 @@ struct ChannelSendRef final { float gain=1.f; bool preFader=false; float pan=0.f; // send-only balance: PRE mono uses equal-power coefficients + bool primaryOutput=false; // OUT selector edge, not a parallel SEND }; struct ChannelStripDefinition final { ChannelId id{}; @@ -53,7 +55,7 @@ enum class ChannelEditFault : std::uint8_t { struct ChannelEdit final { enum class Kind : std::uint8_t { add, duplicate, remove, move, rename, setFormat, setFader, setPan, - setMute, setSolo, addInsertReference, addSendReference + setMute, setSolo, addInsertReference, addSendReference, setPrimaryOutput } kind=Kind::add; ChannelId id{}; // existing channel (except add) ChannelId target{}; // send destination @@ -63,6 +65,7 @@ struct ChannelEdit final { float value=0.f; bool enabled=false; // mute/solo value (or future enable operation) bool preFader=false; // send tap at construction, no hidden POST default + bool primaryOutput=false; // exclusive OUT edge, independent of parallel SEND float sendPan=0.f; // independent send PAN, never channel fader PAN std::string text; }; @@ -189,15 +192,34 @@ class DynamicChannelRoster final { else it->insertCatalogIds.push_back(op.text); break; case ChannelEdit::Kind::addSendReference: - if(op.target.value==0 || op.target==op.id || seek(op.target)==candidate.end()) + if(op.primaryOutput && std::any_of(it->sends.begin(),it->sends.end(), + [](const auto& s){return s.primaryOutput;})) + result.fault=ChannelEditFault::invalidValue; + else if(op.target.value==0 || op.target==op.id || seek(op.target)==candidate.end()) result.fault=ChannelEditFault::invalidValue; else if(it->sends.size()>=budget_.maximumSendsPerChannel) result.fault=ChannelEditFault::budgetExceeded; else if(!std::isfinite(op.value)||op.value<0.f||op.value>4.f|| !std::isfinite(op.sendPan)||op.sendPan< -1.f||op.sendPan>1.f) result.fault=ChannelEditFault::invalidValue; - else it->sends.push_back({op.target,op.value,op.preFader,op.sendPan}); + else it->sends.push_back({op.target,op.value,op.preFader,op.sendPan,op.primaryOutput}); + break; + case ChannelEdit::Kind::setPrimaryOutput: { + if(it->role==ChannelRole::main || it->role==ChannelRole::monitor || + op.target==op.id || (op.target.value && seek(op.target)==candidate.end())) { + result.fault=ChannelEditFault::invalidValue;break; + } + auto& edges=it->sends; + edges.erase(std::remove_if(edges.begin(),edges.end(), + [](const auto& x){return x.primaryOutput;}),edges.end()); + if(op.target.value) { + if(edges.size()>=budget_.maximumSendsPerChannel) { + result.fault=ChannelEditFault::budgetExceeded;break; + } + edges.push_back({op.target,1.f,false,0.f,true}); + } break; + } default:result.fault=ChannelEditFault::invalidAction;break; } if(result.fault!=ChannelEditFault::none)break; @@ -216,6 +238,77 @@ class DynamicChannelRoster final { return result; } + // One Studio Console transaction: new independent BUS + multi-source + // primary output reroute, or FX return + parallel sends. CONTROL THREAD. + // Caller must compile one native graph and publish with device epoch/ACK. + ChannelEditResult createBusForSelected( + std::uint64_t expectedRevision,std::span selected, + std::string name,ChannelRole role,float parallelGain=.25f) { + ChannelEditResult result;result.revision=revision_; + if(expectedRevision!=revision_) { + result.fault=ChannelEditFault::staleRevision;return result; + } + if((role!=ChannelRole::group && role!=ChannelRole::fxReturn) || + selected.empty() || !validName(name) || + !std::isfinite(parallelGain)||parallelGain<0.f||parallelGain>4.f || + revision_==std::numeric_limits::max()) { + result.fault=ChannelEditFault::invalidAction;return result; + } + if(nextId_==0 || nextId_==std::numeric_limits::max()) { + result.fault=ChannelEditFault::idExhausted;return result; + } + auto candidate=channels_; + auto mainIt=std::find_if(candidate.begin(),candidate.end(), + [](const auto& row){return row.role==ChannelRole::main;}); + if(mainIt==candidate.end() || std::count_if(candidate.begin(),candidate.end(), + [](const auto& row){return row.role==ChannelRole::main;})!=1) { + result.fault=ChannelEditFault::invalidAction;return result; + } + const auto mainId=mainIt->id; + const ChannelId busId{nextId_}; + std::unordered_set seen; + seen.reserve(selected.size()); + for(std::size_t i=0;irole==ChannelRole::main || it->role==ChannelRole::monitor) { + result.fault=ChannelEditFault::invalidValue;return result; + } + if(role==ChannelRole::group) { + it->sends.erase(std::remove_if(it->sends.begin(),it->sends.end(), + [](const auto& edge){return edge.primaryOutput;}), + it->sends.end()); + } + if(it->sends.size()>=budget_.maximumSendsPerChannel) { + result.fault=ChannelEditFault::budgetExceeded;return result; + } + it->sends.push_back({busId,role==ChannelRole::group?1.f:parallelGain, + false,0.f,role==ChannelRole::group}); + } + ChannelStripDefinition bus; + bus.id=busId;bus.role=role;bus.format=ProcessingFormat::stereo; + bus.name=std::move(name); + bus.sends.push_back({mainId,1.f,false,0.f,true}); + const auto position=static_cast(mainIt-candidate.begin()); + candidate.insert(candidate.begin()+static_cast(position), + std::move(bus)); + if(!withinBudget(candidate)) { + result.fault=ChannelEditFault::budgetExceeded;return result; + } + channels_.swap(candidate); + ++nextId_;result.revision=++revision_; + result.createdIds.push_back(busId); + return result; + } + private: static bool validFormat(ProcessingFormat f) noexcept { return f==ProcessingFormat::mono || f==ProcessingFormat::stereo; From 50750c28092c7b8baaa263fae3f4efcd1063270e Mon Sep 17 00:00:00 2001 From: Ari Sulistiono Date: Sat, 31 Oct 2026 19:59:44 +0700 Subject: [PATCH 02/12] test(m3): deterministic 2 Mic to new Vocal BUS + parallel FX return PCM, OUT NONE and atomic rollback --- tests/mixer_routing_plan_test.cpp | 106 ++++++++++++++++++++++++++++++ 1 file changed, 106 insertions(+) diff --git a/tests/mixer_routing_plan_test.cpp b/tests/mixer_routing_plan_test.cpp index 30b77b98f..a4ccd898f 100644 --- a/tests/mixer_routing_plan_test.cpp +++ b/tests/mixer_routing_plan_test.cpp @@ -15,6 +15,111 @@ using namespace armix::mixer; static bool close(float a,float b,float tol=1.e-5f){return std::abs(a-b) create{}; + for(int i=0;i<3;++i){ + create[i].kind=Kind::add;create[i].position=static_cast(i); + create[i].role=i==2?ChannelRole::main:ChannelRole::input; + create[i].format=i==2?ProcessingFormat::stereo:ProcessingFormat::mono; + create[i].text=i==0?"Lead Vocal":i==1?"Backing Vocal":"MAIN"; + } + auto made=bank.edit(0,create); + assert(made.ok()&&bank.size()==3); + const auto a=made.createdIds[0],b=made.createdIds[1]; + const auto mainId=made.createdIds[2]; + std::array outs{}; + for(int i=0;i<2;++i){ + outs[i].kind=Kind::setPrimaryOutput; + outs[i].id=made.createdIds[static_cast(i)]; + outs[i].target=mainId; + } + assert(bank.edit(bank.revision(),outs).ok()); + const std::array vocalIds{a,b}; + auto groupResult=bank.createBusForSelected(bank.revision(),vocalIds, + "VOCAL BUS",ChannelRole::group); + assert(groupResult.ok()&&groupResult.createdIds.size()==1); + const auto vocalBus=groupResult.createdIds[0]; + assert(bank.size()==4&&bank.find(vocalBus)->role==ChannelRole::group); + for(const auto id:vocalIds){ + const auto& sends=bank.find(id)->sends; + assert(sends.size()==1&&sends.front().primaryOutput); + assert(sends.front().destination==vocalBus); + } + assert(bank.find(vocalBus)->sends.front().destination==mainId); + // FX return is a NEW logical lane, not a borrowed physical input strip. + // It adds a parallel send while preserving selected source primary OUT. + const std::array fxSource{a}; + auto fxResult=bank.createBusForSelected(bank.revision(),fxSource, + "FX REVERB",ChannelRole::fxReturn,.25f); + assert(fxResult.ok()&&bank.size()==5); + const auto fxBus=fxResult.createdIds.front(); + assert(bank.find(fxBus)->role==ChannelRole::fxReturn); + assert(bank.find(a)->sends.size()==2); + assert(bank.find(a)->sends[0].destination==vocalBus); + assert(bank.find(a)->sends[0].primaryOutput); + assert(bank.find(a)->sends[1].destination==fxBus); + assert(!bank.find(a)->sends[1].primaryOutput); + // Selecting OUT:NONE removes just the primary destination. SEND + // remains audible, so CONSOLE should present a SEND ONLY label. + ChannelEdit output;output.kind=Kind::setPrimaryOutput; + output.id=a;output.target={}; + assert(bank.edit(bank.revision(),std::span(&output,1)).ok()); + assert(bank.find(a)->sends.size()==1); + assert(bank.find(a)->sends[0].destination==fxBus); + output.target=vocalBus; + assert(bank.edit(bank.revision(),std::span(&output,1)).ok()); + // One prepared PCM graph, source -> GROUP (2x insert) -> MAIN, + // plus parallel Lead Vocal -> FX bus (.25) -> MAIN. + DynamicGraphRequest req; + req.physicalInputs=2;req.maxFrames=32; + req.sources={{a,0,-1,false},{b,1,-1,false}}; + DynamicPreparedMixerBlock render; + DynamicGraphError error; + assert(DynamicPreparedMixerBlock::compile(bank,req,render,error)); + assert(render.channelCount()==5&&render.activeChannels()==5); + std::array micA{},micB{},l{},r{}; + micA.fill(.2f);micB.fill(.4f); + const float* inputs[]{micA.data(),micB.data()}; + int fxCalls=0; + const auto fx=[&](ChannelId id,float* left,float* right,int frames) noexcept { + ++fxCalls; + if(id==vocalBus) + for(int i=0;i duplicate{a,a}; + auto rejected=bank.createBusForSelected(revision,duplicate, + "INVALID",ChannelRole::group); + assert(rejected.fault==ChannelEditFault::invalidAction); + rejected=bank.createBusForSelected(revision-1,vocalIds, + "STALE",ChannelRole::group); + assert(rejected.fault==ChannelEditFault::staleRevision); + const std::array missing{ChannelId{999999}}; + rejected=bank.createBusForSelected(revision,missing, + "MISSING",ChannelRole::group); + assert(rejected.fault==ChannelEditFault::missingChannel); + assert(bank.size()==5&&bank.revision()==revision); + assert(render.process(inputs,2,l.data(),r.data(),32,fx)); + assert(close(l[0],expected)); + // OUT NONE without any SEND removes source from actual PCM graph. + ChannelEdit clearOutput;clearOutput.kind=Kind::setPrimaryOutput; + clearOutput.id=b;clearOutput.target={}; + assert(bank.edit(revision,std::span(&clearOutput,1)).ok()); + assert(DynamicPreparedMixerBlock::compile(bank,req,render,error)); + assert(render.process(inputs,2,l.data(),r.data(),32,fx)); + assert(close(l[0],(2.f*.2f+.25f*.2f)*center)); +} + static void verifyDynamicChannelRoster() { DynamicChannelRoster bank; std::vector addOps; @@ -548,6 +653,7 @@ static void verifyRealtimeAuxMasterPcmBothOutputs() { } int main() { + verifyStudioConsoleBusBatchPcm(); verifyRealtimeAuxMasterPcmBothOutputs(); verifyRealtimeAuxPostGainWithoutGraphRebuild(); verifyLegacyToDynamicProductionPcmParity(); From 9eaf8fe169fbd9e59be0a358648632e48ae8611d Mon Sep 17 00:00:00 2001 From: Ari Sulistiono Date: Sat, 31 Oct 2026 20:01:25 +0700 Subject: [PATCH 03/12] docs(m3): PRD_STUDIO_CONSOLE_DYNAMIC_LIVE_V3_20261031.md canonical Studio Console v3 --- ...STUDIO_CONSOLE_DYNAMIC_LIVE_V3_20261031.md | 31 +++++++++++++++++++ 1 file changed, 31 insertions(+) create mode 100644 docs/PRD_STUDIO_CONSOLE_DYNAMIC_LIVE_V3_20261031.md diff --git a/docs/PRD_STUDIO_CONSOLE_DYNAMIC_LIVE_V3_20261031.md b/docs/PRD_STUDIO_CONSOLE_DYNAMIC_LIVE_V3_20261031.md new file mode 100644 index 000000000..3973d12ec --- /dev/null +++ b/docs/PRD_STUDIO_CONSOLE_DYNAMIC_LIVE_V3_20261031.md @@ -0,0 +1,31 @@ +# ArSonMix PRD v3.0 — Studio Console workflow for REAL-TIME mixing +Date: 31 October 2026 · Primary product requirement · Owner: #170 / #192 + +## Purpose and benchmark +ArSonMix is a Windows-first low-latency LIVE digital mixer for stage, karaoke, podcast, broadcasting and user-configured ASIO/WASAPI, physical and virtual output destinations. The product is not a DAW timeline arranger/recorder and does not mandate OBS or virtual cable. Its everyday Console workflow should match the speed and capabilities of Studio One / Fender Studio Pro, with distinct premium ArSonMix gunmetal styling (no copyrighted asset cloning). +Official references: +- https://fenderstudiopromanual.fender.com/en/Content/Mixing_Topics/The_Console.htm +- https://fenderstudiopromanual.fender.com/en/Content/Mixing_Topics/Effects_Signal_Routing.htm + +## Required user flows (binding acceptance, not feature claims) +1. ADD CHANNEL creates a real mono/stereo audio channel node with its own stable ID, live FX rack, fader, meter, pan, mute/solo, input source selector and primary output; it may start unpatched/muted. Physical pin count does not limit logical channel count. No fake browser-only tracks. +2. Multi-select CH1, CH2, CH3 with Ctrl/Shift → right-click → ADD BUS FOR SELECTED CHANNELS creates a NEW, independently numbered and named GROUP BUS and changes all three PRIMARY OUT destinations to the new bus in one atomic operator action. Bus PRIMARY OUT defaults to MAIN. The input channels retain their numbers, hardware pin and FX state; no input lane is consumed to create the BUS. +3. ADD BUS creates an empty summing BUS. ADD FX CHANNEL creates an independent parallel FX RETURN with native VST3 inserts. Sources can SEND PRE/POST to FX while primary OUT remains unchanged; a reasonable reverb plugin can be set to 100% wet by the operator, not hardwired as DSP. +4. Each common Console strip displays IN (hardware alias or bus fan-in count), OUT → selected primary destination, and active SEND(s) with PRE/POST/gain/pan. OUT NONE must not erase SENDs: if sends exist, label SEND ONLY. An FX Bus or Group Bus has input-source count with click-to-list, Select All sources, Show/Hide Sources. Selected Bus highlights real accepted senders and downstream destination. Optional Signal Flow overlays solid primary paths and dashed parallel sends; no permanent spaghetti between faders. +5. Universal OUTPUT picker accepts MAIN, an existing legal BUS, NONE and real validated destination/monitor paths where implemented; illegal cycles/feedback/double-dry paths are rejected before acceptance. BUS may send to another BUS as long as the graph remains acyclic. +6. All audio lanes CH1..N, group, FX and MAIN share ONE native processing/insert lifecycle and uniform Rack GUI where role-appropriate. Real vendor editor, bypass, move, Show chunks and Plugin Catalog state are consistent. Duplicate creates an independent VST instance, not a shared plugin object. VCA/DCA Group is control-only, NOT an audio Bus. +7. Show SAVE/RECALL: stable ChannelIds, names, ordering, source bindings, routes, effects/chunks and safe hardware endpoint rebinding survive restart; never silently arm unknown outputs. + +## Visual and interaction baseline +- Keep original compact brushed gunmetal / steel, PNG faders, BTN-180, aligned meter/fader grid, MASTER pinned right, and low-end PC responsiveness. Distinct source/Group/FX role labels and tasteful color accents, zero artificial hover blur/glow, no oversized panels or repeated jargon. At 1366px bank or scroll horizontally, never cram 40 tiny strips. +- Source, OUT and SEND controls accessible from selected/individual strip in 1-2 meaningful actions. Advanced physical PATCH remains available separately, not required for routine BUS routing. +- Accepted native state vs pending DRAFT is explicit; activity LED/meter only for real native telemetry. Do not rerender all channel DOM nodes on each meter tick. + +## Current SOURCE-VERIFIED truth +main at draft baseline 22e4fdf: existing single native 10CH+4 AUX mixer callback, M2B BUS borrows an unused CH strip, CH1 vendor FX special case, MASTER FX/PDC incomplete. DynamicChannelRoster and DynamicPreparedMixerBlock are OFFLINE precompiled foundations, not live JUCE channels. DEVICE4 named I/O remains production functionality. The new group/FX batch transaction is a CONTROL-THREAD feature and still cannot be clicked as live ADD BUS until native callback handoff is complete. CI green is not physical zero-FX FAT (#15). + +## Feature milestone acceptance +M3: replace old fixed 10CH engine with ONE ChannelId-keyed live graph/FX instance owner preserving all existing device/Show/Orbit/monitor data. Physically patch Mic1/Mic2 to a NEW Vocal Bus (not borrowed CH10), then add a NEW FX Reverb return; preserve MAIN and AUX and reject stale ACK/feedback. +M4: full Console keyboard and right-click selected-channel workflow plus real BUS source list, OUT selector, highlighted accepted routing, dynamic strip views, safe Show of N channels; 1366/1440/1680 Chromium geometry and browser-vs-native differentiation. +M5: native MASTER FX/PDC/zero-FX crackle #15 mitigation with Windows hardware FAT: 44.1/48/96 kHz, 64/128/256 buffers, 30-minute soak, plugin state restore and device loss, driver telemetry and low-end responsiveness. +DONE = native PCM + exact-head Windows MSVC/CTest/ZIP + Chromium UI + actual physical FAT, never merely screenshots or source contracts. From 22d028a84fa392ed266d68e07b49daae9839e746 Mon Sep 17 00:00:00 2001 From: Ari Sulistiono Date: Sat, 31 Oct 2026 20:01:28 +0700 Subject: [PATCH 04/12] docs(m3): ARD_STUDIO_CONSOLE_DYNAMIC_LIVE_V3_20261031.md canonical Studio Console v3 --- ...STUDIO_CONSOLE_DYNAMIC_LIVE_V3_20261031.md | 28 +++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 docs/ARD_STUDIO_CONSOLE_DYNAMIC_LIVE_V3_20261031.md diff --git a/docs/ARD_STUDIO_CONSOLE_DYNAMIC_LIVE_V3_20261031.md b/docs/ARD_STUDIO_CONSOLE_DYNAMIC_LIVE_V3_20261031.md new file mode 100644 index 000000000..1d1fd490e --- /dev/null +++ b/docs/ARD_STUDIO_CONSOLE_DYNAMIC_LIVE_V3_20261031.md @@ -0,0 +1,28 @@ +# ArSonMix ARD v3.0 — Single ChannelId Graph and Studio-style Bus Workflow +Date: 31 October 2026 · Technical architecture for #192, #95, #174 and #15 + +## Non-negotiable architecture +ONE JUCE AudioDeviceManager / input callback, ONE native immutable prepared audio routing graph, ONE authoritative session ChannelId roster and FX lease map. Do not add another WebAudio/JS DSP, plugin host, standby render graph or second callback. ArSonMix must remain a REAL-TIME mixer, not an audio editor. Use existing DynamicChannelRoster.h, DynamicPreparedMixerBlock.h and LegacyLiveGraphMigration.h, rather than rewriting a naive mixer from scratch. + +## Domain / persistent state +- Stable uint64 ChannelId identifies each actual audio lane independently of display ordering and physical I/O pins. Roles: INPUT, GROUP, FX RETURN, MAIN and MONITOR. A VCA/DCA is a separate controller, NOT a signal-summing Bus. +- Channel: role, name, mono/stereo PROCESSING FORMAT, separately verified SOURCE binding, signed gain/pan/mute/solo, VST3 catalog refs + independently created native instance leases, primary OutputDestination, and zero-or-more parallel SEND edges PRE/POST with send gain, pan and enabled state. Naming source format vs processing format vs physical pin count must remain independent. +- The V3 control-roster implementation tags primaryOutput on a ChannelSendRef to preserve current DynamicPreparedMixerBlock edge ABI; the single primary OUT edge is distinct from other parallel sends. OUT NONE removes only primary output. DSP graph compiler must prevent cycles, duplicate graph edges, invalid destinations, format mismatches and accidental dry duplication. + +## Atomic Studio transaction +- Add Bus for Selected Channels accepts expected session revision + a set of unique source ChannelIds, creates a NEW independent GROUP ChannelId, replaces each selected channel's primary OUT with new Bus, adds Bus's primary OUT → MAIN, and leaves all parallel SENDs unchanged. One action/one validated candidate, no half-routed intermediate session and no stale index references. +- Add FX Channel for selected channels creates new FX RETURN, keeps source primary OUT as-is, adds parallel POST SEND(s) at selected send gain, and connects FX return to MAIN. Separate empty BUS/FX commands create new nodes without sources; source can be assigned later. Rename/reorder/delete/copy/duplicate use the stable ID. +- Stage off RT, validate resource budget and compiled topological DAG, prepare channel scratch and VST instances off callback, then only publish live after approved device-epoch / route-revision / MUTE and native ACK. Failures leave accepted audio byte-identical, no hidden unmute or auto hardware switch. + +## DSP and GUI wiring plan +1. DYN0 stable ChannelId roster and DYN1A/B preallocated PCM graph already exist. DYN1C control-thread createBusForSelected / setPrimaryOutput plus two-mic PCM tests are now implemented in the M3 candidate PR, NOT live user actions. +2. Migrate current 10 CH + 4 AUX + MAIN + independent MONITOR/secondary output Show to ChannelIds, matching old exact PCM and preserving sparse ASIO callback ordinal translation, channel mode, fader smoothing, solo closure, mono MASTER after FX, vendor Orbit, native CH1 Show chunks, editor identity and VST3 sidechain. +3. Resolve legacy CH1 special-case FX ownership. Key per-ChannelId native lease through single immutable audio schedule. No second processing/render or per-callback heap/mutex/JSON, no copying plugin object while busy. Prewarm/prepare/destroy in quiescent control thread with bounded fade/retirement. +4. Expose one native ACKed SessionSnapshot containing IDs/order, accepted sources, primary destinations and sends, fan-in count, plugin instances, meter IDs, and epoch/revision. JS app/bridge/mixer-io/monitor are projections of that same snapshot. Draft state is separate overlay; no placeholder Groups or parallel JS 10CH registry. +5. Render same compact strip component regardless of role; only source-specific controls (no physical preamp on BUS) are semantically hidden. Highlight relations from accepted graph on selection changes, not animated per audio buffer. Auto-bank/virtualize N strips at 1366px, preserve pinned MASTER and all L2 geometry. + +## Reliability / vetoes +- Real-time callback: bounded preallocated buffers, no allocations/locks/device enumerate/VST lifecycle/graph sort/JS IPC. The renderer's prepared graph owns mono/stereo input, external FX callbacks via stable id, PRE/POST sends and physical MAIN/MONITOR split. Topology compile remains O(V+E) control-side with memory and CPU admission; do NOT promise unlimited active channels. +- MUTE→APPLY→native revision ACK governs structural changes; continuity and crackle must be tested physically. Realtime fader/pan/mute/send gain changes use smoothed RT-safe parameters, not graph rebuild. +- Regresion gates: old 10CH/4AUX/CH1 Orbital native state and Show, all M1/M2B and DEVICE4 source/device switching, master/monitor/secondary output route, independent streams and factory FX provenance, low-end GUI. +- 0-VST crackle issue #15 and true roundtrip ASIO/WASAPI measured latency are NOT solved by green Windows CI. Refuse to mark hardware FAT complete without real audio. From 20dac48be872f24d6b5c3cfb869edc5f7dc72723 Mon Sep 17 00:00:00 2001 From: Ari Sulistiono Date: Sat, 31 Oct 2026 20:01:31 +0700 Subject: [PATCH 05/12] docs(m3): HANDOFF_STUDIO_CONSOLE_M3_M5_20261031.md canonical Studio Console v3 --- docs/HANDOFF_STUDIO_CONSOLE_M3_M5_20261031.md | 30 +++++++++++++++++++ 1 file changed, 30 insertions(+) create mode 100644 docs/HANDOFF_STUDIO_CONSOLE_M3_M5_20261031.md diff --git a/docs/HANDOFF_STUDIO_CONSOLE_M3_M5_20261031.md b/docs/HANDOFF_STUDIO_CONSOLE_M3_M5_20261031.md new file mode 100644 index 000000000..ea2236030 --- /dev/null +++ b/docs/HANDOFF_STUDIO_CONSOLE_M3_M5_20261031.md @@ -0,0 +1,30 @@ +# Handoff v3 — implement true Studio-style ArSonMix Console +Date: 31 October 2026 · Engineering execution / physical FAT + +## Product directive and read-first order +Read AGENTS.md, PRD_STUDIO_CONSOLE_DYNAMIC_LIVE_V3_20261031.md, ARD_STUDIO_CONSOLE_DYNAMIC_LIVE_V3_20261031.md, DYN1B_LEGACY_PARITY_BRIDGE_20261031.md, then latest main branch, PR ledger, exact source and CI. +The app is a flexible realtime mixer for karaoke/live/podcast/broadcast; mirror Studio One CONSOLE operator actions (not arrangement/timeline editing), keep original ArSonMix material beauty, optimize for low-spec PCs and do not assume OBS/virtual cable. +Official sources: https://fenderstudiopromanual.fender.com/en/Content/Mixing_Topics/The_Console.htm ; https://fenderstudiopromanual.fender.com/en/Content/Mixing_Topics/Effects_Signal_Routing.htm + +## Accurate baseline and concurrent owners +At original audit main 22e4fdf: M2B #235 merged with 10CH capacity and BUS borrowing an unused strip; DEVICE4 named ASIO/WASAPI source matrix merged; CH1 special legacy VST and native 10CH+4 AUX renderer unchanged. DYN0 and DYN1B are offline; DO NOT pretend live ADD TRACK. #192 = ChannelId graph owner, #95 native FX/PDC, #170 product, #174 bus, #15 hardware 0FX crackle. Older unmerged #115/#117/#225/#229 PRs may conflict; do not bulk merge. +This PR adds a real CONTROL-THREAD group/parallel-FX batch operation plus one deterministic PCM regression. It does NOT expose new live channels yet. + +## M3 — one meaningful native live feature milestone, not tiny UX PRs +- Keep exactly ONE callback and graph. Start by compiling actual incumbent routing (10 CH, 4 AUX, monitor, MAIN, source aliases, device/epoch/revision) into ChannelId-based PCM and comparing native sampled audio plus plugin order. Freeze Show compatibility and plugin instance lifetimes; CH1 vendor Orbit and editor must not be orphaned. +- New control API supports ADD BUS FOR SELECTED CHANNELS: unique source IDs, new GROUP ID, source exclusive OUT to Group, Group OUT MAIN, preserve existing sends. ADD FX CHANNEL: same new node but sources keep their OUT and gain-controlled parallel sends. OUT NONE is silent on primary but independent sends can continue. +- Add real native command/ACK with stale revision, cycles, device epoch, full budget and malformed input rejection; prepare VSTs off RT, bounded ramp handoff and memory retirement safe. No new physical pins, duplicate graph, callback allocations or uncontrolled structural change while output armed. +- Gate: two physical inputs to genuinely new Group + FX Channel (not CH10), correct FX insert/process and meter, positive native ACK, rollback preserving old audio and old Show, old 10CH golden PCM, build + package green. No fake GUI +BUTTON until this passes. + +## M4 — integrated premium Studio Console GUI +- Full Ctrl/Shift multi-select and right-click Add Bus for Selected Channels in one action. Empty ADD CHANNEL, ADD BUS, ADD FX CHANNEL; rename/duplicate/delete/reorder and saved user Strip/FX state. Safe 1366px banked UI and pinned MAIN. +- Every common strip shows IN verified alias (or BUS IN source count), OUT primary MAIN/BUS/NONE, parallel sends PRE/POST levels. BUS input count opens source list with Select All and Hide/Show Sources; select a BUS highlights its sources and destinations; optional Signal Flow selected map solid primary vs dashed parallel. Show live accepted state distinct from DRAFT. +- No tooltip clutter, blur/glow or huge cards; preserve exact fader PNG, knob feel, 11-strip L2 grid and fast native/WebView2 pointer. Do not re-run routing graph based on hover or per-buffer meter paints. + +## M5 — hardening, PDC, true physical FAT and distribution +- Equal CH1..N/FX/MAIN insert lease and editor, native MASTER FX/PDC policy with intentional zero-FX fast path, full VST3 vendor chunks on Show Save/Recall, correct physical and monitor buses. +- Native golden/negative tests (2 mic submix, parallel FX, OUT NONE, nested bus/no feedback, resource budget, stale device, editor lease, plugin failure rollback), Chromium 1366/1440/1680, Windows exact-SHA MSVC/CTest + integrity-verified ZIP, then physical Windows ASIO/WASAPI 44.1/48/96k at 64/128/256 frames, measured latency/xruns, 30-minute soak, #15 0FX crackle, vendor driver unplug/hotplug and low-end iGPU. +- Save exact source SHA, device driver, patch, buffer, log/spectrogram/loopback and evidence. Hardware FAT cannot be marked PASS from CI screenshots. Do NOT promise absolute 0ms latency, unbounded active channels or third-party plugin licenses. + +## Merge and efficiency rules +One integrated M3 code gate per meaningful delivery; no repeated commits that run Windows CI for docs-only changes. Refresh main and PR head before merging. Never destroy M2B/DEVICE4/FX lease; reject unsafe operation and retain previous accepted graph. Keep product decision, ADR/PRD/HANDOFF synchronized through versioned docs, not contradictory stale historical handoffs. From ef0f394b1b0721572aa3b11e08bb4c64300c1b23 Mon Sep 17 00:00:00 2001 From: Ari Sulistiono Date: Sat, 31 Oct 2026 20:01:58 +0700 Subject: [PATCH 06/12] docs(m3): reconcile AGENTS.md with authoritative Studio Console v3 --- AGENTS.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 1517a53b6..76c080867 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,4 +1,6 @@ -> **M2 UNIFIED FX CONSOLE / BUS WORKFLOW 2026-10-31 (BRANCH IN VALIDATION):** Read docs/M2_UNIFIED_CONSOLE_BUS_WORKFLOW_20261031.md before editing FX Rack/bus routing. Current branch unifies CH1–10 FX Rack UI using one presenter and offers real +BUS/+FX BUS using an otherwise unused native 10CH lane and existing muted native ACK. It intentionally does NOT remove CH1's legacy vendor VST3 lease, create dynamic CH11, implement native MASTER FX/PDC, or certify physical #15 FAT. Protect device + SOURCE PR #228/#231/#232/#233, Show/Orbit, one JUCE callback, epoch revision ACK, and AGENTS product truth. The next major engine milestone is real per-ChannelId FxRack/Show migration, not another cosmetic branch. +> **LATEST PRODUCT/ENGINE CONTRACT 2026-10-31: M3 REAL DYNAMIC STUDIO CONSOLE.** Read [PRD v3](docs/PRD_STUDIO_CONSOLE_DYNAMIC_LIVE_V3_20261031.md), [ARD v3](docs/ARD_STUDIO_CONSOLE_DYNAMIC_LIVE_V3_20261031.md), [M3–M5 handoff](docs/HANDOFF_STUDIO_CONSOLE_M3_M5_20261031.md) BEFORE modifying channel, routing, bus, FX, Show or GUI. Studio One operator parity: real Add Channel, Add Bus for Selected Channels, Add FX Channel, permanent IN / primary OUT / parallel SEND and BUS source-count + selected highlight. A BUS is a NEW independent stable ChannelId, NEVER CH10 borrowed. ONE prepared native DSP graph, ONE JUCE callback, independently owned VST3 lease for CH1..N/Bus/Main, epoch/revision-fenced native ACK, zero unnecessary runtime allocations. Existing M2B and DEVICE4 MUST be preserved. Current M3 control-thread bus batch and PCM tests are NOT yet live GUI/ASIO features. No fake JS channels, no new timeline editor, no OBS-only routing, no absolute zero-millisecond latency promises. Preserve L2 compact premium brushed gunmetal faders/meter alignment, no blur/glow, low-end pointer performance and #15 0-VST crackle FAT gate. This CURRENT directive supersedes historical 10CH milestone priority/status, not the safety invariants. + +> **M2 UNIFIED FX CONSOLE / BUS WORKFLOW 2026-10-31 (MERGED HISTORICAL BASELINE):** Read docs/M2_UNIFIED_CONSOLE_BUS_WORKFLOW_20261031.md before editing FX Rack/bus routing. Current branch unifies CH1–10 FX Rack UI using one presenter and offers real +BUS/+FX BUS using an otherwise unused native 10CH lane and existing muted native ACK. It intentionally does NOT remove CH1's legacy vendor VST3 lease, create dynamic CH11, implement native MASTER FX/PDC, or certify physical #15 FAT. Protect device + SOURCE PR #228/#231/#232/#233, Show/Orbit, one JUCE callback, epoch revision ACK, and AGENTS product truth. The next major engine milestone is real per-ChannelId FxRack/Show migration, not another cosmetic branch. > **LATEST CROSS-THREAD STATUS (2026-10-31, main after #234):** Read [M1/M2 & release reconciliation](docs/RECONCILED_PROGRESS_M1_M2_20261031.md) FIRST. DEVICE2+SOURCE2 are merged together in #234 (`7db4ab70`); #232 closed superseded, never merge its old head. #235 M2 FX/BUS is OPEN with Chromium regressions and not production; #229/#225 FactoryFX overlap and need selective reconcile. The native Windows FAT ZIP from `main@a7fb6151` predates #234; use a newer successful main artifact when published. No MAONO/WASAPI hardware FAT or #15 zero-VST crackle clearance, and FactoryFX approved lock still empty. Older AGENTS milestones below are historical if they conflict. Preserve one JUCE device owner, one native graph/route authority, stable L2/RAIL3, and explicit native ACK / output safety. From ba0750840a57e7052d260a2df42ec7490013a06e Mon Sep 17 00:00:00 2001 From: Ari Sulistiono Date: Sat, 31 Oct 2026 20:02:03 +0700 Subject: [PATCH 07/12] docs(m3): reconcile docs/PRD_ARSONMIX_PRO_MIXER_WORKSPACE_ROUTING_20261030.md with authoritative Studio Console v3 --- docs/PRD_ARSONMIX_PRO_MIXER_WORKSPACE_ROUTING_20261030.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/PRD_ARSONMIX_PRO_MIXER_WORKSPACE_ROUTING_20261030.md b/docs/PRD_ARSONMIX_PRO_MIXER_WORKSPACE_ROUTING_20261030.md index 4618991ce..d26b789e1 100644 --- a/docs/PRD_ARSONMIX_PRO_MIXER_WORKSPACE_ROUTING_20261030.md +++ b/docs/PRD_ARSONMIX_PRO_MIXER_WORKSPACE_ROUTING_20261030.md @@ -1,3 +1,5 @@ +> **SUPERSEDED AS CURRENT PRIORITY BY STUDIO CONSOLE v3 (2026-10-31):** [PRD v3](PRD_STUDIO_CONSOLE_DYNAMIC_LIVE_V3_20261031.md) · [ARD v3](ARD_STUDIO_CONSOLE_DYNAMIC_LIVE_V3_20261031.md) · [implementation handoff v3](HANDOFF_STUDIO_CONSOLE_M3_M5_20261031.md). This earlier file remains historical detail. Existing 10CH native M2B and DEVICE4 are merged; live dynamic CH/BUS and common CH1 vendor lifecycle are NOT complete. Read v3 and current main before acting. Safety/Show/zero-FX hardware requirements here still apply. + # ArSonMix — PRD v2.0: Pro Digital Mixer, Channel Modes, Hardware I/O and AUX/BUS **2026-10-30 hardware setup implementation addendum:** [crosspoint PRD](PRD_HARDWARE_AUDIO_IO_MATRIX_20261030.md) adds real verified-pin M/L/R input and MAIN output matrices reusing the existing native epoch/revision ACK controller. This is a focused operator UX milestone, not a second DSP engine or completion of physical MONITOR/DYN2/zero-FX hardware FAT. The existing descriptions below are architectural goals and may reflect earlier implementation states. From e9e1b643432d848410808ba387bcf22a5d58d007 Mon Sep 17 00:00:00 2001 From: Ari Sulistiono Date: Sat, 31 Oct 2026 20:02:08 +0700 Subject: [PATCH 08/12] docs(m3): reconcile docs/ARD_PRD_MIXER_IO_AUX_BUS_REFORM_20261030.md with authoritative Studio Console v3 --- docs/ARD_PRD_MIXER_IO_AUX_BUS_REFORM_20261030.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/ARD_PRD_MIXER_IO_AUX_BUS_REFORM_20261030.md b/docs/ARD_PRD_MIXER_IO_AUX_BUS_REFORM_20261030.md index 2a6727ab4..bffc0bbe4 100644 --- a/docs/ARD_PRD_MIXER_IO_AUX_BUS_REFORM_20261030.md +++ b/docs/ARD_PRD_MIXER_IO_AUX_BUS_REFORM_20261030.md @@ -1,3 +1,5 @@ +> **SUPERSEDED AS CURRENT PRIORITY BY STUDIO CONSOLE v3 (2026-10-31):** [PRD v3](PRD_STUDIO_CONSOLE_DYNAMIC_LIVE_V3_20261031.md) · [ARD v3](ARD_STUDIO_CONSOLE_DYNAMIC_LIVE_V3_20261031.md) · [implementation handoff v3](HANDOFF_STUDIO_CONSOLE_M3_M5_20261031.md). This earlier file remains historical detail. Existing 10CH native M2B and DEVICE4 are merged; live dynamic CH/BUS and common CH1 vendor lifecycle are NOT complete. Read v3 and current main before acting. Safety/Show/zero-FX hardware requirements here still apply. + # ArSonMix — ARD v2.0: Unified Mixer, Native Hardware I/O, FX Rack and AUX/Bus Routing **2026-10-30 native-connected hardware matrix implementation:** [implementation ARD](ARD_HARDWARE_AUDIO_IO_MATRIX_20261030.md), [operator PRD](PRD_HARDWARE_AUDIO_IO_MATRIX_20261030.md), [handoff](HANDOFF_HARDWARE_IO_MATRIX_20261030.md). Matrix crosspoints use existing `monitor.js` staging and the native ASIO/WASAPI route controller. UI-only incomplete stereo cannot publish audio; MAIN physical output requires ACK. Still fixed 10 live sources+4 AUX; MS3B MONITOR and DYN2 expansion are separate; #15 hardware FAT is open. From fb463ff4132a3b1de97732ec36c24ebd40205207 Mon Sep 17 00:00:00 2001 From: Ari Sulistiono Date: Sat, 31 Oct 2026 20:02:12 +0700 Subject: [PATCH 09/12] docs(m3): reconcile docs/EXECUTION_HANDOFF_ARSONMIX_MIXER_REFORM_20261030.md with authoritative Studio Console v3 --- docs/EXECUTION_HANDOFF_ARSONMIX_MIXER_REFORM_20261030.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/EXECUTION_HANDOFF_ARSONMIX_MIXER_REFORM_20261030.md b/docs/EXECUTION_HANDOFF_ARSONMIX_MIXER_REFORM_20261030.md index 808041a04..d0a5eb363 100644 --- a/docs/EXECUTION_HANDOFF_ARSONMIX_MIXER_REFORM_20261030.md +++ b/docs/EXECUTION_HANDOFF_ARSONMIX_MIXER_REFORM_20261030.md @@ -1,3 +1,5 @@ +> **SUPERSEDED AS CURRENT PRIORITY BY STUDIO CONSOLE v3 (2026-10-31):** [PRD v3](PRD_STUDIO_CONSOLE_DYNAMIC_LIVE_V3_20261031.md) · [ARD v3](ARD_STUDIO_CONSOLE_DYNAMIC_LIVE_V3_20261031.md) · [implementation handoff v3](HANDOFF_STUDIO_CONSOLE_M3_M5_20261031.md). This earlier file remains historical detail. Existing 10CH native M2B and DEVICE4 are merged; live dynamic CH/BUS and common CH1 vendor lifecycle are NOT complete. Read v3 and current main before acting. Safety/Show/zero-FX hardware requirements here still apply. + # ARSONMIX — 2026-10-30 NEXT-THREAD EXECUTION HANDOFF (CANONICAL) **R6 override (2026-10-30):** This historical G1/G2 handoff is NOT the current work queue. [Audited R6 architecture/current status](R6_CURRENT_STATE_ARCHITECTURE_EXECUTION_20261030.md), [operator UX contract](R6_OPERATOR_WORKFLOW_CONTRACT_20261030.md) and #176 L2 shell supersede it. Main@8251bd6e includes G1/G2, G3 and L2; next milestone #173 native mono/stereo, then #174 typed FX/group buses, #175 multi-hardware outputs, #95 FX/PDC and parallel #15. Keep all 11 faders linked, original VST CH1 Orbit, native ACK/MUTE, and existing left rail. Treat old statements below as historical for their date. From 95afbbd3e879ce45db4d8b3de9dceba7da681a30 Mon Sep 17 00:00:00 2001 From: Ari Sulistiono Date: Sat, 31 Oct 2026 20:11:16 +0700 Subject: [PATCH 10/12] perf(m3): O(N+S) stable ID admission for multi-source Bus transaction --- engine/core/DynamicChannelRoster.h | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/engine/core/DynamicChannelRoster.h b/engine/core/DynamicChannelRoster.h index 72b78533d..0981ee840 100644 --- a/engine/core/DynamicChannelRoster.h +++ b/engine/core/DynamicChannelRoster.h @@ -10,6 +10,7 @@ #include #include #include +#include // DYN0: control-thread session model, NOT a second renderer or a LIVE audio graph. // One state type serves every future input, return, group, monitor and master. @@ -258,6 +259,12 @@ class DynamicChannelRoster final { result.fault=ChannelEditFault::idExhausted;return result; } auto candidate=channels_; + // One O(N) stable-ID lookup; a 1000-channel group assignment must + // not scan all descriptors for each source selected in the Console. + std::unordered_map indexById; + indexById.reserve(candidate.size()); + for(std::size_t i=0;i(found->second); if(it->role==ChannelRole::main || it->role==ChannelRole::monitor) { result.fault=ChannelEditFault::invalidValue;return result; } From 1f760ed46d869fe35e8f5b14bc325857ae4de62e Mon Sep 17 00:00:00 2001 From: Ari Sulistiono Date: Sat, 31 Oct 2026 20:11:31 +0700 Subject: [PATCH 11/12] fix(m3): classify legacy direct-to-MAIN as exclusive primary OUT for safe Bus migration --- engine/core/LegacyLiveGraphMigration.h | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/engine/core/LegacyLiveGraphMigration.h b/engine/core/LegacyLiveGraphMigration.h index a22e29327..2358e6724 100644 --- a/engine/core/LegacyLiveGraphMigration.h +++ b/engine/core/LegacyLiveGraphMigration.h @@ -116,9 +116,10 @@ class LegacyGraphMigration final { op.id=id;op.enabled=enabled;ops.push_back(std::move(op)); }; const auto link=[&](ChannelId from,ChannelId to,float gain, - float pan=0.f,bool pre=false){ + float pan=0.f,bool pre=false,bool primary=false){ ChannelEdit op;op.kind=ChannelEdit::Kind::addSendReference; op.id=from;op.target=to;op.value=gain;op.sendPan=pan;op.preFader=pre; + op.primaryOutput=primary; ops.push_back(std::move(op)); }; for(int i=0;i0.f) link(id,next.ids.monitor,monitorGains[i]); } @@ -149,7 +150,7 @@ class LegacyGraphMigration final { ChannelEdit marker;marker.kind=ChannelEdit::Kind::addInsertReference; marker.id=id;marker.text="legacy:aux-rack"; ops.push_back(std::move(marker)); - if(cfg.toMaster)link(id,next.ids.main,1.f); + if(cfg.toMaster)link(id,next.ids.main,1.f,0.f,false,true); if(monitorEnabled && monitorGains[stripCount+b]>0.f) link(id,next.ids.monitor,monitorGains[stripCount+b]); } From 39bf682afee075b807951bd6862e153026892ff3 Mon Sep 17 00:00:00 2001 From: Ari Sulistiono Date: Sat, 31 Oct 2026 20:12:01 +0700 Subject: [PATCH 12/12] test(m3): legacy-to-dynamic Bus reroute removes old MAIN primary with no doubled signal --- tests/mixer_routing_plan_test.cpp | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/tests/mixer_routing_plan_test.cpp b/tests/mixer_routing_plan_test.cpp index a4ccd898f..a367a50a9 100644 --- a/tests/mixer_routing_plan_test.cpp +++ b/tests/mixer_routing_plan_test.cpp @@ -475,6 +475,29 @@ static void verifyLegacyToDynamicProductionPcmParity() { assert(migrated.ids.legacyFxIndex(migrated.ids.aux[0])==stripCount); assert(migrated.ids.legacyFxIndex(migrated.ids.main)==-1); assert(migrated.ids.legacyFxIndex(migrated.ids.monitor)==-2); + // M3: legacy implicit MAIN paths are now marked PRIMARY, not ordinary + // parallel SENDs. Otherwise a migrated Studio subgroup would double + // its dry output (old direct MAIN plus new BUS -> MAIN). + const auto& direct=migrated.roster.find(migrated.ids.inputs[1])->sends; + assert(std::any_of(direct.begin(),direct.end(),[&](const auto& edge){ + return edge.destination==migrated.ids.main && edge.primaryOutput; + })); + const auto& auxDirect=migrated.roster.find(migrated.ids.aux[0])->sends; + assert(std::any_of(auxDirect.begin(),auxDirect.end(),[&](const auto& edge){ + return edge.destination==migrated.ids.main && edge.primaryOutput; + })); + DynamicChannelRoster audition=migrated.roster; // only control-side clone + const std::array toBus{migrated.ids.inputs[1]}; + const auto newBus=audition.createBusForSelected( + audition.revision(),toBus,"MIGRATED VOCAL BUS",ChannelRole::group); + assert(newBus.ok() && audition.size()==migrated.roster.size()+1); + const auto& redirected=audition.find(migrated.ids.inputs[1])->sends; + assert(std::none_of(redirected.begin(),redirected.end(),[&](const auto& edge){ + return edge.primaryOutput && edge.destination==migrated.ids.main; + })); + assert(std::any_of(redirected.begin(),redirected.end(),[&](const auto& edge){ + return edge.primaryOutput && edge.destination==newBus.createdIds.front(); + })); PreparedRenderGraph oldGraph; RenderError error; assert(PreparedRenderGraph::compile(channels,ports,sends,oldGraph,error,aux));