Repository navigation
Lock approved ArSonMix GUI v0.8 across main, agents, and tested Pages #12
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,21 @@ | ||
| # Repository instructions — ArSonMix (all future threads and AI coding agents) | ||
|
|
||
| **MANDATORY: Read [docs/GUI_BASELINE_LOCK_2026-10-25.md](docs/GUI_BASELINE_LOCK_2026-10-25.md) before editing UI or reconciling VST3 engine PRs.** | ||
|
|
||
| ## Approved visual contract | ||
| - GUI v0.8 approved by the product owner on 2026-10-25. Original exact source commit: `343692fc9b702661a8455cca30f0ffd108907324`; merged to `main` via PR #2 (merge `aff95a7c811a3817edf61303e1f24ef31e53d11d`). | ||
| - Permanent recovery reference: `checkpoint/gui-v0.8-approved-20261025` (never update or delete it). New contributions start from latest `main`. | ||
| - Maintain a 12-input + 1 master aligned strip console; 6 visible FX slots on each; master FX, PAN and stereo L/R; one top toolbar; compact left rail; fixed MUTE label; live insert power state; no-jump fader drag; contextual, realistically shaded controls and clear selected border. | ||
| - The streaming analyzer has **only LUFS-I and dBTP**. In the browser label values as simulated; do not invent actual DSP meter readings. | ||
| - Never copy stale UI files from the native branch over the approved GUI. Native integration must adapt the engine events and visuals to this baseline **without regressing GUI or changing its design without user request**. | ||
| - Source modules: `web/index.html`, `web/styles.css`, `web/app.js`. Self-contained offline distributable: `AR-MIX-Live-FX-Host-Standalone-v0.3.html` (historical name). Keep CSS/JS/HTML byte-for-byte synchronized with the standalone. `site/` supplies landing and review shell; `scripts/build_pages.py` copies the standalone. | ||
| - No universal button CSS override; preserve the original file assets and physical sizes. Native GUI changes must preserve layout and usability at 1680x920 and 1440x820. | ||
| - Run `node --check web/app.js`, all PNG/standalone asset checks, `python tests/gui_baseline_lock_test.py`, and `python tests/ui_smoke.py` before merging a GUI PR. | ||
| - GitHub Pages production deploys **from `main` after a green main Chromium smoke**. Do not create a competing preview-branch publisher. | ||
| - Native JUCE/VST3 PRs #1 and #3–#11 were **not** validated or merged by GUI PR #2. Do not mark them done or close them until native hardware, RT safety, actual meter/bypass and plugin tests pass. Reconciliation PR #11 is built from an older GUI and must be rebased/reworked against this lock. | ||
|
|
||
| ## If you are a future ChatGPT thread | ||
| 1. Fetch live repository `main`, this file and the lock document. Cite approved commit and deployment metadata accurately. | ||
| 2. Check current native PRs / base graph before cherry-picking; do not accidentally erase more recent GUI or engine work. | ||
| 3. Propose and implement only the requested incremental changes, validate actual behavior, and capture new checkpoints if another GUI revision is approved. | ||
| 4. Distinguish *GUI-preview simulation* from *live native audio* in reports and releases. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,56 +1,61 @@ | ||
| # AR MIX Studio — Open-Source Live FX Host (v0.3 UI & Architecture) | ||
| # ArSonMix — Live Mixer & VST3 Host | ||
|
|
||
| **Status: interactive UI prototype + C++ real-time messaging primitives. No audio engine yet.** | ||
| **Project status (25 October 2026):** the premium **GUI v0.8** has been visually approved and merged into `main`. The browser preview remains a **UI prototype with simulated audio/meters**. The native Windows/JUCE/VST3 engine is progressing separately through stacked draft PRs; those builds and hardware paths are **not** certified by the GUI merge. | ||
|
|
||
| AR MIX Studio targets live vocal processing for karaoke performers and livestream creators. It is VST3-first: the principal activity is building a beautiful, low-friction FX chain with a digital-console look. The core engine is planned as C++20/JUCE with Windows ASIO/WASAPI; the frontend is a self-contained HTML/CSS/SVG UI embedded in JUCE WebView2. | ||
| > **GUI SOURCE OF TRUTH — LOCKED:** [GUI v0.8 baseline](docs/GUI_BASELINE_LOCK_2026-10-25.md) · approved commit `343692fc9b702661a8455cca30f0ffd108907324` · merged in [PR #2](https://github.com/masarray/arsonmix/pull/2) · preserved as `checkpoint/gui-v0.8-approved-20261025`. **Do not restore the previous GUI from native-engine branches.** | ||
|
|
||
| ## Public website and interactive GUI preview | ||
| ArSonMix is a Windows-first digital mixer and low-latency live VST3 host project for live vocals, karaoke and livestreaming. Its interface emphasizes fast **FX Rack / insert power**, tactile console controls, accurate channel identification and uncluttered mixing. | ||
|
|
||
| - **Landing website:** https://masarray.github.io/arsonmix/ | ||
| - **Review the actual mixer GUI:** https://masarray.github.io/arsonmix/preview/ | ||
| - **Open mixer full-screen:** https://masarray.github.io/arsonmix/preview/mixer.html | ||
| ## Open the approved mixer | ||
|
|
||
| GitHub Pages publishes the current **GUI development branch** through [the main-branch Pages workflow](.github/workflows/pages-publish.yml), after UI smoke tests pass. This preview is intentionally separate from the stable `main` code and from the native audio engine work. It is a **browser GUI prototype with simulated meters**, not a functioning VST audio host. | ||
| - **Landing:** https://masarray.github.io/arsonmix/ | ||
| - **Interactive mixer:** https://masarray.github.io/arsonmix/preview/ | ||
| - **Standalone full-screen GUI:** https://masarray.github.io/arsonmix/preview/mixer.html | ||
| - **Deployed commit:** https://masarray.github.io/arsonmix/preview/build.json | ||
|
|
||
| ## Try the current prototype now | ||
| **Pages builds the canonical standalone GUI from `main`, after the main-branch Chromium smoke test succeeds.** The last visual sign-off is GUI v0.8; a later change must preserve the accepted design or obtain another explicit review. | ||
|
|
||
| Open `AR-MIX-Live-FX-Host-Standalone-v0.3.html` in a current Chrome or Edge browser. No installation or internet access is required. The meters are intentionally **simulated**. Clicking `FX RACK` opens a chain editor: add a *demo* plugin, bypass/reorder/remove it; `MIX` offers faders, pan and MUTE/SOLO; `SIGNAL FLOW` describes the path; `SETUP` previews the driver wizard; `EASY VIEW` toggles Pro controls. Save a local FX chain preset or Mixer Snapshot, and export/import a JSON session file. | ||
| ## Approved GUI v0.8 features | ||
|
|
||
| **Important:** catalog entries are visual demo effects, not installed VST3 binaries. Nothing will process live audio or activate your mic in this version. The Windows JUCE shell is source-only and has not been compiled/validated on Windows in this environment. | ||
| - 12 color-coded input strips plus aligned stereo **MASTER strip #13**; full-height amber selected-strip highlight. | ||
| - 6 visible FX inserts per strip and master; independent compact on/off bypass for occupied inserts and separate open/edit action. | ||
| - Mirror-symmetric silver metal faders, distinct red master fader, relative no-jump pointer drag. | ||
| - Compact horizontal PAN with L/C/R values, restrained illuminated fill and noticeable center detent; master PAN included. | ||
| - Fixed hardware legend **MUTE** (red = muted); SOLO yellow, HPF green. Context-specific supplied metal button families, without global restyling. | ||
| - Stereo master L/R display with peak holds and clip latches; two streaming reference readouts only: **LUFS-I** and **dBTP**. | ||
| - Channel name/color/icon editor, quick-sound presets, mixer snapshots, explicit **SAVE SNAPSHOT / SAVE FX / EXPORT** actions. | ||
| - One application toolbar, organized left rail, and GitHub Pages preview with SHA-aware reload. | ||
|
|
||
| ## Build JUCE WebView2 shell (Windows) | ||
| **Accuracy boundary:** The browser's LUFS-I, dBTP, peak and VU values are illustrative. They are **not ITU-R BS.1770 measurements** and do not prove audio loss, clipping or real-world latency. When integrating the native engine, use authentic DSP data and never mix fake demo metering into the live audio UI. | ||
|
|
||
| Prerequisites: Visual Studio 2022 with C++, CMake >=3.22, a local compatible JUCE 8/9 source checkout, and WebView2 runtime. See licenses before distribution. | ||
| ## Working on the project / handing off to another thread | ||
|
|
||
| ```powershell | ||
| .\build_windows.ps1 -JuceRoot C:\dev\JUCE | ||
| ``` | ||
|
|
||
| CMake example: | ||
| **Start by reading [AGENTS.md](AGENTS.md) and [docs/GUI_BASELINE_LOCK_2026-10-25.md](docs/GUI_BASELINE_LOCK_2026-10-25.md).** The approved GUI is in `main`; do not use the historical GUI branch as the source for new designs. If working on native VST3, apply the engine to the new GUI contract rather than replacing `web/app.js`, `web/styles.css` or the standalone HTML with a stale copy. | ||
|
|
||
| ```powershell | ||
| cmake -S . -B build -G "Visual Studio 17 2022" -A x64 -DJUCE_ROOT="C:/dev/JUCE" | ||
| cmake --build build --config Release | ||
| ``` | ||
| The native PR chain [#1](https://github.com/masarray/arsonmix/pull/1), [#3–#10](https://github.com/masarray/arsonmix/pulls) and reconciliation PR [#11](https://github.com/masarray/arsonmix/pull/11) represent **separate in-progress engineering work**. Merge only after native build/test qualification, user hardware FAT and UI baseline parity; do not close these unfinished PRs just to tidy the issue list. | ||
|
|
||
| The shell embeds the same UI through JUCE BinaryData and uses `WebBrowserComponent::withResourceProvider`. `withEventListener("arMixParameter")` only logs events on the **JUCE message thread**. Implement the typed control dispatcher + RT backend before making it process audio. `JUCE_ASIO=1` is **not yet enabled** in this shell; check GPLv3 ASIO SDK compatibility and driver setup as specified in the ARD. | ||
| ## Local preview and tests | ||
|
|
||
| ## C++20 realtime primitives test | ||
| Open `AR-MIX-Live-FX-Host-Standalone-v0.3.html` with Chrome/Edge for an offline GUI trial. The standalone's filename is historical; its content is the **approved v0.8 GUI**. | ||
|
|
||
| ```bash | ||
| g++ -std=c++20 -O2 -Wall -Wextra -pedantic -pthread tests/realtime_control_test.cpp -o rt_tests | ||
| ./rt_tests | ||
| node --check web/app.js | ||
| python tests/button_asset_test.py | ||
| python tests/fader_asset_test.py | ||
| python tests/pan_button_asset_test.py | ||
| python tests/gui_baseline_lock_test.py | ||
| python tests/ui_smoke.py | ||
| python scripts/build_pages.py --out dist-pages --branch main | ||
| ``` | ||
|
|
||
| ## Files | ||
| The Chromium smoke test needs Playwright Chromium installed. `.github/workflows/ui-smoke.yml` runs it for pull requests and relevant `main` changes. The single `.github/workflows/pages-publish.yml` publisher runs **after successful main GUI smoke**. See [Pages runbook](docs/GITHUB_PAGES_PREVIEW.md). | ||
|
|
||
| ## Windows native host | ||
|
|
||
| `src/`, `engine/`, `CMakeLists.txt`, and `build_windows.ps1` in `main` are the original scaffold and reusable real-time primitives; evolving native versions are held in separate PR branches. Use Visual Studio 2022/CMake/JUCE and suitable ASIO/WASAPI drivers for native development. Browser-only UI acceptance is **not** proof of native VST3 load, FabFilter/RX compatibility, audio callback reliability, interop or full-fidelity plugin state. | ||
|
|
||
| - `docs/ARD_AR_MIX_LIVE_FX_HOST_v0.3.md` — full product/technical architecture, RT rules, UX flows, benchmarks, roadmap and risk register. | ||
| - `docs/UI_AUDIT_AND_QA_v0.3.md` — source UI audit, fixes and executed smoke test. | ||
| - `web/{index.html,styles.css,app.js}` — maintainable UI frontend. | ||
| - `AR-MIX-Live-FX-Host-Standalone-v0.3.html` — complete single-file offline trial. | ||
| - `src/Main.cpp`, `CMakeLists.txt`, `build_windows.ps1` — native UI host scaffold. | ||
| - `engine/core/RealtimeControl.h`, `tests/realtime_control_test.cpp` — tested sample real-time control patterns, not complete DSP. | ||
| See the historical [architecture & roadmap](docs/ARD_AR_MIX_LIVE_FX_HOST_v0.3.md) and [GUI checkpoint](docs/GUI_BASELINE_LOCK_2026-10-25.md) for current precedence. | ||
|
|
||
| ## Licensing | ||
| ## License and assets | ||
|
|
||
| Code in this trial is authored for the project and provided under AGPL-3.0-only to align with JUCE open-source licensing. JUCE, ASIO SDK and VST3 SDK have their own notices and obligations; check exact version and dependency licensing before publishing binaries. No third-party VST binaries or proprietary mixer UI graphics are included. | ||
| The repository contains project code and user-supplied visual PNG artwork. Retain notices and verify redistribution permission for every external visual asset, VST3 binary, JUCE/ASIO/VST3 SDK and third-party dependency before public binary release. The GUI milestone is **not a native product release**. |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
When this workflow is manually dispatched while the latest
mainChromium smoke is pending or failed, this checkout selects currentmainanyway: the build-job condition permits every non-workflow_runevent, and the subsequent build steps never runtests/ui_smoke.pyor verify a successful smoke result for the selected SHA. A GUI regression that passes syntax and asset checks can therefore reach production despite the new gate. Require a successful main smoke for the exact SHA on manual dispatch too, or run the Chromium smoke before deploying. This violates the production-deployment requirement inAGENTS.md.AGENTS.md reference: AGENTS.md:L14-L14
Useful? React with 👍 / 👎.