GuitarEngine 3.0

A real-time VST3 guitar multi-effects host, built to run fullscreen on a custom hardware unit but usable on any Windows machine with an ASIO audio interface. It provides gapless bank switching, node-based signal routing, VST3 hosting, a master EQ, per-preset variations, and a touch-first UI.

• Engine: C++20, JUCE 8, Tracktion Engine, nlohmann::json
• UI: React + a typed TypeScript IPC bridge, React Flow, Vite, hosted in a JUCE WebView2 component
• Platform: Windows only (WebView2 and ASIO)

For how the engine is built internally and why, see ARCHITECTURE.md. For third-party licenses, see CREDITS.md.

---

Requirements

You build JUCE and Tracktion Engine from source (both are vendored into this repo under external/), so this is a full C++ toolchain setup, not a one-click install.

• Windows 10/11 (64-bit).
• Visual Studio 2022 or newer with the "Desktop development with C++" workload. The exporter here targets VS2026; you can retarget it to your VS version in Projucer.
• The Projucer app (ships with any JUCE download). Used once to generate the Visual Studio project from GuitarEngine3.0.jucer.
• Steinberg ASIO SDK. JUCE_ASIO is enabled, so the build needs the ASIO SDK headers. They cannot be redistributed, so they are not in this repo; you add them once by hand (step 1 below).
• Node.js 18+ and npm, to build the UI bundle.
• Microsoft Edge WebView2 Runtime on the machine that runs the app (usually already present on Windows 11).
• An ASIO-capable audio interface and its driver.

JUCE, Tracktion Engine, and the VST3 SDK are already included under external/, so you do not download those separately.

---

Repository layout

Source/                        C++ engine (JUCE / Tracktion). Header-only components.
UI/                            React UI (Vite). Built into UI/dist and embedded in the app.
Teensy Code/                   Firmware for the optional footswitch + LED controller.
external/JUCE/                 Bundled JUCE (its own LICENSE.md kept inside).
external/tracktion_engine/     Bundled Tracktion Engine (its own LICENSE.md kept inside).
GuitarEngine3.0.jucer          Projucer project (generates the Visual Studio build).
ARCHITECTURE.md                Design and rationale reference.
CREDITS.md                     Third-party components and licenses.
LICENSE                        GPLv3.

Builds/ and JuceLibraryCode/ (Projucer output) and UI/node_modules/ and UI/dist/ (npm and Vite output) are generated locally and are not committed.

---

Setup and build

Do the steps in order. The UI is built first because the C++ build embeds it.

1. Add the ASIO SDK

The Steinberg ASIO SDK cannot be redistributed, so the bundled JUCE ships without it. Download the ASIO SDK from Steinberg and copy its headers into JUCE, where JUCE expects them:

external/JUCE/modules/juce_audio_devices/native/asio/
    asio.h
    asiosys.h
    iasiodrv.h

