JUCE WebView Demo

A demonstration project for bidirectional communication between C++ and web-based UI using JUCE 8's WebBrowserComponent.

Overview

This project demonstrates:

• Bidirectional Communication: How to implement both C++ → web-based UI and web-based UI → C++ communication using JUCE 8's WebBrowserComponent
• VS Code Debugging: Debugging methods for both C++ and JavaScript when using Visual Studio Code

Features

• C++ ↔ JavaScript Communication
  • C++ → JavaScript: Using evaluateJavascript()
  • JavaScript → C++: Using emitEventIfBrowserIsVisible() and native function binding
  • Router Pattern: Single dispatcher function for scalable parameter handling
• VS Code Integration
  • C++ debugging with MSVC/GDB/LLDB
  • JavaScript debugging with browser DevTools
  • See DEBUGGING.md for details
• Example Application: Simple sine wave synthesizer with frequency control (20 Hz - 2000 Hz)

Architecture

┌─────────────────────────────────────┐
│  HTML/JS Frontend                   │
│  - index.html (UI Layout)           │
│  - script.js (Event Handling)       │
│  - juce/index.js (IPC Layer)        │
└──────────────┬──────────────────────┘
               │ sendParameter(id, value)
               ▼
               │ evaluateJavascript()
               ▲
┌──────────────┴──────────────────────┐
│  WebViewManager (C++)               │
│  - Handles IPC routing              │
│  - Dispatcher Pattern               │
└──────────────┬──────────────────────┘
               │ std::atomic<float>
               ▼
┌─────────────────────────────────────┐
│  AudioEngine (C++)                  │
│  - Sine Wave Synthesis              │
│  - Lock-Free Parameter Reading      │
└─────────────────────────────────────┘

Key Components

• Source/Main.cpp: Application entry point
• Source/MainComponent.h/.cpp: Main window setup and WebView integration
• Source/WebViewManager.h/.cpp: WebView management and IPC routing (dispatcher pattern)
• Source/AudioEngine.h/.cpp: Audio processing engine with atomic parameter storage
• Source/Web/: Web frontend resources
  • index.html: User interface layout
  • script.js: UI event handling
  • style.css: Styling
  • juce/index.js: JUCE interop layer (not used in this project, but provided as a convenience for withNativeFunction usage)

Requirements

Build environment follows JUCE requirements.

• CMake 3.22 or later
• JUCE 8.x (included as submodule)

Building

Clone with Submodules

git clone --recursive <repository-url>
cd juce_webview

If you've already cloned without --recursive:

git submodule update --init --recursive

Configure and Build

Windows (Visual Studio)

cmake -B build -G "Visual Studio 17 2022" -A x64
cmake --build build --config Release

macOS (Xcode)

cmake -B build -G Xcode
cmake --build build --config Release

Linux (Make)

cmake -B build -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release
cmake --build build

Run

The executable will be located in:

• Windows: build/JuceWebViewDemo_artefacts/Release/JUCE WebView Demo.exe
• macOS: build/JuceWebViewDemo_artefacts/Release/JUCE WebView Demo.app
• Linux: build/JuceWebViewDemo_artefacts/Release/JUCE WebView Demo

The Web folder is automatically copied to the appropriate location during build.

Usage

1. Launch the application
2. The WebView displays an HTML-based UI with a frequency slider
3. Adjust the slider to change the sine wave frequency (20 Hz - 2000 Hz)
4. This demonstrates the bidirectional communication between C++ and JavaScript

For debugging, see DEBUGGING.md.

Communication Protocol

JavaScript → C++ (Router Pattern)

All parameter changes use a single dispatcher function:

// In script.js
window.__JUCE__.backend.sendParameter('frequency', 440.0);

C++ Handler

// In WebViewManager.cpp
void handleParameterChange(const juce::String& paramID, float value) {
    if (paramID == "frequency")
        audioEngine.setFrequency(value);
}

This pattern scales better than creating individual native functions for each parameter.

Project Structure

juce_webview/
├── CMakeLists.txt              # Build configuration
├── AGENTS.md                   # AI agent development guidelines
├── DEBUGGING.md                # Debugging and troubleshooting guide
├── README.md                   # This file
├── .gitmodules                 # JUCE submodule reference
├── JUCE/                       # JUCE framework (submodule)
└── Source/
    ├── Main.cpp                # Application entry point
    ├── MainComponent.h/.cpp    # Main window and WebView setup
    ├── WebViewManager.h/.cpp   # WebView IPC routing
    ├── AudioEngine.h/.cpp      # Audio processing engine
    └── Web/
        ├── index.html          # UI layout
        ├── script.js           # Frontend logic
        ├── style.css           # Styling
        └── juce/
            ├── index.js        # JUCE interop layer
            └── check_native_interop.js

Development Guidelines

For AI/LLM Agents

See AGENTS.md for detailed instructions when working with AI coding assistants.

Key principles:

• Always check actual source code before modifications
• Never modify JUCE framework files
• Use minimal, targeted changes (YAGNI principle)
• All code comments and commits in English

Debugging

See DEBUGGING.md for troubleshooting common issues.