miiaowuwu/dsh-sound-lab

dsh-sound-lab —— 声音工坊（Sound Lab）

English | 中文

DSH Web GUI 声音工坊（Sound Lab）：四个触发条件各自可选用音效（会话结束 / 弹出选项 / 请求许可 / 停止），AI 生成角色语音，音效库上传与管理——全程可视化点选，无需改代码；悬浮角色桌宠（默认）或圆球按钮、三种外观、配置双持久化。

🐋 角色引用：本项目为《明日方舟》（Arknights）角色 安洁莉娜（Angelina） 的粉丝向自制项目，默认示例音效为安洁莉娜「hirari do～」「呢？」与「啊哇哇！」语音片段，仅供个人学习与娱乐使用，不用于任何商业用途。

安装

两种方式对两类用户（桌面版 / web 版）都适用，任选其一即可。

方式一：Setup 安装器（推荐，零依赖，两种用户都可用）

1. 如果 dsh 尚未运行，请先启动一次（桌面应用或 npx dsh web），完成 profile 初始化；然后退出正在运行的 dsh（桌面应用或 dsh web 服务）
2. 下载 dsh-sound-lab-Setup-1.3.2-x64.exe，双击
3. 安装器会自动重启 dsh，看到悬浮的 安洁莉娜角色桌宠（默认）即安装成功（无帧素材时自动回退圆球按钮）

• 更新：重新下载最新版 Setup exe 并双击（会自动重启 dsh；旧版本会被自动覆盖，无需先卸载，不会冲突）
• 卸载：双击 dsh-sound-lab-UnSetup-1.3.2-x64.exe（完成后会自动重启 dsh）

说明（仅了解原理，无需任何操作）：安装器把插件部署到 $DSH_HOME\plugins\dsh-sound-lab，并扫描 $DSH_HOME\profiles 下所有已初始化的 profile（web / desktop / …）逐一调用官方 dsh plugin 命令登记，使各 profile 共用同一份部署副本；若本机没有 dsh CLI，会自动穷举补齐（桌面应用自带 runtime → 系统 npx → 自动下载 Node.js）；若 dsh 尚未初始化（无 profiles），会自动运行 dsh web 完成首次初始化。安装完成后自动重启 dsh：桌面版先关闭正在运行的实例，再重新启动（模拟双击打开，无终端窗口，关闭安装器窗口不影响）；未检测到桌面应用（web 环境）时提示手动重启 dsh web 服务。全程自动化，不手改任何配置。

方式二：dsh CLI（需 Node.js，两种用户都可用）

如果 dsh 尚未运行，请先启动一次（npx @deepseek-ai/dsh web），完成 profile 初始化，再进行安装（npm run setup 与方式一安装器在未初始化时会自动执行该步骤）。 尚未安装 dsh？下载 DeepSeek Harness 桌面版，或安装 Node.js（https://nodejs.org）后运行 npx @deepseek-ai/dsh web。

请二选一：根据你的实际运行方式（桌面版 / web 版）选择执行其中一条，不要两条都执行：

# 桌面版用户 —— 执行这一条
npx @deepseek-ai/dsh plugin --profile desktop add dsh-sound-lab --config.minimumReleaseAge=0

# web 用户（用 `npx dsh web` 运行）—— 执行这一条
npx @deepseek-ai/dsh plugin --profile web add dsh-sound-lab --config.minimumReleaseAge=0

然后重启 dsh（若尚未启动则直接启动）：

npx @deepseek-ai/dsh web

开发便利：npm run setup 自动检测本机所有 profile 并逐一登记本插件；npm run setup:deploy 把副本部署到 $DSH_HOME/plugins 并让所有 profile 指向它（发布/固定使用模式）。加 --profile <name>（如 node tools/install.mjs --profile web --unify）可只操作单个 profile；node tools/install.mjs --npm --start 以 npm 包方式安装并在完成后自动启动对应端（desktop 弹应用窗口 / web 启动并自动打开浏览器）。

功能

