Recent changes to FAQ

FAQ modified by Bayram Emekli

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

--- v5
+++ v6
@@ -38,7 +38,7 @@
 Use Windows **Apps & Features**, which runs `Sucrose.Undo.exe`, or your package manager (`choco uninstall sucrose`, `scoop uninstall sucrose`, winget). The uninstaller can optionally remove your settings/data folder too. See [Uninstalling-Sucrose](Uninstalling-Sucrose) and [Undo-Internals](Undo-Internals).

 ### I got a "checksum mismatch" error during install. What happened?
-The Bundle installer verifies every extracted file against an embedded MD5 manifest (`Hashes.json`). A mismatch means the download was incomplete or corrupted. The installer shows an "Installation Error" page that offers to re-download from GitHub, the Microsoft Store, SourceForge, or the official website. Re-download and run it again. See [Installation](Installation) and [Bundle-Installer-Internals](Bundle-Installer-Internals).
+The Bundle installer verifies every extracted file against an embedded SHA256 manifest (`Hashes.json`). A mismatch means the download was incomplete or corrupted. The installer shows an "Installation Error" page that offers to re-download from GitHub, the Microsoft Store, SourceForge, or the official website. Re-download and run it again. See [Installation](Installation) and [Bundle-Installer-Internals](Bundle-Installer-Internals).

 ---

FAQ modified by Bayram Emekli

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

--- v4
+++ v5
@@ -95,7 +95,7 @@
 ## Creating wallpapers

 ### What is the file format of a Sucrose wallpaper?
-A wallpaper is a **folder** containing a `SucroseInfo.json` descriptor, plus optional siblings `SucroseProperties.json` (customization controls), `SucroseCompatible.json` (the JS data bridge), and `SucroseStore.json`. See [Create-Overview](Create-Overview) and [Create-Package-Format](Create-Package-Format).
+A wallpaper is a **folder** containing a `SucroseInfo.json` descriptor, plus optional siblings `SucroseProperties.json` (customization controls), `SucroseCompatible.json` (the JS data bridge), `SucroseStore.json` (an empty marker on Store-installed wallpapers), and `SucrosePremium.json` (present in wallpapers bought from the Premium Store). See [Create-Overview](Create-Overview) and [Create-Package-Format](Create-Package-Format).

 ### How do I add sliders/checkboxes that users can tweak?
 Define them in `SucroseProperties.json` and respond to the `SucrosePropertyListener(name, value)` callback in your wallpaper. See [Create-Customization-Controls](Create-Customization-Controls) and [Create-Property-Listener-Filters](Create-Property-Listener-Filters).

FAQ modified by Bayram Emekli

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

--- v3
+++ v4
@@ -85,7 +85,7 @@
 Gif and Video default to **MpvPlayer**; Url, Web, and YouTube default to **CefSharp**; Application uses **Aurora**. You can change the per-type engine on the Wallpaper settings page. See [Choosing-Engines](Choosing-Engines) and [Settings-Wallpaper](Settings-Wallpaper).

 ### Why is my web wallpaper not reacting to audio?
-Audio-reactive and system-status data is only injected into **Web**-type wallpapers rendered by **WebView** or **CefSharp**. Video, GIF, and Application engines do not receive system data. The wallpaper must also declare the hook (e.g. `SystemAudio`) in its `SucroseCompatible.json`. See [Create-Audio-API](Create-Audio-API) and [Troubleshooting-Common](Troubleshooting-Common).
+Audio-reactive and system-status data is only injected into **Web**-type wallpapers rendered by **WebView** or **CefSharp**. Video, Gif, and Application engines do not receive system data. The wallpaper must also declare the hook (e.g. `SystemAudio`) in its `SucroseCompatible.json`. See [Create-Audio-API](Create-Audio-API) and [Troubleshooting-Common](Troubleshooting-Common).

 ### Can I run a game or external app as my wallpaper?
 Yes, with the **Application** type and the **Aurora** engine, which embeds one instance of the program per monitor. It accepts `Arguments` but rejects URLs. See [Type-Application](Type-Application) and [Engine-Aurora](Engine-Aurora).

FAQ modified by Bayram Emekli

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

