English | 中文

foo_ui_webview2

Documentation: https://nereafantasia.github.io/foo_ui_webview2/

A modern UI component for foobar2000 built on WebView2 (C++ DLL). It turns the entire foobar2000 window into a WebView2 canvas, letting you build the interface with modern web technologies while keeping native Windows 11 visual effects (Mica/Acrylic).

• Version: 1.9.0
• License: GPL-3.0-or-later (main component) / MIT (sdk/)

Features

• Full WebView2 UI — the entire client area is rendered by WebView2
• Native Windows 11 effects — Mica / Acrylic / Tabbed backgrounds
• Extended title bar into the client area — custom title bar content, Snap Layout support
• Bidirectional C++ / JS bridge (BridgeCore)
• 200+ APIs across 20+ namespaces
• Plugin extension system (PluginRegistry)
• Web Components library (fb-* elements)
• SMP compatibility layer
• MCP Server — AI agent integration via CDP
• DUI / CUI panel support

Tech Stack

npm Packages

The two JavaScript packages below are published to npm and can be installed directly (no source build required):

Project Structure

foo_ui_webview2/
├── src/                    # C++ source code
│   ├── core/               # WebView core, UserInterface, etc.
│   ├── window/             # MainWindow, PopupWindow, WindowManager
│   ├── webview/            # WebView host and environment
│   ├── api/                # BridgeCore + API handlers
│   ├── callbacks/          # foobar2000 SDK event callbacks
│   ├── panels/             # DUI/CUI panel integration
│   ├── selection/          # Selection tracking
│   ├── interfaces/         # Service abstractions
│   └── utils/              # Utility functions
├── sdk/                    # TypeScript SDK (foo-webview-sdk)
│   ├── src/                # Source (bridge/, components/, smp/, types/)
│   └── package.json
├── mcp/                    # MCP Server (AI agent CDP bridge)
│   ├── src/                # TypeScript source
│   └── tests/              # Unit + E2E tests
├── tests/                  # C++ unit tests (GoogleTest)
├── docs/vitepress/         # User documentation site
├── lib/                    # Third-party libraries
│   ├── foobar2000_sdk/     # foobar2000 SDK (BSD)
│   ├── columns_ui-sdk/     # Columns UI SDK (submodule)
│   └── json/               # nlohmann/json (MIT)
├── build.ps1               # Standard build script
├── build-package.ps1       # .fb2k-component packaging
├── foo_ui_webview2.sln     # VS solution
├── foo_ui_webview2.vcxproj # VS project file
└── packages.config         # NuGet package config

Build

Requirements

• Visual Studio 2022 (17.8+), v145 toolset
• Windows SDK 10.0.22621+
• WebView2 Runtime
• Node.js 18+ (to build the SDK / MCP / docs site)

C++ Component

# Standard build
.\build.ps1 -Config Release -Platform x64

# Package .fb2k-component (x86 + x64)
.\build-package.ps1

# Package offline documentation (Windows users need no extra runtime)
.\build-docs-package.ps1

The documentation ZIP opens through open-docs.cmd and uses only Windows 10/11 built-in Windows PowerShell 5.1, .NET Framework, and the default browser. It does not require Node.js, Python, npm, administrator access, or an Internet connection.

TypeScript SDK (build from source, for development)

Consumers do not need to build it — just npm install foo-webview-sdk (see "npm Packages" above).

cd sdk
npm run build

MCP Server (build from source, for development)

Consumers do not need to build it — just npx foo-ui-webview2-mcp (see "npm Packages" above).

cd mcp
npm install
npm run build

WebUI / Themes

The component ships without a built-in frontend. Place your WebUI under your foobar2000 profile directory at webview-ui\<template>\, with index.html as the required entry point at the template root (e.g. <profile>\webview-ui\default\index.html). <template> defaults to default and can be managed / switched from the component's preferences page. The legacy location <component dir>\foo_ui_webview2_resources\dist\ is still supported for backward compatibility. Restart foobar2000 to load it. You can build custom themes on top of sdk/ (foo-webview-sdk).

API Overview

200+ APIs span the following namespaces:

playback, playlist, library, window, config, file, dialog, clipboard, shell, http, keyboard, ui, lyrics, metadata, audio, console, dnd, queue, discovery, replaygain, playcount, titleformat, selection, port

Events (colon format)

playback:trackChanged, playback:paused, playback:stopped, playback:seeked,
playback:volumeChanged, playback:time, playlist:itemsAdded, playlist:itemsRemoved,
playlist:activated, playlist:created, playlist:removed, playlist:renamed,
playlist:selectionChanged, metadb:changed, plugin:registered, api:registered

Usage Example

// invoke uses dot format
const track = await fb2k.invoke('playback.getCurrentTrack');
const results = await fb2k.invoke('library.search', { query: 'artist:Radiohead' });

// event listeners use colon format
fb2k.on('playback:trackChanged', (track) => { /* ... */ });

Plugin Extensions

Other foobar2000 plugins can register APIs through PluginRegistry for the frontend to call:

#include "api/PluginRegistry.h"

void RegisterMyApis() {
    auto& registry = PluginRegistry::GetInstance();
    registry.RegisterPlugin("my_plugin", "My Plugin", "1.0.0", "Author", "Description");
    registry.RegisterExternalApi("my_plugin", "doSomething",
        [](const json& params) -> json {
            return {{"result", "done"}};
        },
        "Perform an operation"
    );
}

const result = await fb2k.invoke('my_plugin.doSomething', { param1: 'value' });

Security Restrictions

Threat model. This is a dedicated, domain-specific UI host for foobar2000 — themes come from you or trusted sources, so installing a theme carries the same trust as installing any foobar2000 component. The goal is therefore fail-safe (stop a buggy theme from accidentally harming the system), not sandboxing untrusted code; over-locking-down such a specialized component would only tie its own hands. The real guardrails are path validation and protocol checks:

License

The main component of this project is licensed under the GNU General Public License v3.0 or later (GPL-3.0-or-later); see LICENSE for the full terms.

• Main component: GPL-3.0-or-later
• TypeScript SDK (sdk/): MIT License (see sdk/LICENSE)

Third-party libraries retain their own licenses: foobar2000 SDK (BSD), pfc / libPPUI (zlib), nlohmann/json (MIT), Columns UI SDK.

Acknowledgements

• foobar2000 SDK
• WebView2
• nlohmann/json
• Columns UI SDK
• WIL