Vai al contenuto principale
W

dsh-pet-extend

wang-yudong/dsh-pet-extend

Adds offline Chinese wake-word detection with speaker verification to dsh-pet, plus right-click chat access and wake reactions. Its HTTP routes have no DSH access check, so a web page open in your browser could call them.

Installazione

dsh plugin --profile web add github:wang-yudong/dsh-pet-extend

README

dsh-pet-extend

dsh-pet 的扩展插件。

这不是一个「语音唤醒插件」——语音唤醒只是当前已落地的第一个能力模块。这个仓库的定位是给 dsh-pet 持续加能力的扩展层:右键菜单、对话联动、唤醒反馈,以及后续还会继续扩展的其他能力,都以模块形式加在这里。所有功能都以插件方式挂在 dsh-pet 上,不改 dsh-pet 源码,也不改 DSH 内核。

本项目扩展的是 PC2005-cloud/dsh-pet。

能力模块

模块状态说明
语音唤醒已实现完全离线的中文唤醒词 + 声纹校验,默认「大肥鱼」,可自定义
右键菜单已实现桌宠右键「更多」直接打开对话,不弹独立窗口
唤醒联动已实现唤醒后打开 pet-chat + 桌宠动画 + 气泡 + 朗读(音色跟随 dsh-pet)
语音任务已实现唤醒后接着说一句命令,用 DSH 官方 SenseVoice 转成文字,写进 DSH 会话(草稿或直接发送)
后续扩展规划中新的交互与自动化能力会继续加到这个扩展里,不限于语音

语音唤醒模块的能力

能力说明
离线语音唤醒默认唤醒词「大肥鱼」,可自定义任意中文词
声纹二次校验最多 3 条声纹模板,逐条比对取最高分,别人喊不醒
并行多档灵敏度同一句词同时用 3~4 档关键词加成解码,覆盖不同语速/节奏/音量
声纹逐条回放每次录入单独存一份原始录音,可逐条播放对比
按住录音测试走与正式监听完全相同的解码 + 声纹链路,但不真的打开对话
唤醒反应打开对话 + 桌宠联动动画 + 气泡 + 朗读(音色跟随 dsh-pet 设置)
诊断面板检测/触发/拒绝/解码/未命中、音频峰值、有效语音占比、并行档位、最近跳过原因
不做的事不自动调节麦克风音量、不做 AGC、不缩放音频幅度、不上传音频

识别与声纹推理全部在本机跑(sherpa-onnx),不上传任何音频。

  • 唤醒引擎:sherpa-onnx 中文 KWS(sherpa-onnx-kws-zipformer-wenetspeech-3.3M)
  • 声纹模型:3D-Speaker CAM++(campplus_sv_zh-cn_16k-common)
  • 宿主:dsh-pet + DSH

环境要求

  • 已安装 DSH,并且 dsh-pet 桌宠可正常使用
  • Node.js >= 22.12.0
  • 语音任务需要 DSH 里启用官方语音输入插件 (@deepseek-ai/dsh-experimental-voice-input-bundle,含 SenseVoice 模型);只用唤醒不需要
  • 可用的麦克风
  • Windows / macOS / Linux(依赖 sherpa-onnx-node 的预编译包)

安装

1. 作为 DSH 插件安装

方式 A:从 npm 安装(推荐,发布后即可)
# <profile> 换成你的 DSH profile 名;desktop 是桌面端 DSH 的默认 profile
dsh plugin --profile desktop add dsh-pet-extend

无需克隆仓库、无需手动装依赖与模型——dsh-pet-extend 发布到 npm 后,DSH 直接从 registry 拉取, 包内已附带模型,可选依赖由 DSH 自动安装。在此之前(未发布时)请用方式 B。

方式 B:从本地源码安装(开发 / 改代码用)
# <profile> 换成你的 DSH profile 名;路径用本目录的绝对路径
dsh plugin --profile <profile> add file:/absolute/path/to/dsh-pet-extend

Windows 示例:

dsh plugin --profile default add file:E:\path\to\dsh-pet-extend

2. 安装依赖

cd dsh-pet-extend
npm install
# 若 DSH 没有自动装可选依赖,再执行一次:
npm run install:deps

package.json 里 sherpa-onnx-node 与 pinyin-pro 是 optionalDependencies: 前者负责 KWS 与声纹推理,后者提供全量汉字拼音(缺失时退回内置常用字表)。