--- v2
+++ v3
@@ -17,7 +17,7 @@
 ## Installation & updates

 ### What is Sucrose?
-Sucrose is a free, open-source (GPL-3.0) live wallpaper engine for Windows. It can render six wallpaper types — GIF, URL, Web, Video, YouTube, and Application — through eight rendering engines, and it exposes an audio-reactive and system-status JavaScript API for web wallpapers. See [Home](Home) and the [Glossary](Glossary) for the big picture.
+Sucrose is a free, open-source (GPL-3.0) live wallpaper engine for Windows. It can render six wallpaper types — Gif, Url, Web, Video, YouTube, and Application — through eight rendering engines, and it exposes an audio-reactive and system-status JavaScript API for web wallpapers. See [Home](Home) and the [Glossary](Glossary) for the big picture.

 ### Is it really free?
 Yes. Sucrose is open-source under the GNU GPL-3.0 license and is distributed for free through every channel listed in [Installation](Installation).

FAQ modified by Bayram Emekli

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

--- v1
+++ v2
@@ -17,7 +17,7 @@
 ## Installation & updates

 ### What is Sucrose?
-Sucrose is a free, open-source (GPL-3.0) live wallpaper engine for Windows. It can render six wallpaper types — GIF, URL, Web, Video, YouTube, and Application — through seven rendering engines, and it exposes an audio-reactive and system-status JavaScript API for web wallpapers. See [Home](Home) and the [Glossary](Glossary) for the big picture.
+Sucrose is a free, open-source (GPL-3.0) live wallpaper engine for Windows. It can render six wallpaper types — GIF, URL, Web, Video, YouTube, and Application — through eight rendering engines, and it exposes an audio-reactive and system-status JavaScript API for web wallpapers. See [Home](Home) and the [Glossary](Glossary) for the big picture.

 ### Is it really free?
 Yes. Sucrose is open-source under the GNU GPL-3.0 license and is distributed for free through every channel listed in [Installation](Installation).
@@ -79,7 +79,7 @@
 Six: `Gif`, `Url`, `Web`, `Video`, `YouTube`, and `Application`. See [Wallpaper-Types](Wallpaper-Types).

 ### What is an "engine"?
-An engine is one of seven separate renderer processes that draws a wallpaper: `MpvPlayer`, `WebView`, `CefSharp`, `Nebula`, `Vexana`, `Xavier`, and `Aurora`. Each wallpaper type maps to a configurable engine. See [Engines-Overview](Engines-Overview) and [Engine-Comparison](Engine-Comparison).
+An engine is one of eight separate renderer processes that draws a wallpaper: `MpvPlayer`, `VlcPlayer`, `WebView`, `CefSharp`, `Nebula`, `Vexana`, `Xavier`, and `Aurora`. Each wallpaper type maps to a configurable engine. See [Engines-Overview](Engines-Overview) and [Engine-Comparison](Engine-Comparison).

 ### Which engine does each type use by default?
 Gif and Video default to **MpvPlayer**; Url, Web, and YouTube default to **CefSharp**; Application uses **Aurora**. You can change the per-type engine on the Wallpaper settings page. See [Choosing-Engines](Choosing-Engines) and [Settings-Wallpaper](Settings-Wallpaper).

FAQ modified by Bayram Emekli

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

Frequently Asked Questions

This page answers the questions people ask most often about Sucrose — installing it, using it, creating wallpapers, performance, and privacy. Each answer links to the page that covers the topic in depth. If your question is a problem rather than a "how does this work" question, start with Troubleshooting-Common or Troubleshooting-Settings-Startup-GPU instead.

Installation & updates
Using Sucrose
Wallpaper types & engines
Creating wallpapers
Performance & battery
Data, privacy & telemetry
Troubleshooting (quick answers)

Installation & updates

What is Sucrose?

Sucrose is a free, open-source (GPL-3.0) live wallpaper engine for Windows. It can render six wallpaper types — GIF, URL, Web, Video, YouTube, and Application — through seven rendering engines, and it exposes an audio-reactive and system-status JavaScript API for web wallpapers. See Home and the Glossary for the big picture.

Is it really free?

