开机动画音效 2034126171/dsh-boot-animation-sound

dsh-boot-animation-sound

给 DeepSeek Harness（DSH）加一段开机动画：启动时铺满窗口播放一段视频。

和别的开机动画比，这一版只改一件事：声音不需要全屏。

纯 JavaScript，没有构建步骤。

作者：LSY（个人创作） · MIT · 版权归 LSY 所有，见 LICENSE。

为什么需要它

参考社区里几个开机动画，它们的做法是：

浏览器禁止带声音自动播放 → 动画一律静音起播 → 想听声音就点一下画面 → 但那一按同时还会 requestFullscreen()，于是「开声音」和「进全屏」被绑成了同一个动作。

（dsh-boot-animation-pro 的 README 自己就是这么写的：点一下画面即可开启声音并进入全屏。）

本插件把这两件事拆开：

| 动作 | 常见的绑定式做法 | 本插件 |
| 起播 | 一律静音 | sound: true 时先试带声音起播 |
| 被系统拦下 | 静音播放，等点击 | 静音播放，等点击（一样） |
| 点一下画面 | 开声 + 进全屏 | 只开声，窗口大小一动不动 |
| 第一次点击/按键 | 必须点在画面上 | 窗口内任意位置的第一次点击/按键就开声 |
| 进全屏 | 开声的副作用 | 只有那个默认关闭的「全屏」按钮才会进 |

代码层面：client.js 里 requestFullscreen() 只出现一次，就在全屏按钮的事件处理函数里；开声那条路径（unlock）只做两件事：video.muted = false 和 video.play()。
这条约束由验证脚本静态断言，改坏了跑测试就会红。

声音到底能不能自动响

先说规则。这个结论是在真实环境里实测出来的，不是照抄文档：

- 在一个没有任何用户手势的页面里，非静音的 play() 会被 Chromium 拒绝（NotAllowedError）。
Electron 的默认自动播放策略本应是 no-user-gesture-required，但实测就是拒绝了，所以本插件按「会被拒绝」来设计，而不是赌它不拒绝。
- 一旦这个页面有过用户手势（哪怕只是之前随便点过一下），非静音播放就会被放行。

于是分三种情况，插件三种都实现了：

1. 平台放行 → 直接就有声音，一次都不用点。
2. 平台拦下 → 画面照常播，右下角出现一个「🔊 点这里开声（不用全屏）」的小按钮； 同时你在窗口里随便点一下或按一下键盘也会开声。同一个窗口，不进全屏。
3. 设置里关掉声音 → 连试都不试，静音播放，也不出现任何开声提示。

想彻底免点击，只能改平台策略本身（例如给 Electron 传 --autoplay-policy=no-user-gesture-required），那不是插件能做的事。
本插件能做的是：不让你用全屏去换声音，并把「要点的那一下」缩到最小——点哪都行。

实测记录

真实窗口里跑过一次之后，插件自己写下的 last-boot.json（原文摘录）：

{
"audio": "on", // 有声播放 "muted": false, // 元素没被静音 "audioDecodedBytes": 115835, // 真的解码出 115 KB 音频，声音确实出来了 "fullscreen": false, // 没有全屏 "fullscreenEverRequested": false, // 全程没请求过全屏 "duration": 7.05, "videoWidth": 1280, "videoHeight": 720, "ua": "… @deepseek-ai/dsh-desktop/0.2.0-rc.2 Chrome/152.0.7977.54 Electron/44.0.0 …"
}

audioDecodedBytes 是关键：它说明音频真的被解码并送进了输出管线，而不是「元素说自己没静音」而已。

触发时机与播放频率

触发时机（什么时刻播）

| 选项 | 含义 |
| 启动应用 | 一次 DSH 运行里只算第一次页面加载 |
| 页面刷新 | 每次页面加载都算（默认；也就是这个插件最早的行为） |
| 新对话 | 点「新建对话」时 |
| 任意会话 | 打开任意对话时，新建的也算 |

「启动应用」与「页面刷新」的区别由宿主判定，不是浏览器猜的：宿主半在每次 DSH 运行时只挂载一次，它数自己服务过多少次首页渲染——第 1 次就是「启动应用」，之后都是「页面刷新」。
这样「触发时机」和「要不要盖住首帧」用的是同一个计数器，不可能互相矛盾。

后两个是会话触发：它们不在页面加载时播，而是在你新建/打开对话时把动画盖在界面上（Esc 随时可退）。

会话触发没有现成的事件可用——DSH 客户端的事件表里只有 connection/reset、locale/change、 slots/changed、theme/change，没有会话事件。所以插件包了一层界面用来导航的那个服务（uiWorkspace 的 startSession / openSession / connectWorkspace）。
这层包装写得很保守：先调用原方法并原样返回它的结果，通知失败绝不影响导航；赋值不成功就干脆不包；插件卸载时逐个还原。宁可这个触发不生效，也不让导航出问题。