3. 模型

仓库内的 models/ 已附带模型(约 32 MB):

models/kws/       encoder / decoder / joiner (.int8.onnx) + tokens.txt
models/speaker/   3dspeaker_speech_campplus_sv_zh-cn_16k-common.onnx

若缺失或损坏:

npm run install:models          # 补装
npm run install:models -- --force   # 强制重下

4. 重启 DSH

插件代码在 DSH 启动时加载,改完代码或首次安装都必须重启 DSH(dsh web 就重启 dsh web)。设置页上的「重新初始化引擎」只会重建 native 语音引擎,不会重载插件 JS。

首次使用

  1. 打开设置页:DSH 设置 → 桌宠扩展设置,或直接访问 http://127.0.0.1:<DSH端口>/dsh-pet-extend/settings
  2. 点「申请麦克风权限」,允许授权
  3. 点「开始录入(3 秒)」,等提示「麦克风已就绪」后连续清晰地念 3 秒唤醒词;建议录 2~3 次
  4. 在「唤醒词」里填写(默认「大肥鱼」),点保存
  5. 打开「语音唤醒」开关
  6. 正常喊唤醒词即可

未录入声纹时开关不可用。数据保存在 ~/.dsh/dsh-pet-extend/。

语音任务(唤醒后直接说命令)

开启后交互变成「小爱」模式:

喊「大肥鱼」
  → 唤醒反应:桌宠动画 + 气泡「我在」+ 朗读(和以前完全一样)
  → 语音播放一结束,气泡立刻换成「我在听」并开始录音(不预录,不在命令里混入之前的尾音)
  → 说一句命令,例如「把 README 里的标题改一下」
       · 一直没开口:2 秒后静默放弃,等下一次唤醒(不朗读、不留提示)
       · 说完后连续静音 2 秒:判定说完,立刻截断去识别
  → SenseVoice 转成文字,剥掉开头录进去的「我在」和唤醒词尾巴(「大肥鱼」/「肥鱼」)
       · 写到当前会话(默认)+ 先填草稿:插到当前输入框光标处,你按回车才开始跑
       · 写到新会话 + 先填草稿:新建会话并填好草稿
       · 直接发送:整条替换 / 新建后立即发出去,agent 马上开跑

流程就是最朴素的「唤醒词 → 念完「我在」→ 我在听 + 录音」,不做任何预录——命令只在反应播放 完毕后才开始录,所以唤醒词之前说的「あれ?」之类不会带进命令。

为什么不是「点击官方语音输入插件」:那个插件只是一个挂在输入框旁的 React 组件, 没有对外服务、没有快捷键,外部无法触发它。本扩展直接调用它背后的同一个宿主服务 ctx.speechToText(SenseVoice 本机推理),所以识别结果、模型、语言都与官方一致, 但流程由我们自己控制。

几个刻意的取舍:

  • 复用唤醒那条已经开着的麦克风流。命令录音不需要再 getUserMedia 一次, 既不会和「语音输入」按钮抢设备(Windows 上两路同时打开多半报 Could not start audio source),也不会多一次权限弹窗。
  • 流程就是「唤醒词 → 念完「我在」→ 我在听 + 录音」:反应(dsh-pet 的 Edge TTS)播完, 气泡立刻切「我在听」并开始收音。合成音频尾部常带几百毫秒~1 秒静音,直接等 <audio>.onended 气泡会多停 1 秒——所以客户端 decodeAudioData 算出「语音真正结束」的时刻,到那一刻就切气泡, 尾静音仍由 <audio> 在后台静默放完(不截断、不丢字)。代价是朗读会被麦克风录进去,收官用 stripReactionText() / stripWakeWordPrefix() 剥掉开头那句回应与唤醒词尾巴。
  • 不预录:录音从「我在」播放完毕那一刻才开始,所以唤醒词之前说的尾音(「あれ?」之类) 不会混进命令。预录环仅用来给端点检测器喂最近几块的 RMS 做底噪估计(不进命令音频), 让底噪阈值秒级收敛。
  • 停嘴判定是「相对峰值」而非「绝对安静」:端点检测记录本次说话的峰值,只要能量掉到峰值的 65% 以下就累计静音——嘈杂环境里底噪不低、噪声偶尔起伏也不会把静音计数清零,不要求房间安静, 只要用户停嘴即可;起音判定仍用相对底噪的阈值,避免把底噪当语音。
  • 不复述识别结果、不需要说「开始」。结果只用气泡显示,避免二次确认的噪声。
  • 不做任何增益:端点检测用的是和 KWS 完全相同的原始 PCM 与电平口径。