Yes. Sucrose is open-source under the GNU GPL-3.0 license and is distributed for free through every channel listed in Installation.

How do I install it?

Pick any channel: the Microsoft Store (product ID XP8JGPBHTJGLCQ), a GitHub Release .exe, or a package manager — choco install sucrose, scoop install sucrose, or winget install Taiizor.SucroseWallpaperEngine. Full details, including the SourceForge and sucrose.soferity.com mirrors, are in Installation.

Do I need administrator rights to install?

No. The installer requests asInvoker (no elevation) and installs per-user to %LocalAppData%\Sucrose. It writes only to your user profile and the HKCU registry hive. See Installation.

What are the system requirements?

Windows (WPF), per-monitor-DPI aware, on x64, x86, or ARM64. Sucrose ships a trimmed private .NET 10 runtime (Sucrose.Runtime), so you do not need a system-wide .NET install. The installer itself needs .NET Framework 4.8. Web/Video engines additionally need the WebView2 runtime and the VC++ redistributable. See System-Requirements and Runtime-Dependencies.

How does updating work?

Auto-update is on by default. You can choose the update source (GitHub or Soferity), channel (Release or PreRelease), and how silently it runs (Visible, SemiSilent, CompleteSilent). See Updating-Sucrose and the internals in Update-Internals.

How do I uninstall it?

Use Windows Apps & Features, which runs Sucrose.Undo.exe, or your package manager (choco uninstall sucrose, scoop uninstall sucrose, winget). The uninstaller can optionally remove your settings/data folder too. See Uninstalling-Sucrose and Undo-Internals.

I got a "checksum mismatch" error during install. What happened?

The Bundle installer verifies every extracted file against an embedded MD5 manifest (Hashes.json). A mismatch means the download was incomplete or corrupted. The installer shows an "Installation Error" page that offers to re-download from GitHub, the Microsoft Store, SourceForge, or the official website. Re-download and run it again. See Installation and Bundle-Installer-Internals.

Using Sucrose

How do I set my first wallpaper?

Open the Portal, pick a Showcase/Library item or a Store item, choose Use, customize if you like, then set it to start with Windows. See Quick-Start.

Where is the window? I only see a tray icon.

The tray icon is owned by the Launcher process, not the Portal. Click it (or relaunch Sucrose) to open the Portal window. See Portal-Interface-Tour and Theme-Tray-Startup.

Can I use different wallpapers on each monitor / span one across all?

Use the Display Preferences dialog. The display mode is Screen (PerDisplay, the default, one wallpaper per chosen monitor), Expand (SpanAcross), or Duplicate (SameDuplicate, currently disabled). See Multi-Monitor.

Can Sucrose rotate through several wallpapers automatically?

Yes — turn on Wallpaper Cycling. Set the transition time (1–999 minutes, default 30) and choose Random or Sequential. You can exclude individual wallpapers. See Wallpaper-Cycling.

How do I make a wallpaper start automatically when Windows boots?

Set Application Startup on the General settings page. The options are 0=None, 1=Normal, 2=Priority (admin), 3=Scheduler. The Scheduler option creates a Windows Task Scheduler task named Autorun for Sucrose. See Theme-Tray-Startup and Settings-General.

How do I import my own GIF/video/web/app?

Drag a .zip, .url, or a media/web/app file onto the Library, or use the Create Wallpaper dialog. See Managing-Library and Create-Step-By-Step.

What is the Store, and is it safe to browse?

The Store is an in-app catalog of community wallpapers served from either a GitHub or Soferity backend. It has an adult-content filter (on by default) and downloads into a local cache under %AppData%\Sucrose\Cache\Store. See Using-Store.

Can I adjust a wallpaper's look (color, blur, speed, mute)?

Yes, via Customize. The available controls depend on the engine — for example MpvPlayer exposes video-zoom, saturation, hue, sharpen, brightness, contrast, blur, gamma, speed (0.25–2.5), mute, and subtitle; browser engines expose CSS-style filters and muted/caption. Changes re-apply live. See Customizing-Wallpaper.

Does Sucrose support Discord Rich Presence?

Yes. Enable Discord Hook in the Other settings; it requires Discord (or PTB) to be running, and refreshes on a configurable delay of 60–3600 seconds (default 60). See Discord-Rich-Presence.

