-
-
Notifications
You must be signed in to change notification settings - Fork 60
FAQ
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)
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 and the Glossary for the big picture.
Yes. Sucrose is open-source under the GNU GPL-3.0 license and is distributed for free through every channel listed in Installation.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Six: Gif, Url, Web, Video, YouTube, and Application. See Wallpaper-Types.
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 and Engine-Comparison.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Turn off both Report Data and Statistics Data in Settings → Other. This stops the Sucrose.Reportdog uploader. See Privacy-Telemetry and Settings-Other.
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.
Use Settings → System: Setting Backup (Export/Import copies the *.json files) and Setting Reset (deletes them to restore defaults). See Backup-Restore-Reset.
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 shows Broken when there's no network. Confirm connectivity and try switching the Store Server (GitHub/Soferity). See Troubleshooting-Common and Using-Store.
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.
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.
Getting Started
- Installation
- System Requirements
- Quick Start
- Portal Interface Tour
- Updating Sucrose
- Uninstalling Sucrose
Wallpaper Types
Using Sucrose
- Managing Library
- Using Store
- Customizing Wallpaper
- Multi-Monitor
- Wallpaper Cycling
- Choosing Engines
- Performance Rules
- Theme, Tray & Startup
- Discord Rich Presence
Settings Reference
- Settings Overview
- Settings: General
- Settings: Personal
- Settings: Performance
- Settings: Wallpaper
- Settings: System
- Settings: Other
- Settings: All Keys
Creating Wallpapers
- Create Overview
- Create: Step By Step
- Create: Package Format
- Create: Customization Controls
- Create: JS Bridge
- Create: Audio API
- Create: System API
- Create: Property Listener & Filters
- Create: Web Architecture
- Create: Compatibility
- Create: Example Wallpapers
- Create: Sharing & Publishing
Engine Reference
- Engines Overview
- Engine: MpvPlayer
- Engine: VlcPlayer
- Engine: WebView
- Engine: CefSharp
- Engine: Nebula
- Engine: Vexana
- Engine: Xavier
- Engine: Aurora
- Engine Comparison
Automation & Command Line
Architecture & Internals
- Architecture Overview
- Lifecycle
- Commandog Dispatcher
- Single-Instance Mutexes
- IPC
- Backgroundog Service
- Crash Reporting
- Update Internals
- Property Service
- Undo Internals
Data, Files & Diagnostics
Building & Contributing
- Building From Source
- Repository Layout
- Shared Item Projects
- Code Conventions
- Preprocessor Symbols
- Publish Pipeline
- Bundle Installer Internals
- Extending Sucrose
- Contributing
- Translating with Localizer
- Localization Coverage
- Security Policy
- Privacy & Telemetry
Help & Support