播放频率（一共能播几次）

| 选项 | 含义 |
| 每次 | 不限（默认） |
| 每天一次 | 每个自然日最多一次（按本机本地日期，不是 24 小时窗口） |
| 只播一次 | 一辈子最多一次 |
| 限播 N 次 | 最多 N 次，N 可填 1–1000 |

计数存在宿主这边（<DSH_HOME>/dsh-boot-animation-sound/play-state.json），不是浏览器里：只存浏览器的话，刷新一下就忘了、开第二个窗口就各算各的。所以：
- 播放权由宿主唯一判定，判定通过时当场扣一次（POST /claim）；被拒绝的请求不扣。
- 只有真的开始播才计数；被拒绝的那些页面加载不算。
- 次数用完后，那些页面加载连首帧遮罩都不会注入——不会先黑屏再放出来。
- 设置页有「重置计数」，否则「只播一次」就是一扇只能改文件才能打开的门。

只在「一次页面加载」时播放

页面加载类的触发还有一道额外的判定：开机动画属于一次页面加载，不属于「插件被加载的那一刻」。
DSH 的 client 模块图是活的——把插件当场启用、或 HMR 把模块塞进一个开着很久的页面，都会加载这个文件。
所以浏览器半会先判断这是不是属于本次加载：

- 宿主在服务端 HTML 里注入的首帧遮罩在 里——它在，就是本次加载（精确信号）；
- 遮罩关掉时（coverApplication: false）退回用页面年龄判断：模块在页面开了几分钟后才到，那一定是热加载，不播。

这样正常启动照常播，而不会突然盖住你正在干活的窗口。

安装

profile 目录是 <DSH_HOME>/profiles/<profile 名>（<DSH_HOME> 未设置时默认 ~/.dsh）。

方式一：让 agent 用 plugin_manager 装（桌面版首选）

plugin_manager: action=install_bundle, target=github:2034126171/dsh-boot-animation-sound

方式二：命令行

npm install -g @deepseek-ai/dsh
dsh plugin --profile web add github:2034126171/dsh-boot-animation-sound

方式三：手动

1. 在 profile 目录的 package.json 里，dependencies 加 "dsh-boot-animation-sound": "github:2034126171/dsh-boot-animation-sound"；
2. 把 "dsh-boot-animation-sound" 加进同一个文件的 dsh.profile.bundles 数组；
3. 在该目录里用 pnpm 执行 install（桌面版自带 pnpm，在 <DSH_HOME>/.desktop-bin/pnpm.cmd）；
4. 重启 DSH。

通过 GitHub 安装需要本机装有 git。

开发机上的现状（与使用者无关，仅供本仓库作者参考）：源码放在工作区，profile 用两个 junction 指过来（profiles/node_modules/… 与 profiles/desktop/node_modules/…；前者给依赖 spec 用，因为它没有空格），并在 dsh.profile.bundles 里列了包名；改 profile package.json 之前已备份为 package.json.before-dsh-boot-animation-sound.bak。

使用

设置页在 设置 → 插件 → 开机动画：

| 项 | 说明 |
| 触发时机 | 启动应用 / 页面刷新 / 新对话 / 任意会话 |
| 播放频率 | 每次 / 每天一次 / 只播一次 / 限播 N 次（N 可填 1–1000） |
| 播放影片声音 | 这个插件的主角。默认开。关掉＝整段动画静音，也不再出现开声提示 |
| 音量 | 0–100% |
| 首次点击/按键自动开声 | 默认开。关掉后只能点右下角那个开声按钮 |
| 启动时显示动画 | 临时关掉动画，但保留已选路径 |
| 显示全屏按钮 | 默认关。和声音毫无关系：开声永远不会触发它 |
| 退出方式 | 右下角按钮 / 点任意位置 / 自动退出 / 不能退出 |
| 视频文件 | 路径输入框 + 「选择文件…」原生对话框 + 保存 / 清除 |
| 播放账本 | 已播次数 + 上次日期，旁边有「重置计数」 |

「清除」＝不再播放，DSH 启动起来和没装这个插件时一模一样。

保命键

Esc 永远能退出动画，任何退出方式下都生效。全屏层吞得掉鼠标点击，吞不掉键盘。
一个铺满屏幕、又关不掉的面板离「软件没法用」只差一个 bug，所以这个键是无条件保留的。

出问题怎么看

每次真实启动的结果都会写进：

<DSH_HOME>/dsh-boot-animation-sound/last-boot.json

设置页底部也会显示一行摘要。关键字段：

