Managing Library

Managing the Library

The Library is the Portal page that lists every wallpaper installed on your machine. From here you apply a wallpaper, customize it, edit its package, share it, report it, delete it, or add/remove it from the cycling rotation. This page explains where library wallpapers come from (drag-and-drop import, the Showcase samples, and Store installs), every command on a library card, how Sucrose handles incompatible or corrupt entries, and what happens to the live engine when you switch wallpapers.

Contents

• Where the library lives
• Opening the Library
• How wallpapers get into the library
• The Showcase auto-import
• The library card context menu
• Incompatible and corrupt wallpapers
• Sorting, paging and previews
• Engine restart on Use
• See also

---

Where the library lives

By default the library folder is %AppData%\Sucrose\Library. You can move it from Settings → General → Private Library (key Location, file Library.json); when Move library files (Move, default true) is enabled, changing the location moves the existing files into the new (empty) target folder.

Every installed wallpaper is a sub-folder that contains a valid SucroseInfo.json (Sucrose.info) plus the assets it references (Thumbnail, Preview, Source). A folder that lacks a readable SucroseInfo.json or whose Thumbnail/Preview/Source files are missing is treated as invalid and skipped (and optionally deleted — see below).

📷 Screenshot needed: Portal → Library page showing a grid of installed wallpaper cards.

Opening the Library

The Library is the first item in the top navigation (menu item General1, icon Library16). The Store is its sibling (General2, icon Gift16). The footer toolbar (Create Wallpaper, Wallpaper Cycling, Display Preferences, theme toggle, Help/About) is visible while you are on the Library or Store. See Portal Interface Tour for the full window walkthrough.

How wallpapers get into the library

There are three ways a wallpaper lands in your library: Store installs, drag-and-drop import, and the Showcase auto-import.

Drag-and-drop import

Drop files onto the Library page and Sucrose decides what to do based on what you dropped:

Dropped item	What happens
.zip archive	Validated by Zip.Helper.Archive.Check, then extracted into a new random 25-character folder under the library.
.url shortcut	The URL= line is parsed and the Create Wallpaper dialog opens pre-filled with that URL.
A gif / video / web / app file	The Create Wallpaper dialog opens with the file path supplied as InitialFilePath.
Plain text that is a URL	The Create Wallpaper dialog opens with that URL as InitialUrl.

Import results are reported through the ThemeImport dialog. The .zip import path is the same package contract used by the Store and by sharing — see Create: Sharing & Publishing and Create: Package Format.

Store installs

Wallpapers downloaded from the in-app Store are copied into the library as a new random 25-character folder, and an empty marker file SucroseStore.json is written into that folder to flag the wallpaper as Store-sourced (which prevents it from being re-published). See Using the Store.

The Showcase auto-import

So that a fresh install never shows an empty library, Sucrose ships sample wallpapers in %AppData%\Sucrose\Showcase. On first load these samples are copied into the library and tracked in the Showcase list inside Warehouse.json, so they are only imported once. The shipped examples (Neo Matrix, Fluid Simulation, Simple System, Music Tunnel, Living Room, Ray Music Visualizer, and others) double as reference material for creators — see Create: Example Wallpapers.

The library card context menu

Each wallpaper is rendered as a LibraryCard. Right-click (or open the card menu) for these commands:

Command	Localization key	What it does
Use	MenuUse	Sets this wallpaper as the active one (Selected in Library.json) and restarts the live engine. Disabled if it is already the selected, running wallpaper, or if it is Incompatible (requires a newer app version).
Customize	MenuCustomize	Opens the wallpaper's property UI through the Property service (Commandog PropertyA, i.e. Sucrose.Property). Enabled only for Web wallpapers that declare properties, or for Gif/Video/YouTube whose selected engine supports a property panel (MpvPlayer / CefSharp / WebView per type). See Customizing a Wallpaper.
Find	MenuFind	Opens the wallpaper's folder in File Explorer.
Edit	ThemeEdit	Re-opens the package metadata for editing.
Share	ThemeShare	Exports the wallpaper to a .zip or publishes it to the Store. See Create: Sharing & Publishing.
Review	ThemeReview	Opens the review dialog for the wallpaper.
Delete	ThemeDelete	Removes the wallpaper from the library.
Cycling add / remove	—	Adds or removes this wallpaper from the cycling Exclusion list in Cycling.json. See Wallpaper Cycling.

Engine paused or closed? When the Backgroundog performance service has Closed or Paused the engine (for example because the workstation is locked or a fullscreen app is running), Use, Delete and Customize are disabled and the card shows a status suffix. The wallpaper resumes according to your performance rules.

📷 Screenshot needed: LibraryCard right-click context menu open over a wallpaper.

Incompatible and corrupt wallpapers

• Incompatible — every package declares an AppVersion. If a wallpaper's AppVersion is newer than your installed Sucrose version, the card is marked Incompatible and Use is disabled until you update the app. See Updating Sucrose.
• Corrupt / incomplete — a library entry without a valid SucroseInfo.json (or with missing Preview/Thumbnail/Source) is skipped during the library scan. If Settings → Personal → Delete corrupt (DeleteCorrupt, default false) is enabled, such entries are deleted automatically on load instead of merely hidden.
• Delete confirm — Settings → Personal → Delete confirm (DeleteConfirm, default true) controls whether a confirmation dialog appears before you delete a wallpaper.

Sorting, paging and previews

These are all on Settings → Personal:

Setting	Key	Default	Range / options
Sort mode	LibrarySortMode	Creation	Name, Creation, Modification
Sort kind	LibrarySortKind	Descending	Ascending, Descending
Library pagination	LibraryPagination	30	1–100 items per page
Library hover preview	LibraryPreview	false	animated preview on hover
Library preview hide	LibraryPreviewHide	false	hide static preview during live preview
Grid item margin	AdaptiveMargin	5	5–25
Max items per row	AdaptiveLayout	0	0–100 (0 = auto)

The footer search box (max 20 characters, 500 ms debounce) filters library cards by word match. See Settings: Personal for the full list.

Engine restart on Use

Choosing Use writes the new selection to Library.json and restarts the live wallpaper engine: the previous engine process is stopped (Kill.Stop()) and the new one is launched (Run.Start()) via the Commandog dispatcher, which picks the correct Sucrose.Live.<engine>.exe for the wallpaper's type. This is why applying a wallpaper briefly clears the desktop — it is a full engine swap, not an in-place reload. Which engine is launched depends on the wallpaper's type and your engine choice.

See also

• Using the Store
• Customizing a Wallpaper
• Wallpaper Cycling
• Wallpaper Types
• Choosing Engines
• Create: Sharing & Publishing
• Settings: Personal