Glossary

Glossary

A reference of the terms, process names, file names, and identifiers used throughout the Sucrose wiki and codebase. Terms are grouped by topic; within each group they're roughly ordered from most to least common. Every term links to the page that covers it in depth where one exists.

Contents

• Core concepts
• Wallpaper types
• Render engines
• Processes & services
• Inter-process communication (IPC)
• Wallpaper package files
• JavaScript API
• Settings, data & telemetry
• Build & distribution

---

Core concepts

Term	Definition
Sucrose	The wallpaper engine itself: a free, open-source (GPL-3.0), multi-process WPF/.NET 10 live-wallpaper app for Windows. See Home.
Portal	The main settings/management window (Sucrose.Portal), built with WPF-UI + MVVM + DI. Hosts the Library, Store, and the settings pages. See Portal-Interface-Tour.
Library	Your collection of installed wallpapers, stored under %AppData%\Sucrose\Library (relocatable). See Managing-Library.
Store	The in-app catalog of community wallpapers, served from a GitHub or Soferity backend. See Using-Store.
Showcase	The sample wallpapers shipped with the install, copied into the Library on first run (tracked in Warehouse.json). See Create-Example-Wallpapers.
Type	The kind of a wallpaper — one of Gif, Url, Web, Video, YouTube, Application — which determines what engine renders it. See Wallpaper-Types.
Engine	One of eight renderer processes that draws a wallpaper. Each type maps to a configurable engine. See Engines-Overview.
Customize / Properties	Per-wallpaper tweakable controls (sliders, color pickers, etc.) defined in SucroseProperties.json and edited via the Property tool. See Customizing-Wallpaper.
Wallpaper Cycling	Automatic rotation through multiple wallpapers on a timer (Random/Sequential). See Wallpaper-Cycling.
Performance rules	Conditions (lock, sleep, fullscreen, battery, CPU/GPU/RAM thresholds, etc.) that automatically Close, Pause, or Resume the wallpaper. See Performance-Rules.
Backdrop	The Portal window's Mica/Acrylic translucency effect (Win11). Stored as BackdropType. See Theme-Tray-Startup.
WorkerW / Progman	The Windows desktop window layers behind the icons that engines attach their render surface to. See Engines-Overview.

---

Wallpaper types

The WallpaperType enum is Gif, Url, Web, Video, YouTube, Application.

Type	Definition
Gif	An animated GIF file. See Type-Gif.
Url	A remote web address shown as a single static page. See Type-Url.
Web	An interactive local web theme (HTML/CSS/JS); the only type that supports audio-reactive and system-status data. See Type-Web.
Video	A local video file (mp4, etc.). See Type-Video.
YouTube	A YouTube video or playlist URL. See Type-YouTube.
Application	An external program/game embedded as the wallpaper, one instance per monitor. See Type-Application.

---

Render engines

The EngineType enum order is AuroraLive, NebulaLive, VexanaLive, XavierLive, WebViewLive, CefSharpLive, MpvPlayerLive, VlcPlayerLive.

Engine	Definition
MpvPlayer	libmpv-based engine (via Sucrose.Mpv.NET, bundled libmpv-<arch>.dll); default for Gif and Video; needs Windows 10 1607+. See Engine-MpvPlayer.
VlcPlayer	libVLC (LibVLCSharp.WPF) engine, native libVLC bundled per architecture; renders Gif and Video; no install or OS-version check. See Engine-VlcPlayer.
WebView	Microsoft Edge WebView2 (Chromium) engine; renders Gif/Url/Web/Video/YouTube; needs WebView2 runtime ≥ 131.0.2903.70. See Engine-WebView.
CefSharp	Chromium Embedded Framework engine (offscreen rendering, local Watson.Lite HTTP server); default for Url/Web/YouTube; needs VC++ redist ≥ 14.40.33816.0. See Engine-CefSharp.
Nebula	WPF MediaElement video engine using OS codecs; renders Video. (Branded codename, not third-party tech.) See Engine-Nebula.
Vexana	In-house GIF frame parser + timer engine (pure WPF); renders Gif. See Engine-Vexana.
Xavier	Sucrose.XamlAnimatedGif AnimationBehavior engine (can stream remote GIFs); renders Gif. See Engine-Xavier.
Aurora	Application-embedding engine (reparents an external app/game window per monitor via Skylark.Wing; rejects URLs); renders Application. See Engine-Aurora.