前置条件:DSH 里启用了官方语音输入插件(@deepseek-ai/dsh-experimental-voice-input-bundle, 默认 provider sensevoice-local)。没启用时本功能自动降级——只打开桌宠对话,并在设置页 「语音任务」卡片里写明原因。

设置项

项目默认说明
唤醒词大肥鱼中文即可,多个词用逗号/换行分隔;会转成模型需要的拼音 token
唤醒加成 keywordsScore3.0数值越高越灵敏,但过高会让流式解码过早重建,反而漏检
触发阈值 keywordsThreshold0.15越低越容易触发
声纹阈值 speakerThreshold0.5越高越严格;0.3 明显更松,误触也会变多
唤醒冷却 cooldownMs1500两次唤醒的最小间隔,低于它会被「冷却」挡掉
语音唤醒关闭总开关;关闭后会真正释放麦克风
语音任务关闭唤醒后继续听一句命令;开启后不再打开桌宠对话
命令写到当前会话current 写进当前会话的草稿/直接提交;new 新建会话
识别完成后先填草稿draft 只填草稿等回车;auto 直接发送并跳转到该会话
说完判定 silenceMs2000说过的最后一句之后连续静音多久算说完
没开口放弃 noSpeechMs2000开始听之后多久没开口就静默放弃
安全上限 maxMs60000单条命令的最长收音时间
识别语言autoSenseVoice 支持 auto / zh / en / yue / ja / ko
黑名单删除,重置,…auto 模式下命中即降级成草稿,必须人工确认

并行档位:引擎实际会同时跑 1.5 / 2 / 2.5 三档(把加成设成 3 时再加一档 3), 同一块音频喂给所有档位,任一档吐词就触发。原因是三字词的最优加成会随语速漂移—— 单档参数一定会在某些语速下漏检。

诊断与排错

设置页「诊断」会显示:

引擎 ready · 并行档位 1.5 / 2 / 2.5
检测 12 / 触发 11 / 拒绝 1
解码 3109 段 · 未命中 3096 段 · 最近跳过 冷却中
音频 3113 段 · 峰值 0.088/1.000 · 有效语音 99%
现象含义处理
解码 不涨引擎没在跑看引擎状态与「重新初始化引擎」
解码 在涨但 检测 0引擎没识别出唤醒词换成四字/叠词、放慢、加大音量;或看「按住录音测试」的归因
检测 在涨但 触发 0识别到了但没通过看「最近跳过」:冷却中 / 声纹未通过 / 分数低于阈值
有效语音占比很低采集端把声音吃掉了检查系统「音频增强/降噪」;靠近麦克风
峰值接近 1.000电平过高已削波调低系统麦克风音量
Could not start audio sourceNotReadableError:麦克风启动不了多为设备被占用:先关掉「语音唤醒」开关、等 5 秒再申请;再查 Windows 隐私里的「允许桌面应用访问麦克风」

「按住录音测试」会在没检出时给出归因:

  • 放大后能检出 → 电平问题,提示调高系统麦克风音量
  • 放大也检不出 → 发音/语速与词表不匹配
  • 换个加成能检出 → 直接告诉你「把加成改成 X 再试」

还可以点「回放刚才的录音」听引擎实际收到的声音,点「回放最近监听」对比正式监听收到的声音。

工作原理

麦克风 ──getUserMedia(关闭降噪/回声消除/AGC)──► AudioContext
   └─ 127 抽头 Blackman 窗 FIR 抗混叠低通 ──► 16 kHz Int16 PCM
        └─ 每 100 ms 一块 ──► POST /api/kws/audio(串行队列,带超时与合并)
             └─ KeywordSpotter × 3~4 档(并行)──► 命中
                  └─ 按唤醒词对齐截取 ──► 声纹余弦相似度 ──► 触发