Wallpaper types & engines

What wallpaper types are there?

Six: Gif, Url, Web, Video, YouTube, and Application. See Wallpaper-Types.

What is an "engine"?

An engine is one of seven separate renderer processes that draws a wallpaper: MpvPlayer, WebView, CefSharp, Nebula, Vexana, Xavier, and Aurora. Each wallpaper type maps to a configurable engine. See Engines-Overview and Engine-Comparison.

Which engine does each type use by default?

Gif and Video default to MpvPlayer; Url, Web, and YouTube default to CefSharp; Application uses Aurora. You can change the per-type engine on the Wallpaper settings page. See Choosing-Engines and Settings-Wallpaper.

Why is my web wallpaper not reacting to audio?

Audio-reactive and system-status data is only injected into Web-type wallpapers rendered by WebView or CefSharp. Video, GIF, and Application engines do not receive system data. The wallpaper must also declare the hook (e.g. SystemAudio) in its SucroseCompatible.json. See Create-Audio-API and Troubleshooting-Common.

Can I run a game or external app as my wallpaper?

Yes, with the Application type and the Aurora engine, which embeds one instance of the program per monitor. It accepts Arguments but rejects URLs. See Type-Application and Engine-Aurora.

Creating wallpapers

What is the file format of a Sucrose wallpaper?

A wallpaper is a folder containing a SucroseInfo.json descriptor, plus optional siblings SucroseProperties.json (customization controls), SucroseCompatible.json (the JS data bridge), and SucroseStore.json. See Create-Overview and Create-Package-Format.

How do I add sliders/checkboxes that users can tweak?

Define them in SucroseProperties.json and respond to the SucrosePropertyListener(name, value) callback in your wallpaper. See Create-Customization-Controls and Create-Property-Listener-Filters.

How does my web wallpaper read audio and system data?

Subscribe to the JS callbacks the engine calls — SucroseAudioData(obj) for the FFT spectrum and now-playing metadata, and SucroseProcessorData, SucroseMemoryData, SucroseNetworkData, etc. for system status. See Create-Audio-API and Create-System-API.

How do I detect that my wallpaper is running inside Sucrose?

Check navigator.userAgent.startsWith('Sucrose'). The default user agent string is Sucrose/2.3 (Windows NT 10.0; Wallpaper Engine) SucroseWebKit. See Create-JS-Bridge and Create-Compatibility.

Will wallpapers I wrote for Lively or Wallpaper Engine work?

You can add fallbacks — Sucrose code can feature-detect and you can also wire up wallpaperRegisterAudioListener / wallpaperPropertyListener so one wallpaper runs on multiple engines. See Create-Compatibility.

Export it to a .zip (ThemeShare), or publish to the Soferity backend (90 MB cap, with field limits). The GitHub Store backend cannot accept publishes. See Create-Sharing-Publishing.

Performance & battery

Does Sucrose use a lot of CPU/GPU?

It depends on the wallpaper and engine. Sucrose has a performance rules system that can automatically Close, Pause, or Resume the wallpaper based on conditions like lock, sleep, fullscreen apps, battery, and CPU/GPU/RAM thresholds. See Performance-Rules and Settings-Performance.

Does it pause when I play a fullscreen game?

If the Full Screen rule is set to Pause or Close, yes. By default FullScreenPerformance is Resume, so set it to your preference on the Performance settings page. See Performance-Rules.

Will it drain my laptop battery?

You can control that. The Battery and Battery Saver rules let you Close/Pause the wallpaper on battery, with a battery-percentage threshold (BatteryUsage, default 50). By default these are Resume. See Performance-Rules and Settings-Performance.

What's the difference between "Heavy" and "Light" pause?

Light pauses rendering; Heavy additionally suspends the process threads (including WebView2/CefSharp child processes and the Aurora application). Set this with Pause performance type (default Light). See Performance-Rules and Backgroundog-Service.

Which engine is lightest?

For GIFs, the pure-WPF engines Vexana and Xavier avoid Chromium/libmpv. For video without libmpv, Nebula uses the OS media stack. See Engine-Comparison.

Data, privacy & telemetry

