# dsh-wallpaper-engine for DSH: Real-Time Local Wallpapers

> dsh-wallpaper-engine places local Wallpaper Engine scenes, webpages, videos, and uploaded media behind a DSH conversation. It supports WebGL rendering, fallback images and videos, appearance presets, and host-side settings without adding agent tools or prompt tokens.

**elysia395/dsh-wallpaper-engine** — 把本机 Wallpaper Engine 的壁纸搬进 DSH 网页界面：场景壁纸由内置 MIT 开源引擎 WebWallGL 实时 WebGL 渲染（粒子 / puppet 骨骼 / SceneScript / 音频反应 / 鼠标交互），失败自动降级内嵌 MP4 与场景静态帧；Web 壁纸严格沙箱 + WE API；iOS 风格液态玻璃 UI 高度自定义，遮挡暂停省电、ffmpeg 帧率上限转码、系统音频频谱与 Now Playing、自定义上传与自动轮播；设置存宿主端，对 agent 零 token 开销。Windows / macOS / Linux 三平台原生（同一个包、同一条命令）。

- Repository: https://github.com/elysia395/dsh-wallpaper-engine
- Stars: 2,488 · Forks: 77
- Language: JavaScript
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/elysia395-dsh-wallpaper-engine

## Why dsh-wallpaper-engine Belongs Inside DSH

dsh-wallpaper-engine addresses the gap between a local Wallpaper Engine collection and the DSH web interface. Its target user already has Scene, Web, or Video projects on the same computer, or wants to upload local JPG, PNG, and MP4 media. The plugin places those assets behind a DSH conversation and supplies the associated playback and appearance controls. Scene projects do not require Wallpaper Engine to remain running because rendering is handled by the plugin.

This is not a general desktop wallpaper replacement. Its visual layer belongs to the DSH host and is configured through the host interface. Application wallpapers are excluded because they require a third-party executable. This restriction also keeps them out of the wallpaper library and automatic rotation. On macOS, where Wallpaper Engine has no official client, users can upload media or point the custom wallpaper storage setting at a directory containing compatible projects.

A useful design choice is the separation between appearance and agent behavior. The plugin does not register tools with the agent or inject prompt text. It stores settings on the host side, so wallpaper selection and visual behavior remain outside the model context. As the README explains, the plugin adds no model token cost. The result is a host UI integration rather than an agent capability. Its usefulness therefore depends on DSH plugin compatibility, browser rendering, local media access, and the quality and structure of the existing wallpaper collection.

## WebWallGL, Sandboxing, and Scene Fallbacks

Scene wallpapers use the bundled WebWallGL engine to render projects in the browser with WebGL. The README lists particles, puppet skeletons, SceneScript, mouse interaction, and audio response among its supported features. WebWallGL is a compatibility layer rather than a promise of perfect Wallpaper Engine emulation. Workshop projects use different resources and scripts, and the README explicitly states that each project cannot be expected to match Wallpaper Engine itself.

The rendering path has a defined fallback policy. If real-time rendering fails, the plugin can use a static frame and an embedded MP4 when suitable assets are available. During preparation of the first frame, an available preview image can occupy the wallpaper area. This design keeps the interface from remaining empty when a scene cannot start. The project assigns detailed renderer and fallback rules to `docs/HOW-IT-WORKS.md`; the README does not expose the exact format eligibility rule for each stage of that chain.

Web wallpapers take a different path. Their pages are mounted in the interface, receive Wallpaper Engine API injection, and run inside strict sandbox isolation. The resulting behavior depends on the webpage as well as browser capabilities. Video wallpapers are played directly by the browser, with frame-rate limits, playback speed, transcoding caches, transitions, and pause controls available around the media.

This architecture removes the need to launch Wallpaper Engine for scene rendering, but compatibility risk moves into the browser. WebGL support, media codecs, audio behavior, sandbox rules, scripts, and external assets can affect the result. A project being discovered by the library therefore does not guarantee that every scene effect will reproduce the desktop application's behavior.

## Installing dsh-wallpaper-engine in a DSH Host

The documented prerequisites are Node.js 18 or later and DSH `>=0.1.5-rc.1`. Desktop users can use the in-app plugin market. A browser or web host can add the package through the `web` profile:

```sh
dsh plugin --profile web add dsh-plugin-wallpaper-engine
```

After installation, restart `dsh web`. The README instructs users to restart the corresponding host after either installing or updating the plugin.

The DSH Desktop command uses a separate profile:

```sh
dsh plugin --profile desktop add dsh-plugin-wallpaper-engine
```

For desktop installations, fully exit the application and open it again. A browser refresh alone is not sufficient. This distinction matters because the desktop host must reload the plugin state after the package changes.

For the first wallpaper selection, open `设置 → Wallpaper Engine → 壁纸库` after restarting the host and choose an available wallpaper. The README also documents a second route through the mascot cord above the chat. Pulling it down opens the `壁纸仓库` drawer. If installation produces an error such as `ERR_PNPM_UNEXPECTED_VIRTUAL_STORE`, the README directs users to `docs/TROUBLESHOOTING.md` for the relevant handling instructions.

## Media Sources, Rotation, and Playback Controls

The wallpaper library recognizes Wallpaper Engine projects and accepts local JPG, PNG, and MP4 uploads. Uploaded media remains on the local machine. Hiding an item changes the library listing without deleting its source file, while clearing the current wallpaper does not remove the original media. These separate controls matter for users who organize a shared library but need to preserve local assets.

Automatic rotation requires at least two playable wallpaper candidates. A rotation list can define the interval and either ordered or random playback. The next wallpaper is prepared before the visible handoff. If preparation fails, the candidate is skipped and the sequence continues. Available transitions include hard cuts, fades, and pushes. When the system requests reduced motion, the plugin uses a hard cut.