| 字段 | 含义 |
| audio | on 有声播放 / off 按设置静音 / blocked 被系统拦下（点一下就能开）/ error 播放失败 |
| muted | 那一刻元素是否静音 |
| audioDecodedBytes | 音频真的被解码出来的字节数。> 0 说明视频有音轨、音频管线真的跑了；0 说明这段视频根本没声音 |
| fullscreen | 那一刻是否处于全屏 |
| fullscreenEverRequested | 本次启动是否请求过全屏（正常情况下永远是 false） |
| userActivation | 当时的用户激活状态 |

排查顺序：先看 audioDecodedBytes 是不是 0（是 0 → 换一个带音轨的视频），再看 audio 是不是 blocked（是 → 点一下窗口任意位置，或确认「首次点击/按键自动开声」是开的），最后看 muted 和音量。

配置（可选）

也可以直接改 profile 的 cordis.patch.yml：

- id: dsh-boot-animation-sound
config:
src: D:/videos/boot.mp4 # 留空字符串 = 不播；不写 = 用自带视频 trigger: pageRefresh # appStart / pageRefresh / newConversation / anySession frequency: every # every / daily / once / times maxPlays: 3 # 仅 frequency: times 时有效，1–1000 sound: true volume: 0.9 fit: cover # cover 铺满裁切 / contain 完整留边 / fill 拉伸 skip: button # button / click / auto / never fadeOutMs: 360 showFullscreenButton: false

设置页里改过的项会盖在 patch 上面（存在 <DSH_HOME>/dsh-boot-animation-sound/settings.json；播放计数另存 play-state.json）。字段写错只会退回默认值，不会导致启动失败。完整字段见 index.js 里的 DEFAULTS。

验证

npm run verify

252 项检查，全部不依赖 DSH、不依赖浏览器，也不需要安装任何依赖：

- verify/check-media.mjs（6 项）：media/ 里的片段是否真的是视频容器、是否带音轨。
自带视频没声音的话这个插件就没意义了，所以这一条是硬检查。
- verify/host-verify.mjs（168 项）：跑宿主半的真实代码——配置归一化、媒体解析、七个 HTTP 路由（媒体流含 Range 取字节、设置保存、开机报告落盘、播放权 claim 与计数 reset）、
首帧遮罩注入，以及静态断言：「requestFullscreen() 只有一个调用点且在按钮里」、「结束时什么都不画」。
触发与频率单独一节逐条验：四种触发×四种频率的判定矩阵、每天一次按本地日期而不是 24 小时、被拒绝的请求不扣次数、次数用尽的页面加载不注入遮罩、以及 /claim 真的把账记到 play-state.json 上。
- verify/client-smoke.mjs（78 项）：用一个迷你 React + 假 DOM + 假 + 可切换的自动播放策略（复现真实环境那个 NotAllowedError）把浏览器半真跑一遍：带声起播 → 被拒 → 静音兜底 → 出现开声提示 → 第一次点击开声 → 全程零次 requestFullscreen()； 断言页面加载时 claim 的是宿主给的那个 occasion、会话触发在页面加载时一次都不 claim、被拒绝的 claim 什么都不画；会话包装原样返回导航结果并且能被还原；热加载进老页面时不播；以及收场回归测试（跳过 / 播完 / Esc 都要让出屏幕）。
这个迷你 React 会真的调用上一次的 effect 清理函数——清理函数要是被丢掉，组件漏掉监听器也能「通过」，那这些测试就没有意义了。

变异验证（一次性做过）：把 if (!running) return null 换回
if (!active) return null，client-smoke.mjs 立刻 2 项失败，失败详情里正是那个
position: fixed; inset: 0; z-index: 2147483000 的盒子和「正在加载视频…」。
测试对着它命名的缺陷会红，才叫回归测试。

已修过的严重缺陷

动画结束后整个界面点不动。 覆盖层是铺满视口的固定定位盒子，而槽位注册表会让组件在整个页面生命周期里保持挂载；原来的渲染判断只看了「该不该播」，没看「还在不在播」，于是播完之后那层 透明但仍在最上面的盒子继续吃掉每一次点击。修法是把「该不该播」和「现在还在不在播」分开，并让所有 effect 跟着它走，另加三道独立保险（pointerEvents 随淡出放行、10 分钟硬上限、 Esc 无条件可退出）。完整来龙去脉见 CHANGELOG.md。

素材与权利

media/视频测试.mp4 是示例片头，不在下面的 MIT 授权范围内，其权利归属请自行确认；要公开分发请先换成你拥有权利的素材（替换该文件即可，不需要改代码）。

verify/check-media.mjs 会检查它带不带音轨——视频必须自带音轨，否则声音那一栏没有任何东西可放。

许可

MIT，覆盖插件代码（见 LICENSE）。示例素材不在该授权范围内，详见 NOTICE。

作者：LSY（个人创作） —— 版权归 LSY 所有。MIT 授权下你可以自由使用、修改、再分发，但请保留 LICENSE 里的版权声明。