dsh-live-wallpaper

Readme

# DSH Live Wallpaper

[中文](#中文) | [English](#english)

## 中文

为 DeepSeek Harness Web UI 提供动态壁纸与页面主题中心。插件不依赖 Steam、Wallpaper Engine 或额外 npm 依赖；无 App Key 时直接使用 ShaderToy 官方播放器，配置 App Key 后可获取源码并在浏览器 WebGL2 中本地渲染。

当前兼容基线为 DeepSeek Harness `0.1.2-rc.1` 的 `dsh web` 浏览器界面。

`0.3.2` 修复 Windows 文件关联缺失导致本地 MP4/WebM/图片被拒绝的问题，并在恢复缓存 ShaderToy 源码时处理 WebGL2 不可用的情况。CI 覆盖 Windows/Linux、Node.js 22/24 和 Chromium 浏览器。插件支持范围为 Web UI；原生桌面客户端的 `file://`/IPC 加载方式不在此声明范围内。

### 功能

- 四款离线程序化动态壁纸：极光、星云、落日流光、霓虹网格
- 粘贴 ShaderToy ID 或官方链接即可应用；App Key 可选
- 未配置 App Key 时使用官方 Embed，配置后优先本地渲染 `Common + Image` 源码
- 应用 HTTP(S) 视频、图片或网页 URL
- 临时应用本地视频、GIF 和图片
- 调整背景暗度、模糊、界面遮罩透明度和视频速度
- 5 套页面主题预设，并可分别自定义主题底色、强调色和按钮颜色
- 圆角、胶囊、直角、玻璃和 DSH 原生共 5 种按钮形态
- 系统无衬线、圆体、衬线、等宽共 4 种字体风格，以及 90%–115% 字号缩放
- 壁纸与主题可独立开关；关闭主题或卸载插件后自动恢复 DSH 原生外观
- 页面隐藏、系统开启“减少动态效果”时自动暂停可暂停的动画
- 除本地文件和标签页捕获外，配置、ShaderToy ID 与已获取源码保存在浏览器 localStorage 中

### 本地安装

```sh
dsh plugin --profile web add ./dsh-live-wallpaper
dsh --profile web --dump-config
dsh web
```

打开 DSH 后，点击右下角的圆形壁纸按钮。

### 从 GitHub 安装

```sh
dsh plugin --profile web add github:hinayoung23/dsh-live-wallpaper#v0.3.2
```

### 从 npm 安装

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

### 素材使用方法

最简单、最稳定的方式是直接使用面板中的四款“内置动态”，它们不需要访问任何外部网站。

使用下载的视频：

1. 在插件面板的“下载壁纸素材”中打开 Pexels 或 Pixabay。
2. 在网站中选择作品并下载 MP4/WebM 文件，不要复制作品详情页地址。
3. 回到插件面板，在“本地文件”中点击“选择视频、GIF 或图片”。

使用 ShaderToy：

1. 粘贴作品 ID（例如 `XXcyRn`）或完整官方链接，点击“应用”；无需 App Key。
2. 未配置 App Key 时，插件直接嵌入 ShaderToy 官方播放器并保存 ID；刷新或重启 DSH 后会自动恢复。
3. 如需本地源码渲染，展开“App Key（可选）/ 高级兼容”，从 [ShaderToy Apps](https://www.shadertoy.com/myapps) 取得 App Key 并保存。之后插件会优先获取 `Common + Image` 源码并在本地 WebGL2 中编译。
4. 源码通道或本地编译不兼容时，插件会自动退回官方播放器；标签页捕获仍保留为高级兼容方式。

“视频 / 图片 URL”要求媒体直链，即在浏览器中打开后直接显示视频或图片；Pexels、Pixabay 等素材详情页不能作为媒体直链使用。

### 来源与安全

- ShaderToy App Key 存放在 DSH 凭据服务中；浏览器只能查询配置状态，无法读回明文。
- Host 接口只接受同源 JSON 请求，并只访问固定的 ShaderToy 官方 API，不是通用网络代理。
- 插件仅获取作者允许通过官方 API 访问的源码，不抓取网页或绕过 Cloudflare 和作品访问控制。
- 仅固定的 ShaderToy 官方 Embed 使用 `allow-same-origin`；用户自定义远程网页仍在更严格的 sandbox iframe 中运行。壁纸层默认不接收鼠标事件。
- 插件不会抓取、代理或绕过任何第三方壁纸市场的访问控制。
- 使用第三方视频、图片或 Shader 前，请确认其授权允许你的使用方式。

### 已知限制

- 浏览器不能在刷新后重新取得本地文件权限，因此本地文件壁纸仅在当前页面生命周期内有效。
- 无 App Key 模式需要持续联网，并依赖 ShaderToy 官方 Embed 可用且作品允许嵌入。
- 远程服务器可能禁止跨站嵌入或热链；这时请下载文件后通过“本地文件”使用。
- 当前本地渲染支持一个 `Image` 通道、可选一个 `Common` 通道且不含外部输入；Buffer A–D、纹理、音频、摄像头和立方体贴图会自动退回官方播放器。
- ShaderToy 官方 API 只返回作者标记为可通过 API 访问的作品；其他可嵌入作品会自动使用官方播放器。
- 本地 ShaderToy 渲染需要 WebGL2。高级标签页捕获仅在当前页面生命周期内有效，并可能要求浏览器的屏幕录制权限。
- 本地视频能否解码取决于浏览器和系统编解码器；建议 H.264 MP4 或 VP8/VP9 WebM。内置动画暂停时请检查系统“动画效果”及插件“尊重减少动态效果”选项。标签页捕获需要 HTTPS 或 localhost 安全上下文。

### 开发验证

```sh
pnpm check
pnpm exec playwright install chromium
pnpm test:browser
pnpm pack
```

### 许可证

MIT

## English

DSH Live Wallpaper adds animated wallpapers and a page theme center to the DeepSeek Harness Web UI. It requires neither Steam, Wallpaper Engine, nor additional npm dependencies. Without an App Key it uses the official ShaderToy player; with an App Key it can fetch source through the local DSH Host and render it with WebGL2.

The current compatibility baseline is the `dsh web` browser UI in DeepSeek Harness `0.1.2-rc.1`.

Version `0.3.2` accepts local MP4/WebM/images when Windows file associations supply an empty or generic MIME type, and falls back to the official player when cached shader source cannot use WebGL2. CI covers Windows/Linux, Node.js 22/24, and Chromium. The supported surface is the Web UI; native desktop `file://`/IPC loading is outside this declaration.

### Features

- Four offline procedural animated wallpapers: Aurora, Nebula, Sunset Flow, and Neon Grid
- Paste a ShaderToy ID or official URL and apply it with no App Key required
- Use the official Embed without a key, or optionally fetch and locally render `Common + Image` source with a key
- Use HTTP(S) video, image, or web page URLs as wallpapers
- Temporarily apply local videos, GIFs, and images
- Adjust background dimming, blur, UI overlay opacity, and video playback speed
- Five page theme presets, with independent customization of the base, accent, and button colors
- Five button styles: rounded, pill, square, glass, and native DSH
- Four font styles—system sans-serif, rounded, serif, and monospace—with 90%–115% font scaling
- Enable wallpapers and themes independently; disabling the theme or uninstalling the plugin restores the native DSH appearance
- Automatically pause supported animations when the page is hidden or the system requests reduced motion
- Store configuration, ShaderToy IDs, and fetched source in browser `localStorage`, except for local files and tab captures

### Local Installation

```sh
dsh plugin --profile web add ./dsh-live-wallpaper
dsh --profile web --dump-config
dsh web
```

After opening DSH, click the round wallpaper button in the lower-right corner.

### Install from GitHub

```sh
dsh plugin --profile web add github:hinayoung23/dsh-live-wallpaper#v0.3.2
```

### Install from npm

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

### How to Use Wallpaper Sources

The easiest and most reliable option is to use one of the four Built-in Animation presets. They do not require access to any external website.

To use a downloaded video:

1. Open Pexels or Pixabay from the Download Wallpaper Media section in the plugin panel.
2. Choose a video and download its MP4/WebM file. Do not copy the asset detail page URL.
3. Return to the plugin panel and click Choose Video, GIF, or Image under Local File.

To use ShaderToy:

1. Paste a work ID such as `XXcyRn`, or a complete official URL, then click Apply. No App Key is required.
2. Without a key, the plugin embeds the official ShaderToy player and saves the ID so the wallpaper restores after a refresh or DSH restart.
3. For local source rendering, expand App Key (Optional) / Advanced Compatibility, obtain a key from [ShaderToy Apps](https://www.shadertoy.com/myapps), and save it. Future applications prefer fetching and compiling `Common + Image` source locally with WebGL2.
4. If the source passes or local compilation are incompatible, the plugin automatically falls back to the official player. Tab capture remains available as an advanced compatibility option.

The Video / Image URL field requires a direct media URL—one that opens the video or image itself in a browser. Pexels and Pixabay asset detail pages are not direct media URLs.

### Sources and Security

- The ShaderToy App Key is stored by the DSH credential service. The browser can query its configuration status but cannot read the saved plaintext value.
- The Host endpoint accepts same-origin JSON requests only and targets the fixed official ShaderToy API; it is not a general network proxy.
- The plugin only fetches source that authors allow through the official API. It does not scrape pages or bypass Cloudflare or work access controls.
- Only the fixed official ShaderToy Embed receives `allow-same-origin`; user-supplied remote pages remain in a stricter sandboxed iframe. The wallpaper layer does not receive pointer events by default.
- The plugin does not scrape, proxy, or bypass access controls for any third-party wallpaper marketplace.
- Before using third-party videos, images, or shaders, confirm that their licenses permit your intended use.

### Known Limitations

- Browsers cannot recover local file permissions after a page reload, so local-file wallpapers remain available only for the current page lifecycle.
- Keyless mode requires a network connection and depends on the official ShaderToy Embed being available and allowed for the work.
- Remote servers may block cross-origin embedding or hotlinking. In that case, download the file and use the Local File option.
- Local rendering currently supports one `Image` pass, an optional `Common` pass, and no external inputs. Buffer A–D, textures, audio, webcam, and cubemaps automatically fall back to the official player.
- The official ShaderToy API only returns works whose authors allow API access. Other embeddable works automatically use the official player.
- Local ShaderToy rendering requires WebGL2. Advanced tab capture lasts only for the current page lifecycle and may require Screen Recording permission.
- Video decoding depends on browser and OS codecs; prefer H.264 MP4 or VP8/VP9 WebM. If built-in animations are paused, check OS animation settings and the plugin's reduced-motion option. Tab capture requires HTTPS or localhost.

### Development Verification

```sh
pnpm check
pnpm exec playwright install chromium
pnpm test:browser
pnpm pack
```

### License

MIT