• 悬浮角色桌宠（默认，明日方舟安洁莉娜动画）：待机（默认站立）/ 点击打招呼 / 拖拽移动 / 左·右·上·下边缘停靠（左右窥视 · 上下睡觉）/ 空闲 90s 睡觉 / 会话运行中持法杖待机 / 会话结束庆祝 / 弹出选项·请求许可疑惑 / 停止·异常倒下（保持末帧，交互后恢复）；可拖动、贴边停靠、点击打开配置弹窗，位置持久化，默认靠左
  • 停靠与隐藏：顶部停靠垂直倒挂并隐藏 80%（仅露 20%）、底部停靠不隐藏、左/右停靠隐藏 40% 并向屏幕内旋转 30°（左顺 / 右逆）；需贴得足够近（30px）才会停靠
  • 动画与衔接：60fps 精灵图（Sprite Sheet）播放（播放速度减半）；事件切换时 150ms 半虚化过渡（最低 40% 透明度再恢复），不交叉重叠、无虚影跳帧
  • 悬浮窗配置弹窗：主题（安洁莉娜桌宠 / 自带悬浮球）+ 事件 · 素材 · 音频（每个事件可指定播放哪个素材动作与音效：默认 greeting 播「呢？」、其余不播放；素材可手动选任意动作，音频只在事件触发时播一次，视频可循环多次；对应触发条件在「触发条件 · 音效」已启用时以详细配置的为准）；帧素材加载中 / 加载失败时自动回退圆球按钮
  • 圆球按钮（可切换）：按住拖到屏幕任意位置；拖到屏幕边缘自动缩成「只有 > 图标」的小半球；点击打开配置弹窗
  • 悬浮样式（外观）：默认角色桌宠，可切换回 圆球按钮（无帧素材时自动回退圆球按钮）
• 配置弹窗：可拖动（按住标题栏）、z-index 置顶
  • 触发条件 × 4：会话结束 / 弹出选项 / 请求许可 / 停止，每个独立【启用勾选 + 音效下拉】，下拉可选 内置提示音 / 不播放 / 具体音效（「内置提示音」为 Web Audio 琶音，不依赖音频文件）
  • 注意类事件（弹出选项 / 请求许可）始终响铃：出现即播，不受会话运行/查看状态限制，且优先于完成类音效
  • 外观风格：鲸鱼娘（默认）/ 纯白 / 纯黑 + 语音名字可自定义（三种风格同时作用于所有弹窗，切换即时生效）
  • 音量滑杆（0–100%）、测试音效 下拉（含「内置提示音」选项）+ ▶ 试听 + 状态栏、重置按钮位置
  • 音效库（插件 sounds/ 目录本地音频 + sounds.json 控制文件管理）+ 刷新 + 「上传」弹窗：选择/拖拽上传音频、删除音效、恢复被隐藏的附带音效；非附带音效支持 ✎ 重命名
  • 「AI生成角色音频」：音效库上方入口，用你自己的阿里云百炼 API Key 与复刻音色ID，输入文本一键生成专属音色语音（可自定义文件名/试听/删除，一键加入音效库自动登记），弹窗内附图文详细教程（配图可点击放大至 3 倍并拖动查看），token 消耗自负
  • 附带音效 × 3（「hirari do～」/「呢？」/「啊哇哇！」）：不可删除、不可重命名（删除=软隐藏，可随时恢复）；隐藏音效可直接试听且秒出
  • 音效库超过 4 条自动上下滚动，不超出配置页高度；音效名不显示文件后缀
• 音效来源：插件包 sounds/ 目录的本地音频文件（mp3/wav/ogg/m4a/flac/opus/aac/wma/webm），宿主端经 /dsh-sounds-control 静态服务（Range/206 分片、ETag、流式）提供
• 配置持久化：localStorage + 宿主端 config.json 双写，重启不丢；加载时逐字段清洗（类型/范围/枚举），脏数据回退默认值
• 启动即预加载：打开软件时自动拉取配置与音效列表并缓冲配置的音效，首次播放秒出
• 默认配置：音量 60%；会话结束 →「hirari do～」、弹出选项/请求许可 →「呢？」、停止 → 内置提示音
• 未选择/加载失败时自动播放 Web Audio 内置提示音兜底
• 开发工程化：npm test（宿主端 list/config/upload/delete 与浏览器端逻辑的 Node 冒烟测试）、npm run setup / setup:fix / setup:deploy（多 profile 自动配置）、releases/build-single-exe.ps1（打包 Setup/UnSetup 安装器）

目录结构