---

Processes & services

Each Sucrose component is a separate Windows executable.

Process	Exe	Role
Launcher	Sucrose.Launcher.exe	Entry point; owns the tray icon and Discord Rich Presence. See Architecture-Overview.
Portal	Sucrose.Portal.exe	Main settings/management UI. See Portal-Interface-Tour.
Commandog	Sucrose.Commandog.exe	Short-lived command dispatcher: parses one encoded command, acts, exits. See Commandog-Dispatcher.
Backgroundog	Sucrose.Backgroundog.exe	Headless system-status + audio service; produces the data wallpapers consume; enforces performance rules. See Backgroundog-Service.
Watchdog	Sucrose.Watchdog.exe	Crash dialog + writes structured crash reports. See Crash-Reporting.
Reportdog	Sucrose.Reportdog.exe	Opt-in telemetry/crash-report uploader (Soferity v8). See Privacy-Telemetry.
Property	Sucrose.Property.exe	Per-wallpaper settings/customization editor. See Property-Service.
Update	Sucrose.Update.exe	Auto-updater. See Update-Internals.
Undo	Sucrose.Undo.exe	The uninstaller / full-removal tool. See Undo-Internals.
Live engines	Sucrose.Live.{Aurora,Nebula,Vexana,Xavier,WebView,CefSharp,MpvPlayer,VlcPlayer}.exe	The eight renderer processes. See Engines-Overview.

---

Inter-process communication (IPC)

Term	Definition
Pipe	Named-pipe transport. Pipe names: Sucrose.Wallpaper.Engine.Launcher.Pipe, Sucrose.Wallpaper.Engine.Backgroundog.Pipe. See IPC.
Signal	File-based transport (signal files such as Launcher.sgnl / Backgroundog.sgnl). See IPC.
Transmission	TCP-over-loopback transport on TransmissionPort; the default live-data channel. See IPC.
CommunicationType	The setting choosing the live-data transport: Pipe, Signal, or Transmission (default Transmission). See Settings-Performance.
Command string	Commandog's marker-delimited wire format: ✔<Command>✖<Value0>✖<Value1> using ✔ (U+2714) as the start marker and ✖ (U+2716) as the value separator; command names are case-insensitive. See Command-Reference.
CommandType	The 31-member enum of dispatcher commands (Log, Kill, Live, Update, Interface, RestartLive, Scheduler, …). See Command-Reference.
Mutex	Named single-instance lock. Gating processes (Live, Portal, Update, Property, Launcher, Reportdog, Backgroundog) use the {Sucrose-Wallpaper-Engine-...} mutex names. See Single-Instance-Mutexes.

---

Wallpaper package files

A wallpaper is a folder containing these canonical files.

File	Definition
SucroseInfo.json	The required descriptor (Title, Author, Type, Source, Tags, etc.). See Create-Package-Format.
SucroseProperties.json	Optional customization-control definitions (sliders, checkboxes, color pickers, …). See Create-Customization-Controls.
SucroseCompatible.json	Optional JS-bridge hook declaration (which data callbacks the wallpaper wants). See Create-JS-Bridge.
SucroseStore.json	Optional Store-related metadata. See Create-Overview.
Store.json / Pattern.json	The downloaded Store catalog and search index, cached under %AppData%\Sucrose\Cache\Store. See Using-Store.
MpvPlayer.config / uMpvPlayer.config	MpvPlayer's generated config and optional user override. See Engine-MpvPlayer.
Hashes.json	The installer's per-architecture MD5 integrity manifest. See Bundle-Installer-Internals.