几个关键取舍:

  • 不做任何自动增益。getUserMedia 各档都显式 autoGainControl: false,编码只做 Float32→Int16 的数值限幅,KWS 与声纹、录入与监听四条路径电平完全一致。
  • 首选 { exact: false } 强制关闭降噪与回声消除。WebRTC 里这三项默认就是 true, 写 false 只是 ideal,设备可以忽略;Windows 驱动一旦开启会把持续人声压到底噪。
  • 命中后重建流而不是 reset。实测 reset 连续 8 轮只中 5/8,每次 createStream 是 8/8。
  • 流在第一次收到音频时才创建。sherpa-onnx 的 KeywordStream 需要「创建后立刻 acceptWaveform」,先建流再等音频会让 isReady 恒为 false。
  • AudioWorklet 内部攒到 4096 帧再发给主线程。每 128 帧发一次(约 375 次/秒)会把主线程淹没。

常见问题

为什么一定要录声纹? 插件是「唤醒词 + 声纹」双重校验,避免别人或电视里的一句话把桌宠叫出来。未录入声纹时开关不可用。

换唤醒词后不灵敏? 模型自带词表全是 4 字/叠词,2~3 字短词对语速和发音很敏感。可以:

  1. 把「唤醒加成」在 1.5~3 之间微调(或看按住测试给出的建议值);
  2. 换成四字词(如模型自带的「小爱同学」);
  3. 放慢、字间稍分开,说完停 0.2~0.3 秒再松手。

多条声纹有什么好处? 最多保留 3 条模板,比对时取最高分。3 次录入的音色/音量差异很大,只比均值会把分数稀释 (实测同一段录音均值 0.292、逐条最高 0.622)。

模型 32 MB 会一直占内存吗? KWS 是 3.3M 的小模型,常驻内存很小;声纹模型只在录入/校验时用。并行多档实测每 100 ms 音频约 6 ms CPU。

朗读用的是什么音色?插件自己做 TTS 吗? 不做。所有朗读都委托给 dsh-pet 的 POST /voice/speak,音色与音量直接读它 /config 里的 main.voiceName / main.voiceVolume——也就是说完全跟随 dsh-pet 的设置,本插件没有任何本地 TTS。

dsh-pet 0.4.x 把音色改成了「限定 id」(provider/voice,默认 edge/zh-CN-XiaoyiNeural)。 旧配置里如果还留着裸名(zh-CN-XiaoyiNeural),/voice/speak 会直接 bad-request, 表现为有动画、有气泡,但没声音。本插件会用 dsh-pet 的 /voice/voices 目录把裸名补全成限定 id, 但它自己那条链路仍然读的是坏配置——所以建议打开 dsh-pet 设置重新选一次音色。

如果选的是需要凭据的云端音色(例如 deepseek/stella),而 DEEPSEEK_API_KEY 没配, /voice/speak 会立刻失败(dsh-pet 日志里是 reason=DEEPSEEK_API_KEY is not configured, 连它自己的碎碎念也一起哑掉)。本插件遇到这种情况会自动改用目录里的 edge 默认音色重试一次, 并把失败原因写进设置页「语音任务」的诊断行,不会让整条唤醒反应没声音。

顺带说明识别侧:dsh-pet 0.4.9 里的 dsh 识别实现,接的就是 DSH 的 speechToText(SenseVoice), 与本插件语音任务用的是同一个引擎,只是各自走各自的入口。

说完判定/没开口放弃要等很久,一直卡在「正在听命令」? 端点检测的阈值必须相对底噪,不能写死一个绝对值。实测这台机器的底噪 RMS 就有 0.0230.033,说话也才 0.0480.072;旧实现把绝对下限写成 0.02(比底噪还低), 于是每一块都被判成「有声」、静音计数永远是 0,只能等到 60 秒上限——录音 60 秒、 识别 1.7 秒,就是你看到的那种「卡很久,最后又执行了」。

现在的规则:

  1. 底噪用预录段(或头 500ms)的中位数估;
  2. 有声阈值 = 底噪 × 1.55 + 0.006,静音判定就是「低于有声阈值」;
  3. 底噪跟随是非对称的(往下快、往上只在贴着底噪的窄带里极慢上调), 避免把说话的中等电平块当成静音、反过来抬高低噪,形成正反馈死循环;
  4. 另加 maxSpeechMs = 20s 兜底,真的一直说不停也不会拖到 60 秒。

想自己核对电平:~/.dsh/dsh-pet-extend/last-listen.wav 就是引擎最近听到的 6 秒原始音频。

