Recent changes to Wallpaper Types

Wallpaper Types modified by Bayram Emekli

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

--- v3
+++ v4
@@ -1,6 +1,6 @@
 # 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.
+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

@@ -18,8 +18,8 @@

 | Value | Type | What it is | `Source` field means | Page |
 |-------|------|-----------|----------------------|------|
-| `0` | **Gif** | An animated GIF file | local `.gif` file name inside the folder | [GIF Wallpapers](Type-Gif) |
-| `1` | **Url** | A remote web address shown as a single page | a remote `http`/`https` URL | [URL Wallpapers](Type-Url) |
+| `0` | **Gif** | An animated GIF file | local `.gif` file name inside the folder | [Gif Wallpapers](Type-Gif) |
+| `1` | **Url** | A remote web address shown as a single page | a remote `http`/`https` URL | [Url Wallpapers](Type-Url) |
 | `2` | **Web** | An interactive local HTML/CSS/JS theme | local entry HTML/web file name inside the folder | [Web Wallpapers](Type-Web) |
 | `3` | **Video** | A local video file | local video file name inside the folder | [Video Wallpapers](Type-Video) |
 | `4` | **YouTube** | A YouTube video or playlist | a YouTube video or playlist URL | [YouTube Wallpapers](Type-YouTube) |

Wallpaper Types modified by Bayram Emekli

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

--- v2
+++ v3
@@ -1,6 +1,6 @@
 # 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 **seven 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.
+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

@@ -36,6 +36,8 @@
         Video --> Neb["Nebula"]
         Video --> WV
         Video --> Cef

+        Gif --> Vlc["VlcPlayer"]
+        Video --> Vlc
         Url["Url (1)"] --> WV
         Url --> Cef
         Web["Web (2)"] --> WV
@@ -63,10 +65,10 @@

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

@@ -90,7 +92,7 @@
 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](Create-Audio-API), [System API](Create-System-API), and [Web Architecture](Create-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, Nebula, Vexana, Xavier) are non-interactive renderers.
+- **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](Performance-Rules) and [Customizing Wallpaper](Customizing-Wallpaper).

 ## Which type should I use?
@@ -113,7 +115,7 @@
 ## See also


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

Wallpaper Types modified by Bayram Emekli

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

--- v1
+++ v2
@@ -25,7 +25,26 @@
 | `4` | **YouTube** | A YouTube video or playlist | a YouTube video or playlist URL | [YouTube Wallpapers](Type-YouTube) |
 | `5` | **Application** | An external program/game run as the wallpaper | local executable file name inside the folder | [Application Wallpapers](Type-Application) |

-> 🖼️ **Diagram needed:** A 6-box row of the wallpaper types (Gif, Url, Web, Video, YouTube, Application) each with a representative icon, fanning out to the engines that can render them.

+    :::mermaid
+    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
+        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

Wallpaper Types modified by Bayram Emekli

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

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 seven 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.

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

🖼️ Diagram needed: A 6-box row of the wallpaper types (Gif, Url, Web, Video, YouTube, Application) each with a representative icon, fanning out to the engines that can render them.

How a type becomes a wallpaper

When you apply a wallpaper, Sucrose:

Reads the wallpaper's SucroseInfo.json and finds its Type.
Looks up which engine is currently selected for that type (a per-type setting you control in Settings → Wallpaper; see Choosing Engines).
Launches the matching engine executable (e.g. Sucrose.Live.MpvPlayer.exe) as a separate process via the Commandog dispatcher.
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
Url	CefSharp	WebView, CefSharp
Web	CefSharp	WebView, CefSharp
Video	MpvPlayer	Nebula, WebView, CefSharp, MpvPlayer
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, 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.