diff --git a/docs/architecture/FEATURE_HOTKEY_FL_OUTPUT_EXECUTION_20261111.md b/docs/architecture/FEATURE_HOTKEY_FL_OUTPUT_EXECUTION_20261111.md index fda38d54d..1e85e0fd9 100644 --- a/docs/architecture/FEATURE_HOTKEY_FL_OUTPUT_EXECUTION_20261111.md +++ b/docs/architecture/FEATURE_HOTKEY_FL_OUTPUT_EXECUTION_20261111.md @@ -1,7 +1,7 @@ # ArSonMix — Hotkey Register & FL Studio External OUT ## Verified UX Research + Engineering Execution Blueprint — 2026-11-11 -**Status: USER-APPROVED DIRECTION / NOT IMPLEMENTED / PHYSICAL FAT PENDING.** +**Status update 2026-11-11: H1 MERGED (#536), H2 MERGED (#551), H2 integration Windows 86/86 CTest PASS; O1/O2 PHYSICAL MULTI-OUTPUT NOT IMPLEMENTED, REAL ASIO FAT PENDING.** For O-only work use [new-thread execution handoff](MILESTONE_O_MULTIOUTPUT_NEW_THREAD_20261111.md). The original research/acceptance contract remains binding. **Audited source:** main a07b16e1c6f04473d328ddd1deab607774375ee3; refresh main and PRs before coding. **Authority:** AGENTS.md, architecture/README.md, MAINTAINABILITY_EXECUTION_V1_20261111.md, FEATURE_EXTENSION_PLAYBOOK.md. Preserve exactly one assembled /preview/ GUI, one installed ChannelId/EdgeId native PCM graph and JUCE callback, one native ACK/readback truth. This document is a product feature workpack, not a new engine proposal or an additional approval gate. diff --git a/docs/architecture/HOTKEY_OUTPUT_NEXT_THREAD_PROMPT_20261111.md b/docs/architecture/HOTKEY_OUTPUT_NEXT_THREAD_PROMPT_20261111.md index af6f0fb09..edd6283a4 100644 --- a/docs/architecture/HOTKEY_OUTPUT_NEXT_THREAD_PROMPT_20261111.md +++ b/docs/architecture/HOTKEY_OUTPUT_NEXT_THREAD_PROMPT_20261111.md @@ -1,6 +1,6 @@ # ArSonMix Hotkey + FL Studio External OUT — Next Execution Thread Prompt -**Status: READABLE EXECUTION HANDOFF.** The technical UX/native contract is [FEATURE_HOTKEY_FL_OUTPUT_EXECUTION_20261111.md](FEATURE_HOTKEY_FL_OUTPUT_EXECUTION_20261111.md). This file authorizes NO unqualified release or unsafe output reassignment. +**HISTORICAL combined H+O mission. H1/H2 are already MERGED (#536/#551). New work should use the [O-ONLY implementation prompt](MILESTONE_O_MULTIOUTPUT_NEW_THREAD_20261111.md); do not reimplement H.** The technical UX/native contract is [FEATURE_HOTKEY_FL_OUTPUT_EXECUTION_20261111.md](FEATURE_HOTKEY_FL_OUTPUT_EXECUTION_20261111.md). This file authorizes NO unqualified release or unsafe output reassignment. Copy the following mission into the next thread (or follow it directly): diff --git a/docs/architecture/MILESTONE_O_MULTIOUTPUT_NEW_THREAD_20261111.md b/docs/architecture/MILESTONE_O_MULTIOUTPUT_NEW_THREAD_20261111.md new file mode 100644 index 000000000..0af570bba --- /dev/null +++ b/docs/architecture/MILESTONE_O_MULTIOUTPUT_NEW_THREAD_20261111.md @@ -0,0 +1,28 @@ +# ArSonMix — NEW THREAD: MILESTONE O ONLY (FL Studio-style physical multi-output) +**Updated:** 2026-11-11 · **Status:** O1/O2 NOT IMPLEMENTED; physical 8-output ASIO FAT PENDING. **Current main at handoff:** `0d4bb2c2ec539d8156d2e43c5ef6f02e23df2d12` (refresh from GitHub; never treat this SHA as immutable). + +**H is DONE in repository — do not repeat it.** H1 global Mute/Solo/FX Rack Power/FX-slot hotkeys merged [#536](https://github.com/masarray/arsonmix/pull/536) (`7da5451e4e395d2fb7a1d4c215b4ba41e6fba1af`); H2 third-party hosted VST3 parameter hotkeys (ParamID, Toggle, Step +/−, Browse Parameters, Last Touched), merged [#551](https://github.com/masarray/arsonmix/pull/551) (`0626591e4dc9f18d3c1ae3d863741cbb6fe5eb05`). Exact H2 integration Windows [FAT #42927881962](https://github.com/masarray/arsonmix/actions/runs/42927881962): MSVC/86 of 86 CTest PASS, verified ZIP/installer (physical vendor/hardware FAT separate). + +## Copy/paste mission for the O-only thread +GitHub connector: https://github.com/masarray/arsonmix. **IMPLEMENT O1 immediately** as a coherent native engine+approved GUI+persistence+tests PR, not a planning-only PR. Do NOT modify/reimplement H1/H2, add hotkey features, or merge ongoing Harmonice/maintainability PRs by accident. Main HEAD, active PRs and audio authority MUST be checked fresh. + +Read [AGENTS.md](../../AGENTS.md), [Smart CI runbook](../SMART_CI_RUNNER_WORKFLOW.md), [architecture map](README.md), [feature playbook](FEATURE_EXTENSION_PLAYBOOK.md), and the complete [FL Studio EXTERNAL OUT contract](FEATURE_HOTKEY_FL_OUTPUT_EXECUTION_20261111.md). Trace existing approved `/preview/` gesture → WebView transport → native intent → control-thread graph/port validation → prepared ChannelId PCM publisher → ONE JUCE ASIO audio callback → device pins → correlated ACK and independent installed readback. Audit current routes before editing, then implement in the same PR. + +**O1 UI/behavior (FL Studio familiar):** On selected `INPUT`, `GROUP` or `FX_RETURN`, show a compact `INTERNAL OUT` (existing WIRE MAIN/GROUP/SOURCE ONLY) and separate `EXTERNAL OUT` dropdown (`None` plus real active driver-verified ASIO stereo pairs and exact labels). Default `None`. Selecting External OUT NEVER disconnects internal WIRE or makes an extra MASTER. To output exclusively to hardware, operator explicitly disconnects existing internal route / chooses SOURCE ONLY. In that state, channel signal/meter/FX and independent external hardware audio remain; MAIN becomes silent for that channel. Preserve approved `/preview/` SVG fader, FX rack, buttons and existing OUTPUTS matrix. No new GUI system. + +**O1 engine:** Use the *same* accepted ChannelId/EdgeId graph, `DynamicPreparedMixerBlock`, `DynamicNativeSessionPublisher`, `LiveDryRoutingLab`, and `LiveAudioEngine` callback. Prepare bounded physical output taps and deterministic per-pair sums **after** channel/BUS FX/fader/pan/solo/mute/PDC in one render graph pass; VST3 executes ONCE per channel per buffer. MAIN/MONITOR own their verified pairs; independent secondary WASAPI retains its original MAIN-copy clock bridge and cannot pace ASIO. Never invent physical pins, use sparse bitmask ordinals as numeric indices, clear aliasing inputs prematurely, create another PCM renderer/callback/device manager, or do allocations/locks/JSON/logging/blocking on the audio callback. + +**Native control safety:** Typed `SET_EXTERNAL_OUTPUT` equivalent with `requestId`, stable `ChannelId`, verified exact backend/device, output pair labels and mask, epoch, graph/roster revision. Prepare immutable new plan on CONTROL, safely transition/declick, publish atomically, emit ACK and *later* accepted device+output readback. Invalid/stale/unsupported assignment must preserve prior installed sound/route and show `REJECTED` or `NEEDS REMAP`, not fake LIVE. No new amplifier pin is armed automatically. Multiple intentional sources may sum to the same pair. A duplicate source-to-same-pair path via MAIN **must warn/require deliberate confirmation**, and a BUS must not steal MONITOR-owned pins. Explicit device/pin collision policy, never silent redirection. + +**Persistence/reconnect:** Save requested External OUT as stable `ChannelId` + device/profile/pair logical identity in additive `.smix` schema, not callback ordinals or a live pointer. Revalidate after restart/swap/rate/buffer change. Wrong/missing device → Needs Remap, with original WIRE/FX/vendor state/H hotkeys retained. Logical/offline session may remember intent but cannot claim LIVE physical output. No recurring Monitor/ARM/Apply wizard for verified existing configurations. + +**Required synthetic native+GUI acceptance:** OUT01 active 2-output no false HW3/4; OUT02 MAIN1/2 + BUS A3/4 on verified 4-out; OUT03 MAIN1/2, BUS A3/4, BUS B5/6, BUS C7/8 on 8-out *fixture* with each plugin rendered once; OUT04 SOURCE ONLY with external audible and MAIN silent; OUT05 intentional same-pair summing without double path; OUT06 MONITOR pin collision fail-closed; OUT07 stale epoch/revision/invalid pins retain prior PCM; OUT08 device restart and `.smix` state preservation; OUT09 post-BUS FX/fader/mute/solo/pan/PDC, direct sound distinct from MAIN FX; RT01 no second callback/allocations/locks; UI01 actual assembled `/preview/` ACK/readback and no hotkey/WIRE/fader/Orbit regression. Use test signal identity, amplitude, render count and channel isolation—not just DOM text. + +**O2 physical FAT:** Independently witness actual 8-channel ASIO interface routing MAIN1/2, BUS A3/4, BUS B5/6, BUS C7/8 with captured distinct signals, 44.1/48kHz and genuinely supported buffers (e.g., 64/128/256 only if available), 0FX and real VST3, MONITOR conflict, hotplug/reopen, secondary WASAPI, no crackle/pops/xrun regression. No equipment = **PHYSICAL FAT PENDING**, never claim it passed from virtual tests or verified ZIP. + +**Primary files to inspect (not a mandate to rewrite):** `src/Main.cpp`, `src/LiveDryRoutingLab.h`, `src/LiveAudioEngine.h`, `src/NativeMixerSessionDocument.h`, `engine/core/DynamicChannelRoster.h`, `DynamicPreparedMixerBlock.h`, `DynamicNativeSessionPublisher.h`, `UnifiedLegacyProductionAdmission.h`, `engine/device/JuceActivePortSnapshot.h`, `web/mixer-io.js`, `web/monitor.js`, `web/approved-native-bridge.js`, `web/approved-native-contract.js`, and `scripts/build_approved_native_gui.py`. + +**Execution and delivery:** One significant O1 product PR (with honest source audit inside), quick checks per changes, then EXACT-SHA `/arsonmix-ci ui ` + `/arsonmix-ci fat ` via connected GitHub PR comments once meaningful candidate is ready. `fat` includes MSVC/CTest, do not schedule duplicate `native`. Agent triggers/checks Actions itself; don't ask user to press Run. Only merge after appropriate real evidence; physical FAT must be stated separately. Final reply must name current main/PR SHA, changed source files, tests, artifacts, physical output proof vs PENDING, and blockers. **Do not stop after making another architecture plan.** + +## Important boundaries +No speaker-management crossover certification, no 2/3/4-way DLMS processing, no dual-soundcard clock aggregate, no 8 fake master faders, no silently duplicated MAIN channel, no new `/preview-v2/` public GUI, no hidden Monitor gate, no accidental resurrection of M4 as second route owner. The goal is **real independent hardware output PCM** at verified pins. diff --git a/docs/architecture/README.md b/docs/architecture/README.md index c0e6c90d6..448aee53a 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -2,7 +2,7 @@ Status: CURRENT ORIENTATION (audit 2026-11-11). This document describes verified repository source and the proposed ownership model; it does NOT certify the installed Windows application or physical audio. Refresh current main/PR HEAD before changing code. -**Feature implementation:** [Hotkey Register + FL Studio External OUT execution contract](FEATURE_HOTKEY_FL_OUTPUT_EXECUTION_20261111.md) · [Hotkey/output next-thread prompt](HOTKEY_OUTPUT_NEXT_THREAD_PROMPT_20261111.md). These are research-backed implementation workpacks; neither feature is shipped until native/audio/FAT evidence proves it. +**Feature milestone status:** H1 hotkeys [MERGED #536](https://github.com/masarray/arsonmix/pull/536), H2 VST3 parameter hotkeys [MERGED #551](https://github.com/masarray/arsonmix/pull/551), exact integrated Windows native **86/86 CTest PASS**; independent physical/vendor field FAT remains pending. O1/O2 FL-style physical multi-output is **NOT IMPLEMENTED**. Use the [O-only execution handoff](MILESTONE_O_MULTIOUTPUT_NEW_THREAD_20261111.md) and [complete technical contract](FEATURE_HOTKEY_FL_OUTPUT_EXECUTION_20261111.md). **Entry points:** [Execution blueprint](MAINTAINABILITY_EXECUTION_V1_20261111.md) · [Fast feature playbook](FEATURE_EXTENSION_PLAYBOOK.md) · [Next-thread prompt](NEXT_THREAD_EXECUTION_PROMPT.md) · [Issue #527](https://github.com/masarray/arsonmix/issues/527).