Wallpaper Types

Wallpaper Types

Sucrose can turn almost any kind of moving (or interactive) content into your desktop background. It does this by supporting six wallpaper types — Gif, Url, Web, Video, YouTube, and Application — and by mapping each type to one of eight render engines that actually draws the content behind your desktop icons. This page is the hub for that system: it explains what each type is, which engine renders it by default, which engines you may switch to, and how the types compare on interactivity, audio/system-data support, and performance. Each type also has its own dedicated page for deeper detail.

Contents

• The six types at a glance
• How a type becomes a wallpaper
• Type-to-engine mapping
• Capability comparison
• Which type should I use?
• Where the type is stored
• See also

The six types at a glance

The type of a wallpaper is fixed in its manifest (SucroseInfo.json) as an integer in the Type field. The enum (Sucrose.Shared.Dependency.Enum.WallpaperType) defines the value-to-name mapping below — and the values matter, because the manifest serializes the type as a number, not a string.

Value	Type	What it is	Source field means	Page
0	Gif	An animated GIF file	local .gif file name inside the folder	Gif Wallpapers
1	Url	A remote web address shown as a single page	a remote http/https URL	Url Wallpapers
2	Web	An interactive local HTML/CSS/JS theme	local entry HTML/web file name inside the folder	Web Wallpapers
3	Video	A local video file	local video file name inside the folder	Video Wallpapers
4	YouTube	A YouTube video or playlist	a YouTube video or playlist URL	YouTube Wallpapers
5	Application	An external program/game run as the wallpaper	local executable file name inside the folder	Application Wallpapers

flowchart LR
    Gif["Gif (0)"] --> Mpv["MpvPlayer"]
    Gif --> Vex["Vexana"]
    Gif --> Xav["Xavier"]
    Gif --> WV["WebView"]
    Gif --> Cef["CefSharp"]
    Video["Video (3)"] --> Mpv
    Video --> Neb["Nebula"]
    Video --> WV
    Video --> Cef
    Gif --> Vlc["VlcPlayer"]
    Video --> Vlc
    Url["Url (1)"] --> WV
    Url --> Cef
    Web["Web (2)"] --> WV
    Web --> Cef
    YouTube["YouTube (4)"] --> WV
    YouTube --> Cef
    Application["Application (5)"] --> Aur["Aurora"]

Defaults: Gif/Video → MpvPlayer, Url/Web/YouTube → CefSharp, Application → Aurora.

How a type becomes a wallpaper

When you apply a wallpaper, Sucrose:

1. Reads the wallpaper's SucroseInfo.json and finds its Type.
2. Looks up which engine is currently selected for that type (a per-type setting you control in Settings → Wallpaper; see Choosing Engines).
3. Launches the matching engine executable (e.g. Sucrose.Live.MpvPlayer.exe) as a separate process via the Commandog dispatcher.
4. The engine reads the same Type again, opens the correct window, and attaches it behind your desktop icons.

Switching wallpapers terminates the old engine process and launches a new one. See Lifecycle and Engines Overview for the full launch path.

Type-to-engine mapping

Each type ships with a default engine and a fixed set of allowed engines. You can change the engine per type, but only to engines that can actually render that type (the Portal only offers compatible engines). The defaults and allowed sets come straight from the codebase.

Type	Default engine	Allowed engines
Gif	MpvPlayer	Vexana, Xavier, WebView, CefSharp, MpvPlayer, VlcPlayer
Url	CefSharp	WebView, CefSharp
Web	CefSharp	WebView, CefSharp
Video	MpvPlayer	Nebula, WebView, CefSharp, MpvPlayer, VlcPlayer
YouTube	CefSharp	WebView, CefSharp
Application	Aurora	Aurora (only)

A quick way to remember it: Gif and Video default to MpvPlayer (libmpv), the three URL-style types (Url, Web, YouTube) default to CefSharp (Chromium), and Application always uses Aurora (process embedding). WebView is the everything-capable browser alternative you can opt into for any of the browser-served types.

For the engines themselves — their underlying technology, runtime requirements, and trade-offs — see Engines Overview, Engine Comparison, and the individual engine pages.

Capability comparison

Not every type is interactive, and only one type can receive Sucrose's live audio/system data. This table summarizes the practical differences.

Type	Interactive (mouse/keyboard)	Audio-reactive / system data	Resolution-independent	Relative resource cost
Gif	No	No	Limited (raster frames)	Low–medium
Url	Depends on the site	No (data hooks not injected into external Url pages)	Yes (web layout)	Medium
Web	Yes	Yes (Audio + System JS API)	Yes (web layout)	Medium–high
Video	No	No	Limited (fixed resolution source)	Medium (hardware-accelerated)
YouTube	Via JS playback controls	No	Yes (streamed)	Medium–high (network)
Application	Yes (the app handles it)	No (Aurora apps receive volume only)	Depends on the app	Varies (runs a real app per monitor)

Key facts that drive this table:

• Only the Web type, rendered by a browser engine (WebView or CefSharp), receives Sucrose's live data. The audio-reactive callback SucroseAudioData and the system-status callbacks (SucroseProcessorData, SucroseMemoryData, etc.) are injected only into web content. See Audio API, System API, and Web Architecture.
• Mouse/keyboard input is forwarded only by the engines that reference the raw-input library (WebView, CefSharp, Aurora). The pure-media GIF/Video engines (MpvPlayer, VlcPlayer, Nebula, Vexana, Xavier) are non-interactive renderers.
• Hardware acceleration, the stretch mode (default UniformToFill), looping, shuffling, and the static background-image fallback apply across engines — see Performance Rules and Customizing Wallpaper.

Which type should I use?

Goal	Recommended type
A quick animated background from a GIF	Gif
A looping cinematic clip with the lowest overhead	Video (MpvPlayer)
An interactive, audio-reactive, or system-monitoring scene	Web
Mirror an existing website live	Url
Play a music video or relaxing playlist	YouTube
Run a real screensaver, game, or app as the desktop	Application

If your goal is audio reactivity or showing system stats (CPU, RAM, network) on the desktop, you must use the Web type — that is the only type wired to Sucrose's JavaScript data bridge.

Where the type is stored

The type lives in the wallpaper's SucroseInfo.json manifest as the Type integer (0–5). The wallpaper itself is a plain folder inside your library location — there is no special archive extension for an unpacked theme. For the full package format, the folder layout, and every manifest field, see Create Package Format and Create Overview.

See also

• Choosing Engines — change the engine used for each type
• Engines Overview — the eight render engines explained
• Create Overview — author your own wallpapers
• Managing Library — import, apply, and organize wallpapers
• Customizing Wallpaper — per-engine adjustment panels