Create Overview

Creating Wallpapers — Overview

Audience: wallpaper creators. This page is the entry point for authoring your own Sucrose wallpapers. It explains the mental model — a wallpaper is just a folder plus a JSON manifest — describes the six wallpaper types, the optional sibling files that add customization controls and live‑data hooks, and which render engines actually deliver the JavaScript bridge APIs. Read this first, then follow Create Step By Step to build one with the Portal.

Contents

• What a Sucrose wallpaper is
• The six wallpaper types
• Files inside a wallpaper folder
• Which engines deliver the JS bridge
• What you need to author each type
• The authoring path
• See also

What a Sucrose wallpaper is

A Sucrose wallpaper (internally called a "theme") is a plain folder that lives inside your Library location. There is no custom archive extension for the unpacked wallpaper — it sits on disk as an ordinary directory. The single required file in that directory is the manifest, SucroseInfo.json. Everything else (media files, HTML/JS/CSS, optional control and data‑hook manifests, thumbnail and preview images) lives alongside it in the same folder.

When you install or create a wallpaper, the folder name is a random 25‑character string, not the title — do not rely on the folder name to identify a wallpaper. The human‑readable title comes from the Title field inside SucroseInfo.json.

flowchart TB
    subgraph Folder["wallpaper folder (random 25-char id)"]
      Info["SucroseInfo.json — REQUIRED manifest"]:::req
      Props["SucroseProperties.json — optional controls"]
      Compat["SucroseCompatible.json — optional live-data hooks"]
      Store["SucroseStore.json — optional store metadata"]
      Thumb["Thumbnail + Preview images"]
      Lic["License.txt (optional)"]
      Src["source files: .gif / .html + js/css / video / .exe"]
    end
    classDef req fill:#2ecc71,stroke:#145a32,color:#000;

Loading

The six wallpaper types

Every wallpaper declares exactly one type via the integer Type field in SucroseInfo.json. The enum (WallpaperType) is serialized as a number — the integer value matters:

Type value	Type	What Source means
0	Gif	Local .gif file name inside the folder
1	Url	A remote http/https URL
2	Web	Local entry HTML/web file name inside the folder
3	Video	Local video file name inside the folder
4	YouTube	A YouTube video or playlist URL
5	Application	Local executable file name inside the folder

Each type is rendered by a separate Live engine process, and the type → engine mapping is configurable per type. See Wallpaper Types for the user‑facing overview and Engines Overview for how engines are selected and launched.

Files inside a wallpaper folder

File	Required?	Purpose
SucroseInfo.json	Required	The manifest: title, author, type, source, thumbnail/preview, tags, etc. See Create Package Format.
SucroseProperties.json	Optional	Defines the user‑adjustable controls Sucrose renders in the "Customize" panel and the JS callback used to push changes into the wallpaper. See Create Customization Controls.
SucroseCompatible.json	Optional	Opts the wallpaper into receiving live audio/system data and engine‑state changes via JS templates. See Create JS Bridge, Create Audio API, and Create System API.
SucroseStore.json	Optional	Store metadata (used by the publishing pipeline). See Create Sharing Publishing.
Thumbnail.jpg (or t_*.jpg)	Recommended	Small static preview image; its file name goes in the Thumbnail field.
Preview.gif (or p_*.gif)	Recommended	Animated preview; its file name goes in the Preview field.
License.txt	Optional	License text referenced by the License field.
<source files>	Depends on type	The actual .gif / .html + JS/CSS / video / .exe, etc.

The canonical file names are fixed constants in the codebase (SucroseInfo.json, SucroseStore.json, SucroseCompatible.json, SucroseProperties.json). Browser engines also generate internal HTML wrappers you do not author (GifContent.html, ImageContent.html, VideoContent.html, YouTubeContent.html), and MpvPlayer reads MpvPlayer.config plus an optional user override uMpvPlayer.config.

📷 Screenshot needed: A wallpaper folder open in File Explorer showing SucroseInfo.json, SucroseProperties.json, an HTML source file, and thumbnail/preview images.

Which engines deliver the JS bridge

The JavaScript bridge (the Audio API, the System API, the property listener, and engine‑state callbacks) is delivered only by the browser‑style engines — WebView (Microsoft Edge WebView2) and CefSharp (Chromium Embedded Framework). The bridge is therefore meaningful for the Web type (and for the built‑in HTML wrappers used by Gif/Video/YouTube), but not for native Application wallpapers rendered by Aurora, nor for pure media engines such as MpvPlayer, Nebula, Vexana, or Xavier.

In practice this means:

• Audio‑reactive and system‑status wallpapers must be authored as the Web type and run on WebView or CefSharp.
• A Web wallpaper that declares SystemAudio in SucroseCompatible.json causes the engine to enable the Backgroundog audio data channel and push FFT data to your JavaScript.

For the full delivery mechanism see Create Web Architecture; for engine capabilities see Engine Comparison.

What you need to author each type

Type	You provide	Notes
Gif	A .gif file	Rendered via the built‑in GifContent.html wrapper when run on a browser engine, so it gets play/pause/filter properties.
Url	An http/https URL	The whole site is shown; you ship no local files. See Type Url.
Web	An HTML entry file + its JS/CSS/assets folder	The entire containing folder is copied in. This is the only type that receives the full JS bridge. See Type Web.
Video	A video file	Accepted extensions are validated; see Create Step By Step.
YouTube	A YouTube/YouTube‑Music video or playlist URL	Rendered via the built‑in YouTubeContent.html (YouTube IFrame API).
Application	An executable (whole folder copied) + optional Arguments	Launched as a native process per monitor by Aurora. No JS bridge. See Type Application.

The authoring path

The canonical way to create a wallpaper is the Portal "Create" dialog, which collects the required fields, validates them, copies your source files into a new folder, and writes SucroseInfo.json for you. You can then add SucroseProperties.json and SucroseCompatible.json by hand (or with a text editor) to enable customization controls and live data. Real, fully‑worked examples ship with Sucrose under the Showcase library — study them in Create Example Wallpapers.

Recommended reading order for creators:

1. Create Step By Step — build a wallpaper with the Portal dialog.
2. Create Package Format — the full SucroseInfo.json reference.
3. Create Customization Controls — add sliders/checkboxes/etc.
4. Create JS Bridge, Create Audio API, Create System API — live data.
5. Create Property Listener Filters — built‑in filters and playback wrappers.
6. Create Compatibility — porting from Lively / Wallpaper Engine.
7. Create Sharing Publishing — export and publish.

See also

• Create Step By Step
• Create Package Format
• Create Web Architecture
• Wallpaper Types
• Engines Overview