---

JavaScript API

The callbacks the engine invokes inside a Web wallpaper (WebView/CefSharp only).

Callback / token	Definition
SucroseAudioData(obj)	Audio callback: obj.Data is a 128-sample FFT spectrum (WASAPI loopback; Data[0]≈bass; all-zero = silence) plus now-playing metadata. See Create-Audio-API.
SucroseProcessorData / SucroseGraphicData / SucroseMemoryData / SucroseNetworkData / SucroseBatteryData / SucroseStorageData / SucroseMotherboardData / SucroseBiosData / SucroseDateData	System-status callbacks; each payload includes a State validity boolean. See Create-System-API.
SucrosePropertyListener(name, value)	Called when a customization control changes, to live-update the wallpaper. See Create-Property-Listener-Filters.
Playback wrappers	SucrosePlay, SucrosePause, SucrosePlayPause, SucroseLoopMode, SucroseShuffleMode, SucroseStretchMode, SucroseSpeedRate. See Create-Property-Listener-Filters.
User-agent detection	A wallpaper detects Sucrose with navigator.userAgent.startsWith('Sucrose') (default UA: Sucrose/2.3 (Windows NT 10.0; Wallpaper Engine) SucroseWebKit). See Create-JS-Bridge.
Lively/WE fallbacks	wallpaperRegisterAudioListener, wallpaperPropertyListener — compatibility shims for cross-engine wallpapers. See Create-Compatibility.

---

Settings, data & telemetry

Term	Definition
SettingManager	The persistence engine that reads/writes the per-category JSON files (SettingManager, SettingManager2, SettingManager3 variants). See Settings-Persistence.
%AppData%\Sucrose	The Roaming data root: Setting, Log, Cache, Library, Showcase. See Data-Locations.
%LocalAppData%\Sucrose	The install root: the binaries plus the bundled Sucrose.Runtime. See Data-Locations.
ExceptionData / TelemetryData	The two opt-in consent switches (crash uploads / analytics + heartbeat). See Privacy-Telemetry.
Soferity	The closed-source backend (base https://sucrose.soferity.com, API v8) used for the Store, telemetry, crash uploads, and updates. See Privacy-Telemetry.
PersonalAccessToken	A 93-character token (YouTube/private store) stored in plaintext in Objectionable.json. See Settings-Other.
Autorun for Sucrose	The Windows Task Scheduler task created for the Scheduler startup mode. See Troubleshooting-Settings-Startup-GPU.

---

Build & distribution

Term	Definition
Bundle	The Sucrose.Bundle self-extracting .NET Framework 4.8 installer .exe that carries the compressed app payload (Sucrose.7z). See Bundle-Installer-Internals.
Sucrose.Runtime	The trimmed private .NET runtime shipped beside the app so no system .NET is required. See Runtime-Dependencies.
Shared Item Project	A .shproj + .projitems code-reuse unit compiled into each consuming project (not a NuGet package or class library). See Shared-Item-Projects.
Preprocessor symbol	Per-app/engine/platform #if symbol (e.g. PORTAL, ENGINE+LIVE_MPVPLAYER, X64). See Preprocessor-Symbols.
Publish pipeline	The .build/Sucrose.ps1 script that publishes ~17 projects, trims the runtime, and produces Sucrose-<arch>.7z. See Publish-Pipeline.
Localizer	The Sucrose.Localizer console tool that manages the XAML/CSV/POEditor translation pipeline. See Translating-Localizer.
Package ids	Chocolatey sucrose, Scoop sucrose, WinGet Taiizor.SucroseWallpaperEngine, Microsoft Store XP8JGPBHTJGLCQ. See Installation.

---

See also

• FAQ
• Architecture-Overview
• Wallpaper-Types
• Engines-Overview
• Getting-Help