Create JS Bridge

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
• Detecting Sucrose
• The hook/template model
• Full hook list
• Worked examples
• Notes and gotchas
• See also

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, 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 array)	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

• Create Audio API
• Create System API
• Create Property Listener Filters
• Create Web Architecture
• Create Compatibility