WebView UI Authoring

Guidance for building WebView-based UIs in iPlug2 plugins. Covers integration mode selection, C++/JS messaging, web framework setup, resource loading, hot reloading, and audio-to-UI visualization.

Core Pattern

Every full-WebView plugin sets up its editor in the constructor via mEditorInitFunc:

// In plugin constructor
#ifdef DEBUG
  SetEnableDevTools(true);
#endif
  SetCustomUrlScheme("iplug2"); // optional, needed for some frameworks

  mEditorInitFunc = [&]() {
    LoadIndexHtml(__FILE__, GetBundleID());
    // OR for hot-reload development:
    // LoadURL("http://localhost:5173/");
    EnableScroll(false);
  };

The plugin class inherits from Plugin. The build configuration must define WEBVIEW_EDITOR_DELEGATE and NO_IGRAPHICS so the delegate selection header (IPlugDelegate_select.h) routes to WebViewEditorDelegate.

On the web side, provide resources/web/index.html as the entry point. The C++ side automatically injects IPlugSendMsg() as the JS-to-native bridge function.

Reference examples: Examples/IPlugWebUI/ (minimal), Examples/IPlugSvelteUI/ (modern framework), Examples/IPlugP5js/ (creative coding).

Choosing an Integration Mode

Choosing a Web Framework

For detailed framework setup and hot reloading, consult references/framework-selection.md.

JavaScript Bridge Functions

JS to C++ (send via IPlugSendMsg(jsonObj)):

C++ to JS (called automatically via EvaluateJavaScript):

For the complete messaging protocol, JSON schemas, and binary data exchange, consult references/messaging-protocol.md.

Parameter Handling from JavaScript

Parameters require a three-step gesture protocol for proper DAW undo/automation:

// 1. Begin gesture (e.g. on mousedown)
BPCFUI(paramIdx);

// 2. Send values during drag (normalized 0-1)
SPVFUI(paramIdx, normalizedValue);

// 3. End gesture (e.g. on mouseup)
EPCFUI(paramIdx);

On page load, WebViewEditorDelegate automatically sends all parameter info as a JSON blob via SAMFD with msgTag == -1. Decode it in your SAMFD handler:

function SAMFD(msgTag, dataSize, msg) {
  if (msgTag == -1 && dataSize > 0) {
    let json = JSON.parse(atob(msg));
    if (json.id === "params") {
      // json.params is an array of {name, type, min, max, default, ...}
      // Use this to configure your UI controls
    }
  }
}

Parameter changes from the C++ side arrive via SPVFD(paramIdx, normalizedValue). Define this function globally to handle them.

Audio-to-UI Data (ISender to WebView)

The C++ side is identical to IGraphics -- declare a sender, feed it in ProcessBlock, transmit in OnIdle:

// .h
IPeakSender<2> mSender;
enum EControlTags { kCtrlTagMeter = 0 };

// ProcessBlock
mSender.ProcessBlock(outputs, nFrames, kCtrlTagMeter);

// OnIdle
mSender.TransmitData(*this);

Data arrives in JavaScript via SCMFD. Decode the base64 payload to typed arrays:

globalThis.SCMFD = (ctrlTag, msgTag, dataSize, msg) => {
  const bytes = new Uint8Array(atob(msg).split('').map(c => c.charCodeAt(0)));
  const header = new Int32Array(bytes.buffer, 0, 3); // [controlTag, nChans, chanOffset]
  const data = new Float32Array(bytes.buffer, 12);   // audio data
  // data[0] = channel 0 peak, data[1] = channel 1 peak, etc.
};

For detailed visualization patterns, consult references/isender-and-visualization.md.

Embedded WebView in IGraphics

Use IWebViewControl to embed a WebView panel within an IGraphics UI:

#include "IWebViewControl.h"

// In mLayoutFunc:
pGraphics->AttachControl(new IWebViewControl(bounds, true,
  [](IWebViewControl* pControl) {            // onReady
    pControl->LoadFile("index.html", "com.yourcompany.yourplugin");
  },
  [](IWebViewControl* pControl, const char* jsonMsg) {  // onMessage
    DBGMSG("Received: %s\n", jsonMsg);
  },
  enableDevTools), kCtrlTagWebView);

The WebView renders as a native overlay on top of IGraphics. Messages from JS arrive at the onMessage lambda as raw JSON -- no automatic parameter routing. Use pControl->EvaluateJavaScript("...") to call JS from C++.

Custom URL Schemes and DevTools

Custom URL scheme: SetCustomUrlScheme("iplug2") serves web content as if from an iplug2:// origin. Required when frameworks generate absolute path imports. Set before the WebView opens.

DevTools: SetEnableDevTools(true) enables the browser inspector (right-click context menu on macOS, F12 on Windows). Typically wrap in #ifdef DEBUG.

Key Source Files