From 3025589fbb4d64da4d8cc3eb3e594a7f802677b0 Mon Sep 17 00:00:00 2001 From: AilaScott Date: Sat, 10 Oct 2026 14:58:26 -0400 Subject: [PATCH] Docs: static-CRT note, system-wide AU path, user-facing troubleshooting --- README.md | 4 +++- plugins/Earware/Documentation/USER_MANUAL.md | 10 +++++++++- plugins/Earware/Documentation/WINDOWS_BUILD.md | 6 ++++-- plugins/Earware/Documentation/WINDOWS_BUILD_AGENT.md | 9 ++++++--- 4 files changed, 22 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index e3187ad..d53c273 100644 --- a/README.md +++ b/README.md @@ -36,7 +36,9 @@ Download the build for your platform from the [Releases](https://github.com/Aila To install, unzip and copy the plugin folder into your audio plugin directory: - **VST3** — `~/.vst3/` (Linux), `C:\Program Files\Common Files\VST3\` (Windows), `~/Library/Audio/Plug-Ins/VST3/` (macOS) -- **AU (macOS)** — `~/Library/Audio/Plug-Ins/Components/` +- **AU (macOS)** — `/Library/Audio/Plug-Ins/Components/` + +Copy the whole `Earware.vst3` folder (not just the file inside it). If the plugin does not appear in your DAW afterwards, rescan your plugin list and restart the DAW. Windows builds need no additional runtime: the MSVC runtime is linked statically, so no VC++ Redistributable install is required. See the [user manual](plugins/Earware/Documentation/USER_MANUAL.md) for full usage. diff --git a/plugins/Earware/Documentation/USER_MANUAL.md b/plugins/Earware/Documentation/USER_MANUAL.md index 593e230..cb8347d 100644 --- a/plugins/Earware/Documentation/USER_MANUAL.md +++ b/plugins/Earware/Documentation/USER_MANUAL.md @@ -4,9 +4,11 @@ Earware is a preset-based corrective EQ plugin that applies [AutoEq](https://git ## Installation -- **VST3:** Copy `Earware.vst3` to your VST3 directory (`~/.vst3/` on Linux, `%COMMONPROGRAMFILES%\VST3\` on Windows). +- **VST3:** Copy the whole `Earware.vst3` folder to your VST3 directory (`~/.vst3/` on Linux, `%COMMONPROGRAMFILES%\VST3\` on Windows, `~/Library/Audio/Plug-Ins/VST3/` on macOS). - **AU (macOS):** Copy `Earware.component` to `/Library/Audio/Plug-Ins/Components/`. +Windows builds need no additional runtime — no VC++ Redistributable install is required. + ## Quick Start 1. Open Earware in your DAW. @@ -36,6 +38,12 @@ Linear phase means the correction adds **no phase distortion**, but it introduce - VST3 (Linux, Windows, macOS) - AU (macOS) +## Troubleshooting + +- **The plugin does not appear in my DAW** — Make sure you copied the whole `Earware.vst3` folder (on Windows, the folder contains `Contents/x86_64-win/Earware.vst3`). Then rescan your plugin list in the DAW's preferences and restart the DAW if needed. +- **"The effect plug-in could not be loaded"** — Close the DAW completely and reopen it, then rescan your plugin list. A stale plugin cache can list the plugin even when it fails to load. +- **"Model list failed to load" in the status bar** — The headphone list did not reach the plugin UI. This is a known issue on the macOS AU build. Please [open an issue](https://github.com/AilaScott/Earware/issues/new) with your OS and DAW. + ## Resources - AutoEq recommended results: https://github.com/jaakkopasanen/AutoEq/blob/master/results/README.md diff --git a/plugins/Earware/Documentation/WINDOWS_BUILD.md b/plugins/Earware/Documentation/WINDOWS_BUILD.md index c4b9383..2484a15 100644 --- a/plugins/Earware/Documentation/WINDOWS_BUILD.md +++ b/plugins/Earware/Documentation/WINDOWS_BUILD.md @@ -5,7 +5,8 @@ Target: Windows 10/11 x64, builds **VST3**, toolchain **MSVC** (Visual Studio 20 ## What already works out of the box - `plugins/Earware/CMakeLists.txt:10-12` already selects the `VST3` format and sets `NEEDS_WEBVIEW2 TRUE` when `WIN32`. -- The top-level `CMakeLists.txt:27-31` already defines `JUCE_USE_WIN_WEBVIEW2=1` on Windows. +- The top-level `CMakeLists.txt` already defines `JUCE_USE_WIN_WEBVIEW2=1` on Windows. +- The top-level `CMakeLists.txt` also sets `CMAKE_MSVC_RUNTIME_LIBRARY=MultiThreaded` for MSVC, so Windows builds link the MSVC runtime statically and do **not** require the VC++ Redistributable on the target machine (matches CI). - The VST3 SDK is vendored inside JUCE 8 — no separate VST3 SDK download is needed. - The DSP code is portable (no platform `#ifdef`s). The editor has one Windows-only block (`PluginEditor.cpp:39`, `#if JUCE_WINDOWS`) for the WebView2 backend and temp user-data folder. @@ -68,12 +69,13 @@ Add `-DJUCE_WEBVIEW2_PACKAGE_LOCATION=...` to the configure line when using Opti ## Install and test -- Copy the `Earware.vst3` folder to `C:\Program Files\Common Files\VST3\` and rescan your DAW. +- Copy the whole `Earware.vst3` folder to a VST3 directory and rescan your DAW. Standard choice: `C:\Program Files\Common Files\VST3\`. Note that writing under `C:\Program Files` requires admin rights (a UAC prompt). A per-DAW folder also works — for REAPER, `C:\Program Files\REAPER (x64)\Plugins\` is on the default scan path (`vstpath64` in `reaper.ini`) and needs the same admin rights. - WebView2 runtime: the Evergreen runtime ships preinstalled on Windows 10/11. `JUCE_USE_WIN_WEBVIEW2_WITH_STATIC_LINKING=1` (set in `plugins/Earware/CMakeLists.txt`) only removes the loader dependency, not the runtime — offline or older systems need the runtime installed separately. ## Troubleshooting - **`WebView2 wasn't found` / configure error from `find_package(WebView2 REQUIRED)`**: install via Option A above, or point `-DJUCE_WEBVIEW2_PACKAGE_LOCATION` at an extracted package (Option B). +- **DAW says the plugin could not be loaded**: confirm you copied the whole `Earware.vst3` folder (not the inner `Contents/x86_64-win/Earware.vst3` file). Then close the DAW completely and reopen it so its plugin cache is rebuilt, and rescan. - **`JUCE_JACK` compile errors**: confirm the `earware_rendertest` block is guarded by `if(UNIX AND NOT APPLE)` (change #1). - **`git submodule update` fails on `_tools/JUCE`**: network or GitHub access issue — the submodule is public, no authentication needed. - **Prefer MSVC.** MinGW-w64 is not recommended for this plugin: JUCE's WebView2 code includes MSVC-only headers (`wrl.h`, `wrl/wrappers/corewrappers.h`), which MinGW-w64 does not ship. diff --git a/plugins/Earware/Documentation/WINDOWS_BUILD_AGENT.md b/plugins/Earware/Documentation/WINDOWS_BUILD_AGENT.md index d981133..7682505 100644 --- a/plugins/Earware/Documentation/WINDOWS_BUILD_AGENT.md +++ b/plugins/Earware/Documentation/WINDOWS_BUILD_AGENT.md @@ -26,10 +26,13 @@ STEPS: git submodule update --init --recursive _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 present (it is, in this repo): +3. Confirm the known changes are already present (they are, 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. + The root CMakeLists.txt also sets a static MSVC runtime + (CMAKE_MSVC_RUNTIME_LIBRARY=MultiThreaded) so the build needs no VC++ + Redistributable — do not revert it to the dynamic runtime. + If either change is missing, apply it and note that. 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 @@ -38,7 +41,7 @@ STEPS: REPORT BACK (concise): - The exact commands you ran. -- rendertest guard: already present, or applied by you. +- rendertest guard and static MSVC runtime: already present, or applied by you. - Build result (pass/fail) and the artifact path. - Any warnings or deviations from WINDOWS_BUILD.md. ```` -- 2.54.0