Customizing Wallpaper
Many wallpapers can be tweaked live without re-applying them. The Customize command on a library card opens a property panel whose controls depend on the rendering engine: video engines (MpvPlayer) expose mpv playback/image controls, while browser engines (CefSharp / WebView) expose CSS-style visual filters and playback toggles. Web wallpapers can additionally expose their own author-defined controls. This page documents both built-in property panels in full, explains how changes are re-applied live, and notes which wallpapers and engines can be customized at all.
- Opening the customize panel
- Which wallpapers can be customized
- The MpvPlayer property panel
- The VlcPlayer property panel
- The browser property panel (CefSharp / WebView)
- Author-defined controls (Web wallpapers)
- How live re-apply works
- See also
Right-click a wallpaper in the Library and choose Customize (MenuCustomize). This launches the wallpaper's property editor through the Property service (Sucrose.Property), dispatched as Commandog PropertyA. The panel that appears is chosen from the wallpaper's PropertiesType (Base, WebView, CefSharp, MpvPlayer, or VlcPlayer), which is determined by the wallpaper type and the engine you have selected for it.
Customize is enabled only for:
-
Web wallpapers that declare properties (an author-supplied
SucroseProperties.json— see Create: Customization Controls); and - Gif / Video / YouTube wallpapers whose selected engine supports a property panel — that is, MpvPlayer, VlcPlayer, CefSharp, or WebView for that type.
Wallpapers rendered by engines without a property panel (Nebula, Vexana, Xavier, Aurora) cannot be customized this way; the Customize command is disabled. If the Backgroundog performance service has paused or closed the engine, Customize is also temporarily disabled.
When a Gif or Video wallpaper is rendered by MpvPlayer, the panel exposes libmpv image and playback controls (PropertiesType.MpvPlayer, stored as the base64 JSON MpvProperties):
| Control | Effect | Notes |
|---|---|---|
| video-zoom | Zoom level | range -5 .. 5 |
| saturation | Color saturation | |
| hue | Hue shift | |
| sharpen | Edge sharpening | |
| brightness | Brightness | |
| contrast | Contrast | |
| scale-blur | Blur | |
| gamma | Gamma correction | |
| speed | Playback speed | range 0.25 – 2.5 |
| mute | Mute audio | |
| sid | Subtitle / caption track toggle |
These map directly to mpv properties on the live player, so adjustments take effect immediately.
When a Gif or Video wallpaper is rendered by VlcPlayer, the panel exposes libVLC image and playback controls (PropertiesType.VlcPlayer, stored as the base64 JSON VlcProperties):
| Control | Effect | Notes |
|---|---|---|
| saturation | Color saturation | −100 .. 100 |
| hue | Hue shift | −100 .. 100 |
| brightness | Brightness | −100 .. 100 |
| contrast | Contrast | −100 .. 100 |
| gamma | Gamma correction | currently non-functional |
| speed | Playback rate | |
| mute | Mute audio |
The four color filters and gamma are applied through libVLC's video-adjust and only take effect when Hardware Acceleration is on; speed and mute work regardless.
When a Gif, Video, or YouTube wallpaper is rendered by a browser engine (CefSharp → PropertiesType.CefSharp / CefProperties, or WebView → PropertiesType.WebView / WebProperties), the panel exposes the same set of CSS-style filters and playback toggles:
| Control | Effect |
|---|---|
| scale | Zoom (CSS scale) |
| saturate | Saturation |
| hue-rotate | Hue rotation |
| brightness | Brightness |
| contrast | Contrast |
| blur | Blur |
| grayscale | Grayscale |
| sepia | Sepia tone |
| invert | Color inversion |
| mirror | Mirror (dropdown) |
| animation | Entrance/idle animation: Flat, Flip, Pulse, Shake, Bounce, Wiggle
|
| playbackRate | Media playback rate |
| muted | Mute audio |
| caption | Caption/subtitle toggle |
A Web wallpaper can ship its own custom controls (sliders, checkboxes, dropdowns, color pickers, text boxes, and more) declared by the author in SucroseProperties.json. These appear in the same Customize panel and are the wallpaper-specific equivalent of the built-in filters above. The full control catalog, the PropertyList/PropertyListener model, and localization of control labels are covered in Create: Customization Controls and Create: Property Listener & Filters.
When you change a value in the Customize panel, the Property tool writes the new value into the wallpaper's properties cache file. Inside the running engine a FileSystemWatcher notices the change and re-injects the values without restarting the wallpaper:
- MpvPlayer applies the new mpv property directly to the live player.
- VlcPlayer applies the new value to the live libVLC player.
-
Browser engines inject the value into the page through
ExecuteScriptAsync, calling the property-listener JavaScript template (SucrosePropertyListener('{0}', {1});) so the page updates in place.
This is why customization is instantaneous and does not flicker the way changing the wallpaper's engine does — there is no engine restart, only a live re-injection. (Changing the engine for a type, by contrast, is a full engine swap; see Choosing Engines.)