Menu ▾ ▴

Create JS Bridge

Bayram Emekli

The JavaScript Bridge — SucroseCompatible.json

Audience: wallpaper creators and developers. Web wallpapers can opt into receiving live audio and system data and engine‑state changes from Sucrose through a JavaScript bridge. This page explains how a page detects that it is running inside Sucrose, the SucroseCompatible.json hook/template model that drives the bridge, the full list of available hooks, and which engines deliver them. The two big data feeds get their own pages: Create Audio API and Create System API.

Contents

Which engines deliver the bridge

The JavaScript bridge is delivered only by the browser‑style engines: WebView (Microsoft Edge WebView2) and CefSharp (Chromium Embedded Framework). It is therefore available to the Web wallpaper type (and to the built‑in HTML wrappers used for Gif/Video/YouTube). It is not available to:

  • the MpvPlayer, VlcPlayer, Nebula, Vexana, or Xavier engines (pure media playback), or
  • the Aurora engine (native Application embedding — apps receive volume only).

So audio‑reactive and system‑status wallpapers must be the Web type rendered by WebView or CefSharp. See Engine Comparison and Engines Overview.

Detecting Sucrose

A web wallpaper detects that it is running inside Sucrose by checking the User‑Agent:

if (navigator.userAgent.startsWith("Sucrose")) {
  // running inside Sucrose — define the Sucrose* callbacks
}

The default User‑Agent string is:

Sucrose/2.3 (Windows NT 10.0; Wallpaper Engine) SucroseWebKit

This is overridable by the user via the UserAgent general setting, but it always begins with Sucrose, so startsWith("Sucrose") is the reliable check. For porting wallpapers that target other engines, feature‑detect first and fall back to the Sucrose API — see Create Compatibility.

The hook/template model

SucroseCompatible.json is a flat JSON dictionary of JavaScript‑call templates. Each value is a string.Format template where {0} is substituted with the JSON payload for that data feed. The engine fires a hook only if the corresponding string is non‑empty.

For each enabled feed the engine runs string.Format(template, payloadJson) via ExecuteScriptAsync inside the page. Critically, the JavaScript function name on the right side is chosen by you — Sucrose just runs whatever template you provide. By convention every shipped wallpaper uses the Sucrose<Thing>Data names, and that is the documented standard.

For example, this hook:

{ "SystemAudio": "SucroseAudioData({0});" }

causes Sucrose, on each audio update, to call:

SucroseAudioData({ /* audio payload, including the FFT Data array */ });

so you define:

window.SucroseAudioData = function (obj) {
  // obj.Data is the FFT spectrum; see Create-Audio-API
};

Full hook list

All keys are optional strings; include only the ones you need.

Key Payload ({0}) Conventional template
LoopMode loop state SucroseLoopMode({0});
ThemeType light/dark theme SucroseThemeType({0});
SystemTheme light/dark theme (alias of theme)
ShuffleMode shuffle state SucroseShuffleMode({0});
StretchMode None/Fill/Uniform/UniformToFill SucroseStretchMode({0});
VolumeLevel volume level SucroseVolumeLevel({0});
SystemAudio Audio object (incl. FFT Data, DataLeft, DataRight spectra) SucroseAudioData({0});
SystemBios Bios object SucroseBiosData({0});
SystemDate Date object SucroseDateData({0});
SystemMemory Memory object SucroseMemoryData({0});
SystemBattery Battery object SucroseBatteryData({0});
SystemGraphic Graphic object SucroseGraphicData({0});
SystemNetwork Network object SucroseNetworkData({0});
SystemStorage Storage object SucroseStorageData({0});
SystemProcessor Processor object SucroseProcessorData({0});
SystemMotherboard Motherboard object SucroseMotherboardData({0});

The data feeds in detail:

  • SystemAudio — the audio‑reactive feed (FFT spectrum + now‑playing metadata). See Create Audio API.
  • SystemProcessor, SystemGraphic, SystemMemory, SystemNetwork, SystemBattery, SystemStorage, SystemMotherboard, SystemBios, SystemDate — the system feeds. See Create System API.
  • LoopMode, ShuffleMode, StretchMode, ThemeType/SystemTheme, VolumeLevel — engine‑state callbacks. See Create Property Listener Filters.

Enabling any System* (or SystemAudio) hook causes the engine to turn on the Backgroundog data channel for this wallpaper and start a communication transport — see Create Web Architecture and IPC.

Worked examples

A pure audio‑reactive wallpaper (Fluid Simulation):

{ "SystemAudio": "SucroseAudioData({0});" }

A system‑monitor wallpaper (Simple System):

{
  "SystemMemory": "SucroseMemoryData({0});",
  "SystemGraphic": "SucroseGraphicData({0});",
  "SystemNetwork": "SucroseNetworkData({0});",
  "SystemProcessor": "SucroseProcessorData({0});"
}

Matching JavaScript (with a Wallpaper‑Engine/Lively fallback, as the showcase wallpapers do):

if (window.wallpaperRegisterAudioListener) {
  // Wallpaper Engine / Lively style
  window.wallpaperRegisterAudioListener(a => { frequencyArray = a; });
} else if (navigator.userAgent.startsWith("Sucrose")) {
  // Sucrose style — name matches the template in SucroseCompatible.json
  window.SucroseAudioData = function (obj) { frequencyArray = obj.Data; };
}

Notes and gotchas

  • Templates are string.Format strings — each must contain {0} (the property listener template in SucroseProperties.json needs both {0} and {1}). A literal { or } in the template would need escaping.
  • The function names are arbitrary, but the ecosystem standard is Sucrose<Thing>Data / SucrosePropertyListener. Stick to the standard so your wallpaper interoperates with examples and tooling.
  • Empty strings disable a hook — Sucrose only fires hooks whose value is non‑empty.
  • Only the browser engines deliver the bridge; do not rely on it for Application wallpapers.
  • Define your callbacks on window (or globally) so the engine's injected ExecuteScriptAsync calls can reach them.

See also

Related

Wiki: IPC

Auth0 Logo