wallpaper-engine

Typed host contracts, Vite tooling, runtime helpers, and a development simulator for Wallpaper Engine web wallpapers.

Documentation · Demo source · Repository

wallpaper-engine provides TypeScript types, Vite integration, and browser utilities for Wallpaper Engine web wallpapers. Define your properties once, use them in typed host callbacks, and preview changes in the browser before testing in Wallpaper Engine.

Features

• Typed host APIs for user properties, audio, media, files, and RGB integrations.
• Shared property schemas that generate project.json, infer callback values, and support native Font Awesome property icons through the optional icon field.
• Property layout with group markers and horizontal separators from dividerProperty().
• Browser devtools with property controls, audio and media simulation, and performance diagnostics. Float, dock, or open the panel in a separate window.
• Runtime helpers for colors, audio analysis and tempo estimation, media, files, and frame pacing.
• Build integration for project metadata, previews, and links to local Wallpaper Engine projects.

The published package has no runtime dependencies. The devtools client is bundled and included only during development.

Installation

bun add wallpaper-engine

For Vite integration, also install Vite:

bun add --dev vite

Follow the Quick Start to create a wallpaper with typed properties and the development simulator. The Installation guide covers TypeScript setup and other package managers.

Documentation and examples

Setup instructions, working examples, and API details live in the documentation.

Topic	Documentation
Working examples	Typed properties, audio, and media
Property definitions and typed callbacks	Property Schemas · Type Inference
Audio and media integration	Audio · Media
Development and production	Simulator · Build and Workshop workflow
Public API and host coverage	API Reference · Web API Coverage

The Vue demo combines these features in a complete consumer application. The package can also be used with vanilla TypeScript and other browser frameworks.

Package entry points

Import	Use
wallpaper-engine	Host types, typed listeners, and browser-global declarations
wallpaper-engine/plugin	Vite plugin, property builders, and project generation
wallpaper-engine/helpers	Tree-shakeable browser utilities

Vite is an optional peer dependency used only by the plugin entry point. Register host listeners immediately during module evaluation, and test the finished wallpaper in Wallpaper Engine; the simulator covers development workflows rather than every native host behavior.

WallpaperPropertyListenerOf<typeof properties> includes built-in properties such as schemecolor, audioprocessing, and the wec_* color controls. Import DefaultWEProps from wallpaper-engine/helpers for their fallback definitions and default values; the matching definition type is exported from wallpaper-engine. Every callback key remains optional. Devtools includes the built-ins and omits audioprocessing when supportsAudioProcessing: false is configured.

Hardware APIs are optional until their plugins load. Wait for wallpaperPluginListener.onPluginLoaded, then guard window.wpPlugins?.led or window.cue before using them.

Development

Run workspace commands from the repository root with Bun:

bun install
bun run build
bun run dev:demo

Use bun run dev:docs to work on the documentation. Before submitting changes, run bun run lint, bun run typecheck, and bun run test:run.

The root build bundles devtools before building the library. Build the documentation separately with bun run build:docs.

License

MIT