Playback settings address resource use for browser-rendered scenes and video. The README documents frame-rate limits, transcoding caches, playback speed, horizontal flipping, and transition selection. Occlusion detection can pause rendering when the DSH window is covered. Users can also select or migrate cache locations when the default path is unsuitable.

System-audio features include an output loop spectrum, Now Playing information, cover art, and optional online lyrics. Windows obtains media information through GSMTC, macOS uses MediaRemote, and Linux uses MPRIS. These integrations expose different capabilities at the operating-system level. The README does not document permission handling for every media service, nor does it guarantee identical audio support across the three platforms.

## Liquid Glass Presets and Host-Side Settings

The plugin applies a liquid-glass appearance across DSH settings, conversations, and the sidebar. Its controls cover color, opacity, blur, borders, and independent sidebar parameters. Glass on the settings window is always enabled. The README documents no global switch that restores the native solid-color treatment, so users who want a fully native interface may regard this as a limitation.

Appearance presets store a configuration snapshot. According to the README, presets can carry fonts, mascot artwork, and avatars, and they support JSON export, import, and sharing. Typography controls include system fonts, terminal fonts, font sets, color roles, layout roles, and the caret. Version `v1.3.2` added one-click presets along with choices for corner rounding and cache paths.

Optional extensions can add session avatars, click or trail effects, and wallpaper-to-interface parallax. These features can be disabled when they are not wanted. Settings remain on the host side, which avoids adding wallpaper instructions to the agent context.

Web wallpapers deserve careful review because they introduce page content, script execution, and API injection. The README states that strict sandbox isolation is applied, but it does not document the precise origin policy, storage permissions, network rules, or audit interface. The implementation and `docs/HOW-IT-WORKS.md` are the relevant places to verify those boundaries before using untrusted workshop projects.

## Compatibility, MIT Licensing, and Upgrade Cost

The package version is `1.3.3`, its main entry is `lib/index.js`, and its declared requirements are Node.js `>=18` and DSH `>=0.1.5-rc.1`. Windows, macOS, and Linux use the same npm package. Platform differences concern system-media access and the availability of Wallpaper Engine project files rather than separate installation packages.

Application wallpaper support is the clearest adoption boundary. Scene compatibility is conditional because WebWallGL, browser sandboxing, codecs, and available assets all affect execution. The README does not publish a browser compatibility matrix or a definitive list of compatible workshop projects. It also warns that Scene projects can differ from Wallpaper Engine itself. Web wallpapers carry a separate risk because their appearance depends on the embedded page and browser environment.

The repository is distributed under the MIT License. That is the license declared for the plugin code, but it does not resolve rights for imported wallpaper artwork, music, fonts, scripts, or third-party assets. Users need to examine the respective terms for the content they distribute.

The repository is not archived. Its last push was on 2026-10-15, and `v1.3.3` was released on 2026-10-15. Updating still has operational costs because the host must restart, and desktop applications must be fully reopened. The npm declaration and `docs/UPGRADING.md` govern compatibility. Historical desktop plugin versions and DSH kernel versions are separate numbering systems. A sensible adoption check is to verify those versions first, then exercise one Scene wallpaper through both its live and fallback paths, one sandboxed Web wallpaper, and one Video wallpaper.

## Conclusion

Adopt dsh-wallpaper-engine if you keep Scene, Web, or Video projects on the same machine and want them inside DSH without Wallpaper Engine running. Do not expect Application wallpapers to work, or assume every workshop project will match Wallpaper Engine itself. Before adoption, verify your DSH kernel and Node.js versions, locate your Wallpaper Engine project directories, and confirm that the required scene, webpage, audio, and fallback assets render in your browser environment.

## FAQ

### Does dsh-wallpaper-engine require Wallpaper Engine to keep running?

No. Scene wallpapers are rendered by the bundled WebWallGL engine, and the README states that Wallpaper Engine does not need to run in the background. Existing project files are still required to display that content.

### Which Wallpaper Engine wallpaper types does dsh-wallpaper-engine support?

It supports Scene, Web, and Video wallpapers, plus uploaded JPG, PNG, and MP4 files. Application wallpapers are unsupported because they require launching a third-party executable.

### What happens when a Scene wallpaper cannot render in real time?

The documented fallback chain uses a static frame and, where suitable, an embedded MP4. An available preview image can also appear while the first frame is being prepared.

### What are the installation requirements for dsh-wallpaper-engine?

The package requires Node.js 18 or later and DSH `>=0.1.5-rc.1`. Web and desktop hosts use different CLI profiles, and the corresponding host must be restarted after installation or updating.

### Does using dsh-wallpaper-engine increase agent token usage?

No. The README states that the plugin registers no agent tools and injects no prompt text, so it adds no model token cost.

### Will every Wallpaper Engine workshop project look identical inside DSH?

No. The plugin uses WebGL rendering and sandboxed web execution, while workshop projects rely on varied resources and scripts. The README does not guarantee exact consistency with Wallpaper Engine itself.

## Sources

- [elysia395/dsh-wallpaper-engine on GitHub](https://github.com/elysia395/dsh-wallpaper-engine)
- [Issues](https://github.com/elysia395/dsh-wallpaper-engine/issues)
- [License: MIT](https://github.com/elysia395/dsh-wallpaper-engine/blob/main/LICENSE)
- [README](https://github.com/elysia395/dsh-wallpaper-engine/blob/main/README.md)
- [Releases](https://github.com/elysia395/dsh-wallpaper-engine/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/elysia395-dsh-wallpaper-engine