Where are my settings stored?

As small JSON files under %AppData%\Sucrose\Setting\ (one file per category, e.g. General.json, Engine.json). There is no monolithic config file and no app registry usage for settings. See Data-Locations and Settings-Persistence.

Does Sucrose collect data about me?

Two opt-in switches govern this: Report Data (ExceptionData, crash uploads) and Statistics Data (TelemetryData, analytics + an online heartbeat). Both default to true and can be turned off on the Other settings page. Data goes to the Soferity v8 backend. See Privacy-Telemetry.

How do I disable telemetry completely?

Turn off both Report Data and Statistics Data in Settings → Other. This stops the Sucrose.Reportdog uploader. See Privacy-Telemetry and Settings-Other.

Is my Personal Access Token stored securely?

No — the PersonalAccessToken (used for YouTube/private store access) is stored in plaintext in Objectionable.json. Treat that file as sensitive. See Privacy-Telemetry and Settings-Other.

How do I back up or reset my settings?

Use Settings → System: Setting Backup (Export/Import copies the *.json files) and Setting Reset (deletes them to restore defaults). See Backup-Restore-Reset.

Troubleshooting (quick answers)

My wallpaper won't show / I get a black screen.

Check the engine's runtime requirements (WebView2, VC++ redist, Windows 10 1607 for MpvPlayer) and try a different engine for that type. See Troubleshooting-Common and Runtime-Dependencies.

The Store says it's offline.

The Store shows Broken when there's no network. Confirm connectivity and try switching the Store Server (GitHub/Soferity). See Troubleshooting-Common and Using-Store.

A setting won't stick / my settings look reset.

If a settings file is missing, empty, or invalid JSON it is auto-reset; and writes silently fail if a file is locked or permission-denied. See Troubleshooting-Settings-Startup-GPU and Settings-Persistence.

How do I get logs for a bug report?

Use Settings → System → Log Temporary → Create (a zip of your logs and settings) or the tray Report action, then attach it to a GitHub issue. See Logs-Diagnostics and Getting-Help.

Recent changes to FAQ

FAQ modified by Bayram Emekli

FAQ modified by Bayram Emekli

FAQ modified by Bayram Emekli

FAQ modified by Bayram Emekli

FAQ modified by Bayram Emekli

FAQ modified by Bayram Emekli

Frequently Asked Questions

Contents

Installation & updates

What is Sucrose?

Is it really free?

How do I install it?

Do I need administrator rights to install?

What are the system requirements?

How does updating work?

How do I uninstall it?

I got a "checksum mismatch" error during install. What happened?

Using Sucrose

How do I set my first wallpaper?

Where is the window? I only see a tray icon.

Can I use different wallpapers on each monitor / span one across all?

Can Sucrose rotate through several wallpapers automatically?

How do I make a wallpaper start automatically when Windows boots?

How do I import my own GIF/video/web/app?

What is the Store, and is it safe to browse?

Can I adjust a wallpaper's look (color, blur, speed, mute)?

Does Sucrose support Discord Rich Presence?

Wallpaper types & engines

What wallpaper types are there?

What is an "engine"?

Which engine does each type use by default?

Why is my web wallpaper not reacting to audio?

Can I run a game or external app as my wallpaper?

Creating wallpapers

What is the file format of a Sucrose wallpaper?

How do I add sliders/checkboxes that users can tweak?

How does my web wallpaper read audio and system data?

How do I detect that my wallpaper is running inside Sucrose?

Will wallpapers I wrote for Lively or Wallpaper Engine work?

How do I share or publish a wallpaper?

Performance & battery

Does Sucrose use a lot of CPU/GPU?

Does it pause when I play a fullscreen game?

Will it drain my laptop battery?

What's the difference between "Heavy" and "Light" pause?

Which engine is lightest?

Data, privacy & telemetry

Where are my settings stored?

Does Sucrose collect data about me?

How do I disable telemetry completely?

Is my Personal Access Token stored securely?

How do I back up or reset my settings?

Troubleshooting (quick answers)

My wallpaper won't show / I get a black screen.

The Store says it's offline.

A setting won't stick / my settings look reset.

How do I get logs for a bug report?

See also