Type Web

Web Wallpapers

A Web wallpaper (type value 2, Web) is a local HTML/CSS/JavaScript theme that runs as your desktop background. It is the most powerful wallpaper type in Sucrose: it is interactive (it receives mouse and keyboard input) and it is the only type that receives Sucrose's live data — the audio-reactive SucroseAudioData callback and the full suite of system-status callbacks (CPU, GPU, memory, network, battery, and more). If you want a music visualizer, an equalizer, or an on-desktop system monitor, you build it as a Web wallpaper. This page explains what a Web wallpaper is, how it runs, and what it can do.

Contents

• What it is
• Engines for web
• How a web wallpaper runs
• Interactivity
• Audio reactivity and system data
• Customization controls
• How to apply a web wallpaper
• Performance
• Tips
• See also

What it is

In the manifest, a Web wallpaper has "Type": 2 and a Source that names the local entry HTML file inside the wallpaper folder (for example Matrix.html). The entry file's extension must pass Sucrose's web-extension filter (typically .html / .htm).

A key packaging rule: when you create a Web wallpaper, the entire containing folder is copied into the theme, and Source is just the entry file name. Keep your wallpaper self-contained in one directory (its HTML, JS, CSS, and assets), and make sure that directory is writable/unlocked when you import it.

Engines for web

Web wallpapers are served by a browser engine. The default and allowed engines:

Engine	Tech	Notes
CefSharp (default)	Chromium Embedded Framework (offscreen)	Serves the theme over a built-in local HTTP server. Requires the VC++ Redistributable (≥ 14.40.33816.0).
WebView	Microsoft Edge WebView2 (Chromium)	Serves the theme over a local HTTP server. Requires the WebView2 runtime (≥ 131.0.2903.70).

Both deliver the full JavaScript bridge (audio, system data, properties, playback). Change the engine in Settings → Wallpaper (the WebPlayer selector). See Choosing Engines, Engine-CefSharp, and Engine-WebView.

How a web wallpaper runs

1. You apply the wallpaper; Sucrose reads SucroseInfo.json and launches the selected browser engine.
2. The engine starts a small local HTTP server and serves your theme at http://localhost:{port}/ and http://127.0.0.1:{port}/ (a free loopback port is chosen automatically). Web content is served over HTTP, not file://.
3. On init, the engine pushes your current customization values into the page via SucrosePropertyListener.
4. If your SucroseCompatible.json opts into live data, the Backgroundog service captures audio (WASAPI loopback → FFT) and polls hardware/media info, then streams it to the engine over a named pipe/transmission channel. The engine calls each of your declared JS callbacks with the payload via ExecuteScriptAsync.
5. Mouse/keyboard activity on the desktop is forwarded into the page as input.

For the full data-flow walkthrough see Create Web Architecture.

🖼️ Diagram needed: Sequence diagram — apply Web wallpaper → engine starts local HTTP server → Backgroundog pumps audio/system data over pipe → engine ExecuteScriptAsync into the page's Sucrose* callbacks.

Interactivity

Web wallpapers are interactive. The browser engines (WebView and CefSharp) reference Sucrose's raw-input library, so when the desktop is focused, mouse movement, clicks, scrolling, and keyboard input are forwarded into your page as standard web events. This is what lets a Web wallpaper respond to the cursor.

Audio reactivity and system data

This is the defining capability of the Web type. A web wallpaper declares which live-data hooks it wants in a SucroseCompatible.json file — a flat map of JS-call templates. When a hook is present, Sucrose pushes that data into your page:

• Audio — SucroseAudioData(obj). obj.Data is the FFT magnitude spectrum (128 samples from WASAPI loopback capture); obj.Data[0] is the lowest band (bass), and an all-zero array means silence. The same object also carries now-playing media-session metadata (title, artist, playback state, etc.). See Create Audio API.
• System status — SucroseProcessorData, SucroseGraphicData, SucroseMemoryData, SucroseNetworkData, SucroseBatteryData, SucroseStorageData, SucroseMotherboardData, SucroseBiosData, and SucroseDateData. Each object carries a State validity boolean and the relevant readings. See Create System API.

Minimal example (feature-detecting Wallpaper Engine / Lively first, then Sucrose):

let spectrum = [];
if (window.wallpaperRegisterAudioListener) {
    window.wallpaperRegisterAudioListener(a => spectrum = a);
} else if (navigator.userAgent.startsWith("Sucrose")) {
    window.SucroseAudioData = function (obj) { spectrum = obj.Data; };
}

Sucrose itself is detected via the User-Agent (navigator.userAgent.startsWith("Sucrose")); the default UA is Sucrose/2.3 (Windows NT 10.0; Wallpaper Engine) SucroseWebKit. See Create JS Bridge and Create Compatibility.

Customization controls

A Web wallpaper can ship a SucroseProperties.json to expose user-adjustable controls (sliders, color pickers, dropdowns, checkboxes, and more) in the Portal's Customize panel. Changes are delivered to your page through SucrosePropertyListener(name, val) and re-applied live. See Create Customization Controls and Customizing Wallpaper.

How to apply a web wallpaper

1. Open the Portal → Library.
2. Import a Web wallpaper folder (or pick a shipped Showcase example) — see Managing Library and Create Example Wallpapers.
3. Right-click the card → Use.
4. Open Customize to adjust any controls the creator exposed.

Performance

Web wallpapers run a Chromium-based process, so they cost more than a video. Audio capture and system polling add a small overhead while the wallpaper is active. To keep things efficient, Sucrose's Performance Rules can pause or close the wallpaper on lock, fullscreen, battery, sleep, or when CPU/GPU/RAM cross thresholds.

Tips

• For audio reactivity, declare "SystemAudio": "SucroseAudioData({0});" in SucroseCompatible.json — without it, no audio data is pushed.
• Only request the system hooks you actually use; each enabled hook adds work.
• Keep the whole wallpaper in one folder; the importer copies the entire directory.
• Porting from Wallpaper Engine or Lively? Feature-detect their hooks and fall back to the Sucrose API — see Create Compatibility.

See also

• Wallpaper Types — all six types and the engine mapping
• Create Audio API and Create System API — the live-data callbacks
• Create Web Architecture — how a web wallpaper runs end to end
• Type-Url — remote websites (no live data injected)
• Engine-CefSharp and Engine-WebView — the browser engines