Type Application

Application Wallpapers

An Application wallpaper (type value 5, Application) runs a real external program — a game, a screensaver, a graphics demo, or any Windows app — as your live desktop background. Instead of rendering content, Sucrose's Aurora engine launches the actual executable and reparents its window behind your desktop icons, one instance per monitor. This is the most open-ended type: anything that opens a window can become a wallpaper. This page covers how it works, its arguments, and its limitations.

Contents

• What it is
• The Aurora engine
• Per-monitor embedding
• Arguments
• How to apply an application wallpaper
• Audio
• Limitations
• Tips
• See also

What it is

In the manifest, an Application wallpaper has "Type": 5 and a Source that names the local executable file inside the wallpaper folder (the executable's extension is validated against Sucrose's app-extension filter, e.g. .exe). When you create one, the entire containing folder is copied into the theme, so bundle the app and all its files together in a single self-contained directory.

The manifest may also carry an Arguments string (command-line arguments, up to 250 characters) passed to the program on launch.

The Aurora engine

Application is the only type rendered by Aurora (Sucrose.Live.Aurora.exe), and Aurora renders only Application. Aurora is not a media renderer — it is a process-embedding engine:

1. It resolves the executable path from Info.Source and records the app's process name.
2. It enumerates your monitors and launches one process instance per screen with the configured Arguments.
3. It waits until every instance is ready, then reparents/embeds each window behind the desktop.
4. A watcher timer monitors the child processes; if any instance exits (or its process is no longer running), Aurora closes (and the wallpaper ends).
5. On a display-settings change, Aurora re-applies the embedding to all instances.

On exit, Aurora kills the spawned application processes it launched, so the apps don't linger after you change wallpapers.

See Engine-Aurora for the full embedding internals.

flowchart TD
    Aurora["Sucrose.Live.Aurora.exe"] --> Resolve["resolve Source executable<br/>+ Arguments"]
    Resolve --> Enum["enumerate monitors"]
    Enum --> M1["launch app instance<br/>Monitor 1"]
    Enum --> M2["launch app instance<br/>Monitor 2"]
    Enum --> Mn["launch app instance<br/>Monitor N"]
    M1 --> R1["reparent window<br/>behind desktop icons"]
    M2 --> R2["reparent window<br/>behind desktop icons"]
    Mn --> Rn["reparent window<br/>behind desktop icons"]
    R1 --> Watch["watcher timer<br/>exit or hang closes wallpaper"]
    R2 --> Watch
    Rn --> Watch

Loading

Per-monitor embedding

Aurora launches and embeds one copy of the application per monitor. This means a three-monitor setup runs three instances of the program. Plan accordingly — a heavyweight game running three times will use roughly three times the resources. (Sucrose's multi-monitor layout options like span/duplicate are oriented at rendered content; Application wallpapers are embedded per display by Aurora. See Multi-Monitor.)

Arguments

The optional Arguments field (≤ 250 characters) lets you pass command-line switches to the program — for example to start a game in a particular mode, set a resolution, or point a demo at a config file. Arguments are entered in the Create dialog and stored in the manifest. They apply to every per-monitor instance.

How to apply an application wallpaper

1. Open the Portal → Library.
2. Use the Create dialog, choose the Application type, pick the executable, and (optionally) enter Arguments.
3. Right-click the card → Use. Aurora launches one instance per monitor and embeds each behind the desktop.

Audio

Aurora gives the embedded application volume control only — it does not inject Sucrose's audio-reactive or system-status data into the app. The app's own sound is managed through Sucrose's volume helper; everything else (the app's behavior, graphics, input handling) is the application's own.

Limitations

• Rejects URLs. Application is for local executables. If the Source looks like a URL, Aurora closes immediately — use Type-Url for web addresses.
• No live data API. The audio-reactive (SucroseAudioData) and system-status (Sucrose*Data) callbacks are exclusive to the local Web type; embedded apps do not receive them.
• One instance per monitor. Multi-monitor setups multiply the resource cost.
• Behavior is the app's. Whether the app fills the screen, accepts input, or behaves well when reparented depends entirely on the program. Apps that insist on their own top-level window, require elevation, or fight reparenting may not embed cleanly.
• Ends if the app exits. If the embedded process closes (its process is no longer running), Aurora shuts the wallpaper down.
• Resource-heavy. Running a real game or demo as a wallpaper can be the most demanding type; Sucrose's Performance Rules (especially the Heavy pause, which suspends the process) help mitigate this.

Tips

• Choose lightweight, fullscreen-friendly apps (graphics demos, screensavers, simple games).
• Keep the executable and its assets in one folder — the whole folder is copied on import.
• Use Arguments to force fullscreen/borderless and a fixed resolution where the app supports it.
• For multi-monitor machines, prefer an app that is cheap to run multiple times.

See also

• Wallpaper Types — all six types and the engine mapping
• Engine-Aurora — the process-embedding engine
• Multi-Monitor — per-display behavior
• Performance Rules — Heavy pause and automatic close behavior
• Create Step By Step — author an application wallpaper