Create JS Bridge modified by Bayram Emekli

Bayram Emekli — Sat, 04 Jul 2026 04:15:50 -0000

--- v2
+++ v3
@@ -71,7 +71,7 @@
 | `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});` |
+| `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});` |

Create JS Bridge modified by Bayram Emekli

Bayram Emekli — Sat, 04 Jul 2026 04:15:49 -0000

--- v1
+++ v2
@@ -16,7 +16,7 @@

 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 **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](Engine-Comparison) and [Engines Overview](Engines-Overview).

Create JS Bridge modified by Bayram Emekli

Bayram Emekli — Sat, 04 Jul 2026 04:15:22 -0000

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.

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.

Recent changes to Create JS Bridge

Create JS Bridge modified by Bayram Emekli

Create JS Bridge modified by Bayram Emekli

Create JS Bridge modified by Bayram Emekli

The JavaScript Bridge — `SucroseCompatible.json`

Contents

Which engines deliver the bridge

Detecting Sucrose

The hook/template model

Full hook list

Worked examples

Notes and gotchas

See also

Recent changes to Create JS Bridge

Create JS Bridge modified by Bayram Emekli

Create JS Bridge modified by Bayram Emekli

Create JS Bridge modified by Bayram Emekli

The JavaScript Bridge — SucroseCompatible.json

Contents

Which engines deliver the bridge

Detecting Sucrose

The hook/template model

Full hook list

Worked examples

Notes and gotchas

See also

The JavaScript Bridge — `SucroseCompatible.json`