wallpaper-engine-dsh

English | 中文

一个 DSH bundle:把本机 Wallpaper Engine 壁纸库变成 DSH web GUI(dsh web)的动态背景。视频壁纸在聊天界面背后播放,网页壁纸直接渲染。交叉淡入、液态玻璃面板、随壁纸自适应的可读性遮罩、手动取景、轮播列表、搜索与中英双语界面,全部集中在一个设置行里。

功能

只列出能真实播放的壁纸。 网格中列出浏览器可以真实渲染的全部类型——视频与网页壁纸。场景/应用壁纸是 Wallpaper Engine 私有的 .pkg 场景包,浏览器无法执行,因此直接过滤,不以降级的静态图代替。列出的每张壁纸都真实播放,并按 视频/网页 标注类型;搜索框可按标题或创意工坊 ID 筛选较大的壁纸库。

任何壁纸上文字都可读。 遮罩颜色始终与文字颜色相反:深色主题用黑色遮罩,浅色主题用白色遮罩,因此过亮或过暗的壁纸都不会盖住文字。在此基础上,「智能可视」每隔几秒采样一次壁纸亮度,亮度过高或过低时自动加强遮罩(网页壁纸的像素在沙箱中读不到,改用其预览图作为采样依据)。下拉菜单、弹窗等浮层显示在 DSH 原生的不透明表面上,不受影响。

手动取景。 先选基础排布(填充、适应、拉伸、原始、自由),再手动调整画面:点「调整画面」将壁纸全屏展开,滚轮缩放,拖动平移。前四种排布下裁剪范围经过限制,画面始终铺满屏幕,不露出边缘;「自由」把壁纸按原始大小放在黑色画布上,可拖动到任意位置,缩放范围 0.1–4×,并可旋转任意角度(±90° 按钮或 Alt+拖动),同时始终保留一小块在屏幕内,不会拖丢。「镜像」水平翻转壁纸,所有排布下都可用——翻转不会破坏铺满。按 Esc 或点「完成」退出,取景设置会保存,「重置裁剪」可一键恢复默认。网页壁纸使用相同的排布下拉与缩放/平移/旋转取景(变换直接作用于 iframe)。

四个实时滑杆。 壁纸模糊、暗化、边框、玻璃,每一步调节立即生效并保存。模糊在原位渲染:任意模糊度下,画面的比例、排布与取景完全一致;屏幕边缘一个模糊半径内的画面向遮罩过渡,被界面边饰覆盖,通常不可见。模糊时叠加轻微噪声,消除渐变色带;模糊为零时媒体完全绕过滤镜管线,像素保持不变。

轮播列表。 可以创建任意多个列表,各自指定壁纸集合、切换间隔(1–120 分钟)与顺序(顺序/随机)。当前列表至少有两张可用壁纸时才会自动轮转;状态行始终显示轮转是否正在运行。首次运行会自动导入第一个可播放的 Wallpaper Engine 播放列表,其他播放列表也可随时导入到任意列表。

资源监控。 实时帧率读数与低帧率提示,页面隐藏或电量不足时可选自动暂停。系统开启 prefers-reduced-motion 时视频默认暂停。

中英双语。 界面跟随 DSH 的「语言」设置(中/英),也可在面板中手动指定。

播放出错自动恢复。 切换与关闭均以淡入淡出过渡。媒体连续解码失败时,先使用新令牌重试一次;仍失败则改用预览图,并在状态行说明;没有预览可用的条目则清空选择,避免黑屏。下次「刷新」会重新尝试原媒体。刷新会更新全部 URL,并直接替换正在播放的元素的地址,播放进度保留。后台重建清单时复用相同 URL,不会中断正在播放的流。

安装

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

或从源码检出安装(便于开发,改动即时生效):

git clone https://github.com/Weilv-D/wallpaper-engine-dsh.git
dsh plugin --profile web add link:<克隆文件夹的绝对路径>

重启 dsh web,打开 设置 → 通用 → 壁纸背景 (Wallpaper Engine)。

使用