状态一直停在「正在听命令…」? 它只是设置页的状态提示。正常情况下收音结束会立刻转成「识别中… Ns」,识别完就消失。 如果它一直不消失,说明「听命令」窗口没有被解除——旧版本里这个窗口最长挂 60 秒, 现在收音一结束就主动解除(POST /api/voice/transcribing),并且窗口本身封顶 20 秒、 识别与落地各有超时(25s / 8s),任何异常都会立刻收场并记进诊断。

语音任务喊完没反应? 先在设置页「语音任务」卡片看第一行状态:

  • 「识别不可用」→ DSH 里没启用官方语音输入插件,本功能只会退化成打开桌宠对话;
  • 「识别就绪」但计数里「进入」不涨 → 唤醒没触发(看上面的唤醒诊断);
  • 「进入」在涨、「识别」不涨 → 命令没被识别:确认说完后停了 2 秒再等结果, 或者把「没开口放弃」调大一点。

为什么说完要等 2 秒? 插件靠「持续静音」判断你说完了,默认 2 秒(voiceTaskSilenceMs)。想更快可以调到 1000~1500 ms,但太短容易把句中停顿当成结束。

「直接发送」会不会乱改代码? auto 只对不命中黑名单的命令生效,其余一律退回草稿等你按回车;即便如此, 它也只是把话发给 agent,改文件的每一步仍然受 DSH 自己的权限确认约束。 这个模式没有「撤销」,需要中断请用会话里的停止按钮。

支持哪些平台? 取决于 sherpa-onnx-node 的预编译包。Windows x64 已验证;macOS / Linux 理论上可用,未逐一实测。

开发

npm test                 # 烟雾 + 回归测试(含假推理模块,不需要真模型)
lib/
  index.js              服务端:HTTP 路由、设置、声纹、模型装配
  client.js             DSH 客户端:菜单、麦克风采集、上传、唤醒反应
  kws.js                KWS 引擎:并行多档、会话、诊断统计
  speech.js             官方 SenseVoice 转写桥(PCM→WAV→transcribe,可选依赖)
  voiceprint.js         声纹录入与校验
  settings.js           设置持久化、唤醒词 → 拼音 token
  models.js             模型路径与下载地址
  pages/settings.html   设置页(原生 JS,无框架)
scripts/install-models.mjs
test/smoke.mjs

常用调试接口(同源):

接口用途
GET /api/kws/status引擎/客户端/诊断计数
POST /api/kws/retry重建引擎(等真正结束再返回)
POST /api/kws/test按住录音测试(body 为 16 kHz Int16LE PCM)
GET /api/kws/test/audio回放刚才的测试录音
GET /api/kws/listen-audio回放正式监听最近 6 秒
GET /api/kws/voiceprint/audio?index=N逐条回放声纹录音
GET /api/kws/level麦克风电平/有效语音占比
GET /api/voice/status官方转写服务/provider 就绪状态 + 语音任务计数与最近一次结果
POST /api/voice/prepare预热识别模型(模型懒加载时先叫醒,省掉几百毫秒)
POST /api/voice/command手动喂 16 kHz Int16LE PCM,返回识别文本与耗时(排查用)

数据与隐私

所有数据都在本机 ~/.dsh/dsh-pet-extend/:

settings.json           设置
keywords.txt            当前唤醒词 token
voiceprint.json         声纹特征向量
voiceprint-*.wav        每次录入的原始录音(用于回放)
voiceprint-audio.json   录音索引

音频不离开本机,也不写入插件目录之外的任何位置。

语音任务的识别同样在本机完成(DSH 官方 SenseVoice provider,模型在 ~/.dsh/speech-to-text/),命令音频只经过本机 HTTP 传给宿主进程,不落盘、不上传。 插件只记录「最近一次识别出的文字」用于设置页诊断,保存在内存里,重启即清空。

许可证

Apache License 2.0,Copyright 2026 dsh-pet-extend contributors。

Apache 2.0 允许商用、修改与再分发,条件是分发时保留本许可证与版权声明、标注你修改过的文件,并且它自带显式的专利授权。

本项目是 PC2005-cloud/dsh-pet 的扩展,dsh-pet 自身的许可证以其仓库为准,本项目不改变它。

模型来自 sherpa-onnx / 3D-Speaker 社区发布,遵循其各自的许可证;仓库内仅为方便安装而附带。

Plugin correlati