diff --git a/README.md b/README.md index 42c68da..e3187ad 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ Throw it on your master and pick your cans from a searchable library of **6033 H -> **I need help!!!!** The macOS VST3/AU build is new and not yet field-tested. Similarly, no DAWS have been tested extensively besides Reaper on any platform. Please try it in your DAW and [open an issue](https://github.com/AilaScott/Earware/issues/new), including which DAW/OS you're using. +> **I need help!!!!** The macOS build is new and not yet field-tested, and the **macOS AU is currently broken** (fix in progress). Similarly, no DAWS have been tested extensively besides Reaper on any platform. Please try it in your DAW and [open an issue](https://github.com/AilaScott/Earware/issues/new), including which DAW/OS you're using. ## For Musicians and Engineers! @@ -42,7 +42,7 @@ See the [user manual](plugins/Earware/Documentation/USER_MANUAL.md) for full usa ## For Devs -Building from source requires **CMake ≥ 3.22**, a **C++20 compiler**, and the **JUCE 8.0.12** git submodule (a vendored JSON-length fix is applied at configure time — see `patches/`). Platform tooling: WebKitGTK/GTK3/Jack/ALSA on Linux, Visual Studio 2022 + the WebView2 SDK (resolved via NuGet) on Windows, and the system WKWebView on macOS. +Building from source requires **CMake ≥ 3.22**, a **C++20 compiler**, and the **JUCE 8.0.12** git submodule (a vendored Linux WebView UTF-8 fix is applied at configure time by the root `CMakeLists.txt` via in-place source edit — reference copy in `patches/`). Platform tooling: WebKitGTK/GTK3/Jack/ALSA on Linux, Visual Studio 2022 + the WebView2 SDK (resolved via NuGet) on Windows, and the system WKWebView on macOS. ```bash git clone https://github.com/AilaScott/Earware.git diff --git a/docs/BUILD_AND_CI_REFERENCE.md b/docs/BUILD_AND_CI_REFERENCE.md index b9268e7..6d00f6e 100644 --- a/docs/BUILD_AND_CI_REFERENCE.md +++ b/docs/BUILD_AND_CI_REFERENCE.md @@ -4,12 +4,13 @@ Authoring notes for the coding agent. Captures the repo layout, DSP architecture ## Repo (AilaScott/Earware, Linux-first) -- `CMakeLists.txt` — root build: platform flags, WebView backend per platform, JUCE submodule, applies the Linux WebView fix, adds the plugin. +- `CMakeLists.txt` — root build: project version 0.4.1, platform flags, WebView backend per platform, JUCE submodule, applies the Linux WebView fix, adds the plugin. - `plugins/Earware/CMakeLists.txt` — `juce_add_plugin`; per-platform formats; `earware_rendertest` (headless DSP test suite). - `plugins/Earware/Source/` — `PluginProcessor` / `PluginEditor` / `ParametricEQData` / `LinearPhaseFIR` (+ `ui/public` WebView assets embedded via `juce_add_binary_data`). +- `plugins/Earware/generate_data.py` — regenerates `Source/ParametricEQData.{h,cpp}` from AutoEq's recommended results (`_tools/AutoEq/results/README.md`). `_tools/AutoEq` is **not** a submodule and is not in the tree, so regeneration currently requires cloning AutoEq locally first. - `_tools/JUCE` — git submodule, official `juce-framework/JUCE` pinned to 8.0.12 (commit `29396c22c9`). - `.github/workflows/build-release.yml` — release + workflow_dispatch CI (Linux/Windows/macOS). -- `patches/juce-8.0.12-commandreceiver-utf8.patch` — the Linux WebView fix, applied at configure time. +- `patches/juce-8.0.12-commandreceiver-utf8.patch` — reference copy of the Linux WebView fix. It is **not** applied as a patch: root `CMakeLists.txt:60-96` performs the same edit in-place via `string(REPLACE ...)` + `file(WRITE ...)` and fails configure if the stock JUCE line isn't found. - `docs/BUILD_AND_CI_REFERENCE.md` — this file. ## DSP Architecture @@ -79,8 +80,11 @@ Test models: 0 (flat), 1, 226 (AKG K240 Studio), 630 (Audio-Technica ATH-M30). ## UI / WebView -- Model dropdown search strips non-alphanumeric characters (`/[^a-z0-9]/g`) from both query and model names before matching, so "HD650" finds "Sennheiser-HD-650". -- Model list: 6,034 entries (index 0 = "No Model Selected" neutral preset). +- Model dropdown search strips non-alphanumeric characters (`/[^a-z0-9]/g`) from both query and model names before matching, then falls back to substring matching — so "HD650" finds "Sennheiser HD 650". +- Model list: 6,034 entries (index 0 = "No Model Selected" neutral preset). The dropdown renders at most 200 entries at a time (`MAX_ITEMS = 200` in `ui/public/js/index.js`); typing narrows the list. +- **Model list delivery (issue #6):** two paths. Primary — `withInitialisationData("models", …)` ×6034 in `PluginEditor.cpp`, injected as user-script JS at document start. Fallback — `js/index.js` `loadModelList()` fetches **`models.json`** from the resource provider (`getResource()` builds it from `earwareModelNames`) when the injected array is absent/empty. After load it sets `window.__EARWARE_DIAG__` (`{models, source}`) and re-emits `earwareReady` so the C++ timer re-pushes the current model. +- **Local JUCE JS modification:** `ui/public/js/juce/check_native_interop.js` normally untouched, but when `window.__JUCE__` is undefined (host user script never ran) it now rebuilds a working `postMessage` from `window.webkit.messageHandlers.__JUCE__` / `window.chrome.webview` instead of installing a no-op. It only activates when the injected script is absent, so healthy platforms are unaffected. +- **UI probe:** ~1.5 s after page load the editor evaluates a JS probe (`runDiagnosticsProbe()` in `PluginEditor.cpp`) via `evaluateJavascript` (works even when the message-handler bridge is dead), logs `Earware UI probe: {…}` through `juce::Logger`, and writes "Model list failed to load" into the status bar if the page-side list never arrived. JS also logs `Earware: model list loaded (N, source)`. - Curve drawn on canvas: 256 log-spaced points, x-axis log-frequency (20 Hz–20 kHz), y-axis linear dB (±12 dB range, 0 dB at vertical center). - Data flows via `evaluateJavascript` from a 30 Hz editor timer; JS signals readiness via `earwareReady` event. @@ -108,14 +112,14 @@ Triggers: `release: published` or `workflow_dispatch` (with optional `tag` input | Windows | windows-2022 | VST3 | WebView2 SDK via NuGet, MSVC | | macOS | macos-14 | VST3 + AU | Universal (arm64;x86_64), deployment target 10.13, ad-hoc codesign | -Artifacts: `Earware_Linux_x64_VST3.zip`, `Earware_Windows_x64_VST3.zip`, `Earware_macOS_Universal_VST3.zip`, `Earware_macOS_Universal_AU.zip`. Uploads to release when tag is available. +Workflow artifacts (`actions/upload-artifact`): `Earware_Linux_x64_VST3`, `Earware_Windows_x64_VST3`, `Earware_macOS_Universal` (one combined VST3+AU artifact; artifact names have no `.zip` suffix). Release assets (the zips staged outside `dist/`): `Earware_Linux_x64_VST3.zip`, `Earware_Windows_x64_VST3.zip`, `Earware_macOS_Universal_VST3.zip`, `Earware_macOS_Universal_AU.zip`. Release upload runs only when a tag is available. ## JUCE facts - `assignImpl` (IIR Coefficients): removes a0 from 6-element input, divides all others by a0 → `getRawCoefficients()` returns 5 values `{b0/a0, b1/a0, b2/a0, a1/a0, a2/a0}`. - JUCE TDF-II processing: `output = input·b0 + lv1; lv1 = input·b1 - output·a1 + lv2; lv2 = input·b2 - output·a2`. - `minimumDecibels = -300.0` (not -100). -- Linux WebView: `CommandReceiver::sendCommand` must write UTF-8 byte count (patched via `patches/`). +- Linux WebView: `CommandReceiver::sendCommand` must write UTF-8 byte count (fixed by the root CMakeLists in-place edit; `patches/` holds the reference diff). - Windows WebView: `withBackend(webview2)` + `withWinWebView2Options` honored only on Windows; Linux/macOS use default backend (WebKit/WKWebView) — platform code ignores the enum. - macOS: WKWebView always; `WebKit.framework` auto-linked via `juce_gui_extra`. - JUCE 8 minimum macOS deployment target ≈ 10.13. @@ -131,6 +135,9 @@ Artifacts: `Earware_Linux_x64_VST3.zip`, `Earware_Windows_x64_VST3.zip`, `Earwar ## Open items - macOS GUI runtime unverified — flag before calling macOS done. +- macOS AU is currently broken (issue #6 — empty model list). Mitigation shipped (models.json fallback + transport fallback + UI probe) but **not yet verified on macOS** — do not claim AU works until someone confirms it. +- Root cause of #6 still unknown: model-data content is proven valid (Linux executes the identical injected blob), so a macOS-specific user-script injection failure is the leading hypothesis; the probe's `initModels`/`transport` fields discriminate the cases once a macOS log exists. +- `_tools/AutoEq` is not vendored/submoduled — `generate_data.py` cannot regenerate `ParametricEQData.{h,cpp}` from a fresh clone without a local AutoEq checkout. - Ad-hoc codesign included; notarization needs a Developer ID (out of scope). - `AilaScott/JUCE` is **private** — do NOT point submodule at it; keep official JUCE + deterministic patch. - `status.json` retains historical LV2 mentions; LV2 and Standalone are removed from build. diff --git a/plugins/Earware/Documentation/USER_MANUAL.md b/plugins/Earware/Documentation/USER_MANUAL.md index 317e93e..593e230 100644 --- a/plugins/Earware/Documentation/USER_MANUAL.md +++ b/plugins/Earware/Documentation/USER_MANUAL.md @@ -10,7 +10,7 @@ Earware is a preset-based corrective EQ plugin that applies [AutoEq](https://git ## Quick Start 1. Open Earware in your DAW. -2. Click the dropdown at the top to search for your headphone model (6033 models available across over-ear, in-ear, and earbud categories, 6034 entries including "No Model Selected"). No correction is applied until you pick a model — you can always reset to "No Model Selected" from the list. +2. Click the dropdown at the top to search for your headphone model (6033 models from AutoEq's recommended results — including over-ear, in-ear and earbud models — 6034 entries including "No Model Selected"). No correction is applied until you pick a model — you can always reset to "No Model Selected" from the list. The dropdown shows at most **200 entries at a time**, so type a few characters to narrow it down. 3. Toggle **Bypass** to compare corrected vs. uncorrected audio. 4. The EQ curve is displayed on the canvas — the black line shows the correction applied. @@ -18,7 +18,7 @@ Earware is a preset-based corrective EQ plugin that applies [AutoEq](https://git | Control | Description | |---------|-------------| -| Model dropdown | Custom searchable dropdown (6033 models from AutoEq's recommended results + "No Model Selected" neutral default, 6034 entries total). Click to see the full list, type to filter (hyphens and spaces are ignored), keyboard ↑/↓/Enter/Esc supported | +| Model dropdown | Custom searchable dropdown (6033 models from AutoEq's recommended results + "No Model Selected" neutral default, 6034 entries total). Click to open the list — up to 200 entries are shown at once, so type to filter. Matching ignores non-alphanumeric characters on both sides and falls back to substring search, so "HD650" finds "Sennheiser HD 650". Keyboard ↑/↓/Enter/Esc supported | | Bypass | Toggle corrective EQ on/off | ## How It Works diff --git a/plugins/Earware/Documentation/WINDOWS_BUILD_AGENT.md b/plugins/Earware/Documentation/WINDOWS_BUILD_AGENT.md index 1181ce5..d981133 100644 --- a/plugins/Earware/Documentation/WINDOWS_BUILD_AGENT.md +++ b/plugins/Earware/Documentation/WINDOWS_BUILD_AGENT.md @@ -14,35 +14,31 @@ SCOPE: - If you must change plugin source to get the build to compile, keep the change minimal and explain it. SOURCE OF TRUTH: -Read plugins/Earware/Documentation/WINDOWS_BUILD.md in this repo first and follow it. +Read plugins/Earware/Documentation/WINDOWS_BUILD.md first and follow it exactly. +It holds the prerequisites, WebView2 SDK / NuGet setup, exact CMake commands, and the +artifact path. This file intentionally does NOT duplicate those details (versions, +commands, paths) so the two documents cannot drift — take them from WINDOWS_BUILD.md, +not from memory. STEPS: -1. Verify prerequisites: VS2022 with the "Desktop development with C++" workload, CMake 3.22+, Git. +1. Read WINDOWS_BUILD.md and follow its prerequisites, WebView2 setup, and build commands. 2. Ensure submodules are present: git submodule update --init --recursive - NOTE: _tools/JUCE points at the public repo https://github.com/juce-framework/JUCE.git + _tools/JUCE points at the public repo https://github.com/juce-framework/JUCE.git (pinned to the 8.0.12 release commit) — no GitHub authentication needed. -3. Confirm the known change is already applied (it is, in this repo): - a) plugins/Earware/CMakeLists.txt: the earware_rendertest target (it sets JUCE_JACK=1, - line ~159) is already wrapped so it only builds on Linux (UNIX AND NOT APPLE). - JACK does not compile on MSVC. +3. Confirm the known change is already present (it is, in this repo): + plugins/Earware/CMakeLists.txt wraps the earware_rendertest target (JUCE_JACK=1) + in if(UNIX AND NOT APPLE), since JACK does not compile on MSVC. If this change is missing, apply it and note that. -4. Ensure the WebView2 SDK is available. Configure hard-fails without it - (find_package(WebView2 REQUIRED) in JUCEUtils.cmake). If missing, install it with: - Register-PackageSource -provider NuGet -name nugetRepository -location https://www.nuget.org/api/v2 - Install-Package Microsoft.Web.WebView2 -Scope CurrentUser -RequiredVersion 1.0.3485.44 -Source nugetRepository - or: nuget install Microsoft.Web.WebView2 -Version 1.0.3485.44 - and pass -DJUCE_WEBVIEW2_PACKAGE_LOCATION= at configure time. -5. Configure and build: - cmake -S . -B build -G "Visual Studio 17 2022" -A x64 -DCMAKE_BUILD_TYPE=Release - cmake --build build --config Release --target Earware_VST3 -6. VERIFY: report the absolute path of the produced artifact - (build/plugins/Earware/Earware_artefacts/Release/VST3/Earware.vst3). +4. If configure fails on find_package(WebView2 REQUIRED), run the NuGet install + commands given in WINDOWS_BUILD.md. +5. Build the Earware_VST3 target, then VERIFY: report the absolute path of the + produced .vst3 artifact (layout given in WINDOWS_BUILD.md). If a step fails, paste the full error output and stop rather than guessing at workarounds. REPORT BACK (concise): - The exact commands you ran. -- Change a): already present, or applied by you. +- rendertest guard: already present, or applied by you. - Build result (pass/fail) and the artifact path. - Any warnings or deviations from WINDOWS_BUILD.md. ````