This is a one-time step per checkout. If the C++ build later fails with a missing iasiodrv.h or asio.h, this is the cause. (Alternatively, add the ASIO SDK folder to the exporter's header search paths in Projucer.)

2. Build the UI

The UI compiles to a static bundle that gets embedded into the app.

cd UI
npm install
npm run build

This produces UI/dist/, which the Projucer project references. Any time you change the UI later, rebuild it (npm run build) and re-save the .jucer (step 3) before the C++ build will pick up the change.

3. Generate the Visual Studio project

Open GuitarEngine3.0.jucer in Projucer. Confirm the exporter's module paths point at the bundled copies:

• JUCE modules: external/JUCE/modules
• tracktion_engine and tracktion_graph: external/tracktion_engine/modules

Then save the project (File > Save). Saving regenerates Builds/ and JuceLibraryCode/, and embeds the current UI/dist/ bundle into JuceLibraryCode/BinaryData.

4. Build the app

Open the generated solution in Visual Studio and build Release / x64, or from a terminal:

MSBuild.exe Builds\VisualStudio2026\GuitarEngine3.vcxproj /p:Configuration=Release /p:Platform=x64 /m

The project depends on the Microsoft.Web.WebView2 NuGet package (Projucer adds the reference when it regenerates the build, because WebView2 is enabled). Visual Studio restores NuGet packages automatically on the first build. If you build from the command line and it fails on a missing WebView2 header or loader, run a restore first (msbuild -t:restore Builds\VisualStudio2026\GuitarEngine3.vcxproj, or open and build once in Visual Studio).

The executable lands at:

Builds\VisualStudio2026\x64\Release\App\GuitarEngine.exe

It is statically linked, so deploying to another machine is a single-file copy (that machine still needs the WebView2 Runtime and an ASIO driver). Kill any running GuitarEngine.exe before rebuilding, or the linker fails on the locked file.

---

Configuring your audio interface (ASIO)

This is the one code change most people need. Out of the box the app looks for a PreSonus AudioBox by name (the development interface). To use your own interface, change the device match in Source/DeviceSetup.h, in the function ge::initialiseAudioDevice.

Find this block:

asioType->scanForDevices();
for (const auto& name : asioType->getDeviceNames()) {
    if (name.containsIgnoreCase("AudioBox") || name.containsIgnoreCase("Audio Box") || name.containsIgnoreCase("PreSonus")) {
        juce::AudioDeviceManager::AudioDeviceSetup setup;
        ...
        setup.sampleRate = 48000;
        ...
        setup.bufferSize = 256;   // opened at 256 to flush the driver...
        ...
        setup.bufferSize = 128;   // ...then dropped to the real buffer
        ...
    }
}

1. Find your device's ASIO name as shown in its ASIO control panel or in any DAW's device list. Only a distinctive piece of it is needed.

2. Change the if condition to match that name. For example:

   // Focusrite Scarlett
   if (name.containsIgnoreCase("Focusrite")) {
   
   // RME
   if (name.containsIgnoreCase("ASIO Fireface")) {
   
   // A generic driver such as ASIO4ALL
   if (name.containsIgnoreCase("ASIO4ALL")) {

3. Optionally set the sample rate and buffer size. setup.sampleRate defaults to 48000. setup.bufferSize opens at 256 to flush the driver and is then set to 128; change both if you want a different buffer.

4. Rebuild (build step 4).

If no device matches, the log shows [ASIO] WARNING: no ASIO device type available (or simply finds no output) and the app starts with no audio. Check the ASIO name against what your driver reports.

---

Where the app looks for plugins

On a scan the app searches the standard Windows VST3 folders:

• C:\Program Files\Common Files\VST3
• %LOCALAPPDATA%\Programs\Common\VST3

Those come from JUCE's default VST3 locations. To scan a different or additional folder, change the search path in Source/PluginScanner.h, in forceScanNewPlugins:

juce::AudioPluginFormat* format = formatManager.getFormat(0);
juce::FileSearchPath paths = format->getDefaultLocationsToSearch();
juce::PluginDirectoryScanner scanner(pluginList, *format, paths, true, juce::File());

• To add a folder on top of the defaults:

  juce::FileSearchPath paths = format->getDefaultLocationsToSearch();
  paths.add(juce::File("D:\\YourPlugins\\VST3"));

• To scan only your own folder instead of the defaults:

  juce::FileSearchPath paths;
  paths.add(juce::File("D:\\YourPlugins\\VST3"));

Rebuild, then run a scan (below). Only VST3 is supported (JUCE_PLUGINHOST_VST3); VST2 is off.

---

First run

• On first launch, open the settings and run Scan VSTs to populate the plugin picker (this reads the folders above and caches the result).
• Runtime data (setlists, saved banks, the plugin cache, logs) is written to C:\GuitarEngineData\. The primary log is C:\GuitarEngineData\Logs\Engine_Log.txt; check it first if something misbehaves.

---

Optional: hardware footswitches

The Teensy Code/ folder holds the firmware for the physical footswitch and LED controller (a Teensy over USB MIDI). It is entirely optional; the app is fully usable with the touchscreen or mouse. The MIDI contract (footswitch CCs and LED colour codes) is documented in ARCHITECTURE.md section 12.

---

License

The software is released under the GNU General Public License v3 (see LICENSE), which satisfies the VST3 open-source licensing terms. Bundled JUCE and Tracktion Engine are used under their GPLv3 option and keep their own license files under external/. Third-party components are listed in CREDITS.md. The custom hardware design is a separate project and is not covered by this license.