1. 从缩略图网格选择壁纸,它会在界面背后淡入。壁纸库较大时用搜索框快速定位。
2. 暂停/播放 控制视频播放;关闭 淡出壁纸;刷新 重新扫描壁纸库——新订阅的创意工坊壁纸无需重载页面即可出现,已改用预览图的壁纸也会重新尝试播放原媒体。
3. 用滑杆调节融合效果。壁纸画面复杂时调高 暗化 和 边框 直到文字清晰;开启智能可视后这些自动完成。界面跟随 DSH 明暗主题,无需手动适配。
4. 排布 一行决定基础摆放,点「调整画面」在画布上直接拖动平移、滚轮缩放取景。
5. 用 新建 创建轮播列表,从网格挑选或导入 WE 播放列表,然后开启 自动轮转。
6. 资源行显示当前帧率与两个自动暂停开关。

你的选择与每一项调节都持久化在浏览器的 localStorage 中。

工作原理

bundle 分为两半:

• 宿主插件 负责发现 Wallpaper Engine 安装位置(Steam 注册表项、libraryfolders.vdf、Windows/macOS/Linux 标准探测路径),从默认项目、我的项目和创意工坊目录枚举壁纸,只保留浏览器可渲染的类型,并通过同源路由提供 JSON 清单与媒体数据:
  • GET /we-background/inventory[?refresh=1]
  • GET /we-background/media/<token>[/<入口文件或子资源>…] —— 支持 HTTP Range,视频可拖动进度。网页壁纸的 URL 直接定位到入口文件(如 …/media/<token>/index.html),文档 URL 与壁纸目录结构一一对应,壁纸内部的相对引用(脚本、样式、图片、fetch)按 Wallpaper Engine 自身的规则解析;媒体响应带 Access-Control-Allow-Origin: *,沙箱 iframe(不透明源)里的壁纸也能 fetch 自己的资源
  • GET /we-background/preview/<token>
• 浏览器插件 把选中的壁纸渲染在应用框架之下的固定层,提供设置界面,所有视觉效果都读取 DSH 设计令牌,主题切换时自动适配。

媒体服务在多个层面做了防护:令牌是无法猜测的 72 位随机值,清单重建时保持不变(后台刷新不会中断正在播放的流),只在显式刷新时重新生成;子资源路径先做词法包含检查,再对照真实文件系统复核,符号链接无法指向壁纸目录之外;HTML 与 SVG 响应带 sandbox CSP,不能以 DSH 源的身份执行;壁纸 iframe 固定使用中性 color-scheme,外壳的深色主题不会泄漏进(并破坏)第三方壁纸应用;媒体响应的 CORS 通配只允许持有令牌的一方读取其本来就能请求的文件,访问权限仍由令牌决定,且整个服务只监听本机回环地址;长度不足的响应会直接中断,而不是悄悄截断。清单由宿主缓存 30 秒;安装位置的发现过程在请求路径之外异步执行,并缓存 10 分钟。本插件不注册模型工具,不占用 prompt。

限制

• 场景与应用壁纸不出现在列表中:它们是 Wallpaper Engine 私有的 .pkg 场景包,动态渲染只能由桌面端的 Wallpaper Engine 完成。
• 网页壁纸与页面存储隔离,需要跨加载保存状态的壁纸无法保留状态。
• 玻璃效果读 DSH 设计令牌;若未来外壳重构重命名令牌,磨砂会退化为普通半透明。

开发

npm install        # prepare 钩子自动构建 lib/client.js
npm test           # 纯核心单元测试 + 线级宿主集成测试
npm run build      # 从 src/client.js 重新生成 lib/client.js
npm run verify     # 在 vm 沙箱中启动产物并断言行为

目录结构:lib/core.js(纯逻辑,有测试)、lib/index.js(宿主插件)、src/client.js(浏览器源码)→ lib/client.js(构建产物,请勿手改)。npm run prepublishOnly 执行完整门禁:test → build → verify。

发布

发布由 GitHub Actions 通过 npm Trusted Publishing(OIDC,无需存储令牌)自动完成。本地只需一条命令:

npm run release          # 补丁版本;另有 release:minor / release:major

它会提升版本号、提交、打 v<版本号> 标签并一并推送。标签推送触发发布工作流:完整门禁 → 校验标签与版本一致 → npm publish --provenance → 自动创建带更新说明的 GitHub Release。