dsh-sound-lab/
├── package.json          # 包声明（dsh.client / dsh.bundle.patch / types / scripts）
├── cordis.patch.yml      # 组成补丁：挂载行 ui-event-sounds
├── CHANGELOG.md          # 版本记录
├── README.md / README.zh.md
├── LICENSE
├── sounds/               # 音效库：附带音效（hirari do～/呢？/啊哇哇！）+ 上传/AI 生成的音频
├── frames/               # 桌宠帧素材：<动作>/sprite.webp 精灵图（WebP lossless）+ motion.json（60fps，12 动作）
├── lib/
│   ├── index.js          # 宿主端：/dsh-sounds-control 静态服务（list/config/音频/TTS）+ /dsh-frames-control（桌宠帧）
│   ├── client.js         # 浏览器端：角色桌宠/悬浮球 + 配置弹窗 + 触发监测 + 播放
│   ├── tutorial/         # AI 生成角色音频的图文教程配图（image1.png / image2.png）
│   └── types/index.d.ts  # 类型声明
└── tools/
    ├── install.mjs       # 多 profile 自动配置（setup / --fix / --unify / --deploy）
    ├── test-host.mjs     # 宿主端接口冒烟测试（list/config/upload/delete/TTS）
    ├── test-client.mjs   # 浏览器端逻辑冒烟测试
    └── api/              # 独立 TTS 脚本（tts_api.py + 使用说明 + 参考音频）

双端结构

插件由 宿主端 + 浏览器端 两半组成，随单个安装包一并自动加载：

• 宿主端（Node 半） lib/index.js：运行在 DSH 主进程（Node），把插件包 sounds/ 目录通过 /dsh-sounds-control 静态服务暴露给浏览器端（音效列表 / 音频文件 / config.json 持久化），并把 frames/ 桌宠帧素材通过 /dsh-frames-control 暴露（动作清单 / 帧 PNG）
• 浏览器端（Web GUI 半） lib/client.js：运行在 DSH 的 Web GUI 页面，负责角色桌宠（动画播放 / 拖动 / 停靠）或悬浮球、配置弹窗、触发监测与音效播放

两半的挂载由 package.json 声明驱动，无需手动分开安装：

• dsh.client 声明（exports "./client"）→ 驱动浏览器端在 Web GUI 加载
• dsh.bundle.patch（cordis.patch.yml）→ 驱动宿主端在 DSH 主进程注册

由于 dsh 插件按 profile 隔离（$DSH_HOME/profiles/<name> 各自持有 package.json / node_modules），需要哪个 profile 用就必须在哪个 profile 登记——这正是安装器与 tools/install.mjs 自动完成的事（见安装）。

使用

1. 准备音效：开发时把音频文件放入仓库 sounds/ 目录（见上方目录树），启动后会自动对账登记进音效库；已安装使用时无需手动找文件夹——打开配置弹窗 → 音效库 → 「上传」，选择本地文件或拖拽导入即可（自动复制进安装位置的 sounds/ 目录），也可在列表中删除音效（附带音效为隐藏，可随时恢复）或 ✎ 重命名。
2. 打开配置弹窗：点击桌宠（或悬浮球）
3. 刷新音效列表：点击「刷新」，插件会枚举 sounds/ 下的所有音频文件
4. 配置触发条件：对「会话结束 / 弹出选项 / 请求许可 / 停止」四个事件，分别【勾选启用 + 选择音效】，下拉可选「内置提示音 / 不播放 / 具体音效」（「内置提示音」为 Web Audio 琶音，不依赖音频文件）
5. 测试音效：在「测试音效」下拉中选择音效并点击 ▶ 试听（下拉含「内置提示音」选项，选它或未指定时试听 Web Audio 琶音）。配合音量滑杆（0–100%）调整音量
6. 生效：之后对话中的对应事件会自动播放所选音效；未选择或加载失败时会自动播放内置提示音兜底

提示：桌宠可拖到屏幕任意位置，拖到屏幕边缘会自动停靠（左右窥视、上下睡觉：左/右停靠隐藏 40% 并旋转 30°、顶部倒挂隐藏 80%、底部不隐藏），无操作 90s 自动睡觉，点击打招呼；「外观」里可切换 角色桌宠 / 圆球按钮，以及 鲸鱼娘 / 纯白 / 纯黑 风格；悬浮窗配置弹窗可单独调整 主题 / 事件·素材·音频；位置与配置会自动保存，重启不丢。

免责声明

• 本项目为 粉丝向（非官方）个人项目，与《明日方舟》官方及上海鹰角网络科技有限公司（Hypergryph）无任何隶属、赞助或授权关系。
• 项目中引用的角色形象、名称、台词及语音素材（含安洁莉娜「hirari do～」「呢？」「啊哇哇！」语音）版权归《明日方舟》官方及其相关权利人所有；语音的著作权归相应的配音演员所有。
• 本项目仅用于个人学习、研究与娱乐，不用于任何商业用途，不以此牟利。
• 项目自带的音效素材来源于使用者自行放入的本地音频文件，使用者须确保其使用方式符合相关法律法规及原权利人的要求。
• 如相关权利人认为本项目的任何内容构成侵权，请联系项目作者删除相关素材，我们将立即处理。
• 本项目按现状提供，作者不对因使用本项目产生的任何后果负责。