# Ebb **Repository Path**: nixius/Ebb ## Basic Information - **Project Name**: Ebb - **Description**: No description available - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-10-27 - **Last Updated**: 2026-10-27 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 潮息 · Ebb 一件会呼吸的桌面壁纸。安静时是一件很慢的柔光抽象画;音乐响起时,整幅画才开始随低频起伏。 - 深色、无文字、无封面、无时钟。 - 手写 WebGL2,零依赖、无构建、不联网。 - 设置保存在本机,每台显示器各自独立。 ## 安装 把整个 `Ebb` 文件夹拖进 Lively 的库窗口即可(或把 `Ebb-x.y.z.zip` 拖进去)。默认用 WebView2 播放。 > 注意:Cef 插件模式的 WebView2 用户数据目录是随机的临时目录,localStorage 不会保留,设置每次都会回到默认值。建议保持 WebView2。 ## 设置 设置有两个入口,改的是同一套参数: 1. **Lively 右键 →「自定义」**:形态、配色、速度、响应、亮度、帧率。这里的值由 Lively 保存在库里, 不受磁盘缓存设置影响,是**唯一能跨重启保留**的入口。 2. **壁纸右下角的小圆点**:同样的控件,改完立刻生效,适合快速试色/试形态;写入 localStorage, 只有开启「磁盘缓存」时才能跨重启保留。 鼠标移到屏幕**右下角**,会有一个极淡的小点展开成齿轮,点击打开面板: | 分组 | 项目 | 说明 | | --- | --- | --- | | 核心 | 形态 | 柔光色场 / 流动丝带 / 几何呼吸 / 暗夜星空 | | 核心 | 配色 | 6 个预设色点 + 自定义主色,其余颜色在 OKLCH 空间自动派生 | | 核心 | 速度 | 0.25×–3×,1× 约 40 秒一个完整漂移周期 | | 核心 | 响应 | 0.4×–2.2×,音频灵敏度乘数 | | 高级 | 亮度 | 0.6–1.6 | | 高级 | 帧率上限 | 30 / 60(默认 30,省电且对这批慢动画几乎无损) | | 高级 | 恢复默认 | 清空本机设置 | 两个入口不会互相覆盖:启动后 1.5 秒内 Lively 推来的值视为初始化回放(本地有存档时以本地为准), 之后在 Customise 里的改动会被当作真实操作,立即生效并同步到本地。 如果点击壁纸完全没反应(Lively 关闭了鼠标输入),说明鼠标事件没有进入页面——此时用 Customise 就行, 桌面也不会再因为壁纸的输入转发而变卡。 ## 它怎么响应音乐 音频来自 Lively 的 `--audio`:每约 100ms 推送一次 128 个**原始 FFT 幅值**(线性频段,立体声 100ms 缓冲时每格约 40Hz,128 格大约只到 5kHz)。归一化、分段、平滑都在壁纸里完成: - 低(0–8 格)→ 呼吸幅度与亮度(暗夜星空里改为星点跟随鼓点明暗、发光,银河本身不胀缩) - 中(9–40 格)→ 流动速度与形变 - 高(41–127 格)→ 色相微移与光泽(不做闪烁:10Hz 的回调做不出闪烁,只会卡顿) - 每个频段独立做「快起慢落」包络,并用近 30 秒的 95 分位做自动增益,所以安静的歌也能推动画面、响的歌也不会顶死。 - 连续约 3.5 秒没有音乐后,呼吸平滑归零,只剩缓慢漂移。 呼吸本身是**整体同相**的:所有元素一起涨落,吸气快、呼气慢。 ## 持久化边界(重要) Lively 的网页播放器默认**不开启磁盘缓存**(`CefDiskCache = false`)。此时 WebView2 的用户数据目录是 `%TEMP%\Lively Wallpaper\CEF\<随机名>`,**每次切换壁纸、每次重启都会换一个新的** —— localStorage 会被清空, 表现为“设置全没了”。 开启磁盘缓存后(Lively 设置 → 壁纸 → 网页浏览器 → 磁盘缓存),目录固定为 `…\Lively Wallpaper\WebView2\Lively.Player.WebView2\PerScreen\Monitor_N`,localStorage 才会真正持久。 开启后 Lively 的 `Settings.json` 里对应字段为 `CefDiskCache: true`。验证方式:切换壁纸再换回来,设置仍在。 仍然存在的边界: - 存储按「显示器 + 布局」隔离:换到 Span / Duplicate 布局、或显示器编号变化,会读到一个新的 profile,表现为回到默认。 - 壁纸文件夹路径变了,虚拟域名(路径哈希)也会变,同样读不到旧数据。 - 用 Cef 插件而不是 WebView2 时,用户数据目录本来就是随机的,这条链路不成立。 ### 修改 LivelyProperties.json 之后 Lively 会把 `LivelyProperties.json` **复制一份**到 `Library\SaveData\wpdata\<壁纸文件夹名>\<显示器序号>\LivelyProperties.json`,之后只读写这份副本, **原文件改了也不会同步**。更新自定义控件后,需要删掉这个 SaveData 目录(或整个壁纸重新导入), 下次加载时才会重新拷贝。 ## 输入与性能 - 画面层(两个 canvas)设了 `pointer-events: none`,指针事件只会落在右下角 168×168 的入口热区和面板上; 壁纸其余部分不参与任何鼠标处理。 - 默认 30fps;WebGL 形态的像素预算 450 万(4K 下约 0.74×),丝带的 2D 画布上限 200 万像素再交给 CSS 放大。 帧时间连续超预算 2 秒会自动再降一档,且不回升。 - 如果桌面鼠标仍然发涩,可以在 Lively 设置里关掉「壁纸输入 → 鼠标」——代价是右下角的小圆点不再响应, 设置改用右键 →「自定义」。 ## 开发 ES 模块需要通过 http 加载(`file://` 下 localStorage 也不可用): ```bash python3 -m http.server 8765 ``` - `?dev=1`:左侧出现假音频面板,可以拖动三档能量、切换静音/轻声/大声/自动,用来在没有音乐时调参。 - `?still=1&scene=aurora&preset=0&t=12&low=0.6&mid=0.4&high=0.2&ui=0`:喂一个固定状态并只画一帧,便于截图对比。 - `?open=1`:直接展开设置面板。 - `?gain=2`:临时提高曝光,用来看清结构。 `tools/shot.mjs`、`tools/check.mjs` 用 CDP 做截图与冒烟测试(Windows 侧 node): ```bash node tools/shot.mjs "http://127.0.0.1:8765/index.html?still=1&ui=0" "D:\shots\a.png" 1600 900 node tools/check.mjs "http://127.0.0.1:8765/index.html" ``` ### 目录 ``` Ebb/ index.html css/app.css js/ main.js 入口、主循环、uniform 组装 audio.js 128 bin → 三段包络 + 自动增益 renderer.js WebGL2 全屏三角形、降级策略 scenes/ 每个形态一个片元着色器 state.js 默认值 / 校验 / localStorage color.js OKLab、OKLCH、配色派生 panel.js 设置面板 dev.js 假音频调试层 LivelyInfo.json LivelyProperties.json 只有说明文字 tools/ 截图与冒烟测试脚本 ``` ## 验收清单 - [ ] 4K 下 60fps 稳定,帧时间 P95 < 20ms - [ ] 静音漂移时进程 CPU 平均 < 1.5%,有音乐时 < 3% - [ ] 音乐开始后 1 秒内出现可感知但不突兀的变化 - [ ] 音乐停止后 2 秒内平滑回落,无可见跳变 - [ ] 改完设置重启 Lively 后完全保持 - [ ] 切换显示器 / 布局不崩溃(允许回落默认) - [ ] 连续运行 8 小时无报错、内存增长不超过 10% ## 第二批 流动丝带、微光粒子。架构上已经在 `js/scenes/` 留好插槽:新增一个模块并在 `scenes/index.js` 注册,面板会自动多出一个按钮。 ## 许可 MIT